Help us improve
Share bugs, ideas, or general feedback.
From pbr
Manages project milestones: create new cycles with phases, complete/archive versions, preview changes, audit integration, analyze gaps. For structured delivery checkpoints.
npx claudepluginhub sienklogic/plan-build-runHow this skill is triggered — by the user, by Claude, or both
Slash command
/pbr:milestoneThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- markdownlint-disable MD012 MD046 -->
Plans milestones step-by-step with review gates: grill-design session, then goal contract todo task specs with user approval at each phase.
Archives completed milestone by copying ROADMAP.md/REQUIREMENTS.md to milestones/, gathering git stats and phase accomplishments, updating PROJECT.md, and git tagging version. Use after /gsd:audit-milestone.
Manages git project releases: creates milestones, generates roadmaps, executes 9-stage pipeline with submodule support, closes releases. Yolo mode enables autonomous runs.
Share bugs, ideas, or general feedback.
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.
Before ANY tool calls, display this banner:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► MILESTONE ║
╚══════════════════════════════════════════════════════════════╝
Then proceed to Step 1.
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.
Reference: skills/shared/context-budget.md for the universal orchestrator rules.
Additionally for this skill:
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.
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
newStart a new milestone cycle with new phases.
Read current state:
Get milestone details via AskUserQuestion:
$ARGUMENTS, use it and skip the name questionDetermine phase numbering:
Mini roadmap session:
Run a condensed version of the /pbr:begin questioning flow:
a. Ask about major components needed (via AskUserQuestion):
b. For each area, ask:
c. Generate phases from the areas:
Update ROADMAP.md: Append new milestone section:
---
## Milestone: {name}
**Goal:** {goal statement}
**Phases:** {start_num} - {end_num}
### Phase {N}: {name}
**Goal:** {goal}
**Requirements:** {list}
**Success criteria:** {criteria}
**Depends on:** {prior phases}
### Phase {N+1}: {name}
...
Create phase directories: For each new phase:
.planning/phases/{NN}-{slug}/
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.
Update STATE.md:
Commit if planning.commit_docs: true:
docs(planning): start milestone "{name}" (phases {start}-{end})
Confirm with branded output — read ${CLAUDE_SKILL_DIR}/templates/new-output.md.tmpl and fill in {name} (milestone name), {count} (phase count), {N} (first phase number).
previewDry-run of milestone completion — shows what would happen without making any changes.
Determine version:
complete: use $ARGUMENTS or ask via AskUserQuestionIdentify milestone phases:
Verification status check:
result frontmatterPreview archive structure:
.planning/milestones/v{version}/
├── ROADMAP.md (snapshot)
├── STATS.md (would be generated)
├── REQUIREMENTS.md (snapshot)
└── phases/
├── {NN}-{slug}/ (moved from .planning/phases/)
│ ├── PLAN-01.md
│ ├── SUMMARY.md
│ └── VERIFICATION.md
└── ...
Show what would change:
Display summary:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► MILESTONE PREVIEW — v{version} ║
╚══════════════════════════════════════════════════════════════╝
Phases to archive: {count}
✓ Verified: {verified_count}
⚠ Unverified: {unverified_count}
⚠ Stale verification: {stale_count}
Archive location: .planning/milestones/v{version}/
Git tag: v{version}
Ready to complete? Run: /pbr:milestone complete v{version}
CRITICAL (no hook): This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
completeArchive a completed milestone and prepare for the next one.
Determine version:
$ARGUMENTS: use it (auto-prefix v if missing)Verify all phases are complete:
Read ROADMAP.md to find milestone phases
For each phase, check for VERIFICATION.md
If any phase lacks VERIFICATION.md:
Present the warning context: Unverified phases:
Use AskUserQuestion (pattern: yes-no from skills/shared/gate-prompts.md):
question: "{count} phases haven't been verified. Continue with milestone completion?"
header: "Unverified"
options:
- label: "Continue anyway" description: "Proceed despite unverified phases (not recommended)"
- label: "Stop and review" description: "Run /pbr:review for unverified phases first"
Timestamp freshness check:
For each phase that has a VERIFICATION.md, compare its checked_at frontmatter timestamp against the most recent SUMMARY.md file modification date in that phase directory (use ls -t or file stats).
If any SUMMARY.md is newer than its VERIFICATION.md checked_at:
Use AskUserQuestion (pattern: stale-continue from skills/shared/gate-prompts.md):
question: "{count} phases were modified after verification. Re-verify or continue?"
header: "Stale"
options:
- label: "Re-verify" description: "Run /pbr:review for affected phases (recommended)"
- label: "Continue anyway" description: "Proceed with potentially outdated verification"
Gather milestone stats:
# Get commit range for this milestone's phases
git log --oneline --since="{milestone start date}" --until="now"
# Count files changed
git diff --stat {first_milestone_commit}..HEAD
Collect:
Extract accomplishments: Read all SUMMARY.md files for milestone phases:
provides fields (what was built)key_decisions fieldspatterns fieldstech_stack unionArchive milestone documents:
CRITICAL (no hook): Pre-flight safety checks BEFORE archiving. Do NOT skip this step.
Before creating or moving anything, verify the destination is safe:
.planning/milestones/{version}/ already exists╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Archive destination `.planning/milestones/{version}/` already contains files.
Completing this milestone would overwrite the existing archive.
**To fix:** Run `/pbr:health` or manually inspect `.planning/milestones/{version}/`.
Use a different version number (e.g., {version}.1) or remove the existing archive first.
Ask the user via AskUserQuestion whether to use a different version or abort.CRITICAL (no hook): Create the archive directory .planning/milestones/{version}/ NOW. Do NOT skip this step.
Create a versioned archive directory and move phase directories into it:
.planning/milestones/{version}/ROADMAP.md — snapshot of ROADMAP.md at completion.planning/milestones/{version}/REQUIREMENTS.md — CRITICAL (no hook): Copy REQUIREMENTS.md to archive NOW. Do NOT skip this step. Snapshot of REQUIREMENTS.md.planning/milestones/{version}/STATS.md — milestone statistics.planning/milestones/{version}/phases/{NN}-{slug}/ — move each milestone phase directory from .planning/phases/ into the archiveCRITICAL (no hook): Move phase directories from .planning/phases/ to archive NOW. Do NOT skip this step.
Move phases: For each phase belonging to this milestone, move (not copy) its directory from .planning/phases/{NN}-{slug}/ to .planning/milestones/{version}/phases/{NN}-{slug}/. This keeps the active phases directory clean for the next milestone.
CRITICAL (no hook): Write STATS.md to .planning/milestones/{version}/STATS.md NOW. Do NOT skip this step.
Stats file content:
Read ${CLAUDE_SKILL_DIR}/templates/stats-file.md.tmpl for the stats file format. Fill in all {variable} placeholders with actual data gathered in Steps 3-4.
Update PROJECT.md:
## Completed Milestones
### {name} ({version})
- **Completed:** {date}
- **Phases:** {start} - {end}
- **Key deliverables:** {summary}
CRITICAL (no hook): Update ROADMAP.md with collapsed milestone section NOW. Do NOT skip this step.
Collapse completed phases in ROADMAP.md: Replace detailed phase entries with collapsed summaries:
## Milestone: {name} ({version}) -- COMPLETED
Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}/ROADMAP.md` for details.
| Phase | Status |
|-------|--------|
| {N}. {name} | Completed |
| {N+1}. {name} | Completed |
CRITICAL (no hook): Update STATE.md to mark milestone as complete NOW. Do NOT skip this step.
7b. Update STATE.md:
.planning/STATE.md to mark the milestone as complete7c. Update HISTORY.md:
.planning/HISTORY.md:
## {date} — Milestone {version} Completed
- Milestone: {name}
- Phases: {start} - {end}
- Duration: {duration} days
- Key deliverables: {summary from Step 4}
7d. Aggregate learnings from milestone phases:
CRITICAL (no hook): Run learnings aggregation NOW. Do NOT skip this step.
node ${CLAUDE_PLUGIN_ROOT}/scripts/milestone-learnings.js .planning/milestones/{version} --project {project-name-from-STATE.md}
node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js learnings check-thresholds
If any thresholds are triggered, display each as a notification:
Note: Learnings threshold met — {key}: {trigger}. Consider implementing the deferred feature.
Git tag:
git tag -a {version} -m "Milestone: {name}"
Commit:
git add .planning/milestones/ .planning/phases/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/HISTORY.md
git commit -m "docs(planning): complete milestone {version}"
9b. Push milestone to remote:
Use AskUserQuestion to ask the user how they want to publish the milestone:
question: "How should this milestone be published to GitHub?"
header: "Publish"
options:
- label: "Push tag + commits" description: "Push the v{version} tag and any unpushed commits to origin"
- label: "Skip for now" description: "Keep everything local — push later manually"
git push origin main --follow-tags to push both commits and the annotated tag in one command. Display success or error.git push origin main --follow-tags"If config.deployment.smoke_test_command is set and non-empty:
Run the command via Bash
If exit code 0: display "Smoke test passed" with command output
If exit code non-zero: display advisory warning:
⚠ Smoke test failed (exit code {N})
Command: {smoke_test_command}
Output: {first 20 lines of output}
This is advisory only — the milestone is already archived. Surface it as a potential issue for the user to investigate.
Confirm with branded output — read ${CLAUDE_SKILL_DIR}/templates/complete-output.md.tmpl and fill in {version}, {count} (phases, plans, commits), {lines}, {duration}.
auditVerify milestone completion with cross-phase integration checks.
Determine target:
Read all VERIFICATION.md files for milestone phases:
gaps_found statusesSpawn integration checker:
Display to the user: ◐ Spawning integration checker...
Spawn Task(subagent_type: "pbr:integration-checker"). Read ${CLAUDE_SKILL_DIR}/templates/integration-checker-prompt.md.tmpl, fill in {version or "current"}, {list of phase directories}, and {phase SUMMARY.md paths}, then use the filled template as the Task() prompt.
Check integration-checker completion:
After the integration-checker completes, check for ## INTEGRATION CHECK COMPLETE in the Task() output. If the marker is absent, warn: ⚠ Integration checker did not return completion marker — results may be incomplete. Proceed with whatever findings were returned but note the incomplete status in the audit report.
Check requirements coverage:
provides fieldsWrite audit report:
Create .planning/{version}-MILESTONE-AUDIT.md using the template:
Read ${CLAUDE_SKILL_DIR}/templates/audit-report.md.tmpl for the audit report format. Fill in all {variable} placeholders with actual data from the audit.
Spot-check: After writing, verify .planning/{version}-MILESTONE-AUDIT.md exists on disk using Glob. If missing, re-attempt the write. If still missing, display an error and include findings inline.
Report to user using branded banners — read ${CLAUDE_SKILL_DIR}/templates/audit-output.md.tmpl. The template contains all 3 variants (PASSED, GAPS FOUND, TECH DEBT). Select the appropriate section based on audit result. Fill in {version}, {count}, {gap 1}, {gap 2} as applicable.
gapsCreate phases to close gaps found during an audit.
Find most recent audit:
*-MILESTONE-AUDIT.md in .planning//pbr:milestone audit first."Read audit report:
Prioritize gaps:
Group by priority:
Present to user:
Gaps from milestone audit:
Must fix ({count}):
- {gap}: {description}
Should fix ({count}):
- {gap}: {description}
Nice to fix ({count}):
- {gap}: {description}
Use AskUserQuestion (pattern: multi-option-priority from `skills/shared/gate-prompts.md`):
question: "Which gaps should we address? ({must_count} must-fix, {should_count} should-fix, {nice_count} nice-to-fix)"
header: "Priority"
options:
- label: "Must-fix only" description: "Address {must_count} critical/high gaps"
- label: "Must + should" description: "Address {must_count + should_count} critical through medium gaps"
- label: "Everything" description: "Address all {total_count} gaps including low priority"
- label: "Let me pick" description: "Choose specific gaps to address"
- If "Must-fix only": filter to must-fix gaps for phase creation
- If "Must + should": filter to must-fix + should-fix gaps
- If "Everything": include all gaps
- If "Let me pick" or "Other": present individual gaps for selection
Group into logical phases:
Update ROADMAP.md: Add gap-closure phases after the current milestone phases:
### Phase {N}: Fix {area} (gap closure)
**Goal:** Address gaps found in milestone audit
**Gaps addressed:**
- {gap 1}
- {gap 2}
**Success criteria:** All addressed gaps pass verification
Create phase directories:
.planning/phases/{NN}-fix-{slug}/
Commit:
docs(planning): add gap-closure phases from milestone audit
Confirm with branded output — read ${CLAUDE_SKILL_DIR}/templates/gaps-output.md.tmpl and fill in {count} (gap-closure phases created), {N} (first gap phase number), {name} (phase name).
All subcommands update STATE.md:
new: Sets current milestone, resets phasecomplete: Clears current milestone, updates historyaudit: Notes audit status and dategaps: Updates phase count and roadmap infoReference: skills/shared/commit-planning-docs.md for the standard commit pattern.
All subcommands commit if planning.commit_docs: true:
new: docs(planning): start milestone "{name}" (phases {start}-{end})complete: docs(planning): complete milestone {version}audit: docs(planning): audit milestone {version} - {status}gaps: docs(planning): add gap-closure phases from milestone auditTags (complete only):
git tag -a {version} -m "Milestone: {name}"For all edge case handling, see ${CLAUDE_SKILL_DIR}/templates/edge-cases.md.
Key scenarios: no ROADMAP.md, no phases, no gaps found, version collision, partially verified, large milestone (8+ phases).