@sienklogic/plan-build-run 2.19.0 → 2.21.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@ 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.21.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.20.0...plan-build-run-v2.21.0) (2026-02-23)
+
+
+### Features
+
+* **tools:** add help docs, concurrent tests, and discuss requirements surfacing ([02e9cc9](https://github.com/SienkLogic/plan-build-run/commit/02e9cc997d5b7d1aed3fc43cd8f8160c6e08d78b))
+* **tools:** add milestone preview subcommand across all plugins ([fa6dca7](https://github.com/SienkLogic/plan-build-run/commit/fa6dca75d78adc952a5ffffd92baf17d8dd23e8e))
+* **tools:** resolve exploration backlog — fix script bugs, add copilot hooks, improve recovery ([8a956dd](https://github.com/SienkLogic/plan-build-run/commit/8a956dd33a7182c402307d5569e0d8d37dbdaf1c))
+
+
+### Bug Fixes
+
+* **tools:** handle concurrent write corruption in flaky test across platforms ([e4e9b4d](https://github.com/SienkLogic/plan-build-run/commit/e4e9b4d524e5c08665b72a3c99555452f8e09089))
+* **tools:** handle empty string race in concurrent .active-skill test on Windows ([9cb294a](https://github.com/SienkLogic/plan-build-run/commit/9cb294a1c7db67c1fe80d9672d4580c8951011c4))
+
+## [2.20.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.19.0...plan-build-run-v2.20.0) (2026-02-23)
+
+
+### Features
+
+* **tools:** add worktree isolation, ConfigChange hook, and claude agents docs ([d704f34](https://github.com/SienkLogic/plan-build-run/commit/d704f340c636fa41f988d27a661a1e1918b04c87))
+
 ## [2.19.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.18.1...plan-build-run-v2.19.0) (2026-02-22)
 
 

package/package.json

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

package/plugins/copilot-pbr/hooks/hooks.json

@@ -139,6 +139,108 @@
         ]
       }
     ],
+    "postToolUseFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" log-tool-failure.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') log-tool-failure.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "preCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" context-budget-check.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') context-budget-check.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" auto-continue.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') auto-continue.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "subagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" log-subagent.js start",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') log-subagent.js start",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "subagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" log-subagent.js stop",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') log-subagent.js stop",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" event-handler.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') event-handler.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "taskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" task-completed.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') task-completed.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
+    "configChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "bash": "node \"$(cd \"$(dirname \"$0\")\" && pwd)/../../pbr/scripts/run-hook.js\" check-config-change.js",
+            "powershell": "node (Join-Path (Split-Path -Parent $PSScriptRoot) 'pbr\\scripts\\run-hook.js') check-config-change.js",
+            "cwd": ".",
+            "timeoutSec": 15
+          }
+        ]
+      }
+    ],
     "sessionEnd": [
       {
         "hooks": [

package/plugins/copilot-pbr/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.19.0",
+  "version": "2.21.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/skills/discuss/SKILL.md

@@ -78,7 +78,7 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
    - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:

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

@@ -91,6 +91,7 @@ Display the following reference to the user:
 |---------|-------------|
 | `/pbr:milestone new` | Start a new milestone cycle. |
 | `/pbr:milestone complete` | Archive completed milestone. |
+| `/pbr:milestone preview` | Dry-run of complete — show what would happen. |
 | `/pbr:milestone audit` | Verify milestone completion. |
 | `/pbr:milestone gaps` | Create phases to close audit gaps. |
 | `/pbr:todo add\|list\|done` | Persistent file-based todos. |
@@ -135,6 +136,7 @@ Display the following reference to the user:
 - **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
 - **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
 - **Configure**: `/pbr:config` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
 - **Tip**: Use `/pbr:quick` for creative/visual work where structured planning adds overhead without benefit.
 - **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
 - **Seeds**: `/pbr:explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.
@@ -149,6 +151,27 @@ Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how
 
 Skills automatically activate the appropriate context: `/pbr:build` uses dev context, `/pbr:discuss` uses research context, `/pbr:review` uses review context.
 
+## When to Use Quick vs Plan+Build
+
+| Use `/pbr:quick` when... | Use `/pbr:plan` + `/pbr:build` when... |
+|--------------------------|----------------------------------------|
+| Change touches ≤3 files | Change touches 4+ files |
+| ≤100 lines of code | 100+ lines of code |
+| Single subsystem | Multiple subsystems or cross-cutting |
+| No architectural decisions | Requires design choices |
+| Bug fix, small feature, docs | New feature, refactor, migration |
+
+## Setup vs Begin
+
+- **`/pbr:begin`** — Use this to start a new project. It handles everything: questioning, research, requirements, roadmap, AND config initialization. This is the standard entry point.
+- **`/pbr:setup`** — Use this only to reconfigure an existing project's settings (model profiles, gates, depth, parallelization) without re-running the full begin flow.
+
+If you're unsure, start with `/pbr:begin`. It will detect existing config and offer to reuse or overwrite.
+
+## Team Discussions
+
+The `features.team_discussions` config flag (and `/pbr:build --team`) enables **Agent Teams** for complex builds. When enabled, executor agents can coordinate with each other during parallel wave execution — sharing context about what they've built, resolving interface conflicts, and avoiding duplicate work. Best for phases where multiple plans have shared dependencies. Configure via `/pbr:config`.
+
 ## Getting Started
 
 ```

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

@@ -52,6 +52,7 @@ Examples:
   "new User Auth"    → subcommand=new, arg="User Auth"
   "complete v1.0"    → subcommand=complete, arg="v1.0"
   "complete 1.0"     → subcommand=complete, arg="v1.0" (auto-prefix v)
+  "preview v1.0"     → subcommand=preview, arg="v1.0"
   "audit v1.0"       → subcommand=audit, arg="v1.0"
   "audit"            → subcommand=audit, arg=current milestone
   "gaps"             → subcommand=gaps, arg=most recent audit
@@ -64,6 +65,7 @@ Usage: /pbr:milestone <subcommand> [version]
 Subcommands:
   new [name]       — Start a new milestone cycle
   complete [ver]   — Archive completed milestone
+  preview [ver]    — Dry-run of complete (show what would happen)
   audit [ver]      — Verify milestone completion
   gaps             — Create phases to close audit gaps
 ```
@@ -189,6 +191,65 @@ Start a new milestone cycle with new phases.
 
 ---
 
+## Subcommand: `preview`
+
+Dry-run of milestone completion — shows what would happen without making any changes.
+
+### Flow
+
+1. **Determine version:**
+   - Same logic as `complete`: use `$ARGUMENTS` or ask via AskUserQuestion
+
+2. **Identify milestone phases:**
+   - Read ROADMAP.md to find phases belonging to this milestone
+   - List each phase with its current status (from STATE.md or VERIFICATION.md)
+
+3. **Verification status check:**
+   - For each milestone phase, check if VERIFICATION.md exists and its `result` frontmatter
+   - Flag phases that are unverified or have stale verification (SUMMARY.md newer than VERIFICATION.md)
+
+4. **Preview archive structure:**
+   - Show what the archive directory would look like:
+     ```
+     .planning/milestones/v{version}/
+     ├── ROADMAP.md (snapshot)
+     ├── STATS.md (would be generated)
+     ├── REQUIREMENTS.md (snapshot)
+     └── phases/
+         ├── {NN}-{slug}/ (moved from .planning/phases/)
+         │   ├── PLAN-01.md
+         │   ├── SUMMARY.md
+         │   └── VERIFICATION.md
+         └── ...
+     ```
+
+5. **Show what would change:**
+   - Which phase directories would be moved
+   - What ROADMAP.md section would be collapsed
+   - What STATE.md updates would occur
+   - What git tag would be created
+
+6. **Display summary:**
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  MILESTONE PREVIEW — v{version}                              ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Phases to archive: {count}
+   ✓ Verified: {verified_count}
+   ⚠ Unverified: {unverified_count}
+   ⚠ Stale verification: {stale_count}
+
+   Archive location: .planning/milestones/v{version}/
+   Git tag: v{version}
+
+   Ready to complete? Run: /pbr:milestone complete v{version}
+   ```
+
+**CRITICAL**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
+
+---
+
 ## Subcommand: `complete`
 
 Archive a completed milestone and prepare for the next one.

package/plugins/copilot-pbr/skills/shared/error-recovery-strategies.md

@@ -0,0 +1,51 @@
+# Error Recovery Strategies Fragment
+
+Standard recovery patterns for skills and agents when operations fail. Reference `error-reporting.md` for display formats.
+
+## Strategy 1: Retry with Backoff
+
+For transient failures (file locks, network timeouts, tool failures):
+
+1. Wait briefly, then retry the same operation (max 2 retries)
+2. If still failing after retries, fall through to Strategy 2
+
+Use for: git operations, file writes blocked by antivirus, API calls.
+
+## Strategy 2: Degrade Gracefully
+
+When a non-critical step fails, skip it and continue:
+
+1. Log a warning using the recoverable error format
+2. Note the skipped step in SUMMARY.md `deferred` field
+3. Continue with remaining work
+
+Use for: optional validations, dashboard launch, hook logger writes, note/todo updates.
+
+## Strategy 3: Escalate to User
+
+When a critical step fails and no automated fix exists:
+
+1. Display the fatal error format with actionable suggestions
+2. Do NOT attempt workarounds that could corrupt state
+3. Suggest `/pbr:health` as the first diagnostic step
+4. If in an agent context, return the error in the agent's output so the orchestrator can relay it
+
+Use for: STATE.md corruption, missing phase directories, config parse failures, git conflicts.
+
+## Strategy 4: Checkpoint and Abort
+
+When a multi-step operation partially fails:
+
+1. Commit any completed work (don't lose progress)
+2. Update STATE.md with accurate status (not the target status)
+3. Write a `.continue-here.md` breadcrumb if mid-phase
+4. Report what completed and what remains
+
+Use for: build phase with mixed plan results, verification with partial failures.
+
+## Anti-Patterns
+
+- **Never silently swallow errors** in catch blocks — at minimum call `logHook()` with the error message
+- **Never retry destructive operations** (deletes, force-pushes, state resets)
+- **Never auto-fix by deleting user artifacts** — only delete PBR internal state files (.active-skill, .context-tracker, .auto-next)
+- **Never continue building after STATE.md write failure** — state integrity is non-negotiable

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

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.19.0",
+  "version": "2.21.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/hooks/hooks.json

@@ -196,6 +196,17 @@
         ]
       }
     ],
+    "ConfigChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'..','pbr','scripts','run-hook.js'))\" check-config-change.js",
+            "statusMessage": "Validating configuration..."
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

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

@@ -79,7 +79,7 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
    - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:

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

@@ -91,6 +91,7 @@ Display the following reference to the user:
 |---------|-------------|
 | `/pbr:milestone new` | Start a new milestone cycle. |
 | `/pbr:milestone complete` | Archive completed milestone. |
+| `/pbr:milestone preview` | Dry-run of complete — show what would happen. |
 | `/pbr:milestone audit` | Verify milestone completion. |
 | `/pbr:milestone gaps` | Create phases to close audit gaps. |
 | `/pbr:todo add\|list\|done` | Persistent file-based todos. |
@@ -135,6 +136,7 @@ Display the following reference to the user:
 - **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
 - **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
 - **Configure**: `/pbr:config` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
 - **Tip**: Use `/pbr:quick` for creative/visual work where structured planning adds overhead without benefit.
 - **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
 - **Seeds**: `/pbr:explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.
@@ -149,6 +151,27 @@ Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how
 
 Skills automatically activate the appropriate context: `/pbr:build` uses dev context, `/pbr:discuss` uses research context, `/pbr:review` uses review context.
 
+## When to Use Quick vs Plan+Build
+
+| Use `/pbr:quick` when... | Use `/pbr:plan` + `/pbr:build` when... |
+|--------------------------|----------------------------------------|
+| Change touches ≤3 files | Change touches 4+ files |
+| ≤100 lines of code | 100+ lines of code |
+| Single subsystem | Multiple subsystems or cross-cutting |
+| No architectural decisions | Requires design choices |
+| Bug fix, small feature, docs | New feature, refactor, migration |
+
+## Setup vs Begin
+
+- **`/pbr:begin`** — Use this to start a new project. It handles everything: questioning, research, requirements, roadmap, AND config initialization. This is the standard entry point.
+- **`/pbr:setup`** — Use this only to reconfigure an existing project's settings (model profiles, gates, depth, parallelization) without re-running the full begin flow.
+
+If you're unsure, start with `/pbr:begin`. It will detect existing config and offer to reuse or overwrite.
+
+## Team Discussions
+
+The `features.team_discussions` config flag (and `/pbr:build --team`) enables **Agent Teams** for complex builds. When enabled, executor agents can coordinate with each other during parallel wave execution — sharing context about what they've built, resolving interface conflicts, and avoiding duplicate work. Best for phases where multiple plans have shared dependencies. Configure via `/pbr:config`.
+
 ## Getting Started
 
 ```

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

@@ -53,6 +53,7 @@ Examples:
   "new User Auth"    → subcommand=new, arg="User Auth"
   "complete v1.0"    → subcommand=complete, arg="v1.0"
   "complete 1.0"     → subcommand=complete, arg="v1.0" (auto-prefix v)
+  "preview v1.0"     → subcommand=preview, arg="v1.0"
   "audit v1.0"       → subcommand=audit, arg="v1.0"
   "audit"            → subcommand=audit, arg=current milestone
   "gaps"             → subcommand=gaps, arg=most recent audit
@@ -65,6 +66,7 @@ Usage: /pbr:milestone <subcommand> [version]
 Subcommands:
   new [name]       — Start a new milestone cycle
   complete [ver]   — Archive completed milestone
+  preview [ver]    — Dry-run of complete (show what would happen)
   audit [ver]      — Verify milestone completion
   gaps             — Create phases to close audit gaps
 ```
@@ -190,6 +192,65 @@ Start a new milestone cycle with new phases.
 
 ---
 
+## Subcommand: `preview`
+
+Dry-run of milestone completion — shows what would happen without making any changes.
+
+### Flow
+
+1. **Determine version:**
+   - Same logic as `complete`: use `$ARGUMENTS` or ask via AskUserQuestion
+
+2. **Identify milestone phases:**
+   - Read ROADMAP.md to find phases belonging to this milestone
+   - List each phase with its current status (from STATE.md or VERIFICATION.md)
+
+3. **Verification status check:**
+   - For each milestone phase, check if VERIFICATION.md exists and its `result` frontmatter
+   - Flag phases that are unverified or have stale verification (SUMMARY.md newer than VERIFICATION.md)
+
+4. **Preview archive structure:**
+   - Show what the archive directory would look like:
+     ```
+     .planning/milestones/v{version}/
+     ├── ROADMAP.md (snapshot)
+     ├── STATS.md (would be generated)
+     ├── REQUIREMENTS.md (snapshot)
+     └── phases/
+         ├── {NN}-{slug}/ (moved from .planning/phases/)
+         │   ├── PLAN-01.md
+         │   ├── SUMMARY.md
+         │   └── VERIFICATION.md
+         └── ...
+     ```
+
+5. **Show what would change:**
+   - Which phase directories would be moved
+   - What ROADMAP.md section would be collapsed
+   - What STATE.md updates would occur
+   - What git tag would be created
+
+6. **Display summary:**
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  MILESTONE PREVIEW — v{version}                              ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Phases to archive: {count}
+   ✓ Verified: {verified_count}
+   ⚠ Unverified: {unverified_count}
+   ⚠ Stale verification: {stale_count}
+
+   Archive location: .planning/milestones/v{version}/
+   Git tag: v{version}
+
+   Ready to complete? Run: /pbr:milestone complete v{version}
+   ```
+
+**CRITICAL**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
+
+---
+
 ## Subcommand: `complete`
 
 Archive a completed milestone and prepare for the next one.

package/plugins/cursor-pbr/skills/shared/error-recovery-strategies.md

@@ -0,0 +1,51 @@
+# Error Recovery Strategies Fragment
+
+Standard recovery patterns for skills and agents when operations fail. Reference `error-reporting.md` for display formats.
+
+## Strategy 1: Retry with Backoff
+
+For transient failures (file locks, network timeouts, tool failures):
+
+1. Wait briefly, then retry the same operation (max 2 retries)
+2. If still failing after retries, fall through to Strategy 2
+
+Use for: git operations, file writes blocked by antivirus, API calls.
+
+## Strategy 2: Degrade Gracefully
+
+When a non-critical step fails, skip it and continue:
+
+1. Log a warning using the recoverable error format
+2. Note the skipped step in SUMMARY.md `deferred` field
+3. Continue with remaining work
+
+Use for: optional validations, dashboard launch, hook logger writes, note/todo updates.
+
+## Strategy 3: Escalate to User
+
+When a critical step fails and no automated fix exists:
+
+1. Display the fatal error format with actionable suggestions
+2. Do NOT attempt workarounds that could corrupt state
+3. Suggest `/pbr:health` as the first diagnostic step
+4. If in an agent context, return the error in the agent's output so the orchestrator can relay it
+
+Use for: STATE.md corruption, missing phase directories, config parse failures, git conflicts.
+
+## Strategy 4: Checkpoint and Abort
+
+When a multi-step operation partially fails:
+
+1. Commit any completed work (don't lose progress)
+2. Update STATE.md with accurate status (not the target status)
+3. Write a `.continue-here.md` breadcrumb if mid-phase
+4. Report what completed and what remains
+
+Use for: build phase with mixed plan results, verification with partial failures.
+
+## Anti-Patterns
+
+- **Never silently swallow errors** in catch blocks — at minimum call `logHook()` with the error message
+- **Never retry destructive operations** (deletes, force-pushes, state resets)
+- **Never auto-fix by deleting user artifacts** — only delete PBR internal state files (.active-skill, .context-tracker, .auto-next)
+- **Never continue building after STATE.md write failure** — state integrity is non-negotiable

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.19.0",
+  "version": "2.21.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/agents/plan-checker.md

@@ -3,6 +3,7 @@ name: plan-checker
 description: "Verifies plans will achieve phase goals before execution. Goal-backward analysis of plan quality across 10 dimensions."
 model: sonnet
 memory: none
+isolation: worktree
 tools:
   - Read
   - Bash

package/plugins/pbr/agents/verifier.md

@@ -3,6 +3,7 @@ name: verifier
 description: "Goal-backward phase verification. Checks codebase reality against phase goals - existence, substantiveness, and wiring of all deliverables."
 model: sonnet
 memory: none
+isolation: worktree
 tools:
   - Read
   - Bash

package/plugins/pbr/hooks/hooks.json

@@ -192,6 +192,17 @@
         ]
       }
     ],
+    "ConfigChange": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"var r=process.env.CLAUDE_PLUGIN_ROOT||'',m=r.match(/^\\/([a-zA-Z])\\/(.*)/);if(m)r=m[1]+String.fromCharCode(58)+String.fromCharCode(92)+m[2];require(require('path').resolve(r,'scripts','run-hook.js'))\" check-config-change.js",
+            "statusMessage": "Validating configuration..."
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/plugins/pbr/scripts/auto-continue.js

@@ -78,10 +78,16 @@ function main() {
         if (attempt === 2) {
           logHook('auto-continue', 'Stop', 'unlink-failed', { error: unlinkErr.message });
         } else {
-          // Exponential backoff: 100ms, 200ms
+          // Exponential backoff: 100ms, 200ms — use Atomics.wait for non-spinning delay
           const delay = 100 * Math.pow(2, attempt);
-          const start = Date.now();
-          while (Date.now() - start < delay) { /* busy-wait */ }
+          try {
+            const buf = new SharedArrayBuffer(4);
+            Atomics.wait(new Int32Array(buf), 0, 0, delay);
+          } catch (_atomicsErr) {
+            // Fallback for environments without SharedArrayBuffer
+            const end = Date.now() + delay;
+            while (Date.now() < end) { /* fallback busy-wait */ }
+          }
         }
       }
     }

