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

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:

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.

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:

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.

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:

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

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

.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

Every task gets its own atomic commit immediately after completion:

abc123f docs(08-02): complete user registration plan
def456g feat(08-02): add email confirmation flow
hij789k feat(08-02): implement password hashing

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.

Commands

Core Workflow

Navigation & Session

Milestone Management:

Phase Management:

Autonomous Mode:

Quality & Debugging:

Knowledge & Ideas:

Utilities:

See the User Guide 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.

Model Profiles

/pbr:set-profile quality

Workflow Agents:

Override per-invocation: /pbr:plan-phase --skip-research or --skip-verify

Parallelization:

Git Branching:

Hook Server:

See the User Guide for the full config schema.

Security

PBR reads files to understand your project. Protect secrets with Claude Code's deny list:

{
  "permissions": {
    "deny": [
      "Read(.env)", "Read(.env.*)", "Read(**/secrets/*)",
      "Read(**/*credential*)", "Read(**/*.pem)", "Read(**/*.key)"
    ]
  }
}

PBR works best with frictionless automation:

claude --dangerously-skip-permissions

Or configure granular permissions in .claude/settings.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:*)"
    ]
  }
}

Troubleshooting

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:

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:

# Plugin
claude plugin uninstall pbr@plan-build-run

# npx
npx @sienklogic/plan-build-run --claude --global --uninstall

Learn More

Local Development

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

CI runs on Node 18/20/22 across Windows, macOS, and Linux (9 platform combinations).