@sienklogic/plan-build-run 2.56.0 → 2.56.2

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to Plan-Build-Run will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.56.2](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.1...plan-build-run-v2.56.2) (2026-03-03)
+
+
+### Bug Fixes
+
+* **tools:** block non-PBR agent types by default with [native] bypass ([0256189](https://github.com/SienkLogic/plan-build-run/commit/02561890e49dba88df03d3977f9a8597740bd389))
+
+## [2.56.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.0...plan-build-run-v2.56.1) (2026-03-03)
+
+
+### Documentation
+
+* **quick-020:** comprehensively update documentation for v2.56.0 ([82f9177](https://github.com/SienkLogic/plan-build-run/commit/82f917792dd573192c4ce69df8633f13b1050b0a))
+
 ## [2.56.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.55.0...plan-build-run-v2.56.0) (2026-03-02)
 
 

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <strong>Context-engineered development workflow for Claude Code, Cursor, and GitHub Copilot CLI.</strong>
+  <strong>Context-engineered development workflow for Claude Code, Cursor, GitHub Copilot CLI, OpenAI Codex, and Google Jules.</strong>
   <br />
   Build ambitious multi-phase software without quality degradation.
   <br />
@@ -27,7 +27,7 @@
   <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
   <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
   <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/Tests-2153_passing-brightgreen?style=for-the-badge" alt="2153 Tests" />
+  <img src="https://img.shields.io/badge/Tests-9283_passing-brightgreen?style=for-the-badge" alt="9283 Tests" />
 </p>
 
 ---
@@ -132,6 +132,48 @@ All three plugins share the same `.planning/` directory — start in any tool, c
 
 </details>
 
+<details>
+<summary><strong>Install for OpenAI Codex CLI</strong></summary>
+
+Plan-Build-Run also works in OpenAI Codex CLI. Skills and agents are available via the `plugins/codex-pbr/` plugin. No hooks (Codex CLI does not support lifecycle hooks).
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/codex-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\codex-pbr\setup.ps1
+```
+
+All five plugins share the same `.planning/` directory. See [`plugins/codex-pbr/README.md`](plugins/codex-pbr/README.md) for full details.
+
+</details>
+
+<details>
+<summary><strong>Install for Google Jules</strong></summary>
+
+Plan-Build-Run also works in Google Jules. Skills and agents are available via the `plugins/jules-pbr/` plugin. No hooks (Jules does not support lifecycle hooks).
+
+**macOS / Linux:**
+```bash
+cd /path/to/your/project
+bash /path/to/plan-build-run/plugins/jules-pbr/setup.sh
+```
+
+**Windows (PowerShell):**
+```powershell
+cd C:\path\to\your\project
+powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\jules-pbr\setup.ps1
+```
+
+All five plugins share the same `.planning/` directory. See [`plugins/jules-pbr/README.md`](plugins/jules-pbr/README.md) for full details.
+
+</details>
+
 <details>
 <summary><strong>Dashboard (Optional)</strong></summary>
 
@@ -219,7 +261,7 @@ Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
 | `/pbr:build <N>` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |
 | `/pbr:review <N>` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |
 
-See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 26 commands with flags, cost-by-depth tables, and detailed descriptions.
+See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 27 commands with flags, cost-by-depth tables, and detailed descriptions.
 
 ---
 
@@ -292,8 +334,8 @@ Requires a GPU with 6+ GB VRAM for best performance. CPU-only works but adds lat
 | Topic | Description |
 |-------|-------------|
 | **[Agents](https://github.com/SienkLogic/plan-build-run/wiki/Agents)** | 12 specialized agents with configurable model profiles and file-based communication |
-| **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 13 config keys, depth/model profiles, 16+ feature toggles, local LLM settings |
-| **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 38 hook scripts that enforce discipline at zero token cost |
+| **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 12 config keys, depth/model profiles, 14+ feature toggles, local LLM settings |
+| **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 41 hook scripts that enforce discipline at zero token cost |
 | **[Local LLM](https://github.com/SienkLogic/plan-build-run/wiki/Configuration#local_llm)** | Offload hook-level inference to Ollama for token savings with automatic fallback |
 | **[Project Structure](https://github.com/SienkLogic/plan-build-run/wiki/Project-Structure)** | The `.planning/` directory layout, key files, and file ownership |
 | **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI with live updates for browsing project state |
@@ -306,28 +348,29 @@ Requires a GPU with 6+ GB VRAM for best performance. CPU-only works but adds lat
 
 ## Platform Compatibility
 
-Plan-Build-Run works across three platforms with varying levels of hook support. Hooks are the mechanism that fires validation scripts on every tool call — they power local LLM offloading, commit format enforcement, context budget tracking, and workflow gates.
-
-| Feature | Claude Code | Copilot CLI | Cursor IDE |
-|---------|:-----------:|:-----------:|:----------:|
-| Skills (slash commands) | All 26 | All 26 | All 26 |
-| Agents (subagent delegation) | All 12 | All 12 | All 12 |
-| `.planning/` state management | Full | Full | Full |
-| **Hook support** | **Full (14 events)** | **Partial (4 events)** | **Unverified** |
-| Commit format enforcement | Hook-enforced | Hook-enforced | Manual |
-| PLAN/SUMMARY quality classification | Hook + skill fallback | Hook + skill fallback | Skill fallback only |
-| Test failure triage | Automatic (hook) | Automatic (hook) | Not available |
-| Context budget tracking | Automatic (hook) | Not available | Not available |
-| Auto-continue between skills | Automatic (hook) | Not available | Not available |
-| Subagent lifecycle logging | Automatic (hook) | Not available | Not available |
-| **Local LLM offloading** | **Full (8 operations)** | **Mostly (6-7 operations)** | **CLI only** |
-| `pbr-tools.js llm` CLI commands | Full | Full | Full |
+Plan-Build-Run works across five platforms with varying levels of hook support. Hooks are the mechanism that fires validation scripts on every tool call — they power local LLM offloading, commit format enforcement, context budget tracking, and workflow gates.
+
+| Feature | Claude Code | Copilot CLI | Cursor IDE | Codex CLI | Jules |
+|---------|:-----------:|:-----------:|:----------:|:---------:|:-----:|
+| Skills (slash commands) | All 27 | All 27 | All 27 | All 27 | All 27 |
+| Agents (subagent delegation) | All 12 | All 12 | All 12 | All 12 | All 12 |
+| `.planning/` state management | Full | Full | Full | Full | Full |
+| **Hook support** | **Full (14 events)** | **Partial (4 events)** | **Unverified** | **None** | **None** |
+| Commit format enforcement | Hook-enforced | Hook-enforced | Manual | Manual | Manual |
+| PLAN/SUMMARY quality classification | Hook + skill fallback | Hook + skill fallback | Skill fallback only | Skill fallback only | Skill fallback only |
+| Test failure triage | Automatic (hook) | Automatic (hook) | Not available | Not available | Not available |
+| Context budget tracking | Automatic (hook) | Not available | Not available | Not available | Not available |
+| Auto-continue between skills | Automatic (hook) | Not available | Not available | Not available | Not available |
+| Subagent lifecycle logging | Automatic (hook) | Not available | Not available | Not available | Not available |
+| **Local LLM offloading** | **Full (8 operations)** | **Mostly (6-7 operations)** | **CLI only** | **CLI only** | **CLI only** |
+| `pbr-tools.js llm` CLI commands | Full | Full | Full | Full | Full |
 
 **Key differences:**
 
 - **Claude Code** has full hook support — all local LLM operations fire automatically on every tool call
 - **Copilot CLI** supports `sessionStart`, `preToolUse`, `postToolUse`, and `sessionEnd` — covers most validation hooks but misses lifecycle events (`SubagentStop`, `PreCompact`, `Stop`)
 - **Cursor IDE** hook support is unverified — hooks.json is configured but whether Cursor actually fires them is unknown. Skills include `pbr-tools.js llm` fallback calls for key operations (plan quality, verification quality) so local LLM classification is available even without hooks
+- **OpenAI Codex CLI** and **Google Jules** do not support hooks. All skills and agents are available via `plugins/codex-pbr/` and `plugins/jules-pbr/` respectively. Agent definitions use AGENTS.md format.
 
 All platforms share the same scripts via relative paths — no code duplication. See the [Copilot CLI](plugins/copilot-pbr/README.md) and [Cursor IDE](plugins/cursor-pbr/README.md) READMEs for platform-specific details.
 
@@ -341,7 +384,7 @@ git clone https://github.com/SienkLogic/plan-build-run.git
 cd plan-build-run
 npm install
 
-# Run tests (2153 tests, 73 suites)
+# Run tests (9283 tests, 281 suites)
 npm test
 
 # Lint
@@ -362,14 +405,19 @@ CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md]
 
 | Metric | Count |
 |--------|-------|
-| Skills (slash commands) | 26 |
+| Skills (slash commands) | 27 |
 | Specialized agents | 12 |
-| Hook scripts | 38 |
+| Hook scripts | 41 |
 | Local LLM operations | 8 |
-| Supported platforms | 3 (Claude Code, Cursor, Copilot CLI) |
-| Tests | 2153 |
-| Test suites | 73 |
-| Config keys | 13 top-level (62+ properties) |
+| Supported platforms | 5 (Claude Code, Cursor, Copilot CLI, Codex, Jules) |
+| Tests | 9283 |
+| Test suites | 281 |
+| Config keys | 12 top-level (62+ properties) |
+| Feature toggles | 14 |
+| Lib modules | 19 |
+| Shared fragments | 12 |
+| Templates | 10 |
+| References | 19 |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.56.0",
+  "version": "2.56.2",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",

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

@@ -361,7 +361,7 @@ All phases with status and completion data.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
 ```
 
-**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+**Output:** `current_phase`, `phase_count`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
 
 ---
 
@@ -375,7 +375,7 @@ Multi-field atomic STATE.md update. Updates all fields in a single pass.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
 ```
 
-**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `last_command`, `blockers`
 
 **Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
 

package/plugins/codex-pbr/skills/audit/SKILL.md

@@ -153,11 +153,11 @@ Task({
 })
 ```
 
-Also spawn a git analysis agent (can use a Bash agent or general-purpose):
+Also spawn a git analysis agent:
 
 ```
 Task({
-  subagent_type: "Bash",
+  subagent_type: "pbr:general",
   model: "haiku",
   prompt: "Run these git commands in {project_dir}:
     1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all

package/plugins/codex-pbr/skills/explore/SKILL.md

@@ -21,7 +21,9 @@ Then proceed to Step 1.
 
 You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
 
-This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
+This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
+
+**CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
 
 ---
 
@@ -103,6 +105,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
 
 ---
 
+## Upfront Research Delegation
+
+When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
+
+**Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
+
+**Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "<research_assignment>
+    Topic: {specific research question from user's request}
+    Output: Return findings as structured markdown in your response.
+    Mode: external-research
+
+    {detailed research instructions}
+  </research_assignment>"
+})
+```
+
+After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
+
+---
+
 ## Mid-Conversation Research
 
 When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.

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

@@ -172,7 +172,7 @@ After running all 10 checks and collecting results, if any of the following auto
 
 | Pattern | Detection | Fix Action |
 |---------|-----------|------------|
-| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
 | STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
 | Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `$pbr-setup` defaults) |
 | Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |

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

@@ -44,6 +44,7 @@ Task({
 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
 

package/plugins/codex-pbr/skills/shared/state-update.md

@@ -53,7 +53,7 @@ Progress: [{progress_bar}] {percent}%
 Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
 Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
 ```
-Calculation: `filled = Math.round((completed_phases / total_phases) * 20)`
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
 
 ### 3. Accumulated Context (lines 16-25)
 ```

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

@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
 ## Task/Subagent Rules (apply to every skill)
 
 10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Agents spawned by `Task()` cannot resolve `$pbr-*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
 
 ## Behavioral Rules (apply to every skill)
 

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.0",
+  "version": "2.56.2",
   "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

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

@@ -361,7 +361,7 @@ All phases with status and completion data.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
 ```
 
-**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+**Output:** `current_phase`, `phase_count`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
 
 ---
 
@@ -375,7 +375,7 @@ Multi-field atomic STATE.md update. Updates all fields in a single pass.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
 ```
 
-**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `last_command`, `blockers`
 
 **Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
 

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

@@ -153,11 +153,11 @@ Task({
 })
 ```
 
-Also spawn a git analysis agent (can use a Bash agent or general-purpose):
+Also spawn a git analysis agent:
 
 ```
 Task({
-  subagent_type: "Bash",
+  subagent_type: "pbr:general",
   model: "haiku",
   prompt: "Run these git commands in {project_dir}:
     1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all

package/plugins/copilot-pbr/skills/begin/templates/STATE.md.tmpl

@@ -2,7 +2,6 @@
 ---
 version: 2
 current_phase: 1
-total_phases: {total}
 phase_slug: "{phase_1_slug}"
 phase_name: "{Phase 1 name}"
 status: "ready_to_plan"

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

@@ -21,7 +21,9 @@ Then proceed to Step 1.
 
 You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
 
-This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
+This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
+
+**CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
 
 ---
 
@@ -103,6 +105,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
 
 ---
 
+## Upfront Research Delegation
+
+When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
+
+**Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
+
+**Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "<research_assignment>
+    Topic: {specific research question from user's request}
+    Output: Return findings as structured markdown in your response.
+    Mode: external-research
+
+    {detailed research instructions}
+  </research_assignment>"
+})
+```
+
+After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
+
+---
+
 ## Mid-Conversation Research
 
 When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.

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

@@ -172,7 +172,7 @@ After running all 10 checks and collecting results, if any of the following auto
 
 | Pattern | Detection | Fix Action |
 |---------|-----------|------------|
-| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
 | STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
 | Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
 | Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |

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

@@ -44,6 +44,7 @@ Task({
 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
 

package/plugins/copilot-pbr/skills/shared/state-update.md

@@ -53,7 +53,7 @@ Progress: [{progress_bar}] {percent}%
 Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
 Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
 ```
-Calculation: `filled = Math.round((completed_phases / total_phases) * 20)`
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
 
 ### 3. Accumulated Context (lines 16-25)
 ```

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

@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
 ## Task/Subagent Rules (apply to every skill)
 
 10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Agents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
 
 ## Behavioral Rules (apply to every skill)
 

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.0",
+  "version": "2.56.2",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

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

@@ -361,7 +361,7 @@ All phases with status and completion data.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
 ```
 
-**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+**Output:** `current_phase`, `phase_count`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
 
 ---
 
@@ -375,7 +375,7 @@ Multi-field atomic STATE.md update. Updates all fields in a single pass.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
 ```
 
-**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `last_command`, `blockers`
 
 **Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
 

package/plugins/cursor-pbr/skills/audit/SKILL.md

@@ -154,11 +154,11 @@ Task({
 })
 ```
 
-Also spawn a git analysis agent (can use a Bash agent or general-purpose):
+Also spawn a git analysis agent:
 
 ```
 Task({
-  subagent_type: "Bash",
+  subagent_type: "pbr:general",
   model: "haiku",
   prompt: "Run these git commands in {project_dir}:
     1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all

package/plugins/cursor-pbr/skills/begin/templates/STATE.md.tmpl

@@ -2,7 +2,6 @@
 ---
 version: 2
 current_phase: 1
-total_phases: {total}
 phase_slug: "{phase_1_slug}"
 phase_name: "{Phase 1 name}"
 status: "ready_to_plan"

package/plugins/cursor-pbr/skills/explore/SKILL.md

@@ -22,7 +22,9 @@ Then proceed to Step 1.
 
 You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
 
-This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
+This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
+
+**CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
 
 ---
 
@@ -104,6 +106,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
 
 ---
 
+## Upfront Research Delegation
+
+When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
+
+**Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
+
+**Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "<research_assignment>
+    Topic: {specific research question from user's request}
+    Output: Return findings as structured markdown in your response.
+    Mode: external-research
+
+    {detailed research instructions}
+  </research_assignment>"
+})
+```
+
+After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
+
+---
+
 ## Mid-Conversation Research
 
 When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.

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

@@ -173,7 +173,7 @@ After running all 10 checks and collecting results, if any of the following auto
 
 | Pattern | Detection | Fix Action |
 |---------|-----------|------------|
-| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
 | STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
 | Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
 | Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |

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

@@ -44,6 +44,7 @@ Task({
 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
 

package/plugins/cursor-pbr/skills/shared/state-update.md

@@ -53,7 +53,7 @@ Progress: [{progress_bar}] {percent}%
 Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
 Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
 ```
-Calculation: `filled = Math.round((completed_phases / total_phases) * 20)`
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
 
 ### 3. Accumulated Context (lines 16-25)
 ```

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

@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
 ## Task/Subagent Rules (apply to every skill)
 
 10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Agents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
 
 ## Behavioral Rules (apply to every skill)
 

package/plugins/pbr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.56.0",
+  "version": "2.56.2",
   "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",

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

@@ -361,7 +361,7 @@ All phases with status and completion data.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js init progress
 ```
 
-**Output:** `current_phase`, `total_phases`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
+**Output:** `current_phase`, `phase_count`, `status`, `phases` array, `total_plans`, `completed_plans`, `percentage`.
 
 ---
 
@@ -375,7 +375,7 @@ Multi-field atomic STATE.md update. Updates all fields in a single pass.
 node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state patch '{"status":"executing","last_activity":"now"}'
 ```
 
-**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `total_phases`, `last_command`, `blockers`
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`, `progress_percent`, `phase_slug`, `last_command`, `blockers`
 
 **Output:** `{ "success": true, "updated": ["status", "last_activity"] }`
 

package/plugins/pbr/scripts/check-plan-format.js

@@ -347,7 +347,7 @@ function validateState(content, _filePath) {
       warnings.push('Unclosed YAML frontmatter');
     } else {
       const frontmatter = content.substring(3, frontmatterEnd);
-      const requiredFields = ['version', 'current_phase', 'total_phases', 'phase_slug', 'status'];
+      const requiredFields = ['version', 'current_phase', 'phase_slug', 'status'];
       for (const field of requiredFields) {
         if (!frontmatter.includes(`${field}:`)) {
           warnings.push(`Frontmatter missing "${field}" field`);
@@ -440,14 +440,12 @@ function syncStateBody(content, filePath) {
 
   const fm = content.substring(3, fmEnd);
   const phaseMatch = fm.match(/^current_phase:\s*(\d+)/m);
-  const totalMatch = fm.match(/^total_phases:\s*(\d+)/m);
   const slugMatch = fm.match(/^phase_name:\s*"?([^"\r\n]+)"?/m);
   const statusMatch = fm.match(/^status:\s*"?([^"\r\n]+)"?/m);
 
   if (!phaseMatch) return null;
 
   const fmPhase = phaseMatch[1];
-  const fmTotal = totalMatch ? totalMatch[1] : null;
   const fmName = slugMatch ? slugMatch[1] : null;
   const fmStatus = statusMatch ? statusMatch[1] : null;
 
@@ -459,9 +457,10 @@ function syncStateBody(content, filePath) {
 
   // Fix phase line drift
   if (bodyPhaseMatch && bodyPhaseMatch[1] !== fmPhase) {
-    const newPhaseLine = fmTotal
-      ? (fmName ? `Phase: ${fmPhase} of ${fmTotal} (${fmName})` : `Phase: ${fmPhase} of ${fmTotal}`)
-      : `Phase: ${fmPhase} of ${bodyPhaseMatch[2]}`;
+    const bodyTotal = bodyPhaseMatch ? bodyPhaseMatch[2] : null;
+    const newPhaseLine = bodyTotal
+      ? (fmName ? `Phase: ${fmPhase} of ${bodyTotal} (${fmName})` : `Phase: ${fmPhase} of ${bodyTotal}`)
+      : `Phase: ${fmPhase}`;
     updated = updated.replace(/^Phase:\s*\d+\s*of\s*\d+.*/m, newPhaseLine);
     needsFix = true;
   }

package/plugins/pbr/scripts/check-state-sync.js

@@ -210,9 +210,6 @@ function updateStatePosition(content, updates) {
       if (updates.fmCurrentPhase !== undefined) {
         fm = fm.replace(/^(current_phase:\s*).*/m, (_, p) => `${p}${updates.fmCurrentPhase}`);
       }
-      if (updates.fmTotalPhases !== undefined) {
-        fm = fm.replace(/^(total_phases:\s*).*/m, (_, p) => `${p}${updates.fmTotalPhases}`);
-      }
       if (updates.fmPhaseSlug !== undefined) {
         fm = fm.replace(/^(phase_slug:\s*).*/m, (_, p) => `${p}"${updates.fmPhaseSlug}"`);
       }
@@ -420,7 +417,6 @@ function checkStateSync(data) {
         if (currentPhase !== null && currentPhase !== phaseNumInt) {
           stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
           stateUpdates.fmCurrentPhase = phaseNumInt;
-          stateUpdates.fmTotalPhases = totalPhases;
           stateUpdates.fmPhaseSlug = phaseSlug;
           stateUpdates.fmPhaseName = phaseName;
           messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);
@@ -503,7 +499,6 @@ function checkStateSync(data) {
         if (currentPhase !== null && currentPhase !== phaseNumInt) {
           stateUpdates.phaseLine = `${phaseNumInt} of ${totalPhases} (${phaseName})`;
           stateUpdates.fmCurrentPhase = phaseNumInt;
-          stateUpdates.fmTotalPhases = totalPhases;
           stateUpdates.fmPhaseSlug = phaseSlug;
           stateUpdates.fmPhaseName = phaseName;
           messages.push(`STATE.md: Phase ${currentPhase} → ${phaseNumInt}`);

package/plugins/pbr/scripts/enforce-pbr-workflow.js

@@ -13,7 +13,7 @@
  *   checkUnmanagedCommit(data)         — PreToolUse Bash: advises git commits to use /pbr:quick
  *
  * All functions return null for pass, or { exitCode, output } for action.
- * checkNonPbrAgent always returns advisory (exitCode 0) — never blocks Task().
+ * checkNonPbrAgent defaults to blocking (exitCode 2) — blocks non-PBR agents.
  */
 
 'use strict';
@@ -136,8 +136,9 @@ const AGENT_MAPPING = {
  *   - subagent_type is missing/empty (can't determine type)
  *   - Enforcement level is "off"
  *
- * In "advisory" mode (default): returns exitCode 0 with additionalContext.
- * In "block" mode: returns exitCode 2 with decision/reason to hard-block the agent spawn.
+ * Defaults to **blocking** (exitCode 2) unless config overrides to "advisory".
+ * This is stricter than checkUnmanagedSourceWrite/checkUnmanagedCommit because
+ * non-PBR agents bypass audit logging, workflow context, and project-aware prompts.
  *
  * @param {Object} data - parsed hook input from Claude Code
  * @returns {null|{ exitCode: number, output: Object }}
@@ -149,6 +150,10 @@ function checkNonPbrAgent(data) {
   // Already using a PBR agent
   if (subagentType.startsWith('pbr:')) return null;
 
+  // Per-call bypass: user says "use native agents" and the LLM includes [native] in description
+  const description = (data.tool_input && data.tool_input.description) || '';
+  if (/\[native\]/i.test(description)) return null;
+
   const cwd = process.cwd();
   const planningDir = path.join(cwd, '.planning');
 
@@ -158,14 +163,35 @@ function checkNonPbrAgent(data) {
   const config = loadEnforcementConfig(planningDir);
   if (config.level === 'off') return null;
 
+  // For agent enforcement, determine the effective level.
+  // Priority: workflow.enforce_pbr_agents > workflow.enforce_pbr_skills > default "block"
+  // Agent enforcement is stricter than source write/commit checks — blocks by default.
+  let agentLevel = 'block'; // default: block non-PBR agents
+  try {
+    const configPath = path.join(planningDir, 'config.json');
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    const agentExplicit = parsed.workflow && parsed.workflow.enforce_pbr_agents;
+    const skillExplicit = parsed.workflow && parsed.workflow.enforce_pbr_skills;
+    if (agentExplicit === 'advisory' || agentExplicit === 'block' || agentExplicit === 'off') {
+      agentLevel = agentExplicit;
+    } else if (skillExplicit === 'advisory' || skillExplicit === 'block' || skillExplicit === 'off') {
+      agentLevel = skillExplicit;
+    }
+  } catch (_e) {
+    // No config — keep default (block)
+  }
+
+  if (agentLevel === 'off') return null;
+
   const suggestion = AGENT_MAPPING[subagentType] || 'a pbr:* agent (e.g., pbr:researcher, pbr:general, pbr:executor)';
 
-  if (config.level === 'block') {
+  // Block non-PBR agents unless explicitly set to advisory
+  if (agentLevel !== 'advisory') {
     const blockMessage =
       `PBR workflow violation: spawning generic agent "${subagentType}" is blocked. ` +
       `Use ${suggestion} instead. ` +
       'PBR agents are auto-loaded via subagent_type — just change the type, no extra setup needed. ' +
-      'Set workflow.enforce_pbr_skills: "advisory" in config to allow with warnings.';
+      'If the user explicitly requested a native agent, add [native] to the Task description to bypass this check.';
 
     logHook('enforce-pbr-workflow', 'PreToolUse', 'block', { agentType: subagentType, suggestion });
     return {

package/plugins/pbr/scripts/lib/state.js

@@ -31,7 +31,6 @@ function parseStateMd(content) {
   if (frontmatter.version === 2 || frontmatter.current_phase !== undefined) {
     result.format = 'frontmatter';
     result.current_phase = frontmatter.current_phase || null;
-    result.total_phases = frontmatter.total_phases || null;
     result.phase_name = frontmatter.phase_slug || frontmatter.phase_name || null;
     result.status = frontmatter.status || null;
     result.progress = frontmatter.progress_percent !== undefined ? frontmatter.progress_percent : null;
@@ -301,7 +300,6 @@ function stateUpdate(field, value, planningDir) {
     'last_activity',
     'progress_percent',
     'phase_slug',
-    'total_phases',
     'last_command',
     'blockers'
   ];
@@ -340,7 +338,7 @@ function statePatch(jsonStr, planningDir) {
   if (!fs.existsSync(statePath)) return { success: false, error: "STATE.md not found" };
   let fields;
   try { fields = JSON.parse(jsonStr); } catch (_e) { return { success: false, error: "Invalid JSON" }; }
-  const validFields = ["current_phase", "status", "plans_complete", "last_activity", "progress_percent", "phase_slug", "total_phases", "last_command", "blockers"];
+  const validFields = ["current_phase", "status", "plans_complete", "last_activity", "progress_percent", "phase_slug", "last_command", "blockers"];
   const updates = [], errors = [];
   for (const [field, value] of Object.entries(fields)) {
     if (!validFields.includes(field)) { errors.push("Unknown field: " + field); continue; }

package/plugins/pbr/scripts/pbr-tools.js

@@ -539,7 +539,7 @@ async function main() {
       const field = args[2];
       const value = args[3];
       if (!field || value === undefined) {
-        error('Usage: pbr-tools.js state update <field> <value>\nFields: current_phase, status, plans_complete, last_activity, progress_percent, phase_slug, total_phases, last_command, blockers');
+        error('Usage: pbr-tools.js state update <field> <value>\nFields: current_phase, status, plans_complete, last_activity, progress_percent, phase_slug, last_command, blockers');
       }
       output(stateUpdate(field, value));
     } else if (command === 'config' && subcommand === 'validate') {

package/plugins/pbr/scripts/status-line.js

@@ -242,12 +242,11 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData, planningDir) {
   // Phase section (always includes brand text)
   if (sections.includes('phase')) {
     const fmPhase = fm && fm.current_phase;
-    const fmTotal = fm && fm.total_phases;
     const fmName = fm && fm.phase_name;
     const phaseMatch = content.match(/Phase:\s*(\d+)\s*of\s*(\d+)\s*(?:\(([^)]+)\))?/);
 
     const phaseNum = fmPhase || (phaseMatch && phaseMatch[1]);
-    const phaseTotal = fmTotal || (phaseMatch && phaseMatch[2]);
+    const phaseTotal = phaseMatch && phaseMatch[2];
     const phaseName = fmName || (phaseMatch && phaseMatch[3]);
 
     if (phaseNum && phaseTotal) {
@@ -263,11 +262,11 @@ function buildStatusLine(content, ctxPercent, cfg, stdinData, planningDir) {
   // Plan section
   if (sections.includes('plan')) {
     const fmComplete = fm && fm.plans_complete;
-    const fmTotal = fm && fm.plans_total;
+    const fmPlansTotal = fm && fm.plans_total;
     const planMatch = content.match(/Plan:\s*(\d+)\s*of\s*(\d+)/);
 
     const done = fmComplete != null ? parseInt(fmComplete, 10) : (planMatch ? parseInt(planMatch[1], 10) : null);
-    const total = fmTotal != null ? parseInt(fmTotal, 10) : (planMatch ? parseInt(planMatch[2], 10) : null);
+    const total = fmPlansTotal != null ? parseInt(fmPlansTotal, 10) : (planMatch ? parseInt(planMatch[2], 10) : null);
 
     if (done != null && total != null && total > 0) {
       const planColor = done === total ? c.green : c.white;

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

@@ -155,11 +155,11 @@ Task({
 })
 ```
 
-Also spawn a git analysis agent (can use a Bash agent or general-purpose):
+Also spawn a git analysis agent:
 
 ```
 Task({
-  subagent_type: "Bash",
+  subagent_type: "pbr:general",
   model: "haiku",
   prompt: "Run these git commands in {project_dir}:
     1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all

package/plugins/pbr/skills/begin/templates/STATE.md.tmpl

@@ -1,7 +1,6 @@
 ---
 version: 2
 current_phase: 1
-total_phases: {total}
 phase_slug: "{phase_1_slug}"
 phase_name: "{Phase 1 name}"
 status: "ready_to_plan"

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

@@ -23,7 +23,9 @@ Then proceed to Step 1.
 
 You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
 
-This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
+This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
+
+**CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
 
 ---
 
@@ -105,6 +107,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
 
 ---
 
+## Upfront Research Delegation
+
+When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
+
+**Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
+
+**Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  prompt: "<research_assignment>
+    Topic: {specific research question from user's request}
+    Output: Return findings as structured markdown in your response.
+    Mode: external-research
+
+    {detailed research instructions}
+  </research_assignment>"
+})
+```
+
+After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
+
+---
+
 ## Mid-Conversation Research
 
 When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.

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

@@ -174,7 +174,7 @@ After running all 10 checks and collecting results, if any of the following auto
 
 | Pattern | Detection | Fix Action |
 |---------|-----------|------------|
-| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, total_phases, status) |
+| Missing STATE.md frontmatter | Check 5 finds STATE.md without `---` block | Regenerate frontmatter from ROADMAP.md phase data (current_phase, phase_slug, status) |
 | STATE.md phase_slug mismatch | Check 5/7 finds phase_slug doesn't match current phase directory name | Correct phase_slug to match the actual directory name in `.planning/phases/` |
 | Missing config.json | Check 1/2 finds no `.planning/config.json` | Create with default config template (same as `/pbr:setup` defaults) |
 | Orphaned .active-skill file | Check 10 or general scan finds `.planning/.active-skill` older than 1 hour | Delete the stale `.active-skill` file |

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

@@ -44,6 +44,7 @@ Task({
 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
 

package/plugins/pbr/skills/shared/state-update.md

@@ -53,7 +53,7 @@ Progress: [{progress_bar}] {percent}%
 Phase 3 of 10 = 20% → [████░░░░░░░░░░░░░░░░] 20%
 Phase 7 of 10 = 70% → [██████████████░░░░░░] 70%
 ```
-Calculation: `filled = Math.round((completed_phases / total_phases) * 20)`
+Calculation: `filled = Math.round((completed_phases / phase_count) * 20)` where `phase_count` is derived from ROADMAP.md (available via `stateLoad` as `phase_count`)
 
 ### 3. Accumulated Context (lines 16-25)
 ```

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

@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
 ## Task/Subagent Rules (apply to every skill)
 
 10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Subagents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
+11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
 
 ## Behavioral Rules (apply to every skill)