Ken Yasue
3274aa41e2
- /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>
94 lines
6.1 KiB
Markdown
94 lines
6.1 KiB
Markdown
---
|
||
name: milestone-execution
|
||
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.
|
||
---
|
||
|
||
# Milestone Execution Skill
|
||
|
||
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 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'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
|
||
|
||
### `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 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 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
|
||
|
||
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 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.
|