@sienklogic/plan-build-run 2.11.0 → 2.12.1

package/plan-build-run/skills/review/templates/debugger-prompt.md.tmpl

@@ -0,0 +1,60 @@
+<!-- Source: review/SKILL.md | Purpose: Prompt template for spawning debugger agent during auto-fix diagnosis -->
+<!-- Depends on: templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Optionally include <project_context> if locked decisions are relevant to debugging -->
+<!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
+
+You are a debugging agent. Analyze these verification failures and determine root causes.
+
+<verification_report>
+Read the verification report for gap details:
+File: {absolute path to VERIFICATION.md}
+
+Focus on the "Gaps Found" section — each gap has the must-have that failed, the layer, and evidence.
+</verification_report>
+
+<build_summaries>
+Build summaries available (read via Read tool for deviation and issue details):
+
+| Plan | Summary File |
+|------|-------------|
+{For each SUMMARY.md in the phase:}
+| {plan_id} | {absolute path to SUMMARY.md} |
+</build_summaries>
+
+<plans>
+Original plans available (read via Read tool to check what was supposed to be built):
+
+| Plan | Plan File |
+|------|-----------|
+{For each PLAN.md in the phase:}
+| {plan_id} | {absolute path to PLAN.md} |
+</plans>
+
+<instructions>
+For each gap:
+1. Read the gap details
+2. Check the relevant source files (use Read, Grep tools)
+3. Determine root cause:
+   - Was the code not written?
+   - Was the code written incorrectly?
+   - Was the wiring missed?
+   - Was there a dependency issue?
+4. Classify the fix difficulty:
+   - TRIVIAL: < 5 lines of code change
+   - MODERATE: New function or file needed
+   - SIGNIFICANT: Architecture-level change needed
+
+Return your analysis as text (do not write files). Format:
+
+# Root Cause Analysis
+
+## Gap 1: {description}
+- **Root cause**: {what went wrong}
+- **Evidence**: {file/line references}
+- **Fix difficulty**: {TRIVIAL | MODERATE | SIGNIFICANT}
+- **Suggested approach**: {how to fix it}
+
+## Gap 2: ...
+</instructions>
+
+Use Read, Grep, Glob, and Bash tools to investigate. Return your analysis as text.

package/plan-build-run/skills/review/templates/gap-planner-prompt.md.tmpl

