PLUMBBOB
DOCS
Home API GITHUB
{{ grp.title }}
{{ it.label }}
Looking for every verb, flag, exit code, or the sidecar layout? API reference →
GET STARTED

Getting started

PlumbBob is first and foremost a Claude Code plugin — eighteen skills you fire from your IDE to run LLM-assisted coding as a loop you control. The easiest way to get it is the robmclarty/agent-tools marketplace. The words it uses (steps, seams, the pause, the latch) are one line each in the glossary. The skills shell out to the CLI, so in the loop you rarely type it. It is a first-class path on its own: every verb runs from a terminal, and a few (use, handoff, defer, check, agent) have no skill of their own. cli-only.md drives one build that way.

The course: docs/learn/README.md walks one build, surprise included. Read happy-path.md for one session end to end, faq.md for the adoption questions, why.md for the argument.

Prerequisites

You drive the loop inside Claude Code, in a git repo. Under the hood the bundled CLI runs on Node ≥ 22.18 (node builtins plus one deliberate dependency, checkride) — the marketplace plugin brings it along, so there's nothing else to set up.

Install

The marketplace plugin is the primary path, and the one to reach for. The npm install is for scripting, hosts other than Claude Code, or driving the CLI yourself. Pick one — both register a Claude Code plugin named plumbbob, so running both collides.

A · MARKETPLACE PLUGINRECOMMENDED

Claude Code installs the published package for you — skills, four hooks, and the CLI on PATH — so you run no npm i -g and no init. This is the whole install.

in Claude Code
/plugin marketplace add robmclarty/agent-tools
/plugin install plumbbob@robmclarty
B · NPM GLOBAL + INITCLI ON PATH

For scripting, other hosts, or driving the verbs yourself. Installs the CLI (also a pb shorthand), then links the skills and four hooks into Claude Code in place.

shell
$ npm i -g plumbbob # the CLI
$ plumbbob init # link it into Claude Code; --uninstall to undo

Restart Claude Code (or /reload-plugins) to activate, then run plumbbob doctor (or /plumbbob:doctor in-session) to confirm the wiring.

Your first session

A session needs a git repo with at least one commit, a clean tree, and something for the check gate to run: the tools the repo already configures, or a "check" command in .plumbbob/settings.json. start says so if any is missing. Then four moves take a goal end to end.

1
Plan. Fire /plumbbob:plan and give it whatever you have — nothing (it interviews you), a rough line (/plumbbob:plan rate-limit POST /login, 5/min/IP, return 429), or a path to a spec file. Together you fill the build's intent.md: the steps, and the build ranges that say where the build stops for your call. No code is written yet.
2
Run. Fire /plumbbob:run. It runs the range holding the next step: each step implemented, checked against the gate, and reviewed against the plan, stopping where the plan says. A range of one step stops at its pause: one block with a fixed shape (the Now line naming the step, a Summary, a Readout of measured rows, a Verdict, Next Up, Your Call, and the model's Recommendation), rendered by the CLI and relayed whole.
3
Reply. Say looks good and it commits the step as a checkpoint, marks it done, and returns to the boundary. Ask (expand 2, or any question) and it shows more without changing anything, closing on one line that points back at the step (say show the pause to see the whole block again); direct it, and nothing lands until you say looks good. Fire /plumbbob:run again for the next range; re-firing it is the clock tick. A range that lands its steps ends on the stop card: the range's review, with every parked idea and a lean proposed for each, which one reply settles. /plumbbob:build walks a step at a time. Lost the thread? /plumbbob:status names the next move.
4
Finish. When the last range lands, answer its stop card with /plumbbob:finish: it records the card, writes a report of what shipped and why, makes the final commit, and clears the slate. The build folder rides the branch into the PR.
Next: The loop in depth →
Working with agents →
NO LOCK-IN
Everything PlumbBob writes is plain markdown and ordinary git commits in your own repo. Your teammates need nothing installed to review the PR. If something better ships, you walk away with your archives and your habits intact — what you learned is the method, and that transfers.
USING THE LOOP

The loop in depth

Everything the model must stay true to lives in one file — intent.md, written before any code: the Frame and an Architecture sketch, the Decisions and Constraints (each with its because), the Steps, each carrying a proof (a checkable finish line) and a seam (the files it's expected to touch), the Build order once a late step has to land before an earlier one, the Build ranges, where the build stops for your call, the Open questions the plan could not settle on paper (status --questions lists them; plumbbob defer leaves one to the work), and the Verdicts a spike records.

The moves every session makes

SKILLDOES
{{ h.skill }} {{ h.does }}

The pause is the whole point

A run's bare range, or /plumbbob:build on any step, carries the step straight through the verify tick and stops:

the pause, its tail
Your Call: - looks good → I checkpoint Step 1; back to the boundary - expand, or any question → I show more of what is there; nothing changes, and show the pause brings all of this back - anything that reads as direction → I make the change and say what moved; nothing lands until you approve - revert → I wind the work back to the last checkpoint
Verdict● Plumb
NowStep 1 on Opus - feat(limiter): add a token-bucket limiter
Next UpStep 2 on Sonnet - feat(login): wire the limiter into POST /login
Range 2 on Sonnet: /plumbbob:run once step 1 lands
Recommendation: Approve it, refilling on read. The gate is green and the seam held. more details

Above that tail sit a Summary of the outcome and a Readout of measured rows (the check, the proof, the decisions and constraints, the seam, the diff with each changed file beneath it, what the step spent). The state table at the foot is headed by the Verdict, with the step Now in flight and Next Up beneath it, and the model's Recommendation closes the card with one link to the rest of its story, which stays in the detail file. A question or a change after the card is answered in the model's own words and closed on one line; show the pause brings the card back. The CLI measures what can be measured and the model supplies only the judgment, so the block reads the same from any model on any day. The whole shape is the turn anatomy.

The pause, drawn: a mechanical hand has set its stone on the line and hovers open and still, while a plumb bob in front comes to rest.

Nothing is locked and nothing refuses you — the loop does a step's labor, pulls up to the line, and waits for you to advance it. You are the clock. Approving commits the step as a checkpoint against a recorded baseline; a wrong turn costs one step, not the afternoon. --auto lets the agent self-approve and chain step after step until the plan is done — halting the moment a check goes red or the self-review finds a mismatch, and at each bare range's pause, a call the plan reserves for you. A range like 1-3 is a bounded auto, and a run is the same walk over a range the plan cut, ending on the stop card. The runs guide walks one plan through three runs and sets each beside the manual moves.

Swap the executor

/plumbbob:build is the default engine, not the only one — the loop doesn't care who writes the code. Implement a step by hand, vibe it in another session, or use another harness entirely, then run /plumbbob:verify instead: same check, same pause, same checkpoint. It reads the diff, not the author.

Capture, don't chase

A mid-build "ooh, what if…" never derails the step. /plumbbob:park captures it to a list in one line; a run's stop card triages the list where its range lands, and /plumbbob:harvest anywhere else, proposing exactly one class per item: blocker (the plan was wrong; fold in now), tangent (defer or kill — the default), or pivot signal (the approach is wrong; stop and replan). You call each one, in one reply at a stop.

When the plan needs work

/plumbbob:step
Revise or sharpen the next step just-in-time. Fired bare, it auto-syncs the step to what the build has taught you.
/plumbbob:refine
Attack the frame for holes (surfaced as Open questions), or repair a plan that drifted from the code. refine ranges re-cuts the build ranges.
/plumbbob:order
Set the build order: the undone steps in the sequence to build them, once a step added late has to land before an existing one. A step keeps its number; the sequence moves, and the build ranges are re-cut to follow it.
/plumbbob:spike
A throwaway worktree experiment for a fork the plan can't settle. The deliverable is the verdict, not the spike code.

The full reference for all eighteen skills — inputs, effects, when to reach for each — is on the API page, alongside the CLI verbs they shell out to.

Next: Runs & the stop card →
USING THE LOOP

Runs & the stop card

A build range is a stretch of steps the plan says can land without you, ending where your call is due. /plumbbob:run lays one: each step lands on a green check with no pause between them, and the run stops where the plan said. A range that ends on a decision stops at its step's pause. A range that ends on a review stops on the stop card, which reviews the whole range and settles every parked idea in one reply.

The plan names the steps

You type /plumbbob:run, or /plumbbob:run 3 for range 3. The turn hook reads the plan's ## Build ranges as you press enter and mints a grant for exactly the steps that range has left, so you never type a step number and the model never decides how far it may go. The run walks those steps in the plan's build order, and it opens on a header naming what it will do:

the run header
run range 2 of 3 · steps 2-3 · ends at step 3's boundary stop: read one real request's line before the timing and the docs build on it grant: steps 2-3

The stop card

When the range's last step lands, the run ends on the stop card in place of that step's boundary. Its Summary is the whole range's, its Readout is measured across the range's commits, and every idea parked along the way sits in a table under Harvested: its bold handle (P1, its place in the park list) and a title that links to the park's line in the build log, why it matters, and the class the model leans toward. The plan's stop rides the state table at the foot:

the stop card, abridged
Readout: steps 2 of 2 landed - 2 2e47835 · 3 9d2de70 check green: 1 of 1 checks, 2 landings seam held: 2 of 2 steps, no strays diff +4 -0 across 4 files spent 39 min · green first run at every landing Harvested: 2 of 2 parked ideas open
ParkWhy it mattersLean
P1: missing request ida line with no id cannot be traced to its requesttangent: an id is still logged when the client sends one
P2: buffered linesa write per request costs a syscall under loadtangent: a performance call this goal does not make
Your Call: Approving locks in each lean above; to change one, say so first (make P1 a blocker). - looks good → I record the review and every lean as proposed, folding a blocker into the plan; back to the boundary - /plumbbob:run → I record them the same way, then run range 3 on Sonnet to its stop - anything that reads as direction → I change the lean and say what moved; nothing is recorded until you approve - expand, or any question → I show more of what is there; nothing changes, and show the stop brings all of this back
Verdict● Plumb
StopRange 2 landed - read one real request's line before the timing and the docs build on it
Next UpStep 4 on Sonnet - feat(http): log how long each request took
Range 3 on Sonnet: /plumbbob:run (steps 4-5)

One reply settles it

YOUR REPLYWHAT HAPPENS
{{ r.reply }} {{ r.does }}

A confirmed blocker folds into the plan before the record lands: a Decision, a new step under the next free number, a place in a range still to come (never the range the card reviews, which has landed), and a place in the build order when it must land before an existing step. The record's ending then names the re-cut run, its steps written in the order they will build: | | Range 3 on Sonnet: /plumbbob:run (steps 6,4-5) |. While a card waits, /plumbbob:build refuses to enter a step, since the step's pause would overwrite the review before your reply recorded it.

Runs beside the manual moves

The same five-step plan, three ranges and one blocker, driven three ways after the plan is approved:

MOMENTWITH RUNSTYPED RANGESA STEP AT A TIME
{{ m.moment }} {{ m.runs }} {{ m.typed }} {{ m.step }}

The keystrokes are the smaller difference: typed ranges cost one prompt more than runs. What separates them is who holds the numbers and what the stop shows you. A typed range is your numbers, so after a re-cut you type the new one yourself, and it ends on its last step's boundary, with no review of the range and the harvest left for a turn of its own. A step at a time stops at six pauses the plan never asked for. The runs guide walks this plan end to end, every card as the CLI renders it, with the refusals, the halts, and the cases where a manual move fits better.

Next: Working with agents →
USING THE LOOP

Working with agents

PlumbBob's executor is author-blind: the tick reads the diff, not who wrote it. So you can plug your own agent in. A user-authored agent is anything executable that speaks one small JSON envelope — there's no SDK to import and no language to adopt. A twelve-line bash script is a complete agent.

The three invariants

Everything is downstream of three rules. When you wonder why the contract refuses something, it's one of these.

1
The envelope has no verb to advance the loop. Nothing an agent returns can checkpoint, flip a step, or trigger another agent. The subprocess boundary enforces human-as-clock by construction, not by policy.
2
The CLI owns every side effect. An agent returns concerns; PlumbBob applies them — parked[] lands through the park verb, never by the agent writing .plumbbob/ itself. The sidecar keeps a single writer.
3
Review is advisory; checkride gates; the human advances. An after-slot agent informs the verify pause. No code path lets it fail a step — a gate an agent can trip is the lock returning in autonomy's costume.

The envelope

Four streams, one shape — a subprocess convention run in production since Terraform's external data source shipped it in 2017. Read stdin to EOF for the StepContext; write one JSON object and nothing else to stdout; narrate freely on stderr (streamed live); exit 0 to make the envelope authoritative.

the output envelope — stdout
{
"contract": 1, // must match the CLI's contract major
"status": "done", // done | blocked | drift
"summary": "read RATE_LIMIT_MAX; default 5",
"body": "…longer prose for the pause…",
"parked": ["429 body should be JSON, not text"],
"notes": "needs FOO in the env to run"
}

Status routes the pause

STATUSMEANINGYOU DO
{{ s.status }} {{ s.meaning }} {{ s.action }}

The routing holds when nobody is pausing between steps. Inside a run, a typed range, or --auto, a blocked or drift envelope halts the walk at that step's pause, and the steps after it wait for your next run: an agent can stop a range, never carry one past its trouble.

Bind it to a step

Drop the agent under .plumbbob/agents/<name>/ (or ~/.plumbbob/agents/ for personal ones), then bind it to a step's lifecycle slot in the build's harness.json: before (context in, at build time), build (authors the diff in your place, still verified the same way), or after (advisory review at the verify pause). /plumbbob:plan authors the bindings at plan time; plumbbob agent list shows what's resolvable. The whole contract, the StepContext fields and the three slots included, is docs/agents.md; a worked example, a local-model reviewer via Ollama, ships in docs/local-model-review.md.

CONCEPTS

Attention-first development

A middle ground between long-horizon autonomy and one-step-at-a-time vibing. The reframe is simple: attention is the scarce resource. The model is cheap, fast, and replaceable; your attention is none of those. So you design the process around it, not around the machine's throughput. The essay in full is docs/attention-first-development.md.

Two modes, and why both fail

FULL AUTONOMY
You write a spec, hand it off, and review the result at the end. The leverage is enormous — but you've delegated the thinking. You are absent from the deciding, and your job shrank to auditing the machine's artifact.
VIBING
You work one prompt at a time, generating and reacting in a stream. Deciding and executing fuse; the model converges before you chose, and new code arrives faster than you can absorb. You are present but overwhelmed.

The failures look opposite but share a root. Two things destroy attention, and the whole method follows from refusing them: the collision between producing and consuming (you can't form intent and absorb output in the same moment — reading overwrites planning), and premature convergence (when implementation arrives before the decisions, you're committed to a shape you never chose).

The principles that follow

{{ p.title }}
{{ p.body }}
The model is a hand, not a head. The directing is the part that does not transfer to it — and the directing is the work.

To watch the difference play out, Who holds the reins? runs one plan two ways: a stagecoach where code holds the reins and each horse is one model call, beside a bareback rider whose horse chooses its own route and its own helpers. The stagecoach repeats itself every run; the rider never does.

Where it sits

The three modes aren't ranked — each is right for a band of work, sorted by how much of it is judgment and how settled that judgment is. Vibe when judgment doesn't matter (throwaway prototypes, spikes you'll delete). Attention-first when judgment is load-bearing and unsettled — most real features, bugs, and refactors you care about. Full autonomy when judgment is settled and the work is large. The poles are the special cases; the middle is where most work that matters lives, which is why attention-first is a default posture rather than a compromise. PlumbBob is the layer below Ridgeline, which runs the settled, large work autonomously.

CONCEPTS

The pause & the latch

A system prompt can ask a model to plan first and stop for review. What it can't do is hold the line when the model doesn't. PlumbBob splits that problem across two planes — and is honest about which half is enforceable.

The work plane: guidance, on purpose

On the work plane the pause is unenforceable, deliberately. A hard lock on every edit buys ritual, not control: a determined model routes around it, and a denial mid-thought leaves no legal move. So PlumbBob guides here rather than fighting — a status dashboard re-injected into every skill keeps the model oriented, and the skills fall into the plan/run/pause rhythm because they were built to. Guidance you fall into, not a lock you fight.

The record plane: the latch

The record is a different plane, and there the tick is latched. checkpoint refuses to land a step until the harness records a human turn since that step began — so the agent cannot self-commit past you. The refusal simply is the pause. It extends the deterministic edges to the one boundary the product is named after, while leaving human what must be human: you, reading the diff.

A run's stop is latched the same way. The checkpoint that lands a run's range owes the stop card, and the turn-end check holds a turn that tries to close without it; plumbbob harvest refuses to record a stop in the turn its card printed, and build refuses to enter a step while a card waits. The review of a range, and the class of every idea parked in it, stay your call.

Measured, not asserted

The latch's payoff is a receipt, not a claim. A headless skill-eval harness sweeps the loop — prose-only baseline vs. the shipped latch, N=5 per contract, every assertion a mechanical read of git state — and commits each receipt to the repo.

the route the latch owns: no checkpoint over a red check, under adversarial pressure
2/5
PROSE-ONLY BASELINE
───→
5/5
SHIPPED LATCH
opus · first sweep 2026-07-11 · reproduced 2026-07-18 @ plumbbob 0.8.7 · all seven contracts 5/5 latched on 2026-07-27 @ plumbbob 0.9.0 · an eighth contract (legible intent) 7/7 on both arms @ 0.9.4 · park capture 3/5 prose-only against 5/5 latched @ 0.10.0 · a run held to its stop card 5/5 latched @ 0.13.1 · the short stop (c13) 5/5 @ 0.13.6 · latest sweep 2026-10-31. The receipts ride the repo under docs/evals/.

And when a raw commit does slip the ledger, status says so and the checkpoint record makes recovery one command. Cheap recovery, not a cage, is the control that matters.

The five deterministic edges

The latch is one of five. The others: a gate that refuses red (checkpoint won't record over a red check gate, start refuses a dirty tree); one SHA per verified step (a ledger of checkpoints, not one diff at the end); a preservation-aware revert (/plumbbob:revert resets to a recorded SHA while keeping your plan and notes, and restores only SHAs the loop wrote); and a build record that rides the PR (the tracked builds/<slug>/ folder merges into main with the branch). Guidance on the work, a latch on the record.