@sienklogic/plan-build-run 2.11.0 → 2.12.1

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

@@ -1,10 +1,10 @@
 ---
 name: setup
-description: "Onboarding wizard. Initialize project, select models, verify setup."
+description: "Reconfigure an existing Plan-Build-Run project (models, features, CLAUDE.md)."
 allowed-tools: Read, Write, Bash, Glob, 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.**
+**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 tokens. Begin executing Step 1 immediately.**
 
 ## Step 0 — Immediate Output
 
@@ -12,190 +12,56 @@ allowed-tools: Read, Write, Bash, Glob, AskUserQuestion
 
 ```
 ╔══════════════════════════════════════════════════════════════╗
-║  PLAN-BUILD-RUN ► SETUP                                      ║
+║  PLAN-BUILD-RUN ► RECONFIGURE                                ║
 ╚══════════════════════════════════════════════════════════════╝
 ```
 
 Then proceed to Step 1.
 
-# /pbr:setup — Plan-Build-Run Setup Wizard
+# /pbr:setup — Plan-Build-Run Reconfigure
 
-You are running the **setup** skill. This is an interactive onboarding wizard that guides users through Plan-Build-Run project setup. Use AskUserQuestion at each step for clear choices.
+You are running the **setup** skill in **reconfigure mode**. This wizard lets existing Plan-Build-Run projects change model profiles, workflow features, and CLAUDE.md integration. It does NOT re-initialize or overwrite project state.
 
 ---
 
-## Step 1: Detect Project State — Idempotency Guard
+## Step 1: Detect Project State
 
-Check if `.planning/` directory exists in the current working directory.
-
-**If `.planning/` exists**:
-- Check for existing core files: `STATE.md`, `ROADMAP.md`, `config.json`
-- If ANY of these exist, present a checkpoint:
-
-  Use AskUserQuestion:
-    question: "Existing project detected with {list of found files}. How should we proceed?"
-    header: "Setup"
-    options:
-      - label: "Resume"       description: "Keep existing .planning/ and review configuration (recommended)"
-      - label: "Reset"        description: "Archive current .planning/ to .planning.bak/ and start fresh"
-      - label: "Abort"        description: "Cancel setup — keep everything as-is"
-
-  - If "Resume": Tell the user: "Keeping existing project. Reviewing configuration." Skip to Step 3 (model selection)
-  - If "Reset": Run `mv .planning .planning.bak` (creating a backup), then proceed with fresh setup below
-  - If "Abort": Display "Setup cancelled. Run `/pbr:status` to see current project state." and stop
-
-- If `.planning/` exists but has NONE of the core files (empty or only has subdirs):
-  - Tell the user: "Found empty .planning/ directory. Proceeding with initialization."
-  - Continue to fresh setup below
-
-**If `.planning/` does NOT exist**:
-- Ask the user:
+Check if `.planning/config.json` exists.
 
+**If `.planning/config.json` does NOT exist:**
+Display:
 ```
-AskUserQuestion:
-  question: "No Plan-Build-Run project found. Would you like to initialize one?"
-  header: "Initialize"
-  options:
-    - label: "Yes, initialize here"
-      description: "Creates .planning/ directory with default config, STATE.md, and ROADMAP.md"
-    - label: "No, just exploring"
-      description: "Exit the wizard — you can run /pbr:begin later for full project setup"
-```
-
-If "No", display: "Run `/pbr:begin` when you're ready to start a project. It includes deep requirements gathering and roadmap creation." Then stop.
-
-If "Yes", create the minimal `.planning/` structure:
+No Plan-Build-Run project found in this directory.
 
-**CRITICAL: Create .planning/ directory structure NOW. Do NOT skip this step.**
+/pbr:setup is for reconfiguring existing projects.
+To start a new project, run: /pbr:new-project
 
-```bash
-mkdir -p .planning/phases .planning/todos/pending .planning/todos/done .planning/logs .planning/research
+/pbr:new-project includes everything /pbr:setup used to do, plus deep requirements gathering and roadmap creation.
 ```
+Stop. Do not proceed further.
 
