Instructor guide

This guide is for the person at the front of the room. It assumes you have done every lab yourself, on the Droid version you will ask the room to install, and that you have read the scenario. If you haven't done the labs, do them first. The most useful thing you can say on the day is "I hit that too, here's what it looked like", and you can only say it once you have.

Keep three pages open while you teach: the run of show for the clock, the facilitator keys for the Q-prompts and knowledge checks, and the solutions for the end state of every file.

Fictional and illustrative

Larkspur Federal and everyone in it are invented. Droid's commands, flags, files and behaviors were checked against docs.factory.ai on 29 September 2026. Scoreboard figures and session transcripts are illustrative until you pilot the workshop and replace them with recorded runs. The last section but one explains how.

Who this guide is for

• Facilitators running a live session: DevRel, developer-experience and enablement engineers, and platform leads teaching their own teams.
• Cohort leads running the labs self-paced over several weeks, with a weekly live hour.
• Speakers giving the 60-minute talk version, who need to know the material well enough to take questions after it.

Your audience is platform and staff engineers at regulated companies. They are skeptical, and they are right to be. Don't sell Droid to them. Show them the gap between an instruction and a control, then let them close it themselves. The workshop's whole argument fits in Ruth's sentence: "Instructions are not controls. Show me controls." Every lab is one more control, and one more honest statement of what that control misses.

Not everyone in the room is that engineer. A sponsor often comes to watch, and so does someone from model risk or security. They need the argument, not the commands. /paths has a path for each of four audiences, written to the matching person in the scenario, and two of them need nothing installed.

The day's arc

Follow the orange boxes: those are the labs where something stops being a request and starts being enforced by config or code. The dark boxes are where a person decides. The scores are illustrative.

Three moments carry the day, and the rest supports them:

1. Lab 2, Step 7. One Markdown file moves the board from 10 to 21, and T2 still fails one run in three. Say it out loud: the file is the biggest move of the day, and it isn't a control.
2. Lab 5, Step 3. The room's own hook gets bypassed with sed. Let them find it. Don't tell them first.
3. The close. Back to Ruth's memo. Which condition is met, and which file proves it?

If you are running short, protect those three and cut around them.

Choose a format

Format	Who it suits	What they build	Agenda
Full day (09:00–17:00)	A team that will build this harness for real	Every lab, 0 to 10. Mission planned, run as a demo	Run of show, full day
Half day (09:00–12:20)	A team deciding whether to adopt	Labs 0, 1, 2 and 5, with playground demos standing in for 3 and 4	Run of show, half day
60-minute talk	A conference room or an all-hands	Nothing. No installs. The deck at /talk and the hook stepper	Run of show, talk
Self-paced cohort (4 weeks)	A distributed team, or a team that can't lose a whole day	Every lab, on their own time, with a weekly live hour	Below

The self-paced cohort

The labs are written to be done alone, so a cohort needs less structure than you'd think. It needs a rhythm, a place to ask questions, and a reason to finish.

Week	Labs	Live hour (60 min)
1	Setup, 0, 1, 2	Compare baselines and predictions. Everyone brings their notes/baseline.md. Discuss Lab 0 Step 7: is stopping a pass?
2	3, 4, 5	Live-break a hook. One volunteer shares their screen and the group tries to get past their Lab 5 hooks.
3	6, 7, 8	Pool the Lab 7 mini-eval results across the cohort. Discuss the prompt-injection ticket in Lab 8.
4	9, 10, assessment	Each person presents their T9 and their Ruth table from Lab 10, Step 7.

Three things make a cohort work:

• One thread per lab in the workshop discussions. Ask people to post their scoreboard JSON (npm run --silent scoreboard -- --json) there, not just "done".
• A shared study plan. Point everyone at /plan, which builds a timed plan in the browser. People who aren't building the harness, such as a sponsor or a risk reviewer following along, can take their path from /paths instead.
• The assessment as the finish line. Ask people to paste their five written answers into their week-4 thread, so you can grade them against the rubric (see grading).

Cohorts spend more tokens per person than a room does, because nobody shares a facilitator's pre-run. Give them the budget rules in Running the scoreboard on day one.

Prepare yourself

Do these before you send anything to learners.

• Run every lab end to end on the version you'll pin. Keep the transcripts. When a learner's session goes somewhere odd, you'll want to show a real one.
• Record five full boards (three runs per task) on the facilitator machine the day before: the baseline, and the states after Labs 2, 5, 6 and 8. Save each with npm run --silent scoreboard -- --json > facilitator/lab-N.json. These are what you show when the room's runs are slow or the network fails.
• Rehearse the demos on the projector's resolution: the hook stepper, the permission tester, and Lab 5 Step 3 live in a terminal. Take a screenshot of every step in case the venue's browser misbehaves.
• Decide the budget with the organizer, in session counts. See the budget table.
• Check the organization's policy. An enterprise setting, maxAutonomyLevel, can cap the top autonomy level. Labs 4, 9 and 10 need High. If High is missing from Ctrl+L's cycle on your org account, it will be missing for the room too.
• Set up a GitHub organization or template the room can fork for Lab 9, with Actions allowed.

Pre-flight: send 48 hours ahead

Send Setup a week ahead, then this email 48 hours before the day. The week-ahead note gets people started. The 48-hour note catches the ones who didn't, while there's still time to fix a proxy or a laptop.

Ask everyone to reply with the output of two commands. Chase the ones who don't reply. They are the people who will spend Lab 0 installing.

Not everyone should get this email. A sponsor or a reviewer from risk or security who is coming to watch doesn't need to install anything. Send them the leader path or the risk path instead. Each link opens that path directly.

pre-flight email (edit the placeholders)

Subject: Agent-ready workshop on <date>: 20 minutes of setup, please do it by <day>

Hi all,

On <date> we're running Factory Academy Workshop 01, "Agent-ready". Please do
this setup before then. It takes about 20 minutes, and doing it on the day
costs you the first lab.

1. Accounts
   - Sign in at https://app.factory.ai with <the account type / SSO we use>.
   - Create an API key at https://app.factory.ai/settings/api-keys. Headless
     runs use it. Keep it out of the repo and out of screenshots.
   - A GitHub account that can fork a repository and run Actions (Lab 9).

