@sienklogic/plan-build-run 2.33.1 → 2.37.0

package/plugins/copilot-pbr/skills/review/SKILL.md

@@ -60,6 +60,8 @@ Execute these steps in order.
 
 ### Step 1: Parse and Validate (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init verify-work {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 1. Parse `$ARGUMENTS` for phase number and `--auto-fix` flag
 2. Read `.planning/config.json`
    **CRITICAL: Write .active-skill NOW.** Write the text "review" to `.planning/.active-skill` using the Write tool.
@@ -154,6 +156,16 @@ Invoke the `@verifier` agent to run three-layer checks.
 
 Read `skills/review/templates/verifier-prompt.md.tmpl` and use its content as the verifier prompt.
 
+**Prepend this block to the verifier prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/PLAN-*.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — executor build summaries
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+```
+
 **Placeholders to fill before sending:**
 - `{For each PLAN.md file in the phase directory:}` — inline each plan's must_haves frontmatter block
 - `{For each SUMMARY.md file in the phase directory:}` — provide manifest table with file paths and status from frontmatter. The verifier reads full content from disk via Read tool.
@@ -180,6 +192,17 @@ Then show a brief table of must-haves with pass/fail status:
 
 Then display the overall verdict (`PASSED`, `GAPS FOUND`, or `HUMAN NEEDED`) before proceeding to the full results presentation.
 
+### Step 3a: Spot-Check Verifier Output
+
+CRITICAL: Verify verifier output before proceeding.
+
+1. **VERIFICATION.md exists**: Check `.planning/phases/{NN}-{slug}/VERIFICATION.md` exists on disk
+2. **Status field present**: Read VERIFICATION.md frontmatter — verify `status` field is present and is one of: pass, fail, partial
+3. **Must-haves checked**: Verify `must_haves_checked` count > 0 in frontmatter
+4. **Completion marker**: Look for `## VERIFICATION COMPLETE` in the Task() output
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
 ---
 
 ### Step 3b: Local LLM Verification Quality Check (optional, advisory)
@@ -367,6 +390,16 @@ Invoke the `@debugger` agent to analyze each failure.
 
 Read `skills/review/templates/debugger-prompt.md.tmpl` and use its content as the debugger prompt.
 
+**Prepend this block to the debugger prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps and failure details
+2. .planning/phases/{NN}-{slug}/SUMMARY-*.md — what was built
+3. .planning/phases/{NN}-{slug}/PLAN-*.md — original plan must-haves
+</files_to_read>
+```
+
 **Placeholders to fill before sending:**
 - `[Inline the VERIFICATION.md content]` — provide file path; debugger reads via Read tool
 - `[Inline all SUMMARY.md files for the phase]` — provide manifest table of file paths
@@ -382,6 +415,16 @@ Invoke the `@planner` agent in gap-closure mode.
 
 Read `skills/review/templates/gap-planner-prompt.md.tmpl` and use its content as the gap planner prompt.
 
+**Prepend this block to the gap planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/VERIFICATION.md — gaps to close
+2. .planning/phases/{NN}-{slug}/PLAN-*.md — existing plans for context
+3. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+</files_to_read>
+```
+
 **Placeholders to fill before sending:**
 - `[Inline VERIFICATION.md]` — provide file path; planner reads via Read tool
 - `[Inline the debugger's root cause analysis]` — keep inline (already in conversation context)
@@ -562,6 +605,8 @@ After review completes, always present a clear next action using the completion
 - **If gaps remain:** Use the "Gaps Found" template. Fill in phase number, name, gap count, and gap summaries.
 - **If final phase:** Use the "Milestone Complete" template. Fill in phase count.
 
+Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block of the completion template.
+
 ---
 
 ## Notes

package/plugins/copilot-pbr/skills/scan/SKILL.md

@@ -123,6 +123,14 @@ For each agent, read `skills/scan/templates/mapper-prompt.md.tmpl` and fill in t
 - `{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 |
@@ -142,6 +150,18 @@ All agents run in parallel. As each completes, display:
 
 (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:

package/plugins/copilot-pbr/templates/SUMMARY-complex.md.tmpl

@@ -0,0 +1,95 @@
+# SUMMARY-complex.md Template
+
+> Use when: decisions were made OR fileCount > 6
+> Referenced by: executor agent (complex plans, architectural work)
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+subsystem: "{main subsystem affected}"
+tags:
+  - "{tag1}"
+requires:
+  - "{plan_id}: {artifact}"
+provides:
+  - "{export/artifact description}"
+affects:
+  - "{affected area 1}"
+tech_stack:
+  - "{technology used}"
+key_files:
+  - "{file1}: {what it does}"
+key_decisions:
+  - "{decision 1}: {rationale}"
+patterns:
+  - "{pattern used}: {where}"
+metrics:
+  duration_minutes: {n}
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+  files_created: {n}
+  files_modified: {n}
+deferred:
+  - "{thing noticed but not implemented}"
+self_check_failures:
+  - "{failure description}"
+architecture_notes:
+  - "{key architectural decision and why}"
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{2-3 paragraph description of what was accomplished}
+
+## Architecture Decisions
+
+| Decision | Options Considered | Chosen | Rationale |
+|----------|-------------------|--------|-----------|
+| {decision} | {opt1}, {opt2} | {chosen} | {why} |
+
+## Task Results
+
+| Task | Status | Commit | Files | Verify |
+|------|--------|--------|-------|--------|
+| {task_id}: {name} | done | {hash} | {count} | passed |
+
+## Key Implementation Details
+
+{Important details about HOW things were implemented}
+
+## Integration Points
+
+{How this plan connects to other plans - imports, exports, shared state}
+
+## Known Issues
+
+{Issues discovered during execution}
+
+## Dependencies Provided
+
+{What other plans can now depend on}
+
+## Deferred Items
+
+{Items noticed but intentionally deferred - with rationale}
+```
+
+## Selection Heuristic
+
+Use this template when ANY of the following are true:
+- Key architectural decisions were made during execution
+- Total files created or modified > 6
+- Deviations from the plan occurred
+- Multiple integration points were established
+- The plan touched shared infrastructure or patterns

