opencode-boilerplate/.opencode/command/plan-milestones.md

description	agent
Plan development milestones grouped into phases and generate one phase file (phaseN-milestones.md) with the milestones and features for each phase	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:

   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
"