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, AGENTS.md, and README updated for the new phase

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

README.md

@@ -14,7 +14,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
 How a project goes from idea to working code with this boilerplate:
 
 ```
-Idea → /setup-project → /define-design → refine design → /generate-app → /add-feature (repeat)
+Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /add-feature (repeat)
 ```
 
 ### Step 1 — Write down your idea
@@ -43,19 +43,26 @@ This is the key design-decision gate: iterate on the design while it is still ch
 Scaffolds the app shell from the approved design: theme (from tokens), routes, screens, and
 reusable components. No feature logic yet.
 
-### Step 6 — Implement features: `/add-feature <feature>`
-A fully autonomous loop, one feature at a time. Each run:
+### Step 6 — Plan milestones: `/plan-milestones`
+Breaks the product into an ordered set of milestones and generates `docs/milestones/`:
+a `roadmap.md` overview plus one document per milestone listing **the features it contains** —
+each sized for exactly one `/add-feature` run, with acceptance criteria and a ready-to-run command.
+Milestone 1 is the MVP; later milestones build on it by priority and dependency.
+
+### Step 7 — Implement features: `/add-feature <feature>`
+A fully autonomous loop, one feature at a time, milestone by milestone. Each run:
 
 1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
-2. Reads the design spec first — and updates it first if the feature changes the UI
+2. Reads the feature's milestone document and the design spec first — and updates the design first if the feature changes the UI
 3. Implements every task in `tasklist.md`, checking items off as it goes
 4. Validates quality with the `implementation-validator` subagent
 5. Runs `npm test`, `npm run lint`, `npm run typecheck` until green
-6. Records a retrospective and reconciles all six `docs/` documents with the feature
+6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its milestone document
 
-### Step 7 — Repeat and maintain
-- More features → `/add-feature <feature>` (again and again)
+### Step 8 — Repeat and maintain
+- More features → `/add-feature <feature>`, working through the milestones in order
 - UI changes → `/update-design <change>` first, then `/add-feature`
+- Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation
 - Document quality checks → `/review-docs <path>`
 
 **A feature is "done" when**: all tasks in its tasklist are `[x]`, validation passes,
@@ -182,12 +189,15 @@ opencode
 ├── docs/                      # Persistent design documents
 │   ├── ideas/
 │   │   └── initial-requirements.md   # Brainstorming notes (pre-PRD)
-│   └── design/                # UI/UX design spec (created by /define-design)
-│       ├── design-brief.md
-│       ├── design-tokens.json
-│       ├── ui-blueprint.json         # source of truth for UI
-│       ├── platform-mapping.md
-│       └── screens/*.svg             # visual references only
+│   ├── design/                # UI/UX design spec (created by /define-design)
+│   │   ├── design-brief.md
+│   │   ├── design-tokens.json
+│   │   ├── ui-blueprint.json         # source of truth for UI
+│   │   ├── platform-mapping.md
+│   │   └── screens/*.svg             # visual references only
+│   └── milestones/            # Milestone plan (created by /plan-milestones)
+│       ├── roadmap.md                # overview + status
+│       └── milestone-NN-[name].md    # features per milestone
 │
 ├── .steering/                 # Per-task steering files (created by /add-feature)
 │   └── .gitkeep
@@ -201,6 +211,7 @@ opencode
     │   ├── define-design.md
     │   ├── generate-app.md
     │   ├── update-design.md
+    │   ├── plan-milestones.md
     │   ├── add-feature.md
     │   └── review-docs.md
     └── skills/                # Task-specific skills
@@ -213,6 +224,7 @@ opencode
         ├── ui-design/             (SKILL.md)
         ├── design-tokens/         (SKILL.md)
         ├── platform-ui-generation/(SKILL.md)
+        ├── milestone-planning/    (SKILL.md + template.md)
         └── steering/              (SKILL.md + templates/)
 ```
 
@@ -318,7 +330,20 @@ than on generated code:
 Scaffolds the initial application for the selected target from the design spec — app shell, theme
 (from tokens), routes, screens, and reusable components. No feature logic is implemented here.
 
-### 4. Add a feature
+### 4. Plan milestones
+
+```
+> /plan-milestones
+> /plan-milestones 3 milestones, MVP first
+```
+
+Breaks the product into ordered milestones and generates `docs/milestones/`: a `roadmap.md`
+overview plus one document per milestone listing the features it contains — each sized for one
+`/add-feature` run, with acceptance criteria and a ready-to-run command. Milestone 1 is the MVP.
+You'll be asked once about milestone count, MVP scope, priorities, and constraints; sensible
+defaults are proposed from the PRD.
+
+### 5. Add a feature
 
 ```
 > /add-feature User authentication
@@ -326,14 +351,15 @@ Scaffolds the initial application for the selected target from the design spec
 
 This fully autonomous workflow:
 1. Creates `.steering/[YYYYMMDD]-[feature-name]/` with `requirements.md`, `design.md`, `tasklist.md`
-2. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
-3. Generates the steering files (planning mode of the steering skill)
-4. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
-5. Launches the `implementation-validator` subagent for quality review
-6. Runs `npm test`, `npm run lint`, `npm run typecheck`
-7. Records a retrospective and reconciles all six persistent docs with the feature
+2. Reads the feature's milestone document (`docs/milestones/`) for scope and acceptance criteria
+3. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
+4. Generates the steering files (planning mode of the steering skill)
+5. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
+6. Launches the `implementation-validator` subagent for quality review
+7. Runs `npm test`, `npm run lint`, `npm run typecheck`
+8. Records a retrospective, reconciles all six persistent docs with the feature, and checks the feature off in its milestone document
 
-### 5. Review a document
+### 6. Review a document
 
 ```
 > /review-docs docs/product-requirements.md
@@ -342,7 +368,7 @@ This fully autonomous workflow:
 Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
 completeness, clarity, consistency, implementability, and measurability.
 
-### 6. Day-to-day editing
+### 7. Day-to-day editing
 
 You don't always need a command — just ask in normal conversation:
 
@@ -366,8 +392,9 @@ Recommended workflow:
    - Re-run `/define-design` to change direction, or
    - Run `/update-design <change>` for targeted refinements
 4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
-5. Use `/add-feature` to add features
-6. Use `/update-design` whenever a feature changes the UI
+5. Run `/plan-milestones` to break the product into milestones with a feature list each
+6. Use `/add-feature` to add features, milestone by milestone
+7. Use `/update-design` whenever a feature changes the UI
 
 Source of truth:
 
@@ -388,6 +415,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
 | `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
 | `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
 | `/update-design` | Update the design spec when a feature changes the UI | `/update-design add a profile screen` |
+| `/plan-milestones` | Plan milestones and generate milestone documents with the features for each | `/plan-milestones 3 milestones, MVP first` |
 | `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` |
 | `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` |
 
@@ -406,6 +434,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
 | `ui-design` | Creating the design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
 | `design-tokens` | Creating and maintaining design tokens | `docs/design/design-tokens.json` |
 | `platform-ui-generation` | Converting design files into Web/Flutter/WinUI 3 code | generated app code |
+| `milestone-planning` | Planning milestones and the feature breakdown per milestone | `docs/milestones/` files |
 | `steering` | Planning, implementing, and retrospecting on a task | `.steering/[date]-[name]/` files |
 
 Each skill folder contains a `SKILL.md` (instructions) plus `template.md` and/or `guide.md` (reference