Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/sienklogic/plan-build-run

Plan it. Build it. Run it. A Claude Code plugin for structured development with context-engineered agents.
https://github.com/sienklogic/plan-build-run

agent-orchestration agentic-coding ai-coding ai-development anthropic claude claude-code claude-code-plugin claude-plugin context-engineering copilot-cli copilot-plugin cursor cursor-plugin developer-tools development-workflow github-copilot multi-platform subagent-delegation

Last synced: about 7 hours ago
JSON representation

Plan it. Build it. Run it. A Claude Code plugin for structured development with context-engineered agents.

Awesome Lists containing this project

README 

          


  Plan-Build-Run Logo






  Context-engineered development workflow for Claude Code, Cursor, and GitHub Copilot CLI.

  


  Build ambitious multi-phase software without quality degradation.

  


  Works with any Claude Code plan. Shines on Max. Now available for Cursor IDE and GitHub Copilot CLI.

  


  


  Why Plan-Build-Run? •

  Getting Started •

  Commands •

  How It Works •

  Local LLM •

  Wiki •

  Contributing






  CI Status

  Claude Code Plugin

  Cursor Plugin

  Copilot CLI Plugin

  Node.js 18+

  License

  npm

  2153 Tests




---



## 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.



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 workflow: begin → plan → build → review




