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>

.opencode/command/add-feature.md

@@ -27,6 +27,7 @@ agent: build
 
 1. Read `AGENTS.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
 
@@ -147,9 +148,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
 
@@ -157,6 +163,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.

.opencode/command/define-design.md

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

.opencode/command/generate-app.md

@@ -27,6 +27,8 @@ opencode
   ↓
 /generate-app web | flutter | winui3   ← you are here
   ↓
+/plan-milestones
+  ↓
 /add-feature
 ```
 
@@ -142,6 +144,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
 "

.opencode/command/plan-milestones.md

@@ -0,0 +1,142 @@
+---
+description: Plan development milestones and generate milestone documents with the features for each milestone
+agent: build
+---
+
+# 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
+
+```
+opencode
+> /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
+
+Follow the **milestone-planning** skill (loaded automatically) 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
+"
+```

.opencode/skills/milestone-planning/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: milestone-planning
+description: Guide for planning development milestones and generating milestone documents with a feature breakdown. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
+---
+
+# Milestone Planning Skill
+
+This skill explains how to break a product into ordered milestones and produce milestone documents under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation (`/add-feature`): every feature in every milestone is sized to be implemented with **one `/add-feature` run**.
+
+## Core Principles
+
+1. **MVP first**: Milestone 1 is the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
+2. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
+3. **One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor.
+4. **Dependency order**: A feature never lands in an earlier milestone than something it depends on.
+5. **Exactly-once assignment**: Every feature belongs to exactly one milestone. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
+6. **Living documents**: Milestone documents track status. `/add-feature` checks off a feature (`[ ]` → `[x]`) when it completes, and the roadmap status is updated when a milestone finishes.
+
+## Inputs
+
+Before planning, read:
+
+- `docs/product-requirements.md` — user stories, priorities (P0/P1/P2), success metrics
+- `docs/functional-design.md` — functional modules and data flows
+- `docs/architecture.md` — technical constraints and dependencies
+- `docs/design/ui-blueprint.json` (if present) — screens and user actions
+- `docs/ideas/*` (if present)
+
+## Outputs
+
+```
+docs/milestones/
+├── roadmap.md                      # Overview: milestone table, ordering rationale, icebox
+├── milestone-01-[name].md          # MVP
+├── milestone-02-[name].md
+└── milestone-NN-[name].md
+```
+
+File naming: `milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`, `milestone-02-collaboration.md`).
+
+Use the structure in `template.md` for each milestone document.
+
+## How to Slice Features
+
+A well-sized feature:
+
+- Delivers observable user value (or unblocks one that does)
+- Touches one primary screen/flow (may touch shared components)
+- Has 3–7 acceptance criteria
+- Can be described in one sentence starting with a verb ("Edit user profile", "Filter tasks by tag")
+- Works verbatim as a command argument: `/add-feature Edit user profile`
+
+Too big (split it): "User management" → "Register account", "Log in / log out", "Edit user profile", "Reset password".
+Too small (merge it): "Change button color" → fold into the feature that owns that screen.
+
+## How to Group Milestones
+
+1. Tag every feature with its PRD priority and its dependencies.
+2. Milestone 1 (MVP): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
+3. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful release on its own ("after milestone N ships, the user can additionally …").
+4. Prefer 2–4 milestones with 3–8 features each. More than ~8 features in one milestone usually means it should be split.
+
+## Status Tracking Rules
+
+- Feature status lives **only** in the feature checkbox of its milestone document.
+- Milestone status (`Not started` / `In progress` / `Completed`) lives in both the milestone document header and the roadmap table — keep them in sync.
+- `/add-feature` Step 8 updates the feature checkbox and, when the last feature of a milestone completes, the milestone and roadmap statuses.
+- Re-planning (adding/moving/removing features) must update both the milestone document(s) and `roadmap.md` in the same change.
+
+## Consistency Checklist
+
+Before finishing:
+
+- [ ] Every P0/P1 PRD requirement maps to a feature in some milestone (or is explicitly in the icebox).
+- [ ] Every feature appears in exactly one milestone.
+- [ ] No feature precedes one of its dependencies.
+- [ ] Milestone 1 is a usable end-to-end product on its own.
+- [ ] Every feature has acceptance criteria and a ready-to-run `/add-feature` command line.
+- [ ] `roadmap.md` table matches the milestone documents (names, counts, statuses).

