ken/claudecode-boilerplate
1
0
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, CLAUDE.md, README, docs/milestones/README.md, and settings.json updated

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Ken Yasue
2026-07-02 11:31:54 +02:00
parent 92d34e2814
commit 33e0c2a60c
7 changed files with 271 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

149
.claude/commands/execute-milestones.md Normal file
View File

@ -0,0 +1,149 @@
---
description: Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously
---
# Execute Milestones (Fully Autonomous Milestone 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.
**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**.
## 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
```
## Position in the Workflow
```
/setup-project
↓
/define-design
↓
/generate-app web | flutter | winui3
↓
/plan-milestones
↓
/execute-milestones ← you are here (alternative: /add-feature per feature)
```
## 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.
## 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.
### Step 1: Load the Skills
1. Load the **milestone-execution skill** (`Skill('milestone-execution')`) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
2. The **steering skill** and **development-guidelines skill** apply during implementation, exactly as in `/add-feature`.
### Step 2: Milestone Loop
**This step repeats for each milestone in the queue, strictly in order. Never start a milestone before the previous one has passed its gate (Step 2.8).**
For the current milestone `[NN] [name]`:
#### 2.1 Create the Milestone Steering Directory
Create `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` with the three files:
- `requirements.md`
- `design.md`
- `tasklist.md`
Each milestone gets its **own** directory — never reuse or append to another milestone's steering documents.
#### 2.2 Generate the Steering Documents
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).
- `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.
#### 2.3 Check the Design Specification
Apply `/add-feature` Step 3.5 for the milestone as a whole: read all four design files before implementation; if any feature in this milestone changes the UI, update the design files first (blueprint → tokens → brief → mapping → SVGs).
#### 2.4 Implementation Loop
Work through `tasklist.md` top to bottom using the same rules as `/add-feature` Step 5:
- Use `Skill('steering')` in **implementation mode**; follow the coding standards in `Skill('development-guidelines')`.
- Mark each task `[ ]` → `[x]` with the `Edit` tool as it completes.
- Exception rules A (split oversized tasks) and B (strike obsolete tasks with a reason) apply.
- **Forbidden**: skipping tasks, ending the loop with unchecked tasks, or asking the user to decide.
#### 2.5 Validate the Milestone
Use the `Task` tool to launch the `implementation-validator` subagent:
- `subagent_type`: "implementation-validator"
- `description`: "Milestone implementation validation"
- `prompt`: "Please validate the quality of all changes implemented for milestone `[NN] [name]`. The target files are `[list of implemented file paths]`. Focus on coding standards, error handling, testability, consistency with existing patterns, and whether every feature's acceptance criteria in `.steering/[dir]/requirements.md` are met."
#### 2.6 Run Automated Tests
```bash
Bash('npm test')
Bash('npm run lint')
Bash('npm run typecheck')
```
If any command fails, analyze, fix, and re-run until all pass.
#### 2.7 Retrospective and Document Reconciliation
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).
#### 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.
**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.
### Step 3: Final Report
When the queue is empty, 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`.
- 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!
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.
Next steps:
- Review the retrospectives in each milestone's tasklist.md
- Run the app and verify the milestones end-to-end
- Re-run /plan-milestones if the remaining roadmap should change
"
```

5
.claude/commands/plan-milestones.md
View File

@ -135,7 +135,8 @@ Milestone documents created:
Next steps:
- Review docs/milestones/ and adjust priorities if needed
- Start milestone 1: run /add-feature [first feature of milestone 1]
- /add-feature marks each feature complete in its milestone document as it finishes
- Run /execute-milestones to implement all milestones one by one autonomously (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
"
```

1
.claude/settings.json
View File

@ -11,6 +11,7 @@
"Skill(design-tokens)",
"Skill(platform-ui-generation)",
"Skill(milestone-planning)",
"Skill(milestone-execution)",
"Skill(steering)"
],
"deny": [],

92
.claude/skills/milestone-execution/SKILL.md Normal file
View File

@ -0,0 +1,92 @@
---
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.
allowed-tools: Read, Write, Edit, Bash
---
# 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.

12
CLAUDE.md
View File

@ -102,8 +102,8 @@ Define "what to do this time" for a specific development task:
### Claude Code Configuration (`.claude/`)
- `.claude/agents/` - Subagent definitions (doc-reviewer, implementation-validator)
- `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, add-feature, review-docs)
- `.claude/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, milestone-planning, steering)
- `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
- `.claude/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, milestone-planning, milestone-execution, steering)
## Development Process
@ -115,7 +115,9 @@ Define "what to do this time" for a specific development task:
4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code
5. Generate the initial app with `/generate-app web | flutter | winui3`
6. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with the features for each milestone)
7. Implement features with `/add-feature [feature]`, milestone by milestone
7. Implement, either way:
- `/execute-milestones` — execute all milestones one by one autonomously (one steering directory per milestone), or
- `/add-feature [feature]` — one feature at a time, milestone by milestone
### Day-to-Day Usage
@ -135,9 +137,11 @@ Define "what to do this time" for a specific development task:
> /generate-app web
> /update-design add a profile screen
# Milestone planning
# Milestone planning and execution
> /plan-milestones
> /plan-milestones 3 milestones, MVP first
> /execute-milestones
> /execute-milestones 1
# Detailed review (when a detailed report is needed)
> /review-docs docs/product-requirements.md

21
README.md
View File

@ -48,8 +48,19 @@ a `roadmap.md` overview plus one document per milestone listing **the features i
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.
### Step 7 — Implement features: `/add-feature <feature>`
A fully autonomous loop, one feature at a time, milestone by milestone. Each run:
### 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 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
@ -59,7 +70,7 @@ A fully autonomous loop, one feature at a time, milestone by milestone. Each run
6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its milestone document
### Step 8 — Repeat and maintain
- More features → `/add-feature <feature>`, working through the milestones in order
- Remaining milestones → `/execute-milestones`, 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>`
@ -99,7 +110,8 @@ claude
> /update-design [refinement] # repeat until the design is approved
> /generate-app web # or flutter | winui3
> /plan-milestones
> /add-feature [feature name] # milestone by milestone
> /execute-milestones # all milestones one by one, or:
> /add-feature [feature name] # one feature at a time
```
See [Development Workflow (Step by Step)](#development-workflow-step-by-step) above for what each step does.
@ -113,5 +125,6 @@ See [Development Workflow (Step by Step)](#development-workflow-step-by-step) ab
| `/update-design` | Refine the design before generation, or update it when a feature changes the UI | `/update-design add a profile screen` |
| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
| `/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` |
| `/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` |

1
docs/milestones/README.md
View File

@ -32,6 +32,7 @@ One document per milestone. Contains the milestone's goal, scope, dependencies,
/define-design → UI/UX design spec
/generate-app → initial app shell
/plan-milestones → creates the files above
/execute-milestones → implements all milestones one by one (one steering directory per milestone), updating statuses here
/add-feature → implements one feature, then checks it off here
```