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, AGENTS.md, README, and docs/milestones/README.md updated

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

.opencode/command/execute-milestones.md

@@ -0,0 +1,150 @@
+---
+description: Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously
+agent: build
+---
+
+# 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
+
+```
+opencode
+> /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. Follow the **milestone-execution** skill (loaded automatically) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
+2. The **steering** and **development-guidelines** skills 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:
+
+- Follow the **steering** skill in **implementation mode**; follow the coding standards in the **development-guidelines** skill.
+- 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
+npm test
+npm run lint
+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. Follow the **steering** skill 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
+"
+```

.opencode/command/plan-milestones.md

@@ -136,7 +136,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]
+- Run /execute-milestones to implement all milestones one by one autonomously (a separate steering directory is created per milestone)
-- /add-feature marks each feature complete in its milestone document as it finishes
+- 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
 "
 ```

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

@@ -0,0 +1,91 @@
+---
+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.
+---
+
+# 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.

AGENTS.md

@@ -102,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, plan-milestones, add-feature, review-docs)
+- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, execute-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, milestone-planning, 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, 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

@@ -49,8 +49,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>`
+### Step 7 — Implement the milestones
-A fully autonomous loop, one feature at a time, milestone by milestone. Each run:
+
+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
@@ -60,7 +71,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>`
@@ -212,6 +223,7 @@ opencode
     │   ├── generate-app.md
     │   ├── update-design.md
     │   ├── plan-milestones.md
+    │   ├── execute-milestones.md
     │   ├── add-feature.md
     │   └── review-docs.md
     └── skills/                # Task-specific skills
@@ -225,6 +237,7 @@ opencode
         ├── design-tokens/         (SKILL.md)
         ├── platform-ui-generation/(SKILL.md)
         ├── milestone-planning/    (SKILL.md + template.md)
+        ├── milestone-execution/   (SKILL.md)
         └── steering/              (SKILL.md + templates/)
 ```
 
@@ -359,7 +372,21 @@ This fully autonomous workflow:
 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
 
-### 6. Review a document
+### 6. Execute all milestones one by one (alternative to per-feature runs)
+
+```
+> /execute-milestones            # all remaining milestones, in order
+> /execute-milestones 1          # only milestone 1
+> /execute-milestones 2-3       # milestones 2 through 3
+```
+
+Works through the milestone plan autonomously, one milestone at a time. For each milestone it
+creates a **separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
+milestone's features into tasks grouped by feature, implements everything, validates, runs the
+test suite, reconciles the docs, marks the milestone `Completed` — and immediately starts the next
+one. It only stops early on a genuine external blocker, which it records in the roadmap.
+
+### 7. Review a document
 
 ```
 > /review-docs docs/product-requirements.md
@@ -368,7 +395,7 @@ This fully autonomous workflow:
 Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
 completeness, clarity, consistency, implementability, and measurability.
 
-### 7. Day-to-day editing
+### 8. Day-to-day editing
 
 You don't always need a command — just ask in normal conversation:
 
@@ -393,7 +420,7 @@ Recommended workflow:
    - Run `/update-design <change>` for targeted refinements
 4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
 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
+6. Use `/execute-milestones` to implement all milestones one by one, or `/add-feature` to go feature by feature
 7. Use `/update-design` whenever a feature changes the UI
 
 Source of truth:
@@ -416,6 +443,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
 | `/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` |
+| `/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` |
 
@@ -435,6 +463,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
 | `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 |
+| `milestone-execution` | Executing milestones one by one with per-milestone steering docs | `.steering/[date]-milestone-NN-[name]/` 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

@@ -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
 ```