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

name	description
milestone-execution	Guide for executing one phase file (phaseN-milestones.md) - implementing its milestones one by one, with a separate steering directory per milestone, features divided into tasks, and 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 one phase file (docs/milestones/phase[N]-milestones.md) — implementing its milestones one at a time. Where /add-feature implements one feature with one steering directory, milestone execution implements one whole milestone per steering directory, and a /execute-milestones run covers exactly the milestones of the given phase file, strictly in order.

Core Principles

1. One phase file per run: /execute-milestones always operates on an explicitly specified phase file — never on "everything". The next phase requires a new run with the next file.
2. 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.
3. Strict order, one at a time: milestones execute in ascending number within the phase file. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
4. Features divided into tasks: the milestone's features (from its section in the phase file) are broken down into concrete tasks in tasklist.md, grouped by feature. The phase file stays the "what"; the steering tasklist is the "how".
5. 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.
6. Status flows upward: task status lives in the steering tasklist.md; feature, milestone, and phase status live in the phase file and roadmap.md. When a milestone's last task completes, check off its features, mark the milestone Completed, and advance the roadmap pointer; when the phase's last milestone completes, mark the phase Completed and point the roadmap at the next phase file.

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's section in the phase file)
• 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:

# 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 the phase file: every feature of the milestone is checked off, and the milestone status is Completed with Completion Notes.
• roadmap.md points to the next milestone (or, after the phase's last milestone, the phase is Completed and the roadmap points to the next phase file).

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 phase file 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, in the phase file, 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 phase file match the completed work.
• Milestone and phase statuses in the phase file match roadmap.md, and the roadmap pointers are correct.
• No task or feature from a later milestone or a later phase file was implemented early.