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

76
README.md
View File

@ -14,7 +14,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
How a project goes from idea to working code with this boilerplate:
```
Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /add-feature (repeat)
Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /execute-milestones (phase by phase)
```
### Step 1 — Write down your idea
@ -44,34 +44,36 @@ Scaffolds the app shell from the approved design: theme (from tokens), routes, s
reusable components. No feature logic yet.
### Step 6 — Plan milestones: `/plan-milestones`
Breaks the product into an ordered set of milestones and generates `docs/milestones/`:
a `roadmap.md` overview plus one document per milestone listing **the features it contains** —
each sized for exactly one `/add-feature` run, with acceptance criteria and a ready-to-run command.
Milestone 1 is the MVP; later milestones build on it by priority and dependency.
Breaks the product into **phases** and milestones, and generates `docs/milestones/`:
a `roadmap.md` overview plus **one file per phase** (`phase1-milestones.md`,
`phase2-milestones.md`, …). Each phase file lists its milestones and **the features they
contain** — each feature sized for exactly one `/add-feature` run, with acceptance criteria and a
ready-to-run command. Phase 1 delivers the MVP; later phases build on it by priority and dependency.
### Step 7 — Implement the milestones
Two ways to work through the plan:
**Option A — execute whole milestones: `/execute-milestones`**
Runs all remaining milestones **one by one, autonomously**. For each milestone it creates a
**separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
milestone's features into concrete tasks grouped by feature, implements them all, validates,
tests, reconciles the docs, and marks the milestone completed — then immediately starts the next
milestone. Takes an optional target (`/execute-milestones 1` or `/execute-milestones 2-3`).
**Option A — execute a phase file: `/execute-milestones <phase-file>`**
Requires the phase file to execute, e.g. `/execute-milestones phase1-milestones.md`. Runs that
phase's milestones **one by one, autonomously**. For each milestone it creates a **separate
steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the milestone's
features into concrete tasks grouped by feature, implements them all, validates, tests,
reconciles the docs, and marks the milestone completed — then immediately starts the next
milestone in the file. When the phase completes, run it again with the next phase file.
**Option B — one feature at a time: `/add-feature <feature>`**
A fully autonomous loop, one feature per run. Each run:
1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
2. Reads the feature's milestone document and the design spec first — and updates the design first if the feature changes the UI
2. Reads the feature's entry in its phase file and the design spec first — and updates the design first if the feature changes the UI
3. Implements every task in `tasklist.md`, checking items off as it goes
4. Validates quality with the `implementation-validator` subagent
5. Runs `npm test`, `npm run lint`, `npm run typecheck` until green
6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its milestone document
6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its phase file
### Step 8 — Repeat and maintain
- Remaining milestones → `/execute-milestones`, or feature by feature with `/add-feature <feature>`
- Remaining phases → `/execute-milestones <next phase file>`, or feature by feature with `/add-feature <feature>`
- UI changes → `/update-design <change>` first, then `/add-feature`
- Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation
- Document quality checks → `/review-docs <path>`
@ -208,7 +210,7 @@ opencode
│ │ └── screens/*.svg # visual references only
│ └── milestones/ # Milestone plan (created by /plan-milestones)
│ ├── roadmap.md # overview + status
│ └── milestone-NN-[name].md # features per milestone
│ └── phaseN-milestones.md # one per phase: milestones + features
│
├── .steering/ # Per-task steering files (created by /add-feature)
│ └── .gitkeep
@ -347,14 +349,14 @@ Scaffolds the initial application for the selected target from the design spec
```
> /plan-milestones
> /plan-milestones 3 milestones, MVP first
> /plan-milestones 2 phases, MVP first
```
Breaks the product into ordered milestones and generates `docs/milestones/`: a `roadmap.md`
overview plus one document per milestone listing the features it contains — each sized for one
`/add-feature` run, with acceptance criteria and a ready-to-run command. Milestone 1 is the MVP.
You'll be asked once about milestone count, MVP scope, priorities, and constraints; sensible
defaults are proposed from the PRD.
Breaks the product into phases and milestones and generates `docs/milestones/`: a `roadmap.md`
overview plus one file per phase (`phase1-milestones.md`, `phase2-milestones.md`, …) listing its
milestones and their features — each feature sized for one `/add-feature` run, with acceptance
criteria and a ready-to-run command. Phase 1 delivers the MVP. You'll be asked once about phase
count, MVP scope, priorities, and constraints; sensible defaults are proposed from the PRD.
### 5. Add a feature
@ -372,19 +374,21 @@ This fully autonomous workflow:
7. Runs `npm test`, `npm run lint`, `npm run typecheck`
8. Records a retrospective, reconciles all six persistent docs with the feature, and checks the feature off in its milestone document
### 6. Execute all milestones one by one (alternative to per-feature runs)
### 6. Execute a phase file (alternative to per-feature runs)
```
> /execute-milestones # all remaining milestones, in order
> /execute-milestones 1 # only milestone 1
> /execute-milestones 2-3 # milestones 2 through 3
> /execute-milestones phase1-milestones.md
> /execute-milestones docs/milestones/phase2-milestones.md
> /execute-milestones 1 # shorthand for phase1-milestones.md
```
Works through the milestone plan autonomously, one milestone at a time. For each milestone it
creates a **separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
milestone's features into tasks grouped by feature, implements everything, validates, runs the
test suite, reconciles the docs, marks the milestone `Completed` — and immediately starts the next
one. It only stops early on a genuine external blocker, which it records in the roadmap.
**The phase file argument is required** — without it the command lists the available phase files
and stops. It then works through that phase's milestones autonomously, one at a time. For each
milestone it creates a **separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`),
divides the milestone's features into tasks grouped by feature, implements everything, validates,
runs the test suite, reconciles the docs, marks the milestone `Completed` — and immediately starts
the next one. When the last milestone finishes, the phase is marked `Completed` in the roadmap.
It only stops early on a genuine external blocker, which it records in the roadmap.
### 7. Review a document
@ -419,8 +423,8 @@ Recommended workflow:
- Re-run `/define-design` to change direction, or
- Run `/update-design <change>` for targeted refinements
4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
5. Run `/plan-milestones` to break the product into milestones with a feature list each
6. Use `/execute-milestones` to implement all milestones one by one, or `/add-feature` to go feature by feature
5. Run `/plan-milestones` to break the product into phases and milestones (one `phaseN-milestones.md` per phase)
6. Use `/execute-milestones phase1-milestones.md` to implement a phase's milestones one by one, or `/add-feature` to go feature by feature
7. Use `/update-design` whenever a feature changes the UI
Source of truth:
@ -442,8 +446,8 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
| `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
| `/update-design` | Update the design spec when a feature changes the UI | `/update-design add a profile screen` |
| `/plan-milestones` | Plan milestones and generate milestone documents with the features for each | `/plan-milestones 3 milestones, MVP first` |
| `/execute-milestones` | Execute milestones one by one, with separate steering documents per milestone | `/execute-milestones` |
| `/plan-milestones` | Plan phases and milestones; generates one `phase[N]-milestones.md` per phase | `/plan-milestones 2 phases, MVP first` |
| `/execute-milestones` | Execute one phase file: its milestones one by one, with separate steering documents per milestone (file argument required) | `/execute-milestones phase1-milestones.md` |
| `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` |
| `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` |
@ -462,8 +466,8 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
| `ui-design` | Creating the design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
| `design-tokens` | Creating and maintaining design tokens | `docs/design/design-tokens.json` |
| `platform-ui-generation` | Converting design files into Web/Flutter/WinUI 3 code | generated app code |
| `milestone-planning` | Planning milestones and the feature breakdown per milestone | `docs/milestones/` files |
| `milestone-execution` | Executing milestones one by one with per-milestone steering docs | `.steering/[date]-milestone-NN-[name]/` files |
| `milestone-planning` | Planning phases/milestones and the feature breakdown per milestone | `docs/milestones/` phase files |
| `milestone-execution` | Executing a phase file's milestones one by one with per-milestone steering docs | `.steering/[date]-milestone-NN-[name]/` files |
| `steering` | Planning, implementing, and retrospecting on a task | `.steering/[date]-[name]/` files |
Each skill folder contains a `SKILL.md` (instructions) plus `template.md` and/or `guide.md` (reference