@sienklogic/plan-build-run 2.9.0 → 2.10.0

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.10.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.9.1...plan-build-run-v2.10.0) (2026-02-20)
+
+
+### Features
+
+* **tools:** add post-compaction recovery, pbr-tools CLI reference, and dashboard UI banner ([84291f2](https://github.com/SienkLogic/plan-build-run/commit/84291f2ff0f9646eea96c02fd50073b8dd17487d))
+
+## [2.9.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.9.0...plan-build-run-v2.9.1) (2026-02-20)
+
+
+### Documentation
+
+* update CLAUDE.md coverage thresholds to 70% and test count to ~1666 ([7d10002](https://github.com/SienkLogic/plan-build-run/commit/7d10002a6d7814d98808f812060d48a4d49da1bb))
+
 ## [2.9.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.8.3...plan-build-run-v2.9.0) (2026-02-20)
 
 

package/CLAUDE.md

@@ -14,14 +14,14 @@ Plan-Build-Run is a **Claude Code plugin** that provides a structured developmen
 ## Commands
 
 ```bash
-npm test                                    # Run all Jest tests (~780 tests, 36 suites)
+npm test                                    # Run all Jest tests (~1666 tests, 57 suites)
 npm run lint                                # ESLint on plugins/pbr/scripts/ and tests/
 npm run validate                            # Validate plugin directory structure
 npx jest tests/validate-commit.test.js      # Run a single test file
 npx jest --coverage                         # Run with coverage report
 ```
 
-Coverage thresholds (enforced in `package.json`): 65% statements, 58% branches, 70% functions, 65% lines.
+Coverage thresholds (enforced in `package.json`): 70% statements, 70% branches, 70% functions, 70% lines.
 
 Dashboard (separate dependency tree):
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sienklogic/plan-build-run",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
   "keywords": [
     "claude-code",
@@ -47,10 +47,10 @@
     ],
     "coverageThreshold": {
       "global": {
-        "statements": 55,
-        "branches": 50,
-        "functions": 55,
-        "lines": 55
+        "statements": 70,
+        "branches": 70,
+        "functions": 70,
+        "lines": 70
       }
     }
   }

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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-rules.md

@@ -28,6 +28,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
 14. Use the `limit` parameter on Read to restrict line counts.
 15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 
 ---
 

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

@@ -0,0 +1,285 @@
+# pbr-tools.js CLI Reference
+
+Command-line interface for structured JSON operations on `.planning/` state.
+Skills and agents call this via Bash to avoid token-expensive text parsing.
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command> [args]
+```
+
+All commands output JSON to stdout. Errors output JSON with an `error` field to stderr (exit code 1).
+
+---
+
+## State Commands
+
+### `state load`
+
+Returns full project state as a single JSON object.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+
+**Output:**
+```json
+{
+  "exists": true,
+  "config": { ... },        // config.json contents
+  "state": {                 // STATE.md frontmatter + parsed body
+    "version": 2,
+    "current_phase": "1",
+    "status": "building",
+    "progress_percent": 45,
+    "last_activity": "2025-01-15",
+    "last_command": "/pbr:build",
+    "blockers": []
+  },
+  "roadmap": {               // Parsed ROADMAP.md
+    "phases": [{ "number": "01", "name": "...", "status": "planned", ... }]
+  },
+  "phase_count": 3,
+  "current_phase": "1",
+  "progress": { "phases": [...], "total_plans": 5, "completed_plans": 2, "percentage": 40 }
+}
+```
+
+### `state check-progress`
+
+Recalculates progress from filesystem (plan files, summaries, verification).
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+```
+
+**Output:**
+```json
+{
+  "phases": [
+    { "directory": "01-setup", "plans": 2, "summaries": 2, "completed": 2, "has_verification": true, "status": "verified" }
+  ],
+  "total_plans": 5,
+  "completed_plans": 3,
+  "percentage": 60
+}
+```
+
+### `state update <field> <value>`
+
+Atomically updates a single field in STATE.md. Uses file locking.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update current_phase 2
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status building
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now   # auto-timestamps
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update plans_complete 3
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`
+
+**Output:** `{ "success": true, "field": "status", "value": "building" }`
+
+---
+
+## Config Commands
+
+### `config validate`
+
+Validates `config.json` against the JSON schema. Detects both schema violations and semantic conflicts.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config validate
+```
+
+**Output:**
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": ["features.auto_continue=true with mode=interactive: auto_continue only fires in autonomous mode"]
+}
+```
+
+### `config resolve-depth [dir]`
+
+Resolves the effective depth profile by merging base profile with user overrides.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth /path/to/.planning
+```
+
+**Output:** Full depth profile object with all resolved values (research rounds, plan detail level, verification depth, etc.)
+
+---
+
+## Plan & Phase Commands
+
+### `plan-index <phase>`
+
+Returns plan inventory for a phase, grouped by wave.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js plan-index 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "total_plans": 3,
+  "plans": [
+    {
+      "file": "PLAN-01.md",
+      "plan_id": "01",
+      "wave": 1,
+      "type": "feature",
+      "autonomous": true,
+      "depends_on": [],
+      "gap_closure": false,
+      "has_summary": true,
+      "must_haves_count": 4
+    }
+  ],
+  "waves": { "wave_1": ["01", "02"], "wave_2": ["03"] }
+}
+```
+
+### `phase-info <phase>`
+
+Comprehensive single-phase status combining roadmap, filesystem, and plan data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "name": "setup",
+  "goal": "Initialize project infrastructure",
+  "roadmap_status": "building",
+  "filesystem_status": "partial",
+  "plans": [...],
+  "plan_count": 3,
+  "summaries": [{ "file": "SUMMARY-01.md", "plan": "01", "status": "complete" }],
+  "completed": 1,
+  "verification": null,
+  "has_context": false
+}
+```
+
+### `must-haves <phase>`
+
+Collects all must-haves from phase plans — truths, artifacts, and key links.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "plans": {
+    "01": { "truths": ["..."], "artifacts": ["..."], "key_links": ["..."] }
+  },
+  "all": { "truths": [...], "artifacts": [...], "key_links": [...] },
+  "total": 12
+}
+```
+
+---
+
+## Frontmatter Command
+
+### `frontmatter <filepath>`
+
+Parses a markdown file's YAML frontmatter and returns as JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter .planning/phases/01-setup/PLAN-01.md
+```
+
+**Output:** The frontmatter fields as a JSON object. Returns `{ "error": "File not found: ..." }` if the file doesn't exist.
+
+---
+
+## Roadmap Commands
+
+### `roadmap update-status <phase> <status>`
+
+Updates the Status column for a phase in ROADMAP.md's Phase Overview table. Uses file locking. Warns on invalid status transitions but does not block them.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status 1 building
+```
+
+**Valid statuses:** `pending`, `planned`, `building`, `built`, `partial`, `needs_fixes`, `verified`, `skipped`
+
+**Output:** `{ "success": true, "old_status": "planned", "new_status": "building" }`
+
+### `roadmap update-plans <phase> <complete> <total>`
+
+Updates the Plans column (e.g., "2/5") for a phase in ROADMAP.md.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans 1 2 5
+```
+
+**Output:** `{ "success": true, "old_plans": "1/5", "new_plans": "2/5" }`
+
+---
+
+## History Commands
+
+### `history append <type> <title> [body]`
+
+Appends a record to HISTORY.md. Creates the file if it doesn't exist.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 Release" "Initial release with core features"
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "01-setup Complete" "3 plans executed, all verified"
+```
+
+**Types:** `milestone`, `phase`
+
+**Output:** `{ "success": true }`
+
+### `history load`
+
+Loads all HISTORY.md records as structured JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load
+```
+
+**Output:**
+```json
+{
+  "records": [
+    { "type": "milestone", "title": "v1.0 Release", "date": "2025-01-15", "body": "..." }
+  ],
+  "line_count": 42
+}
+```
+
+Returns `null` if HISTORY.md doesn't exist.
+
+---
+
+## Event Command
+
+### `event <category> <event> [JSON-details]`
+
+Logs a structured event to `.planning/logs/events.jsonl`.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event build plan-complete '{"plan":"01","phase":"01-setup"}'
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"script":"validate-task.js"}'
+```
+
+**Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
+
+If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.

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

@@ -3,6 +3,18 @@ name: dashboard
 description: "Launch the PBR web dashboard for the current project."
 ---
 
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► DASHBOARD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
 ## Behavior
 
 1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.

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

@@ -215,6 +215,29 @@ Apply selections:
 
 ---
 
+## Step 4b: 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.
+
+Append/create this content:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- 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.
+
+**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
 
 Run a quick health check:

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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-rules.md

@@ -28,6 +28,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
 14. Use the `limit` parameter on Read to restrict line counts.
 15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 
 ---
 

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

@@ -0,0 +1,285 @@
+# pbr-tools.js CLI Reference
+
+Command-line interface for structured JSON operations on `.planning/` state.
+Skills and agents call this via Bash to avoid token-expensive text parsing.
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command> [args]
+```
+
+All commands output JSON to stdout. Errors output JSON with an `error` field to stderr (exit code 1).
+
+---
+
+## State Commands
+
+### `state load`
+
+Returns full project state as a single JSON object.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+
+**Output:**
+```json
+{
+  "exists": true,
+  "config": { ... },        // config.json contents
+  "state": {                 // STATE.md frontmatter + parsed body
+    "version": 2,
+    "current_phase": "1",
+    "status": "building",
+    "progress_percent": 45,
+    "last_activity": "2025-01-15",
+    "last_command": "/pbr:build",
+    "blockers": []
+  },
+  "roadmap": {               // Parsed ROADMAP.md
+    "phases": [{ "number": "01", "name": "...", "status": "planned", ... }]
+  },
+  "phase_count": 3,
+  "current_phase": "1",
+  "progress": { "phases": [...], "total_plans": 5, "completed_plans": 2, "percentage": 40 }
+}
+```
+
+### `state check-progress`
+
+Recalculates progress from filesystem (plan files, summaries, verification).
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+```
+
+**Output:**
+```json
+{
+  "phases": [
+    { "directory": "01-setup", "plans": 2, "summaries": 2, "completed": 2, "has_verification": true, "status": "verified" }
+  ],
+  "total_plans": 5,
+  "completed_plans": 3,
+  "percentage": 60
+}
+```
+
+### `state update <field> <value>`
+
+Atomically updates a single field in STATE.md. Uses file locking.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update current_phase 2
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status building
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now   # auto-timestamps
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update plans_complete 3
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`
+
+**Output:** `{ "success": true, "field": "status", "value": "building" }`
+
+---
+
+## Config Commands
+
+### `config validate`
+
+Validates `config.json` against the JSON schema. Detects both schema violations and semantic conflicts.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config validate
+```
+
+**Output:**
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": ["features.auto_continue=true with mode=interactive: auto_continue only fires in autonomous mode"]
+}
+```
+
+### `config resolve-depth [dir]`
+
+Resolves the effective depth profile by merging base profile with user overrides.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth /path/to/.planning
+```
+
+**Output:** Full depth profile object with all resolved values (research rounds, plan detail level, verification depth, etc.)
+
+---
+
+## Plan & Phase Commands
+
+### `plan-index <phase>`
+
+Returns plan inventory for a phase, grouped by wave.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js plan-index 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "total_plans": 3,
+  "plans": [
+    {
+      "file": "PLAN-01.md",
+      "plan_id": "01",
+      "wave": 1,
+      "type": "feature",
+      "autonomous": true,
+      "depends_on": [],
+      "gap_closure": false,
+      "has_summary": true,
+      "must_haves_count": 4
+    }
+  ],
+  "waves": { "wave_1": ["01", "02"], "wave_2": ["03"] }
+}
+```
+
+### `phase-info <phase>`
+
+Comprehensive single-phase status combining roadmap, filesystem, and plan data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "name": "setup",
+  "goal": "Initialize project infrastructure",
+  "roadmap_status": "building",
+  "filesystem_status": "partial",
+  "plans": [...],
+  "plan_count": 3,
+  "summaries": [{ "file": "SUMMARY-01.md", "plan": "01", "status": "complete" }],
+  "completed": 1,
+  "verification": null,
+  "has_context": false
+}
+```
+
+### `must-haves <phase>`
+
+Collects all must-haves from phase plans — truths, artifacts, and key links.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "plans": {
+    "01": { "truths": ["..."], "artifacts": ["..."], "key_links": ["..."] }
+  },
+  "all": { "truths": [...], "artifacts": [...], "key_links": [...] },
+  "total": 12
+}
+```
+
+---
+
+## Frontmatter Command
+
+### `frontmatter <filepath>`
+
+Parses a markdown file's YAML frontmatter and returns as JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter .planning/phases/01-setup/PLAN-01.md
+```
+
+**Output:** The frontmatter fields as a JSON object. Returns `{ "error": "File not found: ..." }` if the file doesn't exist.
+
+---
+
+## Roadmap Commands
+
+### `roadmap update-status <phase> <status>`
+
+Updates the Status column for a phase in ROADMAP.md's Phase Overview table. Uses file locking. Warns on invalid status transitions but does not block them.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status 1 building
+```
+
+**Valid statuses:** `pending`, `planned`, `building`, `built`, `partial`, `needs_fixes`, `verified`, `skipped`
+
+**Output:** `{ "success": true, "old_status": "planned", "new_status": "building" }`
+
+### `roadmap update-plans <phase> <complete> <total>`
+
+Updates the Plans column (e.g., "2/5") for a phase in ROADMAP.md.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans 1 2 5
+```
+
+**Output:** `{ "success": true, "old_plans": "1/5", "new_plans": "2/5" }`
+
+---
+
+## History Commands
+
+### `history append <type> <title> [body]`
+
+Appends a record to HISTORY.md. Creates the file if it doesn't exist.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 Release" "Initial release with core features"
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "01-setup Complete" "3 plans executed, all verified"
+```
+
+**Types:** `milestone`, `phase`
+
+**Output:** `{ "success": true }`
+
+### `history load`
+
+Loads all HISTORY.md records as structured JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load
+```
+
+**Output:**
+```json
+{
+  "records": [
+    { "type": "milestone", "title": "v1.0 Release", "date": "2025-01-15", "body": "..." }
+  ],
+  "line_count": 42
+}
+```
+
+Returns `null` if HISTORY.md doesn't exist.
+
+---
+
+## Event Command
+
+### `event <category> <event> [JSON-details]`
+
+Logs a structured event to `.planning/logs/events.jsonl`.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event build plan-complete '{"plan":"01","phase":"01-setup"}'
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"script":"validate-task.js"}'
+```
+
+**Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
+
+If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.

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

