@sienklogic/plan-build-run 2.12.0 → 2.12.1

package/README.md

@@ -1,300 +1,379 @@
 <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="#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
+## Install
 
-- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.45+ &nbsp;(`claude --version`)
-- Node.js 18+
-
-### 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>
+<summary><strong>How it works under the hood</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.
+PBR is a **thin orchestrator** that delegates heavy work to fresh subagent contexts via `Task()`. Data flows through files on disk, not through messages.
 
-**macOS / Linux:**
-```bash
-cd /path/to/your/project
-bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh
 ```
+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.
+
+Every task gets its own **atomic commit** immediately after completion:
 
-**Windows (PowerShell):**
-```powershell
-cd C:\path\to\your\project
-powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1
+```bash
+abc123f docs(08-02): complete user registration plan
+def456g feat(08-02): add email confirmation flow
+hij789k feat(08-02): implement password hashing
 ```
 
-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.
+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.
 
 </details>
 
-<details>
-<summary><strong>Dashboard (Optional)</strong></summary>
+---
 
-Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser.
+## Commands
 
-```bash
-# One-time install of dashboard dependencies
-npm run dashboard:install
+### Core Workflow
 
-# Launch the dashboard (defaults to current directory)
-npm run dashboard
+| 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 |
 
-# Or specify a project directory and port
-npm run dashboard -- --dir /path/to/your/project --port 3000
-```
+<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 |
+
+**Utilities:**
+
+| Command | What it does |
+|---------|--------------|
+| `/pbr:settings` | Configure model profile and workflow |
+| `/pbr:set-profile <profile>` | Switch model profile (quality/balanced/budget) |
+| `/pbr:add-todo [desc]` | Capture idea for later |
+| `/pbr:check-todos` | List pending todos |
+| `/pbr:note [text]` | Quick idea capture |
+| `/pbr:debug [desc]` | Systematic debugging with persistent state |
+| `/pbr:health [--repair]` | Validate `.planning/` integrity |
+| `/pbr:audit [--today]` | Review past sessions for workflow compliance |
+| `/pbr:dashboard` | Launch web dashboard |
+| `/pbr:statusline` | Install terminal status line |
+| `/pbr:explore [topic]` | Think through approaches |
+| `/pbr:help` | Show all commands and usage |
+| `/pbr:update` | Update PBR with changelog preview |
 
-Or launch it directly from a Claude Code, Cursor, or Copilot CLI session:
-```
-/pbr:dashboard
-```
+</details>
 
-Opens at `http://127.0.0.1:3000` with live updates via SSE.
+See the **[User Guide](docs/USER-GUIDE.md)** for all flags, cost-by-depth tables, and detailed descriptions.
 
-</details>
+---
 
-### Quick Start (Max / Max 5x)
+## Configuration
 
-Full pipeline with parallel research and multi-agent builds. Best experience.
+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:set-profile quality
 ```
-/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
-```
+<details>
+<summary><strong>More configuration options</strong></summary>
 
-That's the whole cycle. Everything lands in a `.planning/` directory. Kill your terminal anytime, `/pbr:resume` picks up where you left off.
+**Workflow Agents:**
 
-### Quick Start (Pro / Free)
+| Setting | Default | What it does |
+|---------|---------|--------------|
+| `workflow.research` | `true` | Research domain before planning each phase |
+| `workflow.plan_check` | `true` | Verify plans before execution |
+| `workflow.verifier` | `true` | Confirm must-haves after execution |
+| `workflow.auto_advance` | `false` | Auto-chain discuss → plan → execute |
 
-Lighter workflow that still gives you structured state tracking and clean commits.
+Override per-invocation: `/pbr:plan-phase --skip-research` or `--skip-verify`
 
-```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
-```
+**Git Branching:**
 
-Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.
+| Strategy | Behavior |
+|----------|----------|
+| `none` (default) | Commits to current branch |
+| `phase` | Branch per phase, merge at completion |
+| `milestone` | One branch for entire milestone |
 
-### Quick Reference
+See the [User Guide](docs/USER-GUIDE.md#configuration-reference) for the full config schema.
 
-| 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` |
+</details>
 
 ---
 
-## Commands
+## Security
 
-### Core Workflow
+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)"
+    ]
+  }
+}
+```
+
+<details>
+<summary><strong>Recommended permissions setup</strong></summary>
+
+PBR works best with frictionless automation:
 
-| 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 |
+```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 **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 22 commands with flags, cost-by-depth tables, and detailed descriptions.
+</details>
 
 ---
 
-## How It Works
+## Troubleshooting
+
+<details>
+<summary><strong>Common issues</strong></summary>
 
-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.
+**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/`
 
+**Using Docker?** Set `CLAUDE_CONFIG_DIR` before installing:
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx @sienklogic/plan-build-run --global
 ```
-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
+
+**Uninstalling:**
+```bash
+# Plugin
+claude plugin uninstall pbr@plan-build-run
+
+# npx
+npx @sienklogic/plan-build-run --claude --global --uninstall
 ```
 
-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
+## Learn More
 
-| 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 |
+| 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 |
 
 ---
 
 ## Local Development
 
 ```bash
-# Clone and install
 git clone https://github.com/SienkLogic/plan-build-run.git
-cd plan-build-run
-npm install
-
-# Run tests (1213 tests, 44 suites)
-npm test
-
-# Lint
-npm run lint
-
-# Validate plugin structure
-npm run validate
-
-# Load locally for manual testing
-claude --plugin-dir .
+cd plan-build-run && npm install
+npm test          # 3600+ tests across 137 suites
+claude --plugin-dir .   # Load locally for testing
 ```
 
-CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.
+CI runs on Node 18/20/22 across Windows, macOS, and Linux.
 
 ---
 
-## Stats
+<div align="center">
 
-| 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 |
+**29 skills &bull; 14 agents &bull; 49 hooks &bull; 4 platforms**
 
----
+**Claude Code is powerful. PBR makes it reliable.**
 
-## License
+[MIT License](LICENSE)
 
-[MIT](LICENSE)
+</div>