@sienklogic/plan-build-run 2.1.0 → 2.1.1

package/CHANGELOG.md

@@ -5,52 +5,54 @@ 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).
 
-## [Unreleased]
-
-## [2.0.0] - 2026-02-17
-
-### Added
-- Token-saving CLI: 6 new commands in `towline-tools.js` — `frontmatter`, `must-haves`, `phase-info`, `state update`, `roadmap update-status`, `roadmap update-plans`
-- Companion web dashboard (Express 5.x, EJS, Pico.css v2, HTMX 2.0) with overview, phase detail, roadmap, todos, and SSE live updates
-- `/dev:import` skill — Import external plan documents into Towline format
-- `/dev:note` skill — Zero-friction idea capture with promote-to-todo support
-- `/dev:setup` skill — Interactive onboarding wizard for new installations
-- `/dev:explore` skill — Socratic conversation for idea exploration
-- `/dev:continue` skill — Execute the next logical step automatically
-- `/dev:health` skill — Validate `.planning/` directory integrity
-- General agent — Lightweight Towline-aware agent for ad-hoc tasks
-- `/dev:build <N> --team` variant — Agent Teams for complex inter-agent coordination
-- `/dev:review <N> --auto-fix` variant — Auto-diagnose and fix verification failures
-- Hook spawn tests for all lifecycle hooks
-- Iterative retrieval protocol for researcher agent
-- Behavioral contexts for agent prompt refinement
-- Published to npm with OIDC trusted publishing
-
-### Changed
-- Skill count increased from 15 to 21
-- Agent count increased from 9 to 10 (added General agent)
-- Hook scripts consolidated: Write/Edit dispatch reduced from 4 spawns to 2
-- All hook scripts now use `logHook()` from `hook-logger.js` for unified logging
-- Agents reference new CLI tooling shortcuts instead of manual YAML parsing
-- README rewritten with badges, comparison table, and acknowledgments
-- Package tarball trimmed from 1.9MB to 305KB via explicit `files` field
-
-### Fixed
-- Windows CI: `parseMustHaves` now trims CRLF line endings
-- Context budget: main orchestrator no longer reads agent definitions (saves ~15% context)
-- Hook logger rotation: `.hook-log` now caps at 200 entries with JSONL format
-- Status line ANSI rendering on Windows terminals
-
-## [1.0.0] - 2025-02-07
-
-### Added
-- Initial release of Plan-Build-Run plugin for Claude Code
-- 15 skills: begin, plan, build, review, discuss, quick, debug, status, pause, resume, milestone, scan, todo, config, help
-- 9 specialized agents: researcher, planner, plan-checker, executor, verifier, integration-checker, debugger, codebase-mapper, synthesizer
-- Hook-enforced quality gates: commit validation, plan format checking, session state injection, pre-compact preservation
-- Wave-based parallel execution via Task() subagents
-- Goal-backward verification at phase and milestone levels
-- Persistent file-based state management (.planning/ directory)
-- Configurable workflow: depth, models, gates, parallelization, git branching
-- Cross-platform Node.js hook scripts (Windows + macOS + Linux)
-- Plugin distribution via npm
+## [2.1.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.1.0...plan-build-run-v2.1.1) (2026-03-16)
+
+
+### Bug Fixes
+
+* **tools:** update validate script to use plugins/pbr/ as plugin root ([d77b233](https://github.com/SienkLogic/plan-build-run/commit/d77b233bed52b2743c1e078191e37c77c4dc4927))
+
+## [2.1.0](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.0.0...plan-build-run-v2.1.0) (2026-03-16)
+
+
+### Features
+
+* **01-01:** add context_window_tokens to config schemas and template ([1f66e15](https://github.com/SienkLogic/plan-build-run/commit/1f66e1553f2836ea661378a9972817ca909ac700))
+* **01-01:** GREEN - add context_window_tokens to portableKeys in config.js and config.cjs ([1689326](https://github.com/SienkLogic/plan-build-run/commit/16893262fca489f8d5cc0b94da5eaa4750ddb930))
+* **02-01:** scale context-bridge and lib/context thresholds from config ([8c6b6e9](https://github.com/SienkLogic/plan-build-run/commit/8c6b6e9e604db3a3700aa7290e997c2da449048b))
+* **02-02:** scale track-context-budget and suggest-compact from config ([86fd842](https://github.com/SienkLogic/plan-build-run/commit/86fd842c9486c3b4d55a4d1e0579f5884ce04fe6))
+* **03-01:** add agent_checkpoint_pct to config schema and profiles ([61e6778](https://github.com/SienkLogic/plan-build-run/commit/61e6778e47bf046e9c306b0ac606727511835b0e))
+* **03-02:** update all 14 agents with context-aware checkpoint rules ([bdbdfc4](https://github.com/SienkLogic/plan-build-run/commit/bdbdfc43deb6ae309d02d5ebd39165b45bf7fecf))
+* **04-01:** add context-aware read depth to shared skill fragments ([ee2b33b](https://github.com/SienkLogic/plan-build-run/commit/ee2b33b59d303ad5a589dbd0fb687823294262df))
+* **04-02:** update build, plan, review, explore skills with 1M read depth ([c3327a1](https://github.com/SienkLogic/plan-build-run/commit/c3327a1912a2c733ea2a4c60a0dd40d608f774e5))
+* **05-01:** scale researcher cycles and output budgets for 1M context ([b2abaaf](https://github.com/SienkLogic/plan-build-run/commit/b2abaaf106b2a1ca7219921b80454273114d6ea6))
+* **05-02:** scale planner, executor, debugger, verifier budgets for 1M context ([13db078](https://github.com/SienkLogic/plan-build-run/commit/13db078a1401588a202b4c37b5c9682f86bfbfc6))
+* **05-03:** scale synthesizer, codebase-mapper, plan-checker, integration-checker budgets for 1M ([8d37be0](https://github.com/SienkLogic/plan-build-run/commit/8d37be02954be5742e6cce04beb6c5f8ea88ae74))
+* **06-01:** add cross-phase verification mode to verifier agent ([8b676c6](https://github.com/SienkLogic/plan-build-run/commit/8b676c6f08620d0444f59a83f074d41d8a501326))
+* **06-02:** surface cross-phase findings in review and build skills ([f9726d2](https://github.com/SienkLogic/plan-build-run/commit/f9726d261b7825b2a0b47461471cbfdc0dddff71))
+* **07-01:** add multi-phase lookahead to continue skill at 1M context ([089f069](https://github.com/SienkLogic/plan-build-run/commit/089f0691647d9965cbf71d6fba987d5ccdb0807f))
+* **08-01:** add pre-spawn conflict detection to build skill at 1M context ([ff8a80e](https://github.com/SienkLogic/plan-build-run/commit/ff8a80e3e4cf5423eeddddd8d77ea0aa53460004))
+
+
+### Bug Fixes
+
+* **02-02:** apply threshold scaling to hooks/ copies and fix config cache paths ([52e781c](https://github.com/SienkLogic/plan-build-run/commit/52e781c35f4f1916587e1acdc6e0561f6393bbda))
+* **03-02:** guard agent_checkpoint_pct &gt; 50 on context_window_tokens &gt;= 500k ([73573af](https://github.com/SienkLogic/plan-build-run/commit/73573af8967a2467e800cac6430f67fc943e5e87))
+* **hooks:** add allow logging to PreToolUse dispatch scripts for visibility ([b731828](https://github.com/SienkLogic/plan-build-run/commit/b73182884ca0ee0122fe419be33438e2caa6bd96))
+
+## [2.0.0](https://github.com/SienkLogic/plan-build-run/commits/plan-build-run-v2.0.0) (2026-03-16)
+
+### Features
+
+* Plan-Build-Run v2.0.0 — structured development workflow plugin for Claude Code
+* Package: `@sienklogic/plan-build-run`, command prefix: `/pbr:`
+* 41 slash commands, 29 skills, 14 agents, 49 hook scripts
+* Core workflow: new-project → discuss-phase → plan-phase → execute-phase → verify-work
+* Quick mode: `/pbr:quick` for ad-hoc tasks with atomic commits
+* Wave-based parallel execution with fresh 200k-token context per agent
+* Vite + React 18 + Express dashboard with WebSocket live updates (port 3141)
+* Configurable status line with context budget tier warnings
+* 4 derivative plugins: pbr, cursor-pbr, copilot-pbr, codex-pbr
+* Depth profiles (quick/standard/comprehensive), model profiles (quality/balanced/budget)
+* Git branching strategies: none, phase, milestone
+* 138 test suites, 3650+ tests across Node 18/20/22 on Windows, macOS, Linux

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 (~780 tests, 36 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`): 65% statements, 58% branches, 70% functions, 65% 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.
+
+28 skills: audit, begin, build, config, continue, dashboard, debug, discuss, do, explore, health, help, import, milestone, note, pause, plan, profile, quick, resume, review, scan, setup, status, statusline, test, todo, undo.
 
 ### 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.
+14 agents: audit, codebase-mapper, debugger, dev-sync, executor, general, integration-checker, nyquist-auditor, plan-checker, planner, researcher, roadmapper, synthesizer, verifier.
+
+### Hook Scripts (`hooks/*.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`.
+49 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,30 +66,39 @@ 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 (Write\|Edit) | pre-write-dispatch.js | check-skill-workflow.js, check-summary-gate.js, check-phase-boundary.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).
 
 **`${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/`** — 41 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
 
@@ -105,6 +121,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 +135,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