@sienklogic/plan-build-run 2.56.0 → 2.56.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.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.1",
   "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/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/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/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.0",
+  "version": "2.56.1",
   "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/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/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/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/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.56.0",
+  "version": "2.56.1",
   "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/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/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/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/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.56.0",
+  "version": "2.56.1",
   "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/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/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/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/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)
 ```