@sienklogic/plan-build-run 2.34.0 → 2.37.0

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/checkpoints.md -->
 # Checkpoints Reference
 
 How Plan-Build-Run uses checkpoint tasks to pause execution and involve the human.
@@ -156,3 +155,35 @@ When creating plans that include checkpoints:
 4. **Provide clear instructions** — the `<action>` and `<verify>` elements should give the human everything they need
 5. **Consider autonomous alternatives** — if a task CAN be verified automatically, prefer `type="auto"` with a robust `<verify>` command
 6. **Set `autonomous: false`** in the plan frontmatter when any task is a checkpoint
+
+---
+
+## Automation-First Philosophy
+
+### 5 Golden Rules
+1. If Claude CAN run it, Claude MUST run it
+2. If Claude CAN verify it, Claude MUST verify it
+3. Only checkpoint for things requiring human senses or credentials
+4. Group manual actions to minimize checkpoint count
+5. Never ask the user to do something automatable
+
+### Automatable Quick Reference
+
+| Action | Automatable? | Notes |
+|--------|-------------|-------|
+| Run tests | YES | `npm test`, `pytest`, etc. |
+| Start dev server | YES | `npm run dev` (check port) |
+| Check environment variables | YES | `env \| grep KEY` |
+| Build project | YES | `npm run build` |
+| Run linting | YES | `npm run lint` |
+| Database migrations | YES | CLI commands |
+| Click email verification link | NO | Requires browser + inbox |
+| 3DS payment verification | NO | Requires card + phone |
+| OAuth consent screen | NO | Requires browser interaction |
+| Hardware token/YubiKey | NO | Physical device |
+
+### Anti-Patterns
+- Asking user to "start the dev server" — just run it
+- Asking user to "check if tests pass" — run `npm test`
+- Saying "please verify the output" without running verification commands first
+- Creating a checkpoint for `mkdir` or `npm install`

package/plugins/cursor-pbr/references/context-quality-tiers.md