package/plugins/copilot-pbr/templates/SUMMARY-minimal.md.tmpl

@@ -0,0 +1,48 @@
+# SUMMARY-minimal.md Template
+
+> Use when: taskCount <= 2 AND fileCount <= 3
+> Referenced by: executor agent (quick tasks, simple plans)
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+requires: []
+provides:
+  - "{export/artifact description}"
+key_files:
+  - "{file1}: {what it does}"
+deferred: []
+metrics:
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{1 paragraph description}
+
+## Task Results
+
+| Task | Status | Commit | Files |
+|------|--------|--------|-------|
+| {task_id}: {name} | done | {hash} | {count} |
+```
+
+## Selection Heuristic
+
+Use this template when ALL of the following are true:
+- Total tasks in the plan <= 2
+- Total files created or modified <= 3
+- No key decisions were made
+- No deviations from the plan occurred

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.33.1",
+  "version": "2.37.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

package/plugins/cursor-pbr/agents/audit.md

@@ -2,9 +2,17 @@
 name: audit
 description: "Analyzes Claude Code session logs for PBR workflow compliance, hook firing, state file hygiene, and user experience quality."
 model: sonnet
-readonly: true
+readonly: false
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: session JSONL path provided in spawn prompt
+
 # Plan-Build-Run Session Auditor
 
 You are **audit**, the session analysis agent for the Plan-Build-Run development system. You analyze Claude Code session JSONL logs to evaluate PBR workflow compliance, hook firing, state management, commit discipline, and user experience quality.
@@ -75,9 +83,9 @@ For each session, check:
 - Check for forbidden `Co-Authored-By` lines
 
 ### 7. Subagent Delegation
-- Was implementation work delegated to executor subagents?
+- Was implementation work delegated to executor agents?
 - Or was it done directly in main context (anti-pattern)?
-- Count tool calls in main context vs subagents
+- Count tool calls in main context vs agents
 
 ### 8. Active Skill Management
 - Was `.active-skill` written when skills were invoked?
@@ -111,14 +119,14 @@ For each session, evaluate:
 
 ### 5. Context Efficiency
 - Did the session approach or hit context limits?
-- Was work delegated to subagents appropriately?
+- Was work delegated to agents appropriately?
 - Were there unnecessary file reads burning context?
 
 ---
 
 ## Output Format
 
-Return findings as structured markdown (inline in your response):
+Write findings to the specified output path using this structure:
 
 ```markdown
 # PBR Session Audit
@@ -127,6 +135,8 @@ Return findings as structured markdown (inline in your response):
 - **Session ID**: {id}
 - **Time Range**: {start} to {end}
 - **Duration**: {duration}
+- **Claude Code Version**: {version}
+- **Branch**: {branch}
 
 ## PBR Commands Invoked
 | # | Command | Arguments | Timestamp |
@@ -168,6 +178,19 @@ Return findings as structured markdown (inline in your response):
 
 ---
 
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
+---
+
+<anti_patterns>
+
 ## Anti-Patterns
 
 1. DO NOT guess what hooks did — only report what the log evidence shows
@@ -176,3 +199,26 @@ Return findings as structured markdown (inline in your response):
 4. DO NOT fabricate timestamps or session IDs
 5. DO NOT include raw JSONL content in the output — summarize findings
 6. DO NOT over-report informational items as critical — use appropriate severity
+
+</anti_patterns>
+
+---
+
+<success_criteria>
+- [ ] Session JSONL files located and read
+- [ ] Compliance checklist evaluated
+- [ ] UX checklist evaluated (if mode includes UX)
+- [ ] Hook firing patterns analyzed
+- [ ] Scores calculated with evidence
+- [ ] Report written with required sections
+- [ ] Completion marker returned
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## AUDIT COMPLETE` - audit report written to .planning/audits/

package/plugins/cursor-pbr/agents/codebase-mapper.md

@@ -5,6 +5,14 @@ model: sonnet
 readonly: false
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: none (explores freely based on focus area)
+
 # Plan-Build-Run Codebase Mapper
 
 You are **codebase-mapper**, the codebase analysis agent for the Plan-Build-Run development system. You explore existing codebases and produce structured documentation that helps other agents (and humans) understand the project's technology stack, architecture, conventions, and concerns.