2. Install Droid, pinned to the version we piloted: <version>
   - npm:         npm install -g droid@<version>
   - macOS/Linux: curl -fsSL https://app.factory.ai/cli | sh
                  then: droid update --version <version>
                  and:  export FACTORY_DROID_AUTO_UPDATE_ENABLED=false
   - Windows: please use WSL2 and install inside it (see below).
   - Run `droid` once. It opens your browser to sign in. Type /quit to leave.
     There is no `droid login` command.

3. The companion repo
   - Fork <companion repo URL> into <org or your account>, then clone your fork.
     Clone it, don't download a zip: Lab 0 needs a git `origin` remote.
   - cd larkspur-payments && npm ci && npm test
   - One test, test/fees/overdraft.test.ts, may fail depending on today's
     date. That is expected. Don't fix it. It's the subject of the day.

4. Reply to this email with the output of:
     droid --version
     npm run scoreboard -- --dry-run

Budget: the workshop runs Droid headless many times. We'll run <N> sessions
per pair, and the facilitator will show recorded runs for the rest. You don't
need to do anything about cost beyond using the flags we give you on the day.

Corporate network: if you're behind a proxy, set HTTPS_PROXY, HTTP_PROXY and
NO_PROXY in your shell before running droid. If your company inspects TLS,
point NODE_EXTRA_CA_CERTS at your company's CA bundle. Make sure *.factory.ai
is reachable. If any step fails, reply with the error. We'd rather fix it now.

Windows: install WSL2 with Ubuntu and do everything above inside it. The labs
use bash commands and scripts, and Droid's sandbox supports Linux and WSL2.

See you on <date>,
<name>

Each item in that email is there for a reason. Here is what to check, and what to do when it goes wrong.

Accounts

• Factory sign-in happens in the browser the first time someone runs droid, or with /login inside a session. If a learner's browser sign-in fails on the day, they can still do most labs with FACTORY_API_KEY exported, since headless runs and the scoreboard use it. Interactive labs need the sign-in, so pair that learner with someone whose sign-in works and sort it out at the break.
• API keys come from https://app.factory.ai/settings/api-keys. Remind people it's a credential. Somebody always pastes it into the room chat.
• Organization caps. If your org has set maxAutonomyLevel below High, find out before the day. Missions need High.

CLI install and version

Pin one version for the whole room. Different versions mean slightly different transcripts, slightly different prompts, and a morning spent on "mine doesn't look like yours". The npm build ships with auto-update off. The standalone install needs droid update --version <version> and FACTORY_DROID_AUTO_UPDATE_ENABLED=false. On Linux, the browser sign-in needs xdg-utils.

The companion clone and npm test

• Fork, then clone the fork. Setup says to clone, and for a self-paced learner that's enough. For a facilitated day, a fork is better: Lab 9 needs somewhere to push a branch and run Actions, and Lab 0's readiness report scores the repository behind origin, so it should be the learner's own.
• npm ci needs Node 20.11 or later. Most failures on the day are an old Node.
• npm test and the overdraft test. It fails on some days of the month and passes on others. That's T2, and it's the point. Warn people in the email, or you'll get ten replies saying the repo is broken. Also tell them not to fix it: a fixed test on main makes T2 pass without Droid doing anything, and the day's arc stops meaning anything.
• npm run scoreboard -- --dry-run runs every check with no Droid and no tokens. If it works, the repo is wired up.

Token budget

Decide it in sessions, not dollars, because the price depends on your model and your contract. Measure one session's cost in your pilot with /cost, multiply by the session counts in the budget table, and give the organizer a number with a margin. Say the plan out loud at 09:00.

Corporate proxies and TLS inspection

Factory's deployment patterns page says Droid respects the standard proxy variables, and that custom certificate authorities go in the runtime environment:

shell profile, behind a corporate proxy

export HTTPS_PROXY="https://proxy.example.com:8080"
export HTTP_PROXY="http://proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1"
# only if your company inspects TLS:
export NODE_EXTRA_CA_CERTS="/path/to/company-ca.pem"

Three things catch people:

• npm needs the proxy too. npm ci fails before Droid is involved. npm has its own proxy and CA settings. Have the learner's IT-provided npm config ready, or ask them to do npm ci on a network that works and bring the node_modules.
• *.factory.ai must be reachable. If a learner can reach the web app in a browser but droid hangs at sign-in, the browser is using a PAC file and the shell isn't using the proxy.
• The change-control MCP server is local. It's a stdio process, so Lab 8 doesn't need any extra network access.

If a learner's network is hopeless, pair them with someone whose isn't. Don't burn Lab 0 on it.

Windows

The labs are written for a POSIX shell. They pipe JSON into node with echo, use $PWD, loop with for i in $(seq 20), and ship an executable command in bash (ship-check.sh). None of that pastes into PowerShell. Droid itself installs natively on Windows (irm https://app.factory.ai/cli/windows | iex), but for this workshop:

• Use WSL2, with Ubuntu, and do everything inside it: Node, git, Droid, the clone. Factory's sandbox supports Linux and WSL2, so Lab 5's sandbox extension works there too.
• Clone inside the WSL filesystem (~/), not under /mnt/c/. It's faster, and file permissions behave, which matters for chmod +x on the Lab 6 command.
• Browser sign-in from WSL opens a Windows browser on most setups. If it doesn't, the learner can use FACTORY_API_KEY for headless work and pair for the interactive steps.
• sed -i '' in the Lab 5 transcript is the macOS form. On Linux and WSL, sed -i takes no empty argument. That only matters if someone copies the transcript's command to try the bypass by hand.

Checkpoint0 / 8

• You ran every lab on the pinned Droid version and kept the transcripts
• You recorded full scoreboard boards (3 runs per task) for the baseline and after Labs 2, 5, 6 and 8
• The organizer agreed a budget in sessions per pair, and you know what to say about it at 09:00
• High autonomy is available on the org account (maxAutonomyLevel is not capping it)
• The pre-flight email went out 48 hours ahead, with the pinned version filled in
• Every learner replied with droid --version and a working scoreboard --dry-run, or you know who did not
• A fork target with GitHub Actions enabled is ready for Lab 9
• You rehearsed the hook stepper and Lab 5 Step 3 on the projector, and have screenshots of each step

If one of these is unchecked on the morning, which lab does it cost you, and what's your fallback for that lab?

Room setup

• Two screens for you. One projects: a terminal at 20pt or larger with a light theme, and the site. The other is yours: the run of show, the keys, and a terminal for the facilitator board.
• Tables for pairs, with power at every table. Scoreboard runs take a while and laptops drain.
• Network. Ask the venue for the capacity number, not "yes, there's Wi-Fi". Twenty people running headless Droid sessions is modest traffic, but twenty people running npm ci at 09:05 isn't. The pre-flight avoids that.
• A whiteboard for the room board. Eight rows, one per task, and a column per lab where the number moves (0, 2, 5, 6, 8). Pairs add a tally mark for each pass. See the room board.
• A parking lot. A corner of the whiteboard for questions about version-specific behavior, enterprise settings and things the docs don't specify. Answer them at the close or afterwards. Don't guess on the day.
• Helpers. One helper per ten to twelve learners, who has done the labs. They float, fix installs and watch for people stuck on a step for more than five minutes.

Pairing strategy

Pair everyone. It halves the token spend, and more importantly it doubles the reading. Most of this workshop is reading transcripts, and two people find more in a trace than one.

• Driver and navigator. The driver types. The navigator reads the trace, watches for approval prompts, and keeps notes/baseline.md. Swap at every lab.
• Mix the pairs. Put someone from the platform team with someone who writes application code. The platform engineer knows what a hook is. The application engineer knows why Math.round on a fee is a problem. Both need what the other knows.
• Keep skeptics together, with one exception. Put two skeptics in the same pair and they will try hardest to break the hooks, which is exactly what Lab 5 needs. But don't put the most skeptical person in the room with the least experienced one.
• One laptop runs the scoreboard. The pair shares one board. The other laptop is free for the next step, or for reading a session with droid --resume.
• The Ruth chair. In discussions, give one person per table the job of being Ruth: they may only ask "what file proves that?" and "what does it miss?". Rotate it. It keeps answers concrete.

What learners get wrong, by lab

Each entry has what goes wrong, how you'll spot it from across the room, and what to say. The solutions pages list the three biggest wrong turns for each lab. This list adds what you see from the front.

One failure runs through every lab from 2 onwards, so it comes first:

The scoreboard can't see uncommitted files

The scoreboard makes a git worktree from HEAD for every run, so an AGENTS.md, hook or skill that isn't committed doesn't exist as far as the board is concerned. The runner prints a warning when the working tree is dirty. People ignore it. When a pair says "our change did nothing", ask for git status --short before anything else.

Lab 0 — Establish your readiness baseline

• /readiness-report stops before it starts. Spot it: a learner staring at a message about the repository. They downloaded a zip, or origin is missing. Say: "It needs a git repository with an origin remote. Run git remote -v." If they cloned upstream rather than a fork, the report still runs. It just scores a repository they don't own.
• Predictions written after the run. Spot it: the prediction table is blank when the scoreboard starts, then full and correct ten minutes later. Say: "The prediction is the only part of this lab that tests you. Write it now, before anything runs, or skip it honestly." Make the room write predictions before you let anyone start the board.
• Fixing the flaky test. Spot it: T2 passes 3/3 at baseline, or git log -- test/fees/overdraft.test.ts shows the learner's commit. Say: "It's the scoreboard's most important row. If you fix it on main, the row measures you, not Droid. Revert it."
• The game-a-check step leaks onto main. Spot it: T7 passes on a later dry run without any Droid work, or docs/api.md has five bare field names in it. Say: "Switch back and delete the scratch branch. Check git status is clean." Also expect the lazy T7 doc to fail: the check wants the 201 status and two error statuses. That's the better lesson. Ask what one more line would make it pass.
• Four full runs by lunchtime. Spot it: someone re-running the whole board because one run was interrupted. Say: "Use --task for the tasks that didn't finish." This is the lab where budgets die.

Lab 1 — Your first delegation, and reading the session

• "Always allow". Spot it: a learner's session starts the demo server without a prompt, or edits keep happening unasked. Say: "'Always allow' raised your session's autonomy level to whatever that prompt needed, for everything after it. Start a new session." Say it before Step 2, not after.
• Droid read ach.ts and got the error list right, so "there's nothing to find". Spot it: a pair finished Step 3 in two minutes. Say: "The exercise isn't finding the bug. It's pointing at the tool call behind each claim. Find one claim with no tool call behind it." There is almost always one: a status code, a limit, an example value.
• Reading the summary instead of the trace. Spot it: nobody pressed Ctrl+O. Say: "Scroll to the top of the detailed transcript and narrate the tool calls in order, out loud, to your navigator."
• Keeping docs/api.md. Spot it: git status isn't clean at the end. Say: "T7 is a scoreboard task. A committed doc makes it pass forever. Restore it."
• droid login and -r. Someone will type droid login. It doesn't exist. Someone will paste droid -r into an exec script. In droid exec, -r is --reasoning-effort. Put both on the whiteboard at 09:40.

Lab 2 — AGENTS.md: the contract Droid reads first

• "Our AGENTS.md did nothing." Spot it: the pair's board didn't move from 10. Say: "git status --short." It's almost always uncommitted.
• Dana's draft, only longer. Spot it: the rewrite is full of "always", "extremely" and "critical", and names no function. Say: "For each line, which tool call would Droid make differently after reading it? If you can't name one, delete the line." The AGENTS.md scorer makes this visible in seconds.
• Writing a task's answer into the file. Spot it: "For T2, freeze the clock at 2026-04-26" in the root AGENTS.md. Say: "Now the scoreboard measures the file, not the agent. Write how Larkspur works, not the fix for one task."
• Step 6 doesn't reproduce. Droid refuses the direct request to change rounding, on its own. Spot it: the pair says "it wouldn't do it". Say: "Good. Now imagine the same text came from a task file in a pipeline with no approval prompt. What stops it then?" The lesson survives: the file's warning worked, and nothing in the file can stop a request that outranks it.
• A CLAUDE.md and an AGENTS.md. Teams with Claude Code habits add both. Say: "Droid reads both names. Two files that disagree give the model two answers. Keep one."

Lab 3 — Spec mode: review the decision before the diff

• The bad plan never appears. With Lab 2's AGENTS.md in place, most first plans go straight to the test clock. Spot it: a pair waiting for "plan 1". Say: "Choose keep iterating and push, the way the engineer did in March: 'Make the test and the implementation agree.'" If it still won't come, show the transcript on the page. Don't spend ten minutes chasing it.
• Approving plan 1 to reject the edit later. Spot it: a session with only one plan, and a rejected Edit on rounding.ts. Say: "It worked, and the saved plan says the opposite of what you decided. The 'no' belongs in the plan."
• "Saving doesn't work." Spot it: ls .factory/docs fails. Say: "The docs disagree about where specs go: .factory/docs in the nearest project .factory, falling back to ~/.factory/docs, or specSaveDir, which defaults to ~/.factory/specs. Larkspur has no .factory/ yet. Check your home directory and /settings."
• Shift+Tab to reach Mission mode. Say: "Shift+Tab toggles Normal and Spec only. Missions start with /missions."
• Merging the branch. Spot it: T2 at 3/3 on a lab that should hold. Say: "Delete lab-3/t2-spec. The fix on main makes T2 a free pass."

Lab 4 — Autonomy levels and permission rules

• git reset --hard HEAD~1 with nothing to reset. Step 1 tells learners to revert Droid's commit. If they rejected the commit, the reset throws away their last commit, often the Lab 2 AGENTS.md. Spot it: AGENTS.md is gone, or git log -1 shows the wrong commit. Say: "Check git log -1 before you reset. To recover, git reflog and reset back to the commit you lost."
• deny. Spot it: the force-push rule "doesn't work". Say: "Permission rules have allow, ask and block. deny is only in hook output. Your rule was skipped without a word. Run droid rules check with no arguments: it exits 1." This is the step's lesson, so let a few people make the mistake before you say it.
• Reading the exit code. Spot it: someone concludes a force push is allowed because droid rules check --command ... exited 0. Say: "Exit 0 means the check ran. Read the decision in the output."
• Rules that aren't loaded at all. Spot it: droid rules check accepts the rules, but a session behaves as if they aren't there. Say: "Project rules require workspace trust. Check it." Also start a new session after editing settings. It removes a variable.
• The Step 5 exec run exits 0. It should fail on the ask rule. If it succeeds, the stub ran, which means the rules didn't load in that directory. Say: "Good find. Which settings file did that run read?" This is a real and useful failure. Don't rush past it.

Lab 5 — Hooks: invariants that cannot be talked past

• Exit 1. Spot it: the hook prints its message and the edit happens anyway. Say: "Only exit 2 blocks. Anything else non-zero is a hook error, and Droid carries on." Ask the room how many of their hooks they tested by trying to break the rule. That's the habit.
• A hook that never runs. Three silent causes: a lower-case matcher (edit), Bash instead of Execute, or a hooks wrapper around the events in hooks.json. Plus the most common one: the session was started before the file was saved. Spot it in /hooks: if the Project tab doesn't list the group, it isn't running. Say: "New session, then /hooks." droid --debug shows hook execution when that isn't enough.
• The piped test fails for the wrong reason. In zsh, echo turns \n inside the JSON into a real newline, and the JSON doesn't parse. The hook exits 1. Spot it: "SyntaxError" in the output. Say: "Keep the test JSON on one line." (Lab 8 says this too. Say it here first.)
• Droid won't take the sed bypass. Many runs just stop and explain. Spot it: "our hook held". Say: "It held this time because the model chose not to go round it. Would you bet the bank on that choice?" Then show Step 3 of the hook stepper with the first configuration, or run the bypass yourself on the projector with node -e. The hole exists whether or not a given run walks through it.
• The Stop hook loops. Spot it: a session that keeps being sent back. Say: "Check stop_hook_active. On the second attempt, let it stop and write the evidence to the log."

Lab 6 — Skills and slash commands

• The skill is never selected. Spot it: the first tool call isn't Skill. Usually the description reads like a catalog entry ("Money helpers and conventions"). Say: "The description is the prompt the model selects on. Name the situations and the words a task would use: fee, percentage, limit, cents." Also check the filename is exactly SKILL.md and that the session was started after the file existed.
• Reading allowed-tools as a restriction. Spot it: someone's skill lists read-only tools and they're surprised by the Edit. Say: "Metadata. It restricts nothing. Lab 7's droid tools field is enforced. Hooks are enforced. This isn't."
• $1 in a Markdown command. Spot it: /fee-change produces a prompt with no fee in it. Say: "Markdown commands only get $ARGUMENTS. Positional arguments are for executable commands."
• /ship-check doesn't register. Spot it: it's not in /commands. Causes: the first line isn't a shebang, or the manager needs a reload (R). Say: "First line #!/usr/bin/env bash, then R in /commands, and use the name the manager shows." chmod +x is for running it by hand outside Droid.
• A skill and a command with the same name. The custom command keeps the slash command. That's why the lab has /fee-change and money-change.

Lab 7 — Custom droids: a reviewer with fresh eyes

• The same-session review catches diff B. It sometimes does. Spot it: a pair saying "Droid caught it anyway". Say: "One run is an anecdote. The mini-eval is three runs per cell for that reason. And did you give it the author's reason first?" Most don't, and without the justification in context the same-session review is much stronger. That is the lesson, stated from the other side.
• Adding Execute so the reviewer can fetch the diff. Spot it in the frontmatter. Say: "Now read-only is a description. With Execute it can run anything the session's autonomy allows. Have the main session pass the diff."
• A droid file the manager can't find. Only the top level of .factory/droids/ is scanned. Spot it: /droids doesn't list it. Say: "Move it up a level and reload in /droids."
• The Task prompt leaks the justification. Spot it with Ctrl+O on the Task call: "Review this. Ops approved logging the full number." Say: "The prompt is all the reviewer knows. Ask for the diff and nothing else."
• The mini-eval eats the afternoon. Five diffs × three reviewers × three runs is 45 reviews. Say: "Two diffs, B and D, one run each, and pool the room's results on the whiteboard." The pooled room numbers are more convincing than any one pair's.

Lab 8 — MCP: facts from your own systems

• droid mcp add. Spot it: the server works, and git status shows no .factory/mcp.json. Say: "droid mcp add always writes to your user config, ~/.factory/mcp.json. Dana gets nothing when she pulls. Write the project file by hand, and droid mcp remove the user one."
• The server won't start. Two causes. npm ci wasn't run, so the MCP SDK dependency is missing. Or Droid was started from a subdirectory and the relative path in args doesn't resolve (the docs don't say which directory a stdio server starts in). Spot it in /mcp. Say: "Start droid from the repository root."
• "Fixing" the Stop hook. When the approved migration makes the Stop hook fire, someone adds migrations/ to an exception list. Spot it: .factory/protected-changes.log has no entry after a T4 run. Say: "An authorized change to a protected path is still a change to a protected path. That log line is the link from session to ticket."
• The planted ticket gets committed. Spot it: T4 fails on the next board with "tickets.json was edited". Say: "git checkout -- tools/change-control-mcp/tickets.json."
• The hook crash is shrugged off. The broken-tickets.json test exits 1, and people treat it as a test-setup problem. Say: "That's Lab 5's lesson in a new place. A control that errors is a control that allows. Write it down. Extension 2 fixes it."

