npx claudepluginhub sienklogic/plan-build-run --plugin pbrThis skill is limited to using the following tools:
templates/check-pattern.md.tmpltemplates/output-format.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.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
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 ► HEALTH CHECK ║
╚══════════════════════════════════════════════════════════════╝
Then proceed to Step 1.
You are running the health skill. Your job is to validate the integrity of the .planning/ directory, report problems, and suggest targeted fixes.
This skill runs inline. It is read-only by default, but offers an optional auto-fix flow for common corruption patterns (see the Auto-Fix section below).
Check if the user passed --repair:
--repair: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.Each check follows the common pattern. Read ${CLAUDE_SKILL_DIR}/templates/check-pattern.md.tmpl for the shared execution flow: target files, validate against rules, classify as PASS/FAIL/WARN/INFO, and record the result with a fix suggestion for any failures.
Read ${CLAUDE_SKILL_DIR}/templates/output-format.md.tmpl for the output format: summary table, status indicators, issues list, optional recent decisions, and final result line.
Run all 10 checks in order. Collect results and present them together at the end.
Validate .planning/ exists with required scaffolding: STATE.md, config.json, ROADMAP.md.
.planning/ is missing: FAIL the entire health check immediately. Display:╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
No .planning/ directory found.
**To fix:** Run `/pbr:begin` to initialize.
Stop all further checks.
/pbr:begin to re-initialize, or create the file manually."Advisory checks — WARN if missing, do not FAIL:
.planning/PROJECT.md
If missing: ⚠ PROJECT.md not found. Run /pbr:begin to generate it, or create from plugins/pbr/templates/PROJECT.md.tmpl.
.planning/REQUIREMENTS.md
If missing: ⚠ REQUIREMENTS.md not found. Run /pbr:begin to generate it, or create from plugins/pbr/templates/REQUIREMENTS.md.tmpl.
.planning/CONTEXT.md (project-level)
If missing: ⚠ CONTEXT.md not found. Run /pbr:discuss --project to capture locked decisions.
These files are generated by /pbr:begin. Absence is expected on projects created before v2.15.
Parse .planning/config.json as JSON. Check required fields: version, depth. Check recommended fields: features, models.
Compare directories in .planning/phases/ against phases defined in ROADMAP.md.
Glob all PLAN*.md and SUMMARY*.md in .planning/phases/. Match by plan number. A PLAN without SUMMARY is normal unless the phase is marked complete.
/pbr:build or mark phase incomplete."Extract current phase, plan identifier, and progress percentage from STATE.md. Verify each against the file system.
Glob all PLAN*.md and SUMMARY*.md in .planning/phases/. Each file must start with ---, have a closing ---, contain valid YAML, and include required fields: title, status.
--- at the top of the file."--- delimiters."{field}: {suggested value} to the frontmatter."Compare ROADMAP.md phase statuses against STATE.md current position. Flag if ROADMAP says a phase is "verified" but STATE says it is "building", or if phases after current are marked complete.
Check if .planning/logs/hooks.jsonl exists. Also check the legacy path .planning/.hook-log (the logger migrates this automatically, but it may still exist if hooks haven't fired since the migration was added). Use whichever file exists (prefer hooks.jsonl). If found, scan last 20 entries for decision: "error" or decision: "unlink-failed".
Read .planning/config.json and check for fields referenced by skills:
features.auto_continue (build skill, auto-continue.js hook)
features.team_discussions (config skill)
features.goal_verification (build, review skills)
features.integration_verification (review skill)
git.mode (config skill)
planning.commit_docs (import, discuss, quick skills) — must be a boolean; validate that the value is strictly true or false, not a string or number
PASS: All expected fields present with correct types
WARN (missing fields): Report each missing field and which skill uses it — "Run /pbr:config to set all options."
The executor creates .PROGRESS-{plan_id} files as crash recovery breadcrumbs during builds and deletes them after SUMMARY.md is written. Similarly, .checkpoint-manifest.json files track checkpoint state during execution. If the executor crashes mid-build, these files remain and could confuse future runs.
Glob for .planning/phases/**/.PROGRESS-* and .planning/phases/**/.checkpoint-manifest.json.
Orphaned progress files detected:
- .planning/phases/02-auth/.PROGRESS-02-01 (executor may have crashed)
Fix suggestion: "These are crash recovery breadcrumbs from interrupted builds. Safe to delete if no /pbr:build is currently running. Remove with rm <path>."Orphaned checkpoint manifests detected:
- .planning/phases/02-auth/.checkpoint-manifest.json (stale build checkpoint)
Fix suggestion: "Checkpoint manifests are leftover from interrupted builds. Safe to delete if no /pbr:build is currently running. Remove with rm <path>."Also check for .planning/.active-skill:
rm .planning/.active-skill."After running all 10 checks and collecting results, if any of the following auto-fixable issues were found, offer to fix them.
| Pattern | Detection | Fix Action |
|---|---|---|
| Missing STATE.md frontmatter | Check 5 finds STATE.md without --- block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
| STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in .planning/phases/ |
| Missing config.json | Check 1/2 finds no .planning/config.json | Create with default config template (same as /pbr:setup defaults) |
| Orphaned .active-skill file | Check 10 or general scan finds .planning/.active-skill older than 1 hour | Delete the stale .active-skill file |
| Empty phases directory | Check 3 finds .planning/phases/ missing | Create the directory: mkdir -p .planning/phases |
| STATE.md over 150 lines | Check 5 finds STATE.md exceeds 150 lines | Compact the ## Accumulated Context section, keeping only the last 3 entries |
After displaying health check results, if any auto-fixable issues were detected:
CRITICAL — Before ANY auto-fix that modifies or regenerates STATE.md (frontmatter regeneration, phase_slug correction, or line compaction), you MUST create a timestamped backup first. DO NOT SKIP THIS STEP.
mkdir -p .planning/backups
cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
This ensures the user can recover the original STATE.md if the fix produces incorrect results.
Count the auto-fixable issues.
If --repair flag was passed: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."
Otherwise: Present the choice:
Use AskUserQuestion: question: "Found {N} auto-fixable issues. How should we handle them?" header: "Fix?" options: - label: "Fix all" description: "Apply all {N} fixes automatically" - label: "Review each" description: "Show each fix and confirm individually" - label: "Skip" description: "Do nothing — just report"
If "Fix all" (or --repair): Apply all fixes in order, then display a summary:
Auto-fix results:
- Fixed: {description of fix 1}
- Fixed: {description of fix 2}
...
If "Review each": For each fixable issue, display:
Issue: {description}
Fix: {what will be done}
Then ask via AskUserQuestion (yes/no): "Apply this fix?"
- Fixed: {description}- Skipped: {description}If "Skip": Do nothing, continue to the rest of the output.
After all checks, look for .planning/logs/decisions.jsonl. If it exists, display the last 5 entries as - {date}: {summary} (phase {N}). If it does not exist, skip silently.
After all checks complete, display the branded result:
If all checks passed (0 failures):
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► HEALTH CHECK PASSED ✓ ║
╚══════════════════════════════════════════════════════════════╝
{N} checks passed, {M} warnings
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Continue your workflow** — planning directory is healthy
`/pbr:status`
<sub>`/clear` first → fresh context window</sub>
**Also available:**
- `/pbr:continue` — execute next logical step
- `/pbr:config` — adjust settings
If failures found:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► HEALTH CHECK FAILED ⚠ ║
╚══════════════════════════════════════════════════════════════╝
{N} checks passed, {F} failures, {M} warnings
╔══════════════════════════════════════════════════════════════╗
║ ▶ NEXT UP ║
╚══════════════════════════════════════════════════════════════╝
**Fix the failures** listed above, then re-run
`/pbr:health`