plan-bender-cli

name

plan-bender-cli

description

Reference for the plan-bender CLI (`pb` and `pba` / `plan-bender-agent`). Use when the user asks about plan-bender commands, the standalone merge command, worktree management, completion marker, the dispatcher skill, recovering a stuck issue, or Linear sync. Also triggers on "what does pb / pba do", "how do I run plan-bender", "pb merge", "pb status", "pb retry", or any question about plan-bender's command surface.

plan-bender CLI

Two binaries ship together:

• pb (alias plan-bender) — human CLI, formatted output
• pba (alias plan-bender-agent) — agent CLI, JSON output, what skills shell out to

Same subcommand surface for the most part; pba returns structured JSON and well-defined error codes.

Verify install

pb doctor
pb --version

If missing:

curl -fsSL https://raw.githubusercontent.com/jasonraimondi/plan-bender/main/install.sh | bash

Setup (run inside any git repo)

pb setup                # idempotent — writes config, generates skills, symlinks
pb setup --linear       # also configure Linear backend
pb setup --yes          # non-interactive

Re-run after config changes; it regenerates skills and re-symlinks. Regeneration is a clean rebuild — skills that were renamed, removed, or filtered out (e.g. backend skills with Linear disabled) are deleted and their dangling symlinks pruned. It also backfills a $schema reference into existing config files that lack one. If .plan-bender.local.json already exists, no .plan-bender.json is created. Set manage_gitignore: false to keep pb setup from touching .gitignore.

Human CLI (pb)

Command	Purpose
pb next <slug>	Recommended next issue (text)
pb status <slug>	Per-issue state: status counts, labels, blocked notes, branch/PR
pb merge <slug>	Merge in-review/deps-done issues into the integration branch in dependency order
pb complete <slug> <id>	Mark issue in-review (ready for review); prints the completion marker
pb retry <slug> <id>	Reset a blocked or needs-input issue back to todo
pb park <slug> <id>	Park an in-progress issue as needs-input
pb worktree create <slug> <id>	Branch + worktree for one issue
pb worktree gc <slug>	Remove plan-bender worktrees + merged branches incl. the per-slug integration worktree (keeps unmerged)
pb sync linear push <slug>	Local JSON → Linear
pb sync linear pull <slug>	Linear → local JSON
pb migrate	One-shot legacy .yaml → .json (supports --dry-run)
pb self-update	Update to latest release
pb completion <shell>	bash, zsh, fish
pb docs	Open repo in browser
pb docs --print	Print repo URL
pb docs --full	Print full config reference inline

Agent CLI (pba)

JSON-only output. Errors are {"error": "...", "code": "..."} with non-zero exit.

Error codes: PLAN_NOT_FOUND, INVALID_PLAN (includes file, line, hint for parse errors), VALIDATION_FAILED, CONFIG_ERROR, INTERNAL.

Command	Returns
pba context	Summary of all plans
pba context <slug>	Full dump — PRD, issues, dep graph, stats
pba validate <slug>	Structured validation errors
pba next <slug>	Recommended next issue (JSON)
pba write-prd <slug> [file]	Validate + atomically write PRD; creates plan dir for fresh slugs
pba write-issue <slug> [file]	Validate + atomically write issue; requires PRD
pba archive <slug>	Move completed plan to .archive/
pba sync linear push|pull <slug>	JSON-emitting variant
pba merge <slug>	{merged: [...], conflicted: [...]}; merges in-review/deps-done issues into the integration branch
pba complete <slug> <id>	Flip to in-review + emit <pba:complete issue-id="N"/>
pba worktree create <slug> <id>	{path, branch, status} — status is post-claim (in-progress)
pba worktree gc <slug>	{removed: [...]}; cleans issue worktrees + per-slug integration worktree, unmerged branches preserved, logged to stderr
pba status <slug>	{plan, issues} per-issue id, status, labels, branch, notes
pba retry <slug> <id>	{status, id, slug, new_status}; refuses a status that is neither blocked nor needs-input
pba park <slug> <id>	{status, id, slug, new_status}; refuses non-in-progress status

write-prd / write-issue read from stdin when no file is given (or when the file arg is -).

Merge

pb merge <slug> (or pba merge) is a standalone, dependency-ordered merge-back — no dispatch loop. It:

• takes the per-slug .dispatch.lock at {plans_dir}/{slug}/.dispatch.lock (fails fast if another merge holds it)
• merges every issue that is in-review with a branch set and whose blocked_by are all done (or are being merged in the same call) into the integration branch in dependency order
• merged → done; a conflict is git merge --abort'd and the issue → blocked while siblings still merge
• nothing in-review → no-op; agent mode emits {"merged":[...],"conflicted":[...]}

The integration branch is <git-user>/<slug> (set pipeline.branch_strategy to integration or direct). All git work runs in a long-lived per-slug integration worktree (lazy-created on first merge, reset on entry, GC'd via pba worktree gc <slug>); the parent repo's HEAD is never touched and the parent can stay dirty. See ADR-0003.

Completion marker

A worker signals completion with pba complete <slug> <id>. The command:

• Flips the issue JSON to status: in-review
• Prints <pba:complete issue-id="N"/> — the completion marker (also in the JSON marker field in agent mode)

The marker is a progress line for logs and out-of-band tooling; it is not the completion signal. The merger keys on the status flip: it picks up an issue only once it is in-review.

Dispatcher skill

Multi-issue implementation is the live agent skill bender-implement-prd (not a CLI subcommand), which drives the harness Workflow tool in a loop-until-stable: scout ready issues (deps done/canceled + status in {backlog, todo, in-progress} — label-agnostic) → spawn one worktree-isolated worker (bender-implement-issue) per ready issue in parallel → run pba merge <slug> as the merger → re-scout. Each worker returns a completed / blocked / needs-decision outcome and self-advances its own status via the CLI (worktree create → in-progress, complete → in-review, park → needs-input). Between round-sets the dispatcher batches every needs-input decision back to the operator, writes the answers into the issue JSON, and resumes with pb retry. Once stable with every issue done, it runs the operator-chosen completion mode — merge, branch, or pr.

Recovering from a stuck issue

pb status <slug>             # per-issue state; failure reason in `notes`
# fix the underlying problem (build break, missing dep, etc.)
pb retry <slug> <id>         # blocked or needs-input → todo, appends `[date] blocked→todo: retry` note

retry refuses any status that is neither blocked nor needs-input — fix done / in-review / canceled by hand if needed. The prior failure note is preserved as audit trail.

Config layering

Three layers, deep-merged (later wins):

File	Scope
~/.config/plan-bender/defaults.json	Global, shared across projects
.plan-bender.json	Project, committed
.plan-bender.local.json	Project, gitignored — secrets here

$VAR / ${VAR} are expanded at load time.

Plan layout

.plan-bender/plans/<slug>/
  prd.json
  issues/
    1-setup-middleware.json
    2-add-token-refresh.json

track ∈ intent | experience | data | rules | resilience. points hard-capped by max_points (default 3). labels: AFK / HITL are escalation hints that tune how eagerly a worker parks on a human decision — not gates on which issues are workable (readiness is dependency-graph + status only).

Discovering more

pb <command> --help          # any subcommand
pb docs --full               # full config reference
pb docs                      # open repo in browser

Repo docs: docs/cli.md, docs/configuration.md, docs/schema.md.