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

name	description
milestone-execution	Guide for executing milestones one by one - creating a separate steering directory per milestone, dividing the milestone's features into tasks, and enforcing 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 the milestone plan (docs/milestones/) one milestone at a time. Where /add-feature implements one feature with one steering directory, milestone execution implements one whole milestone per steering directory — and processes milestones strictly in roadmap order.

Core Principles

1. 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.
2. Strict order, one at a time: milestones execute in ascending number. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
3. Features divided into tasks: the milestone's features (from its milestone document) are broken down into concrete tasks in tasklist.md, grouped by feature. The milestone document stays the "what"; the steering tasklist is the "how".
4. 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.
5. Status flows upward: task status lives in the steering tasklist.md; feature and milestone status live in docs/milestones/. When a milestone's last task completes, check off its features, mark the milestone Completed, and advance the roadmap pointer.

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 document)
• 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 docs/milestones/: every feature is checked off, the milestone status is Completed with Completion Notes, and roadmap.md points to the next milestone.

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 milestone document 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 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 milestone document match the completed work.
• roadmap.md statuses and current-milestone pointer are correct.
• No task or feature from a later milestone was implemented early.