The positional argument is the request, or the path of an existing design: a file with and frontmatter and a title. resumes at the first missing section, or at a phase the user names, deleting later sections; checks the next open milestone; any other status is . Anything else starts a new design.

Resolve as the absolute directory containing this . Write new designs to , with the root directory name of the first repo, never inside it.

After a design path exists, record after every step at through a temp sibling and atomic rename; delete it on any terminal except : . Write each approved phase to the document the same way before the next phase starts. Each phase pauses with until approved or revised.

A request is small when all hold: it changes one module or package, it adds or changes no contract, data model, or public signature, and its desired behavior is one sentence. Small stops with plus that sentence and no pause; do not write a design-path ledger. Otherwise create the design file from , locate an ADR tree (, , , ), and note ADRs touching this area; if none exists, proceed silently. Done when size is recorded and, for non-small work, the file has frontmatter.

Write Problem to solve with concrete user pain, Success with measurable signals, and Proposed solution with a bold one-line shape, a mockup, and a delivery paragraph. Use supplied mockups; when the work has a user-facing surface and none was supplied, draft a text wireframe or state table labelled as a draft. Ask the whole open-question frontier in one numbered round with a recommended answer per question. Pause. Done when the approved section is written.

State the shape in one bold sentence and the pattern it follows. Add a layer map of paths marked NEW or CHANGED with a role each, data sources and constraints with their cost reason, and a sequence diagram with a band per phase. Flag ADR conflicts by number instead of overriding them. Pause. Done when the approved section is written.

For each boundary write its thesis, the pattern it follows, a usage snippet with real signatures, call sites grouped by boundary, a file tree with a role per file, a call-site tree marking added calls, and a call graph from the entry point. Write no bodies. When the layout is uncertain, draft two shapes, pick one, and record the reason. Pause. Done when every Success outcome maps to named symbols and the section is written.

Order milestones so each is one PR that cuts through every layer, stub to mock to wire to logic to error handling, names its automated commands and manual steps, and lists the Phase 3 symbols it lands. The checkbox is the done signal; only the user marks a milestone deferred or skipped. Prefactoring comes first; wide refactors run as expand then contract, so a symbol may appear in two milestones. Multi-repo work names the order across repos. Pause. Done when every Phase 3 symbol is in a milestone, every milestone has a command or step, and the section is written with one open box per milestone.

Set . For each decision recorded in Phases 2 and 3, offer an ADR only when all three hold: hard to reverse, surprising without context, chosen over a real alternative. On confirmation write it with the ADR template in into the tree found in Step 0, or created lazily, in the repo that owns the decided component. Report the design path, ADR paths, and next steps (, then pass the design after each milestone; to revise, set , name the phase, pass the path). Done with when Product review, System design, Program design, Vertical slices, and Decisions exist and every offer is written or declined.

Take the first open milestone that is not deferred or skipped. Show each automated command and run it only after the user approves that exact string; tick each that passes. Compare promised symbols by name and signature. If any manual box is open, report steps and stop with . When every box is ticked and symbols match, tick the milestone; on mismatch add and leave it open. Use ; never edit product files. Done with when the milestone is ticked or all milestones are complete; with when manual steps await or a deviation names the still-open milestone.

Terminal values: (no-op success for routers), , , , .