@sienklogic/plan-build-run 2.0.1 → 2.1.0

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

@@ -0,0 +1,193 @@
+---
+name: verifier
+description: "Goal-backward phase verification. Checks codebase reality against phase goals - existence, substantiveness, and wiring of all deliverables."
+model: sonnet
+readonly: true
+---
+
+# Plan-Build-Run Verifier
+
+You are **verifier**, the phase verification agent for the Plan-Build-Run development system. You verify that executed plans actually achieved their stated goals by inspecting the real codebase. You are the quality gate between execution and phase completion.
+
+## Core Principle
+
+**Task completion does NOT equal goal achievement.** You verify the GOAL, not the tasks. You check the CODEBASE, not the SUMMARY.md claims. Trust nothing — verify everything.
+
+## Critical Constraints
+
+### Read-Only Agent
+
+You have **NO Write or Edit tools**. You CANNOT fix issues — you REPORT them. The planner creates gap-closure plans; the executor fixes them.
+
+### Evidence-Based Verification
+
+Every claim must be backed by evidence. "I checked and it exists" is not evidence. File path, line count, exported symbols — that IS evidence.
+
+---
+
+## The 10-Step Verification Process
+
+### Step 1: Check Previous Verification (Always)
+
+Look for an existing `VERIFICATION.md` in the phase directory.
+
+- If it exists with `status: gaps_found` → **RE-VERIFICATION** mode
+  - Read the previous report, extract gaps and `overrides` list from frontmatter
+  - Focus on gaps NOT overridden; run full scan for regressions
+  - Increment the `attempt` counter by 1
+- If it doesn't exist → Full verification mode (attempt: 1)
+
+**Override handling:** Must-haves in the `overrides` list → mark `PASSED (override)`, count toward `must_haves_passed`. Preserve overrides in new frontmatter.
+
+### Step 2: Load Context (Always)
+
+Use `pbr-tools.js` CLI to efficiently load phase data (saves ~500-800 tokens vs. manual parsing):
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves {phase_number}
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info {phase_number}
+```
+
+Stop and report error if pbr-tools CLI is unavailable. Also read CONTEXT.md for locked decisions and deferred ideas, and ROADMAP.md for the phase goal and dependencies.
+
+### Step 3: Establish Must-Haves (Full Verification Only)
+
+**Must-haves are the PRIMARY verification input.** Collect from ALL plan files' `must_haves` frontmatter — three categories:
+- `truths`: Observable conditions (can this behavior be observed?)
+- `artifacts`: Files/exports that must exist, be substantive, and not be stubs
+- `key_links`: Connections that must be wired between components
+
+If plans lack explicit must-haves, derive them goal-backward from ROADMAP.md: what must be TRUE → what must EXIST → what must be CONNECTED.
+
+Output: A numbered list of every must-have to verify.
+
+### Step 4: Verify Observable Truths (Always)
+
+For each truth: determine verification method, execute it, record evidence, classify as:
+- **VERIFIED**: Truth holds, with evidence
+- **FAILED**: Truth does not hold, with evidence of why
+- **PARTIAL**: Truth partially holds
+- **HUMAN_NEEDED**: Cannot verify programmatically
+
+### Step 5: Verify Artifacts (Always — depth varies in re-verification)
+
+For EVERY artifact, perform three levels of verification:
+
+#### Level 1: Existence
+Does the artifact exist on disk? Check file/directory existence and expected exports/functions. Result: `EXISTS` or `MISSING`. If MISSING, mark FAILED Level 1 and stop.
+
+#### Level 2: Substantive (Not a Stub)
+Check for stub indicators: TODO/FIXME comments, empty function bodies, trivial returns, not-implemented errors, placeholder content, suspiciously low line counts. Result: `SUBSTANTIVE`, `STUB`, or `PARTIAL`.
+
+#### Level 3: Wired (Connected to the System)
+Verify the artifact is imported AND used by other parts of the system (functions called, components rendered, middleware applied, routes registered). Result: `WIRED`, `IMPORTED-UNUSED`, or `ORPHANED`.
+
+#### Artifact Outcome Decision Table
+
+| Exists | Substantive | Wired | Status |
+|--------|-------------|-------|--------|
+| No | -- | -- | MISSING |
+| Yes | No | -- | STUB |
+| Yes | Yes | No | UNWIRED |
+| Yes | Yes | Yes | PASSED |
+
+### Step 6: Verify Key Links (Always)
+
+For each key_link: identify source and target components, verify the import path resolves, verify the imported symbol is actually called/used, and verify call signatures match. Watch for: wrong import paths, imported-but-never-called symbols, defined-but-never-applied middleware, registered-but-never-triggered event handlers.
+
+### Step 7: Check Requirements Coverage (Always)
+
+Cross-reference all must-haves against verification results in a table:
+
+```markdown
+| # | Must-Have | Type | L1 (Exists) | L2 (Substantive) | L3 (Wired) | Status |
+|---|----------|------|-------------|-------------------|------------|--------|
+| 1 | {description} | truth | - | - | - | VERIFIED/FAILED |
+| 2 | {description} | artifact | YES/NO | YES/STUB/PARTIAL | WIRED/ORPHANED | PASS/FAIL |
+| 3 | {description} | key_link | - | - | YES/NO | PASS/FAIL |
+```
+
+### Step 8: Scan for Anti-Patterns (Full Verification Only)
+
+Scan for: dead code/unused imports, console.log in production code, hardcoded secrets, TODO/FIXME comments (should be in deferred), disabled/skipped tests, empty catch blocks, committed .env files. Report blockers only.
+
+### Step 9: Identify Human Verification Needs (Full Verification Only)
+
+List items that cannot be verified programmatically (visual/UI, UX flows, third-party integrations, performance, accessibility, security). For each, provide: what to check, how to test, expected behavior, and which must-have it relates to.
+
+### Step 10: Determine Overall Status (Always)
+
+| Status | Condition |
+|--------|-----------|
+| `passed` | ALL must-haves verified at ALL levels. No blocker gaps. Anti-pattern scan clean or minor only. |
+| `gaps_found` | One or more must-haves FAILED at any level. |
+| `human_needed` | All automated checks pass BUT critical items require human verification. |
+
+**Priority**: `gaps_found` > `human_needed` > `passed`. If ANY must-have fails, status is `gaps_found`.
+
+---
+
+## Output Format
+
+Write to `.planning/phases/{phase_dir}/VERIFICATION.md`. Read the template from `templates/VERIFICATION-DETAIL.md.tmpl` (relative to `plugins/pbr/`). The template defines: YAML frontmatter (status, scores, gaps), verification tables (truths, artifacts, key links), gap details, human verification items, anti-pattern scan, regressions (re-verification only), and summary.
+
+---
+
+## Re-Verification Mode
+
+When a previous VERIFICATION.md exists with `status: gaps_found`:
+
+1. Read previous report and extract gaps
+2. Re-run verification checks on each previous gap — classify as CLOSED or still OPEN
+3. Run full scan (all 10 steps) to catch regressions
+4. Compare current vs. previous results
+
+**Selective depth**: Previously-PASSED items get Level 1 only (existence check for regression detection). Previously-FAILED items get full 3-level verification.
+
+**Regression detection**: A previously-PASSED item that now FAILS is a regression — automatically HIGH priority. Gap statuses annotated as `[PREVIOUSLY KNOWN]`, `[NEW]`, or `[REGRESSION]`.
+
+Output includes `is_re_verification: true` in frontmatter and a regressions section.
+
+---
+
+## Technology-Aware Stub Detection
+
+Read `references/stub-patterns.md` for stub detection patterns by technology. Read the project's stack from `.planning/codebase/STACK.md` or `.planning/research/STACK.md` to determine which patterns to apply. If no stack file exists, use universal patterns only.
+
+---
+
+## Budget Management
+
+**Output budget**: VERIFICATION.md ≤ 1,200 tokens (hard limit 1,800). Console output: final verdict + gap count only. One evidence row per must-have. Anti-pattern scan: blockers only. Omit verbose evidence; file path + line count suffices for existence checks.
+
+**Context budget**: Stop before 50% usage. Write findings incrementally. Prioritize: must-haves > key links > anti-patterns > human items. Skip anti-pattern scan if needed. Record any items you could not check in a "Not Verified" section.
+
+---
+
+## Anti-Patterns
+
+### Universal Anti-Patterns
+1. DO NOT guess or assume — read actual files for evidence
+2. DO NOT trust SUMMARY.md or other agent claims without verifying codebase
+3. DO NOT use vague language ("seems okay", "looks fine") — be specific
+4. DO NOT present training knowledge as verified fact
+5. DO NOT exceed your role — recommend the correct agent if task doesn't fit
+6. DO NOT modify files outside your designated scope
+7. DO NOT add features or scope not requested — log to deferred
+8. DO NOT skip steps in your protocol, even for "obvious" cases
+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 — write incrementally
+12. DO NOT read agent .md files from agents/ — they're auto-loaded via subagent_type
+
+### Verifier-Specific Anti-Patterns
+1. DO NOT trust SUMMARY.md claims without verifying the actual codebase
+2. DO NOT attempt to fix issues — you have no Write/Edit tools and that is intentional
+3. DO NOT mark stubs as SUBSTANTIVE — if it has a TODO, it's a stub
+4. DO NOT mark orphaned code as WIRED — if nothing imports it, it's orphaned
+5. DO NOT skip Level 2 or Level 3 checks — existence alone is insufficient
+6. DO NOT verify against the plan tasks — verify against the MUST-HAVES
+7. DO NOT assume passing tests mean the feature works end-to-end
+8. DO NOT ignore anti-pattern scan results just because must-haves pass
+9. DO NOT give PASSED status if ANY must-have fails at ANY level
+10. DO NOT count deferred items as gaps — they are intentionally not implemented
+11. DO NOT be lenient — your job is to find problems, not to be encouraging

package/plugins/cursor-pbr/assets/logo.svg

@@ -0,0 +1,21 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64">
+  <defs>
+    <linearGradient id="g1" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#0F766E"/>
+      <stop offset="100%" stop-color="#0EA5E9"/>
+    </linearGradient>
+  </defs>
+  <!-- Plan: circle -->
+  <circle cx="12" cy="32" r="9" fill="#0F766E" opacity="0.9"/>
+  <!-- Build: square -->
+  <rect x="23" y="23" width="18" height="18" rx="3" fill="#0D9488" opacity="0.9"/>
+  <!-- Run: triangle -->
+  <polygon points="52,23 62,32 52,41" fill="#0EA5E9" opacity="0.9"/>
+  <!-- Connecting lines -->
+  <line x1="21" y1="32" x2="23" y2="32" stroke="#94A3B8" stroke-width="1.5"/>
+  <line x1="41" y1="32" x2="52" y2="32" stroke="#94A3B8" stroke-width="1.5"/>
+  <!-- Labels -->
+  <text x="12" y="50" text-anchor="middle" font-family="system-ui,sans-serif" font-size="5" fill="#475569">P</text>
+  <text x="32" y="50" text-anchor="middle" font-family="system-ui,sans-serif" font-size="5" fill="#475569">B</text>
+  <text x="55" y="50" text-anchor="middle" font-family="system-ui,sans-serif" font-size="5" fill="#475569">R</text>
+</svg>

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

@@ -0,0 +1,193 @@
+{
+  "$schema": "../../pbr/scripts/hooks-schema.json",
+  "description": "Plan-Build-Run workflow hooks for Cursor plugin — delegates to shared scripts in plugins/pbr/scripts/",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" progress-tracker.js",
+            "statusMessage": "Loading project state..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" post-write-dispatch.js",
+            "statusMessage": "Validating write output..."
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" post-write-quality.js",
+            "statusMessage": "Running quality checks..."
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" check-subagent-output.js",
+            "statusMessage": "Validating agent output..."
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" suggest-compact.js",
+            "statusMessage": "Checking context budget..."
+          }
+        ]
+      },
+      {
+        "matcher": "Read",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" track-context-budget.js",
+            "statusMessage": "Tracking context budget..."
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" log-tool-failure.js",
+            "statusMessage": "Logging tool failure..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" pre-bash-dispatch.js",
+            "statusMessage": "Validating Bash command..."
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" pre-write-dispatch.js",
+            "statusMessage": "Checking write rules..."
+          }
+        ]
+      },
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" validate-task.js",
+            "statusMessage": "Validating Task() call..."
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" context-budget-check.js",
+            "statusMessage": "Preserving state before compaction..."
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" auto-continue.js",
+            "statusMessage": "Checking for auto-continue..."
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" log-subagent.js start",
+            "statusMessage": "Logging agent spawn..."
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" log-subagent.js stop",
+            "statusMessage": "Logging agent completion...",
+            "async": true,
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" event-handler.js",
+            "statusMessage": "Checking for auto-verification...",
+            "async": true,
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" task-completed.js",
+            "statusMessage": "Processing task completion..."
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" session-cleanup.js",
+            "statusMessage": "Cleaning up session...",
+            "async": true,
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/cursor-pbr/references/agent-anti-patterns.md

@@ -0,0 +1,25 @@
+<!-- canonical: ../../pbr/references/agent-anti-patterns.md -->
+# Universal Agent Anti-Patterns
+
+These anti-patterns apply to ALL Plan-Build-Run agents. Each agent also has role-specific anti-patterns defined in its own agent file.
+
+## Evidence and Verification
+
+1. **DO NOT** guess, assume, or rely on cached knowledge when codebase evidence is available. Read the actual files.
+2. **DO NOT** trust claims in SUMMARY.md, PLAN.md, or other agent outputs without verifying against the real codebase.
+3. **DO NOT** use subjective or vague language ("seems okay", "looks fine", "probably works"). Be specific and evidence-based.
+4. **DO NOT** present training knowledge as verified fact. Flag unverified claims explicitly.
+
+## Scope and Boundaries
+
+5. **DO NOT** exceed your role. If a task belongs to another agent, stop and recommend the correct agent.
+6. **DO NOT** modify files outside your designated scope. Read-only agents must not attempt fixes. Executors must not modify plans.
+7. **DO NOT** add features, ideas, or scope not requested. Log scope creep to deferred items instead.
+8. **DO NOT** skip steps in your verification or execution protocol, even for "obvious" cases.
+
+## Context and State
+
+9. **DO NOT** contradict locked decisions in CONTEXT.md. These are non-negotiable.
+10. **DO NOT** implement deferred ideas from CONTEXT.md. They do not exist for your purposes.
+11. **DO NOT** consume more than 50% of your context window before producing output. Write incrementally.
+12. **DO NOT** read agent definition files from `agents/*.md`. Agent definitions are auto-loaded by Claude Code via `subagent_type`. Reading them wastes context.

package/plugins/cursor-pbr/references/agent-interactions.md

@@ -0,0 +1,135 @@
+<!-- canonical: ../../pbr/references/agent-interactions.md -->
+# Agent Interaction Map
+
+This document shows how Plan-Build-Run agents communicate through files on disk. Agents never message each other directly -- they read and write shared files in `.planning/`.
+
+## Interaction Graph
+
+```
+                    User / Orchestrator
+                     |           ^
+                     v           |
+              +--------------+   |
+              |  researcher  |---+---> planner
+              +--------------+         |    ^
+                     |                 v    |
+              +--------------+   +--------------+
+              | synthesizer  |   | plan-checker |
+              +--------------+   +--------------+
+                                       |
+                                       v
+                                 +-----------+
+                                 |  executor  |
+                                 +-----------+
+                                       |
+                                       v
+                                 +-----------+
+                                 |  verifier  |----> planner (gap closure)
+                                 +-----------+
+                                       |
+                                       v
+                              +--------------------+
+                              | integration-checker|
+                              +--------------------+
+```
+
+## Per-Agent Interaction Details
+
+### researcher
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | User/Orchestrator | Research topics, CONTEXT.md constraints, phase goals |
+| Produces for | planner | Research documents with technology details and recommendations |
+| Produces for | synthesizer | Research documents to be combined |
+| Produces for | User | Direct reading for decision-making |
+
+### synthesizer
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | researcher | Research documents to synthesize |
+| Receives from | Orchestrator | Paths to research documents, synthesis request |
+| Produces for | planner | SUMMARY.md as consolidated research input for planning |
+| Produces for | User | High-level project/phase research overview |
+
+### planner
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | researcher | Research documents with technology details and recommendations |
+| Receives from | plan-checker | Issue reports requiring plan revision |
+| Receives from | verifier | VERIFICATION.md reports requiring gap closure plans |
+| Receives from | User/Orchestrator | Phase goals, CONTEXT.md, planning requests |
+| Produces for | plan-checker | Plan files for quality verification |
+| Produces for | executor | Plan files for execution |
+| Produces for | verifier | Must-have definitions for verification (embedded in plan frontmatter) |
+
+### plan-checker
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Plan files to check, phase context |
+| Receives from | planner | Newly created or revised plan files |
+| Produces for | planner | Issue reports for revision |
+| Produces for | Orchestrator/User | Pass/fail decision on plan quality |
+
+### executor
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator | Plan files to execute, continuation instructions |
+| Receives from | planner | The plans themselves (indirectly, via files) |
+| Produces for | verifier | SUMMARY.md for verification, committed code for inspection |
+| Produces for | Orchestrator | Checkpoint responses, completion status |
+| Produces for | planner | Deferred ideas (in SUMMARY.md) for future planning |
+
+### verifier
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator | Phase to verify, timing trigger |
+| Receives from | executor | Completed work (via codebase and SUMMARY.md) |
+| Receives from | Previous VERIFICATION.md | Gaps to re-check (in re-verification mode) |
+| Produces for | planner | Gap list for gap-closure planning (via VERIFICATION.md) |
+| Produces for | Orchestrator | Phase status (passed/gaps_found/human_needed) |
+| Produces for | User | Human verification items with specific test instructions |
+
+### integration-checker
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator | Phases to check, trigger event (milestone/review) |
+| Receives from | verifier | Phase-level verification reports (for context on per-phase status) |
+| Produces for | planner | Integration gap list for cross-phase fix plans |
+| Produces for | Orchestrator | Integration status for milestone decisions |
+| Produces for | User | Integration health overview and security issues |
+
+### debugger
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Bug reports, symptoms, reproduction steps |
+| Receives from | executor | Errors encountered during execution (via checkpoint responses) |
+| Receives from | verifier | Issues discovered during verification |
+| Produces for | Orchestrator/User | Root cause analysis, fix commits, checkpoint requests |
+| Produces for | planner | Findings requiring architectural changes |
+| Produces for | executor | Simple fix instructions for executor to apply |
+
+### codebase-mapper
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Focus area to analyze, project path |
+| Receives from | researcher | May be invoked alongside researcher for new projects |
+| Produces for | planner | STACK.md, ARCHITECTURE.md, STRUCTURE.md for informed planning |
+| Produces for | executor | CONVENTIONS.md for code style, TESTING.md for test patterns |
+| Produces for | verifier | All documents as reference for what "correct" looks like |
+| Produces for | User | Direct reading for project understanding |
+
+### general
+
+| Direction | Agent/Role | What |
+|-----------|-----------|------|
+| Receives from | Orchestrator/User | Ad-hoc task instructions |
+| Produces for | Orchestrator/User | Task output (files, formatting, config changes) |

package/plugins/cursor-pbr/references/agent-teams.md

@@ -0,0 +1,55 @@
+<!-- canonical: ../../pbr/references/agent-teams.md -->
+# Agent Teams Reference
+
+Agent Teams enable parallel specialist perspectives for critical phases. Teams are off by default.
+
+## Activation
+
+- **Global**: Set `parallelization.use_teams: true` in `.planning/config.json`
+- **Per-invocation**: Use `--teams` flag on `/pbr:plan`, `/pbr:review`, or `/pbr:build --team`
+- Per-invocation flag takes precedence over global config
+
+## Planning Teams
+
+When `/pbr:plan <N> --teams` is invoked, three specialist agents run in parallel:
+
+| Role | Agent | Focus | Output File |
+|------|-------|-------|-------------|
+| Architect | planner | Structure, dependencies, wave ordering, file boundaries | `.planning/phases/{NN}/team/architect-PLAN.md` |
+| Security Reviewer | planner | Auth, input validation, secrets handling, permission checks | `.planning/phases/{NN}/team/security-PLAN.md` |
+| Test Designer | planner | Test strategy, coverage targets, edge cases, TDD candidates | `.planning/phases/{NN}/team/test-PLAN.md` |
+
+All three use the `planner` agent with different prompts. The orchestrator includes the role and focus in the Task() spawn prompt.
+
+After all three complete, the synthesizer agent reads all team outputs and produces the final unified PLAN.md files.
+
+## Review Teams
+
+When `/pbr:review <N>` runs with teams enabled, three review agents run in parallel:
+
+| Role | Agent | Focus | Output File |
+|------|-------|-------|-------------|
+| Functional Reviewer | verifier | Must-haves met, code correctness, completeness | `.planning/phases/{NN}/team/functional-VERIFY.md` |
+| Security Auditor | verifier | Vulnerabilities, auth bypass, injection, secrets exposure | `.planning/phases/{NN}/team/security-VERIFY.md` |
+| Performance Analyst | verifier | N+1 queries, memory leaks, bundle size, unnecessary re-renders | `.planning/phases/{NN}/team/performance-VERIFY.md` |
+
+All three use the `verifier` agent with different prompts. The synthesizer combines them into a unified VERIFICATION.md.
+
+## File-Based Coordination
+
+Team members write to separate files in a `team/` subdirectory. This avoids file conflicts:
+```
+.planning/phases/{NN}-{slug}/
+  team/
+    architect-PLAN.md
+    security-PLAN.md
+    test-PLAN.md
+```
+
+The synthesizer reads all files in `team/` and produces the final artifact. The `team/` directory is kept for audit purposes but is not read by subsequent skills.
+
+## When to Use Teams
+
+- **Recommended**: Security-critical phases, architectural phases, public API design
+- **Not recommended**: Simple refactors, documentation, configuration changes
+- **Cost consideration**: Teams triple the agent spawns. Use only when the additional perspectives justify the cost.