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

Restructure milestone plan into phase files; /execute-milestones now requires a phase file

Browse Source 
- /plan-milestones groups milestones into phases and generates one file per phase (phase1-milestones.md, phase2-milestones.md, ...) plus roadmap.md; milestone numbering stays global across phases
- /execute-milestones takes a required phase file argument (phase1-milestones.md | full path | phase1 | 1) and executes only that file's milestones one by one; with no argument it lists available phase files and stops; closes the phase in the roadmap when done
- milestone-planning skill/template rewritten around the Phase > Milestone > Feature hierarchy; milestone-execution skill scoped to one phase file per run
- /add-feature, AGENTS.md, README, and docs/milestones/README.md updated to phase-file references

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

62
.opencode/skills/milestone-planning/SKILL.md
View File

@ -1,20 +1,30 @@
---
name: milestone-planning
description: Guide for planning development milestones and generating milestone documents with a feature breakdown. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
description: Guide for planning development milestones grouped into phases and generating one phase file (phaseN-milestones.md) with the milestones and feature breakdown for each phase. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
---
# Milestone Planning Skill
This skill explains how to break a product into ordered milestones and produce milestone documents under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation (`/add-feature`): every feature in every milestone is sized to be implemented with **one `/add-feature` run**.
This skill explains how to break a product into ordered **phases** and **milestones**, and produce one phase file per phase under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation: every feature in every milestone is sized to be implemented with **one `/add-feature` run**, and every phase file is sized to be executed with **one `/execute-milestones` run**.
## Hierarchy
```
Roadmap (roadmap.md)
└── Phase (phase[N]-milestones.md — the /execute-milestones unit)
└── Milestone (numbered globally: 01, 02, …)
└── Feature (the /add-feature unit)
```
## Core Principles
1. **MVP first**: Milestone 1 is the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
1. **MVP first**: Phase 1 delivers the MVP; milestone 1 is its core — the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
2. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
3. **One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor.
4. **Dependency order**: A feature never lands in an earlier milestone than something it depends on.
5. **Exactly-once assignment**: Every feature belongs to exactly one milestone. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
6. **Living documents**: Milestone documents track status. `/add-feature` checks off a feature (`[ ]` → `[x]`) when it completes, and the roadmap status is updated when a milestone finishes.
4. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release.
5. **Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies.
6. **Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
7. **Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`.
## Inputs
@ -30,15 +40,15 @@ Before planning, read:
```
docs/milestones/
├── roadmap.md # Overview: milestone table, ordering rationale, icebox
├── milestone-01-[name].md # MVP
├── milestone-02-[name].md
└── milestone-NN-[name].md
├── roadmap.md # Overview: phase/milestone table, ordering rationale, icebox
├── phase1-milestones.md # Phase 1 (MVP): its milestones and their features
├── phase2-milestones.md
└── phaseN-milestones.md
```
File naming: `milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`, `milestone-02-collaboration.md`).
File naming: `phase[N]-milestones.md` with `N` starting at 1 (e.g. `phase1-milestones.md`). Milestones are numbered globally and consecutively across all phase files (`01`, `02`, …) — numbering never restarts per phase.
Use the structure in `template.md` for each milestone document.
Use the structure in `template.md` for each phase file and for the roadmap.
## How to Slice Features
@ -53,27 +63,31 @@ A well-sized feature:
Too big (split it): "User management" → "Register account", "Log in / log out", "Edit user profile", "Reset password".
Too small (merge it): "Change button color" → fold into the feature that owns that screen.
## How to Group Milestones
## How to Group Milestones and Phases
1. Tag every feature with its PRD priority and its dependencies.
2. Milestone 1 (MVP): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
3. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful release on its own ("after milestone N ships, the user can additionally …").
4. Prefer 2–4 milestones with 3–8 features each. More than ~8 features in one milestone usually means it should be split.
2. Milestone 1 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish).
3. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone.
4. **Phase 1** contains milestone 1 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each.
5. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state.
## Status Tracking Rules
- Feature status lives **only** in the feature checkbox of its milestone document.
- Milestone status (`Not started` / `In progress` / `Completed`) lives in both the milestone document header and the roadmap table — keep them in sync.
- `/add-feature` Step 8 updates the feature checkbox and, when the last feature of a milestone completes, the milestone and roadmap statuses.
- Re-planning (adding/moving/removing features) must update both the milestone document(s) and `roadmap.md` in the same change.
- Feature status lives **only** in the feature checkbox inside its phase file.
- Milestone status (`Not started` / `In progress` / `Completed`) lives in the milestone's section of the phase file **and** in the roadmap table — keep them in sync.
- Phase status lives in the phase file header **and** in the roadmap table.
- `/add-feature` Step 8 updates the feature checkbox; `/execute-milestones` additionally updates milestone and phase statuses and the roadmap pointers.
- Re-planning (adding/moving/removing features or milestones) must update both the affected phase file(s) and `roadmap.md` in the same change.
## Consistency Checklist
Before finishing:
- [ ] Every P0/P1 PRD requirement maps to a feature in some milestone (or is explicitly in the icebox).
- [ ] Every feature appears in exactly one milestone.
- [ ] No feature precedes one of its dependencies.
- [ ] Milestone 1 is a usable end-to-end product on its own.
- [ ] Every feature appears in exactly one milestone; every milestone in exactly one phase file.
- [ ] Milestone numbering is global and consecutive across phase files.
- [ ] No feature or milestone precedes one of its dependencies.
- [ ] Phase 1 delivers a usable end-to-end MVP on its own.
- [ ] Every feature has acceptance criteria and a ready-to-run `/add-feature` command line.
- [ ] `roadmap.md` table matches the milestone documents (names, counts, statuses).
- [ ] Every phase file header has its ready-to-run `/execute-milestones` command line.
- [ ] `roadmap.md` table matches the phase files (names, counts, statuses).

52
.opencode/skills/milestone-planning/template.md
View File

@ -1,34 +1,42 @@
# Milestone Document Template
# Phase File Template
Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
Use this structure for each `docs/milestones/phase[N]-milestones.md`. A phase file contains one or more milestones; milestone numbers are global across all phase files.
```markdown
# Milestone [NN]: [Name]
# Phase [N]: [Name]
**Status**: Not started | In progress | Completed
**Goal**: [One sentence: what this phase delivers as a release]
**Execute**: `/execute-milestones phase[N]-milestones.md`
**Milestones**: [NN]–[NN]
---
## Milestone [NN]: [Name]
**Status**: Not started | In progress | Completed
**Goal**: [One sentence: what the user can do after this milestone that they could not before]
## Scope
### Scope
### In Scope
#### In Scope
- [Theme or capability included in this milestone]
### Out of Scope
#### Out of Scope
- [Explicitly excluded item] → [where it lives instead: milestone NN / icebox]
## Dependencies
### Dependencies
- [What must exist before this milestone can start: previous milestone, external system, decision]
## Features
### Features
> One `/add-feature` run per feature. Check off each feature when its run completes.
- [ ] [Feature 1 name]
- [ ] [Feature 2 name]
- [ ] [Feature 3 name]
### Feature: [Feature 1 name]
#### Feature: [Feature 1 name]
- **Description**: [What it does and the user value, 1–3 sentences]
- **Related requirements**: [PRD user story / requirement IDs or headings]
@ -39,7 +47,7 @@ Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
- [Criterion 3]
- **Command**: `/add-feature [Feature 1 name]`
### Feature: [Feature 2 name]
#### Feature: [Feature 2 name]
- **Description**: ...
- **Related requirements**: ...
@ -48,16 +56,22 @@ Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
- ...
- **Command**: `/add-feature [Feature 2 name]`
## Definition of Done
### Definition of Done
- [ ] All features above are checked off
- [ ] `npm test`, `npm run lint`, `npm run typecheck` pass
- [ ] Persistent documents in `docs/` are reconciled with all features
- [ ] [Milestone-specific criterion, e.g. "demo flow X→Y→Z works end-to-end"]
## Completion Notes
### Completion Notes
_Filled in when the milestone completes: completion date, deviations from plan, lessons learned._
---
## Milestone [NN+1]: [Name]
[Same structure as above]
```
# Roadmap Template
@ -67,14 +81,16 @@ Use this structure for `docs/milestones/roadmap.md`.
```markdown
# Development Roadmap
**Current phase**: [N — name] (`phase[N]-milestones.md`)
**Current milestone**: [NN — name]
## Milestones
## Phases and Milestones
| # | Name | Goal | Features | Status |
|---|------|------|----------|--------|
| 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
| 02 | [name] | [one-line goal] | [count] | Not started |
| Phase | File | Milestone | Name | Goal | Features | Status |
|-------|------|-----------|------|------|----------|--------|
| 1 | `phase1-milestones.md` | 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
| 1 | `phase1-milestones.md` | 02 | [name] | [one-line goal] | [count] | Not started |
| 2 | `phase2-milestones.md` | 03 | [name] | [one-line goal] | [count] | Not started |
## Ordering Rationale