.opencode/skills/milestone-planning/template.md

@@ -0,0 +1,88 @@
+# Milestone Document Template
+
+Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
+
+```markdown
+# Milestone [NN]: [Name]
+
+**Status**: Not started | In progress | Completed
+**Goal**: [One sentence: what the user can do after this milestone that they could not before]
+
+## Scope
+
+### In Scope
+- [Theme or capability included in this milestone]
+
+### Out of Scope
+- [Explicitly excluded item] → [where it lives instead: milestone NN / icebox]
+
+## Dependencies
+
+- [What must exist before this milestone can start: previous milestone, external system, decision]
+
+## Features
+
+> One `/add-feature` run per feature. Check off each feature when its run completes.
+
+- [ ] [Feature 1 name]
+- [ ] [Feature 2 name]
+- [ ] [Feature 3 name]
+
+### Feature: [Feature 1 name]
+
+- **Description**: [What it does and the user value, 1–3 sentences]
+- **Related requirements**: [PRD user story / requirement IDs or headings]
+- **Affected screens**: [screen ids from ui-blueprint.json, or "n/a"]
+- **Acceptance criteria**:
+  - [Criterion 1]
+  - [Criterion 2]
+  - [Criterion 3]
+- **Command**: `/add-feature [Feature 1 name]`
+
+### Feature: [Feature 2 name]
+
+- **Description**: ...
+- **Related requirements**: ...
+- **Affected screens**: ...
+- **Acceptance criteria**:
+  - ...
+- **Command**: `/add-feature [Feature 2 name]`
+
+## Definition of Done
+
+- [ ] All features above are checked off
+- [ ] `npm test`, `npm run lint`, `npm run typecheck` pass
+- [ ] Persistent documents in `docs/` are reconciled with all features
+- [ ] [Milestone-specific criterion, e.g. "demo flow X→Y→Z works end-to-end"]
+
+## Completion Notes
+
+_Filled in when the milestone completes: completion date, deviations from plan, lessons learned._
+```
+
+# Roadmap Template
+
+Use this structure for `docs/milestones/roadmap.md`.
+
+```markdown
+# Development Roadmap
+
+**Current milestone**: [NN — name]
+
+## Milestones
+
+| # | Name | Goal | Features | Status |
+|---|------|------|----------|--------|
+| 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
+| 02 | [name] | [one-line goal] | [count] | Not started |
+
+## Ordering Rationale
+
+[Why this sequence: MVP definition, dependency chains, priority decisions made with the user]
+
+## Later / Icebox
+
+Consciously deferred — revisit when re-planning:
+
+- [Deferred item] — [why deferred]
+```

AGENTS.md

@@ -86,6 +86,11 @@ Define "what to build" and "how to build it" for the entire application:
 - **screens/\*.svg** - Visual wireframes (references only)
 - Created by `/define-design`, updated by `/update-design`, consumed by `/generate-app` and `/add-feature`
 
+#### Milestone Documents (`docs/milestones/`)
+- **roadmap.md** - Milestone overview: table, ordering rationale, current milestone, icebox
+- **milestone-[NN]-[name].md** - One per milestone: goal, scope, and the features it contains (each sized for one `/add-feature` run)
+- Created by `/plan-milestones`; `/add-feature` checks features off as it completes them
+
 ### Work-Unit Documents (`.steering/`)
 
 Define "what to do this time" for a specific development task:
