npx claudepluginhub sienklogic/plan-build-run --plugin pbrThis skill is limited to using the following tools:
templates/audit-output.md.tmpltemplates/audit-report.md.tmpltemplates/complete-output.md.tmpltemplates/edge-cases.mdtemplates/gaps-output.md.tmpltemplates/integration-checker-prompt.md.tmpltemplates/new-output.md.tmpltemplates/stats-file.md.tmplSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Enables AI agents to execute x402 payments with per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents pay for APIs, services, or other agents.
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).