cyne-wulf/make-milestones

Was macht make-milestones?

Turn one master requirements document into a chain of milestone documents that context-limited implementation sessions can execute one at a time, with clean handoffs between them.

Mode selection

• Generate mode (the rest of this document): no PRD-<N>.md milestone docs exist yet, or the user explicitly asks to (re)generate milestones.
• Verify mode: the arguments contain "verify", or milestone docs already exist and the user's intent is to check completed work rather than author docs. Skip straight to "Verify mode" at the bottom.

Verify mode

Run the current milestone's verification checklist as an interactive quiz:

1. Determine the milestone: from the arguments (e.g. verify 2), else the "Current milestone" line in the project's agent-instructions file (CLAUDE.md, AGENTS.md, or equivalent), else ask the user.
2. Read that milestone doc's Verification checklist and any preparation notes. Tell the user what materials to have ready before starting (fixture files, test data, etc.).
3. Present one checklist item at a time: state the exact steps to perform and the expected observable outcome, then wait for the user's pass/fail answer (use the ask-user question tool when available, with Pass / Fail / Skip-for-now options). Never batch items or assume a pass. Items the model can verify itself (e.g. running the test suite) it runs directly and reports, still confirming with the user.
4. Keep a running tally. On a fail: diagnose and fix (or file it if the user prefers), then re-verify that item and any already-passed items the fix could have affected.
5. When every item passes: check the boxes in the milestone doc (- [x]), tell the user the gate is cleared, and remind the implementer's next obligations — write the handoff doc specified in the milestone's Handoff section, update the current-milestone line in the agent-instructions file, commit and tag milestone-<N>.
6. Skipped items block the gate: the milestone is not complete until they are resolved.

Inputs

• Master document: use the path given in the arguments; otherwise look for a PRD/requirements/vision file in the repo root (PRD.md, master-prd*.md, vision.md, SPEC.md). If none exists, stop and tell the user this skill needs a requirements document first — offer to help write one.
• Milestone count: use the count given in the arguments; otherwise choose 3–7 based on project size. Prefer fewer, fatter milestones over many thin ones — each handoff costs context and human verification time.
• If the master document is thin (a vision sketch rather than a real spec), flesh out requirement detail inside the milestone docs rather than demanding a rewrite, but flag to the user what you had to invent.

Preserve the master

If the master document will be superseded by the milestone docs, keep it intact (rename to master-prd-backup.md if the user wants the original filename freed). Milestone docs reference it by requirement ID; it stays the single source for product-level context.

Slicing milestones

Order by dependency, not by feature area. Rules that produce clean cuts:

1. Foundation first: the data layer / persistence contract everything else builds on (file formats, schemas, storage). Make it verifiable with hand-made fixtures so it needs none of the later functionality.
2. Data contracts as early as their producer allows: the most load-bearing interface in the app (the schema/API every later milestone consumes) gets its own milestone with "get this right" called out explicitly.
3. Each milestone ends in a demonstrable state: a human can run the app (or system) and check every box without any code from later milestones. If a requirement can't be verified until milestone N+2, it belongs in milestone N+2.
4. Stub across the seam: when milestone N produces something milestone N+1 consumes (e.g. data capture before the processing pipeline exists), milestone N writes an explicit stub and marks the seam — a named file/function where N+1 plugs in. The handoff doc must identify the seam precisely.
5. The product's "soul" milestone: the experience the project exists for gets its own milestone once its dependencies exist — don't smear it across phases.
6. Lifecycle, parity, and polish last, ending with the master document's acceptance/success criteria as the final checklist item.

Structure of each PRD-<N>.md

Every milestone doc must be self-contained enough for a fresh model holding only it plus the previous handoff doc. Include (in order):

