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

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

Position in the Workflow

/setup-project
  ↓
/define-design
  ↓
/generate-app web | flutter | winui3
  ↓
/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.

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('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
"