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

10
.opencode/command/add-feature.md
View File

@ -27,7 +27,7 @@ agent: build
1. Read `AGENTS.md` to grasp the overall picture of the project.
2. Review the persistent documents in the `docs/` directory to understand the relevant design philosophy and architecture.
3. If `docs/milestones/` exists, read `docs/milestones/roadmap.md` and find the milestone document that contains this feature. Use its description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any milestone, note that it is unplanned work and proceed.
3. If `docs/milestones/` exists, read `docs/milestones/roadmap.md` and find the phase file (`docs/milestones/phase[N]-milestones.md`) whose milestone contains this feature. Use the feature's description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any phase file, note that it is unplanned work and proceed.
## Step 3: Investigate Existing Patterns
@ -149,9 +149,9 @@ If any of the following situations occur while the implementation loop is runnin
- ✅ `docs/glossary.md` — add/update any new domain terms introduced by the feature
3. **Update the milestone documents (if `docs/milestones/` exists)**:
- In the feature's milestone document, use the edit tool to check the feature off (`[ ]` → `[x]`).
- If this was the last unchecked feature of the milestone, set the milestone's status to `Completed` (in both the milestone document and `docs/milestones/roadmap.md`), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone.
- If the feature was not part of any milestone, add it to the current milestone's document as a completed (`[x]`) feature so the plan reflects reality.
- In the feature's phase file, use the edit tool to check the feature off (`[ ]` → `[x]`).
- If this was the last unchecked feature of the milestone, set the milestone's status to `Completed` (in both the phase file and `docs/milestones/roadmap.md`), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone. If it was also the phase's last milestone, mark the phase `Completed` and point the roadmap at the next phase file.
- If the feature was not part of any milestone, add it to the current milestone's section in the current phase file as a completed (`[x]`) feature so the plan reflects reality.
4. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
@ -163,6 +163,6 @@ This workflow completes automatically once all of the following conditions are m
- Step 5: All tasks in `tasklist.md` are complete (`[x]` or skipped for a valid reason).
- Step 6: The `implementation-validator` subagent's validation passes.
- Step 7: The `test`, `lint`, and `typecheck` commands all succeed without errors.
- Step 8: Handover notes are recorded in `tasklist.md`, all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each), and the feature is checked off in its milestone document (if `docs/milestones/` exists).
- Step 8: Handover notes are recorded in `tasklist.md`, all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each), and the feature is checked off in its phase file (if `docs/milestones/` exists).
Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.

59
.opencode/command/execute-milestones.md
View File

@ -1,23 +1,26 @@
---
description: Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously
description: Execute one phase file (phaseN-milestones.md) - implement its milestones one by one with separate steering documents per milestone
agent: build
---
# Execute Milestones (Fully Autonomous Milestone Execution Mode)
# Execute Milestones (Fully Autonomous Phase Execution Mode)
This command works through the milestone plan in `docs/milestones/` **one milestone at a time**. For each milestone it generates a **separate set of steering documents** under `.steering/`, divides the milestone's features into concrete tasks, implements them all, validates, tests, and reconciles the documents — then immediately moves on to the next milestone.
This command executes **one phase file** from `docs/milestones/` — implementing its milestones **one at a time, in order**. For each milestone it generates a **separate set of steering documents** under `.steering/`, divides the milestone's features into concrete tasks, implements them all, validates, tests, and reconciles the documents — then immediately moves on to the next milestone in the phase file.
**Important:** This workflow is designed to run fully automatically from start to finish without user intervention. Do not ask the user for confirmation between milestones.
**Target**: `$ARGUMENTS` — optional: a milestone number (e.g. `2`), a range (e.g. `1-3`), or empty to execute **all remaining milestones in order**.
**Phase file (required)**: `$ARGUMENTS` — the phase file to execute. Accepted forms:
- `phase1-milestones.md`
- `docs/milestones/phase1-milestones.md`
- `phase1` or `1` (resolved to `docs/milestones/phase1-milestones.md`)
## How to Run
```
opencode
> /execute-milestones # execute all remaining milestones one by one
> /execute-milestones 1 # execute only milestone 1
> /execute-milestones 2-3 # execute milestones 2 through 3
> /execute-milestones phase1-milestones.md
> /execute-milestones docs/milestones/phase2-milestones.md
> /execute-milestones 1
```
## Position in the Workflow
@ -31,21 +34,26 @@ opencode
↓
/plan-milestones
↓
/execute-milestones ← you are here (alternative: /add-feature per feature)
/execute-milestones phase1-milestones.md ← you are here (one phase file per run)
↓
/execute-milestones phase2-milestones.md (next run)
```
## Pre-Run Check
1. Confirm `docs/milestones/roadmap.md` and at least one `docs/milestones/milestone-*.md` exist. If not, stop and tell the user to run `/plan-milestones` first.
2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user and suggest running `/define-design` first. Do not silently proceed without a design spec.
1. **The phase file argument is required.** If `$ARGUMENTS` is empty, or it does not resolve to an existing `docs/milestones/phase[N]-milestones.md` file, **stop**, list the phase files that exist under `docs/milestones/` with their statuses, and ask the user to specify one. Never pick a phase file yourself.
2. If no phase files exist at all, stop and tell the user to run `/plan-milestones` first.
3. Read `docs/milestones/roadmap.md`. If an **earlier phase** is not yet `Completed`, warn the user (later phases build on earlier ones) and continue only if the user accepts.
4. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user and suggest running `/define-design` first. Do not silently proceed without a design spec.
## Procedure
### Step 0: Build the Execution Queue
1. Read `docs/milestones/roadmap.md` and every milestone document.
2. The execution queue is the milestones selected by `$ARGUMENTS` (all of them when empty), **excluding** milestones whose status is already `Completed`, in ascending milestone number.
3. If the queue is empty, report that all selected milestones are already completed and finish.
1. Read the specified phase file and `docs/milestones/roadmap.md`.
2. The execution queue is every milestone in the phase file whose status is not already `Completed`, in ascending milestone number.
3. If the queue is empty, report that the phase is already completed and finish.
4. Set the phase's status to `In progress` (in the phase file header and in `roadmap.md`).
### Step 1: Load the Skills
@ -72,7 +80,7 @@ Each milestone gets its **own** directory — never reuse or append to another m
Following the milestone-execution skill:
- `requirements.md`: the milestone's goal, scope, and every feature with its description, related PRD requirements, affected screens, and acceptance criteria (copied and expanded from the milestone document).
- `requirements.md`: the milestone's goal, scope, and every feature with its description, related PRD requirements, affected screens, and acceptance criteria (copied and expanded from the phase file).
- `design.md`: the implementation approach across the milestone's features — shared components, data model changes, and order of implementation — consistent with `docs/architecture.md` and `docs/design/`.
- `tasklist.md`: the milestone's features **divided into concrete tasks, grouped by feature** (one `## Feature:` section per feature, each ending with its verification tasks). Every task must be small enough to complete in one implementation-loop iteration.
@ -112,39 +120,42 @@ Apply `/add-feature` Step 8 for the milestone:
1. Follow the **steering** skill in **retrospective mode**; record handover notes in this milestone's `tasklist.md`.
2. Reconcile all six persistent documents in `docs/` with everything implemented in this milestone (updates applied, or a skip reason noted for each).
3. In the milestone document: check off every feature (`[ ]` → `[x]`), set the status to `Completed`, and fill in the "Completion Notes".
4. In `docs/milestones/roadmap.md`: set this milestone's status to `Completed` and move the current-milestone pointer to the next milestone in the queue (or mark the roadmap complete).
3. In the **phase file**: check off every feature of this milestone (`[ ]` → `[x]`), set the milestone's status to `Completed`, and fill in its "Completion Notes".
4. In `docs/milestones/roadmap.md`: set this milestone's status to `Completed` and move the current-milestone pointer to the next milestone in the queue.
#### 2.8 Milestone Gate — then Continue
The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck are green, the six documents are reconciled, and the milestone + roadmap statuses are updated.
The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck are green, the six documents are reconciled, and the milestone status is updated in the phase file and the roadmap.
**Once the gate passes, never stop; immediately start Step 2 for the next milestone in the queue.** If the gate genuinely cannot be passed (external blocker), record the blocker in the milestone's `tasklist.md` and in `roadmap.md`, then stop and report — this is the only permitted early stop.
**Once the gate passes, never stop; immediately start Step 2 for the next milestone in the queue.** If the gate genuinely cannot be passed (external blocker), record the blocker in the milestone's `tasklist.md`, the phase file, and `roadmap.md`, then stop and report — this is the only permitted early stop.
### Step 3: Final Report
### Step 3: Close the Phase and Report
When the queue is empty, report per milestone: steering directory created, features implemented, test results, and document updates.
1. When the queue is empty, set the phase's status to `Completed` in the phase file header and in `roadmap.md`, and move the roadmap's current-phase pointer to the next phase file (or mark the roadmap complete if this was the last phase).
2. Report per milestone: steering directory created, features implemented, test results, and document updates.
## Completion Criteria
- Every milestone in the execution queue has status `Completed` in `docs/milestones/roadmap.md`.
- Every milestone in the specified phase file has status `Completed`.
- The phase's status is `Completed` in both the phase file and `docs/milestones/roadmap.md`.
- Each executed milestone has its own `.steering/[date]-milestone-[NN]-[name]/` directory with all tasks `[x]`.
- Tests, lint, and typecheck pass on the final state.
- The six persistent documents reflect everything implemented.
Completion message:
```
"Milestone execution is complete!
"Phase execution is complete: [phase file]
Executed:
✅ Milestone 01 [name] — .steering/[date]-milestone-01-[name]/ ([n] features, [m] tasks)
✅ Milestone NN [name] — .steering/[date]-milestone-NN-[name]/ ([n] features, [m] tasks)
All statuses updated in docs/milestones/roadmap.md.
All statuses updated in [phase file] and docs/milestones/roadmap.md.
Next steps:
- Review the retrospectives in each milestone's tasklist.md
- Run the app and verify the milestones end-to-end
- Run the app and verify the phase end-to-end
- Continue with the next phase: /execute-milestones [next phase file]
- Re-run /plan-milestones if the remaining roadmap should change
"
```

