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