1. Banner blockquote at the top. For PRD-1 it explains the whole system: where the master doc is, what IDs refer to, that work is split into N milestones, and the gating rule. For PRD-2+: "Before starting: read PRD-<N>-start-here.md (written at the end of Milestone )", the relevant master-doc sections, and: "Do not start until the human confirms Milestone 's checklist is verified."
2. Goal — one paragraph: what exists at the end of this milestone that didn't before, and why it's the foundation for what follows.
3. Scope — explicit In: and Out: lists. The Out list is what prevents scope creep; name the milestone where each excluded item lands.
4. Requirements — grouped, carrying the master document's requirement IDs. Copy in the substance (don't just cite IDs — the implementer may only have this file); add implementation-level detail the master doc lacks. Mark partial deliveries ("REC-4 partial") when a requirement spans milestones.
5. Decisions already made (do not relitigate) — resolve the master doc's open questions into firm calls here so implementing agents don't reopen them. If a decision genuinely needs the user, get it before writing the docs.
6. Definition of done — implemented requirements + named unit tests the model writes and gets passing on its own + suite green + any performance bars. This is the autonomous bar: the model reaches it unattended, before any human verification.
7. Verification checklist (human-run) — see below.
8. Handoff (required, after the checklist is verified) — see below.

Verification checklists

Verification has two barriers, and they belong to different parties. First, autonomously: as it implements, the model writes and runs automated tests proving each feature's technical functionality, and must get the suite green by itself — this is the part a model can judge. Only then does the second barrier engage: the human interactive quiz. It exists precisely because a model can't smell a UI the way a person can, and can convince itself that passing results are real when they aren't — so the model works autonomously until the milestone is otherwise finished, then stops and brings the human in on what tests can't reach (real end-to-end behavior, look and feel), rather than self-certifying.

• Open every checklist with the interactive-verification instruction: when implementation is complete, the implementing model runs the checklist as a step-by-step quiz — presenting one item at a time with the exact steps and materials the human needs, waiting for pass/fail, keeping a tally; on a fail it fixes the issue and re-verifies that item plus any already-passed items the fix could have affected; the handoff doc is written only after the human confirms every item.
• Checkbox list of concrete steps a human performs, each with an observable expected outcome ("delete the generated index.json, relaunch, it rebuilds") — never vague ("test saving works").
• Include a preparation note when steps need materials ("prepare a 500-row CSV; have a second user account ready").
• Test the seams and failure modes, not just happy paths: external modification, crash/relaunch mid-operation, corrupt input in a batch, deleting rebuildable caches.
• Include earlier-milestone regressions where later work could break them ("renaming still works — M1 behavior intact").
• The automated suite must already be green before the quiz starts (the model's autonomous bar); still list "suite passes" as the final box so the human sees it confirmed.
• The final milestone's last box is the master document's end-to-end acceptance scenario.
• 10–20 boxes per milestone. State everywhere: the next milestone must not start until every box is checked by the human.

Handoff documents

Do not pre-write the start-here docs. They describe the actual implemented state, which doesn't exist yet. Instead, each milestone doc's Handoff section instructs the implementer to write PRD-<N+1>-start-here.md after verification, and specifies its required contents:

• One-paragraph project summary; how to build, run, and test.
• Updated file map: each source file's responsibility in one line.
• The exact contracts the next milestone consumes: schemas with a real example, the seam (file + function) where the next milestone plugs in, reusable helpers it must use rather than reinvent.
• Deviations from the milestone doc and why; known issues and tech debt.
• Tailor the spec per milestone: name the specific interfaces the next milestone's work depends on and demand they be spelled out.
• Close with: "Assume the reader is a fresh model with zero context beyond PRD-<N+1> and your document."

The final milestone's handoff instead produces PROJECT-STATE.md: consolidated architecture, all deviations across milestones, ranked tech debt, the deferred/descoped list with hook-in points, and build/test/release instructions — the living document for all post-v1 work.

Descoping rule

Anything a milestone might drop (a risky feature, an unproven library) gets an explicit descope condition in "Decisions already made": it may be cut only with the human's explicit sign-off, documented in the handoff.

After writing the docs

1. Add a milestone workflow section to the project's agent-instructions file (CLAUDE.md, AGENTS.md, or equivalent — create it if absent) containing: a "Current milestone: 1 (not started)" line with the instruction to update it only when the human confirms a milestone's full checklist; the read-order rule (milestone doc first, plus the previous handoff for milestones 2+); the hard gating rule; the stay-in-scope rule; the interactive-verification obligation; and the commit/tag convention (milestone-<N> at each verified gate).
2. Summarize for the user: the milestone map (one line each), how the gating and handoff mechanism works, and every decision you resolved on their behalf — so they can flip any call before Milestone 1 begins.