Ken Yasue
1649a71781
The initial app is no longer generated by a separate command. /plan-milestones now always makes milestone 01 'App Shell Generation' (target platform asked in the single question round): theme from design tokens, one screen per blueprint entry, routes, reusable components — no feature logic — plus Playwright setup and the e2e/app-shell.spec.ts smoke spec. It is executed like any other milestone via /execute-milestones (which follows platform-ui-generation for it) or /add-feature. Milestone 02 becomes the MVP core. All workflow diagrams, skills, docs READMEs, AGENTS.md, and README updated; docs/design README also gains the screen-inventory.md entry. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
151 lines
7.7 KiB
Markdown
151 lines
7.7 KiB
Markdown
---
|
||
description: Plan development milestones grouped into phases and generate one phase file (phaseN-milestones.md) with the milestones and features for each phase
|
||
agent: build
|
||
---
|
||
|
||
# Plan Milestones (Milestone Planning Phase)
|
||
|
||
This command breaks the product down into **phases**, each containing one or more **milestones**, and generates one file per phase under `docs/milestones/` (`phase1-milestones.md`, `phase2-milestones.md`, …). Each milestone lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run. Each phase file is the execution unit for `/execute-milestones`.
|
||
|
||
**Planning preferences (optional)**: `$ARGUMENTS` (e.g. `/plan-milestones 2 phases, MVP in phase 1, auth first`)
|
||
|
||
## How to Run
|
||
|
||
```
|
||
opencode
|
||
> /plan-milestones
|
||
> /plan-milestones 2 phases, MVP first, payments last
|
||
```
|
||
|
||
## Position in the Workflow
|
||
|
||
```
|
||
/setup-project
|
||
↓
|
||
/define-design
|
||
↓
|
||
/plan-milestones ← you are here
|
||
↓
|
||
/execute-milestones phase1-milestones.md (one phase file at a time; milestone 01 generates the app shell)
|
||
```
|
||
|
||
## Pre-Run Check
|
||
|
||
1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run `/setup-project` first:
|
||
- `docs/product-requirements.md`
|
||
- `docs/functional-design.md`
|
||
- `docs/architecture.md`
|
||
2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user that milestones will be planned without a design spec — and that milestone 01 (App Shell Generation) is scaffolded from that spec — and suggest running `/define-design` first. Continue only if the user accepts.
|
||
3. Create the milestones directory if it does not exist:
|
||
```bash
|
||
mkdir -p docs/milestones
|
||
```
|
||
|
||
## Procedure
|
||
|
||
### Step 0: Read the Inputs
|
||
|
||
Read all of the following:
|
||
|
||
- `docs/product-requirements.md` (especially user stories and priorities)
|
||
- `docs/functional-design.md`
|
||
- `docs/architecture.md`
|
||
- `docs/design/ui-blueprint.json` and `docs/design/design-brief.md` (if present)
|
||
- `docs/ideas/*` (if present)
|
||
- The planning preferences provided in `$ARGUMENTS` (if any)
|
||
|
||
### Step 1: Gather Planning Preferences (ask the user once)
|
||
|
||
If `$ARGUMENTS` does not already answer these, ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the PRD priorities and confirm it before proceeding.
|
||
|
||
- **Target platform** — `web`, `flutter`, or `winui3` (propose the default from `docs/architecture.md` and `docs/design/platform-mapping.md`); milestone 01 generates the app shell for this platform
|
||
- **Number of phases** (default: 2–3) and **milestones per phase** (default: 1–3)
|
||
- **MVP definition** — what is the smallest product worth releasing? (phase 1 must deliver it)
|
||
- **Priorities** — features that must come first or last
|
||
- **Constraints** — deadlines, dependencies on external systems, team capacity
|
||
|
||
Collect the answers in a single round; do not pause again until generation is complete.
|
||
|
||
### Step 2: Load the Milestone Planning Skill
|
||
|
||
Follow the **milestone-planning** skill (loaded automatically) for the planning rules and the phase file template.
|
||
|
||
### Step 3: Build the Feature Inventory
|
||
|
||
Derive the complete list of features from the documents:
|
||
|
||
- Every user story / requirement in the PRD (with its priority)
|
||
- Every functional module in the functional design
|
||
- Every screen and user action in `ui-blueprint.json` (if present)
|
||
|
||
Size each feature so it can be implemented with **one `/add-feature` run**. Split anything larger; merge trivial fragments.
|
||
|
||
### Step 4: Group Features into Milestones, and Milestones into Phases
|
||
|
||
- Number milestones globally and consecutively across all phases (`01`, `02`, …).
|
||
- **Milestone 01 is always "App Shell Generation"** (there is no separate generate-app command — the shell is built as the first milestone). Following the **platform-ui-generation** skill, it scaffolds the app for the target platform from `docs/design/`: theme from `design-tokens.json`, routes/screens (one per blueprint screen) and reusable components from `ui-blueprint.json`, **no feature logic**, plus Playwright setup with the `e2e/app-shell.spec.ts` smoke spec. Its features are pre-defined in the milestone-planning skill.
|
||
- **Milestone 02 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product on top of the shell.
|
||
- Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
|
||
- **Phase 1 delivers the MVP**: it contains milestones 01 (app shell) and 02 (plus any milestone needed to make the MVP releasable). Later phases group the remaining milestones by theme and priority — each phase should be a meaningful release on its own.
|
||
- Every feature belongs to **exactly one** milestone, and every milestone to **exactly one** phase. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
|
||
|
||
### Step 5: Create the Roadmap Overview
|
||
|
||
Create `docs/milestones/roadmap.md` containing:
|
||
|
||
- A table of all phases and their milestones: phase, file, milestone number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
|
||
- The ordering rationale (why this sequence)
|
||
- A pointer to the current phase file and current milestone
|
||
- The "Later / Icebox" list of consciously deferred items
|
||
|
||
### Step 6: Create One File per Phase
|
||
|
||
For each phase, create `docs/milestones/phase[N]-milestones.md` (e.g. `phase1-milestones.md`, `phase2-milestones.md`) following the milestone-planning skill's template. Each phase file contains:
|
||
|
||
- The phase header: goal, status, and its ready-to-run command: `/execute-milestones phase[N]-milestones.md`
|
||
- One section per milestone in the phase (goal, scope, dependencies, definition of done)
|
||
- Under each milestone, its features — and each feature includes:
|
||
- A checkbox for status tracking (`- [ ]`)
|
||
- Description and user value
|
||
- Related PRD requirements / user stories
|
||
- Affected screens from `ui-blueprint.json` (if a design spec exists)
|
||
- Acceptance criteria
|
||
- The ready-to-run command: `/add-feature [feature name]`
|
||
|
||
### Step 7: Consistency Check
|
||
|
||
Re-read all generated files and confirm:
|
||
|
||
- Milestone 01 is the App Shell milestone (target platform recorded, features per the milestone-planning skill).
|
||
- Every P0/P1 requirement in the PRD is covered by a milestone (or explicitly parked in the icebox).
|
||
- Every feature appears in exactly one milestone, and every milestone in exactly one phase file.
|
||
- Milestone numbering is global and consecutive across the phase files.
|
||
- Dependencies are ordered correctly across milestones and phases.
|
||
- Phase 1 delivers a coherent, usable MVP on its own.
|
||
- Each feature name works as a `/add-feature` argument, and each phase file name works as an `/execute-milestones` argument.
|
||
|
||
Fix any inconsistencies found before finishing.
|
||
|
||
## Completion Criteria
|
||
|
||
- `docs/milestones/roadmap.md` exists
|
||
- One `phase[N]-milestones.md` per phase exists
|
||
- Every feature is assigned to exactly one milestone (in exactly one phase file) with acceptance criteria
|
||
|
||
Completion message:
|
||
```
|
||
"Milestone planning is complete!
|
||
|
||
Milestone documents created:
|
||
✅ docs/milestones/roadmap.md (overview + status)
|
||
✅ docs/milestones/phase1-milestones.md (MVP phase: milestone 01 = app shell, milestones 02–NN)
|
||
✅ docs/milestones/phase2-milestones.md (milestones NN–NN)
|
||
|
||
Next steps:
|
||
- Review docs/milestones/ and adjust priorities if needed
|
||
- Run /execute-milestones phase1-milestones.md to implement phase 1 (a separate steering directory is created per milestone)
|
||
- Or go feature by feature: run /add-feature [first feature of milestone 01 — the app shell]
|
||
- Either way, each feature is marked complete in its phase file as it finishes
|
||
"
|
||
```
|