@sienklogic/plan-build-run 2.34.0 → 2.38.0

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

@@ -136,7 +136,12 @@ For each session:
 ```
 Task({
   subagent_type: "pbr:audit",
-  prompt: "<audit_assignment>
+  prompt: "<files_to_read>
+    CRITICAL: Read these files BEFORE any other action:
+    1. {absolute_path_to_session.jsonl} — session log to analyze
+    2. {subagent log paths, if any} — subagent session logs
+  </files_to_read>
+  <audit_assignment>
     Session JSONL: {absolute_path_to_session.jsonl}
     Subagent logs: {list of subagent jsonl paths, or 'none'}
     Audit mode: {mode}
@@ -172,7 +177,9 @@ Display progress:
 
 ## Step 5 — Collect and Synthesize
 
-As agents complete, collect their findings. Wait for all agents before proceeding.
+As agents complete, check each audit agent's Task() output for `## AUDIT COMPLETE`. If the marker is absent, mark that session as "analysis failed" in the synthesis and skip its findings — do not treat incomplete output as valid analysis. Log: `⚠ Session {id}: audit agent did not return completion marker — skipping.`
+
+Wait for all agents before proceeding.
 
 Synthesize across all sessions:
 
@@ -257,6 +264,15 @@ The report should follow this structure:
 
 ---
 
+## Step 6b — Spot-Check Artifacts
+
+**Before displaying results, verify the report landed on disk:**
+
+1. Glob `.planning/audits/{YYYY-MM-DD}-session-audit.md` to confirm the file exists
+2. If missing: re-attempt the write (Step 6). If still missing, display an error and include findings inline instead.
+
+---
+
 ## Step 7 — Display Summary
 
 After writing the report, display inline (keep it concise — the full report is on disk):
@@ -288,7 +304,7 @@ Full report: .planning/audits/{filename}
 - If todos identified: **Create todos** → `/pbr:todo add "{description}"`
 - Default: **See project status** → `/pbr:status`
 
-`/clear` first → fresh context window
+<sub>`/clear` first → fresh context window</sub>
 ```
 
 ---

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/config/SKILL.md

@@ -112,10 +112,11 @@ Use AskUserQuestion:
     - label: "Depth"          description: "quick/standard/comprehensive"
     - label: "Model profile"  description: "quality/balanced/budget/adaptive"
     - label: "Features"       description: "Toggle workflow features, gates, status line"
-    - label: "Git settings"   description: "branching strategy, commit mode"
+    - label: "Git settings"      description: "branching strategy, commit mode"
+    - label: "Save as defaults"  description: "Save current config as user-level defaults for new projects"
   multiSelect: false
 
-Note: The original 7 categories are condensed to 4. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features".
+Note: The original 7 categories are condensed to 5. "Models" (per-agent) is accessible through "Model profile" with a follow-up option. "Gates", "Parallelization", and "Status Line" are grouped under "Features". "Save as defaults" exports to ~/.claude/pbr-defaults.json.
 
 **Follow-up based on selection:**
 
@@ -178,6 +179,15 @@ Use AskUserQuestion:
     - label: "Disabled"    description: "No git integration"
   multiSelect: false
 
+If user selects "Save as defaults":
+Save current project config as user-level defaults for future projects:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" config save-defaults
+```
+
+Display: "Saved your preferences to ~/.claude/pbr-defaults.json. New projects created with /pbr:setup will use these as starting values."
+
 If user types something else (freeform): interpret as a direct setting command and handle via Step 2 argument parsing logic.
 
 ### 4. Apply Changes

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/health/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: health
 description: "Check planning directory integrity. Find and fix corrupted state."
+argument-hint: "[--repair]"
 ---
 
 ## Step 0 — Immediate Output
@@ -17,10 +18,16 @@ Then proceed to Step 1.
 
 # /pbr:health — Planning Directory Diagnostics
 
-You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes. You never auto-repair anything.
+You are running the **health** skill. Your job is to validate the integrity of the `.planning/` directory, report problems, and suggest targeted fixes.
 
 This skill runs **inline**. It is read-only by default, but offers an optional **auto-fix** flow for common corruption patterns (see the Auto-Fix section below).
 
+## Argument Parsing
+
+Check if the user passed `--repair`:
+- `--repair`: Skip the AskUserQuestion prompt in the Auto-Fix section and automatically apply ALL fixes (equivalent to selecting "Fix all"). Still create backups before any destructive operations.
+- No flag: Use the interactive AskUserQuestion flow as described below (default behavior).
+
 ---
 
 ## How Checks Work
@@ -184,7 +191,11 @@ cp .planning/STATE.md .planning/backups/STATE-$(date +%Y%m%dT%H%M%S).md
 
 This ensures the user can recover the original STATE.md if the fix produces incorrect results.
 
-1. Count the auto-fixable issues and present:
+1. Count the auto-fixable issues.
+
+   **If `--repair` flag was passed**: Skip the question and go directly to "Fix all" (step 2). Display: "Auto-repair mode: applying {N} fixes..."
+
+   **Otherwise**: Present the choice:
 
    Use AskUserQuestion:
      question: "Found {N} auto-fixable issues. How should we handle them?"
@@ -194,7 +205,7 @@ This ensures the user can recover the original STATE.md if the fix produces inco
        - label: "Review each"   description: "Show each fix and confirm individually"
        - label: "Skip"          description: "Do nothing — just report"
 
-2. If "Fix all": Apply all fixes in order, then display a summary:
+2. If "Fix all" (or `--repair`): Apply all fixes in order, then display a summary:
    ```
    Auto-fix results:
    - Fixed: {description of fix 1}
@@ -213,8 +224,6 @@ This ensures the user can recover the original STATE.md if the fix produces inco
 
 4. If "Skip": Do nothing, continue to the rest of the output.
 
-**Note:** When auto-fix is active, the health skill is no longer strictly read-only. The `allowed-tools` frontmatter must include `Write` and `AskUserQuestion` for auto-fix to work. Update the frontmatter accordingly.
-
 ---
 
 ## Bonus: Recent Decisions

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.