hq/00-META/process/04-build-handoff.md

Playbook 04 — Work breakdown and handoff

Trigger. A to-be design is settled (playbook 02) and its building is about to start.

Who runs it. The lead who will run the feature, on the larger model. It is one sitting, bounded at about an hour, and said to the operator if it runs past.

What it produces

A design becomes milestones, and each milestone becomes issues:

• A milestone is usable on its own. Once it is delivered, the operator or the mesh can do something new, said in one sentence ("a Claude Code session is mirrored into a thread on the bus"). A milestone that changes nothing anyone can use is not a milestone; fold it into the next.
• A milestone is one release of playbook 07: prepared, developed whole, reviewed, checked and delivered as one, never cut for its size or for time (the operator, 2026-10-17).
• A milestone is one piece of functionality, never cut by an order between its parts (the operator, 2026-10-21: a milestone may span several modules, repositories and dependencies such as an SDK change; 2026-10-22: "a milestone is a milestone, we shouldn't cut it"). Which of its modules reaches the machines first (a reader of a new manifest word before the modules that use it, a provider before its consumers) is the assigner's rules' (design 47); an SDK change is built into its users. The parts such an order touches are found in playbook 07 step 0 item 6 and become issues of the same milestone; an order those rules cannot keep is an issue of the build and delivery system, not a cut. Until 2026-10-22 this rule cut milestones by release order (design 47's release 1-2 became six milestones).
• An issue is one repository's part of a milestone, sized so a fixing agent finishes it inside the milestone's development time. Issues that must land in order are linked depends-on.

Steps

1. Confirm the design is settled. Its frontmatter reads status: designed, and every claim in it traces to a decision record in the knowledge base (knowledge-base.get for each entry of its decisions:). An open question in the text is a reason to go back to playbook 01, not to build around it.
2. Name the owners. Set code: in the design's frontmatter to the repositories from repos.md. A repository that does not exist yet is added to repos.md in the same change.
3. Check the as-is. Read the matching 03-DESIGN/00-as-is/ document. What is being replaced is stated there; if it is not, write it before changing it. Building against an undocumented as-is is how a shipped behaviour gets lost.
4. Break it into milestones. Write them into the design, in a section Milestones: for each, its number, its one-sentence outcome, the acceptance tests of the design it proves, the repositories it touches, and what it depends on. Order them so each is usable as soon as it is delivered, the smallest useful one first. A milestone is named by what it lets someone do; how it ships is shaped by the modules its changes move and the nodes that run them (ADR 0401 §6), read from the indexer's fingerprints through the status view's indexer_modules and indexer_candidates, and from the nodes' haves (node_haves). 4a. Give each milestone its part (playbook 02, The shape of a design): every line the milestone builds moves from the main file into NN-milestones/<milestone>.md, as numbered design lines, each naming what its builder needs. A milestone whose part would pass 60 KB is split here into two milestones, each usable on its own; this is the one place a milestone is ever cut, for what one agent can read, before any work starts. The main file stays within 80 KB. Written by hq-design-writer in the same change as the milestones.
5. Ask the operator to confirm the milestones, in a short table: number, outcome, the acceptance tests it proves, repositories, the parts each repository builds. Change what they change.
6. Open the issues. For each confirmed milestone, issue-tracker.open one issue per repository part, its title the symptom or capability in plain words, its report naming the design, the milestone and the decisions it builds with; link the order with depends-on. Write the issue numbers into the milestone's entry in the design.
7. Flip the status. status: in-progress, updated: today; the design change goes through playbook 08 (one hq pull request).
8. Hand each milestone to playbook 07, one at a time. The milestone is one release of playbook 07; its issues are the release's issues; the next milestone starts when the previous one is delivered. Playbook 07 builds from the milestone part alone and starts its develop step only once that part answers every design question its prepare finds (playbook 07, Design complete); a question is never answered by building around it. A design waits while another design's milestones are being built: one design is built at a time (playbook 07), so this step starts only when the design before it is delivered.
9. On completion of the last milestone, run the "when something ships" section of playbook 02.

Rules

• What the handoff leaves for later is an issue with an owner, named in the design or the decision that leaves it — never a sentence saying "later". The design's code: names who owns what is built; the issue names who owns what is not. The knowledge base's rule deferral checks the decision record when it is proposed (issue 354).
• HQ is not a code repository and never carries implementation.
• How the building is done — worktrees, agents, review, checks, the Approve and the delivery — is playbook 07's, not this one's.

How it is checked

Read by the lead and the reviewer today; a check among hq's Go tests is tracked by issue 845.

• A design in status: in-progress has a Milestones section, each milestone with its outcome and its issues; an in-progress design without one is the smell of building without a breakdown.
• Each milestone of an in-progress design has its part under NN-milestones/, within 60 KB, its lines numbered (ls -l 03-DESIGN/01-to-be/NN-milestones/); a milestone handed to playbook 07 without one is step 4a skipped.
• Every issue a milestone names exists in the tracker (issue-tracker.get), and an issue in fixing names its milestone in its report.
• A milestone whose issues are all resolved is delivered (the status view said delivered for its source revision); its outcome sentence and acceptance tests are proven on the mesh before the next milestone starts.