aiwfx-plan-milestones

name	aiwfx-plan-milestones
description	Decomposes an approved aiwf epic into a sequenced set of independently-shippable milestones. Allocates each M-NNNN via `aiwf add milestone --epic E-NNNN`, scaffolds each milestone spec from its template, sequences them by dependency. Use after `aiwfx-plan-epic` when the user says "break this into milestones" or "plan the work for E-NNNN".

aiwfx-plan-milestones

Decomposes an existing epic into milestones. The skill drives the conversation about what to ship in what order; aiwf owns id allocation and per-milestone commits.

When to use

An epic spec exists. The user says: "break E-NNNN into milestones", "plan the work for the auth epic", "sequence the milestones for X".

If the epic doesn't exist yet, use aiwfx-plan-epic first.

Workflow

1. Read the epic spec. Open work/epics/E-NNNN-<slug>/epic.md. Understand:

   • The goal — what the epic is delivering.
   • The scope (in / out).
   • The constraints — what each milestone must respect.
   • The success criteria — what "done" looks like at epic close.

2. Decompose into milestones. Each milestone:

   • Is independently shippable. After a prior milestone lands, the system is in a coherent state even if this one never runs.
   • Has clear, testable acceptance criteria.
   • Targets 1–3 days of focused work. If a candidate is bigger, split it. If smaller, fold it into a sibling.
   • Has explicit dependencies (or none). Forward-flowing — a later milestone may depend on an earlier one; never the reverse.

3. Sequence them. Foundational first. Group related work; don't scatter concerns. Identify any milestones that can be parallelized (no dependency between them).

4. Allocate each milestone via aiwf. For each one in sequence:

   aiwf add milestone --epic E-NNNN --title "<imperative title>"
   

   aiwf allocates the next free M-NNNN (global, not epic-scoped), creates work/epics/E-NNNN-<slug>/M-NNNN-<slug>.md with the minimal body skeleton, sets parent: E-NNNN in frontmatter, and produces one commit per milestone with aiwf-verb: add trailers.

5. Replace each milestone's body with the rich template at .claude/templates/milestone-spec.md (materialized by aiwf update; if it's missing, run aiwf update rather than copying an existing milestone spec). Fill in:

   • Goal — 1–2 sentences.
   • Context — what exists before; what must be in place; why now.
   • Acceptance criteria — created as AC entities via aiwf add ac, not freehand template prose (see the AC-creation block below the template list).
   • Constraints — non-negotiable invariants for this milestone.
   • Design notes — locked decisions; reference ADRs by id.
   • Out of scope — what this milestone explicitly does NOT do.
   • Dependencies — prior milestones, external deps, decision records.

   Frontmatter (id, parent, status: draft) was set by aiwf add — don't touch.

   Land each filled-in body through the trailered verb, not a plain git commit:

   aiwf edit-body M-NNNN     # bless mode: commits the in-place body edit with aiwf-verb / -entity / -actor trailers
   

   aiwf edit-body <id> commits the working-copy body bytes with provenance trailers in one atomic operation; a plain git commit against a milestone spec would trip the kernel's provenance-untrailered-entity-commit finding — the same finding step 6 warns about for depends_on edits. See the aiwf-edit-body skill for the --body-file and --reason variants.

   Create the acceptance criteria as AC entities now — at plan time, not deferred to milestone start. For each criterion, run aiwf add ac (which appends the AC to the milestone's frontmatter acs[] and scaffolds its ### AC-N body heading), then fill that heading with the testable contract via aiwf edit-body:

   aiwf add ac M-NNNN --title "<observable behavior>"   # once per criterion
   aiwf edit-body M-NNNN                                 # fill each ### AC-N body with its contract
   

   Creating and body-filling the ACs here — before the merge-to-main step below — is what keeps a milestone from ever landing on main with zero ACs or empty AC bodies; the milestone-draft-incomplete-acs check (subcodes zero-acs / empty-body) surfaces exactly that gap on a draft milestone. aiwfx-start-milestone's preflight then expects the ACs to already exist, treating on-the-spot creation as a recovery fallback for a hand-written spec.

6. Declare milestone dependencies via verb, not by hand-editing frontmatter. Two writer surfaces, each producing one atomic commit with aiwf-verb trailers when the list actually changes — re-declaring the list already stored converges to exit 0 with no commit:

   # At allocation time: pass --depends-on on aiwf add milestone
   aiwf add milestone --epic E-NNNN --tdd <policy> \
     --title "..." --depends-on M-PPPP[,M-QQQQ]
   
   # Post-allocation (the edge surfaced after the milestone was allocated):
   aiwf milestone depends-on M-NNNN --on M-PPPP[,M-QQQQ]
   
   # Empty an existing list:
   aiwf milestone depends-on M-NNNN --clear
   

   Replace-not-append semantics: a second --on invocation replaces the list, it does not extend. To add a single dependency to an existing list, pass the full updated list. --on and --clear are mutually exclusive. Each id passed to --depends-on or --on must already resolve to an existing milestone — typos and forward-references are refused with an error naming the unresolvable id. Cycle detection happens at the next aiwf check (and pre-push hook); the writers don't pre-check global DAG validity.

   Do not hand-edit depends_on: in frontmatter. Bless-mode aiwf edit-body refuses frontmatter changes, and a plain git commit against the milestone file trips the kernel's provenance-untrailered-entity-commit warning. Both writer verbs above leave a trailered commit that aiwf history M-NNNN can render whenever they change the list.

7. Update the epic's Milestones list. Edit the epic spec to list all milestones in execution order. Use the format from the epic template — link, one-line description, dependencies.

8. Update ROADMAP.md by running:

   aiwf render roadmap --write
   

   --write only rewrites the file on disk — it does not commit. If the content changed, stage and commit it:

   git add ROADMAP.md
   git commit -m "docs(roadmap): regenerate after planning E-NN milestones" \
     --trailer "aiwf-verb: plan-milestones" \
     --trailer "aiwf-entity: E-NN" \
     --trailer "aiwf-actor: human/<id>"
   

   The trailer keys are quoted from CLAUDE.md §"Commit conventions" verbatim — variant casings (e.g. Aiwf-Verb) fail the kernel's trailer-keys policy. Skip the git add/git commit if the render reported the file already up to date.

9. Confirm the sequence with the user. Walk through the milestone list together. Identify any scope adjustments before drafting begins.

10. Merge planning to main. Planning is closed; the entity tree on this ritual branch now diverges from main. Default behavior is to merge to main now so the freshly-allocated M-NNNN ids, the epic's updated Milestones list, and any depends_on edges are visible to other worktrees, machines, or operators. Held on a long-lived branch, planning data is hostage: other Claude Code sessions see only main's view, parallel epics walk separate filesystem-only next-free-id views (id collisions surface only at eventual merge), and milestone branches stack on a long-lived parent — making the epic-wrap diff balloon.

    Prompt the user as a strong recommendation with explicit decline:

    Planning is closed. Default behavior is to merge to main now. Decline only with a specific reason — entity shape uncertain, near-term re-planning expected, team convention overrides. Merge now? (Y/n)

    When the operator confirms, drive the in-place merge:

    git checkout main
    git merge --ff-only <ritual-branch>     # falls back to a three-way merge if FF isn't possible
    

    When the operator declines, capture the one-line reason in the conversation transcript so future readers know.

    Workflow assumption — single checkout, not a worktree. The skill assumes the operator runs planning in a single checkout (the same one calling the skill). Planning is sequential conversation; it doesn't benefit from worktree-level parallelism, and the cwd-and-session switching that worktrees impose adds friction without payoff. Worktrees are an implementation-phase tool, not a planning-phase tool.

What this skill does NOT do

• Does not draft individual milestone specs in deep detail — that happens just-in-time when each milestone is started (via aiwfx-start-milestone). This skill produces the milestone list and shape, not the full spec body for milestones not yet started.
• Does not promote any milestone past draft. Promotion happens at aiwfx-start-milestone.

Anti-patterns

• Front-loading detail. Don't write 10 fully-specced milestones up front. Spec details rot fast; AC definitions written 6 weeks before the work starts are usually wrong.
• Inventing global ordering when only local matters. If two milestones don't depend on each other, leave their order soft.
• Scope creep mid-decomposition. If decomposition surfaces work that wasn't in the epic, decide: amend the epic spec (and re-confirm with the user) or capture as a gap (aiwf add gap) for later. Either branch is a decision worth keeping — invoke aiwfx-record-decision to capture it, so the next reader finds the reasoning instead of re-deriving it, and so the question doesn't resurface as a review finding once implementation is under way.
• Inventing id-shaped labels for not-yet-allocated milestones. Per CLAUDE.md: don't write M-a, M-alpha, M-NNNN, "Phase 1", "alpha/beta" anywhere — committed prose or conversation. The mechanical chokepoint body-prose-id catches malformed shapes that leak into committed bodies. In conversation, when sequencing several not-yet-allocated milestones, short numeric labels (M-1, M-2, M-3) are acceptable as conversational shorthand — distinguishable from canonical ids by their narrow width. Once aiwf add milestone runs, the verb assigns the canonical id and the deliverable name becomes the slug; replace the casual labels with the real ids in any prose that lands in entity bodies.

Next step

Status-aware — the right next skill depends on the parent epic's status:

• Epic still proposed (the first-time plan-epic → plan-milestones flow): → aiwfx-start-epic E-NNNN. It performs the sovereign proposed → active promote and cuts the epic/E-NNNN-<slug> branch that milestone branches fork from — the step aiwfx-start-milestone requires to have run first.
• Epic already active (re-planning or adding milestones mid-epic): → aiwfx-start-milestone <M-NNNN> for the first drafted milestone.

Either way, run this only after the planning commits have landed on main (per step 10) so implementation branches fork cleanly from main rather than stacking on the ritual branch.