package/plugins/pbr/scripts/check-config-change.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+/**
+ * ConfigChange hook: Validates config.json changes and warns about inconsistencies.
+ *
+ * Fires when Claude Code detects configuration file changes (v2.1.49+).
+ * Checks .planning/config.json for:
+ *   - Required top-level keys
+ *   - Semantic conflicts (e.g., parallel agents enabled with max=1)
+ *   - Version field presence
+ *
+ * Exit codes:
+ *   0 = always (advisory hook, never blocks)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { logHook } = require('./hook-logger');
+const { logEvent } = require('./event-logger');
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let input = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => { input += chunk; });
+    process.stdin.on('end', () => {
+      try {
+        resolve(JSON.parse(input));
+      } catch (_e) {
+        resolve({});
+      }
+    });
+  });
+}
+
+function findPlanningDir() {
+  let dir = process.cwd();
+  const root = path.parse(dir).root;
+  while (dir !== root) {
+    const candidate = path.join(dir, '.planning');
+    if (fs.existsSync(candidate)) return candidate;
+    dir = path.dirname(dir);
+  }
+  return null;
+}
+
+function validateConfig(configPath) {
+  const warnings = [];
+
+  let config;
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    config = JSON.parse(raw);
+  } catch (e) {
+    warnings.push(`config.json parse error: ${e.message}`);
+    return warnings;
+  }
+
+  // Check required top-level keys
+  const requiredKeys = ['version', 'features', 'models', 'gates'];
+  for (const key of requiredKeys) {
+    if (!(key in config)) {
+      warnings.push(`Missing required key: ${key}`);
+    }
+  }
+
+  // Check version
+  if (config.version && config.version < 2) {
+    warnings.push(`Config version ${config.version} is outdated — expected version 2+`);
+  }
+
+  // Check semantic conflicts
+  if (config.parallelization) {
+    const p = config.parallelization;
+    if (p.enabled && p.max_concurrent_agents === 1) {
+      warnings.push('Semantic conflict: parallelization.enabled=true but max_concurrent_agents=1');
+    }
+    if (!p.enabled && (p.plan_level || p.task_level)) {
+      warnings.push('Semantic conflict: parallelization.enabled=false but plan_level/task_level are true');
+    }
+  }
+
+  // Check model values
+  if (config.models) {
+    const validModels = ['sonnet', 'opus', 'haiku', 'inherit'];
+    for (const [role, model] of Object.entries(config.models)) {
+      if (!validModels.includes(model)) {
+        warnings.push(`Invalid model "${model}" for ${role} — expected: ${validModels.join(', ')}`);
+      }
+    }
+  }
+
+  return warnings;
+}
+
+async function main() {
+  await readStdin();
+  const startTime = Date.now();
+
+  const planningDir = findPlanningDir();
+  if (!planningDir) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no .planning dir' }, startTime);
+    process.exit(0);
+  }
+
+  const configPath = path.join(planningDir, 'config.json');
+  if (!fs.existsSync(configPath)) {
+    logHook('check-config-change', 'ConfigChange', 'skip', { reason: 'no config.json' }, startTime);
+    process.exit(0);
+  }
+
+  const warnings = validateConfig(configPath);
+
+  if (warnings.length > 0) {
+    const msg = `⚠️ Config validation (${warnings.length} issue${warnings.length > 1 ? 's' : ''}):\n${warnings.map(w => `  - ${w}`).join('\n')}`;
+
+    logHook('check-config-change', 'ConfigChange', 'warn', { warnings }, startTime);
+    logEvent('workflow', 'config-change', { warnings });
+
+    process.stdout.write(JSON.stringify({ additionalContext: msg }));
+  } else {
+    logHook('check-config-change', 'ConfigChange', 'ok', {}, startTime);
+    logEvent('workflow', 'config-change', { status: 'valid' });
+  }
+
+  process.exit(0);
+}
+
+if (require.main === module || process.argv[1] === __filename) main();
+module.exports = { validateConfig, findPlanningDir };

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

@@ -108,7 +108,12 @@ function main() {
       }
 
       process.exit(0);
-    } catch (_e) {
+    } catch (e) {
+      logHook('check-roadmap-sync', 'PostToolUse', 'error', { reason: 'parse failure in main', error: e.message });
+      const output = {
+        additionalContext: `[Roadmap Sync] Warning: Failed to parse STATE.md or ROADMAP.md — ${e.message}. Run /pbr:health to diagnose.`
+      };
+      process.stdout.write(JSON.stringify(output));
       process.exit(0);
     }
   });
@@ -326,7 +331,8 @@ function checkFilesystemDrift(roadmapContent, phasesDir) {
   let entries;
   try {
     entries = fs.readdirSync(phasesDir, { withFileTypes: true });
-  } catch (_e) {
+  } catch (e) {
+    logHook('check-roadmap-sync', 'PostToolUse', 'error', { reason: 'failed to read phases dir', error: e.message });
     return warnings;
   }
 

package/plugins/pbr/scripts/hooks-schema.json

@@ -18,6 +18,7 @@
         "SubagentStart": { "$ref": "#/definitions/hookEntryList" },
         "SubagentStop": { "$ref": "#/definitions/hookEntryList" },
         "TaskCompleted": { "$ref": "#/definitions/hookEntryList" },
+        "ConfigChange": { "$ref": "#/definitions/hookEntryList" },
         "SessionEnd": { "$ref": "#/definitions/hookEntryList" }
       },
       "additionalProperties": false

package/plugins/pbr/scripts/progress-tracker.js

@@ -100,8 +100,16 @@ function buildContext(planningDir, stateFile) {
         const ageMs = Date.now() - stateStat.mtimeMs;
         const ageMinutes = Math.round(ageMs / 60000);
         if (ageMinutes > 30) {
-          parts.push(`\nWarning: STATE.md shows status "Building" but was last modified ${ageMinutes} minutes ago. This may indicate a crashed executor. Run /pbr:health to diagnose.`);
-          logHook('progress-tracker', 'SessionStart', 'stale-building', { ageMinutes });
+          // Auto-repair: reset stale "Building" status back to "Planned"
+          try {
+            const { stateUpdate } = require('./pbr-tools');
+            stateUpdate(planningDir, { status: 'planned' });
+            parts.push(`\nAuto-repaired: STATE.md was stuck in "Building" for ${ageMinutes} minutes (likely crashed executor). Reset to "Planned". Run /pbr:build to retry.`);
+            logHook('progress-tracker', 'SessionStart', 'stale-building-repaired', { ageMinutes });
+          } catch (_repairErr) {
+            parts.push(`\nWarning: STATE.md shows status "Building" but was last modified ${ageMinutes} minutes ago. This may indicate a crashed executor. Run /pbr:health to diagnose.`);
+            logHook('progress-tracker', 'SessionStart', 'stale-building', { ageMinutes });
+          }
         }
       } catch (_e) { /* best-effort */ }
     }
