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, AGENTS.md, README, and docs/milestones/README.md updated to phase-file references

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.opencode/skills/milestone-execution/SKILL.md

@@ -1,26 +1,27 @@
 ---
 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.
+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 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.
+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 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.
+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 document)
+- 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
@@ -72,13 +73,14 @@ A milestone passes its gate only when **all** of the following hold. Only then m
 - [ ] 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.
+- [ ] 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 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.
+- **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
 
@@ -86,6 +88,6 @@ 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.
+- [ ] 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.