@sienklogic/plan-build-run 2.18.1 → 2.19.1

package/README.md

@@ -1,300 +1,535 @@
 <p align="center">
-  <img src="./assets/pbr_banner_logo.png" alt="Plan-Build-Run Logo" width="550" />
+  <img src="./docs/assets/pbr_banner_logo.png" alt="Plan-Build-Run Logo" width="550" />
 </p>
 
 <p align="center">
-  <strong>Context-engineered development workflow for Claude Code, Cursor, and GitHub Copilot CLI.</strong>
+  <strong>Context-engineered development workflow for Claude Code, Cursor, GitHub Copilot CLI, OpenAI Codex, and OpenCode.</strong>
   <br />
   Build ambitious multi-phase software without quality degradation.
-  <br />
-  Works with any Claude Code plan. Shines on Max. Now available for Cursor IDE and GitHub Copilot CLI.
-  <br />
-  <br />
-  <a href="#why-plan-build-run">Why Plan-Build-Run?</a> &bull;
-  <a href="#getting-started">Getting Started</a> &bull;
-  <a href="#commands">Commands</a> &bull;
-  <a href="#how-it-works">How It Works</a> &bull;
-  <a href="https://github.com/SienkLogic/plan-build-run/wiki">Wiki</a> &bull;
-  <a href=".github/CONTRIBUTING.md">Contributing</a>
 </p>
 
 <p align="center">
-  <a href="https://github.com/SienkLogic/plan-build-run/actions"><img src="https://img.shields.io/github/actions/workflow/status/SienkLogic/plan-build-run/ci.yml?style=for-the-badge&label=CI&logo=github" alt="CI Status" /></a>
+  <a href="https://github.com/SienkLogic/plan-build-run/actions"><img src="https://img.shields.io/github/actions/workflow/status/SienkLogic/plan-build-run/test.yml?branch=main&style=for-the-badge&logo=github&label=CI" alt="CI Status" /></a>
   <a href="#install"><img src="https://img.shields.io/badge/Claude_Code-Plugin-7C3AED?style=for-the-badge&logo=anthropic&logoColor=white" alt="Claude Code Plugin" /></a>
   <a href="https://github.com/SienkLogic/plan-build-run/wiki/Cursor-IDE"><img src="https://img.shields.io/badge/Cursor-Plugin-00A67E?style=for-the-badge&logo=cursor&logoColor=white" alt="Cursor Plugin" /></a>
   <a href="https://github.com/SienkLogic/plan-build-run/wiki/Copilot-CLI"><img src="https://img.shields.io/badge/Copilot_CLI-Plugin-1F6FEB?style=for-the-badge&logo=github&logoColor=white" alt="Copilot CLI Plugin" /></a>
+  <br />
+  <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white&color=CB3837" alt="npm version" /></a>
   <img src="https://img.shields.io/badge/Node.js-18%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18+" />
+  <a href="https://github.com/SienkLogic/plan-build-run"><img src="https://img.shields.io/github/stars/SienkLogic/plan-build-run?style=for-the-badge&logo=github&color=181717" alt="GitHub stars" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/github/license/SienkLogic/plan-build-run?style=for-the-badge" alt="License" /></a>
-  <a href="https://www.npmjs.com/package/@sienklogic/plan-build-run"><img src="https://img.shields.io/npm/v/@sienklogic/plan-build-run?style=for-the-badge&logo=npm&logoColor=white" alt="npm" /></a>
-  <img src="https://img.shields.io/badge/Tests-1213_passing-brightgreen?style=for-the-badge" alt="1213 Tests" />
+</p>
+
+<p align="center">
+  <a href="#the-problem">Problem</a> &bull;
+  <a href="#install">Install</a> &bull;
+  <a href="#quick-start">Quick Start</a> &bull;
+  <a href="#commands">Commands</a> &bull;
+  <a href="#architecture">Architecture</a> &bull;
+  <a href="#configuration">Config</a> &bull;
+  <a href="docs/USER-GUIDE.md">User Guide</a> &bull;
+  <a href="https://github.com/SienkLogic/plan-build-run/wiki">Wiki</a>
 </p>
 
 ---
 
 ## The Problem
 
-Claude Code is remarkably capable...until your context window fills up. As tokens accumulate during a long session, reasoning quality degrades, hallucinations increase, and the model starts losing track of earlier decisions. This is **context rot**, and it's the primary failure mode when building anything beyond a single-session project.
-
-**Plan-Build-Run solves this.** It keeps your main orchestrator under ~15% context usage by delegating heavy work to fresh subagent contexts, each getting a clean 200k token window. All state lives on disk. Sessions are killable at any second without data loss. Whether you're on a free tier or Max 5x, wasted context means wasted budget, and context rot is the biggest source of waste.
-
-## Why Plan-Build-Run?
-
-Most AI coding tools treat context as infinite. They index your codebase, track your edits, and hope the model keeps up. That works for single-file changes. It falls apart when you're building something that takes days, spans dozens of files, and requires decisions made on Monday to still hold on Friday.
+Claude Code is remarkably capable — until your context window fills up. As tokens accumulate, reasoning quality degrades, hallucinations increase, and the model loses track of earlier decisions. This is **context rot**.
 
-Plan-Build-Run takes a different approach: **structured context isolation**. Instead of stuffing everything into one session, it delegates each operation to a fresh subagent with a clean 200k token window and coordinates through files on disk.
+**Plan-Build-Run solves this.** It keeps your orchestrator lean by delegating heavy work to fresh subagent contexts. All state lives on disk. Sessions are killable without data loss. Whether you're on Free or Max 5x, wasted context means wasted budget.
 
 <p align="center">
-  <img src="./assets/pbr-demo.gif" alt="Plan-Build-Run workflow: begin → plan → build → review" width="800" />
+  <img src="./docs/assets/pbr-demo.gif" alt="Plan-Build-Run workflow demo" width="800" />
 </p>
 
-Goal-backward verification, lifecycle hooks, wave-based parallelism, kill-safe state, and more. See **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** for the full comparison and differentiators.
-
-> **When to use Plan-Build-Run:** Multi-phase projects where quality matters. New features spanning 5+ files, large refactors, greenfield builds, anything that would take more than one Claude Code session to complete. Use `depth: quick` or `depth: standard` to control agent spawn count per phase.
+> **Use PBR for:** Multi-phase projects — new features spanning 5+ files, large refactors, greenfield builds. Use `depth: quick` on Free/Pro, `depth: standard` on Max, `depth: comprehensive` on Max 5x.
 >
-> **When to skip it:** Single-file fixes, quick questions, one-off scripts. Use `/pbr:quick` for atomic commits without full workflow overhead: single executor spawn, no research or verification agents.
-
-Works on every Claude Code plan. Use `depth: quick` on Free/Pro, `depth: standard` on Max, `depth: comprehensive` on Max 5x. See **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart#plan-build-run-on-different-claude-code-plans)** for tier-specific guidance.
+> **Skip PBR for:** Single-file fixes, quick questions, one-off scripts. Use `/pbr:quick` for atomic commits without full workflow overhead.
 
 ---
 
-## Getting Started
-
-### Prerequisites
-
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.45+ &nbsp;(`claude --version`)
-- Node.js 18+
+## Install
 
-### Install
+**Claude Code Plugin (recommended):**
 
 ```bash
-# From your terminal
 claude plugin marketplace add SienkLogic/plan-build-run
 claude plugin install pbr@plan-build-run
-
-# Or from inside a Claude Code session
-/plugin marketplace add SienkLogic/plan-build-run
-/plugin install pbr@plan-build-run
 ```
 
-All `/pbr:*` commands are now available globally.
+Verify: `/pbr:help`
 
 <details>
