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 its delivery plan is done, 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 feature step of playbook 07: prepared, developed in one to two hours, reviewed, checked and delivered as one. A milestone larger than that is split.
• 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 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.
5. Ask the operator to confirm the milestones, in a short table: number, outcome, 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 the feature step; its issues are the step's issues; the next milestone starts when the previous one's delivery plan is done.
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 ready mark 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 in hq's merge-check 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.
• 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 has had its delivery plan done; its outcome sentence is proven on the mesh before the next milestone starts.