@sienklogic/plan-build-run 2.34.0 → 2.37.0

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

@@ -281,6 +281,13 @@ NOTE: The pbr:plan-checker subagent type auto-loads the agent definition. Do NOT
 ```
 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} ---
@@ -311,7 +318,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).
 
@@ -331,6 +346,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/pbr/skills/milestone/SKILL.md

@@ -491,6 +491,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}
 
@@ -510,20 +516,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/pbr/skills/plan/SKILL.md

@@ -139,6 +139,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 subagent prompts — include paths and one-line descriptions, NOT full file bodies. Agents have the Read tool and will pull file contents on-demand.
 
 ```
@@ -232,8 +234,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 Task() 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)
@@ -344,7 +360,9 @@ Task({
   prompt: <planning prompt>
 })
 
-NOTE: The pbr:planner subagent type auto-loads the agent definition. Do NOT inline it.
+NOTE: The pbr:planner subagent type auto-loads the agent definition.
+
+After planner completes, check for completion markers: `## PLANNING COMPLETE`, `## PLANNING FAILED`, or `## PLANNING INCONCLUSIVE`. Route accordingly. Do NOT inline it.
 ```
 
 **Path resolution**: Before constructing the agent prompt, resolve `${CLAUDE_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.
@@ -359,6 +377,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:
@@ -369,6 +397,17 @@ After the planner returns, read the plan files it created to extract counts. Dis
 
 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)
@@ -402,6 +441,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:
@@ -492,7 +540,9 @@ Use AskUserQuestion (pattern: approve-revise-abort from `skills/shared/gate-prom
   4. Update the `Plans Complete` column to `0/{N}` where N = number of plan files just created
   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`
+- Update STATE.md via CLI **(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 ${CLAUDE_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: `Skill({ skill: "pbr:build", args: "{N}" })`. This continues the build→review→plan→build cycle automatically.
 - **Otherwise:** Suggest next action: `/pbr:build {N}`
 

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

@@ -45,6 +45,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."
@@ -168,9 +170,17 @@ Display to the user: `◐ Spawning executor...`
 
 Spawn a `Task(subagent_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}
@@ -193,6 +203,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/pbr/skills/review/SKILL.md

@@ -64,6 +64,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.
@@ -164,6 +166,7 @@ Spawn a verifier Task() to run three-layer checks:
 ```
 Task({
   subagent_type: "pbr:verifier",
+  // After verifier completes, check for: ## VERIFICATION COMPLETE
   prompt: <verifier prompt>
 })
 ```
@@ -174,6 +177,16 @@ Task({
 
 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.
@@ -200,6 +213,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)
@@ -395,6 +419,16 @@ Task({
 
 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
@@ -417,6 +451,16 @@ Task({
 
 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)
@@ -601,6 +645,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/pbr/skills/scan/SKILL.md

@@ -126,6 +126,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 |
@@ -145,6 +153,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:

package/plugins/pbr/templates/SUMMARY-complex.md.tmpl

@@ -0,0 +1,95 @@
+# SUMMARY-complex.md Template
+
+> Use when: decisions were made OR fileCount > 6
+> Referenced by: executor agent (complex plans, architectural work)
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+subsystem: "{main subsystem affected}"
+tags:
+  - "{tag1}"
+requires:
+  - "{plan_id}: {artifact}"
+provides:
+  - "{export/artifact description}"
+affects:
+  - "{affected area 1}"
+tech_stack:
+  - "{technology used}"
+key_files:
+  - "{file1}: {what it does}"
+key_decisions:
+  - "{decision 1}: {rationale}"
+patterns:
+  - "{pattern used}: {where}"
+metrics:
+  duration_minutes: {n}
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+  files_created: {n}
+  files_modified: {n}
+deferred:
+  - "{thing noticed but not implemented}"
+self_check_failures:
+  - "{failure description}"
+architecture_notes:
+  - "{key architectural decision and why}"
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{2-3 paragraph description of what was accomplished}
+
+## Architecture Decisions
+
+| Decision | Options Considered | Chosen | Rationale |
+|----------|-------------------|--------|-----------|
+| {decision} | {opt1}, {opt2} | {chosen} | {why} |
+
+## Task Results
+
+| Task | Status | Commit | Files | Verify |
+|------|--------|--------|-------|--------|
+| {task_id}: {name} | done | {hash} | {count} | passed |
+
+## Key Implementation Details
+
+{Important details about HOW things were implemented}
+
+## Integration Points
+
+{How this plan connects to other plans - imports, exports, shared state}
+
+## Known Issues
+
+{Issues discovered during execution}
+
+## Dependencies Provided
+
+{What other plans can now depend on}
+
+## Deferred Items
+
+{Items noticed but intentionally deferred - with rationale}
+```
+
+## Selection Heuristic
+
+Use this template when ANY of the following are true:
+- Key architectural decisions were made during execution
+- Total files created or modified > 6
+- Deviations from the plan occurred
+- Multiple integration points were established
+- The plan touched shared infrastructure or patterns

package/plugins/pbr/templates/SUMMARY-minimal.md.tmpl

@@ -0,0 +1,48 @@
+# SUMMARY-minimal.md Template
+
+> Use when: taskCount <= 2 AND fileCount <= 3
+> Referenced by: executor agent (quick tasks, simple plans)
+
+## Frontmatter (YAML)
+
+```yaml
+---
+phase: "{phase_id}"
+plan: "{plan_id}"
+status: "complete"           # complete | partial | checkpoint
+requires: []
+provides:
+  - "{export/artifact description}"
+key_files:
+  - "{file1}: {what it does}"
+deferred: []
+metrics:
+  tasks_completed: {n}
+  tasks_total: {n}
+  commits: {n}
+---
+```
+
+## Body Structure
+
+```markdown
+# Plan Summary: {plan_id}
+
+## What Was Built
+
+{1 paragraph description}
+
+## Task Results
+
+| Task | Status | Commit | Files |
+|------|--------|--------|-------|
+| {task_id}: {name} | done | {hash} | {count} |
+```
+
+## Selection Heuristic
+
+Use this template when ALL of the following are true:
+- Total tasks in the plan <= 2
+- Total files created or modified <= 3
+- No key decisions were made
+- No deviations from the plan occurred