Add /execute-milestones to run milestones one by one with per-milestone steering docs

- New command /execute-milestones: executes all (or selected) milestones strictly in order; for each milestone creates a separate .steering/[date]-milestone-NN-[name]/ directory, divides its features into tasks grouped by feature, implements, validates, tests, reconciles docs, and updates milestone/roadmap statuses before starting the next
- New skill milestone-execution: per-milestone steering structure, task-division rules, gate criteria between milestones, and failure handling
- plan-milestones completion message, CLAUDE.md, README, docs/milestones/README.md, and settings.json updated

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

.claude/commands/execute-milestones.md

@@ -0,0 +1,149 @@
+---
+description: Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously
+---
+
+# Execute Milestones (Fully Autonomous Milestone Execution Mode)
+
+This command works through the milestone plan in `docs/milestones/` **one milestone at a time**. For each milestone it generates a **separate set of steering documents** under `.steering/`, divides the milestone's features into concrete tasks, implements them all, validates, tests, and reconciles the documents — then immediately moves on to the next milestone.
+
+**Important:** This workflow is designed to run fully automatically from start to finish without user intervention. Do not ask the user for confirmation between milestones.
+
+**Target**: `$ARGUMENTS` — optional: a milestone number (e.g. `2`), a range (e.g. `1-3`), or empty to execute **all remaining milestones in order**.
+
+## How to Run
+
+```bash
+claude
+> /execute-milestones            # execute all remaining milestones one by one
+> /execute-milestones 1          # execute only milestone 1
+> /execute-milestones 2-3       # execute milestones 2 through 3
+```
+
+## Position in the Workflow
+
+```
+/setup-project
+  ↓
+/define-design
+  ↓
+/generate-app web | flutter | winui3
+  ↓
+/plan-milestones
+  ↓
+/execute-milestones      ← you are here (alternative: /add-feature per feature)
+```
+
+## Pre-Run Check
+
+1. Confirm `docs/milestones/roadmap.md` and at least one `docs/milestones/milestone-*.md` exist. If not, stop and tell the user to run `/plan-milestones` first.
+2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user and suggest running `/define-design` first. Do not silently proceed without a design spec.
+
+## Procedure
+
+### Step 0: Build the Execution Queue
+
+1. Read `docs/milestones/roadmap.md` and every milestone document.
+2. The execution queue is the milestones selected by `$ARGUMENTS` (all of them when empty), **excluding** milestones whose status is already `Completed`, in ascending milestone number.
+3. If the queue is empty, report that all selected milestones are already completed and finish.
+
+### Step 1: Load the Skills
+
+1. Load the **milestone-execution skill** (`Skill('milestone-execution')`) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
+2. The **steering skill** and **development-guidelines skill** apply during implementation, exactly as in `/add-feature`.
+
+### Step 2: Milestone Loop
+
+**This step repeats for each milestone in the queue, strictly in order. Never start a milestone before the previous one has passed its gate (Step 2.8).**
+
+For the current milestone `[NN] [name]`:
+
+#### 2.1 Create the Milestone Steering Directory
+
+Create `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` with the three files:
+
+- `requirements.md`
+- `design.md`
+- `tasklist.md`
+
+Each milestone gets its **own** directory — never reuse or append to another milestone's steering documents.
+
+#### 2.2 Generate the Steering Documents
+
+Following the milestone-execution skill:
+
+- `requirements.md`: the milestone's goal, scope, and every feature with its description, related PRD requirements, affected screens, and acceptance criteria (copied and expanded from the milestone document).
+- `design.md`: the implementation approach across the milestone's features — shared components, data model changes, and order of implementation — consistent with `docs/architecture.md` and `docs/design/`.
+- `tasklist.md`: the milestone's features **divided into concrete tasks, grouped by feature** (one `## Feature:` section per feature, each ending with its verification tasks). Every task must be small enough to complete in one implementation-loop iteration.
+
+#### 2.3 Check the Design Specification
+
+Apply `/add-feature` Step 3.5 for the milestone as a whole: read all four design files before implementation; if any feature in this milestone changes the UI, update the design files first (blueprint → tokens → brief → mapping → SVGs).
+
+#### 2.4 Implementation Loop
+
+Work through `tasklist.md` top to bottom using the same rules as `/add-feature` Step 5:
+
+- Use `Skill('steering')` in **implementation mode**; follow the coding standards in `Skill('development-guidelines')`.
+- Mark each task `[ ]` → `[x]` with the `Edit` tool as it completes.
+- Exception rules A (split oversized tasks) and B (strike obsolete tasks with a reason) apply.
+- **Forbidden**: skipping tasks, ending the loop with unchecked tasks, or asking the user to decide.
+
+#### 2.5 Validate the Milestone
+
+Use the `Task` tool to launch the `implementation-validator` subagent:
+- `subagent_type`: "implementation-validator"
+- `description`: "Milestone implementation validation"
+- `prompt`: "Please validate the quality of all changes implemented for milestone `[NN] [name]`. The target files are `[list of implemented file paths]`. Focus on coding standards, error handling, testability, consistency with existing patterns, and whether every feature's acceptance criteria in `.steering/[dir]/requirements.md` are met."
+
+#### 2.6 Run Automated Tests
+
+```bash
+Bash('npm test')
+Bash('npm run lint')
+Bash('npm run typecheck')
+```
+
+If any command fails, analyze, fix, and re-run until all pass.
+
+#### 2.7 Retrospective and Document Reconciliation
+
+Apply `/add-feature` Step 8 for the milestone:
+
+1. Run `Skill('steering')` in **retrospective mode**; record handover notes in this milestone's `tasklist.md`.
+2. Reconcile all six persistent documents in `docs/` with everything implemented in this milestone (updates applied, or a skip reason noted for each).
+3. In the milestone document: check off every feature (`[ ]` → `[x]`), set the status to `Completed`, and fill in the "Completion Notes".
+4. In `docs/milestones/roadmap.md`: set this milestone's status to `Completed` and move the current-milestone pointer to the next milestone in the queue (or mark the roadmap complete).
+
+#### 2.8 Milestone Gate — then Continue
+
+The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck are green, the six documents are reconciled, and the milestone + roadmap statuses are updated.
+
+**Once the gate passes, never stop; immediately start Step 2 for the next milestone in the queue.** If the gate genuinely cannot be passed (external blocker), record the blocker in the milestone's `tasklist.md` and in `roadmap.md`, then stop and report — this is the only permitted early stop.
+
+### Step 3: Final Report
+
+When the queue is empty, report per milestone: steering directory created, features implemented, test results, and document updates.
+
+## Completion Criteria
+
+- Every milestone in the execution queue has status `Completed` in `docs/milestones/roadmap.md`.
+- Each executed milestone has its own `.steering/[date]-milestone-[NN]-[name]/` directory with all tasks `[x]`.
+- Tests, lint, and typecheck pass on the final state.
+- The six persistent documents reflect everything implemented.
+
+Completion message:
+```
+"Milestone execution is complete!
+
+Executed:
+✅ Milestone 01 [name] — .steering/[date]-milestone-01-[name]/ ([n] features, [m] tasks)
+✅ Milestone NN [name] — .steering/[date]-milestone-NN-[name]/ ([n] features, [m] tasks)
+
+All statuses updated in docs/milestones/roadmap.md.
+
+Next steps:
+- Review the retrospectives in each milestone's tasklist.md
+- Run the app and verify the milestones end-to-end
+- Re-run /plan-milestones if the remaining roadmap should change
+"
+```