@@ -191,8 +199,15 @@ function buildContext(planningDir, stateFile) {
       const ageMinutes = Math.floor(ageMs / 60000);
       if (ageMinutes > 60) {
         const skill = fs.readFileSync(activeSkillFile, 'utf8').trim();
-        parts.push(`\nWarning: .active-skill is ${ageMinutes} minutes old (skill: "${skill}"). This may be a stale lock from a crashed session or concurrent session conflict. Run /pbr:health to auto-fix, or delete .planning/.active-skill manually.`);
-        logHook('progress-tracker', 'SessionStart', 'stale-active-skill', { ageMinutes, skill });
+        // Auto-cleanup stale .active-skill lock (> 60 minutes = certainly stale)
+        try {
+          fs.unlinkSync(activeSkillFile);
+          parts.push(`\nAuto-cleaned: Stale .active-skill lock removed (skill: "${skill}", age: ${ageMinutes} minutes). Was likely from a crashed or abandoned session.`);
+          logHook('progress-tracker', 'SessionStart', 'stale-active-skill-cleaned', { ageMinutes, skill });
+        } catch (_cleanupErr) {
+          parts.push(`\nWarning: .active-skill is ${ageMinutes} minutes old (skill: "${skill}"). Could not auto-remove — delete .planning/.active-skill manually.`);
+          logHook('progress-tracker', 'SessionStart', 'stale-active-skill', { ageMinutes, skill });
+        }
       }
     } catch (_e) {
       // Ignore errors

package/plugins/pbr/scripts/track-context-budget.js

@@ -77,6 +77,11 @@ function main() {
           unique_files: tracker.files.length,
         });
         const prevCharsTotal = tracker.total_chars;
+        // Emit user-visible warning before resetting (was previously silent)
+        const resetWarning = {
+          additionalContext: `[Context Budget] Tracker reset: ${tracker.files.length} unique files read (~${Math.round(tracker.total_chars / 1000)}k chars). File list cleared but char total preserved. Consider delegating remaining work to a Task() subagent.`
+        };
+        process.stdout.write(JSON.stringify(resetWarning));
         tracker = { skill: currentSkill, reads: 0, total_chars: prevCharsTotal, files: [] };
       }
 

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

@@ -82,7 +82,7 @@ Read the following files to understand what this phase needs to accomplish:
    - What patterns have been established (`patterns` field)
    - What decisions were already made (`key_decisions` field)
 
-3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase
+3. **REQUIREMENTS.md** (if exists) — Read project requirements relevant to this phase. **CRITICAL**: After reading, display to the user which specific requirements map to this phase. Flag any requirements that could constrain decisions. If the user's discussion decisions later contradict a stated requirement, surface the contradiction immediately — don't wait until planning.
 
 4. **CONTEXT.md** (if exists in the phase directory) — Check if a prior discussion already happened
    - If CONTEXT.md exists, inform the user and use the **context-handling** pattern from `skills/shared/gate-prompts.md`:

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

@@ -94,6 +94,7 @@ Display the following reference to the user:
 |---------|-------------|
 | `/pbr:milestone new` | Start a new milestone cycle. |
 | `/pbr:milestone complete` | Archive completed milestone. |