@@ -4,6 +4,18 @@ description: "Launch the PBR web dashboard for the current project."
 argument-hint: "[--port N]"
 ---
 
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► DASHBOARD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
 ## Behavior
 
 1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.

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

@@ -215,6 +215,29 @@ Apply selections:
 
 ---
 
+## Step 4b: 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.
+
+Append/create this content:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- 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.
+
+**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
 
 Run a quick health check:

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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-rules.md

@@ -27,6 +27,7 @@ Condensed from the 3,100-line `docs/DEVELOPMENT-GUIDE.md`. When in doubt, these
 13. Read STATE.md and config.json fully. Read ROADMAP.md by section. Read PLAN.md/SUMMARY.md/VERIFICATION.md frontmatter only.
 14. Use the `limit` parameter on Read to restrict line counts.
 15. Proactively suggest `/pbr:pause` when context gets heavy — before compaction, not after.
+15b. **After compaction or context recovery**, always read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
 
 ---
 

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

@@ -0,0 +1,285 @@
+# pbr-tools.js CLI Reference
+
+Command-line interface for structured JSON operations on `.planning/` state.
+Skills and agents call this via Bash to avoid token-expensive text parsing.
+
+```
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js <command> [args]
+```
+
+All commands output JSON to stdout. Errors output JSON with an `error` field to stderr (exit code 1).
+
+---
+
+## State Commands
+
+### `state load`
+
+Returns full project state as a single JSON object.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load
+```
+
+**Output:**
+```json
+{
+  "exists": true,
+  "config": { ... },        // config.json contents
+  "state": {                 // STATE.md frontmatter + parsed body
+    "version": 2,
+    "current_phase": "1",
+    "status": "building",
+    "progress_percent": 45,
+    "last_activity": "2025-01-15",
+    "last_command": "/pbr:build",
+    "blockers": []
+  },
+  "roadmap": {               // Parsed ROADMAP.md
+    "phases": [{ "number": "01", "name": "...", "status": "planned", ... }]
+  },
+  "phase_count": 3,
+  "current_phase": "1",
+  "progress": { "phases": [...], "total_plans": 5, "completed_plans": 2, "percentage": 40 }
+}
+```
+
+### `state check-progress`
+
+Recalculates progress from filesystem (plan files, summaries, verification).
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state check-progress
+```
+
+**Output:**
+```json
+{
+  "phases": [
+    { "directory": "01-setup", "plans": 2, "summaries": 2, "completed": 2, "has_verification": true, "status": "verified" }
+  ],
+  "total_plans": 5,
+  "completed_plans": 3,
+  "percentage": 60
+}
+```
+
+### `state update <field> <value>`
+
+Atomically updates a single field in STATE.md. Uses file locking.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update current_phase 2
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update status building
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update last_activity now   # auto-timestamps
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state update plans_complete 3
+```
+
+**Valid fields:** `current_phase`, `status`, `plans_complete`, `last_activity`
+
+**Output:** `{ "success": true, "field": "status", "value": "building" }`
+
+---
+
+## Config Commands
+
+### `config validate`
+
+Validates `config.json` against the JSON schema. Detects both schema violations and semantic conflicts.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config validate
+```
+
+**Output:**
+```json
+{
+  "valid": true,
+  "errors": [],
+  "warnings": ["features.auto_continue=true with mode=interactive: auto_continue only fires in autonomous mode"]
+}
+```
+
+### `config resolve-depth [dir]`
+
+Resolves the effective depth profile by merging base profile with user overrides.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js config resolve-depth /path/to/.planning
+```
+
+**Output:** Full depth profile object with all resolved values (research rounds, plan detail level, verification depth, etc.)
+
+---
+
+## Plan & Phase Commands
+
+### `plan-index <phase>`
+
+Returns plan inventory for a phase, grouped by wave.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js plan-index 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "total_plans": 3,
+  "plans": [
+    {
+      "file": "PLAN-01.md",
+      "plan_id": "01",
+      "wave": 1,
+      "type": "feature",
+      "autonomous": true,
+      "depends_on": [],
+      "gap_closure": false,
+      "has_summary": true,
+      "must_haves_count": 4
+    }
+  ],
+  "waves": { "wave_1": ["01", "02"], "wave_2": ["03"] }
+}
+```
+
+### `phase-info <phase>`
+
+Comprehensive single-phase status combining roadmap, filesystem, and plan data.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js phase-info 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "name": "setup",
+  "goal": "Initialize project infrastructure",
+  "roadmap_status": "building",
+  "filesystem_status": "partial",
+  "plans": [...],
+  "plan_count": 3,
+  "summaries": [{ "file": "SUMMARY-01.md", "plan": "01", "status": "complete" }],
+  "completed": 1,
+  "verification": null,
+  "has_context": false
+}
+```
+
+### `must-haves <phase>`
+
+Collects all must-haves from phase plans — truths, artifacts, and key links.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js must-haves 1
+```
+
+**Output:**
+```json
+{
+  "phase": "01-setup",
+  "plans": {
+    "01": { "truths": ["..."], "artifacts": ["..."], "key_links": ["..."] }
+  },
+  "all": { "truths": [...], "artifacts": [...], "key_links": [...] },
+  "total": 12
+}
+```
+
+---
+
+## Frontmatter Command
+
+### `frontmatter <filepath>`
+
+Parses a markdown file's YAML frontmatter and returns as JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js frontmatter .planning/phases/01-setup/PLAN-01.md
+```
+
+**Output:** The frontmatter fields as a JSON object. Returns `{ "error": "File not found: ..." }` if the file doesn't exist.
+
+---
+
+## Roadmap Commands
+
+### `roadmap update-status <phase> <status>`
+
+Updates the Status column for a phase in ROADMAP.md's Phase Overview table. Uses file locking. Warns on invalid status transitions but does not block them.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-status 1 building
+```
+
+**Valid statuses:** `pending`, `planned`, `building`, `built`, `partial`, `needs_fixes`, `verified`, `skipped`
+
+**Output:** `{ "success": true, "old_status": "planned", "new_status": "building" }`
+
+### `roadmap update-plans <phase> <complete> <total>`
+
+Updates the Plans column (e.g., "2/5") for a phase in ROADMAP.md.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js roadmap update-plans 1 2 5
+```
+
+**Output:** `{ "success": true, "old_plans": "1/5", "new_plans": "2/5" }`
+
+---
+
+## History Commands
+
+### `history append <type> <title> [body]`
+
+Appends a record to HISTORY.md. Creates the file if it doesn't exist.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append milestone "v1.0 Release" "Initial release with core features"
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history append phase "01-setup Complete" "3 plans executed, all verified"
+```
+
+**Types:** `milestone`, `phase`
+
+**Output:** `{ "success": true }`
+
+### `history load`
+
+Loads all HISTORY.md records as structured JSON.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js history load
+```
+
+**Output:**
+```json
+{
+  "records": [
+    { "type": "milestone", "title": "v1.0 Release", "date": "2025-01-15", "body": "..." }
+  ],
+  "line_count": 42
+}
+```
+
+Returns `null` if HISTORY.md doesn't exist.
+
+---
+
+## Event Command
+
+### `event <category> <event> [JSON-details]`
+
+Logs a structured event to `.planning/logs/events.jsonl`.
+
+```bash
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event build plan-complete '{"plan":"01","phase":"01-setup"}'
+node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js event error hook-failure '{"script":"validate-task.js"}'
+```
+
+**Output:** `{ "logged": true, "category": "build", "event": "plan-complete" }`
+
+If the JSON-details argument is not valid JSON, it's stored as `{ "raw": "<the string>" }`.

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

@@ -7,6 +7,18 @@ argument-hint: "[--port N]"
 
 **STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Begin executing immediately.**
 
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► DASHBOARD
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
 ## Behavior
 
 1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.

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

@@ -218,6 +218,29 @@ Apply selections:
 
 ---
 
+## Step 4b: 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.
+
+Append/create this content:
+
+```markdown
+## Plan-Build-Run
+
+This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
+
+- 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.
+
+**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
 
 Run a quick health check: