@sienklogic/plan-build-run 2.19.0 → 2.20.0

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.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.20.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,19 @@
         ]
       }
     ],
+    "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.20.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/cursor-pbr/.cursor-plugin/plugin.json

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

@@ -1,6 +1,6 @@
 {
   "name": "pbr",
-  "version": "2.19.0",
+  "version": "2.20.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/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/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/skills/help/SKILL.md

@@ -138,6 +138,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.