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

---
name: milestone-planning
description: 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).