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

30
.claude/skills/milestone-execution/SKILL.md
View File

@ -1,27 +1,28 @@
---
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.
description: Guide for executing one phase file (phaseN-milestones.md) - implementing its milestones one by one, with a separate steering directory per milestone, features divided into tasks, and 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.
This skill explains how to execute **one phase file** (`docs/milestones/phase[N]-milestones.md`) — implementing its milestones one at a time. Where `/add-feature` implements **one feature** with one steering directory, milestone execution implements **one whole milestone** per steering directory, and a `/execute-milestones` run covers exactly the milestones of the given phase file, strictly in 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.
1. **One phase file per run**: `/execute-milestones` always operates on an explicitly specified phase file — never on "everything". The next phase requires a new run with the next file.
2. **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.
3. **Strict order, one at a time**: milestones execute in ascending number within the phase file. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
4. **Features divided into tasks**: the milestone's features (from its section in the phase file) are broken down into concrete tasks in `tasklist.md`, grouped by feature. The phase file stays the "what"; the steering tasklist is the "how".
5. **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.
6. **Status flows upward**: task status lives in the steering `tasklist.md`; feature, milestone, and phase status live in the phase file and `roadmap.md`. When a milestone's last task completes, check off its features, mark the milestone `Completed`, and advance the roadmap pointer; when the phase's last milestone completes, mark the phase `Completed` and point the roadmap at the next phase file.
## 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)
- Milestone goal (from the milestone's section in the phase file)
- In/out of scope
- One section per feature: description, related PRD requirements, affected screens, acceptance criteria
- The milestone's Definition of Done
@ -73,13 +74,14 @@ A milestone passes its gate only when **all** of the following hold. Only then m
- [ ] 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.
- [ ] In the phase file: every feature of the milestone is checked off, and the milestone status is `Completed` with Completion Notes.
- [ ] `roadmap.md` points to the next milestone (or, after the phase's last milestone, the phase is `Completed` and the roadmap points to the next phase file).
## 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.
- **A feature turns out to be unimplementable as specified**: update the phase file 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`, in the phase file, 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
@ -87,6 +89,6 @@ 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.
- [ ] Feature checkboxes in the phase file match the completed work.
- [ ] Milestone and phase statuses in the phase file match `roadmap.md`, and the roadmap pointers are correct.
- [ ] No task or feature from a later milestone or a later phase file was implemented early.

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

@ -1,21 +1,31 @@
---
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/.
allowed-tools: Read, Write, Edit
---
# 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
@ -31,15 +41,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
@ -54,27 +64,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
.claude/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