plan-build-run

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

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.

Milestone Management:

Phase Management:

Autonomous Mode:

Quality & Debugging:

Knowledge & Ideas:

Utilities:

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.

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:*)"
    ]
  }
}

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