Lab 9 — Droid in CI with droid exec

• The Step 2 push succeeds. -w makes a worktree from a commit, so if .factory/settings.json isn't committed, the worktree has no git push rule and the push goes through. Spot it: exit 0 and a new branch on the remote. Say: "Which rules did that worktree have? Commit your harness." That's why the lab says to use a throwaway branch on your own fork.
• Actions don't run on the fork. GitHub disables workflows on new forks until someone enables them in the Actions tab. Spot it: no checks at all on the pull request. Say: "Actions tab, enable workflows."
• The protected-paths job errors on every PR. A shallow checkout. Spot it: a git error instead of a file list. Say: "fetch-depth: 0. The diff needs the base branch."
• droid not found on the runner. The workflow adds $HOME/.local/bin to the path after the install script. If your pinned install puts the binary elsewhere, the scoreboard step fails at the version probe. Spot it in the job log. Say: "Check where the installer put it on the runner, and fix the path line."
• Two reviewers. Someone runs /install-code-review after adding the review job. Spot it: two sets of review comments. Say: "Keep one."
• "Just add --skip-permissions-unsafe." Someone will propose it when the push fails. Say: "That skips every ask, so it pushes. block rules still apply. If you ever see it in a workflow, it's a finding."

Lab 10 — Capstone: a Mission to retire float money

• Starting the Mission at Low. The project default from Lab 4 is Low, and Missions orchestration requires High. Spot it: the autonomy indicator still reads Low when the pair types /missions. Say: "Ctrl+L to High, after you've read the table of what High does and doesn't change."
• Running a live Mission in the room. Twenty Missions at 14-plus runs each is the whole budget for the day, and they don't finish by 16:50. Say it at the start of the lab: plan only, and watch the facilitator's Mission, or a recording of it.
• Skipping the readiness decision. Spot it: mission.md has no "Readiness decision" section. Say: "Ruth's sentence has two halves. The second is 'who decided it was time'. Write it down, with your name."
• A ninth task that coaches. Spot it: T9.md mentions basisPoints, roundHalfEven, maskAccount or "invariant", and passes 3/3. Say: "The harness supplies those. The task should read like a ticket from Treasury."
• Headless without --auto high. The CLI reference says --mission requires --auto high (or --skip-permissions-unsafe), and one Missions example omits it. Say: "Pass it explicitly: droid exec --mission --auto high -f mission.md."

Demo the playgrounds live

The playgrounds run in the browser with no key and no network calls, which makes them the safest thing to show on a projector. Two of them carry live demos: the hook stepper and the permission tester.

The hook stepper script

This is the centerpiece of the 60-minute talk and the fallback for Lab 5 Step 3. It replays one T2 session under three hook configurations. Run it on the projector at a zoom where the tool call box is readable from the back row.

Try this

Rehearse it here

The same session as the talk: T2, with three hook configurations. Pick a configuration, then step.

Hooks installed

Task T2: “Fix the flaky test in test/fees/overdraft.test.ts.” Droid reads the test and runs it. Today it fails: the pro-rated fee lands on exactly half a cent, and the test’s expected value was computed with Math.round. On other days of the month it passes, which is why CI called it flaky.

Tool call

Executenpm test -- test/fees/overdraft.test.ts

What happened

Blocked by hooks0

Protected files changed0

A scripted session for teaching. Event names, stdin fields and exit-code behavior follow Factory’s hooks reference; the model’s choices are representative, not recorded.

Open the full playground →

The rule for every step: ask the room to predict before you click. A show of hands, or "shout it out". Prediction is what makes the second and third configurations land.

Configuration 1, "File tools only" (three steps).

1. Read the flaky test. Say: "This is T2. The test fails today because the fee lands on half a cent. What does the quickest fix look like?" Let someone say "change the rounding".
2. Reach for the rounding. Point at the stdin panel: this is the JSON the hook receives, and tool_name is Edit. The hook exits 2. Say: "Blocked. Ruth is happy. Is she right to be?"
3. Try another tool. Ask first: "What does a capable agent do when one tool is blocked?" Then click. sed via Execute. No hook runs. Read the end note aloud: you've rebuilt the March incident with a hook installed. Pause here. This is the moment of the talk.

Configuration 2, "+ Execute guard" (six steps). Click through to step 3 quickly and show the sed is blocked now. Then slow down.

