Plan to project tree

Turn one plan/design file into the planning tree:

docs/plans/
  README.md                    index of projects + shared conventions
  <project>/                   one directory per program of work, named by the thing being built
    ROADMAP.md                 milestone numbering, statuses, milestone -> directory map
    <YYYY-MM-DD>-<name>.md     global design (spans all milestones) — the source doc, moved here
    <capability>/              one directory per milestone, named by capability
      SPEC.md                  durable "what and contracts" for that milestone
      NN-<feature>.md          feature-level plans, numbered in build order

<project> is the program the source doc describes (search-rewrite, billing-v2) — one ROADMAP and one design doc per project, so several programs coexist without their milestone numbers colliding. A repo with one project still gets the directory.

Rules that govern every file you write

1. Milestone directories are named by capability, never by number. Numbers shift; they live only in ROADMAP.md. Reference milestones as "Milestone 3" spelled out.
2. SPEC.md outlives the build; feature plans are disposable. SPEC = what and contracts. Feature plan = how, one PR chain each, retired to [DONE] when merged.
3. Status tag at the top of every doc: [DESIGN], [PLANNED], [IN PROGRESS], [DONE], [SUPERSEDED by <link>].
4. Conflicts resolve upward: the global design doc is authoritative and revisioned; SPEC/plan defers to it.
5. Name by what it delivers, not how it works. The label must stand alone with the description covered. Write the boring literal name first.
6. Invent nothing. Every claim traces to the source doc. Where the source is silent, write an explicit ## Open questions entry — never a plausible-sounding guess.
7. Milestone numbering is per project. "Milestone 3" always means the third milestone of its own ROADMAP; never number across projects.
8. Every milestone and SPEC states exit criteria — an observable condition, not "done".

Procedure

1. Pick the project directory. Name it after the program being built, in product language. Reuse an existing docs/plans/<project>/ when the source doc extends that program; create a new one when it is a separate program with its own milestone sequence. Everything below is written inside it.
2. Read the source doc in full. Find its build-sequence / phases / steps section; that is the milestone raw material. Note invariants, numbered requirements, and open decisions — they get referenced, not restated.
3. Draft the milestone list. Group steps into milestones by deliverable capability — each milestone is one sentence of the form "when this lands, X exists and is demonstrable". Mark which milestone is first externally showable. Propose a capability directory name per milestone.
4. Confirm before writing. Show the user the milestone table (number, capability name, steps folded in, one-line meaning) and the proposed build order. Ask about any ordering deviation from the source doc. Do not create files until they confirm — renaming a tree later is expensive.
5. Write ROADMAP.md — milestone table, step table with abridged exit criteria and status, long-lead external dependencies, open decisions gating early steps. Statuses start not started except work already done. Run its review gate before writing anything under it.
6. Write the active milestone's SPEC.md. Later milestones live as ROADMAP rows until reached — a SPEC written years ahead of its build is fiction. Run its review gate before writing feature plans, which inherit every contract it gets wrong.
7. Write the feature plans, split by PR chain. Each NN- plan is one landable chain: 4-8 build items, its own tests, an entry in the SPEC. If a plan needs more than ~8 items, split it. Number in build order; earlier plans must not depend on later ones. Every plan gets its own review gate.
8. Move the source doc into docs/plans/<project>/ with a YYYY-MM-DD- prefix if not already there, tag it [DESIGN], and link it from every SPEC's "Design references" line.
9. Write/update docs/plans/README.md — the structure block, the conventions list, and an index table (location, scope, status): a row per project linking its ROADMAP, then a row per doc within the project you just wrote.
10. Reread only the headings and labels. Any that needs its body to make sense gets renamed. Then report the tree.

Review gates

Every doc this skill writes gets reviewed before the docs that depend on it are written. Order matters: ROADMAP, then SPEC, then each feature plan. A flaw in the ROADMAP's milestone split propagates into every SPEC; a wrong contract in the SPEC propagates into every plan. Reviewing at the end means rewriting the tree.

For each doc, in that order:

1. Run /review-plan <path> (the reviewer-subagent loop) if that skill is installed. If it is not, spawn one fresh subagent per doc with the review prompt below and apply only the findings that hold up — the loop is the point, a single self-reread is not a review.
2. Apply the findings you judge correct; for each one you reject, say why in one line to the user rather than silently dropping it.
3. Record what changed: bump the doc's rev in its status line (rev 2 after review round 1 (…)), so a later reader sees the doc was hardened and against what.
4. Re-run only if the round produced structural changes — a round that yields wording nits is the stopping signal.

Review prompt per doc type:

• ROADMAP — Does each milestone name a capability that is demonstrable on its own? Any milestone that cannot be shown to someone? Do the exit criteria state observable conditions? Any step that depends on a later step? Any long-lead dependency missing from the table?
• SPEC — Are the contracts complete enough to build against without guessing? Does anything conflict with the design doc (the design wins)? Are the exit criteria checkable by someone who did not write them? Does any claim lack support in the source doc — and should it be an open question instead?
• Feature plan — Is this one landable PR chain, or two? Does it depend on a later-numbered plan? Does every build item have a test that locks the behavior? Are the decisions it pins for downstream work stated explicitly?

Cost note: this is one reviewer loop per doc. On a milestone with six feature plans that is eight loops. Say so before starting, and offer to gate reviews to ROADMAP + SPEC + plan 01 when the user wants it cheap.

After writing

• If the repo has a CLAUDE.md, add or verify the documentation-organization section so the rules survive the session.
• Report the tree, and the review round count per doc.

Templates for ROADMAP.md, SPEC.md, and NN-<feature>.md: references/templates.md.