+| `/pbr:milestone preview` | Dry-run of complete — show what would happen. |
 | `/pbr:milestone audit` | Verify milestone completion. |
 | `/pbr:milestone gaps` | Create phases to close audit gaps. |
 | `/pbr:todo add\|list\|done` | Persistent file-based todos. |
@@ -138,6 +139,7 @@ Display the following reference to the user:
 - **Depth**: `quick` (skip research, ~50% cheaper) | `standard` | `comprehensive` (~2x cost)
 - **State files**: `.planning/STATE.md` (position), `.planning/ROADMAP.md` (phases), `.planning/config.json` (settings)
 - **Configure**: `/pbr:config` to change depth, models, gates, parallelization
+- **List agents**: Run `claude agents` in your terminal to see all registered PBR agents and verify loading
 - **Tip**: Use `/pbr:quick` for creative/visual work where structured planning adds overhead without benefit.
 - **PR hygiene**: When creating PRs from a Plan-Build-Run project, `.planning/` commits can be filtered using phase branching (`git.branching: phase`) which squash-merges code-only changes to main.
 - **Seeds**: `/pbr:explore` can create seed files (`.planning/seeds/`) with trigger conditions. Seeds auto-inject into planning when their trigger phase is reached.
@@ -152,6 +154,27 @@ Plan-Build-Run includes three behavioral contexts in `contexts/` that adjust how
 
 Skills automatically activate the appropriate context: `/pbr:build` uses dev context, `/pbr:discuss` uses research context, `/pbr:review` uses review context.
 
+## When to Use Quick vs Plan+Build
+
+| Use `/pbr:quick` when... | Use `/pbr:plan` + `/pbr:build` when... |
+|--------------------------|----------------------------------------|
+| Change touches ≤3 files | Change touches 4+ files |
+| ≤100 lines of code | 100+ lines of code |
+| Single subsystem | Multiple subsystems or cross-cutting |
+| No architectural decisions | Requires design choices |
+| Bug fix, small feature, docs | New feature, refactor, migration |
+
+## Setup vs Begin
+
+- **`/pbr:begin`** — Use this to start a new project. It handles everything: questioning, research, requirements, roadmap, AND config initialization. This is the standard entry point.
+- **`/pbr:setup`** — Use this only to reconfigure an existing project's settings (model profiles, gates, depth, parallelization) without re-running the full begin flow.
+
+If you're unsure, start with `/pbr:begin`. It will detect existing config and offer to reuse or overwrite.
+
+## Team Discussions
+
+The `features.team_discussions` config flag (and `/pbr:build --team`) enables **Agent Teams** for complex builds. When enabled, executor agents can coordinate with each other during parallel wave execution — sharing context about what they've built, resolving interface conflicts, and avoiding duplicate work. Best for phases where multiple plans have shared dependencies. Configure via `/pbr:config`.
+
 ## Getting Started
 
 ```

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

@@ -57,6 +57,7 @@ Examples:
   "new User Auth"    → subcommand=new, arg="User Auth"
   "complete v1.0"    → subcommand=complete, arg="v1.0"
   "complete 1.0"     → subcommand=complete, arg="v1.0" (auto-prefix v)
+  "preview v1.0"     → subcommand=preview, arg="v1.0"
   "audit v1.0"       → subcommand=audit, arg="v1.0"
   "audit"            → subcommand=audit, arg=current milestone
   "gaps"             → subcommand=gaps, arg=most recent audit
@@ -69,6 +70,7 @@ Usage: /pbr:milestone <subcommand> [version]
 Subcommands:
   new [name]       — Start a new milestone cycle
   complete [ver]   — Archive completed milestone
+  preview [ver]    — Dry-run of complete (show what would happen)
   audit [ver]      — Verify milestone completion
   gaps             — Create phases to close audit gaps
 ```
@@ -194,6 +196,65 @@ Start a new milestone cycle with new phases.
 
 ---
 
+## Subcommand: `preview`
+
+Dry-run of milestone completion — shows what would happen without making any changes.
+
+### Flow
+
+1. **Determine version:**
+   - Same logic as `complete`: use `$ARGUMENTS` or ask via AskUserQuestion
+
+2. **Identify milestone phases:**
+   - Read ROADMAP.md to find phases belonging to this milestone
+   - List each phase with its current status (from STATE.md or VERIFICATION.md)
+
+3. **Verification status check:**
+   - For each milestone phase, check if VERIFICATION.md exists and its `result` frontmatter
+   - Flag phases that are unverified or have stale verification (SUMMARY.md newer than VERIFICATION.md)
+
+4. **Preview archive structure:**
+   - Show what the archive directory would look like:
+     ```
+     .planning/milestones/v{version}/
+     ├── ROADMAP.md (snapshot)
+     ├── STATS.md (would be generated)
+     ├── REQUIREMENTS.md (snapshot)
+     └── phases/
+         ├── {NN}-{slug}/ (moved from .planning/phases/)
+         │   ├── PLAN-01.md
+         │   ├── SUMMARY.md
+         │   └── VERIFICATION.md
+         └── ...
+     ```
+
+5. **Show what would change:**
+   - Which phase directories would be moved
+   - What ROADMAP.md section would be collapsed
+   - What STATE.md updates would occur
+   - What git tag would be created
+
+6. **Display summary:**
+   ```
+   ╔══════════════════════════════════════════════════════════════╗
+   ║  MILESTONE PREVIEW — v{version}                              ║
+   ╚══════════════════════════════════════════════════════════════╝
+
+   Phases to archive: {count}
+   ✓ Verified: {verified_count}
+   ⚠ Unverified: {unverified_count}
+   ⚠ Stale verification: {stale_count}
+
+   Archive location: .planning/milestones/v{version}/
+   Git tag: v{version}
+
+   Ready to complete? Run: /pbr:milestone complete v{version}
+   ```
+
+**CRITICAL**: This subcommand is READ-ONLY. Do not create directories, move files, modify STATE.md, modify ROADMAP.md, or create git tags. Only read and display.
+
+---
+
 ## Subcommand: `complete`
 
 Archive a completed milestone and prepare for the next one.