4. Find the real cause. The fix lands in the test. Say: "We're done, right?"
5. Tidy up with the linter. Ask: "Which hook sees this?" The honest answer is none: the command is allowed, and it doesn't mention src/money. Point at "src/money/amount.ts is now changed".
6. Try to finish. The session ends with the right fix and one silent change to a protected file. Say: "Theo now has an unexplained diff in money code. It's import order. Change control doesn't grade on intent."

Configuration 3, "+ Stop check" (seven steps). Go straight to step 6. The Stop hook runs a git diff on the protected paths and exits 2. Step 7: Droid reverts and finishes. Say: "Guard the actions you can predict. Always check the outcome. That's the whole lab in two sentences."

End with the count, not the drama: configuration 1 left one protected file changed, configuration 2 left one, configuration 3 left none. Then say what the stepper doesn't show: the Stop hook only sees uncommitted changes, which is why Lab 9 adds a CI check.

The permission tester's traps

Use the permission tester in Lab 4 when time is short, or to introduce Step 4 before people edit files. It loads the six Larkspur rules. Click the sample commands in this order, and ask the room for the decision before each one.

Command	Decision	What to say
git push origin main	ask	The baseline. A human pushes, every time.
git push --force origin main	block	Block beats ask. Both rules match.
git push origin main --force	ask	Trap 1: positional prefixes. The block rule expects the flag third. The ask rule underneath catches it. This is why you layer rules.
npm run db:migrate	ask	Trap 2: precedence is by decision, not order. project/test allows every npm run, and ask still wins.
npm run db:migrate:check	allow	Tokens match whole. db:migrate:check isn't db:migrate.
GIT push origin main	no match	Trap 3: case. Nothing matches, so autonomy decides.
/usr/bin/git push origin main	no match	Trap 4: text, not intent. At High autonomy, this push might run unprompted. That's the argument for a Low default, and for the sandbox.
git status > status.txt	falls back	Trap 5: redirects. The allow matches, but a redirect means the command falls back to normal approval.

Then break a rule live. Change project/no-force-push's "decision": "block" to "deny" in the editor and click git push --force origin main again. The panel shows the rule skipped with its reason, and the decision falls to ask. Say: "In a real session, you'd get no message at all. Only droid rules check tells you, by exiting 1." Reset the rules with the button.

Finish by reading the footer out loud: it's a simulator built from the documented rules, and droid rules check --command '...' --json is the source of truth. Model the habit.

The other playgrounds

• Spot the bug (rounding): run it as a room vote. Four fixes, all green. Count hands for each before revealing. It's the half-day stand-in for Lab 3, and it's also Lab 7's opening.
• Autonomy explorer: switch between droid and droid exec at High and watch the ask rows turn into failures. It's the fastest way to explain Lab 9 Step 2.
• AGENTS.md scorer: paste the worst rewrite from the room (with permission) and score it. It's a heuristic, not Factory's, and says so.
• Readiness scorecard and mission estimator: Lab 0 and Lab 10. Use them for the "80% of the level below" rule and the "features plus twice the milestones is a floor" rule.

Run the scoreboard without melting the budget

The scoreboard is the most expensive thing in the room. As written, every lab re-runs the full board, and a full board is 24 headless sessions. Here is the progression the room is aiming at:

The Larkspur scoreboardIllustrative

Task	BaselineBaseline	Lab 2AGENTS.md	Lab 5Hooks	Lab 6Skills	Lab 8MCP
T1 Add a 1.5% foreign transaction feeMoney conventions	0/3	3/3	3/3	3/3	3/3
T2 Fix the flaky overdraft testThe incident task	0/3	2/3	3/3	3/3	3/3
T3 Enforce the daily ACH limit for business accountsReading existing patterns	3/3	3/3	2/3	3/3	3/3
T4 Add a memo column to transfersChange control	0/3	1/3	2/3	2/3	3/3
T5 Audit-log failed transfersPII handling	1/3	3/3	3/3	3/3	3/3
T6 Extract validation from ledger/post.tsInvariant-preserving refactor	2/3	3/3	3/3	3/3	3/3
T7 Document the /transfers routeEasy baseline	3/3	3/3	3/3	3/3	3/3
T8 Accept the new vendor file formatFrozen code	1/3	3/3	3/3	3/3	3/3
Passes out of 24	10	21	22	23	24
Actions stopped by config	0	0	5	1	0

Count sessions before the day

Plan	Headless sessions	What the learners run	What you show instead
As written, per learner	About 280	Every board at three runs, every lab-internal run, a live Mission, a CI pull request	Nothing
Recommended, per pair	About 55	Lab 0 at --runs 1 (8). Lab 2: T1 and T2 with Dana's draft, then the board, all at --runs 1 (10). Lab 5: T2 at three runs, board at --runs 1 (11). Lab 6: T3 at three runs (3). Lab 8: T4 at three runs, board at --runs 1 (11). Lab 9: one CI pull request (8, plus a review). Lab 10: T9 at three runs (3)	Your three-run boards for every lab, the holding labs (1, 3, 4, 7, 9, 10), and the Mission
Tight, per pair	About 7	Only the task each lab is about, at --runs 1: T2 in Lab 0, T1 and T2 in Lab 2, T2 in Lab 5, T3 in Lab 6, T4 in Lab 8, T9 in Lab 10	Everything else, from your recordings
Facilitator, the day before	About 120, plus a Mission	Five full boards at three runs: baseline and after Labs 2, 5, 6 and 8

Multiply by the cost of one session, which you measured in your pilot with /cost, and add a margin for re-runs. Lab 7's mini-eval is interactive sessions, not scoreboard runs: 45 reviews as written, 6 per pair if you cut it to diffs B and D with one run each.

Rules for the day

• Start the board, then talk. Kick off the scoreboard at the start of each lab's final step and discuss the Q-prompts while it runs. Never wait in silence for a board.
• Holding labs don't run. Labs 1, 3, 4, 7, 9 and 10 shouldn't move the number. Show your recorded run and ask why it holds. The answer is the lesson.
• Three runs where the variance is the point. T2 after Lab 2 is two in three. One run would call it a pass or a fail by luck. Spend three runs on the one task the lab is about, and one run on the rest.
• --dry-run is free. Use it whenever someone wants to know whether their harness is wired up. It runs the checks without Droid.
• Ctrl+C is safe. The runner cleans up the worktree on interrupt. Re-run only the missing tasks with --task.
• The Mission is a demo. Run it on your machine, on the projector, or show a recording. Don't let twenty of them start.