-<summary><strong>Install scopes</strong></summary>
+<summary><strong>Other install methods</strong></summary>
+
+**npx (alternative):**
+
+```bash
+npx @sienklogic/plan-build-run@latest
+```
+
+The installer prompts for runtime (Claude Code, OpenCode, Gemini, Codex) and location (global/local).
+
+**Non-interactive (Docker, CI, Scripts):**
+
+```bash
+npx @sienklogic/plan-build-run --claude --global    # Claude Code
+npx @sienklogic/plan-build-run --opencode --global   # OpenCode
+npx @sienklogic/plan-build-run --gemini --global     # Gemini CLI
+npx @sienklogic/plan-build-run --codex --global      # Codex CLI
+npx @sienklogic/plan-build-run --all --global        # All runtimes
+```
+
+**Plugin install scopes:**
 
 | Scope | Command | Effect |
 |-------|---------|--------|
 | **Global** (default) | `claude plugin install pbr@plan-build-run` | Available in all projects |
-| **Project only** | `claude plugin install pbr@plan-build-run --scope local` | This project only, gitignored |
-| **Team project** | `claude plugin install pbr@plan-build-run --scope project` | Shared via git, teammates get prompted |
+| **Project only** | `claude plugin install pbr@plan-build-run --scope local` | This project only |
+| **Team project** | `claude plugin install pbr@plan-build-run --scope project` | Shared via git |
+
+**Cursor IDE:** See [Cursor Plugin](https://github.com/SienkLogic/plan-build-run/wiki/Cursor-IDE) wiki page.
+
+**GitHub Copilot CLI:** See [Copilot CLI](https://github.com/SienkLogic/plan-build-run/wiki/Copilot-CLI) wiki page.
+
+**Codex CLI:** See [Codex](plugins/codex-pbr/README.md) plugin README.
+
+**Development install:**
+
+```bash
+git clone https://github.com/SienkLogic/plan-build-run.git
+cd plan-build-run && npm install
+claude --plugin-dir .   # Load as local plugin
+```
 
 </details>
 
-<details>
-<summary><strong>Install for Cursor IDE</strong></summary>
+---
 
-Plan-Build-Run also works in Cursor. The setup script symlinks rules and agents into your project's `.cursor/` directory.
+## Quick Start
 
-**macOS / Linux:**
 ```bash
-cd /path/to/your/project
-bash /path/to/plan-build-run/plugins/cursor-pbr/setup.sh
+cd your-project && claude
 ```
 
-**Windows (PowerShell):**
-```powershell
-cd C:\path\to\your\project
-powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\cursor-pbr\setup.ps1
+```
+/pbr:new-project          # Questions → research → requirements → roadmap
+/pbr:plan-phase 1         # Research + plan the first phase
+/pbr:execute-phase 1      # Build with parallel agents, atomic commits
+/pbr:verify-work 1        # Confirm the codebase matches requirements
 ```
 
-Both plugins share the same `.planning/` directory — start a project in Claude Code, continue in Cursor, or vice versa. See [`plugins/cursor-pbr/README.md`](plugins/cursor-pbr/README.md) for full details.
+Repeat **plan → execute → verify** for each phase. Kill your terminal anytime — `/pbr:resume-work` picks up where you left off.
 
-</details>
+> **Already have code?** Run `/pbr:map-codebase` first to analyze your existing stack, then `/pbr:new-project`.
 
-<details>
-<summary><strong>Install for GitHub Copilot CLI</strong></summary>
+---
 
-Plan-Build-Run also works in GitHub Copilot CLI. The setup script installs PBR as a Copilot CLI plugin and symlinks agents into your project.
+## Architecture
 
-**macOS / Linux:**
-```bash
-cd /path/to/your/project
-bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh
-```
+PBR is a **thin orchestrator** that delegates heavy work to fresh subagent contexts via `Task()`. Data flows through files on disk, not through messages.
 
-**Windows (PowerShell):**
-```powershell
-cd C:\path\to\your\project
-powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1
 ```
+Main Session (~15% context)
+  │
+  ├── Task(researcher)  →  writes .planning/research/
+  ├── Task(planner)     →  writes PLAN.md files
+  ├── Task(executor)    →  builds code, creates commits
+  ├── Task(executor)    →  (parallel, same wave)
+  └── Task(verifier)    →  checks codebase against must-haves
+```
+
+Plans are grouped into **waves** based on dependencies. Within each wave, plans run in parallel. Waves run sequentially. Each executor gets a fresh context window — zero accumulated garbage.
 
-All three plugins share the same `.planning/` directory — start in any tool, continue in another. See [`plugins/copilot-pbr/README.md`](plugins/copilot-pbr/README.md) for full details.
+<details>
+<summary><strong>Three layers: Skills → Agents → Hooks</strong></summary>
+
+### Skills (39 slash commands)
+
+Markdown files with YAML frontmatter defining `/pbr:*` slash commands. Each skill is a complete prompt that reads state, interacts with the user, and spawns agents. Skills are the user-facing interface.
+
+### Agents (17 specialized subagents)
+
+Markdown files defining agent prompts that run in fresh `Task()` contexts with clean 200k token windows. Each agent type has a specific role:
+
+| Agent | Role |
+|-------|------|
+| `researcher` | Domain research before planning |
+| `planner` | Create execution plans with task breakdown |
+| `plan-checker` | Validate plans across 10 dimensions before build |
+| `executor` | Build code, write tests, create atomic commits |
+| `verifier` | Goal-backward verification against must-haves |
+| `debugger` | Hypothesis-driven systematic debugging |
+| `codebase-mapper` | Parallel codebase analysis |
+| `integration-checker` | Cross-phase integration and E2E flow verification |
+
+### Hooks (26 lifecycle hooks)
+
+Node.js scripts that fire on Claude Code lifecycle events — enforcing commit format, validating agent dispatch, tracking context budget, syncing state files, and more. Hooks provide **deterministic guardrails** that don't rely on the LLM remembering to follow rules.
 
 </details>
 
 <details>
-<summary><strong>Dashboard (Optional)</strong></summary>
+<summary><strong>Hook server architecture</strong></summary>
 
-Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser.
+### Persistent HTTP Hook Server
 
-```bash
-# One-time install of dashboard dependencies
-npm run dashboard:install
+PBR runs a persistent HTTP server (`hook-server.js`) on `localhost:19836` that handles hook dispatch. Instead of spawning a new Node.js process for every hook event, Claude Code sends HTTP POST requests to the server, which routes them to the appropriate handler.
 
-# Launch the dashboard (defaults to current directory)
-npm run dashboard
+**Why a hook server?**
 
-# Or specify a project directory and port
-npm run dashboard -- --dir /path/to/your/project --port 3000
-```
+- **Performance**: HTTP dispatch is 2-30ms vs 200-500ms for process spawning per hook
+- **Shared state**: In-memory config cache, circuit breaker state, and event log shared across all hooks
+- **Consolidated routing**: 38 handler routes registered in a single `initRoutes()` function
+- **Fail-open design**: Connection failures and timeouts are non-blocking — Claude Code continues normally
+
+**How it works:**
 
-Or launch it directly from a Claude Code, Cursor, or Copilot CLI session:
 ```
-/pbr:dashboard
+Claude Code                     Hook Server (localhost:19836)
+    │                                  │
+    ├── POST /hook/PreToolUse/Bash  →  │── pre-bash-dispatch.js
+    │   ← { decision: "allow" }        │     ├── validate-commit.js
+    │                                  │     └── check-dangerous-commands.js
+    │                                  │
+    ├── POST /hook/PostToolUse/Write → │── post-write-dispatch.js
+    │   ← { additionalContext: ... }   │     ├── check-plan-format.js
+    │                                  │     ├── check-roadmap-sync.js
+    │                                  │     └── check-state-sync.js
+    │                                  │
+    ├── POST /hook/PostToolUse/Read  → │── track-context-budget.js
+    │   ← { }                          │
+    │                                  │
+    └── GET /health                  → │── { status: "ok", uptime: ... }
 ```
 
-Opens at `http://127.0.0.1:3000` with live updates via SSE.
+**Lifecycle events handled:**
+
+| Event | Hooks | Purpose |
+|-------|-------|---------|
+| `PreToolUse` | 6 routes | Commit validation, dangerous command blocking, write policies, agent dispatch gates, context budget enforcement |
+| `PostToolUse` | 10 routes | Context tracking, plan/state sync, architecture guard, subagent output validation, test result analysis |
+| `PostToolUseFailure` | 1 route | Tool failure logging |
+| `SubagentStart/Stop` | 2 routes | Agent lifecycle tracking, auto-verification triggers |
+| `TaskCompleted` | 1 route | Task result processing |
+| `PreCompact/PostCompact` | 2 routes | State preservation across context compaction |
+| `ConfigChange` | 1 route | Config validation |
+| `SessionEnd` | 1 route | Cleanup and graceful server shutdown |
+| `UserPromptSubmit` | 1 route | Prompt routing |
+| `Notification` | 1 route | Notification logging |
+
+**5 hooks remain as command-type** (process-spawned): `SessionStart`, `Stop`, `InstructionsLoaded`, `WorktreeCreate`, `WorktreeRemove` — these need stdin/stdout interaction that HTTP can't provide.
+
+**Server reliability features:**
+
+- **PID lockfile** with port tracking (`.hook-server.pid`)
+- **EADDRINUSE recovery** — tries sequential ports if configured port is taken
+- **Crash recovery** — auto-restart on health check failure
+- **MSYS path normalization** — Windows Git Bash compatibility
+- **Per-hook timing** — 100ms alert threshold, `hooks perf` CLI for analysis
+- **Circuit breaker** — tracks handler failures to avoid cascading errors
 
 </details>
 
-### Quick Start (Max / Max 5x)
+<details>
+<summary><strong>File-based state (the data model)</strong></summary>
 
-Full pipeline with parallel research and multi-agent builds. Best experience.
+Skills and agents communicate through files on disk, not messages:
 
-```bash
-cd your-project && claude
 ```
+.planning/
+  ├── STATE.md           ← source of truth for current position
+  ├── ROADMAP.md         ← phase structure, goals, dependencies
+  ├── PROJECT.md         ← project metadata, locked decisions
+  ├── REQUIREMENTS.md    ← requirements with completion tracking
+  ├── config.json        ← workflow settings
+  └── 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
 ```
-/pbr:begin                # Plan-Build-Run asks about your project, researches the domain,
-                          # scopes requirements, and generates a phased roadmap
 
-/pbr:plan 1               # Research + plan the first phase
-/pbr:build 1              # Build it with parallel agents, atomic commits
-/pbr:review 1             # Verify the codebase matches requirements
-/pbr:plan 2               # Repeat for next phase
+Every task gets its own **atomic commit** immediately after completion:
+
+```bash
+abc123f docs(08-02): complete user registration plan
+def456g feat(08-02): add email confirmation flow
+hij789k feat(08-02): implement password hashing
 ```
 
-That's the whole cycle. Everything lands in a `.planning/` directory. Kill your terminal anytime, `/pbr:resume` picks up where you left off.
+The orchestrator never does heavy lifting. It spawns agents, waits, integrates results. Your main context stays at 30-40% while thousands of lines of code are written in parallel fresh contexts.
 
-### Quick Start (Pro / Free)
+</details>
 
-Lighter workflow that still gives you structured state tracking and clean commits.
+---
+
+## Commands
+
+### Core Workflow
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:new-project` | Full init: questions → research → requirements → roadmap |
+| `/pbr:discuss-phase [N]` | Capture implementation decisions before planning |
+| `/pbr:plan-phase [N]` | Research + plan + verify for a phase |
+| `/pbr:execute-phase <N>` | Execute all plans in parallel waves |
+| `/pbr:verify-work [N]` | User acceptance testing with auto-diagnosis |
+| `/pbr:continue` | Auto-advance to the next logical step |
+| `/pbr:quick` | Ad-hoc task with atomic commit (no full workflow) |
+
+### Navigation & Session
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:progress` | Where am I? What's next? |
+| `/pbr:resume-work` | Restore from last session |
+| `/pbr:pause-work` | Create handoff when stopping mid-phase |
+| `/pbr:map-codebase` | Analyze existing codebase before new-project |
+
+<details>
+<summary><strong>All commands</strong></summary>
+
+**Milestone Management:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:audit-milestone` | Verify milestone achieved its definition of done |
+| `/pbr:complete-milestone` | Archive milestone, tag release |
+| `/pbr:new-milestone` | Start next version |
+| `/pbr:plan-milestone-gaps` | Create phases to close gaps from audit |
+
+**Phase Management:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:add-phase` | Append phase to roadmap |
+| `/pbr:insert-phase [N]` | Insert urgent work between phases |
+| `/pbr:remove-phase [N]` | Remove future phase, renumber |
+| `/pbr:list-phase-assumptions [N]` | See Claude's intended approach before planning |
+
+**Autonomous Mode:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:autonomous` | Run multiple phases hands-free (discuss → plan → build → verify) |
+| `/pbr:do [text]` | Route freeform text to the right PBR skill automatically |
+
+**Quality & Debugging:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:debug [desc]` | Systematic debugging with persistent hypothesis tracking |
+| `/pbr:test` | Generate tests for completed phase code |
+| `/pbr:validate-phase` | Post-build quality gate with test gap detection |
+| `/pbr:audit [--today]` | Review past sessions for workflow compliance |
+| `/pbr:health [--repair]` | Validate `.planning/` integrity |
+
+**Knowledge & Ideas:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:note [text]` | Quick idea capture (persists across sessions) |
+| `/pbr:todo [text]` | File-based persistent todos |
+| `/pbr:explore [topic]` | Think through approaches, route insights |
+| `/pbr:intel` | Refresh or query codebase intelligence |
+
+**Utilities:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:settings` | Configure model profile and workflow |
+| `/pbr:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
+| `/pbr:dashboard` | Launch web dashboard (Vite + React) |
+| `/pbr:statusline` | Install terminal status line |
+| `/pbr:scan` | Analyze an existing codebase |
+| `/pbr:ship` | Create a rich PR from planning artifacts |
+| `/pbr:release` | Generate changelog and release notes |
+| `/pbr:help` | Show all commands and usage |
+| `/pbr:update` | Update PBR with changelog preview |
+
+</details>
+
+See the **[User Guide](docs/USER-GUIDE.md)** for all flags, cost-by-depth tables, and detailed descriptions.
+
+---
+
+## Configuration
+
+PBR stores settings in `.planning/config.json`. Configure during `/pbr:new-project` or update with `/pbr:settings`.
+
+| Setting | Options | Default | What it controls |
+|---------|---------|---------|------------------|
+| `mode` | `autonomous`, `interactive` | `interactive` | Auto-approve vs confirm at each step |
+| `depth` | `quick`, `standard`, `comprehensive` | `standard` | Agent spawn count and research scope |
+| `context_window_tokens` | `100000`-`2000000` | `200000` | Context window size — set to `1000000` for Opus 1M |
+
+### Model Profiles
+
+| Profile | Planning | Execution | Verification |
+|---------|----------|-----------|--------------|
+| `quality` | Opus | Opus | Sonnet |
+| `balanced` (default) | Opus | Sonnet | Sonnet |
+| `budget` | Sonnet | Sonnet | Haiku |
 
-```bash
-cd your-project && claude
-```
 ```
-/pbr:setup                # Create .planning/ structure without the heavy research step
-/pbr:plan 1 --skip-research   # Plan without spawning a research agent
-/pbr:build 1              # Build it
-/pbr:quick                # For one-off tasks: single agent, atomic commit, lowest cost
+/pbr:set-profile quality
 ```
 
-Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
+<details>
+<summary><strong>More configuration options</strong></summary>
 
-### Quick Reference
+**Workflow Agents:**
 
-| What you want | Command |
-|---------------|---------|
-| Start a new project | `/pbr:begin` (or `/pbr:setup` for lightweight init) |
-| Plan a phase | `/pbr:plan 1` |
-| Build a phase | `/pbr:build 1` |
-| Verify a phase | `/pbr:review 1` |
-| Do something quick | `/pbr:quick` |
-| See where you are | `/pbr:status` |
-| Resume after restart | `/pbr:resume` |
-| Auto-advance | `/pbr:continue` |
-| Change settings | `/pbr:config` |
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| `features.research_phase` | `true` | Research domain before planning each phase |
+| `features.plan_checking` | `true` | Verify plans before execution (always-on, lighter check for quick depth) |
+| `features.goal_verification` | `true` | Confirm must-haves after execution |
+| `features.auto_advance` | `false` | Auto-chain discuss → plan → execute |
+| `features.inline_simple_tasks` | `true` | Simple tasks run inline without subagent overhead |
+| `features.self_verification` | `true` | Executor self-checks before presenting output |
 
----
+Override per-invocation: `/pbr:plan-phase --skip-research` or `--skip-verify`
 
-## Commands
+**Parallelization:**
 
-### Core Workflow
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| `parallelization.enabled` | `true` | Parallel plan execution within waves |
+| `parallelization.max_concurrent_agents` | `5` | Max simultaneous executor subagents |
+| `parallelization.min_plans_for_parallel` | `2` | Minimum plans in a wave to trigger parallel execution |
+
+**Git Branching:**
+
+| Strategy | Behavior |
+|----------|----------|
+| `none` (default) | Commits to current branch |
+| `phase` | Branch per phase, merge at completion |
+| `milestone` | One branch for entire milestone |
 
-| Command | Description | Agents |
-|---------|-------------|--------|
-| `/pbr:begin` | Start a new project: questioning, research, requirements, roadmap | 4-6 (quick: 2-3) |
-| `/pbr:plan <N>` | Plan a phase: research, plan creation, verification loop | 2-3 (quick: 1-2) |
-| `/pbr:build <N>` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |
-| `/pbr:review <N>` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |
+**Hook Server:**
 
-See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 22 commands with flags, cost-by-depth tables, and detailed descriptions.
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| `hook_server.enabled` | `true` | Route hooks through persistent HTTP server |
+| `hook_server.port` | `19836` | TCP port for hook server (localhost only) |
+| `hook_server.event_log` | `true` | Log all hook events to `.hook-events.jsonl` |
+
+See the [User Guide](docs/USER-GUIDE.md#configuration-reference) for the full config schema.
+
+</details>
 
 ---
 
-## How It Works
+## Security
 
-Plan-Build-Run is a **thin orchestrator** that delegates heavy work to fresh subagent contexts via `Task()`. Data flows through files on disk, not through messages.
+PBR reads files to understand your project. Protect secrets with Claude Code's deny list:
 
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(.env)", "Read(.env.*)", "Read(**/secrets/*)",
+      "Read(**/*credential*)", "Read(**/*.pem)", "Read(**/*.key)"
+    ]
+  }
+}
 ```
-Main Session (~15% context)
-  │
-  ├── Task(researcher)  ──▶  writes .planning/research/
-  ├── Task(planner)     ──▶  writes PLAN.md files
-  ├── Task(executor)    ──▶  builds code, creates commits
-  ├── Task(executor)    ──▶  (parallel, same wave)
-  └── Task(verifier)    ──▶  checks codebase against must-haves
+
+<details>
+<summary><strong>Recommended permissions setup</strong></summary>
+
+PBR works best with frictionless automation:
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+Or configure granular permissions in `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(date:*)", "Bash(echo:*)", "Bash(cat:*)", "Bash(ls:*)",
+      "Bash(mkdir:*)", "Bash(wc:*)", "Bash(head:*)", "Bash(tail:*)",
+      "Bash(sort:*)", "Bash(grep:*)", "Bash(tr:*)",
+      "Bash(git add:*)", "Bash(git commit:*)", "Bash(git status:*)",
+      "Bash(git log:*)", "Bash(git diff:*)", "Bash(git tag:*)"
+    ]
+  }
+}
 ```
 
-See **[Architecture](https://github.com/SienkLogic/plan-build-run/wiki/Architecture)** for key concepts, the token-saving CLI, data flow details, and supporting directories.
+</details>
 
 ---
 
-## Deep Dive
+## Troubleshooting
 
-| Topic | Description |
-|-------|-------------|
-| **[Agents](https://github.com/SienkLogic/plan-build-run/wiki/Agents)** | 10 specialized agents with configurable model profiles and file-based communication |
-| **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 12 config keys, depth/model profiles, 16+ feature toggles |
-| **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 15 lifecycle hooks that enforce discipline at zero token cost |
-| **[Project Structure](https://github.com/SienkLogic/plan-build-run/wiki/Project-Structure)** | The `.planning/` directory layout, key files, and file ownership |
-| **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI with live updates for browsing project state |
-| **[Cursor IDE](https://github.com/SienkLogic/plan-build-run/wiki/Cursor-IDE)** | Cursor plugin installation and cross-IDE workflow |
-| **[Copilot CLI](https://github.com/SienkLogic/plan-build-run/wiki/Copilot-CLI)** | GitHub Copilot CLI plugin: installation, hooks, and differences |
-| **[Philosophy](https://github.com/SienkLogic/plan-build-run/wiki/Philosophy)** | Design principles and platform alignment strategy |
-| **[What Sets It Apart](https://github.com/SienkLogic/plan-build-run/wiki/What-Sets-It-Apart)** | Feature comparison and key differentiators |
+<details>
+<summary><strong>Common issues</strong></summary>
 
----
+**Commands not found after install?**
+- Restart your runtime to reload commands
+- Plugin: verify with `claude plugin list`
+- npx: verify files exist in `~/.claude/commands/pbr/`
 
-## Local Development
+**Using Docker?** Set `CLAUDE_CONFIG_DIR` before installing:
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @sienklogic/plan-build-run --global
+```
 
