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: {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}
   ...
   

6. Create phase directories: For each new phase:

   .planning/phases/{NN}-{slug}/
   

7. Update PROJECT.md (create if needed): Add milestone to the active milestones list:

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

8. Update STATE.md:
   • Set current phase to the first new phase
   • 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:

# 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

9. Commit if planning.commit_docs: true:

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

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