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. App shell first: Milestone 01 is always App Shell Generation — there is no separate generate-app command; the initial app is built as the first milestone (see "Milestone 01" below).
2. MVP first: Phase 1 delivers the MVP; milestone 02 is its core — the smallest coherent, end-to-end usable product on top of the shell. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use.
3. Vertical slices: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone".
4. 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.
5. One phase file = one /execute-milestones run: A phase groups 1–3 milestones that together form a meaningful release.
6. 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.
7. 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.
8. 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.

Milestone 01: App Shell Generation (always the first milestone)

The initial app is not created by a separate command — it is milestone 01, the first milestone of phase 1, executed like any other milestone (via /execute-milestones phase1-milestones.md or feature by feature with /add-feature). Implementation follows the platform-ui-generation skill for the design→code mapping.

Record the target platform (web | flutter | winui3) in the milestone's Scope. Its features are:

• Generate the app shell and theme from the design tokens — entry point, layout shell, and the platform's styling system converted from design-tokens.json
• Generate routes, screens, and reusable components from the UI blueprint — one screen per ui-blueprint.json entry, navigation wired, shared components extracted, no feature logic
• Set up Playwright and the app-shell smoke spec — playwright.config.ts, test:e2e script, and e2e/app-shell.spec.ts verifying the shell renders and every blueprint route navigates (see the e2e-testing skill; platform equivalents for flutter/winui3)

Definition of done (in addition to the standard one): the app runs, every blueprint screen is reachable, tokens are the only styling source (no hard-coded values), and no feature logic exists beyond what the documents describe.

Dependency: milestone 01 requires the design spec (docs/design/). Every later milestone depends on milestone 01.

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 01 (App Shell): always first — see "Milestone 01" above.
3. Milestone 02 (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).
4. 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.
5. Phase 1 contains milestones 01 and 02 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.
6. 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:

• Milestone 01 is the App Shell milestone, with its target platform recorded and the three shell features listed.
• 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).