opencode-boilerplate/.opencode/skills/milestone-planning/SKILL.md

name	description
milestone-planning	Guide for planning development milestones grouped into phases and generating one phase file (phaseN-milestones.md) with the milestones and feature breakdown for each phase. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.

Milestone Planning Skill

This skill explains how to break a product into ordered phases and milestones, and produce one phase file per phase under docs/milestones/. The documents are the bridge between the specification (docs/) and implementation: every feature in every milestone is sized to be implemented with one /add-feature run, and every phase file is sized to be executed with one /execute-milestones run.

Hierarchy

Roadmap (roadmap.md)
└── Phase (phase[N]-milestones.md — the /execute-milestones unit)
    └── Milestone (numbered globally: 01, 02, …)
        └── Feature (the /add-feature unit)

Core Principles

1. MVP first: Phase 1 delivers the MVP; milestone 1 is its core — 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. One phase file = one /execute-milestones run: A phase groups 1–3 milestones that together form a meaningful release.
5. Dependency order: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies.
6. Exactly-once assignment: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
7. Living documents: Phase files track status. /add-feature and /execute-milestones check off features ([ ] → [x]) as they complete, and milestone/phase statuses are updated in both the phase file and roadmap.md.

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: phase/milestone table, ordering rationale, icebox
├── phase1-milestones.md     # Phase 1 (MVP): its milestones and their features
├── phase2-milestones.md
└── phaseN-milestones.md

File naming: phase[N]-milestones.md with N starting at 1 (e.g. phase1-milestones.md). Milestones are numbered globally and consecutively across all phase files (01, 02, …) — numbering never restarts per phase.

Use the structure in template.md for each phase file and for the roadmap.

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 and Phases

1. Tag every feature with its PRD priority and its dependencies.
2. Milestone 1 (MVP core): 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 step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone.
4. Phase 1 contains milestone 1 plus any milestone required to make the MVP releasable. Following phases group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each.
5. A phase should be independently valuable: after /execute-milestones phase[N]-milestones.md finishes, the product is in a releasable state.

Status Tracking Rules

• Feature status lives only in the feature checkbox inside its phase file.
• Milestone status (Not started / In progress / Completed) lives in the milestone's section of the phase file and in the roadmap table — keep them in sync.
• Phase status lives in the phase file header and in the roadmap table.
• /add-feature Step 8 updates the feature checkbox; /execute-milestones additionally updates milestone and phase statuses and the roadmap pointers.
• Re-planning (adding/moving/removing features or milestones) must update both the affected phase file(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; every milestone in exactly one phase file.
• Milestone numbering is global and consecutive across phase files.
• No feature or milestone precedes one of its dependencies.
• Phase 1 delivers a usable end-to-end MVP on its own.
• Every feature has acceptance criteria and a ready-to-run /add-feature command line.
• Every phase file header has its ready-to-run /execute-milestones command line.
• roadmap.md table matches the phase files (names, counts, statuses).