@@ -0,0 +1,45 @@
+# Context Quality Tiers
+
+Behavioral guidance for agents based on context window utilization.
+
+## Tier Definitions
+
+| Tier | Context Used | Quality | Guidance |
+|------|-------------|---------|----------|
+| PEAK | 0-30% | Full capacity | Explore freely, read broadly, take time to understand |
+| GOOD | 30-50% | High capacity | Be selective with reads, skip non-essential exploration |
+| DEGRADING | 50-70% | Declining capacity | Write incrementally, finish current task, skip nice-to-haves |
+| POOR | 70%+ | Critical | Finish current task IMMEDIATELY and return. No new reads. |
+
+## Behavioral Rules Per Tier
+
+### PEAK (0-30%)
+- Read all relevant files before making changes
+- Explore adjacent code for patterns and conventions
+- Write comprehensive commit messages
+- Full self-check protocols
+
+### GOOD (30-50%)
+- Read only files directly relevant to current task
+- Skip exploratory reads of "nice to have" context
+- Standard commit messages
+- Standard self-check
+
+### DEGRADING (50-70%)
+- Write changes incrementally (don't accumulate large diffs)
+- Skip optional verification steps
+- Brief commit messages
+- Abbreviated self-check (key_files only)
+
+### POOR (70%+)
+- STOP exploring. Finish the current task only.
+- Write SUMMARY.md immediately if executor
+- Return completion marker immediately
+- Do NOT start new tasks or reads
+
+## Agent-Specific Overrides
+
+- **Researcher**: At DEGRADING, write findings immediately rather than accumulating
+- **Executor**: At DEGRADING, complete current task then return CHECKPOINT
+- **Verifier**: At DEGRADING, check existence only (skip substantiveness/wiring layers)
+- **Planner**: At GOOD, reduce task detail level; at DEGRADING, finish current plan file only

package/plugins/cursor-pbr/references/pbr-tools-cli.md

@@ -283,3 +283,118 @@ node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"scri
 **Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
 
 If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.
+
+---
+
+## Compound Init Commands
+
+Compound commands that compose multiple data sources into a single JSON response.
+Replace multi-step context loading in skills with a single CLI call.
+
+### `init execute-phase <phase>`
+
+Everything an executor needs to start building a phase.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init execute-phase 3
+```
+
+**Output:**
+```json
+{
+  "executor_model": "sonnet",
+  "verifier_model": "sonnet",
+  "config": { "depth": "standard", "mode": "interactive", "parallelization": {}, "planning": {}, "gates": {}, "features": {} },
+  "phase": { "num": "3", "dir": "03-auth", "name": "auth", "goal": "...", "has_context": false, "status": "planned", "plan_count": 2, "completed": 0 },
+  "plans": [{ "file": "PLAN-01.md", "plan_id": "01", "wave": 1, "autonomous": true, "has_summary": false, "must_haves_count": 4, "depends_on": [] }],
+  "waves": { "wave_1": ["01", "02"] },
+  "branch_name": "main",
+  "git_clean": true
+}
+```
+
+### `init plan-phase <phase>`
+
+Everything a planner needs to start phase planning.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init plan-phase 3
+```
+
+**Output:** `researcher_model`, `planner_model`, `checker_model`, `config` (depth profile, features, planning settings), `phase` (num, dir, goal, depends_on), `existing_artifacts`, `workflow` flags.
+
+### `init quick <description>`
+
+Everything the quick skill needs: next task number, slug, directory path.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init quick "add search feature"
+```
+
+**Output:** `next_task_number`, `slug`, `dir`, `dir_name`, `timestamp`, `config` subset.
+
+### `init verify-work <phase>`
+
+Everything a verifier needs to start verification.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init verify-work 3
+```
+
+**Output:** `verifier_model`, `phase` info, `has_verification`, `prior_attempts`, `prior_status`, `summaries`.
+
+### `init resume`
+
+Detect interrupted state and suggest continuation.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init resume
+```
+
+**Output:** `state`, `auto_next`, `continue_here`, `active_skill`, `current_phase`, `progress`.
+
+### `init progress`
+
+All phases with status and completion data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
+```
+
+**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+
+---
+
+## State Mutation Extensions
+
+### `state patch <JSON>`
+
+Multi-field atomic STATE.md update. Updates all fields in a single pass.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+
+**Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
+
+### `state advance-plan`
+
+Increment current plan number in STATE.md and update progress percentage.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state advance-plan
+```
+
+**Output:** `{ "success": true, "previous_plan": 1, "current_plan": 2, "total_plans": 5, "progress_percent": 40 }`
+
+### `state record-metric [--duration Nm] [--plans-completed N]`
+
+Record session/execution metrics. Appends to HISTORY.md and updates last_activity.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state record-metric --duration 15m --plans-completed 3
+```
+
+**Output:** `{ "success": true, "duration_minutes": 15, "plans_completed": 3 }`

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

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/questioning.md -->
 # Deep Questioning Guide
 
 Techniques for understanding a user's project vision during `/pbr:begin`. The goal is to build a complete mental model of what needs to be built, not just a feature list.
@@ -213,3 +212,24 @@ See **[skills/shared/domain-probes.md](../shared/domain-probes.md)** for technol
 9. **DO NOT** lead the user toward a particular solution
 10. **DO NOT** forget to summarize and confirm understanding
 11. **DO NOT** ask what you already know — track what the user has stated and never re-ask it. If they said "I'm using React", do not later ask "Are you using a frontend framework?" If they said "PostgreSQL", do not ask "What database are you using?" Redundant questions waste exchanges and erode trust. Instead, build on what you know: "You mentioned React — are you using Next.js or plain CRA?"
+
+---
+
+## Dream Extraction Philosophy
+
+The goal of questioning is not to gather requirements — it's to extract the user's dream and make it buildable.
+
+### 4-Item Context Checklist
+Before planning can begin, you must know:
+1. **What** are we building? (concrete deliverable, not abstract concept)
+2. **Why** does it exist? (the problem it solves, not the tech it uses)
+3. **Who** is it for? (specific users, not "everyone")
+4. **What does done look like?** (observable outcomes, not technical milestones)
+
+### Conversation Rules
+- **Start open**: "Tell me about what you want to build"
+- **Follow energy**: When they light up about something, dig deeper there
+- **Challenge vagueness**: "You said 'user-friendly' — what does that mean specifically?"
+- **Know when to stop**: When you have the 4 items above, move to planning
+- **NEVER ask about technical experience**: It's irrelevant and condescending
+- **NEVER present a menu of options**: Open questions reveal more than multiple choice

package/plugins/cursor-pbr/references/verification-patterns.md

@@ -1,4 +1,3 @@
-<!-- canonical: ../../pbr/references/verification-patterns.md -->
 # Goal-Backward Verification Patterns
 
 Reference patterns for deriving verification criteria from goals. Used by the planner to create `<verify>` and `<done>` elements, and by the verifier to check phase completion.
@@ -197,3 +196,55 @@ Bad:  "Tests pass"
 Good: "All 5 auth middleware tests pass: valid token, expired token,
        missing token, malformed token, and correct user extraction"
 ```
+
+---
+
+## Wiring Verification Patterns
+
+4 concrete patterns for verifying components are actually connected, not just present.
+
+### Pattern 1: Component to API
+1. Find the fetch/axios call in the component
+2. Verify the call is NOT commented out
+3. Verify the response is assigned to state (not discarded)
+4. Verify error handling exists (try/catch or .catch)
+
+### Pattern 2: API to Database
+1. Find the database query in the route handler
+2. Verify `await` is present (not fire-and-forget)
+3. Verify the result is returned in the response (not discarded)
+4. Verify error cases return appropriate HTTP status codes
+
+### Pattern 3: Form to Handler
+1. Find the form's onSubmit handler
+2. Verify it calls an API function (not just preventDefault)
+3. Verify form validation runs before the API call
+4. Verify success/error feedback is shown to the user
+
+### Pattern 4: State to Render
+1. Find state variables (useState, store, etc.)
+2. Verify they appear in JSX/template via .map(), interpolation, or conditional rendering
+3. Verify loading/error states are rendered (not just success state)
+4. Verify empty state is handled (not just "no data" crash)
+
+### Quick Verification Checklists
+
+**Component Checklist (8 items):**
+- [ ] Component file exists and exports correctly
+- [ ] Props/types are defined (not `any`)
+- [ ] API calls use actual endpoints (not hardcoded data)
+- [ ] Loading state renders something meaningful
+- [ ] Error state renders something meaningful
+- [ ] Empty state renders something meaningful
+- [ ] User interactions trigger actual handlers
+- [ ] Component is imported and rendered in parent
+
+**API Route Checklist (8 items):**
+- [ ] Route file exists and exports handler
+- [ ] Route is registered in router/app
+- [ ] Request validation exists (body, params, query)
+- [ ] Database query uses parameterized inputs
+- [ ] Success response includes expected data shape
+- [ ] Error response includes status code and message
+- [ ] Authentication/authorization check exists if needed
+- [ ] Response matches what the frontend expects

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/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: