Add milestone planning phase between /generate-app and /add-feature
- New command /plan-milestones: generates docs/milestones/ (roadmap.md + one document per milestone with its features, acceptance criteria, and ready-to-run /add-feature commands) - New skill milestone-planning: MVP-first vertical-slice planning rules + milestone/roadmap templates - /add-feature: reads the feature's milestone document before planning and checks the feature off (updating milestone/roadmap status) in Step 8 - Workflow diagrams, CLAUDE.md, README, and settings.json updated for the new phase Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
80
.claude/skills/milestone-planning/SKILL.md
Normal file
80
.claude/skills/milestone-planning/SKILL.md
Normal file
@ -0,0 +1,80 @@
|
||||
---
|
||||
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/.
|
||||
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**.
|
||||
|
||||
## 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.
|
||||
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.
|
||||
|
||||
## Inputs
|
||||
|
||||
Before planning, read:
|
||||
|
||||
- `docs/product-requirements.md` — user stories, priorities (P0/P1/P2), success metrics
|
||||
- `docs/functional-design.md` — functional modules and data flows
|
||||
- `docs/architecture.md` — technical constraints and dependencies
|
||||
- `docs/design/ui-blueprint.json` (if present) — screens and user actions
|
||||
- `docs/ideas/*` (if present)
|
||||
|
||||
## Outputs
|
||||
|
||||
```
|
||||
docs/milestones/
|
||||
├── roadmap.md # Overview: milestone table, ordering rationale, icebox
|
||||
├── milestone-01-[name].md # MVP
|
||||
├── milestone-02-[name].md
|
||||
└── milestone-NN-[name].md
|
||||
```
|
||||
|
||||
File naming: `milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`, `milestone-02-collaboration.md`).
|
||||
|
||||
Use the structure in `template.md` for each milestone document.
|
||||
|
||||
## How to Slice Features
|
||||
|
||||
A well-sized feature:
|
||||
|
||||
- Delivers observable user value (or unblocks one that does)
|
||||
- Touches one primary screen/flow (may touch shared components)
|
||||
- Has 3–7 acceptance criteria
|
||||
- Can be described in one sentence starting with a verb ("Edit user profile", "Filter tasks by tag")
|
||||
- Works verbatim as a command argument: `/add-feature Edit user profile`
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## 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 has acceptance criteria and a ready-to-run `/add-feature` command line.
|
||||
- [ ] `roadmap.md` table matches the milestone documents (names, counts, statuses).
|
||||
88
.claude/skills/milestone-planning/template.md
Normal file
88
.claude/skills/milestone-planning/template.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Milestone Document Template
|
||||
|
||||
Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
|
||||
### In Scope
|
||||
- [Theme or capability included in this milestone]
|
||||
|
||||
### Out of Scope
|
||||
- [Explicitly excluded item] → [where it lives instead: milestone NN / icebox]
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [What must exist before this milestone can start: previous milestone, external system, decision]
|
||||
|
||||
## 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]
|
||||
|
||||
- **Description**: [What it does and the user value, 1–3 sentences]
|
||||
- **Related requirements**: [PRD user story / requirement IDs or headings]
|
||||
- **Affected screens**: [screen ids from ui-blueprint.json, or "n/a"]
|
||||
- **Acceptance criteria**:
|
||||
- [Criterion 1]
|
||||
- [Criterion 2]
|
||||
- [Criterion 3]
|
||||
- **Command**: `/add-feature [Feature 1 name]`
|
||||
|
||||
### Feature: [Feature 2 name]
|
||||
|
||||
- **Description**: ...
|
||||
- **Related requirements**: ...
|
||||
- **Affected screens**: ...
|
||||
- **Acceptance criteria**:
|
||||
- ...
|
||||
- **Command**: `/add-feature [Feature 2 name]`
|
||||
|
||||
## 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
|
||||
|
||||
_Filled in when the milestone completes: completion date, deviations from plan, lessons learned._
|
||||
```
|
||||
|
||||
# Roadmap Template
|
||||
|
||||
Use this structure for `docs/milestones/roadmap.md`.
|
||||
|
||||
```markdown
|
||||
# Development Roadmap
|
||||
|
||||
**Current milestone**: [NN — name]
|
||||
|
||||
## Milestones
|
||||
|
||||
| # | Name | Goal | Features | Status |
|
||||
|---|------|------|----------|--------|
|
||||
| 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
|
||||
| 02 | [name] | [one-line goal] | [count] | Not started |
|
||||
|
||||
## Ordering Rationale
|
||||
|
||||
[Why this sequence: MVP definition, dependency chains, priority decisions made with the user]
|
||||
|
||||
## Later / Icebox
|
||||
|
||||
Consciously deferred — revisit when re-planning:
|
||||
|
||||
- [Deferred item] — [why deferred]
|
||||
```
|
||||
Reference in New Issue
Block a user