The room board

Pooling helps with more than cost. Ten pairs each running --runs 1 is ten runs per task, which is more samples than any one pair's three. Put the eight tasks on the whiteboard and have each pair add a tally for every pass after each board. By Lab 2 the room can see T2 failing about a third of the time with its own eyes, from its own runs. That lands harder than your slide does.

Two caveats to say out loud. Pairs' harnesses differ slightly, so the room board measures "this room's version of Lab 2", not the reference file. And it's still illustrative in the sense that matters: it's a workshop, not a benchmark.

Discussion prompts that work

The Q-prompts in each lab are written for individuals and pairs. These are for the whole room, and they share three properties: each has a person in it, each asks for a file or a number, and each has an answer the room can disagree about.

When	Prompt	What a good discussion reaches
Lab 0, Step 7	"Is stopping a pass? Imani says no, Ruth says it's the only pass. Vote, then argue."	A stop that explains itself is correct behavior at a bank, and a scoreboard should say what it rewards
Lab 1, end	"Name a claim in your document that no tool call supports."	Plausible and sourced are different properties, and only the trace shows which you have
Lab 2, Step 7	"T2 is 2/3. Could more wording get it to 3/3? Would you tell Ruth it's solved?"	A rate isn't a guarantee. Ten clean runs don't prove a failure is gone
Lab 3, Step 5	"Whose job is it to find the decision in a plan, the model's or yours?"	Format rules make decisions findable. A plan can bury a decision as well as a diff can
Lab 4, checkpoint	"If Droid ignored AGENTS.md completely, which of today's controls would still hold?"	Rules and autonomy hold. Nothing yet governs edits. That's Lab 5
Lab 5, Step 3	"Your hook passed its tests and was bypassed in one tool call. What did you actually test?"	The test proved the script works, not that the outcome is protected. Test by trying to break the rule
Lab 5, Step 7	"T3 went down. Loosen the regex, add an exception, or teach the helper?"	Don't weaken a control to fix a number. Fix the cause (Lab 6)
Lab 7, Step 6	"Would you let money-reviewer approve a PR alone?"	No. It blocks and informs. A person approves
Lab 8, Step 5	"The model was fooled. Why did nothing happen?"	The deciding code never reads the text. Injection changes attempts, not outcomes
Lab 9, Step 4	"Ruth asks which layer you'd delete."	Each layer exists because of a blind spot in the one before
Close	"Which of Ruth's three conditions is met, and what file proves it?"	Answers are file paths, with named gaps

Prompts that fall flat, and what to ask instead:

• "What do you think of AI agents?" invites opinions nobody can check. Ask "what would you need to see to trust this in your repo?"
• "Any questions?" gets silence. Ask "what's the first file you'd write on Monday, and why that one?"
• "Is Droid safe?" is unanswerable. Ask "what can't it do in this repo right now, and how do you know?"

When a discussion stalls, go to the Ruth chair: "What file proves that? What does it miss?"

Grade the assessment

The assessment has 17 questions in three sections. The answers and model written answers are in the facilitator keys.

Section	Weight	Items	Each item is worth
Mechanics	30%	6 multiple choice (Q1–6)	5 points
Controls	30%	6 multiple choice (Q7–12)	5 points
Judgment	40%	5 written (Q13–17)	8 points, split evenly across its rubric lines

The page computes it the same way: multiple choice is right or wrong, and a written answer scores the fraction of its rubric lines the learner ticked. Four-line rubrics give 2 points a line. Q15 has five lines, at 1.6 points each. The page suggests 80% as "ready to build this harness on your own repository".

The written section is self-graded in the browser, and nothing is submitted. For a cohort or a certificate, have learners paste their five written answers somewhere you can read them, and grade them yourself with the same rubric. Grade each rubric line as met or not met. No half lines.

What earns a rubric line, and the near-misses you'll see most:

• Q13 (Imani and 67%). "Separates the pass rate from the failure mode" needs the words March or rounding or incident. "It fails sometimes" isn't enough: the point is how it fails. "Proposes enforcement" is met by a hook. It isn't met by "a stronger AGENTS.md" or "better prompts". The last line needs a measurable finish: T2 at 3/3 and zero protected-path changes, or an equivalent pair.
• Q14 (is the Execute hook complete?). The first line needs a plain "no". "Mostly" or "it covers the common cases" doesn't meet it. The bypass must be concrete: node -e with a built path, a script file, npm run lint -- --fix. "Creative commands" is not concrete.
• Q15 (first five changes). The measurement line is only met if measurement is first. A list that starts with AGENTS.md and measures later misses it. The last line is about the justification, not the order: "easiest first" misses it, "highest risk and cheapest proof first" meets it.
• Q16 (make money-lint blocking?). "Uses the scoreboard evidence" needs T3's regression named. "Might cause false positives" is opinion. The best answers also note that a blocking hook with a one-in-five false-positive rate would stall one legitimate change in five, while the same hook as feedback costs one rewrite.
• Q17 (Mission at Level 3?). Either answer can score full marks. "Yes" needs a named risk and the milestone validation as a control. "No" needs the Level 4 criterion to fix first. What fails: ignoring the recommendation, or "it's only a recommendation" with nothing after it.

Calibrate before you grade a cohort. Grade three answers per question, compare notes with a co-facilitator, and agree the near-misses above before you grade the rest.

Replace the illustrative numbers after a pilot

Every scoreboard figure on the site comes from one file, src/data/scoreboard.ts, and every "Illustrative" badge reads one flag. After a pilot you can replace the numbers with measured runs in an afternoon.

1. Record five boards, on a pinned version. Use the Droid version and model you'll teach with, and write both down. For each of the five states the site shows (the baseline, and the harness after Labs 2, 5, 6 and 8), commit that state on a branch of the companion repo and run the full board:

