ken/claudecode-boilerplate
1
0
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, CLAUDE.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:25 +02:00
parent 33e0c2a60c
commit 33b33c4bab
9 changed files with 214 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
.claude/commands/execute-milestones.md
View File

@ -1,22 +1,25 @@
---
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
---
# 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
```bash
claude
> /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
@ -30,21 +33,26 @@ claude
↓
/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
@ -71,7 +79,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.
@ -111,39 +119,42 @@ Apply `/add-feature` Step 8 for the milestone:
1. Run `Skill('steering')` 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
"
```