package/plugins/pbr/skills/shared/error-recovery-strategies.md

@@ -0,0 +1,51 @@
+# Error Recovery Strategies Fragment
+
+Standard recovery patterns for skills and agents when operations fail. Reference `error-reporting.md` for display formats.
+
+## Strategy 1: Retry with Backoff
+
+For transient failures (file locks, network timeouts, tool failures):
+
+1. Wait briefly, then retry the same operation (max 2 retries)
+2. If still failing after retries, fall through to Strategy 2
+
+Use for: git operations, file writes blocked by antivirus, API calls.
+
+## Strategy 2: Degrade Gracefully
+
+When a non-critical step fails, skip it and continue:
+
+1. Log a warning using the recoverable error format
+2. Note the skipped step in SUMMARY.md `deferred` field
+3. Continue with remaining work
+
+Use for: optional validations, dashboard launch, hook logger writes, note/todo updates.
+
+## Strategy 3: Escalate to User
+
+When a critical step fails and no automated fix exists:
+
+1. Display the fatal error format with actionable suggestions
+2. Do NOT attempt workarounds that could corrupt state
+3. Suggest `/pbr:health` as the first diagnostic step
+4. If in an agent context, return the error in the agent's output so the orchestrator can relay it
+
+Use for: STATE.md corruption, missing phase directories, config parse failures, git conflicts.
+
+## Strategy 4: Checkpoint and Abort
+
+When a multi-step operation partially fails:
+
+1. Commit any completed work (don't lose progress)
+2. Update STATE.md with accurate status (not the target status)
+3. Write a `.continue-here.md` breadcrumb if mid-phase
+4. Report what completed and what remains
+
+Use for: build phase with mixed plan results, verification with partial failures.
+
+## Anti-Patterns
+
+- **Never silently swallow errors** in catch blocks — at minimum call `logHook()` with the error message
+- **Never retry destructive operations** (deletes, force-pushes, state resets)
+- **Never auto-fix by deleting user artifacts** — only delete PBR internal state files (.active-skill, .context-tracker, .auto-next)
+- **Never continue building after STATE.md write failure** — state integrity is non-negotiable