Ken Yasue
00cb087f77
- 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, AGENTS.md, README, and docs/milestones/README.md updated Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
92 lines
5.4 KiB
Markdown
92 lines
5.4 KiB
Markdown
---
|
||
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.
|
||
---
|
||
|
||
# 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.
|