@@ -97,8 +102,8 @@ Define "what to do this time" for a specific development task:
 ### opencode Configuration (`.opencode/`)
 
 - `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator)
-- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, add-feature, review-docs)
+- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, add-feature, review-docs)
-- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, steering)
+- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, milestone-planning, steering)
 
 ## Development Process
 
@@ -109,7 +114,8 @@ Define "what to do this time" for a specific development task:
 3. Define the UI/UX design with `/define-design` (creates `docs/design/`)
 4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code
 5. Generate the initial app with `/generate-app web | flutter | winui3`
-6. Implement features with `/add-feature [feature]`
+6. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with the features for each milestone)
+7. Implement features with `/add-feature [feature]`, milestone by milestone
 
 ### Day-to-Day Usage
 
@@ -129,6 +135,10 @@ Define "what to do this time" for a specific development task:
 > /generate-app web
 > /update-design add a profile screen
 
+# Milestone planning
+> /plan-milestones
+> /plan-milestones 3 milestones, MVP first
+
 # Detailed review (when a detailed report is needed)
 > /review-docs docs/product-requirements.md
 ```

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>`
+### Step 6 — Plan milestones: `/plan-milestones`
-A fully autonomous loop, one feature at a time. Each run:
+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
+### Step 8 — Repeat and maintain
-- More features → `/add-feature <feature>` (again and again)
+- 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/                # UI/UX design spec (created by /define-design)
-│       ├── design-brief.md
+│   │   ├── design-brief.md
-│       ├── design-tokens.json
+│   │   ├── design-tokens.json
-│       ├── ui-blueprint.json         # source of truth for UI
+│   │   ├── ui-blueprint.json         # source of truth for UI
-│       ├── platform-mapping.md
+│   │   ├── platform-mapping.md
-│       └── screens/*.svg             # visual references only
+│   │   └── 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
+2. Reads the feature's milestone document (`docs/milestones/`) for scope and acceptance criteria
-3. Generates the steering files (planning mode of the steering skill)
+3. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
-4. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
+4. Generates the steering files (planning mode of the steering skill)
-5. Launches the `implementation-validator` subagent for quality review
+5. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
-6. Runs `npm test`, `npm run lint`, `npm run typecheck`
+6. Launches the `implementation-validator` subagent for quality review
-7. Records a retrospective and reconciles all six persistent docs with the feature
+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
+5. Run `/plan-milestones` to break the product into milestones with a feature list each
-6. Use `/update-design` whenever a feature changes the UI
+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

docs/milestones/README.md

@@ -0,0 +1,40 @@
+# Milestone Documents (`docs/milestones/`)
+
+This directory holds the project's **milestone plan**: an ordered breakdown of the product into releases, with the features for each milestone. It is created by `/plan-milestones` and kept up to date by `/add-feature`.
+
+## Structure
+
+```
+docs/milestones/
+├── roadmap.md                      # Overview: milestone table, ordering rationale, icebox
+├── milestone-01-[name].md          # Milestone 1 (the MVP)
+├── milestone-02-[name].md
+└── milestone-NN-[name].md
+```
+
+## File purposes
+
+### `roadmap.md`
+The overview: a table of all milestones (goal, feature count, status), the ordering rationale, a pointer to the current milestone, and a "Later / Icebox" list of consciously deferred items.
+
+### `milestone-[NN]-[name].md`
+One document per milestone. Contains the milestone's goal, scope, dependencies, and its **feature list** — each feature sized for exactly one `/add-feature` run, with description, related PRD requirements, affected screens, acceptance criteria, and the ready-to-run command.
+
+## Status tracking
+
+- Each feature has a checkbox in its milestone document; `/add-feature` checks it off (`[ ]` → `[x]`) when the feature completes.
+- Milestone status (`Not started` / `In progress` / `Completed`) is kept in sync between the milestone document and the roadmap table.
+
+## Workflow
+
+```
+/setup-project     → product/architecture docs
+/define-design     → UI/UX design spec
+/generate-app      → initial app shell
+/plan-milestones   → creates the files above
+/add-feature       → implements one feature, then checks it off here
+```
+
+## Status
+
+This directory is populated by running `/plan-milestones`. Until then, the files above do not exist.