-**CRITICAL: Write .planning/config.json NOW. Do NOT skip this step.**
-
-Create `.planning/config.json` with defaults:
-```json
-{
-  "version": 2,
-  "context_strategy": "aggressive",
-  "mode": "interactive",
-  "depth": "standard",
-  "features": {
-    "structured_planning": true,
-    "goal_verification": true,
-    "integration_verification": true,
-    "context_isolation": true,
-    "atomic_commits": true,
-    "session_persistence": true,
-    "research_phase": true,
-    "plan_checking": true,
-    "tdd_mode": false,
-    "status_line": true,
-    "auto_continue": false,
-    "auto_advance": false,
-    "team_discussions": false,
-    "inline_verify": false
-  },
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "sonnet"
-  },
-  "parallelization": {
-    "enabled": true,
-    "plan_level": true,
-    "task_level": false,
-    "max_concurrent_agents": 3,
-    "min_plans_for_parallel": 2,
-    "use_teams": false
-  },
-  "planning": {
-    "commit_docs": true,
-    "max_tasks_per_plan": 3,
-    "search_gitignored": false
-  },
-  "git": {
-    "branching": "none",
-    "commit_format": "{type}({phase}-{plan}): {description}",
-    "phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
-    "milestone_branch_template": "plan-build-run/{milestone}-{slug}",
-    "mode": "enabled"
-  },
-  "gates": {
-    "confirm_project": true,
-    "confirm_roadmap": true,
-    "confirm_plan": true,
-    "confirm_execute": false,
-    "confirm_transition": true,
-    "issues_review": true
-  },
-  "safety": {
-    "always_confirm_destructive": true,
-    "always_confirm_external_services": true
-  }
-}
-```
-
-**CRITICAL: Write .planning/STATE.md NOW. Do NOT skip this step.**
-
-Create `.planning/STATE.md`:
-```markdown
----
-version: 2
-current_phase: 0
-total_phases: 0
-status: "initialized"
-progress_percent: 0
-last_activity: "{today's date}"
-last_command: "/pbr:setup"
-blockers: []
----
-# Project State
-
-## Current Position
-Phase: 0 of 0
-Status: initialized
-
-Plan-Build-Run project initialized via /pbr:setup. Run /pbr:begin to start requirements gathering and roadmap creation.
-```
+**If `.planning/config.json` exists:**
+- Read `.planning/config.json`
+- Display the current settings summary:
+  ```
+  Current configuration:
+  - Model profile: {derived from models block — balanced/quality/budget or custom}
+  - Depth: {depth}
+  - Mode: {mode}
+  - Auto-continue: {features.auto_continue}
+  - TDD mode: {features.tdd_mode}
+  - Git branching: {git.branching}
+  ```
+- Proceed to Step 2.
 
 ---
 
-## Step 2: Project Type (new projects only)
+## Step 2: Model Selection
 
-```
-AskUserQuestion:
-  question: "What kind of project is this?"
-  header: "Project type"
-  options:
-    - label: "Greenfield"
-      description: "Starting from scratch — full planning cycle recommended"
-    - label: "Existing codebase"
-      description: "Adding Plan-Build-Run to an existing project — run /pbr:scan first"
-    - label: "Prototype/experiment"
-      description: "Quick iteration — lighter workflow with fewer gates"
-```
-
-Based on selection:
-- **Greenfield**: Keep defaults (full gates, structured planning)
-- **Existing codebase**: Suggest running `/pbr:scan` after setup to map the codebase
-- **Prototype**: Set `depth: "quick"`, disable `gates.verification`, disable `gates.review`, set `features.research_phase: false`
-
-Update config.json with any changes.
-
----
+Note: These profiles control agent models, not the orchestrator. The orchestrator uses your Claude Code session model. For cost optimization, consider running your session on Sonnet -- agents with `inherit` will follow. See `references/model-profiles.md` for details.
 
-## Step 3: Model Selection
-
-```
-AskUserQuestion:
-  question: "Which model profile should Plan-Build-Run use for agents?"
+Use AskUserQuestion:
+  question: "Which model profile should agents use?"
   header: "Models"
   options:
     - label: "Balanced (Recommended)"
@@ -204,19 +70,20 @@ AskUserQuestion:
       description: "Opus for executor and planner, Sonnet for others. Best results, highest cost."
     - label: "Budget"
       description: "Haiku for most agents. Fastest and cheapest, but lower quality."
-```
+    - label: "Keep current"
+      description: "Leave model settings unchanged."
 
-Apply the selected profile to `config.json`:
-- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
-- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
-- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku
+Apply the selected profile to the models block in config.json:
+- **Balanced**: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50, extended_context=false
+- **Quality**: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet, context_window_tokens=1000000, agent_checkpoint_pct=65, extended_context=true
+- **Budget**: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku, context_window_tokens=200000, agent_checkpoint_pct=50, extended_context=false
+- **Keep current**: no change to models block, no change to context_window_tokens
 
 ---
 
-## Step 4: Workflow Preferences
+## Step 3: Workflow Features
 
-```
-AskUserQuestion:
+Use AskUserQuestion:
   question: "Which workflow features do you want enabled?"
   header: "Features"
   multiSelect: true
@@ -229,9 +96,8 @@ AskUserQuestion:
       description: "Require verification AND review to pass before advancing phases"
     - label: "Git branching"
       description: "Create a branch per phase for cleaner PR history"
-```
 
-Apply selections:
+Apply selections (others unchanged):
 - **Auto-continue**: Set `features.auto_continue: true`
 - **TDD mode**: Set `features.tdd_mode: true`
 - **Strict gates**: Set `gates.verification: true`, `gates.review: true`, `gates.plan_approval: true`
@@ -239,15 +105,23 @@ Apply selections:
 
 ---
 
-## Step 4b: CLAUDE.md Integration
+## Step 4: CLAUDE.md Integration
 
 Check if a `CLAUDE.md` file exists in the project root.
 
-**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
-**If it does NOT exist**: Create `CLAUDE.md` with the block below.
+**If it exists**: Read it. If it does NOT already contain a "Plan-Build-Run" section, offer to append the integration block.
+**If it does NOT exist**: Offer to create `CLAUDE.md` with the integration block.
 
-Append/create this content:
+Use AskUserQuestion:
+  question: "Update CLAUDE.md with Plan-Build-Run integration notes?"
+  header: "CLAUDE.md"
+  options:
+    - label: "Yes"
+      description: "Add or update the Plan-Build-Run section in CLAUDE.md"
+    - label: "No"
+      description: "Skip — leave CLAUDE.md as-is"
 
+If "Yes", append/create:
 ```markdown
 ## Plan-Build-Run
 
@@ -255,45 +129,118 @@ This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run)
 
 - Project state: `.planning/STATE.md` (source of truth for current phase and progress)
 - Configuration: `.planning/config.json`
-- Run `/pbr:status` to see current project state and suggested next action.
+- Run `/pbr:progress` to see current project state and suggested next action.
 
 **After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 ```
 
 ---
 
-## Step 5: Verification
+## Step 5: Platform Settings
+
+Manage Claude Code platform settings that PBR recommends for optimal token usage.
+
+**Read `.planning/config.json`** (already loaded in Step 1). Check for a `platform_settings` block:
+- If absent, treat it as `{}` (no managed settings).
+
+**Check for existing `.claude/settings.json`**:
+- If it exists, read its contents. Parse as JSON (or `{}` if empty/missing).
+- If it does not exist, start from `{}`.
+
+**Compute the merge**:
+- Start with the existing `.claude/settings.json` content.
+- Apply each key from `platform_settings` in config.json on top.
+- If `platform_settings` is absent or empty, skip the write entirely.
+
+**Report drift** (compare before/after):
+- List keys being ADDED (were absent in .claude/settings.json)
+- List keys being CHANGED (differ from existing .claude/settings.json value)
+- List keys that MATCH (already correct — no change needed)
+
+Display the report:
+
+```
+Platform Settings:
+  Keys added:   includeGitInstructions → false
+  Keys matched: (none)
+  Keys changed: (none)
+
+Writing .claude/settings.json...
+```
+
+If all keys already match, display:
+
+```
+Platform Settings: .claude/settings.json is already in sync — no changes needed.
+```
+
+**Conflict detection**: If an existing `.claude/settings.json` has a key from `platform_settings` set to the OPPOSITE value (e.g., `"includeGitInstructions": true` when PBR wants `false`), display a WARNING before overwriting:
+
+```
+WARNING: .claude/settings.json has includeGitInstructions: true
+         PBR recommends false (removes redundant built-in git instructions).
+         Overwriting with PBR recommended value.
+```
+
+**Write the merged settings.json**:
+- Write to `.claude/settings.json` in the project root (alongside `.planning/`).
+- Ensure the directory `.claude/` exists (create it if needed with Bash `mkdir -p .claude`).
+- Write with 2-space indentation. Include a `$schema` key at the top:
+  ```json
+  {
+    "$schema": "https://json.schemastore.org/claude-code-settings.json",
+    "includeGitInstructions": false
+  }
+  ```
+  (Merge in any pre-existing keys from .claude/settings.json that are NOT managed by PBR — pass them through unchanged at the bottom of the object.)
+
+**Drift detection note**: On subsequent /pbr:setup runs, if `.claude/settings.json` has drifted from `platform_settings` (e.g., user manually changed it), this step will detect and re-apply the PBR values with a drift warning. This is by design — platform_settings in config.json is the source of truth.
+
+---
+
+## Step 6: Write Updated Config
 