68
.opencode/command/plan-milestones.md
View File

@ -1,20 +1,20 @@
---
description: Plan development milestones and generate milestone documents with the features for each milestone
description: Plan development milestones grouped into phases and generate one phase file (phaseN-milestones.md) with the milestones and features for each phase
agent: build
---
# Plan Milestones (Milestone Planning Phase)
This command breaks the product down into an ordered set of **milestones** and generates milestone documents under `docs/milestones/`. Each milestone document lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run.
This command breaks the product down into **phases**, each containing one or more **milestones**, and generates one file per phase under `docs/milestones/` (`phase1-milestones.md`, `phase2-milestones.md`, …). Each milestone lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run. Each phase file is the execution unit for `/execute-milestones`.
**Planning preferences (optional)**: `$ARGUMENTS` (e.g. `/plan-milestones 3 milestones, MVP in 2 weeks, auth first`)
**Planning preferences (optional)**: `$ARGUMENTS` (e.g. `/plan-milestones 2 phases, MVP in phase 1, auth first`)
## How to Run
```
opencode
> /plan-milestones
> /plan-milestones 3 milestones, MVP first, payments last
> /plan-milestones 2 phases, MVP first, payments last
```
## Position in the Workflow
@ -28,7 +28,7 @@ opencode
↓
/plan-milestones ← you are here
↓
/add-feature (once per feature, milestone by milestone)
/execute-milestones phase1-milestones.md (one phase file at a time)
```
## Pre-Run Check
@ -60,8 +60,8 @@ Read all of the following:
If `$ARGUMENTS` does not already answer these, ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the PRD priorities and confirm it before proceeding.
- **Number of milestones** (default: 2–4 depending on scope)
- **MVP definition** — what is the smallest product worth releasing?
- **Number of phases** (default: 2–3) and **milestones per phase** (default: 1–3)
- **MVP definition** — what is the smallest product worth releasing? (phase 1 must deliver it)
- **Priorities** — features that must come first or last
- **Constraints** — deadlines, dependencies on external systems, team capacity
@ -69,7 +69,7 @@ Collect the answers in a single round; do not pause again until generation is co
### Step 2: Load the Milestone Planning Skill
Follow the **milestone-planning** skill (loaded automatically) for the planning rules and the milestone document template.
Follow the **milestone-planning** skill (loaded automatically) for the planning rules and the phase file template.
### Step 3: Build the Feature Inventory
@ -81,49 +81,55 @@ Derive the complete list of features from the documents:
Size each feature so it can be implemented with **one `/add-feature` run**. Split anything larger; merge trivial fragments.
### Step 4: Group Features into Milestones
### Step 4: Group Features into Milestones, and Milestones into Phases
- **Milestone 1 is the MVP**: the smallest set of features that forms a coherent, end-to-end usable product.
- Number milestones globally and consecutively across all phases (`01`, `02`, …).
- **Milestone 1 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product.
- Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
- Every feature belongs to **exactly one** milestone. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
- **Phase 1 delivers the MVP**: it contains milestone 1 (plus any milestone needed to make the MVP releasable). Later phases group the remaining milestones by theme and priority — each phase should be a meaningful release on its own.
- Every feature belongs to **exactly one** milestone, and every milestone to **exactly one** phase. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
### Step 5: Create the Roadmap Overview
Create `docs/milestones/roadmap.md` containing:
- A table of all milestones: number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
- A table of all phases and their milestones: phase, file, milestone number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
- The ordering rationale (why this sequence)
- A pointer to the current milestone
- A pointer to the current phase file and current milestone
- The "Later / Icebox" list of consciously deferred items
### Step 6: Create One Document per Milestone
### Step 6: Create One File per Phase
For each milestone, create `docs/milestones/milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`) following the milestone-planning skill's template. Each document lists the milestone's features, and each feature includes:
For each phase, create `docs/milestones/phase[N]-milestones.md` (e.g. `phase1-milestones.md`, `phase2-milestones.md`) following the milestone-planning skill's template. Each phase file contains:
- A checkbox for status tracking (`- [ ]`)
- Description and user value
- Related PRD requirements / user stories
- Affected screens from `ui-blueprint.json` (if a design spec exists)
- Acceptance criteria
- The ready-to-run command: `/add-feature [feature name]`
- The phase header: goal, status, and its ready-to-run command: `/execute-milestones phase[N]-milestones.md`
- One section per milestone in the phase (goal, scope, dependencies, definition of done)
- Under each milestone, its features — and each feature includes:
- A checkbox for status tracking (`- [ ]`)
- Description and user value
- Related PRD requirements / user stories
- Affected screens from `ui-blueprint.json` (if a design spec exists)
- Acceptance criteria
- The ready-to-run command: `/add-feature [feature name]`
### Step 7: Consistency Check
Re-read all generated files and confirm:
- Every P0/P1 requirement in the PRD is covered by a milestone (or explicitly parked in the icebox).
- Every feature appears in exactly one milestone.
- Dependencies are ordered correctly across milestones.
- Milestone 1 is a coherent, usable MVP on its own.
- Each feature name works as a `/add-feature` argument.
- Every feature appears in exactly one milestone, and every milestone in exactly one phase file.
- Milestone numbering is global and consecutive across the phase files.
- Dependencies are ordered correctly across milestones and phases.
- Phase 1 delivers a coherent, usable MVP on its own.
- Each feature name works as a `/add-feature` argument, and each phase file name works as an `/execute-milestones` argument.
Fix any inconsistencies found before finishing.
## Completion Criteria
- `docs/milestones/roadmap.md` exists
- One `milestone-[NN]-[name].md` per milestone exists
- Every feature is assigned to exactly one milestone with acceptance criteria
- One `phase[N]-milestones.md` per phase exists
- Every feature is assigned to exactly one milestone (in exactly one phase file) with acceptance criteria
Completion message:
```
@ -131,13 +137,13 @@ Completion message:
Milestone documents created:
✅ docs/milestones/roadmap.md (overview + status)
✅ docs/milestones/milestone-01-....md (MVP)
✅ docs/milestones/milestone-NN-....md
✅ docs/milestones/phase1-milestones.md (MVP phase: milestones 01–NN)
✅ docs/milestones/phase2-milestones.md (milestones NN–NN)
Next steps:
- Review docs/milestones/ and adjust priorities if needed
- Run /execute-milestones to implement all milestones one by one autonomously (a separate steering directory is created per milestone)
- Run /execute-milestones phase1-milestones.md to implement phase 1 (a separate steering directory is created per milestone)
- Or go feature by feature: run /add-feature [first feature of milestone 1]
- Either way, each feature is marked complete in its milestone document as it finishes
- Either way, each feature is marked complete in its phase file as it finishes
"
```