@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/CLAUDE.md

@@ -14,14 +14,18 @@ Plan-Build-Run is a **Claude Code plugin** that provides a structured developmen
 ## Commands
 
 ```bash
-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
+npm test                    # Run all Jest tests
+npm run test:coverage       # Jest with coverage enforcement
+npm run test:dashboard      # Vitest dashboard tests
+npm run lint                # ESLint on hooks and tests
+npm run build:hooks         # Bundle hooks for distribution
+npm run sync:generate       # Generate derivative plugins
+npm run sync:verify         # Verify derivative consistency
+npm run dashboard           # Launch dashboard UI
+npm run dashboard:install   # Install dashboard dependencies
 ```
 
-Coverage thresholds (enforced in `package.json`): 70% statements, 70% branches, 70% functions, 70% lines.
+Coverage thresholds (enforced in `jest.config.cjs`): 70% statements, 68% branches, 70% functions, 70% lines.
 
 Dashboard (separate dependency tree):
 ```bash
@@ -38,20 +42,23 @@ CI runs on Node 18/20/22 across Windows, macOS, and Linux. All three platforms m
 
 ## Architecture
 
-All plugin code lives under `plugins/pbr/`. Three layers:
+Three layers:
 
-### Skills (`skills/{name}/SKILL.md`)
-Markdown files with YAML frontmatter defining slash commands (`/pbr:begin`, `/pbr:plan`, etc.). Each SKILL.md is a complete prompt that tells the orchestrator what to do. Skills read state, interact with the user, and spawn agents.
+### Skills (`plan-build-run/skills/{name}/SKILL.md`)
 
-21 skills: begin, build, config, continue, debug, discuss, explore, health, help, import, milestone, note, pause, plan, quick, resume, review, scan, setup, status, todo.
+Markdown files with YAML frontmatter defining slash commands (`/pbr:new-project`, `/pbr:plan-phase`, etc.). Each SKILL.md is a complete prompt that tells the orchestrator what to do. Skills read state, interact with the user, and spawn agents.
+
+34 skills: audit, begin, build, config, continue, dashboard, debug, discuss, do, explore, health, help, import, intel, milestone, note, pause, plan, profile, quick, resume, review, scan, setup, status, statusline, test, todo, undo, and more.
 
 ### Agents (`agents/{name}.md`)
+
 Markdown files with YAML frontmatter defining specialized subagent prompts. Agents run in fresh `Task()` contexts with clean 200k token windows. Spawned via `subagent_type: "pbr:{name}"` — auto-loaded by Claude Code.
 
-10 agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer, general.
+17 agents: audit, codebase-mapper, debugger, dev-sync, executor, general, integration-checker, intel-updater, nyquist-auditor, plan-checker, planner, researcher, roadmapper, synthesizer, ui-checker, ui-researcher, verifier.
 
-### Scripts (`scripts/*.js`)
-28 Node.js hook scripts that fire on Claude Code lifecycle events. Configured in `hooks/hooks.json`. All use CommonJS, must be cross-platform (`path.join()`, not hardcoded separators), and log via `logHook()` from `hook-logger.js`.
+### Hook Scripts (`hooks/*.js`)
+
+50 Node.js hook scripts that fire on Claude Code lifecycle events. Configured in `hooks/hooks.json`. All use CommonJS, must be cross-platform (`path.join()`, not hardcoded separators), and log via `logHook()` from `hook-logger.js`.
 
 **Dispatch pattern**: Several hooks use dispatch scripts that fan out to sub-scripts based on the file being written/read:
 
@@ -59,34 +66,47 @@ Markdown files with YAML frontmatter defining specialized subagent prompts. Agen
 |------------|-------------|-------------|
 | SessionStart | progress-tracker.js | — (injects project state) |
 | PostToolUse (Write\|Edit) | post-write-dispatch.js | check-plan-format.js, check-roadmap-sync.js, check-state-sync.js |
-| PostToolUse (Write\|Edit) | post-write-quality.js | check-doc-sprawl.js, check-skill-workflow.js |
+| PostToolUse (Write\|Edit) | post-write-quality.js | — (autoFormat, typeCheck, detectConsoleLogs) |
 | PostToolUse (Task) | check-subagent-output.js | — (validates agent output) |
 | PostToolUse (Write\|Edit) | suggest-compact.js | — (context budget warnings) |
 | PostToolUse (Read) | track-context-budget.js | — (tracks reads for budget) |
 | PostToolUseFailure | log-tool-failure.js | — (logs failures) |
-| PreToolUse (Bash) | pre-bash-dispatch.js | validate-commit.js, check-dangerous-commands.js, check-phase-boundary.js |
-| PreToolUse (Write\|Edit) | pre-write-dispatch.js | — (write guards) |
+| PreToolUse (Bash) | pre-bash-dispatch.js | validate-commit.js, check-dangerous-commands.js |
+| PreToolUse (Write\|Edit) | pre-write-dispatch.js | check-skill-workflow.js, check-summary-gate.js, check-doc-sprawl.js |
 | PreCompact | context-budget-check.js | — (preserves STATE.md) |
 | Stop | auto-continue.js | — (chains next command) |
 | SubagentStart/Stop | log-subagent.js | — (tracks lifecycle) |
 | SubagentStop | event-handler.js | — (auto-verification trigger) |
 | TaskCompleted | task-completed.js | — (processes task completion) |
+| InstructionsLoaded | hook-server-client.js | — (detects instruction reload) |
+| ConfigChange | hook-server-client.js | — (config change detection) |
+| WorktreeCreate | hook-server-client.js | — (worktree setup) |
+| WorktreeRemove | hook-server-client.js | — (worktree cleanup) |
+| Notification | log-notification.js | — (notification logging) |
+| UserPromptSubmit | prompt-routing.js | — (prompt routing) |
 | SessionEnd | session-cleanup.js | — (cleanup) |
 
 **Hook exit codes**: 0 = success, 2 = block (PreToolUse hooks that reject a tool call).
 
+**Hook ordering**: When multiple PostToolUse hooks fire on the same event (e.g., Write|Edit), execution order is not guaranteed. See `references/hook-ordering.md` for ordering expectations, design rules, and known safe pairs.
+
 **`${CLAUDE_PLUGIN_ROOT}`**: Used in hooks.json to reference script paths. Claude Code expands this internally — works on all platforms without shell expansion.
 
-### Supporting directories
+### Supporting Directories
 
-- **`references/`** — Shared reference docs loaded by skills (plan format, commit conventions, UI formatting, deviation rules)
-- **`templates/`** — EJS-style `.tmpl` files for generated markdown (VERIFICATION.md, SUMMARY.md, etc.)
-- **`commands/`** — Command registration files (one `.md` per command mapping to its skill)
-- **`skills/shared/`** — 14 shared skill fragments extracted from repeated patterns across skills (config-loading, digest-select, revision-loop, context-loader-task, universal-anti-patterns, phase-argument-parsing, gate-prompts, state-loading, state-update, commit-planning-docs, context-budget, domain-probes, progress-display, error-reporting)
+- **`plan-build-run/bin/`** — CLI tools (`pbr-tools.cjs` + `lib/` modules)
+- **`plan-build-run/references/`** — Shared reference docs loaded by skills (plan format, commit conventions, UI formatting, deviation rules)
+- **`plan-build-run/templates/`** — EJS-style `.tmpl` files for generated markdown (VERIFICATION.md, SUMMARY.md, etc.)
+- **`commands/pbr/`** — 59 command registration files (one `.md` per command mapping to its skill)
+- **`plan-build-run/skills/shared/`** — 12 shared skill fragments extracted from repeated patterns across skills
+- **`plugins/`** — Derivative plugins (codex-pbr, cursor-pbr, copilot-pbr)
+- **`dashboard/`** — Vite + React 18 dashboard with Express backend
 
 ## Key Conventions
 
-**Commit format**: `{type}({scope}): {description}` — enforced by PreToolUse hook. Types: feat, fix, refactor, test, docs, chore, wip. Scopes: `{NN}-{MM}` (phase-plan), `quick-{NNN}`, `planning`, `tools`, or descriptive word.
+**Commit format**: `{type}({scope}): {description}` — enforced by PreToolUse hook. Types: feat, fix, refactor, test, docs, chore, wip, revert, perf, ci, build. Scopes should be **component names**: `hooks`, `skills`, `agents`, `cli`, `dashboard`, `templates`, `plugin`, `ci`, `config`, `tests`, `commands`, `refs`. Also accepts `quick-{NNN}`, `planning`, or descriptive words.
+
+**Releases**: Run `node scripts/release.js` to bump version, generate changelog (via git-cliff), tag, push, and create GitHub Release. The changelog groups entries by component (Hooks, Skills, Agents, etc.) based on commit scope and message keywords.
 
 **Skill frontmatter** (SKILL.md):
 ```yaml
@@ -105,6 +125,8 @@ name: agent-name
 description: "What this agent does"
 model: sonnet|inherit|haiku
 memory: none|user|project
+isolation: worktree        # Run agent in isolated git worktree (optional)
+color: <name|hex>          # Terminal color for agent output (optional)
 tools:
   - Read
   - Write
@@ -117,33 +139,31 @@ tools:
 Skills and agents communicate through files on disk, not messages:
 
 ```
-.planning/STATE.md      ← source of truth for current position
-.planning/ROADMAP.md    ← phase structure, goals, dependencies
-.planning/config.json   ← workflow settings (~62 properties across 12 top-level keys)
+.planning/STATE.md      <- source of truth for current position
+.planning/ROADMAP.md    <- phase structure, goals, dependencies
+.planning/config.json   <- workflow settings
 .planning/phases/NN-slug/
-  PLAN.md               ← written by planner, read by executor
-  SUMMARY.md            ← written by executor, read by orchestrator
-  VERIFICATION.md       ← written by verifier, read by review skill
+  PLAN.md               <- written by planner, read by executor
+  SUMMARY.md            <- written by executor, read by orchestrator
+  VERIFICATION.md       <- written by verifier, read by review skill
 ```
 
 The orchestrator stays lean (~15% context) by delegating heavy work to agents. Each agent gets a fresh context window.
 
-**Utility library**: `pbr-tools.js` is a shared Node.js library (stateLoad, configLoad, frontmatterParse, mustHavesCollect, etc.) used by multiple hook scripts. It provides CLI subcommands that agents call to avoid wasting tokens on file parsing.
+**Utility library**: `plan-build-run/bin/pbr-tools.cjs` is a shared Node.js library (stateLoad, configLoad, frontmatterParse, mustHavesCollect, etc.) used by multiple hook scripts. It provides CLI subcommands that agents call to avoid wasting tokens on file parsing.
 
 ## Testing
 
 Tests live in `tests/` using Jest. Test files mirror script names: `validate-commit.test.js` tests `validate-commit.js`.
 
+Dashboard tests live in `dashboard/tests/` using Vitest (not Jest). Run with `npm run test:dashboard`.
+
 **Fixture project**: `tests/fixtures/fake-project/.planning/` provides read-only fixture data for tests.
 
 **Mutation tests**: Use `fs.mkdtempSync()` to create temporary directories — never mutate the fixture project.
 
-**`pbr-tools.js` tests** span both `pbr-tools.test.js` and `integration.test.js`.
-
 When adding a new hook script, create a corresponding test file. Tests must pass on Windows, macOS, and Linux.
 
 ## Dashboard
 
-The dashboard (`dashboard/`) is a separate Express.js application with its own dependency tree (`dashboard/package.json`). It provides a web UI for browsing `.planning/` state. Tech: Express 5.x, EJS, Pico.css, HTMX 2.0, chokidar for file watching, SSE for live updates.
-
-Dashboard tests use Vitest (not Jest) and live in `dashboard/tests/`. Run with `npm --prefix dashboard test`.
+The dashboard (`dashboard/`) is a Vite + React 18 application with a separate Express backend (`dashboard/server/`). It provides a web UI for browsing `.planning/` state. Frontend: React 18, recharts, lucide-react. Backend: Express server with chokidar for file watching, WebSockets for live updates. CLI entry point: `dashboard/bin/cli.cjs` (default port 3141).

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2025 Towline Contributors
+Copyright (c) 2025 Lex Christopherson
+Copyright (c) 2026 SienkLogic
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal