@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/plugins/cursor-pbr/skills/review/templates/debugger-prompt.md.tmpl

@@ -1,61 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/review/templates/debugger-prompt.md.tmpl -->
-<!-- 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/plugins/cursor-pbr/skills/review/templates/gap-planner-prompt.md.tmpl

@@ -1,41 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/review/templates/gap-planner-prompt.md.tmpl -->
-<!-- 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/plugins/cursor-pbr/skills/review/templates/verifier-prompt.md.tmpl

@@ -1,116 +0,0 @@
-<\!-- canonical: ../../../../pbr/skills/review/templates/verifier-prompt.md.tmpl -->
-<!-- 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/plugins/cursor-pbr/skills/scan/SKILL.md

@@ -1,300 +0,0 @@
----
-name: scan
-description: "Analyze an existing codebase. Maps structure, architecture, conventions, and concerns."
----
-
-## Step 0 — Immediate Output
-
-**Before ANY tool calls**, display this banner:
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-Then proceed to Step 1.
-
-# /pbr:scan — 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.
-
-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. **Write `.planning/codebase/RECON.md`** with project type, scale, key directories, entry points, and quick stats
-
-Refer to the "Reconnaissance Detection Reference" section of `skills/scan/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.
-
-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 `skills/scan/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/`
-
-| 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 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:scan` 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-formatting.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:begin`
-
-<sub>`/clear` first → fresh context window</sub>
-
-
-**Also available:**
-- `/pbr:milestone new` — create a milestone to address concerns
-- `/pbr:status` — 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
-
----
-
-## 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:begin
-- 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
-
-Reference: `skills/shared/universal-anti-patterns.md` for rules that apply to ALL skills.
-
-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