claudecode-boilerplate/.claude/skills/milestone-planning/SKILL.md

name	description	allowed-tools
milestone-planning	Guide for planning development milestones and generating milestone documents with a feature breakdown. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.	Read, Write, Edit

Milestone Planning Skill

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

Core Principles

1. MVP first: Milestone 1 is 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. Dependency order: A feature never lands in an earlier milestone than something it depends on.
5. Exactly-once assignment: Every feature belongs to exactly one milestone. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
6. Living documents: Milestone documents track status. /add-feature checks off a feature ([ ] → [x]) when it completes, and the roadmap status is updated when a milestone finishes.

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: milestone table, ordering rationale, icebox
├── milestone-01-[name].md          # MVP
├── milestone-02-[name].md
└── milestone-NN-[name].md

File naming: milestone-[NN]-[kebab-case-name].md (e.g. milestone-01-mvp.md, milestone-02-collaboration.md).

Use the structure in template.md for each milestone document.

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

1. Tag every feature with its PRD priority and its dependencies.
2. Milestone 1 (MVP): 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 release on its own ("after milestone N ships, the user can additionally …").
4. Prefer 2–4 milestones with 3–8 features each. More than ~8 features in one milestone usually means it should be split.

Status Tracking Rules

• Feature status lives only in the feature checkbox of its milestone document.
• Milestone status (Not started / In progress / Completed) lives in both the milestone document header and the roadmap table — keep them in sync.
• /add-feature Step 8 updates the feature checkbox and, when the last feature of a milestone completes, the milestone and roadmap statuses.
• Re-planning (adding/moving/removing features) must update both the milestone document(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.
• No feature precedes one of its dependencies.
• Milestone 1 is a usable end-to-end product on its own.
• Every feature has acceptance criteria and a ready-to-run /add-feature command line.
• roadmap.md table matches the milestone documents (names, counts, statuses).