.claude/commands/plan-milestones.md

@@ -135,7 +135,8 @@ Milestone documents created:
 
 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
+- 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
 "
 ```

.claude/settings.json

@@ -11,6 +11,7 @@
       "Skill(design-tokens)",
       "Skill(platform-ui-generation)",
       "Skill(milestone-planning)",
+      "Skill(milestone-execution)",
       "Skill(steering)"
     ],
     "deny": [],

.claude/skills/milestone-execution/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: milestone-execution
+description: Guide for executing milestones one by one - creating a separate steering directory per milestone, dividing the milestone's features into tasks, and enforcing gate criteria between milestones. Use when running /execute-milestones or implementing a whole milestone in one run.
+allowed-tools: Read, Write, Edit, Bash
+---
+
+# Milestone Execution Skill
+
+This skill explains how to execute the milestone plan (`docs/milestones/`) one milestone at a time. Where `/add-feature` implements **one feature** with one steering directory, milestone execution implements **one whole milestone** per steering directory — and processes milestones strictly in roadmap order.
+
+## Core Principles
+
+1. **One milestone = one steering directory**: every milestone gets its own `.steering/[YYYYMMDD]-milestone-[NN]-[name]/` with its own `requirements.md`, `design.md`, and `tasklist.md`. Documents are never shared or reused between milestones.
+2. **Strict order, one at a time**: milestones execute in ascending number. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
+3. **Features divided into tasks**: the milestone's features (from its milestone document) are broken down into concrete tasks in `tasklist.md`, grouped by feature. The milestone document stays the "what"; the steering tasklist is the "how".
+4. **Same discipline as `/add-feature`**: the steering skill's implementation mode, the development guidelines, the validator subagent, and the test loop all apply per milestone.
+5. **Status flows upward**: task status lives in the steering `tasklist.md`; feature and milestone status live in `docs/milestones/`. When a milestone's last task completes, check off its features, mark the milestone `Completed`, and advance the roadmap pointer.
+
+## Steering Directory per Milestone
+
+Naming: `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` (e.g. `.steering/20260702-milestone-01-mvp/`).
+
+### `requirements.md`
+- Milestone goal (from the milestone document)
+- In/out of scope
+- One section per feature: description, related PRD requirements, affected screens, acceptance criteria
+- The milestone's Definition of Done
+
+### `design.md`
+- Implementation approach across the whole milestone
+- Shared components and data-model changes used by multiple features (build these first)
+- Feature implementation order within the milestone, with a one-line rationale
+- Consistency notes against `docs/architecture.md` and `docs/design/ui-blueprint.json`
+
+### `tasklist.md`
+Tasks are **grouped by feature**, in the implementation order chosen in `design.md`:
+
+```markdown
+# Tasklist: Milestone 01 — MVP
+
+## Shared Foundations
+- [ ] [Task that multiple features depend on, e.g. data model, shared component]
+
+## Feature: Register account
+- [ ] [Task 1: data/model layer]
+- [ ] [Task 2: logic/service layer]
+- [ ] [Task 3: UI per affected screen]
+- [ ] [Task 4: tests for the acceptance criteria]
+
+## Feature: Log in / log out
+- [ ] ...
+
+## Milestone Verification
+- [ ] All acceptance criteria in requirements.md confirmed
+- [ ] npm test / lint / typecheck pass
+
+## Post-Implementation Retrospective
+_Filled at the end: completion date, plan vs. actual, lessons learned._
+```
+
+## How to Divide a Feature into Tasks
+
+- 3–8 tasks per feature; each completable in **one implementation-loop iteration**.
+- Slice along the natural layers the feature touches: data/model → logic/service → UI (one task per affected screen) → tests.
+- Every feature's section ends with a task that verifies its acceptance criteria.
+- Tasks that unblock several features go into a "Shared Foundations" section at the top — never duplicated per feature.
+
+## Gate Criteria Between Milestones
+
+A milestone passes its gate only when **all** of the following hold. Only then may the next milestone start:
+
+- [ ] Every task in the milestone's `tasklist.md` is `[x]` (or struck with a technical reason).
+- [ ] The `implementation-validator` subagent's validation passed.
+- [ ] `npm test`, `npm run lint`, `npm run typecheck` all succeed.
+- [ ] The six persistent documents in `docs/` are reconciled with the milestone's changes.
+- [ ] In `docs/milestones/`: every feature is checked off, the milestone status is `Completed` with Completion Notes, and `roadmap.md` points to the next milestone.
+
+## Failure Handling
+
+- **A task fails repeatedly**: split it (exception rule A) or re-approach via `design.md`; do not skip it.
+- **A feature turns out to be unimplementable as specified**: update the milestone document and `requirements.md` with the revised scope and reason, then continue — the plan must reflect reality.
+- **An external blocker stops the milestone** (missing credential, unavailable service, a decision only the user can make): record the blocker in the milestone's `tasklist.md` and in `roadmap.md` (status stays `In progress`), then stop and report. This is the **only** permitted early stop; never silently skip to the next milestone, because later milestones depend on earlier ones.
+
+## Consistency Checklist
+
+Before declaring a milestone (or the whole run) complete:
+
+- [ ] Each executed milestone has exactly one steering directory, named `[date]-milestone-[NN]-[name]`.
+- [ ] Every feature of the milestone appears as a section in that `tasklist.md`.
+- [ ] Feature checkboxes in the milestone document match the completed work.
+- [ ] `roadmap.md` statuses and current-milestone pointer are correct.
+- [ ] No task or feature from a later milestone was implemented early.

CLAUDE.md

@@ -102,8 +102,8 @@ Define "what to do this time" for a specific development task:
 ### Claude Code Configuration (`.claude/`)
 
 - `.claude/agents/` - Subagent definitions (doc-reviewer, implementation-validator)
-- `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, add-feature, review-docs)
-- `.claude/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)
+- `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
+- `.claude/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, milestone-execution, steering)
 
 ## Development Process
 
@@ -115,7 +115,9 @@ Define "what to do this time" for a specific development task:
 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. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with the features for each milestone)
-7. Implement features with `/add-feature [feature]`, milestone by milestone
+7. Implement, either way:
+   - `/execute-milestones` — execute all milestones one by one autonomously (one steering directory per milestone), or
+   - `/add-feature [feature]` — one feature at a time, milestone by milestone
 
 ### Day-to-Day Usage
 
@@ -135,9 +137,11 @@ Define "what to do this time" for a specific development task:
 > /generate-app web
 > /update-design add a profile screen
 
-# Milestone planning
+# Milestone planning and execution
 > /plan-milestones
 > /plan-milestones 3 milestones, MVP first
+> /execute-milestones
+> /execute-milestones 1
 
 # Detailed review (when a detailed report is needed)
 > /review-docs docs/product-requirements.md

README.md

@@ -48,8 +48,19 @@ a `roadmap.md` overview plus one document per milestone listing **the features i
 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:
+### Step 7 — Implement the milestones
+
+Two ways to work through the plan:
+
+**Option A — execute whole milestones: `/execute-milestones`**
+Runs all remaining milestones **one by one, autonomously**. For each milestone it creates a
+**separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
+milestone's features into concrete tasks grouped by feature, implements them all, validates,
+tests, reconciles the docs, and marks the milestone completed — then immediately starts the next
+milestone. Takes an optional target (`/execute-milestones 1` or `/execute-milestones 2-3`).
+
+**Option B — one feature at a time: `/add-feature <feature>`**
+A fully autonomous loop, one feature per run. Each run:
 
 1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
 2. Reads the feature's milestone document and the design spec first — and updates the design first if the feature changes the UI
@@ -59,7 +70,7 @@ A fully autonomous loop, one feature at a time, milestone by milestone. Each run
 6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its milestone document
 
 ### Step 8 — Repeat and maintain
-- More features → `/add-feature <feature>`, working through the milestones in order
+- Remaining milestones → `/execute-milestones`, or feature by feature with `/add-feature <feature>`
 - 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>`