Goal-backward verification, lifecycle hooks, wave-based parallelism, kill-safe state, and **[local LLM offloading](#local-llm-offload)** to cut frontier token costs on routine tasks. 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.

>

> **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.



---



## Getting Started



### Prerequisites



- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 2.1.47+  (`claude --version`)

- Node.js 18+



### Install



```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.



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 |



Install for Cursor IDE



Plan-Build-Run also works in Cursor. The setup script symlinks rules and agents into your project's `.cursor/` directory.



**macOS / Linux:**

```bash

cd /path/to/your/project

bash /path/to/plan-build-run/plugins/cursor-pbr/setup.sh

```



**Windows (PowerShell):**

```powershell

cd C:\path\to\your\project

powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\cursor-pbr\setup.ps1

```



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.



Install for GitHub Copilot CLI



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.



**macOS / Linux:**

```bash

cd /path/to/your/project

bash /path/to/plan-build-run/plugins/copilot-pbr/setup.sh

```



**Windows (PowerShell):**

```powershell

cd C:\path\to\your\project

powershell -ExecutionPolicy Bypass -File C:\path\to\plan-build-run\plugins\copilot-pbr\setup.ps1

```



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.



Dashboard (Optional)



Plan-Build-Run ships with a companion web dashboard for browsing your project's planning state in a browser.



```bash

# One-time install of dashboard dependencies

npm run dashboard:install



# Launch the dashboard (defaults to current directory)

npm run dashboard



# Or specify a project directory and port

npm run dashboard -- --dir /path/to/your/project --port 3000

```



Or launch it directly from a Claude Code, Cursor, or Copilot CLI session:

```

/pbr:dashboard

```



Opens at `http://127.0.0.1:3000` with live updates via SSE.



### Quick Start (Max / Max 5x)



Full pipeline with parallel research and multi-agent builds. Best experience.



```bash

cd your-project && claude

```

```

/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

```



That's the whole cycle. Everything lands in a `.planning/` directory. Kill your terminal anytime, `/pbr:resume` picks up where you left off.



### Quick Start (Pro / Free)



Lighter workflow that still gives you structured state tracking and clean commits.



```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

```



Set `depth: quick` in `/pbr:config` to reduce agent spawns across all workflows.



### Quick Reference



| 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` |



---



## Commands



### Core Workflow



| Command | Description | Agents |

|---------|-------------|--------|

| `/pbr:begin` | Start a new project: questioning, research, requirements, roadmap | 4-6 (quick: 2-3) |

| `/pbr:plan ` | Plan a phase: research, plan creation, verification loop | 2-3 (quick: 1-2) |

| `/pbr:build ` | Build a phase: parallel execution in waves, atomic commits | 2-4 (quick: 1-2) |

| `/pbr:review ` | Verify a phase: automated 3-layer checks + conversational UAT | 1 |



See **[Commands](https://github.com/SienkLogic/plan-build-run/wiki/Commands)** for all 26 commands with flags, cost-by-depth tables, and detailed descriptions.



---



## How It Works



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.



```

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

```



See **[Architecture](https://github.com/SienkLogic/plan-build-run/wiki/Architecture)** for key concepts, the token-saving CLI, data flow details, and supporting directories.



---



## Local LLM Offload



Plan-Build-Run can offload lightweight inference tasks to a local model running on your machine, saving frontier tokens and reducing API costs — without sacrificing quality on complex operations.



**This is a novel capability.** Other AI coding frameworks use local LLMs as the primary model or not at all. PBR operates at the **sub-session level**: hook scripts that fire on every tool call use a local model for fast classification tasks (artifact type, commit scope, error category, file intent) while the frontier model handles planning, execution, and verification. You get the cost savings of local inference where it matters, with automatic fallback to Claude when confidence is low.



### How it works



```

Hook fires (e.g., PostToolUse:Write)

  │

  ├─ Complexity scorer evaluates the prompt

  │   └─ High complexity? → Route to frontier (Claude)

  │   └─ Low complexity? ↓

  │

  ├─ Local LLM classifies (Ollama, ~50-200ms)

  │   └─ Confidence below threshold? → Fallback to frontier

  │   └─ Confidence OK? → Use local result ✓

  │

  └─ Metrics logged to .planning/logs/local-llm-metrics.jsonl

```



### Key features



- **3 routing strategies**: `local_first` (default), `balanced`, `quality_first` — control the cost/quality tradeoff

- **8 offloadable operations**: artifact classification, task validation, commit classification, error classification, file intent, test triage, source scoring, context summarization

- **Shadow mode**: Run local and frontier in parallel, compare results, but always use frontier output — safe way to validate local accuracy before trusting it

- **Adaptive threshold tuning**: Analyzes shadow logs to suggest confidence threshold adjustments per operation

- **Circuit breaker**: Automatically disables local routing after consecutive failures — no cascading slowdowns

- **Session metrics**: See tokens saved, cost reduction, and per-operation breakdowns via `/pbr:status` or the dashboard



### Quick setup



```bash

# 1. Install Ollama (ollama.com/download)

# 2. Pull the recommended model

ollama pull qwen2.5-coder:7b



# 3. Enable in your project config

/pbr:config local_llm.enabled true

```



Requires a GPU with 6+ GB VRAM for best performance. CPU-only works but adds latency. See **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration#local_llm)** for full setup details, hardware requirements, and Windows-specific notes.



---



## Deep Dive



| Topic | Description |

|-------|-------------|

| **[Agents](https://github.com/SienkLogic/plan-build-run/wiki/Agents)** | 12 specialized agents with configurable model profiles and file-based communication |

| **[Configuration](https://github.com/SienkLogic/plan-build-run/wiki/Configuration)** | 13 config keys, depth/model profiles, 16+ feature toggles, local LLM settings |

| **[Hooks](https://github.com/SienkLogic/plan-build-run/wiki/Hooks)** | 38 hook scripts that enforce discipline at zero token cost |

| **[Local LLM](https://github.com/SienkLogic/plan-build-run/wiki/Configuration#local_llm)** | Offload hook-level inference to Ollama for token savings with automatic fallback |

| **[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 |



---



## Platform Compatibility



Plan-Build-Run works across three platforms with varying levels of hook support. Hooks are the mechanism that fires validation scripts on every tool call — they power local LLM offloading, commit format enforcement, context budget tracking, and workflow gates.



| Feature | Claude Code | Copilot CLI | Cursor IDE |

|---------|:-----------:|:-----------:|:----------:|

| Skills (slash commands) | All 26 | All 26 | All 26 |

| Agents (subagent delegation) | All 12 | All 12 | All 12 |

| `.planning/` state management | Full | Full | Full |

| **Hook support** | **Full (14 events)** | **Partial (4 events)** | **Unverified** |

| Commit format enforcement | Hook-enforced | Hook-enforced | Manual |

| PLAN/SUMMARY quality classification | Hook + skill fallback | Hook + skill fallback | Skill fallback only |

| Test failure triage | Automatic (hook) | Automatic (hook) | Not available |

| Context budget tracking | Automatic (hook) | Not available | Not available |

| Auto-continue between skills | Automatic (hook) | Not available | Not available |

| Subagent lifecycle logging | Automatic (hook) | Not available | Not available |

| **Local LLM offloading** | **Full (8 operations)** | **Mostly (6-7 operations)** | **CLI only** |

| `pbr-tools.js llm` CLI commands | Full | Full | Full |



**Key differences:**



- **Claude Code** has full hook support — all local LLM operations fire automatically on every tool call

- **Copilot CLI** supports `sessionStart`, `preToolUse`, `postToolUse`, and `sessionEnd` — covers most validation hooks but misses lifecycle events (`SubagentStop`, `PreCompact`, `Stop`)

- **Cursor IDE** hook support is unverified — hooks.json is configured but whether Cursor actually fires them is unknown. Skills include `pbr-tools.js llm` fallback calls for key operations (plan quality, verification quality) so local LLM classification is available even without hooks



All platforms share the same scripts via relative paths — no code duplication. See the [Copilot CLI](plugins/copilot-pbr/README.md) and [Cursor IDE](plugins/cursor-pbr/README.md) READMEs for platform-specific details.



---



## Local Development



```bash

# Clone and install

git clone https://github.com/SienkLogic/plan-build-run.git

cd plan-build-run

npm install



# Run tests (2153 tests, 73 suites)

npm test



# Lint

npm run lint



# Validate plugin structure

npm run validate



# Load locally for manual testing

claude --plugin-dir .

```



CI runs on Node 18/20/22 across Windows, macOS, and Linux. See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for guidelines.



---



## Stats



| Metric | Count |

|--------|-------|

| Skills (slash commands) | 26 |

| Specialized agents | 12 |

| Hook scripts | 38 |

| Local LLM operations | 8 |

| Supported platforms | 3 (Claude Code, Cursor, Copilot CLI) |

| Tests | 2153 |

| Test suites | 73 |

| Config keys | 13 top-level (62+ properties) |



---



## License



[MIT](LICENSE)