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

# Playbook 04 — Work breakdown and handoff

**Trigger.** A to-be design is settled (playbook [02](02-graduation.md)) 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](07-feature-branches.md): 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](07-feature-branches.md)
  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](01-research.md), not to build around it.
2. **Name the owners.** Set `code:` in the design's frontmatter to the repositories from
   [`repos.md`](../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`).
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](08-small-fixes.md) (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. A design waits
   while another design's milestones are being built: one design is built at a time (playbook
   [07](07-feature-branches.md)), 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](02-graduation.md).

## 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](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md)).
- 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 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` 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.