@@ -99,7 +110,8 @@ claude
 > /update-design [refinement]      # repeat until the design is approved
 > /generate-app web                 # or flutter | winui3
 > /plan-milestones
-> /add-feature [feature name]       # milestone by milestone
+> /execute-milestones               # all milestones one by one, or:
+> /add-feature [feature name]       # one feature at a time
 ```
 
 See [Development Workflow (Step by Step)](#development-workflow-step-by-step) above for what each step does.
@@ -113,5 +125,6 @@ See [Development Workflow (Step by Step)](#development-workflow-step-by-step) ab
 | `/update-design` | Refine the design before generation, or update it when a feature changes the UI | `/update-design add a profile screen` |
 | `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
 | `/plan-milestones` | Plan milestones and generate milestone documents with the features for each | `/plan-milestones 3 milestones, MVP first` |
+| `/execute-milestones` | Execute milestones one by one, with separate steering documents per milestone | `/execute-milestones` |
 | `/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` |

docs/milestones/README.md

@@ -32,6 +32,7 @@ One document per milestone. Contains the milestone's goal, scope, dependencies,
 /define-design     → UI/UX design spec
 /generate-app      → initial app shell
 /plan-milestones   → creates the files above
+/execute-milestones → implements all milestones one by one (one steering directory per milestone), updating statuses here
 /add-feature       → implements one feature, then checks it off here
 ```