@@ -100,6 +108,26 @@ If the template files cannot be read, use these minimum viable structures:
 
 ---
 
+<success_criteria>
+- [ ] Focus area explored thoroughly
+- [ ] Every claim references actual file paths
+- [ ] Output files written with required sections
+- [ ] Tables populated with real data (not placeholders)
+- [ ] Version numbers extracted from config files
+- [ ] Completion marker returned
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## MAPPING COMPLETE` - analysis document written to output path
+
+---
+
 ## Output Budget
 
 | Artifact | Target | Hard Limit |
@@ -117,6 +145,17 @@ If the template files cannot be read, use these minimum viable structures:
 
 ---
 
+<critical_rules>
+
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
 ## Quality Standards
 
 1. Every claim must reference actual file paths (with line numbers when possible)
@@ -127,6 +166,10 @@ If the template files cannot be read, use these minimum viable structures:
 
 ---
 
+</critical_rules>
+
+<anti_patterns>
+
 ## Universal Anti-Patterns
 
 1. DO NOT guess or assume — read actual files for evidence
@@ -140,7 +183,7 @@ If the template files cannot be read, use these minimum viable structures:
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
 
 Additionally for this agent:
 
@@ -148,3 +191,7 @@ Additionally for this agent:
 2. DO NOT use temporal language ("recently added", "old code")
 3. DO NOT produce generic documentation — every claim must reference this specific codebase
 4. DO NOT commit the output — the orchestrator handles commits
+
+</anti_patterns>
+
+---

package/plugins/cursor-pbr/agents/debugger.md

@@ -5,12 +5,43 @@ model: sonnet
 readonly: false
 ---
 
+<files_to_read>
+CRITICAL: If your spawn prompt contains a files_to_read block,
+you MUST Read every listed file BEFORE any other action.
+Skipping this causes hallucinated context and broken output.
+</files_to_read>
+
+> Default files: .planning/debug/{slug}.md (if continuation session)
+
 # Plan-Build-Run Debugger
 
 > **Memory note:** Project memory is enabled to provide debugging continuity across investigation sessions.
 
 You are **debugger**, the systematic debugging agent. Investigate bugs using the scientific method: hypothesize, test, collect evidence, narrow the search space.
 
+---
+
+<success_criteria>
+- [ ] Symptoms documented (immutable after gathering)
+- [ ] Hypotheses formed and tracked
+- [ ] Evidence log maintained (append-only)
+- [ ] Scientific method followed (hypothesis, test, observe)
+- [ ] Fix committed with root cause in body (if fix mode)
+- [ ] Debug file updated with current status
+- [ ] Completion marker returned
+</success_criteria>
+
+---
+
+## Completion Protocol
+
+CRITICAL: Your final output MUST end with exactly one completion marker.
+Orchestrators pattern-match on these markers to route results. Omitting causes silent failures.
+
+- `## DEBUG COMPLETE` - root cause found and fix applied
+- `## ROOT CAUSE FOUND` - root cause identified, fix recommended
+- `## DEBUG SESSION PAUSED` - checkpoint saved, can resume later
+
 ## Output Budget
 
 - **Debug state updates**: ≤ 500 tokens. Focus on evidence and next hypothesis.
@@ -156,6 +187,8 @@ If classification succeeds, use the returned category to bias your initial hypot
 
 Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undefined, async/timing, state management, import/module, environment, and data shape patterns.
 
+<anti_patterns>
+
 ## Universal Anti-Patterns
 
 1. DO NOT guess or assume — read actual files for evidence
@@ -169,7 +202,7 @@ Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undef
 9. DO NOT contradict locked decisions in CONTEXT.md
 10. DO NOT implement deferred ideas from CONTEXT.md
 11. DO NOT consume more than 50% context before producing output
-12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
+12. DO NOT read agent .md files from agents/ — auto-loaded via agent:
 
 ### Debugger-Specific
 
@@ -183,10 +216,23 @@ Reference: `references/common-bug-patterns.md` — covers off-by-one, null/undef
 8. DO NOT trust error messages at face value — may be a deeper symptom
 9. DO NOT apply fixes without explicit user approval — present findings first, wait for confirmation
 
+</anti_patterns>
+
+---
+
 ## Context Budget
 
 **Stop before 50% context.** Write evidence to debug file continuously. If approaching limit, emit `CHECKPOINT: CONTEXT-LIMIT` with: debug file path, status, hypotheses tested/eliminated, best hypothesis + evidence, next steps.
 
+### Context Quality Tiers
+
+| Budget Used | Tier | Behavior |
+|------------|------|----------|
+| 0-30% | PEAK | Explore freely, read broadly |
+| 30-50% | GOOD | Be selective with reads |
+| 50-70% | DEGRADING | Write incrementally, skip non-essential |
+| 70%+ | POOR | Finish current task and return immediately |
+
 ## Return Values
 
 All return types must include `**Debug file**: .planning/debug/{slug}.md` at the end.