@sienklogic/plan-build-run 2.34.0 → 2.38.0

package/plugins/copilot-pbr/skills/health/SKILL.md

@@ -17,10 +17,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 +190,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 +204,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 +223,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/copilot-pbr/skills/import/SKILL.md

@@ -275,6 +275,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} ---
@@ -305,7 +312,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).
 
@@ -325,6 +340,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/copilot-pbr/skills/milestone/SKILL.md

@@ -486,6 +486,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}
 
@@ -505,20 +511,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/copilot-pbr/skills/plan/SKILL.md

@@ -3,6 +3,8 @@ name: plan
 description: "Create a detailed plan for a phase. Research, plan, and verify before building."
 ---
 
+**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.
@@ -135,6 +137,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.
 
 ```
@@ -221,8 +225,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)
@@ -336,6 +354,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:
@@ -346,6 +374,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)
@@ -372,6 +411,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:
@@ -463,6 +511,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/copilot-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/copilot-pbr/skills/review/SKILL.md

@@ -60,6 +60,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.
@@ -154,6 +156,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.
@@ -180,6 +192,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)
@@ -367,6 +390,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
@@ -382,6 +415,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)
@@ -562,6 +605,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/copilot-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:

package/plugins/copilot-pbr/skills/setup/SKILL.md

@@ -71,7 +71,15 @@ mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning
 
 **CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
 
-Create `.planning/config.json` with defaults:
+Before writing config.json, check for user-level defaults:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" config load-defaults
+```
+
+If user defaults exist (the output has keys like `mode`, `features`, etc.), inform the user: "Found your saved preferences from ~/.claude/pbr-defaults.json. These will be merged into your project config (project-specific settings take precedence)." Then deep-merge user defaults into the config below before writing.
+
+Create `.planning/config.json` with defaults (merged with user defaults if they exist):
 ```json
 {
   "version": 2,

package/plugins/copilot-pbr/skills/shared/context-budget.md

@@ -17,6 +17,16 @@ Every skill that spawns agents or reads significant content must follow these ru
 4. **Delegate** heavy work to agents — the orchestrator routes, it doesn't execute
 5. **Before spawning agents**: If you've already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider running `/pbr:pause` to checkpoint progress." Suggest pause proactively rather than waiting for compaction.
 
+## Context Degradation Awareness
+
+Quality degrades gradually before panic thresholds fire. Watch for these early warning signs:
+
+- **Silent partial completion** — agent claims task is done but implementation is incomplete. Self-check catches file existence but not semantic completeness. Always verify agent output meets the plan's must_haves, not just that files exist.
+- **Increasing vagueness** — agent starts using phrases like "appropriate handling" or "standard patterns" instead of specific code. This indicates context pressure even before budget warnings fire.
+- **Skipped steps** — agent omits protocol steps it would normally follow. If an agent's success criteria has 8 items but it only reports 5, suspect context pressure.
+
+When delegating to agents, the orchestrator cannot verify semantic correctness of agent output — only structural completeness. This is a fundamental limitation. Mitigate with must_haves.truths and spot-check verification.
+
 ## Customization
 
 Skills should add skill-specific rules below the reference line. Common skill-specific additions:

package/plugins/copilot-pbr/skills/shared/universal-anti-patterns.md

@@ -36,3 +36,9 @@ These rules prevent context rot -- quality degradation as the context window fil
 14. **Do not** suggest multiple next actions without clear priority -- one primary suggestion, alternatives listed secondary.
 15. **Do not** use `git add .` or `git add -A` -- stage specific files only.
 16. **Do not** include sensitive information (API keys, passwords, tokens) in planning documents or commits.
+
+## Error Recovery Rules (apply to every skill)
+
+17. **Git lock detection**: Before any git operation, if it fails with "Unable to create lock file", check for stale `.git/index.lock` and advise the user to remove it (do not remove automatically — another process may hold it legitimately).
+18. **Config fallback awareness**: `configLoad()` returns `null` silently on invalid JSON. If your skill depends on config values, check for null and warn the user: "config.json is invalid or missing — running with defaults. Run `/pbr:health` to diagnose."
+19. **Partial state recovery**: If STATE.md references a phase directory that doesn't exist, do not proceed silently. Warn the user and suggest `/pbr:health` to diagnose the mismatch.

package/plugins/copilot-pbr/skills/test/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: test
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+---
+
+**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by the plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**
+
+# /pbr:test — Post-Phase Test Generation
+
+You are the orchestrator for `/pbr:test`. This skill generates tests for code that was built WITHOUT TDD mode. It targets key files from completed phases and creates meaningful test coverage.
+
+## Context Budget
+
+Reference: `skills/shared/context-budget.md` for the universal orchestrator rules.
+
+Additionally for this skill:
+- **Delegate** all test writing to executor agents — never write test code in the main context
+- Read only SUMMARY.md frontmatter for `key_files` lists — do not read full summaries
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► GENERATING TESTS FOR PHASE {N}             ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+Where `{N}` is the phase number from `$ARGUMENTS`. Then proceed to Step 1.
+
+## Prerequisites
+
+- `.planning/config.json` exists
+- Phase has been built: SUMMARY.md files exist in `.planning/phases/{NN}-{slug}/`
+- Phase should NOT already have TDD coverage (check if `features.tdd_mode` is false in config — if TDD mode is enabled, warn user that tests should already exist and ask to proceed anyway)
+
+---
+
+## Argument Parsing
+
+Parse `$ARGUMENTS` according to `skills/shared/phase-argument-parsing.md`.
+
+| Argument | Meaning |
+|----------|---------|
+| `3` | Generate tests for phase 3 |
+| (no number) | Use current phase from STATE.md |
+
+---
+
+## Step 1 — Gather Context
+
+**CRITICAL: Run init command to load project state efficiently.**
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" init execute-phase {phase_number}
+```
+
+This returns STATE.md snapshot, phase plans, ROADMAP excerpt, and config — all in one call.
+
+## Step 2 — Detect Test Framework
+
+Scan the project root for test framework indicators:
+
+1. Check `package.json` for `jest`, `vitest`, `mocha`, `ava` in devDependencies
+2. Check for `pytest.ini`, `pyproject.toml` (with `[tool.pytest]`), `setup.cfg` (with `[tool:pytest]`)
+3. Check for `jest.config.*`, `vitest.config.*`, `.mocharc.*`
+4. Check for existing test directories: `tests/`, `test/`, `__tests__/`, `spec/`
+5. Check for existing test file patterns: `*.test.*`, `*.spec.*`, `test_*.py`
+
+If no test framework is detected, ask the user:
+
+Use AskUserQuestion:
+  question: "No test framework detected. Which should I use?"
+  header: "Framework"
+  options:
+    - label: "Jest"      description: "JavaScript/TypeScript testing (most common)"
+    - label: "Vitest"    description: "Vite-native testing (faster, ESM-friendly)"
+    - label: "pytest"    description: "Python testing framework"
+  multiSelect: false
+
+## Step 3 — Collect Target Files
+
+Read SUMMARY.md frontmatter from each plan in the phase to extract `key_files`:
+
+```bash
+node "${PLUGIN_ROOT}/scripts/pbr-tools.js" frontmatter .planning/phases/{NN}-{slug}/SUMMARY.md
+```
+
+Collect all `key_files` across all plans in the phase. Filter to only source files (exclude config, docs, assets). Group by:
+- **High priority**: Files with business logic, API endpoints, data models
+- **Medium priority**: Utility functions, helpers, middleware
+- **Low priority**: Config, types-only files, constants
+
+Present the file list to the user:
+
+Use AskUserQuestion:
+  question: "Found {N} source files from phase {P}. Generate tests for which?"
+  header: "Scope"
+  options:
+    - label: "High priority only"  description: "{X} files — business logic, APIs, models"
+    - label: "High + Medium"       description: "{Y} files — adds utilities and helpers"
+    - label: "All files"           description: "{Z} files — comprehensive coverage"
+  multiSelect: false
+
+## Step 4 — Generate Test Plans
+
+For each target file, create a lightweight test plan (NOT a full PBR PLAN.md — just a task list):
+
+```
+File: src/auth/login.js
+Tests to generate:
+  - Happy path: valid credentials return token
+  - Error: invalid password returns 401
+  - Error: missing email returns 400
+  - Edge: expired session handling
+Framework: jest
+Output: tests/auth/login.test.js
+```
+
+## Step 5 — Spawn Executor Agents
+
+**CRITICAL: Delegate ALL test writing to agents. Do NOT write test code in the main context.**
+
+For each target file (or batch of related files), spawn an executor agent:
+
+```
+Spawn agent_type: "pbr:executor"
+
+Task: Generate tests for the following file(s):
+
+<files_to_test>
+{file_path}: {brief description from SUMMARY}
+</files_to_test>
+
+<test_framework>
+{detected framework name and version}
+Existing test directory: {path}
+Test file naming: {pattern, e.g., *.test.js}
+</test_framework>
+
+<test_plan>
+{test plan from Step 4}
+</test_plan>
+
+Instructions:
+1. Read each source file to understand the implementation
+2. Write test files following the project's existing test patterns
+3. Each test file should cover: happy path, error cases, edge cases
+4. Use the project's existing mocking patterns if any exist
+5. Run the tests to verify they pass: {test command}
+6. Commit with format: test({phase}-tests): add tests for {file}
+```
+
+Spawn up to `parallelization.max_concurrent_agents` agents in parallel for independent files.
+
+## Step 6 — Verify and Report
+
+After all agents complete, check results:
+
+1. Glob for new test files created in this session
+2. Run the test suite to verify all new tests pass:
+   ```bash
+   {test_command}
+   ```
+3. Count: files tested, tests written, tests passing
+
+Display completion:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► TESTS GENERATED ✓                          ║
+╚══════════════════════════════════════════════════════════════╝
+
+Phase {N}: {X} test files created, {Y} tests passing
+
+Files tested:
+  - src/auth/login.js → tests/auth/login.test.js (8 tests)
+  - src/api/users.js → tests/api/users.test.js (12 tests)
+
+
+
+╔══════════════════════════════════════════════════════════════╗
+║  ▶ NEXT UP                                                   ║
+╚══════════════════════════════════════════════════════════════╝
+
+**Run coverage check** to see how much is covered
+
+`npm test -- --coverage`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:review {N}` — verify the full phase
+- `/pbr:continue` — execute next logical step
+
+
+```
+
+---
+
+## Anti-Patterns
+
+1. **DO NOT** write test code in the main orchestrator context — always delegate to executor agents
+2. **DO NOT** generate tests for files not listed in SUMMARY.md key_files — stay scoped to the phase
+3. **DO NOT** skip running the tests — always verify they pass before reporting success
+4. **DO NOT** generate trivial tests (testing getters/setters, testing constants) — focus on behavior
+5. **DO NOT** read full source files in the orchestrator — let the executor agents read them