milestone

<!-- 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:
2. blob.milestones for existing milestone sections from ROADMAP.md
3. blob.state.current_phase and blob.state.status for current position
4. blob.has_project to check if PROJECT.md exists (read it for milestone history if needed)
5. blob.phase_count for total phase count

1. Get milestone details via AskUserQuestion:
2. "What's the name/goal for this new milestone?"
3. "What are the major features or capabilities it should deliver?"
4. If the user provided a name in $ARGUMENTS, use it and skip the name question

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

1. 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

1. Update ROADMAP.md:

Append new milestone section:

```markdown

## Milestone: {name}

Goal: {goal statement} Phases: {start_num} - {end_num}

### Phase {N}: {name} Goal: {goal} Requirements: {REQ-IDs mapped to this phase} Success Criteria: {verifiable conditions for phase completion} Depends on: {prior phases}

### Phase {N+1}: {name} ... ```

1. Create phase directories:

For each new phase: `` .planning/phases/{NN}-{slug}/ ``

1. Update PROJECT.md (create if needed):

Add milestone to the active milestones list:

```markdown ## Active Milestones

### {name}

• Phases: {start} - {end}
• Created: {date}
• Status: In progress

```

CRITICAL (no hook) -- DO NOT SKIP: Update STATE.md frontmatter AND body with new milestone info.

1. Update STATE.md:
2. Set current phase to the first new phase
3. Update milestone info

CRITICAL (no hook) -- DO NOT SKIP: Generate root MILESTONE.md file.

8b. Generate root MILESTONE.md: Read the current milestone section from ROADMAP.md (the ## Milestone: section just created in Step 5) and STATE.md for current phase and status. Write MILESTONE.md at the project root with:

```markdown # Current Milestone: {name} Version: {version} | Status: In Progress | Created: {date}

Goal: {goal}

## Phases | Phase | Goal | Status | |-------|------|--------| | {N}. {name} | {goal} | Pending | ...

Auto-generated by /pbr:milestone new. Updated by /pbr:autonomous. ```

• Read the phase list from the ROADMAP.md section just written in Step 5
• Status column: "Pending" for all new phases

Milestone branch creation (when git.branching is 'milestone'): When starting a new milestone and git.branching is milestone:

• Create branch: git switch -c pbr/milestone-v{version}
• All phase work happens on this branch
• Branch is merged when /pbr:milestone complete is run

1. Commit if planning.commit_docs: true:

`` docs(planning): start milestone "{name}" (phases {start}-{end}) ``

1. Confirm with branded output — read ${CLAUDE_SKILL_DIR}/templates/new-output.md.tmpl and fill in {name} (milestone name), `{