-**CRITICAL: Run validation checks NOW to confirm setup succeeded. Do NOT skip this step.**
+**CRITICAL: Write `.planning/config.json` NOW with all changes from Steps 2-3. Do NOT skip this step.**
 
-Run a quick health check:
+Write the updated config.json to disk with all applied changes.
 
-1. Verify `.planning/config.json` is valid JSON
-2. Verify `.planning/STATE.md` exists and is parseable
-3. Verify hook scripts are accessible: `node ${CLAUDE_PLUGIN_ROOT}/scripts/progress-tracker.js` from the project directory
-4. Check that `npm test` works (if package.json exists)
+### Commit Changes
 
-Display results:
+Reference: `skills/shared/commit-planning-docs.md` for the commit pattern.
 
+If `planning.commit_docs` is true in config.json, commit modified files:
+
+```text
+docs(setup): reconfigure project — {changed_settings}
 ```
-Setup Complete!
-
-Project: {cwd basename}
-Model profile: {balanced/quality/budget}
-Depth: {quick/standard/comprehensive}
-Features: {list of enabled non-default features}
-
-Next steps:
-  /pbr:begin  — Full project setup with requirements and roadmap
-  /pbr:scan   — Analyze existing codebase (if adding to existing project)
-  /pbr:help   — Command reference
-  /pbr:config — Fine-tune individual settings
+
+---
+
+## Step 7: Verification
+
+Run a quick check:
+1. Verify `.planning/config.json` is valid JSON (read it back)
+2. Display updated settings summary
+
+Display:
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  PLAN-BUILD-RUN ► RECONFIGURE COMPLETE ✓                     ║
+╚══════════════════════════════════════════════════════════════╝
+
+Updated:
+- Model profile: {new profile}
+- Features changed: {list or "none"}
+- CLAUDE.md: {updated/skipped}
+- Platform settings: {".claude/settings.json updated" or "already in sync" or "no managed settings"}
+
+Run /pbr:progress to see current project state.
 ```
 
 ---
 
 ## Error Handling
 
-- If `.planning/` creation fails (permissions): Tell user to create it manually and retry
+- If config.json parse fails: Display the raw content and ask user to fix it manually, then retry
 - If config.json write fails: Display the JSON content and ask user to save it manually
-- If health check fails: Display specific failure and suggest `/pbr:health` for diagnostics

package/plugins/pbr/skills/shared/agent-context-enrichment.md

@@ -0,0 +1,21 @@
+## Agent Context Enrichment
+
+When spawning a Task() executor or other subagent, enrich the spawn prompt with project context if `features.rich_agent_prompts` is enabled in config.
+
+### How to Use
+
+Before spawning Task(), call the enrichment modules:
+
+1. **Rich context** (from `lib/gates/rich-agent-context.js`):
+   - `buildRichAgentContext(planningDir, config, 5000)` returns a markdown string with project summary, state, decisions, conventions.
+   - Append this to the Task() prompt under a `## Project Context` header.
+
+2. **Multi-phase plans** (from `lib/gates/multi-phase-loader.js`):
+   - `loadMultiPhasePlans(planningDir, currentPhase, config)` returns plans from adjacent phases.
+   - Include the current phase plans in full. Include adjacent phase plans as frontmatter summaries only (first 30 lines).
+
+### Budget Control
+
+- Rich context defaults to 5000 chars (~1250 tokens). Adjust via `budgetChars` parameter.
+- Multi-phase loading is bounded by `workflow.max_phases_in_context` (default 3).
+- If orchestrator context is above 50%, reduce budgetChars to 2500.

package/plugins/pbr/skills/shared/agent-type-resolution.md

