claudecode-boilerplate/.claude/commands/execute-milestones.md

---
description: Execute one phase file (phaseN-milestones.md) - implement its milestones one by one with separate steering documents per milestone
---

# Execute Milestones (Fully Autonomous Phase Execution Mode)

This command executes **one phase file** from `docs/milestones/` — implementing its milestones **one at a time, in order**. 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 in the phase file.

**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.

**Phase file (required)**: `$ARGUMENTS` — the phase file to execute. Accepted forms:
- `phase1-milestones.md`
- `docs/milestones/phase1-milestones.md`
- `phase1` or `1` (resolved to `docs/milestones/phase1-milestones.md`)

## How to Run

```bash
claude
> /execute-milestones phase1-milestones.md
> /execute-milestones docs/milestones/phase2-milestones.md
> /execute-milestones 1
```

## Position in the Workflow

```
/setup-project
  ↓
/define-design
  ↓
/plan-milestones
  ↓
/execute-milestones phase1-milestones.md   ← you are here (one phase file per run)
  ↓
/execute-milestones phase2-milestones.md   (next run)
```

## Pre-Run Check

1. **The phase file argument is required.** If `$ARGUMENTS` is empty, or it does not resolve to an existing `docs/milestones/phase[N]-milestones.md` file, **stop**, list the phase files that exist under `docs/milestones/` with their statuses, and ask the user to specify one. Never pick a phase file yourself.
2. If no phase files exist at all, stop and tell the user to run `/plan-milestones` first.
3. Read `docs/milestones/roadmap.md`. If an **earlier phase** is not yet `Completed`, warn the user (later phases build on earlier ones) and continue only if the user accepts.
4. 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 the specified phase file and `docs/milestones/roadmap.md`.
2. The execution queue is every milestone in the phase file whose status is not already `Completed`, in ascending milestone number.
3. If the queue is empty, report that the phase is already completed and finish.
4. Set the phase's status to `In progress` (in the phase file header and in `roadmap.md`).

### 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`.
3. **If the milestone is the App Shell milestone (milestone 01)**, additionally load the **platform-ui-generation skill** (`Skill('platform-ui-generation')`) for the design→code mapping rules of the target platform recorded in the milestone. Its E2E verification is the `e2e/app-shell.spec.ts` smoke spec (shell renders, every blueprint route navigates).

### 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 phase file).
- `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 (including Playwright E2E)

1. Write or update the milestone's end-to-end tests following the **e2e-testing skill** (`Skill('e2e-testing')`): one `e2e/[feature-name].spec.ts` per feature in the milestone, covering its acceptance criteria. Set up Playwright first (as described in the skill) if it is missing.
2. Run:

```bash
Bash('npm test')
Bash('npm run lint')
Bash('npm run typecheck')
Bash('npm run test:e2e')
```

If any command fails, analyze, fix, and re-run until all pass. Never skip or delete a failing test to make verification 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 **phase file**: check off every feature of this milestone (`[ ]` → `[x]`), set the milestone's status to `Completed`, and fill in its "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.

#### 2.8 Milestone Gate — then Continue

The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck/E2E (Playwright) are green, the six documents are reconciled, and the milestone status is updated in the phase file and the roadmap.

**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`, the phase file, and `roadmap.md`, then stop and report — this is the only permitted early stop.

### Step 3: Close the Phase and Report

1. When the queue is empty, set the phase's status to `Completed` in the phase file header and in `roadmap.md`, and move the roadmap's current-phase pointer to the next phase file (or mark the roadmap complete if this was the last phase).
2. Report per milestone: steering directory created, features implemented, test results, and document updates.

## Completion Criteria

- Every milestone in the specified phase file has status `Completed`.
- The phase's status is `Completed` in both the phase file and `docs/milestones/roadmap.md`.
- Each executed milestone has its own `.steering/[date]-milestone-[NN]-[name]/` directory with all tasks `[x]`.
- Tests, lint, typecheck, and Playwright E2E tests pass on the final state, with E2E coverage for every implemented feature's acceptance criteria.
- The six persistent documents reflect everything implemented.

Completion message:
```
"Phase execution is complete: [phase file]

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 [phase file] and docs/milestones/roadmap.md.

Next steps:
- Review the retrospectives in each milestone's tasklist.md
- Run the app and verify the phase end-to-end
- Continue with the next phase: /execute-milestones [next phase file]
- Re-run /plan-milestones if the remaining roadmap should change
"
```