Restructure milestone plan into phase files; /execute-milestones now requires a phase file

- /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>

.claude/commands/plan-milestones.md

@@ -1,19 +1,19 @@
 ---
-description: Plan development milestones and generate milestone documents with the features for each milestone
+description: Plan development milestones grouped into phases and generate one phase file (phaseN-milestones.md) with the milestones and features for each phase
 ---
 
 # Plan Milestones (Milestone Planning Phase)
 
-This command breaks the product down into an ordered set of **milestones** and generates milestone documents under `docs/milestones/`. Each milestone document lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run.
+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 3 milestones, MVP in 2 weeks, auth first`)
+**Planning preferences (optional)**: `$ARGUMENTS` (e.g. `/plan-milestones 2 phases, MVP in phase 1, auth first`)
 
 ## How to Run
 
 ```bash
 claude
 > /plan-milestones
-> /plan-milestones 3 milestones, MVP first, payments last
+> /plan-milestones 2 phases, MVP first, payments last
 ```
 
 ## Position in the Workflow
@@ -27,7 +27,7 @@ claude
   ↓
 /plan-milestones        ← you are here
   ↓
-/add-feature (once per feature, milestone by milestone)
+/execute-milestones phase1-milestones.md   (one phase file at a time)
 ```
 
 ## Pre-Run Check
@@ -59,8 +59,8 @@ Read all of the following:
 
 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.
 
-- **Number of milestones** (default: 2–4 depending on scope)
-- **MVP definition** — what is the smallest product worth releasing?
+- **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
 
@@ -68,7 +68,7 @@ Collect the answers in a single round; do not pause again until generation is co
 
 ### Step 2: Load the Milestone Planning Skill
 
-Load the **milestone-planning skill** (`Skill('milestone-planning')`) for the planning rules and the milestone document template.
+Load the **milestone-planning skill** (`Skill('milestone-planning')`) for the planning rules and the phase file template.
 
 ### Step 3: Build the Feature Inventory
 
@@ -80,49 +80,55 @@ Derive the complete list of features from the documents:
 
 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
+### Step 4: Group Features into Milestones, and Milestones into Phases
 
-- **Milestone 1 is the MVP**: the smallest set of features that forms a coherent, end-to-end usable product.
+- Number milestones globally and consecutively across all phases (`01`, `02`, …).
+- **Milestone 1 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product.
 - Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
-- Every feature belongs to **exactly one** milestone. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
+- **Phase 1 delivers the MVP**: it contains milestone 1 (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 milestones: number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
+- 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 milestone
+- A pointer to the current phase file and current milestone
 - The "Later / Icebox" list of consciously deferred items
 
-### Step 6: Create One Document per Milestone
+### Step 6: Create One File per Phase
 
-For each milestone, create `docs/milestones/milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`) following the milestone-planning skill's template. Each document lists the milestone's features, and each feature includes:
+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:
 
-- 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]`
+- 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:
 
 - 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.
-- Dependencies are ordered correctly across milestones.
-- Milestone 1 is a coherent, usable MVP on its own.
-- Each feature name works as a `/add-feature` argument.
+- 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 `milestone-[NN]-[name].md` per milestone exists
-- Every feature is assigned to exactly one milestone with acceptance criteria
+- 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:
 ```
@@ -130,13 +136,13 @@ Completion message:
 
 Milestone documents created:
 ✅ docs/milestones/roadmap.md            (overview + status)
-✅ docs/milestones/milestone-01-....md   (MVP)
-✅ docs/milestones/milestone-NN-....md
+✅ docs/milestones/phase1-milestones.md  (MVP phase: milestones 01–NN)
+✅ docs/milestones/phase2-milestones.md  (milestones NN–NN)
 
 Next steps:
 - Review docs/milestones/ and adjust priorities if needed
-- Run /execute-milestones to implement all milestones one by one autonomously (a separate steering directory is created per milestone)
+- 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 1]
-- Either way, each feature is marked complete in its milestone document as it finishes
+- Either way, each feature is marked complete in its phase file as it finishes
 "
 ```