/milestone

name: milestone
description: "Manage milestones: new, complete, audit, gaps."
allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
argument-hint: "new|complete|audit|gaps [version]"

<!-- markdownlint-disable MD012 MD046 -->

**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► MILESTONE                                  ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:milestone — Milestone Management

You are running the **milestone** skill. Milestones represent significant project checkpoints — a set of phases that together deliver a cohesive chunk of functionality. This skill handles the full milestone lifecycle: creation, completion, auditing, and gap analysis.

This skill runs **inline** for most subcommands, but spawns agents for `audit`.

References

• `references/questioning.md` — Questioning patterns for milestone review decisions
• `references/ui-brand.md` — Status symbols, banners, milestone celebration format

---

Context Budget

Reference: `skills/shared/context-budget.md` for the universal orchestrator rules. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• **Never** perform integration checks yourself — delegate to the integration-checker subagent
• **Minimize** reading audit and verification outputs — read only frontmatter and status fields
• **Delegate** all cross-phase integration analysis to the integration-checker subagent

---

Multi-Session Sync

Before any phase-modifying operations (archiving phases, updating ROADMAP.md/STATE.md/PROJECT.md), acquire a claim:

acquireClaim(planningDir, sessionId)

If the claim fails (another session owns this project), display: "Another session owns this project. Use `/pbr:progress` to see active claims."

On completion or error (including all exit paths), release the claim:

releaseClaim(planningDir, sessionId)

Core Principle

**Milestones are the rhythm of the project.** They force you to step back, verify everything works together, and create a clean snapshot before moving on. Never skip the audit — integration issues hide at milestone boundaries.

---

Argument Parsing

Parse `$ARGUMENTS` for the subcommand and optional version:

$ARGUMENTS format: {subcommand} [{version/name}]

Examples:
  "new"              → subcommand=new, arg=none
  "new User Auth"    → subcommand=new, arg="User Auth"
  "complete v1.0"    → subcommand=complete, arg="v1.0"
  "complete 1.0"     → subcommand=complete, arg="v1.0" (auto-prefix v)
  "preview v1.0"     → subcommand=preview, arg="v1.0"
  "audit v1.0"       → subcommand=audit, arg="v1.0"
  "audit"            → subcommand=audit, arg=current milestone
  "gaps"             → subcommand=gaps, arg=most recent audit

**If no subcommand recognized:** Show usage:

Usage: /pbr:milestone <subcommand> [version]

Subcommands:
  new [name]       — Start a new milestone cycle
  complete [ver]   — Archive completed milestone
  preview [ver]    — Dry-run of complete (show what would happen)
  audit [ver]      — Verify milestone completion
  gaps             — Create phases to close audit gaps

**CRITICAL — After parsing the subcommand, run init command before any manual state reads:**

node plugins/pbr/scripts/pbr-tools.js init milestone

Store the JSON result as `blob`. This single call replaces multiple file reads across all subcommands:

• `blob.state.current_phase`, `blob.state.status` — current phase and status from STATE.md
• `blob.state.last_milestone_version`, `blob.state.last_milestone_completed` — milestone history
• `blob.has_roadmap` — whether ROADMAP.md exists
• `blob.has_project` — whether PROJECT.md exists
• `blob.milestones` — array of milestone sections parsed from ROADMAP.md (each with `name` and `phases_range`)
• `blob.existing_archives` — array of existing archive directory names
• `blob.phase_count` — total phase count
• `blob.config.mode`, `blob.config.planning`, `blob.config.git` — config settings

If `blob.error` is set, display the error banner and stop (no project found).

---

Subcommand: `new`

Start a new milestone cycle with new phases.

Flow

1. **Read current state from init blob:**

• `blob.milestones` for existing milestone sections from ROADMAP.md
• `blob.state.current_phase` and `blob.state.status` for current position
• `blob.has_project` to check if PROJECT.md exists (read it for milestone history if needed)
• `blob.phase_count` for total phase count

2. **Get milestone details** via AskUserQuestion:

• "What's the name/goal for this new milestone?"
• "What are the major features or capabilities it should deliver?"
• If the user provided a name in `$ARGUMENTS`, use it and skip the name question

3. **Determine phase numbering:**

• Find the highest phase number in the current ROADMAP.md
• New phases start at highest + 1
• Example: if phases 1-5 exist, new milestone starts at phase 6

4. **Mini roadmap session:** Run a condensed version of the `/pbr:new-project` questioning flow:

a. Ask about major components needed (via AskUserQuestion):

• "What are the 2-5 major areas of work for this milestone?"

b. For each area, ask:

• "Any specific requirements or constraints for {area}?"

c. Generate phases from the areas:

• Each major area becomes a phase
• Order by dependency (foundations first)
• Include brief description and success criteria

5. **Update ROADMAP.md:** Append new milestone section:

   ---

   ## Milestone: