@sienklogic/plan-build-run 2.21.1 → 2.21.2

package/CLAUDE.md

@@ -10,18 +10,24 @@ Plan-Build-Run is a **Claude Code plugin** that provides a structured developmen
 
 - **NEVER add AI co-author lines** to git commits or PRs. No `Co-Authored-By: Claude` or similar. Only add co-author lines referencing actual human contributors.
 - **NEVER inline agent definitions** into skill prompts. Use `subagent_type: "pbr:{name}"` — Claude Code auto-loads agent definitions from `agents/`. Reading agent `.md` files wastes main context.
+- **Always use PBR workflow commands** (`/pbr:*` skills) for development work, not ad-hoc manual fixes. PBR skills enforce state tracking, verification, and artifact creation that manual edits skip. When hooks don't fire (e.g., direct file edits outside Claude Code), workflow integrity degrades silently.
+- **Post-work checklist** — before finishing any task or session, verify: (1) `npm test` passes, (2) no uncommitted changes (`git status` is clean), (3) file paths in artifacts are correct and files exist. This catches drift that accumulates during long sessions.
 
 ## 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`): 55% statements, 47% branches, 58% functions, 56% lines.
 
 Dashboard (separate dependency tree):
 ```bash
@@ -34,24 +40,27 @@ Load the plugin locally for manual testing:
 claude --plugin-dir .
 ```
 
-CI runs on Node 18/20/22 across Windows, macOS, and Linux. All three platforms must pass.
+CI runs on Node 20/22 across Windows, macOS, and Linux. All three platforms must pass.
 
 ## 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`)
 
-25 skills: audit, begin, build, config, continue, dashboard, debug, discuss, do, explore, health, help, import, milestone, note, pause, plan, quick, resume, review, scan, setup, status, statusline, 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.
+
+46 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.
 
-11 agents: audit, codebase-mapper, debugger, executor, general, integration-checker, plan-checker, planner, researcher, synthesizer, verifier.
+18 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.
+
+### Hook Scripts (`plugins/pbr/scripts/*.js`)
 
-### 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`.
+66 Node.js hook scripts that fire on Claude Code lifecycle events. Configured in `plugins/pbr/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 +68,58 @@ 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 | — (autoFormat, typeCheck, detectConsoleLogs) |
-| PostToolUse (Task) | check-subagent-output.js | — (validates agent output) |
+| PostToolUse (Write\|Edit) | context-bridge.js | — (context tier tracking) |
+| PostToolUse (Write\|Edit) | graph-update.js | — (architecture graph) |
+| PostToolUse (Write\|Edit) | architecture-guard.js | — (dependency violations) |
 | PostToolUse (Write\|Edit) | suggest-compact.js | — (context budget warnings) |
-| PostToolUse (Read) | track-context-budget.js | — (tracks reads for budget) |
+| PostToolUse (Read\|Glob\|Grep) | track-context-budget.js | — (tracks reads for budget) |
+| PostToolUse (Bash) | post-bash-triage.js | — (test output triage) |
+| PostToolUse (Bash) | context-bridge.js | — (context tier tracking) |
+| PostToolUse (Task) | check-subagent-output.js | — (validates agent output) |
+| PostToolUse (Task) | context-bridge.js | — (context tier tracking) |
+| PostToolUse (AskUserQuestion) | track-user-gates.js | — (gate tracking) |
 | 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 | check-skill-workflow.js, check-summary-gate.js, check-phase-boundary.js, check-doc-sprawl.js |
+| 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 |
+| PreToolUse (Task) | pre-task-dispatch.js | — (build/plan gates) |
+| PreToolUse (Skill) | pre-skill-dispatch.js | — (context budget, args) |
+| PreToolUse (Read) | block-skill-self-read.js | — (prevents SKILL.md self-read) |
+| PreToolUse (EnterPlanMode) | intercept-plan-mode.js | — (blocks plan mode in PBR) |
 | PreCompact | context-budget-check.js | — (preserves STATE.md) |
+| PostCompact | post-compact.js | — (post-compact recovery) |
 | Stop | auto-continue.js | — (chains next command) |
-| SubagentStart/Stop | log-subagent.js | — (tracks lifecycle) |
-| SubagentStop | event-handler.js | — (auto-verification trigger) |
+| SubagentStart | log-subagent.js | — (tracks lifecycle) |
+| SubagentStop | log-subagent.js, event-handler.js | — (auto-verification trigger) |
 | TaskCompleted | task-completed.js | — (processes task completion) |
+| InstructionsLoaded | instructions-loaded.js | — (instruction reload detection) |
+| ConfigChange | check-config-change.js | — (config change detection) |
+| WorktreeCreate | worktree-create.js | — (worktree setup) |
+| WorktreeRemove | worktree-remove.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/archive/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.js` + `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.)
+- **`plugins/pbr/commands/`** — 71 command registration files (one `.md` per command mapping to its skill)
+- **`plan-build-run/skills/shared/`** — 15 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
@@ -103,8 +136,10 @@ argument-hint: "<N> [--flag]"
 ---
 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)
+permissionMode: default    # Optional: permissions for agent (optional)
 tools:
   - Read
   - Write
@@ -112,38 +147,38 @@ tools:
 ---
 ```
 
+Model selection is config-driven via `config.json` `models` map, not via agent frontmatter.
+
 ## Data Flow
 
 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.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.
 
 ## 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