claudecode-boilerplate/.claude/commands/plan-milestones.md

description
Plan development milestones and generate milestone documents with the features for each milestone

Plan Milestones (Milestone Planning Phase)

This command breaks the product down into an ordered set of milestones and generates milestone documents under docs/milestones/. Each milestone document lists the features it contains, sized so that each feature can be implemented with one /add-feature run.

Planning preferences (optional): $ARGUMENTS (e.g. /plan-milestones 3 milestones, MVP in 2 weeks, auth first)

How to Run

claude
> /plan-milestones
> /plan-milestones 3 milestones, MVP first, payments last

Position in the Workflow

/setup-project
  ↓
/define-design
  ↓
/generate-app web | flutter | winui3
  ↓
/plan-milestones        ← you are here
  ↓
/add-feature (once per feature, milestone by milestone)

Pre-Run Check

1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run /setup-project first:
   • docs/product-requirements.md
   • docs/functional-design.md
   • docs/architecture.md
2. Check whether the design files (docs/design/ui-blueprint.json etc.) exist. If they do not, warn the user that milestones will be planned without a design spec and suggest running /define-design first. Continue only if the user accepts.
3. Create the milestones directory if it does not exist:

   mkdir -p docs/milestones
   

Procedure

Step 0: Read the Inputs

Read all of the following:

• docs/product-requirements.md (especially user stories and priorities)
• docs/functional-design.md
• docs/architecture.md
• docs/design/ui-blueprint.json and docs/design/design-brief.md (if present)
• docs/ideas/* (if present)
• The planning preferences provided in $ARGUMENTS (if any)

Step 1: Gather Planning Preferences (ask the user once)

If $ARGUMENTS does not already answer these, ask the user about the following. If the user does not provide detailed preferences, propose a sensible default derived from the PRD priorities and confirm it before proceeding.

• Number of milestones (default: 2–4 depending on scope)
• MVP definition — what is the smallest product worth releasing?
• Priorities — features that must come first or last
• Constraints — deadlines, dependencies on external systems, team capacity

Collect the answers in a single round; do not pause again until generation is complete.

Step 2: Load the Milestone Planning Skill

Load the milestone-planning skill (Skill('milestone-planning')) for the planning rules and the milestone document template.

Step 3: Build the Feature Inventory

Derive the complete list of features from the documents:

• Every user story / requirement in the PRD (with its priority)
• Every functional module in the functional design
• Every screen and user action in ui-blueprint.json (if present)

Size each feature so it can be implemented with one /add-feature run. Split anything larger; merge trivial fragments.

Step 4: Group Features into Milestones

• Milestone 1 is the MVP: the smallest set of features that forms a coherent, end-to-end usable product.
• Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
• Every feature belongs to exactly one milestone. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.

Step 5: Create the Roadmap Overview

Create docs/milestones/roadmap.md containing:

• A table of all milestones: number, name, goal, feature count, status (Not started / In progress / Completed)
• The ordering rationale (why this sequence)
• A pointer to the current milestone
• The "Later / Icebox" list of consciously deferred items

Step 6: Create One Document per Milestone

For each milestone, create docs/milestones/milestone-[NN]-[kebab-case-name].md (e.g. milestone-01-mvp.md) following the milestone-planning skill's template. Each document lists the milestone's features, and each feature includes:

• A checkbox for status tracking (- [ ])
• Description and user value
• Related PRD requirements / user stories
• Affected screens from ui-blueprint.json (if a design spec exists)
• Acceptance criteria
• The ready-to-run command: /add-feature [feature name]

Step 7: Consistency Check

Re-read all generated files and confirm:

• Every P0/P1 requirement in the PRD is covered by a milestone (or explicitly parked in the icebox).
• Every feature appears in exactly one milestone.
• Dependencies are ordered correctly across milestones.
• Milestone 1 is a coherent, usable MVP on its own.
• Each feature name works as a /add-feature argument.

Fix any inconsistencies found before finishing.

Completion Criteria

• docs/milestones/roadmap.md exists
• One milestone-[NN]-[name].md per milestone exists
• Every feature is assigned to exactly one milestone with acceptance criteria

Completion message:

"Milestone planning is complete!

Milestone documents created:
✅ docs/milestones/roadmap.md            (overview + status)
✅ docs/milestones/milestone-01-....md   (MVP)
✅ docs/milestones/milestone-NN-....md

Next steps:
- Review docs/milestones/ and adjust priorities if needed
- Run /execute-milestones to implement all milestones one by one autonomously (a separate steering directory is created per milestone)
- Or go feature by feature: run /add-feature [first feature of milestone 1]
- Either way, each feature is marked complete in its milestone document as it finishes
"