@@ -0,0 +1,40 @@
+<!-- Source: review/SKILL.md | Purpose: Prompt template for spawning planner agent in gap-closure mode -->
+<!-- Depends on: templates/prompt-partials/phase-project-context.md.tmpl -->
+
+You are the planner agent operating in Gap Closure mode.
+
+<verification_report>
+Read the verification report for gap details:
+File: {absolute path to VERIFICATION.md}
+</verification_report>
+
+<root_cause_analysis>
+[Inline the debugger's root cause analysis]
+</root_cause_analysis>
+
+<existing_plans>
+Read existing plans for context on what was already built:
+
+| Plan | File Path |
+|------|-----------|
+{For each PLAN.md in the phase directory:}
+| {plan_id} | {absolute path to PLAN.md} |
+</existing_plans>
+
+<!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Include <project_context> only -- gap planner gets phase context from verification report -->
+
+<gap_closure_instructions>
+Create targeted gap-closure plans to fix each verified gap.
+
+Rules:
+1. Number new plans starting after the last existing plan number
+2. Set gap_closure: true in frontmatter
+3. Keep plans small — one gap per plan if possible
+4. Set wave: 1 for all gap-closure plans (they should be independent)
+5. Include specific fix instructions in <action> — not vague descriptions
+6. Reference the root cause analysis for each fix
+
+Write gap-closure plan files to: .planning/phases/{NN}-{slug}/
+Use the Write tool.
+</gap_closure_instructions>

package/plan-build-run/skills/review/templates/verifier-prompt.md.tmpl

@@ -0,0 +1,115 @@
+<!-- Source: review/SKILL.md | Purpose: Prompt template for spawning verifier agent during phase review -->
+<!-- Depends on: templates/prompt-partials/phase-project-context.md.tmpl -->
+<!-- Include <phase_context> only -- verifier uses <phase_plans> and <build_results> instead of project_context -->
+<!-- Context blocks: Read and fill templates/prompt-partials/phase-project-context.md.tmpl -->
+
+You are a verification agent. Your job is to verify that a phase build matches its plans.
+
+<verification_methodology>
+For each must-have, perform a three-layer check:
+
+Layer 1 — Existence: Does the artifact exist?
+  - Use `ls` to check file existence
+  - Use `grep` to check for exported functions/classes
+  - Use `Bash` to check database tables, routes, etc.
+
+Layer 2 — Substantiveness: Is it more than a stub?
+  - Check file has meaningful content (not just empty exports)
+  - Check functions have implementations (not just signatures)
+  - Check tests have actual test cases
+
+Layer 3 — Wiring: Is it connected to the rest of the system?
+  - Check imports: is the module imported where needed?
+  - Check usage: is the function called where expected?
+  - Check configuration: is the component configured in app initialization?
+</verification_methodology>
+
+<phase_plans>
+These are the plans that were executed. Extract must-haves from each plan's frontmatter.
+
+{For each PLAN.md file in the phase directory:}
+--- Plan: {filename} ---
+{Inline the YAML frontmatter section only — specifically the must_haves block}
+--- End Plan ---
+</phase_plans>
+
+<build_results>
+These are the build results. Read each summary via the Read tool to check what was built.
+
+| Plan | Summary File | Status |
+|------|-------------|--------|
+{For each SUMMARY.md file in the phase directory:}
+| {plan_id} | {absolute path to SUMMARY.md} | {status from frontmatter} |
+
+Read each summary file to compare actual build output against the must-haves above.
+</build_results>
+
+<instructions>
+1. Extract ALL must-haves across all plans:
+   - Collect all truths
+   - Collect all artifacts
+   - Collect all key_links
+
+2. For each must-have, run the three-layer check:
+   - Use Bash tool to execute verification commands
+   - Use Grep to search for patterns in files
+   - Use Glob to find files
+   - Record PASS or FAIL for each layer
+
+3. Write your verification report to:
+   .planning/phases/{NN}-{slug}/VERIFICATION.md
+
+Report format:
+---
+status: "passed" | "gaps_found" | "human_needed"
+phase: "{NN}-{slug}"
+checked_at: "{date}"
+must_haves_total: {count}
+must_haves_passed: {count}
+must_haves_failed: {count}
+must_haves_human: {count}
+---
+
+# Phase {N} Verification: {phase name}
+
+## Summary
+{One paragraph: overall assessment}
+
+## Results
+
+### Must-Have Truths
+
+| # | Truth | Layer 1 | Layer 2 | Layer 3 | Status |
+|---|-------|---------|---------|---------|--------|
+| 1 | {truth text} | PASS | PASS | PASS | PASSED |
+| 2 | {truth text} | PASS | FAIL | -- | GAP |
+
+### Must-Have Artifacts
+
+| # | Artifact | Exists | Substantive | Wired | Status |
+|---|----------|--------|-------------|-------|--------|
+| 1 | {file path} | YES | YES | YES | PASSED |
+| 2 | {file path} | YES | NO | -- | GAP |
+
+### Must-Have Key Links
+
+| # | Key Link | Connected | Status |
+|---|----------|-----------|--------|
+| 1 | {link description} | YES | PASSED |
+| 2 | {link description} | NO | GAP |
+
+## Gaps Found
+{For each gap:}
+
+### Gap {N}: {short description}
+- **Must-have**: {the must-have that failed}
+- **Failed layer**: {1-Existence | 2-Substantiveness | 3-Wiring}
+- **Details**: {what the check found}
+- **Evidence**: {command output or grep results}
+- **Suggested fix**: {what needs to be done}
+
+## Verification Commands Run
+{List of all commands executed with their results — for auditability}
+</instructions>
+
+Use the Write tool to create the verification report. Use Bash, Grep, and Glob for checks.

package/plan-build-run/skills/scan/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: scan
+description: "Analyze an existing codebase. Maps structure, architecture, conventions, and concerns."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+---
+
+**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 ► SCANNING CODEBASE                          ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Then proceed to Step 1.
+
+# /pbr:map-codebase — Codebase Analysis
+
+You are running the **scan** skill. Your job is to analyze an existing codebase and produce a comprehensive map of its structure, architecture, conventions, and concerns. This is the entry point for brownfield projects — codebases that already have code before Plan-Build-Run is introduced.
+
+This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agents for analysis.
+
+---
+
+## 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** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper subagents
+- **Minimize** reading mapper outputs — read only frontmatter or first 20 lines of each output document
+- **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper subagents
+
+---
+
+## Core Principle
+
+**Understand before you change.** Scanning a codebase is about building a mental model of what exists. Every file produced by this skill becomes context that the planner and executor use to make informed decisions. Accuracy matters more than speed.
+
+---
+
+## Flow
+
+### Step 1: Check for Existing Analysis
+
+Check if `.planning/codebase/` directory exists:
+
+**If it exists and has files:**
+
+First, resolve the depth profile so you know which areas are available:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+```
+Read `profile["scan.mapper_areas"]` to determine available areas (quick: tech, arch; standard/comprehensive: tech, arch, quality, concerns).
+
+Then present to user via AskUserQuestion:
+  ```
+  A codebase analysis already exists (from {date based on file modification}).
+
+  Files found:
+  - {list of .md files in the directory}
+
+  Options:
+  1. Refresh the full analysis (overwrites existing)
+  2. Refresh a specific area ({list available areas from depth profile})
+  3. Keep existing analysis
+  ```
+- If user chooses "Keep": display a summary of existing analysis and stop
+- If user chooses "Refresh specific": present the available areas based on the already-resolved depth profile (quick mode only offers tech/arch; standard/comprehensive offers all 4). Only spawn the selected agent. Skip re-resolving depth in Step 3 since it was already resolved here.
+- If user chooses "Refresh all": proceed with full scan
+
+**If it doesn't exist:**
+- Create `.planning/codebase/` directory
+- Also create `.planning/` if it doesn't exist (scan can be run before begin)
+- Proceed with full scan
+
+### Step 2: Initial Reconnaissance
+
+Reference: `skills/shared/context-loader-task.md` (Scan Reconnaissance variation) for the underlying pattern.
+
+Before spawning agents, do a quick scan to identify what we're working with. This gives agents better context.
+
+1. **Detect project type** — check for language-specific config files (package.json, requirements.txt, go.mod, Cargo.toml, etc.)
+2. **Detect project scale** — count source files (exclude node_modules, venv, .git, build, dist). Categories: Small (<50), Medium (50-200), Large (200-1000), Very Large (1000+)
+3. **Detect key directories** — identify src, test, docs, config, scripts, public, migrations directories
+4. **Read existing docs** — README.md, architecture docs, .env.example
+5. **CRITICAL (no hook) -- DO NOT SKIP:** Write `.planning/codebase/RECON.md` with project type, scale, key directories, entry points, and quick stats
+
+Refer to the "Reconnaissance Detection Reference" section of `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` for the full detection checklists.
+
+### Step 3: Spawn Analysis Agents
+
+**Resolve mapper configuration:** Before spawning, resolve the depth profile:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+```
+
+Read `profile["scan.mapper_count"]` and `profile["scan.mapper_areas"]` to determine how many mappers to spawn and which focus areas to cover.
+
+**Default mappings by depth:**
+- `quick` (budget): 2 mappers -- `tech` and `arch` only. Produces STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md. Skips quality and concerns analysis.
+- `standard` (balanced): 4 mappers -- all areas. Full analysis.
+- `comprehensive` (thorough): 4 mappers -- all areas. Full analysis.
+
+**Extended context override:** If `features.extended_context` is `true` in `.planning/config.json`, always spawn 4 mappers (all areas: tech, arch, quality, concerns) regardless of the depth profile's `scan.mapper_count` and `scan.mapper_areas`. The 1M context window allows the orchestrator to absorb all 4 mapper outputs without context pressure. Log: "Extended context: spawning all 4 mappers regardless of depth"
+
+Display to the user:
+```
+◐ Spawning {mapper_count} codebase mapper(s) in parallel...
+  → Technology stack analysis
+  → Architecture patterns
+  → Code quality assessment
+  → Concerns & risks
+```
+
+(Only list the focus areas that will actually be spawned based on the depth profile.)
+
+Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each area in `scan.mapper_areas`. All should be spawned in a single response for maximum parallelism.
+
+For each agent, read `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` and fill in the placeholders:
+- `{focus_area}`: one of `tech`, `arch`, `quality`, `concerns`
+- `{project_path}`: the working directory
+- `{recon_data}`: contents of RECON.md
+- `{scale}`: detected scale from Step 2
+- `{output_path}`: `.planning/codebase/`
+
+**Prepend this block to each mapper prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/codebase/RECON.md — baseline reconnaissance data (if exists)
+</files_to_read>
+```
+
+| Agent | Focus | Output Files | When |
+|-------|-------|-------------|------|
+| 1 | tech | STACK.md, INTEGRATIONS.md | Always |
+| 2 | arch | ARCHITECTURE.md, STRUCTURE.md | Always |
+| 3 | quality | CONVENTIONS.md, TESTING.md | standard + comprehensive |
+| 4 | concerns | CONCERNS.md | standard + comprehensive |
+
+### Step 4: Wait for Agents
+
+All agents run in parallel. As each completes, display:
+```
+✓ Technology stack analysis complete
+✓ Architecture patterns complete
+✓ Code quality assessment complete
+✓ Concerns & risks complete
+```
+
+(Only display lines for the focus areas that were actually spawned.)
+
+### Step 4b: Check Completion Markers
+
+After each codebase-mapper Task() completes, check the Task() output for the `## MAPPING COMPLETE` marker:
+
+- If `## MAPPING COMPLETE` is present: the mapper finished successfully, proceed normally
+- If the marker is missing: warn the user that the mapper may not have completed successfully:
+  ```
+  ⚠ Codebase mapper ({focus_area}) did not report MAPPING COMPLETE.
+  Output may be incomplete — check .planning/codebase/ for partial results.
+  ```
+  Continue to Step 5 verification regardless (the file existence checks will catch truly missing output).
+
+### Step 5: Verify Output
+
+After all agents complete, verify the expected files exist:
+
+**Required files (always):**
+- `.planning/codebase/RECON.md` (created in Step 2)
+- `.planning/codebase/STACK.md` (tech mapper)
+- `.planning/codebase/INTEGRATIONS.md` (tech mapper)
+- `.planning/codebase/ARCHITECTURE.md` (arch mapper)
+- `.planning/codebase/STRUCTURE.md` (arch mapper)
+
+**Required files (standard + comprehensive only):**
+- `.planning/codebase/CONVENTIONS.md` (quality mapper)
+- `.planning/codebase/TESTING.md` (quality mapper)
+- `.planning/codebase/CONCERNS.md` (concerns mapper)
+
+Check only the files that correspond to the mapper areas that were actually spawned.
+
+For any missing files, display:
+```
+╔══════════════════════════════════════════════════════════════╗
+║  ERROR                                                       ║
+╚══════════════════════════════════════════════════════════════╝
+
+Missing analysis output: {filename}
+Agent that failed: {focus_area} mapper
+
+**To fix:** Re-run with `/pbr:map-codebase` and select "Refresh a specific area" → {focus_area}.
+```
+
+### Step 6: Present Summary
+
+Read key findings from each file (frontmatter or first section) and display using the branded stage banner from `references/ui-brand.md`:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► SCAN COMPLETE ✓                            ║
+╚══════════════════════════════════════════════════════════════╝
+
+Project: {type} ({scale})
+Stack: {primary language} + {framework}
+Architecture: {style}
+
+Key Stats:
+- {file count} source files, {test count} test files
+- {dependency count} dependencies
+- {integration count} external integrations
+
+Full analysis: .planning/codebase/
+```
+
+**Concerns section** (only display if ALL of these conditions are true: (1) the concerns mapper was included in `scan.mapper_areas` for the resolved depth profile, (2) the concerns mapper was actually spawned, AND (3) `.planning/codebase/CONCERNS.md` exists and contains at least one concern entry). If any condition is false, skip this entire section silently — do NOT display an empty concerns block or a "no concerns" message:
+
+```
+Concerns: {critical} critical, {high} high, {medium} medium
+
+Top concerns:
+1. {most critical concern}
+2. {second concern}
+3. {third concern}
+```
+
+Then use the "Next Up" routing block:
+```
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Start a project** — use the scan results to plan your work
+
+`/pbr:new-project`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:intel` — build persistent codebase intelligence from scan results
+- `/pbr:new-milestone` — create a milestone to address concerns
+- `/pbr:progress` — see project status
+
+
+```
+
+### Step 7: Git Integration
+
+Reference: `skills/shared/commit-planning-docs.md` for the standard commit pattern.
+
+If `.planning/config.json` exists and `planning.commit_docs: true`:
+
+```bash
+git add .planning/codebase/
+git commit -m "docs(planning): map existing codebase"
+```
+
+If no config exists yet (scan before begin), use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+  question: "Commit the codebase analysis to git?"
+  header: "Commit?"
+  options:
+    - label: "Yes"  description: "Stage and commit .planning/codebase/ files"
+    - label: "No"   description: "Skip commit — files are saved but not committed"
+- If "Yes": run `git add .planning/codebase/ && git commit -m "docs(planning): map existing codebase"`
+- If "No" or "Other": skip commit
+
+---
+
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
+## Edge Cases
+
+### Monorepo with multiple projects
+- Detect by multiple package.json, separate src directories, workspace config
+- Ask user via AskUserQuestion: "This looks like a monorepo. Scan the whole repo or a specific project?"
+- If specific: scope all agents to that subdirectory
+- If whole: note the monorepo structure in ARCHITECTURE.md
+
+### Empty or near-empty codebase
+- If fewer than 5 source files: "This codebase is very small. A scan may not be necessary."
+- Still allow it if user wants
+- Output will be minimal
+
+### No source code (config-only repo, docs repo)
+- Detect: no recognized source file extensions
+- Adapt: focus on documentation quality, config structure
+- Skip code quality analysis
+
+### Codebase has existing analysis
+- Check for architectural docs, ADRs, design docs
+- Reference them in the scan output
+- Don't contradict existing docs without strong evidence
+
+### Binary files, large assets
+- Skip binary files in analysis
+- Note their existence in STRUCTURE.md
+- Flag large committed binaries as a concern
+
+### Scan before /pbr:new-project
+- This is a valid and encouraged workflow
+- Scan results become input for the begin skill
+- Create `.planning/` and `.planning/codebase/` if needed
+- Don't require config.json
+
+---
+
+## Anti-Patterns
+
+Additionally for this skill:
+
+1. **DO NOT** modify any source code — scan is read-only analysis
+2. **DO NOT** run the project (no `npm start`, `python app.py`, etc.) — analyze statically
+3. **DO NOT** install dependencies — analyze package files, don't install
+4. **DO NOT** generate concerns without evidence — every concern needs a file reference
+5. **DO NOT** ignore positive observations — knowing what works well is valuable
+6. **DO NOT** produce generic output — every finding should be specific to THIS codebase
+7. **DO NOT** scan node_modules, venv, .git, or build output directories
+8. **DO NOT** read every file in large codebases — sample and extrapolate
+9. **DO NOT** skip the RECON step — agents need baseline context
+10. **DO NOT** combine agents — the 4 agents must run in parallel with separate focuses