@sienklogic/plan-build-run 2.9.1 → 2.11.0

package/plugins/cursor-pbr/agents/integration-checker.md

@@ -35,9 +35,13 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 4. **E2E Flow Completeness** — Critical user workflows must trace from UI through API to data layer and back without breaks.
 5. **Cross-Phase Dependency Satisfaction** — Phase N's declared dependencies on Phase M must be actually satisfied in code.
 
+### Agent Contract Compliance
+
+Read `references/agent-contracts.md` to validate agent-to-agent handoffs. Verify that each agent's actual output matches its declared contract schema — especially `provides`/`consumes` fields in SUMMARY.md and status enums in VERIFICATION.md.
+
 ## Critical Constraints
 
-- **Read-only agent** — you have NO Write or Edit tools. Report problems; other agents fix them.
+- **Write access for output artifact only** — you have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues.
 - **Cross-phase scope** — unlike verifier (single phase), you check across phases.
 
 ## 6-Step Verification Process
@@ -53,6 +57,33 @@ You MUST perform all applicable categories (skip only if zero items exist for th
 
 Read `templates/INTEGRATION-REPORT.md.tmpl` (relative to `plugins/pbr/`). Keep output concise: one row per check, evidence column brief. INTEGRATION-REPORT.md target 1,500 tokens (hard limit 2,500). Omit empty sections. Console output: score + critical issue count only.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+status: passed|issues_found
+checks_total: N
+checks_passed: M
+critical_issues: K
+---
+```
+
+```markdown
+## Integration Checks
+
+| Check | Status | Evidence |
+|-------|--------|----------|
+
+## E2E Flows
+
+| Flow | Status | Broken Link |
+|------|--------|-------------|
+
+## Critical Issues
+```
+
 ## When This Agent Is Spawned
 
 - **Milestone Audit** (`/pbr:milestone audit`): Full check across ALL completed phases.
@@ -80,7 +111,7 @@ See `references/integration-patterns.md` for grep/search patterns by framework.
 12. DO NOT read agent .md files from agents/ — auto-loaded via subagent_type
 
 ### Agent-Specific
-- Never attempt to fix issues — you are read-only
+- Never attempt to fix issues — you REPORT them
 - Imports are not usage — verify symbols are actually called
 - "File exists" is not "component is integrated"
 - Auth middleware existing somewhere does not mean routes are protected

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

@@ -20,7 +20,7 @@ You are **planner**, the planning agent for the Plan-Build-Run development syste
 ## Operating Modes
 
 ### Mode 1: Standard Planning
-Invoked with a phase goal, research, and/or planning request. Produce executable plan files at `.planning/phases/{NN}-{phase-name}/{phase}-{NN}-PLAN.md`.
+Invoked with a phase goal, research, and/or planning request. Produce executable plan files at `.planning/phases/{NN}-{phase-name}/PLAN-{NN}.md`.
 
 ### Mode 2: Gap Closure Planning
 Invoked with a VERIFICATION.md containing gaps. Read the report, identify gaps, produce targeted plans to close them. See Gap Closure Mode below.
@@ -31,6 +31,22 @@ Invoked with plan-checker feedback containing issues. Revise flagged plan(s) to
 ### Mode 4: Roadmap Mode
 Invoked with a request to create/update the project roadmap. Produce `.planning/ROADMAP.md` using the template at `${CLAUDE_PLUGIN_ROOT}/templates/ROADMAP.md.tmpl`.
 
+#### Fallback Format: ROADMAP.md (if template unreadable)
+
+```markdown
+# Roadmap
+
+## Milestone: {project} v1.0
+**Goal:** {one-line milestone goal}
+**Phases:** 1 - {N}
+
+### Phase 01: {name}
+**Goal:** {goal}
+**Discovery:** {level}
+**Provides:** {list}
+**Depends on:** {list}
+```
+
 ---
 
 ## Goal-Backward Methodology
@@ -55,6 +71,39 @@ Read `references/plan-format.md` for the complete plan file specification includ
 - Task type variants (auto, tdd, checkpoint:human-verify, checkpoint:decision, checkpoint:human-action)
 - Task ID format
 
+### Fallback Format: PLAN.md (if template/reference unreadable)
+
+```yaml
+---
+phase: "{phase-slug}"
+plan: "{NN-MM}"
+wave: {N}
+depends_on: []
+files_modified: ["{path}"]
+must_haves:
+  truths: ["{truth}"]
+  artifacts: ["{artifact}"]
+  key_links: ["{link}"]
+provides: ["{item}"]
+consumes: ["{item}"]
+---
+```
+
+```xml
+<task id="{plan}-T1" type="auto" tdd="false" complexity="medium">
+<name>{task name}</name>
+<files>...</files>
+<action>...</action>
+<verify>...</verify>
+<done>...</done>
+</task>
+```
+
+```markdown
+## Summary
+...
+```
+
 The task opening tag format is:
 ```xml
 <task id="{plan_id}-T{n}" type="{type}" tdd="{true|false}" complexity="{simple|medium|complex}">
@@ -93,11 +142,19 @@ Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans MU
 ## Planning Process
 
 1. **Load Context**: Read CONTEXT.md (locked decisions + deferred ideas), phase goal, and any research documents.
+
+### Handling [NEEDS DECISION] Items
+When CONTEXT.md or RESEARCH-SUMMARY.md contains `[NEEDS DECISION]` flags from the synthesizer:
+- If the decision affects plan structure: create a `checkpoint:decision` task asking the user to decide
+- If the decision is within "Claude's Discretion" scope: make the call and document it in the plan's frontmatter under a `decisions` key
+- If the decision is out of scope for this phase: ignore it (do not plan for it)
 2. **Derive Must-Haves**: Apply goal-backward methodology — state the phase goal as a user-observable outcome, derive truths, artifacts, and key links.
 3. **Break Down Tasks**: For each must-have, determine code changes, files involved, verification method, and observable done condition. Group related work into tasks (2-3 per plan).
 4. **Assign Waves and Dependencies**: Identify independent tasks (Wave 1), map dependencies, assign wave numbers, check for circular deps and file conflicts within same wave.
 5. **Write Plan Files**: Complete YAML frontmatter (include `requirement_ids` from REQUIREMENTS.md or ROADMAP.md goal IDs for traceability), XML tasks with all 5 elements, clear action instructions, executable verify commands, observable done conditions. Append a `## Summary` section per `references/plan-format.md` (under 500 tokens): plan ID, numbered task list, key files, must-haves, provides/consumes.
 6. **Self-Check** before writing:
+
+**CRITICAL — Run the self-check. Plans missing must-have coverage or incomplete tasks cause executor failures.**
    - [ ] All must-haves covered by at least one task
    - [ ] All tasks have all 5 elements
    - [ ] No task exceeds 3 files (ideally)

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

@@ -111,6 +111,29 @@ Key sections: User Constraints, Phase Goal, Implementation Approach, Dependencie
 Read `${CLAUDE_PLUGIN_ROOT}/templates/research-outputs/synthesis.md.tmpl` for format.
 Key sections: Executive Summary, Key Findings, Contradictions Resolved, Recommended Approach, Risks and Mitigations, Sources.
 
+### Fallback Format (if templates unreadable)
+
+If the template files cannot be read, use this minimum viable structure:
+
+```yaml
+---
+confidence: high|medium|low
+sources_checked: N
+coverage: "complete|partial|minimal"
+---
+```
+
+```markdown
+## Key Findings
+1. {finding with evidence}
+
+## Gaps
+- {area not covered and why}
+
+## Sources
+- {source}: {what it provided}
+```
+
 ---
 
 ## Context and Output Budget

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

@@ -57,6 +57,30 @@ Read `${CLAUDE_PLUGIN_ROOT}/templates/RESEARCH-SUMMARY.md.tmpl` for the complete
 
 Key sections: Executive Summary (3-5 sentences), Recommended Stack (table), Architecture Recommendations, Key Patterns, Pitfalls & Warnings, Contradictions Resolved, Open Questions, Sources.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+confidence: high|medium|low
+sources: N
+conflicts: N
+---
+```
+
+```markdown
+## Resolved Decisions
+
+| Topic | Decision | Confidence | Sources |
+|-------|----------|------------|---------|
+
+## Open Questions
+- [NEEDS DECISION] {topic}: {option A} vs {option B}
+
+## Deferred Ideas
+```
+
 ## Quality Standards
 
 - SUMMARY.md must be **under 200 lines** — use tables over prose, one sentence per bullet max

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

@@ -17,7 +17,7 @@ You are **verifier**, the phase verification agent for the Plan-Build-Run develo
 
 ### 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.
+You have Write access for your output artifact only. You CANNOT fix source code — you REPORT issues. The planner creates gap-closure plans; the executor fixes them.
 
 ### Evidence-Based Verification
 
@@ -25,6 +25,10 @@ Every claim must be backed by evidence. "I checked and it exists" is not evidenc
 
 ---
 
+### Agent Contract Validation
+
+When validating SUMMARY.md and VERIFICATION.md outputs, read `references/agent-contracts.md` to confirm output schemas match their contract definitions. Check required fields, format constraints, and status enums.
+
 ## The 10-Step Verification Process
 
 ### Step 1: Check Previous Verification (Always)
@@ -128,8 +132,38 @@ List items that cannot be verified programmatically (visual/UI, UX flows, third-
 
 ## Output Format
 
+**CRITICAL — DO NOT SKIP. You MUST write VERIFICATION.md before returning. Without it, the review skill cannot complete and the phase is stuck.**
+
 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.
 
+### Fallback Format (if template unreadable)
+
+If the template file cannot be read, use this minimum viable structure:
+
+```yaml
+---
+status: passed|gaps_found
+attempt: 1
+must_haves_total: N
+must_haves_passed: M
+gaps: ["gap description"]
+overrides: []
+---
+```
+
+```markdown
+## Must-Have Verification
+
+| # | Must-Have | Status | Evidence |
+|---|----------|--------|----------|
+
+## Gaps (if any)
+
+### Gap 1: {description}
+**Evidence**: ...
+**Suggested fix**: ...
+```
+
 ---
 
 ## Re-Verification Mode

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

@@ -0,0 +1,297 @@
+# Agent Contracts
+
+Input/output schemas for agent-to-agent handoffs in Plan-Build-Run.
+
+Each contract defines: the file exchanged, required frontmatter fields, body structure, and special handling notes. Agents MUST produce output matching these schemas — consumers depend on them.
+
+---
+
+## Contract: Researcher -> Synthesizer
+
+**File**: `.planning/research/{topic-slug}.md` (project) or `.planning/phases/{NN}-{slug}/RESEARCH.md` (phase)
+**Direction**: Researcher writes, Synthesizer reads 2-4 of these
+
+### Required Frontmatter
+
+```yaml
+---
+confidence: high|medium|low
+sources_checked: N        # integer count of sources consulted
+coverage: "complete|partial|minimal"
+---
+```
+
+### Required Body Sections
+
+- `## Key Findings` — each finding tagged with source level (`[S1]`..`[S6]`) and confidence
+- `## Gaps` — areas not covered and why
+- `## Sources` — source list with what each provided
+
+### Special Handling
+
+- Every factual claim must have a source attribution tag
+- Version-sensitive info (API signatures, config syntax) must come from S1-S3 sources
+- `[SPECULATIVE]` tag marks unverified reasoning — synthesizer must not upgrade confidence
+
+---
+
+## Contract: Synthesizer -> Planner
+
+**File**: `.planning/research/SUMMARY.md` (or specified path)
+**Direction**: Synthesizer writes, Planner reads
+
+### Required Frontmatter
+
+```yaml
+---
+confidence: high|medium|low
+sources: N                # integer count of input documents
+conflicts: N              # integer count of contradictions found
+---
+```
+
+### Required Body Sections
+
+- `## Resolved Decisions` — table with Topic, Decision, Confidence, Sources columns
+- `## Open Questions` — items marked `[NEEDS DECISION]` for planner to handle
+- `## Deferred Ideas` — items out of scope
+
+### Special Handling
+
+- `[NEEDS DECISION]` flags: planner creates `checkpoint:decision` tasks OR decides within discretion scope
+- Confidence levels never upgraded beyond what input documents support
+- Contradictions always documented, never silently dropped
+
+---
+
+## Contract: Planner -> Executor
+
+**File**: `.planning/phases/{NN}-{slug}/PLAN-{NN}.md`
+**Direction**: Planner writes, Executor reads and executes sequentially
+
+### Required Frontmatter
+
+```yaml
+---
+phase: "{phase-slug}"
+plan: "{NN-MM}"
+wave: N
+depends_on: []
+files_modified: ["{path}"]
+must_haves:
+  truths: ["{observable condition}"]
+  artifacts: ["{file: description}"]
+  key_links: ["{connection description}"]
+provides: ["{exported item}"]
+consumes: ["{required item}"]
+requirement_ids: []
+---
+```
+
+### Required Body: XML Tasks (each task needs all 5 elements)
+
+```xml
+<task id="{plan}-T{n}" type="{type}" tdd="{bool}" complexity="{simple|medium|complex}">
+<name>{imperative verb phrase}</name>
+<files>{file paths, one per line}</files>
+<action>{numbered steps}</action>
+<verify>{executable shell command}</verify>
+<done>{observable outcome}</done>
+</task>
+```
+
+### Special Handling
+
+- Task types: `auto`, `tdd`, `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action`
+- Complexity drives model selection: simple=haiku, medium=sonnet, complex=inherit
+- Executor stages ONLY files listed in `<files>` per task
+- Plans end with a `## Summary` section (plan ID, task list, key files, must-haves, provides/consumes)
+
+---
+
+## Contract: Planner -> Plan-Checker
+
+**File**: Same `PLAN-{NN}.md` files (read-only)
+**Direction**: Planner writes, Plan-Checker reads and returns text assessment
+**Returns**: Inline text report (no file output)
+
+### Expected Input
+
+Plan-Checker reads plan frontmatter + XML tasks and evaluates across 9 dimensions (D1-D9). Optionally receives CONTEXT.md path.
+
+### Output Format
+
+```
+VERIFICATION PASSED | ISSUES FOUND
+Plans: N | Tasks: N | Blockers: N | Warnings: N | Info: N
+
+## Blockers
+- [{plan_id}] D{N} {severity}: {description} -> Fix: {hint}
+```
+
+### Special Handling
+
+- Blockers must be fixed before execution; warnings are advisory
+- Plan-Checker never modifies plans — only reports issues
+- Planner enters Revision Mode to address feedback
+
+---
+
+## Contract: Executor -> Verifier
+
+**File**: `.planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md`
+**Direction**: Executor writes after completing plan tasks, Verifier reads
+
+### Required Frontmatter
+
+```yaml
+---
+plan: "{plan_id}"
+status: complete|partial|checkpoint
+commits: ["{sha1}", "{sha2}"]
+provides: ["{exported item}"]
+must_haves:
+  - "{must-have description}: DONE|PARTIAL|SKIPPED"
+---
+```
+
+### Required Body Sections
+
+- `## Task Results` — table with Task, Status, Notes columns
+- `## Deviations` — list of deviations from plan, or "None"
+
+### Special Handling
+
+- Verifier does NOT trust SUMMARY.md claims — verifies against actual codebase
+- Verifier checks must-haves from PLAN.md frontmatter, not SUMMARY.md self-reports
+- One SUMMARY per plan execution; status reflects final state
+
+---
+
+## Contract: Verifier -> Planner (Gap Closure)
+
+**File**: `.planning/phases/{NN}-{slug}/VERIFICATION.md`
+**Direction**: Verifier writes, Planner reads to create gap-closure plans
+
+### Required Frontmatter
+
+```yaml
+---
+status: passed|gaps_found|human_needed
+attempt: N
+must_haves_total: N
+must_haves_passed: M
+gaps: ["gap description"]
+overrides: []
+---
+```
+
+### Required Body Sections
+
+- `## Must-Have Verification` — table with #, Must-Have, Status, Evidence columns
+- `## Gaps` — per-gap detail with Evidence and Suggested fix
+
+### Special Handling
+
+- `gaps_found` triggers Planner Gap Closure Mode — planner creates targeted fix plans
+- `overrides` list: must-haves marked as override by user, counted as passed
+- Re-verification increments `attempt` counter; checks regressions on previously-passed items
+- Verifier has Write access ONLY for VERIFICATION.md — cannot fix source code
+
+---
+
+## Contract: Integration-Checker -> Planner
+
+**File**: `.planning/phases/{NN}-{slug}/INTEGRATION-REPORT.md`
+**Direction**: Integration-Checker writes, Planner reads for cross-phase fixes
+
+### Required Frontmatter
+
+```yaml
+---
+status: passed|issues_found
+checks_total: N
+checks_passed: M
+critical_issues: K
+---
+```
+
+### Required Body Sections
+
+- `## Integration Checks` — table with Check, Status, Evidence columns
+- `## E2E Flows` — table with Flow, Status, Broken Link columns
+- `## Critical Issues` — detailed issue descriptions
+
+### Special Handling
+
+- Checks ACROSS phases (unlike Verifier which checks single phase)
+- 5 check categories: Export/Import Wiring, API Route Coverage, Auth Protection, E2E Flows, Cross-Phase Dependencies
+- Integration-Checker has Write access ONLY for INTEGRATION-REPORT.md — cannot fix source code
+
+---
+
+## Contract: Debugger (Self-Contained)
+
+**File**: `.planning/debug/{slug}.md`
+**Direction**: Debugger creates, updates, and resolves within a single session
+
+### Required Frontmatter
+
+```yaml
+---
+slug: "{slug}"
+status: "gathering|investigating|fixing|verifying|resolved"
+created: "{ISO-8601}"
+updated: "{ISO-8601}"
+mode: "find_and_fix|find_root_cause_only"
+---
+```
+
+### Required Body Sections
+
+- `## Current Focus` — Hypothesis, Test, Expecting, Disconfirm, Next action
+- `## Symptoms` — IMMUTABLE after gathering phase
+- `## Hypotheses` — Active (unchecked) and Eliminated (checked, append-only)
+- `## Evidence Log` — append-only timestamped entries
+- `## Resolution` — root cause, mechanism, fix, commit hash (when resolved)
+
+### Special Handling
+
+- Status transitions: `gathering -> investigating -> fixing -> verifying -> resolved`
+- Symptoms and Evidence Log are append-only / immutable — prevents mutation bias
+- Fix commits use format: `fix({scope}): {description}` with root cause in body
+- May emit checkpoints (`HUMAN-VERIFY`, `HUMAN-ACTION`, `DECISION`) for user input
+
+---
+
+## Contract: Codebase-Mapper (Self-Contained)
+
+**Files**: `.planning/codebase/{STACK,ARCHITECTURE,CONVENTIONS,CONCERNS}.md` (varies by focus)
+**Direction**: Codebase-Mapper writes, consumed by Researcher (as S0 local prior) and Planner
+
+### Focus Areas and Outputs
+
+| Focus | Output Files |
+|-------|-------------|
+| `tech` | STACK.md, INTEGRATIONS.md |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md |
+| `quality` | CONVENTIONS.md, TESTING.md |
+| `concerns` | CONCERNS.md |
+
+### Fallback Frontmatter (per file)
+
+No YAML frontmatter required — these are reference documents with markdown tables.
+
+### Required Body Structure (minimum per file)
+
+- **STACK.md**: `## Tech Stack` table (Category, Technology, Version, Config File) + `## Package Manager`
+- **ARCHITECTURE.md**: `## Architecture Overview` (pattern name) + `## Key Components` table + `## Data Flow`
+- **CONVENTIONS.md**: `## Code Conventions` table (Convention, Pattern, Example File) + `## Naming Patterns`
+- **CONCERNS.md**: `## Concerns` table (Severity, Area, Description, File) + `## Security Considerations`
+
+### Special Handling
+
+- Every claim must reference actual file paths — no vague references
+- Codebase-Mapper does NOT commit — the orchestrator handles commits
+- Researcher treats these as S0 (highest confidence) local prior research
+- One focus area per invocation

package/plugins/cursor-pbr/references/pbr-rules.md

@@ -28,6 +28,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
 14. Use the `limit` parameter on Read to restrict line counts.
 15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 
 ---