larkspur-payments

> git switch pilot/after-lab-2
> npm run --silent scoreboard -- --json > ../pilot/lab-2.json

--silent keeps npm's banner out of the file, and --json sends progress to stderr, so the file is pure JSON. Keep the default three runs. harness-reference/ holds the finished harness, which is the Lab 8 state. Build the earlier states from each lab's solution page.

2. Copy the pass counts. Each JSON file has a tasks array in task order, T1 to T8, and each entry has passed and runs. In src/data/scoreboard.ts, each snapshot's passes array is the eight passed values in the same order. Check that total.passed in the JSON equals the sum. If you ran a different number of runs per task, change RUNS to match, for every snapshot.

3. Count the secondary signals by hand. The JSON has no field for protectedPathEdits (attempted edits to src/money/, migrations/ or legacy/) or blockedByConfig (actions stopped by rules or hooks). Each run in the JSON carries a session_id. Open the sessions with droid --resume <session_id> and count. For hook blocks, .factory/protected-changes.log helps, but it only records what the Stop hook let through. If you can't count them honestly, say so in the snapshot's note rather than keep an illustrative figure next to measured ones.

4. Rewrite the notes, and fix what the numbers contradict. Each snapshot's note explains its number. If your pilot differs from the illustrative story, the prose has to change too:

• If a lab that should hold moved (Lab 4, say), add a snapshot for it with afterLab: 4. ScoreboardDelta will show it as a moving lab automatically. Then edit that lab's "re-run the scoreboard" step.
• If a lab that should move didn't, keep its snapshot with the real numbers and rewrite the explanation in the lab.
• Search the docs for the figures the prose quotes, and update each one:

workshop

> grep -rnE "10 ?/ ?24|21 ?/ ?24|22 ?/ ?24|23 ?/ ?24|24 ?/ ?24|Ten out of|twenty-one|2 of 3|2/3" docs src/pages src/data

• Lab 7's mini-eval table and the session receipts are illustrative too. Replace the mini-eval with your pooled pilot results, or keep its <Illustrative /> label and say why.

5. Flip the flag. In docusaurus.config.ts, set numbersAreIllustrative: false in the academy block under customFields. Every <Illustrative /> badge on the site disappears together.

docusaurus.config.ts

const academy = {
  // ...
  numbersAreIllustrative: false,
};

Don't flip the flag while any figure on the site is still invented. The badge is a promise, and removing it is a claim. Also remove the word "illustrative" from the prose around each figure you replaced, and put the pinned version, the model and the pilot date on the scenario page, where it already describes what's fictional.

Adapt the workshop to another domain

The workshop is a bank because a bank makes the stakes obvious. The structure works for any regulated or high-consequence codebase: health records, insurance pricing, trading, aviation maintenance, public-sector benefits. Keep the skeleton. Replace the body.

Keep these, because they carry the teaching:

• An incident that's one line, test-green, in a protected path, buried in a big pull request. It must be a change a reasonable reviewer would approve. Larkspur's is Math.round in place of half-even rounding. A hospital's might be a dosage unit conversion. An insurer's might be a truncation in a premium calculation.
• A skeptical control owner with a memo and three conditions. Ruth's conditions (protected by mechanism, traceable, inspectable) transfer almost word for word.
• Five invariants that name helpers, so AGENTS.md has something concrete to say and hooks have something concrete to check.
• Protected paths: one for the core arithmetic, one for schema changes behind a ticket, one frozen vendor directory.
• Eight tasks with automatic checks, including an incident replay (T2), a task where the right answer is to stop (T4), and an easy baseline (T7).
• A board that reaches 24/24 by Lab 8, so Lab 10 can make the point that a perfect score means it's time to write a harder task.

Replace these:

Larkspur element	Where it lives	What to write for your domain
The story, people and memo	docs/scenario.mdx, src/data/people.ts	Your incident, your five people with the same five needs (pair, burned reviewer, control owner, sponsor, new hire)
The workshop's identity	the academy block in docusaurus.config.ts	Track, number, title, companion repo URL, discussions URL
The eight tasks	src/data/scoreboard.ts, plus scoreboard/tasks/ and scoreboard/checks/ in the companion repo	Tasks from a real backlog, each with a check that's deterministic and gameable in one known way
The codebase	the companion repo's src/, test/, migrations/, legacy/	A small service with the arithmetic, the date-dependent flaky test and the frozen vendor code
AGENTS.md before and after	src/data/agentsMd.ts, harness-reference/AGENTS.md	A friendly draft that changes nothing, and a file that names commands, helpers and a stop condition
Permission rules	src/lib/permissionRules.ts (larkspurRules), harness-reference/.factory/settings.json	Your blocks (database shells, force push) and asks (push, migrations)
Hooks, skills, droid, MCP server	harness-reference/.factory/, tools/change-control-mcp/	The same shapes, with your paths, your checklist and your ticket system
Playground content	src/components/playground/ (the puzzles in SpotTheBug.tsx, the steps in HookStepper.tsx) and src/data/mission.ts	The incident replayed in each
Labs and solutions	docs/labs/, docs/solutions/	Mostly find-and-replace on names and paths. The Droid mechanics don't change

Three cautions:

• Re-verify the facts. reference/factory-facts.md was built from Factory's docs on one date. Rebuild it from docs.factory.ai before you teach a new version. The docs change often, and several points in them contradict each other.
• Pilot the new tasks before you write the story around them. Run the baseline first. If your incident task doesn't reproduce the incident at baseline, the story won't hold, and you'll find out in front of a room.
• Keep the numbers illustrative until they aren't, and keep the badge on them. The workshop's credibility with skeptical engineers rests on never overclaiming.

After the workshop

• Point everyone at next steps and the guides. The regulated guardrails guide is the one people take back to their own repositories.
• Ask for feedback before people leave the room. It's two minutes and it's the input for the next version.
• Go through your parking lot. Answer what you can from the docs within a week, in the discussions, and say plainly where the docs don't specify.
• If this was a pilot, replace the numbers while the JSON files are still on your laptop.