+**Hook server not starting?**
+- Check port availability: `curl http://localhost:19836/health`
+- Review logs: `.planning/.hook-events.jsonl`
+- Run `hooks perf` via pbr-tools for timing analysis
+
+**Uninstalling:**
 ```bash
-# Clone and install
-git clone https://github.com/SienkLogic/plan-build-run.git
-cd plan-build-run
-npm install
+# Plugin
+claude plugin uninstall pbr@plan-build-run
 
-# Run tests (1213 tests, 44 suites)
-npm test
+# npx
+npx @sienklogic/plan-build-run --claude --global --uninstall
+```
 
-# Lint
-npm run lint
+</details>
 
-# Validate plugin structure
-npm run validate
+---
 
-# Load locally for manual testing
-claude --plugin-dir .
-```
+## Learn More
 
-CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
+| Resource | Description |
+|----------|-------------|
+| **[User Guide](docs/USER-GUIDE.md)** | Full configuration reference, all command flags, cost tables |
+| **[Wiki](https://github.com/SienkLogic/plan-build-run/wiki)** | Agents, hooks, project structure, philosophy, platform details |
+| **[Contributing](.github/CONTRIBUTING.md)** | Development setup, testing, contribution guidelines |
+| **[Dashboard](https://github.com/SienkLogic/plan-build-run/wiki/Dashboard)** | Web UI for browsing `.planning/` state |
+| **[Changelog](CHANGELOG.md)** | Release history grouped by component |
 
 ---
 
-## Stats
+## Local Development
+
+```bash
+git clone https://github.com/SienkLogic/plan-build-run.git
+cd plan-build-run && npm install
+npm test          # 6500+ tests across 296 suites
+claude --plugin-dir .   # Load locally for testing
+```
 
-| Metric | Count |
-|--------|-------|
-| Skills (slash commands) | 22 |
-| Specialized agents | 10 |
-| Hook scripts | 28 |
-| Supported platforms | 3 (Claude Code, Cursor, Copilot CLI) |
-| Tests | 1213 |
-| Test suites | 44 |
-| Config toggles | 12 top-level keys |
+CI runs on Node 18/20/22 across Windows, macOS, and Linux (9 platform combinations).
 
 ---
 
-## License
+<div align="center">
+
+**39 skills &bull; 17 agents &bull; 26 hooks &bull; 38 server routes &bull; 4 platforms**
+
+**Claude Code is powerful. PBR makes it reliable.**
+
+[MIT License](LICENSE)
 
-[MIT](LICENSE)
+</div>