opencode-boilerplate/.opencode/command/execute-milestones.md

description	agent
Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously	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

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
"