The Spec → Implementation Handoff
The handoff contract is the bridge between a completed PRD and a dispatched agent — feeding it wrong is as bad as writing a bad spec.
The Handoff Is Where Specs Fail
You have a well-written PRD with testable acceptance criteria. You have decomposed it into per-phase PRDs with explicit file ownership. Now you dispatch an agent to build Phase C. The agent receives the PRD and starts working.
Twenty minutes later, the agent reports it has updated index.ts, modified tracks.ts, and added the new track to tiers.ts. The second agent running in parallel has done the same. You now have two conflicting versions of three registry files, and neither version is complete.
The handoff failed — not because the PRD was wrong, but because the dispatch prompt didn't specify which files were off-limits. The PRD quality doesn't matter if the handoff is broken.
The /ship Phase Pipeline
Understanding the handoff requires understanding where it sits in the full delivery pipeline:
The handoff — feeding the per-phase PRD to the build agent — happens at the Phase A→C transition. Phase A (Preflight) and Phase B (Research+Security) produce context. Phase C (Build) consumes that context via the dispatch prompt. The dispatch prompt is not the PRD — it is the PRD plus the five handoff fields that make it executable.
The Consumer-Contract Check Before Output Shape
Before Phase C starts, one check must happen: every consumer of the new module's output must be identified by grep, and the PRD's output shape must be verified compatible with every caller.
This check is not optional for any change that modifies an existing function's return type. The lesson from Knox's MEMORY.md: "Implementation framing requires consumer-contract check — before specifying output shape, grep existing callers; every dispatch prompt lists Consumers-of-this-output."
The practical rule: if your feature adds a field to a shared type, run:
grep -rn "TypeName\|function-name" $(git ls-files) > /tmp/callers.txt
Review every call site. Document them in the PRD's consumer contracts section. Pass the list to the agent in the dispatch prompt. The agent's Phase C output must not break any listed caller.
The Five-Field Dispatch Contract
Every agent dispatch prompt for a spec-driven build must contain five fields:
1. Scope: The specific acceptance criteria from the per-phase PRD this agent is responsible for. Not the entire PRD — only the criteria assigned to this phase.
2. Definition of Done: The exact conditions under which the agent may declare PASS. These are the binary pass/fail criteria from the PRD, translated into verifiable commands: tsc --noEmit → 0 errors, npm run test → all passing, ≥90% coverage.
3. Files in scope: An explicit list of the files and directories the agent may create or modify. This is the positive boundary.
4. Files off-limits: An explicit list of shared files the agent must not touch. At minimum: components/mdx/index.ts, lib/tracks.ts, lib/tiers.ts. These are orchestrator-only files edited in a single atomic pass after all agents complete.
5. Verification: The exact commands the agent must run and the exact output format required for its PASS report. "All tests pass" is not acceptable. "$ npm run test → 24 passing, coverage 92.4%" is acceptable.
Missing any of these fields degrades the dispatch from a contract to a request. Requests get interpreted liberally. Contracts get followed precisely.
The Literal Evidence Rule
When an agent reports PASS, the orchestrator must validate the evidence before accepting the result and moving to the registry editing phase. Literal command output is required — not a paraphrase, not a description.
# Acceptable PASS evidence
$ npx tsc --noEmit
(0 errors — empty output)
$ npm run test
✓ components/mdx/SddPrdAnatomy.tsx renders (2ms)
✓ content/academy/lesson-430 has valid frontmatter (1ms)
24 tests passed
Coverage: 93.7%
# Unacceptable PASS evidence
"I ran the tests and they all passed"
"TypeScript compiled without errors"
"Coverage looks good"
Paraphrased evidence can mask a test run where 1 of 24 tests was skipped, or where coverage dropped from 94% to 88% and the agent rounded up. Literal output catches this at the orchestrator level before converging.
Phase A → Phase C: The Preflight Handoff
The /ship preflight phase produces specific outputs that Phase C (Build) needs:
- Host check result: your laptop or the production server. Changes which infrastructure commands Phase C uses.
- Branch check: Is the working branch correct? Not main, not a stale feature branch?
- Env var gap list: Which required env vars are missing? Phase C cannot build against undefined config.
The per-phase PRD for Phase C must include these as required inputs. The agent building Phase C needs to know which machine it is targeting — a command that works on the production server may not exist on your laptop, and vice versa.
What's Next
The next lesson goes deep on the quality gates themselves: the definition of done, the 90% coverage floor, test-first discipline for bug fixes, and the specific checks that block merge. Understanding the gate structure is what makes the "Done means the running system works" principle actionable.