@sienklogic/plan-build-run 2.12.0 → 2.12.1

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

@@ -1,7 +1,7 @@
 ---
 name: status
 description: "Show current project status and suggest what to do next."
-allowed-tools: Read, Glob, Grep, AskUserQuestion
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion
 ---
 
 **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.**
@@ -18,12 +18,17 @@ allowed-tools: Read, Glob, Grep, AskUserQuestion
 
 Then proceed to Step 1.
 
-# /pbr:status — Project Status Dashboard
+# /pbr:progress — Project Status Dashboard
 
 You are running the **status** skill. Your job is to read the project state and present a clear, actionable status dashboard. You suggest the most logical next action based on where the project is.
 
 This skill runs **inline** and is **read-only** — it never modifies any files.
 
+## References
+
+- `references/questioning.md` — Questioning philosophy (for routing intelligence)
+- `references/ui-brand.md` — Status symbols, banners, progress display format
+
 ---
 
 ## Core Principle
@@ -36,17 +41,15 @@ This skill runs **inline** and is **read-only** — it never modifies any files.
 
 ### Step 1: Read Project State
 
-**Tooling shortcut**: Instead of parsing multiple files manually, you can run:
-```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
-```
-and
+**CRITICAL — STOP. You MUST run this CLI command FIRST. Do NOT skip it. Do NOT read files manually instead.**
+
 ```bash
-node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js status render
 ```
-These return structured JSON with config, state, roadmap, and filesystem-verified progress. Falls back gracefully if the script is missing — parse files manually in that case.
 
-Read the following files (skip any that don't exist):
+This returns a **complete, deterministic JSON object** with ALL project status: milestones, phases, progress bar, routing recommendations, todos, notes, quick tasks, paused work, documents, and warnings. Parse the JSON and proceed directly to Step 4 (Display) using the structured data.
+
+**If and ONLY if the CLI command fails** (non-zero exit or invalid JSON), fall back to reading files manually:
 
 1. **`.planning/config.json`** — Project settings
    - If this doesn't exist, display:
@@ -57,7 +60,7 @@ Read the following files (skip any that don't exist):
 
      No Plan-Build-Run project found.
 
-     **To fix:** Run `/pbr:begin` to start a new project, or `/pbr:scan` to analyze an existing codebase.
+     **To fix:** Run `/pbr:new-project` to start a new project, or `/pbr:map-codebase` to analyze an existing codebase.
      ```
    - Stop here if no project found.
 
@@ -73,6 +76,63 @@ Read the following files (skip any that don't exist):
 5. **`.planning/REQUIREMENTS.md`** — Requirements (if exists)
    - Extract: requirement completion status if tracked
 
+### Step 1b: Read Local LLM Stats (advisory — skip on any error)
+
+After loading config.json, check `local_llm.enabled`. If `true`:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm status
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm metrics
+```
+
+Parse both JSON responses. Capture:
+
+- `status.model` — model name
+- `metrics.total_calls` — lifetime total calls
+- `metrics.tokens_saved` — lifetime frontier tokens saved
+- `metrics.cost_saved_usd` — lifetime cost estimate
+- `metrics.avg_latency_ms` — lifetime average latency
+
+Also run session-scoped metrics if `.planning/.session-start` exists:
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js llm metrics --session <content-of-.session-start>
+```
+
+If `local_llm.enabled` is `false` or commands fail, skip this step silently.
+
+### Step 1c: Read Context Budget (advisory — skip on any error)
+
+Run:
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js context-triage
+```
+
+Parse the JSON response. Capture:
+- `tier` — one of PEAK / GOOD / DEGRADING / POOR / CRITICAL
+- `percentage` — numeric 0-100 (or null if unavailable)
+- `recommendation` — PROCEED / CHECKPOINT / COMPACT
+
+Store these for use in Step 4 display and Step 5 routing.
+
+6. **`.planning/STATE.md` `velocity` frontmatter field** (if exists)
+   - Note: velocity metrics object with plans_executed, avg_duration_minutes, trend
+   - Display in status dashboard if present
+
+6b. **`.planning/STATE.md` session continuity fields** (if exists)
+   - Extract: `session_last`, `session_stopped_at`, `session_resume` from frontmatter
+   - Display last session info if present
+
+7. **`.planning/PROJECT.md` ## Context section** (if exists)
+   - Note: locked decisions, user constraints, deferred ideas (consolidated from legacy CONTEXT.md)
+   - **Backwards compat:** If PROJECT.md has no ## Context section but `.planning/CONTEXT.md` exists, read from the legacy file
+
+### Step 1d: Check Project Documents
+
+Check existence of the core project-level documents and record their status for Step 4 display:
+- `.planning/PROJECT.md` — exists or not (includes ## Context section for locked decisions)
+- `.planning/REQUIREMENTS.md` — exists or not
+
 ### Step 2: Scan Phase Directories
 
 For each phase listed in ROADMAP.md:
@@ -87,15 +147,21 @@ For each phase listed in ROADMAP.md:
 
 3. Calculate phase status:
 
-| Condition | Status |
-|-----------|--------|
-| No directory | Not started |
-| Directory exists, no plans | Discussed only |
-| Plans exist, no summaries | Planned (ready to build) |
-| Some summaries, not all | Building (in progress) |
-| All summaries exist | Built (ready to review) |
-| VERIFICATION.md exists, status=passed | Verified (complete) |
-| VERIFICATION.md exists, status=gaps_found | Needs fixes |
+| Condition | Status | Status Value |
+|-----------|--------|-------------|
+| No directory | Not started | `not_started` |
+| Directory exists, CONTEXT.md only | Discussed | `discussed` |
+| Directory exists, no plans, ready for planning | Ready to plan | `ready_to_plan` |
+| Planning in progress (planner running) | Planning | `planning` |
+| Plans exist, no summaries | Planned | `planned` |
+| Plans exist, ready to execute | Ready to execute | `ready_to_execute` |
+| Some summaries, not all | Building (in progress) | `building` |
+| All summaries exist | Built (ready to review) | `built` |
+| Some plans completed with issues | Partial | `partial` |
+| VERIFICATION.md exists, status=passed | Verified | `verified` |
+| VERIFICATION.md exists, status=gaps_found | Needs fixes | `needs_fixes` |
+| Phase fully done | Complete | `complete` |
+| Phase explicitly skipped | Skipped | `skipped` |
 
 4. Calculate progress percentage:
    - Count total plans across all phases
@@ -114,7 +180,7 @@ Warning: STATE.md is {N} lines (limit: 150). Run any build/review command to aut
 - Does the plan count match? If not: `Warning: STATE.md says {X} plans but filesystem has {Y}.`
 - Does the status match? If STATE.md says "verified" but no `VERIFICATION.md` exists: `Warning: STATE.md says "verified" but no VERIFICATION.md found.`
 
-If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
+If any discrepancy found, add: `Run /pbr:resume-work to auto-reconcile STATE.md.`
 
 ### Step 3: Check for Special Conditions
 
@@ -136,7 +202,7 @@ If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
 - **Dependency fingerprint check**: For each planned phase with `dependency_fingerprints` in plan frontmatter:
   1. Compare the fingerprints against current dependency SUMMARY.md files
   2. If any fingerprint is stale (dependency was re-built after the plan was created):
-     - Flag: "WARN: Phase {N} plans may be stale — dependency phase {M} was re-built since planning. Consider re-planning with `/pbr:plan {N}`."
+     - Flag: "WARN: Phase {N} plans may be stale — dependency phase {M} was re-built since planning. Consider re-planning with `/pbr:plan-phase {N}`."
 
 #### Active Debug Sessions
 - Check `.planning/debug/` for files with `status: active`
@@ -146,6 +212,18 @@ If any discrepancy found, add: `Run /pbr:resume to auto-reconcile STATE.md.`
 - Check `.planning/todos/pending/` for pending todo files
 - Count and summarize if any exist
 
+#### Critical Path
+Identify the single next-blocking item — the one phase or plan whose completion unblocks the most downstream work.
+
+Logic:
+1. From ROADMAP.md dependency graph, find all phases that are NOT yet verified.
+2. For each unverified phase, count how many other unverified phases list it in `depends_on` (direct + transitive).
+3. The phase with the highest downstream dependent count is the critical-path phase.
+4. If all unverified phases are independent (no dependencies between them), the critical path is the current phase from STATE.md.
+5. Within the critical-path phase, the critical-path plan is the lowest-numbered plan without a SUMMARY.md.
+
+Store: `criticalPhase` (number + name), `criticalPlan` (plan ID or null if phase not yet planned), `criticalCount` (number of downstream phases blocked).
+
 #### Quick Notes
 - Check `.planning/notes/` directory for note files (individual `.md` files)
 - Count active notes (files where frontmatter does NOT contain `promoted: true`)
@@ -171,6 +249,34 @@ Phase Status:
 | 2. {name} | {status indicator} {status text} | {completed}/{total} | {percentage}% |
 | ...
 
+**Project documents:**
+| File | Status |
+|------|--------|
+| PROJECT.md | {exists / not found -- run /pbr:new-project} (includes ## Context section) |
+| REQUIREMENTS.md | {exists / not found -- run /pbr:new-project} |
+
+{If STATE.md frontmatter contains a `velocity` field (JSON object), display velocity metrics in a single compact line:}
+Velocity:  {velocity.plans_executed} plans | avg {velocity.avg_duration_minutes} min/plan | trend: {velocity.trend}
+Total:     {total_plans} plans across all phases
+{If no `velocity` field exists in STATE.md frontmatter, skip this block entirely — do not show "No metrics".}
+
+{If STATE.md frontmatter contains `session_last`, display session continuity:}
+Last session: {session_last}{if session_stopped_at:} — stopped at: {session_stopped_at}{/if}
+{If no `session_last` field exists, skip this block entirely.}
+
+{If context tier is DEGRADING, POOR, or CRITICAL:}
+⚠ Context: {percentage}% used ({tier}) — {recommendation_text}
+  Run `/compact` to reclaim context before spawning more agents.
+
+Where `{recommendation_text}` maps:
+- DEGRADING → "quality may degrade on complex agents"
+- POOR → "context window is filling up"
+- CRITICAL → "STOP — compact before continuing"
+
+{If criticalPhase is identified AND criticalCount >= 1 AND there are 2+ unverified phases with dependencies:}
+Critical Path: Phase {N} — {phase name}{, Plan {criticalPlan} is next} [BLOCKING {criticalCount} downstream phase(s)]
+{Else: omit — not meaningful when only one phase remains or no inter-phase dependencies exist}
+
 {If blockers exist:}
 Blockers:
 - {blocker 1}
@@ -180,24 +286,34 @@ Blockers:
 Blockers: None
 
 {If paused work:}
-Paused: Phase {N} has a checkpoint at plan {M}. Run `/pbr:resume` to continue.
+Paused: Phase {N} has a checkpoint at plan {M}. Run `/pbr:resume-work` to continue.
 
 {If verification gaps:}
-Gaps: Phase {N} verification found {count} gaps. Run `/pbr:plan {N} --gaps` to address.
+Gaps: Phase {N} verification found {count} gaps. Run `/pbr:plan-phase {N} --gaps` to address.
 
 {If cross-phase re-planning needed:}
-Warning: Phase {N} was planned before Phase {M} was built. Consider re-planning with `/pbr:plan {N}`.
+Warning: Phase {N} was planned before Phase {M} was built. Consider re-planning with `/pbr:plan-phase {N}`.
 
 {If active debug sessions:}
 Debug: {count} active session(s). Run `/pbr:debug` to continue.
 
 {If pending todos:}
-Todos: {count} pending. Run `/pbr:todo list` to see them.
+Todos: {count} pending. Run `/pbr:check-todos` to see them.
 
 {If notes exist:}
 Notes: {count} quick capture(s). `/pbr:note list` to review.
+
+{If local_llm.enabled AND total_calls > 0:}
+Local LLM: enabled ({model}, avg {avg_ms}ms)
+This session: {session_calls} calls, ~{session_tokens} frontier tokens saved
+Lifetime: {total_calls} calls, ~{tokens_saved} tokens saved (~{cost_str} at $3/M)
+
+{If local_llm.enabled AND total_calls == 0:}
+Local LLM: enabled ({model}) — no calls yet this session
 ```
 
+The Local LLM block is **advisory only** — it never affects the routing decision or Next Up suggestion.
+
 ### Progress Bar
 
 Generate a 20-character progress bar:
@@ -215,15 +331,16 @@ Use Unicode block characters:
 
 ### Status Indicators
 
-Use indicators from `references/ui-formatting.md`:
+Use the standardized symbol set from `references/ui-brand.md`:
 
 | Status | Indicator |
 |--------|-----------|
-| Complete/Verified | checkmark |
-| In Progress | half-filled circle |
-| Not started | empty circle |
-| Needs fixes | warning triangle |
-| Blocked | blocked symbol |
+| Complete/Verified | `✓` |
+| In Progress | `◆` |
+| Not started | `○` |
+| Needs fixes / Warning | `⚠` |
+| Failed / Blocked | `✗` |
+| Auto-approved | `⚡` |
 
 ### Step 5: Smart Routing
 
@@ -233,36 +350,61 @@ Based on the project state, suggest the single most logical next action:
 
 ```
 1. Is there paused work (.continue-here.md)?
-   YES → "Resume your work: `/pbr:resume`"
+   YES → "Resume your work: `/pbr:resume-work`"
 
 2. Is there a verification with gaps?
-   YES → "Fix verification gaps: `/pbr:plan {N} --gaps`"
+   YES → "Fix verification gaps: `/pbr:plan-phase {N} --gaps`"
 
 3. Is the current phase planned but not built?
-   YES → "Build the current phase: `/pbr:build {N}`"
+   YES → "Build the current phase: `/pbr:execute-phase {N}`"
 
 4. Is the current phase built but not reviewed?
-   YES → "Review what was built: `/pbr:review {N}`"
+   YES → Read `workflow.validate_phase` from config.json (default: `true`).
+     IF true  → "Validate coverage gaps: `/pbr:validate-phase {N}`"
+     IF false → "Review what was built: `/pbr:verify-work {N}`"
 
 5. Is the current phase verified (complete)?
    YES → Is there a next phase?
      YES → Was next phase already planned?
        YES → Does it need re-planning? (dependency phase changed)
-         YES → "Re-plan with updated context: `/pbr:plan {N+1}`"
-         NO → "Build the next phase: `/pbr:build {N+1}`"
-       NO → "Plan the next phase: `/pbr:plan {N+1}`"
-     NO → Check for existing `*-MILESTONE-AUDIT.md` in `.planning/`:\n       IF audit passed → "All phases complete and audited! `/pbr:milestone complete` to archive and tag."\n       IF audit has gaps → "Audit found gaps. `/pbr:milestone gaps` to address them."\n       IF no audit → "All phases complete! `/pbr:milestone audit` to verify cross-phase integration (recommended), then `/pbr:milestone complete`."
+         YES → "Re-plan with updated context: `/pbr:plan-phase {N+1}`"
+         NO → "Build the next phase: `/pbr:execute-phase {N+1}`"
+       NO → "Plan the next phase: `/pbr:plan-phase {N+1}`"
+     NO → Check for existing `*-MILESTONE-AUDIT.md` in `.planning/`:\n       IF audit passed → "All phases complete and audited! `/pbr:complete-milestone` to archive and tag."\n       IF audit has gaps → "Audit found gaps. `/pbr:plan-milestone-gaps` to address them."\n       IF no audit → "All phases complete! `/pbr:audit-milestone` to verify cross-phase integration (recommended), then `/pbr:complete-milestone`."
 
 6. Is the current phase not started?
    YES → Has it been discussed?
-     YES → "Plan this phase: `/pbr:plan {N}`"
-     NO → "Start with a discussion: `/pbr:discuss {N}` or jump to `/pbr:plan {N}`"
+     YES → "Plan this phase: `/pbr:plan-phase {N}`"
+     NO → "Start with a discussion: `/pbr:discuss-phase {N}` or jump to `/pbr:plan-phase {N}`"
 
 7. Active debug sessions?
    YES → "Continue debugging: `/pbr:debug`"
 
-8. Nothing active?
-   → "Start your project: `/pbr:begin`"
+8. Pending notes to review?
+   YES → "Review notes: `/pbr:note list`"
+
+9. Nothing active?
+   → "Start your project: `/pbr:new-project`"
+
+Autonomous mode suggestion (conditional):
+After the primary next-action is determined, check the number of pending phases:
+- Count all phases in ROADMAP.md whose status is `not_started`, `discussed`, `ready_to_plan`, or `planned`
+- If count >= 2 AND `config.mode` is NOT `autonomous`:
+  Display this advisory block below the primary next-action suggestion:
+
+  ─────────────────────────────────────────────
+  Multiple phases ready: {count} phases pending.
+  Run all phases hands-free with `/pbr:autonomous`
+  ─────────────────────────────────────────────
+
+- If count < 2 OR config.mode is already `autonomous`: skip — do not display.
+
+Other skills available for routing:
+- `/pbr:explore` — open-ended idea exploration
+- `/pbr:note` — zero-friction idea capture
+- `/pbr:debug` — systematic debugging
+- `/pbr:import` — import external plans
+- `/pbr:autonomous` — run multiple phases hands-free (when multiple phases are pending)
 ```
 
 **If only one reasonable next action exists**, present it with branded routing:
@@ -278,7 +420,10 @@ Based on the project state, suggest the single most logical next action:
 
 `{suggested command}`
 
-<sub>`/clear` first → fresh context window</sub>
+{If context percentage > 40% OR tier is DEGRADING/POOR/CRITICAL:}
+<sub>`/clear` first → fresh context window ({percentage}% used)</sub>
+{Else: omit the /clear hint entirely}
+{If `percentage` is null (no context data): omit the hint}
 
 
 ```
@@ -304,12 +449,14 @@ Build options dynamically from the decision tree results. Always include "Someth
 
 ---
 
+Reference: `skills/shared/error-reporting.md` for branded error output patterns.
+
 ## Edge Cases
 
 ### No `.planning/` directory at all
 - Display: "No Plan-Build-Run project found."
-- Suggest: `/pbr:begin` to start a new project
-- Also mention: `/pbr:scan` if there's an existing codebase to analyze first
+- Suggest: `/pbr:new-project` to start a new project
+- Also mention: `/pbr:map-codebase` if there's an existing codebase to analyze first
 
 ### STATE.md exists but is outdated
 - STATE.md may not reflect the actual file system state
@@ -320,11 +467,11 @@ Build options dynamically from the decision tree results. Always include "Someth
 ### All phases complete
 - Celebrate briefly: "All phases complete!"
 - Check for existing audit report: look for `*-MILESTONE-AUDIT.md` in `.planning/`
-  - **If audit exists and passed:** Suggest `/pbr:milestone complete` to archive (audit already done)
-  - **If audit exists with gaps:** Suggest `/pbr:milestone gaps` to address issues
-  - **If no audit exists:** Suggest `/pbr:milestone audit` to verify cross-phase integration (recommended first)
-- Then: `/pbr:milestone complete` to archive the milestone and tag it
-- Or: `/pbr:milestone new` to start the next set of features
+  - **If audit exists and passed:** Suggest `/pbr:complete-milestone` to archive (audit already done)
+  - **If audit exists with gaps:** Suggest `/pbr:plan-milestone-gaps` to address issues
+  - **If no audit exists:** Suggest `/pbr:audit-milestone` to verify cross-phase integration (recommended first)
+- Then: `/pbr:complete-milestone` to archive the milestone and tag it
+- Or: `/pbr:new-milestone` to start the next set of features
 
 ### ROADMAP.md has phases but no phase directories
 - This is normal for future phases
@@ -352,9 +499,10 @@ This skill should be fast. It's a status check, not an analysis.
 - Cache nothing (always read fresh state)
 
 **DO NOT:**
+
 - Read full SUMMARY.md contents (frontmatter is enough)
 - Read plan file contents (just check existence)
-- Run any Bash commands
+- Run Bash commands except for Step 1b (`pbr-tools llm` calls only when `local_llm.enabled: true`) and Step 1c (`pbr-tools context-triage`, always run but skip on error)
 - Modify any files
 - Spawn any Task agents
 

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

@@ -0,0 +1,254 @@
+---
+name: test
+description: "Generate tests for completed phase code. Detects test framework and targets key files."
+allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
+argument-hint: "<phase-number>"
+---
+
+**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: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.
+Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.
+
+Additionally for this skill:
+- **Delegate** all test writing to executor subagents — 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`.
+
+**CRITICAL — DO NOT SKIP: Set active skill.** Write `.planning/.active-skill` with content `test`.
+
+Then proceed to Step 1.
+
+## Prerequisites
+
+- `.planning/config.json` exists
+- Phase has been built: SUMMARY.md files exist in `.planning/phases/{NN}-{slug}/`
+- If no SUMMARY.md files exist in the phase directory, display error and exit. Do not proceed without build output.
+- 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 "${CLAUDE_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.
+
+The init command returns `files_to_read` context. Ensure SUMMARY.md files are read before spawning test agents.
+
+## 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 "${CLAUDE_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 subagents. Do NOT write test code in the main context.**
+
+For each target file (or batch of related files), spawn an executor agent:
+
+```
+Spawn subagent_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 quality gate** to check for requirement-to-test gaps
+
+`/pbr:validate-phase {N}`
+
+**Run coverage check** to see how much is covered
+
+`npm test -- --coverage`
+
+<sub>`/clear` first → fresh context window</sub>
+
+
+
+**Also available:**
+- `/pbr:verify-work {N}` — verify the full phase
+- `/pbr:continue` — execute next logical step
+
+
+```
+
+**Clear active skill:** Delete `.planning/.active-skill`.
+
+---
+
+## Step 7 — Update State
+
+Reference: `skills/shared/state-update.md` for state update patterns.
+
+Update STATE.md `last_activity`: "Tests generated for phase {N} ({X} files, {Y} tests)"
+
+---
+
+## Step 8 — Commit
+
+Reference: `skills/shared/commit-planning-docs.md` for the commit pattern.
+
+If `planning.commit_docs` is true in config.json, commit test files:
+
+```text
+test({N}-tests): add tests for phase {N} ({X} test files)
+```
+
+---
+
+## 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
+
+---
+
+## Error Handling
+
+Reference: `skills/shared/error-reporting.md` for error output patterns.
+
+If test framework detection fails or no `key_files` found, display branded error and clear `.planning/.active-skill`.