Add milestone planning phase between /generate-app and /add-feature

- New command /plan-milestones: generates docs/milestones/ (roadmap.md + one document per milestone with its features, acceptance criteria, and ready-to-run /add-feature commands)
- New skill milestone-planning: MVP-first vertical-slice planning rules + milestone/roadmap templates
- /add-feature: reads the feature's milestone document before planning and checks the feature off (updating milestone/roadmap status) in Step 8
- Workflow diagrams, CLAUDE.md, README, and settings.json updated for the new phase

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.claude/commands/add-feature.md

@@ -26,6 +26,7 @@ description: Implement a new feature following existing patterns, fully autonomo
 
 1. Read `CLAUDE.md` to grasp the overall picture of the project.
 2. Review the persistent documents in the `docs/` directory to understand the relevant design philosophy and architecture.
+3. If `docs/milestones/` exists, read `docs/milestones/roadmap.md` and find the milestone document that contains this feature. Use its description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any milestone, note that it is unplanned work and proceed.
 
 ## Step 3: Investigate Existing Patterns
 
@@ -149,9 +150,14 @@ If any of the following situations occur while the implementation loop is runnin
    - ✅ `docs/development-guidelines.md` — add/update any new conventions, patterns, or standards established during the feature
    - ✅ `docs/glossary.md` — add/update any new domain terms introduced by the feature
 
-3. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
+3. **Update the milestone documents (if `docs/milestones/` exists)**:
+   - In the feature's milestone document, use the `Edit` tool to check the feature off (`[ ]` → `[x]`).
+   - If this was the last unchecked feature of the milestone, set the milestone's status to `Completed` (in both the milestone document and `docs/milestones/roadmap.md`), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone.
+   - If the feature was not part of any milestone, add it to the current milestone's document as a completed (`[x]`) feature so the plan reflects reality.
 
-4. **Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.**
+4. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
+
+5. **Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.**
 
 ## Completion Criteria
 
@@ -159,6 +165,6 @@ This workflow completes automatically once all of the following conditions are m
 - Step 5: All tasks in `tasklist.md` are complete (`[x]` or skipped for a valid reason).
 - Step 6: The `implementation-validator` subagent's validation passes.
 - Step 7: The `test`, `lint`, and `typecheck` commands all succeed without errors.
-- Step 8: Handover notes are recorded in `tasklist.md`, and all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each).
+- Step 8: Handover notes are recorded in `tasklist.md`, all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each), and the feature is checked off in its milestone document (if `docs/milestones/` exists).
 
 Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.

.claude/commands/define-design.md

@@ -25,6 +25,8 @@ claude
   ↓
 /generate-app web | flutter | winui3
   ↓
+/plan-milestones
+  ↓
 /add-feature
 ```
 

.claude/commands/generate-app.md

@@ -26,6 +26,8 @@ claude
   ↓
 /generate-app web | flutter | winui3   ← you are here
   ↓
+/plan-milestones
+  ↓
 /add-feature
 ```
 
@@ -141,6 +143,7 @@ Generated:
 
 Next steps:
 - Run the app and verify the shell renders
+- Run /plan-milestones to break the product into milestones with a feature list each
 - Use /add-feature to implement features (they will respect the design spec)
 - Use /update-design when a feature changes the UI
 "

.claude/commands/plan-milestones.md

@@ -0,0 +1,141 @@
+---
+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
+
+```bash
+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:
+   ```bash
+   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
+- Start milestone 1: run /add-feature [first feature of milestone 1]
+- /add-feature marks each feature complete in its milestone document as it finishes
+"
+```