@@ -0,0 +1,20 @@
+# Agent Type Resolution
+
+PBR agents register under two naming formats depending on how the plugin loads:
+
+- **Plugin format**: `pbr:{name}` (e.g., `pbr:executor`) — when Claude Code loads agents from the plugin's `agents/` directory
+- **Standalone format**: `pbr-{name}` (e.g., `pbr-executor`) — when agents load from a root `agents/` directory
+
+**Resolution rule**: Always use `pbr:{name}` first. If the Task() spawn fails with "Agent type not found", retry the same Task() call with `pbr-{name}`. Do not change anything else in the prompt — only the `subagent_type` value.
+
+Example:
+
+```
+# First attempt (plugin format)
+Task({ subagent_type: "pbr:executor", prompt: ... })
+
+# If "Agent type not found" error, retry with:
+Task({ subagent_type: "pbr-executor", prompt: ... })
+```
+
+This applies to ALL `pbr:*` agent spawns: executor, verifier, planner, researcher, synthesizer, debugger, codebase-mapper, plan-checker, integration-checker, intel-updater, audit, general, ui-checker, ui-researcher.

package/plugins/pbr/skills/shared/commit-planning-docs.md

@@ -16,6 +16,14 @@ If `planning.commit_docs: false` or config.json missing:
 - Skip the commit step
 ```
 
+**Note:** CLI state commands (`state advance-plan`, `phase complete`, `state update-progress`) automatically update STATE.md and ROADMAP.md. The commit step here covers planning artifacts (PLAN.md, SUMMARY.md, VERIFICATION.md), not state files -- those are updated atomically by CLI commands.
+
+## Session Affinity
+
+When a session ID is available (from `.planning/.session.json`), append `[session:{short_id}]` to the commit description, where `short_id` is the first 8 characters of the session_id. This enables conflict tracing when multiple sessions modify planning docs concurrently.
+
+Example: `docs(planning): capture phase 3 discussion decisions [session:a1b2c3d4]`
+
 ## Commit Messages by Skill
 
 | Skill | Commit message format |

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

@@ -12,10 +12,48 @@ Every skill that spawns agents or reads significant content must follow these ru
 
 1. **Never** read agent definition files (`agents/*.md`) — `subagent_type` auto-loads them
 2. **Never** inline large files into Task() prompts — tell agents to read files from disk instead
-3. **Minimize** reading subagent output into main context — read only frontmatter, not full content
+3. **Read depth scales with context window** — check `context_window_tokens` in `.planning/config.json`:
+   - At < 500000 tokens (default 200k): read only frontmatter, status fields, or summaries. Never read full SUMMARY.md, VERIFICATION.md, or RESEARCH.md bodies.
+   - At >= 500000 tokens (1M model): MAY read full subagent output bodies when the content is needed for inline presentation or decision-making. Still avoid unnecessary reads.
 4. **Delegate** heavy work to subagents — 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.
 
+## Read Depth by Context Window
+
+| Context Window | Subagent Output Reading | SUMMARY.md | VERIFICATION.md | PLAN.md (other phases) |
+|---------------|------------------------|------------|-----------------|------------------------|
+| < 500k (200k model) | Frontmatter only | Frontmatter only | Frontmatter only | Current phase only |
+| >= 500k (1M model) | Full body permitted | Full body permitted | Full body permitted | Current phase only |
+
+**How to check:** Read `.planning/config.json` and inspect `context_window_tokens`. If the field is absent, treat as 200k (conservative default).
+
+**Applies to:** build, plan, review skills — any skill that reads back subagent artifacts.
+
+## 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.
+
+## State Consolidation Impact
+
+State consolidation (Phase 5) reduces core planning files from 5 to 3:
+- CONTEXT.md is now merged into PROJECT.md ## Context section
+- HISTORY.md is now merged into STATE.md ## History section
+- This reduces per-phase context loading overhead — fewer files to read, same information
+
+**File size estimates (post-consolidation):**
+- PROJECT.md: ~2-4 KB (includes Context section)
+- STATE.md: ~3-6 KB (includes History section)
+- ROADMAP.md: ~3-8 KB (depending on phase count)
+- config.json: ~1-2 KB
+
+**Note:** PROJECT.md is larger now with the merged Context section. Factor this into context budget when loading project state.
+
 ## Customization
 
 Skills should add skill-specific rules below the reference line. Common skill-specific additions:
@@ -38,3 +76,30 @@ Additionally for this skill:
 - {Skill-specific rule 1}
 - {Skill-specific rule 2}
 ```
+
+## Agent Elapsed Time Estimates
+
+When displaying agent spawn lines (e.g., "Spawning researcher..."), append a parenthetical estimate:
+
+| Agent Type | Display Text | Estimate |
+|------------|-------------|----------|
+| researcher | Spawning researcher... | (est. 1-3 min) |
+| planner | Spawning planner... | (est. 2-5 min) |
+| executor | Spawning executor... | (est. 3-8 min) |
+| verifier | Spawning verifier... | (est. 1-2 min) |
+| codebase-mapper | Spawning codebase-mapper... | (est. 1-2 min) |
+| plan-checker | Spawning plan-checker... | (est. 1-2 min) |
+| integration-checker | Spawning integration-checker... | (est. 2-4 min) |
+| debugger | Spawning debugger... | (est. 2-5 min) |
+| general | Spawning agent... | (est. 1-4 min) |
+| audit | Spawning audit... | (est. 2-4 min) |
+
+**Usage**: In any skill that spawns Task() agents, prefix spawn displays with the agent name and append the estimate from this table. Example:
+
+```
+Spawning researcher... (est. 1-3 min)
+Spawning planner... (est. 2-5 min)
+[Wave 1: 3 plans in parallel] Spawning executors... (est. 3-8 min each)
+```
+
+Skills that spawn agents: build, plan, review, debug, scan, milestone, quick.

package/plugins/pbr/skills/shared/context-loader-task.md

@@ -14,7 +14,7 @@ Use this pattern when:
 - Reading all context files directly would consume too much orchestrator context
 
 Do NOT use this pattern when:
-- The skill already uses `pbr-tools.js state load` (build, plan, review, import)
+- The skill already uses `pbr-tools.cjs state load` (build, plan, review, import)
 - The skill reads only STATE.md lines 1-20 (continue, status, resume)
 - The skill has no project dependency (note with `--global`)
 
@@ -28,22 +28,28 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
     - .planning/research/SUMMARY.md (if exists)
     - .planning/notes/*.md (if notes directory exists — read frontmatter for date/promoted status)
-    - .planning/HISTORY.md (if exists — scan for decisions relevant to current work only, do NOT summarize all history)
+    - .planning/KNOWLEDGE.md (if exists -- project knowledge: rules, patterns, lessons)
+    - .planning/STATE.md ## History section (scan for decisions relevant to current work only, do NOT summarize all history)
 
   Return ONLY the briefing text. No preamble, no suggestions."
 })
 ```
 
+### CLI Alternative
+
+Alternatively, the skill can call `node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load` for structured JSON state instead of spawning a briefing Task. Use the CLI approach when only state data is needed; use the Task approach when project context (decisions, notes, history) is also needed.
+
 ### Key Rules
 
 1. **Only runs if `.planning/` directory exists.** Skills invoked on fresh projects with no planning directory skip this entirely.
 2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
 3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
 4. **Read-only.** The briefing task must not write any files.
+5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
 
 ### Using the Briefing
 
@@ -64,9 +70,10 @@ Task({
     - .planning/STATE.md
     - .planning/ROADMAP.md
     - .planning/REQUIREMENTS.md
-    - .planning/CONTEXT.md
-    - Any .planning/phases/*/CONTEXT.md files
-    - .planning/HISTORY.md (if exists — scan for decisions relevant to '{topic}' only, do NOT summarize all history)
+    - .planning/PROJECT.md (if exists — project vision, scope, and context)
+    - Any .planning/phases/*/CONTEXT.md files (phase-level locked decisions)
+    - .planning/KNOWLEDGE.md (if exists -- project knowledge: rules, patterns, lessons)
+    - .planning/STATE.md ## History section (scan for decisions relevant to '{topic}' only, do NOT summarize all history)
 
   Focus on: decisions, requirements, and phase goals related to '{topic}'.
   Return ONLY the briefing text. No preamble, no suggestions."
@@ -77,7 +84,7 @@ Task({
 
 ## Variation: Scan Reconnaissance
 
-For `/pbr:scan`, the pattern adapts to codebase analysis rather than project state:
+For `/pbr:map-codebase`, the pattern adapts to codebase analysis rather than project state:
 
 1. The orchestrator performs a quick inline scan (detect project type, scale, key directories)
 2. Writes the results to `.planning/codebase/RECON.md`

package/plugins/pbr/skills/shared/digest-select.md

@@ -64,11 +64,11 @@ These fields give downstream skills enough context to build on prior work withou
 
 ## Skill-Specific Notes
 
-### /pbr:plan
+### /pbr:plan-phase
 - Direct dependencies: frontmatter + "Key Decisions" section (planner reads full bodies from disk)
 - Used in Step 2: Load Context
 
-### /pbr:build
+### /pbr:execute-phase
 - Direct dependencies (completed earlier waves): frontmatter only for prior work table
 - Used in Step 6a: Spawn Executors (prior_work section of executor prompt)