@sienklogic/plan-build-run 2.33.1 → 2.37.0

package/plugins/cursor-pbr/skills/begin/SKILL.md

@@ -226,6 +226,14 @@ For each researcher, construct the prompt by reading the template and filling in
 
 Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
 
+**Prepend this block to the researcher prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
+</files_to_read>
+```
+
 **Placeholders to fill:**
 - `{project name from questioning}` — project name gathered in Step 2
 - `{2-3 sentence description from questioning}` — project description from Step 2
@@ -268,6 +276,11 @@ Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure
 - When all complete: "All {N} researchers finished. Proceeding to synthesis."
 - Wait for all to complete before proceeding
 
+**After each researcher completes**, check the agent output for a completion marker:
+- If `## RESEARCH COMPLETE` is present: researcher finished successfully, proceed
+- If `## RESEARCH BLOCKED` is present: warn the user that research could not complete, ask if they want to proceed with limited context or stop
+- If neither marker is present: warn that researcher may not have completed successfully, but proceed if output files exist on disk
+
 ---
 
 ### Step 6: Synthesis (delegated to agent)
@@ -284,12 +297,38 @@ Invoke the `@synthesizer` agent with the synthesis prompt.
 
 Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
 
+**Prepend this block to the synthesizer prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/research/*.md — all research output files from Step 5
+</files_to_read>
+```
+
 **Placeholders to fill:**
 - `{List all .planning/research/*.md files that were created}` — list the research files produced in Step 5
 
-**After the synthesizer completes**, display:
+**After the synthesizer completes**, check for completion markers in the Task() output:
+
+- If `## SYNTHESIS COMPLETE` is present: proceed normally
+- If `## SYNTHESIS BLOCKED` is present: warn the user and offer to proceed without synthesis:
+  ```
+  ⚠ Synthesizer reported BLOCKED: {reason from output}
+  Research files are still available individually in .planning/research/.
+  ```
+  Use AskUserQuestion (pattern: yes-no from `skills/shared/gate-prompts.md`):
+    question: "Synthesis was blocked. Continue without synthesis?"
+    header: "Blocked"
+    options:
+      - label: "Yes"  description: "Proceed to requirements — use individual research files"
+      - label: "No"   description: "Stop and investigate"
+  - If "Yes": proceed to Step 7 without SUMMARY.md
+  - If "No": stop and suggest reviewing .planning/research/ files
+- If neither marker is found: warn the user that the synthesizer may not have completed successfully, but proceed if SUMMARY.md exists on disk
+
+If synthesis succeeded, display:
 ```
-Research synthesis complete — see .planning/research/SUMMARY.md
+✓ Research synthesis complete — see .planning/research/SUMMARY.md
 ```
 
 ---
@@ -353,12 +392,26 @@ Invoke the `@planner` agent in roadmap mode with the roadmap prompt.
 
 Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
 
+**Prepend this block to the roadmap planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/REQUIREMENTS.md — scoped requirements for phase planning
+2. .planning/research/SUMMARY.md — research synthesis (if exists)
+</files_to_read>
+```
+
 **Placeholders to fill:**
 - `{project name}` — project name from Step 2
 - `{description}` — project description from Step 2
 - `{quick|standard|comprehensive}` — depth setting from Step 3
 
-**After the planner completes:**
+**After the planner completes**, check the agent output for a completion marker:
+- If `## PLANNING COMPLETE` is present: planner finished successfully, proceed
+- If `## PLANNING FAILED` is present: warn the user that planning could not complete, display the reason, and offer to retry or abort
+- If neither marker is present: warn that planner may not have completed successfully, but proceed if ROADMAP.md exists on disk
+
+- **Spot-check:** Verify `.planning/ROADMAP.md` exists on disk using Glob before attempting to read it. If missing, the planner may have failed silently — warn: `⚠ ROADMAP.md not found after planner completed. Re-spawning planner...` and retry once.
 - Read `.planning/ROADMAP.md`
 - Count the phases and milestones from the roadmap content
 - Display:
@@ -505,7 +558,7 @@ Delete `.planning/.active-skill` if it exists. This must happen on all paths (su
 
 After all steps complete, present the final summary using the stage banner format from Read `references/ui-formatting.md`:
 
-Display the `PROJECT INITIALIZED` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to `/pbr:discuss 1` with alternatives: `/pbr:explore`, `/pbr:plan 1`, `/pbr:config`.
+Display the `PROJECT INITIALIZED ✓` banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to `/pbr:discuss 1` with alternatives: `/pbr:explore`, `/pbr:plan 1`, `/pbr:milestone new`, `/pbr:config`. Include `<sub>/clear first → fresh context window</sub>` inside the Next Up routing block.
 
 ---
 

package/plugins/cursor-pbr/skills/build/SKILL.md

@@ -133,6 +133,8 @@ Phase {N} depends on Phase {M}, which is not complete.
 
 ### Step 2: Load Config (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init execute-phase {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 Read configuration values needed for execution. See `skills/shared/config-loading.md` for the full field reference; build uses: `parallelization.*`, `features.goal_verification`, `features.inline_verify`, `features.atomic_commits`, `features.auto_continue`, `features.auto_advance`, `planning.commit_docs`, `git.commit_format`, `git.branching`.
 
 ---
@@ -302,6 +304,13 @@ Construct the executor prompt:
 ```
 You are the executor agent. Execute the following plan.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/{plan_id}-PLAN.md — the full plan with task details
+2. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+3. .planning/STATE.md — current project state and progress
+</files_to_read>
+
 <plan_summary>
 [Inline only the ## Summary section from PLAN.md]
 </plan_summary>
@@ -371,7 +380,9 @@ Task({
   prompt: <executor prompt constructed above>
 })
 
-NOTE: The pbr:executor agent type auto-loads the agent definition. Do NOT inline it.
+NOTE: The pbr:executor agent type auto-loads the agent definition.
+
+After executor completes, check for completion markers: `## PLAN COMPLETE`, `## PLAN FAILED`, or `## CHECKPOINT: {TYPE}`. Route accordingly — PLAN COMPLETE proceeds to next plan, PLAN FAILED triggers failure handling, CHECKPOINT triggers checkpoint flow. Do NOT inline it.
 ```
 
 **Path resolution**: Before constructing the agent prompt, resolve `${PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
@@ -407,6 +418,11 @@ After reading each SUMMARY, perform a lightweight verification:
 - If ANY spot-check fails, warn the user before proceeding to the next wave:
   "Spot-check failed for plan {id}: {detail}. Inspect before continuing?"
 
+**Additional wave spot-checks:**
+- Check for `## Self-Check: FAILED` in SUMMARY.md — if present, warn user before proceeding to next wave
+- Between waves: verify no file conflicts from parallel executors (check `git status` for uncommitted changes)
+- If ANY spot-check fails, present user with: **Retry this plan** / **Continue to next wave** / **Abort build**
+
 **Read executor deviations:**
 
 After all executors in the wave complete, read all SUMMARY frontmatter and:
@@ -449,7 +465,14 @@ For each plan that completed successfully in this wave:
 Task({
   agent_type: "pbr:verifier",
   model: "haiku",
-  prompt: "Targeted inline verification for plan {plan_id}.
+  prompt: "<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/{plan_id}-PLAN.md — must-haves to verify against
+2. .planning/phases/{NN}-{slug}/SUMMARY-{plan_id}.md — what the executor claims was built
+3. .planning/phases/{NN}-{slug}/VERIFICATION.md — prior verification results (if exists)
+</files_to_read>
+
+Targeted inline verification for plan {plan_id}.
 
 Verify ONLY these files: {comma-separated key_files list}
 
@@ -654,6 +677,8 @@ Task({
 })
 
 NOTE: The pbr:verifier agent type auto-loads the agent definition. Do NOT inline it.
+
+After verifier completes, check for completion marker: `## VERIFICATION COMPLETE`. Read VERIFICATION.md frontmatter for status.
 ```
 
 **Path resolution**: Before constructing the agent prompt, resolve `${PLUGIN_ROOT}` to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
@@ -662,6 +687,16 @@ NOTE: The pbr:verifier agent type auto-loads the agent definition. Do NOT inline
 
 Use the same verifier prompt template as defined in `/pbr:review`: read `skills/review/templates/verifier-prompt.md.tmpl` and fill in its placeholders with the phase's PLAN.md must_haves and SUMMARY.md file paths. This avoids maintaining duplicate verifier prompts across skills.
 
+**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>
+```
+
 After the verifier returns, read the VERIFICATION.md frontmatter and display the results:
 
 - If status is `passed`: display `✓ Verifier: {X}/{Y} must-haves verified` (where X = `must_haves_passed` and Y = `must_haves_checked`)

package/plugins/cursor-pbr/skills/debug/SKILL.md

@@ -210,7 +210,18 @@ Continuing investigation...
 
 ### Step 4: Handle Debugger Results
 
-When the debugger agent completes, display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
+When the debugger agent completes, first check for completion markers in the Task() output before routing:
+
+| Marker in Task() Output | Route To |
+|--------------------------|----------|
+| `## DEBUG COMPLETE` | ROOT CAUSE FOUND + FIX path |
+| `## ROOT CAUSE FOUND` | ROOT CAUSE FOUND (no fix) path |
+| `## DEBUG SESSION PAUSED` | CHECKPOINT path |
+| No marker found | INCONCLUSIVE path |
+
+**Spot-check:** Before routing, verify `.planning/debug/{NNN}-{slug}.md` exists and was recently updated (modified timestamp is newer than the Task() spawn time). If the debug file was not updated, warn: `⚠ Debug file not updated by agent — results may be incomplete.`
+
+Display: `✓ Debug session complete — {N} hypotheses tested` (read the hypothesis count from the debug file's Hypotheses table).
 
 The debugger returns one of four outcomes:
 

package/plugins/cursor-pbr/skills/explore/SKILL.md

@@ -119,7 +119,12 @@ Display to the user: `◐ Spawning researcher...`
 ```
 Task({
   subagent_type: "pbr:researcher",
-  prompt: "<research_assignment>
+  prompt: "<files_to_read>
+    CRITICAL: Read these files BEFORE any other action:
+    1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+    2. .planning/STATE.md — current project state (if exists)
+  </files_to_read>
+  <research_assignment>
     Topic: {specific research question}
     Output file: .planning/research/{topic-slug}.md
     Mode: project-research
@@ -131,7 +136,13 @@ Task({
 })
 ```
 
-After the researcher completes, display: `✓ Research complete — results in .planning/research/{topic-slug}.md`
+After the researcher completes, check for completion markers in the Task() output:
+
+- If `## RESEARCH COMPLETE` is present: proceed normally
+- If `## RESEARCH BLOCKED` is present: display the blocker reason and offer to retry:
+  `⚠ Research blocked: {reason}. Try a different angle or continue without research.`
+
+Display: `✓ Research complete — results in .planning/research/{topic-slug}.md`
 
 Then:
 - Read ONLY the frontmatter and summary section of the research file (not the full document)

package/plugins/cursor-pbr/skills/import/SKILL.md

@@ -276,6 +276,13 @@ Task({
 ```
 You are the plan-checker agent.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+2. .planning/STATE.md — current project state and progress
+3. .planning/ROADMAP.md — phase structure, goals, and dependencies
+</files_to_read>
+
 <plans_to_check>
 {For each generated PLAN.md:}
 --- Plan File: {filename} ---
@@ -306,7 +313,15 @@ Run all verification dimensions on these plans. Return your structured report.
 Do NOT write any files. Return your findings as your response text.
 ```
 
-**Process checker results — revision loop:**
+**Process checker results — completion marker check:**
+
+After the plan-checker completes, check for completion markers in the Task() output:
+
+- If `## CHECK PASSED` is present: skip the revision loop entirely and proceed to Step 7.
+- If `## ISSUES FOUND` is present: enter the revision loop below.
+- If neither marker is found: treat as issues found and enter the revision loop.
+
+**Revision loop:**
 
 Reference: `skills/shared/revision-loop.md` for the full Check-Revise-Escalate pattern (max 3 iterations).
 
@@ -326,6 +341,16 @@ If existing plans are being replaced (user confirmed in Step 1):
 
 ---
 
+**Step 7b — Spot-check artifacts:**
+
+After writing plan files, verify they landed on disk:
+
+1. Glob `.planning/phases/{NN}-{slug}/PLAN-*.md` to confirm files exist
+2. Count matches — must equal the number of plans generated in Step 5
+3. If any are missing: re-attempt the write. If still missing, display an error listing the missing files.
+
+---
+
 ### Step 8: Update All State (inline)
 
 Perform all state updates in this order:

package/plugins/cursor-pbr/skills/milestone/SKILL.md

@@ -487,6 +487,12 @@ Verify milestone completion with cross-phase integration checks.
    ```
    You are integration-checker. Perform cross-phase integration verification.
 
+   <files_to_read>
+   CRITICAL: Read these files BEFORE any other action:
+   1. .planning/ROADMAP.md — phase structure, goals, and dependencies
+   2. .planning/phases/{NN}-{slug}/SUMMARY.md — for each milestone phase (read all)
+   </files_to_read>
+
    Milestone: {version or "current"}
    Phases to check: {list of phase directories}
 
@@ -506,20 +512,26 @@ Verify milestone completion with cross-phase integration checks.
    5. Return findings as a structured report
    ```
 
-4. **Check requirements coverage:**
+4. **Check integration-checker completion:**
+
+   After the integration-checker completes, check for `## INTEGRATION CHECK COMPLETE` in the Task() output. If the marker is absent, warn: `⚠ Integration checker did not return completion marker — results may be incomplete.` Proceed with whatever findings were returned but note the incomplete status in the audit report.
+
+5. **Check requirements coverage:**
    - Read REQUIREMENTS.md
    - For each requirement tagged for this milestone:
      - Search VERIFICATION.md files for coverage
      - Search SUMMARY.md `provides` fields
      - Flag uncovered requirements
 
-5. **Write audit report:**
+6. **Write audit report:**
 
    Create `.planning/{version}-MILESTONE-AUDIT.md` using the template:
 
    Read `skills/milestone/templates/audit-report.md.tmpl` for the audit report format. Fill in all `{variable}` placeholders with actual data from the audit.
 
-6. **Report to user** using branded banners:
+   **Spot-check:** After writing, verify `.planning/{version}-MILESTONE-AUDIT.md` exists on disk using Glob. If missing, re-attempt the write. If still missing, display an error and include findings inline.
+
+7. **Report to user** using branded banners:
 
    **If PASSED:**
    ```

package/plugins/cursor-pbr/skills/plan/SKILL.md

@@ -4,6 +4,8 @@ description: "Create a detailed plan for a phase. Research, plan, and verify bef
 argument-hint: "<phase-number> [--skip-research] [--assumptions] [--gaps] | add | insert <N> | remove <N>"
 ---
 
+**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.**
+
 # /pbr:plan — Phase Planning
 
 You are the orchestrator for `/pbr:plan`. This skill creates detailed, executable plans for a specific phase. Plans are the bridge between the roadmap and actual code — they must be specific enough for an executor agent to follow mechanically. Your job is to stay lean, delegate heavy work to agents, and keep the user's main context window clean.
@@ -136,6 +138,8 @@ Reference: `skills/shared/config-loading.md` for the tooling shortcut (`state lo
 
 ### Step 2: Load Context (inline)
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init plan-phase {N}` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 Read context file PATHS and metadata. Build lean context bundles for agent prompts — include paths and one-line descriptions, NOT full file bodies. Agents have the Read tool and will pull file contents on-demand.
 
 ```
@@ -222,8 +226,22 @@ Read `skills/plan/templates/researcher-prompt.md.tmpl` and use it as the prompt
 - `{dependencies from roadmap}` - dependency list
 - Fill `<project_context>` and `<prior_work>` blocks per the shared partial (`templates/prompt-partials/phase-project-context.md.tmpl`): Decision Summary for context, manifest table for prior work
 
+**Prepend this block to the researcher prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/ROADMAP.md — phase goals, dependencies, and structure
+2. .planning/REQUIREMENTS.md — scoped requirements for this phase (if exists)
+</files_to_read>
+```
+
 Wait for the researcher to complete before proceeding.
 
+After the researcher completes, check the agent output for a completion marker:
+- If `## RESEARCH COMPLETE` is present: proceed to planner
+- If `## RESEARCH BLOCKED` is present: warn the user that research could not complete, ask if they want to proceed with limited context or stop
+- If neither marker is present: warn that researcher may not have completed successfully, but proceed
+
 ---
 
 ### Step 4.5: Seed Scanning (inline, before planning)
@@ -337,6 +355,16 @@ Read `skills/plan/templates/planner-prompt.md.tmpl` and use it as the prompt tem
 - `<config>` - max tasks, parallelization, TDD mode from config.json
 - `<planning_instructions>` - phase-specific planning rules and output path
 
+**Prepend this block to the planner prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/CONTEXT.md — locked decisions and constraints (if exists)
+2. .planning/ROADMAP.md — phase goals, dependencies, and structure
+3. .planning/phases/{NN}-{slug}/RESEARCH.md — research findings (if exists)
+</files_to_read>
+```
+
 Wait for the planner to complete.
 
 After the planner returns, read the plan files it created to extract counts. Display a completion summary:
@@ -347,6 +375,17 @@ Planner created {N} plan(s) across {M} wave(s)
 
 Where `{N}` is the number of PLAN.md files written and `{M}` is the number of distinct wave values across those plans (from frontmatter).
 
+### Step 5b: Spot-Check Planner Output
+
+CRITICAL: Verify planner output before proceeding.
+
+1. **PLAN files exist**: Check `.planning/phases/{NN}-{slug}/PLAN-*.md` files exist on disk
+2. **Valid frontmatter**: Read first 20 lines of each PLAN file — verify `depends_on`, `files_modified`, `must_haves` fields present
+3. **Task structure**: Verify at least one `<task>` block exists in each plan file
+4. **Plan count matches**: Number of PLAN files matches what the planner reported
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
 ---
 
 ### Step 6: Plan Validation (delegated, conditional)
@@ -373,6 +412,15 @@ Read `skills/plan/templates/checker-prompt.md.tmpl` and use it as the prompt tem
 - `<phase_context>` - phase goal and requirement IDs
 - `<context>` - file paths to project-level and phase-level CONTEXT.md files (checker reads via Read tool)
 
+**Prepend this block to the checker prompt before sending:**
+```
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/phases/{NN}-{slug}/PLAN-*.md — plan files to validate
+2. .planning/CONTEXT.md — locked decisions to check against (if exists)
+</files_to_read>
+```
+
 **Process checker results:**
 
 After the plan checker returns, display its result:
@@ -464,6 +512,8 @@ Use the approve-revise-abort pattern from `skills/shared/gate-prompts.md`:
   5. Update the `Status` column to `planned`
   6. Save the file — do NOT skip this step
 - Update STATE.md **(CRITICAL — update BOTH frontmatter AND body)**: set `status: "planned"`, `plans_total`, `last_command` in frontmatter AND update `Status:`, `Plan:` lines in body `## Current Position`
+
+**Tooling shortcut**: `node ${PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"planned","last_command":"/pbr:plan {N}"}'`
 - **If `features.auto_advance` is `true` AND `mode` is `autonomous`:** Chain directly to build. This continues the build->review->plan->build cycle automatically.
 - **Otherwise:** Suggest next action: `/pbr:build {N}`
 

package/plugins/cursor-pbr/skills/quick/SKILL.md

@@ -44,6 +44,8 @@ Additionally for this skill:
 
 ### Step 1: Check Project Context
 
+**Init-first pattern**: When spawning agents, pass the output of `node plugins/pbr/scripts/pbr-tools.js init quick "{description}"` as context rather than having the agent read multiple files separately. This reduces file reads and prevents context-loading failures.
+
 1. Check if `.planning/` directory exists
    - If yes: read config.json for settings
    - If no: create **both** `.planning/` and `.planning/quick/` directories, then warn "No Plan-Build-Run project found. This will create a standalone quick task. Consider running `/pbr:begin` first for full project tracking."
@@ -167,9 +169,17 @@ Display to the user: `◐ Spawning executor...`
 
 Spawn a `Task(agent_type: "pbr:executor")` with the following prompt:
 
+> **Completion markers**: After executor completes, check for `## PLAN COMPLETE` or `## PLAN FAILED`. Route accordingly.
+
 ```
 You are executor. Execute the following quick task plan.
 
+<files_to_read>
+CRITICAL: Read these files BEFORE any other action:
+1. .planning/quick/{NNN}-{slug}/PLAN.md — the quick task plan with task details
+2. .planning/STATE.md — current project state and progress (if exists)
+</files_to_read>
+
 Plan file: .planning/quick/{NNN}-{slug}/PLAN.md
 Phase: quick
 Plan ID: {NNN}
@@ -192,6 +202,17 @@ After the executor completes:
    - `partial` — some tasks completed, others failed
    - `failed` — task failed entirely
 
+### Step 8b: Spot-Check Executor Output
+
+CRITICAL: Verify executor output before proceeding.
+
+1. **SUMMARY.md exists**: Check `.planning/quick/{NNN}-{slug}/SUMMARY.md` exists
+2. **Key files exist**: Verify first 2 files from SUMMARY.md `key_files` frontmatter exist on disk
+3. **Commits present**: Run `git log --oneline -5` and verify at least one commit matches the task scope
+4. **Self-check status**: Look for `## Self-Check: FAILED` in SUMMARY.md — if present, warn the user
+
+If ANY spot-check fails, present the user with options: **Retry** / **Continue anyway** / **Abort**
+
 ### Step 9: Update STATE.md
 
 If STATE.md exists, update the Quick Tasks section.

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

@@ -61,6 +61,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.
@@ -155,6 +157,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.
@@ -181,6 +193,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)
@@ -368,6 +391,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
@@ -383,6 +416,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)
@@ -563,6 +606,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/cursor-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: