ken/opencode-boilerplate
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add /execute-milestones to run milestones one by one with per-milestone steering docs

Browse Source 
- New command /execute-milestones: executes all (or selected) milestones strictly in order; for each milestone creates a separate .steering/[date]-milestone-NN-[name]/ directory, divides its features into tasks grouped by feature, implements, validates, tests, reconciles docs, and updates milestone/roadmap statuses before starting the next
- New skill milestone-execution: per-milestone steering structure, task-division rules, gate criteria between milestones, and failure handling
- plan-milestones completion message, AGENTS.md, README, and docs/milestones/README.md updated

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Ken Yasue
2026-07-02 11:32:01 +02:00
parent 5e30ac8ef3
commit 00cb087f77
6 changed files with 288 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

91
.opencode/skills/milestone-execution/SKILL.md Normal file
View File

@ -0,0 +1,91 @@
---
name: milestone-execution
description: 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`:
```markdown
# 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.