milestone-workflow

name	milestone-workflow
description	Use when planning, building, or reviewing a software milestone/release/version — any task framed as "ship vX", "build the next milestone", "plan and execute a feature set", "do a research + build pass", or "review what we shipped".

Milestone Workflow

A disciplined way to take a milestone from idea to shipped, distilled from real high-quality milestone cycles. Three phases, each with a dedicated command:

1. Research & design (/milestone-research) — figure out what's worth building before writing code; produce an approved design doc.
2. Build (/milestone-build) — execute the design in atomic, verified steps.
3. Adversarial review (/milestone-review) — a cross-perspective pass that catches what self-review can't, before declaring done.

Run them in order across a milestone. You don't have to use the commands — when you recognize a phase, apply its discipline directly.

First: load the repo's specifics

This workflow is generic. Before acting, read the repo's CLAUDE.md (and .planning/STATE.md / ROADMAP.md if present) to learn the project-specific:

• package manager + verify commands (build, test, lint, any drift/consistency guard)
• deploy model (does a push deploy? is there a paths-ignore for docs?)
• conventions (commit style, import rules, where planning docs live)
• the project's "moat" / core-value rule (the thing it must never compromise)

Never hardcode another project's commands. If CLAUDE.md doesn't state a verify command, ask or infer from package.json scripts — don't guess silently.

Cross-cutting discipline (all phases)

These are the through-lines that made the reference cycles work:

• Atomic commits, one logical change each, conventional-commit messages.
• Verify after each step, smallest meaningful check first: lint changed files → build/type-check → tests → any repo consistency guard. Add a test for every behavior change.
• Never push after a failed test run until a clean rerun is confirmed FIRST.
• Keep counts/docs in sync in the same commit as the change that moves them (route/model/job counts, CLAUDE.md, any drift-guard fixture).
• Honesty is the moat. Never overclaim. If something can't be proven, say why instead of faking it. No ghost "coming soon" CTAs, no placeholder that reads as real, no claimed-but-absent features.
• Respect P0/P1/P2. Stay in scope; when something is blocked on an API/tool that doesn't exist yet, note it for a later tier rather than designing around a fiction.
• Treat outward-facing changes as deploy-sensitive — confirm before shipping a new public endpoint or anything that triggers a production deploy.

Phase detail

The full, paste-ready instructions for each phase live in references/:

• references/phase-research.md
• references/phase-build.md
• references/phase-review.md

The /milestone-* commands are thin entry points to these same files, so the skill and commands never duplicate the prompt text.

Provenance

This skill is the generalized form of the patterns observed across real milestone cycles (research-rounds + cross-AI consult → P0 design → phased build with verify-after-each-wave → numbered adversarial-fix batches). It is the HOW; each repo's CLAUDE.md + design doc is the WHAT.