plan-build-run

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

Build ambitious multi-phase software without quality degradation.

Problem • Install • Quick Start • Commands • Architecture • Config • User Guide • Wiki

---

The Problem

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

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.

Skip PBR for: Single-file fixes, quick questions, one-off scripts. Use /pbr:quick for atomic commits without full workflow overhead.

---

Install

Claude Code Plugin (recommended):

claude plugin marketplace add SienkLogic/plan-build-run
claude plugin install pbr@plan-build-run

Verify: /pbr:help

Other install methods

npx (alternative):

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):

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
Team project	claude plugin install pbr@plan-build-run --scope project	Shared via git

Cursor IDE: See Cursor Plugin wiki page.

GitHub Copilot:

npx @sienklogic/plan-build-run --copilot --local   # Install to .github/ in current project
npx @sienklogic/plan-build-run --copilot --global   # Install to ~/.copilot/ for all projects

This installs PBR agents, skills, references, and a minimal preToolUse hook guard into Copilot's directory structure. A copilot-instructions.md file is generated to bootstrap the workflow.

Note: Copilot runs PBR in degraded mode — lightweight skills (pbr-status, pbr-todo, pbr-note, pbr-health, pbr-quick, pbr-explore, etc.) work fully. Advanced workflow skills (pbr-plan, pbr-build, pbr-review) require subagent spawning (Task()), which Copilot doesn't support yet. For the full PBR workflow, use Claude Code.

See Copilot Integration for details on what's supported.

Codex CLI: See Codex plugin README.

Development install:

git clone https://github.com/SienkLogic/plan-build-run.git
cd plan-build-run && npm install
claude --plugin-dir .   # Load as local plugin

---

Quick Start

cd your-project && claude

/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

Repeat plan → execute → verify for each phase. Kill your terminal anytime — /pbr:resume-work picks up where you left off.

Already have code? Run /pbr:map-codebase first to analyze your existing stack, then /pbr:new-project.

---

Architecture

PBR 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

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.

Three layers: Skills → Agents → Hooks

Skills (46 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 (18 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.

Hook server architecture

Persistent HTTP Hook Server

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.

Why a hook server?

• 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:

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: ... }

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

File-based state (the data model)

Skills and agents communicate through files on disk, not messages: