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.
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.
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.
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.
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.
Restart Claude Code (or /reload-plugins) to activate, then run plumbbob doctor (or /plumbbob:doctor in-session) to confirm the wiring.
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.
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.
A run's bare range, or /plumbbob:build on any step, carries the step straight through the verify tick and stops:
| Verdict | ● Plumb |
|---|---|
| Now | Step 1 on Opus - feat(limiter): add a token-bucket limiter |
| Next Up | Step 2 on Sonnet - feat(login): wire the limiter into POST /login |
| Range 2 on Sonnet: /plumbbob:run once step 1 lands |
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.
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.
/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.
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.
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.
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.
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:
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:
| Park | Why it matters | Lean |
|---|---|---|
| P1: missing request id | a line with no id cannot be traced to its request | tangent: an id is still logged when the client sends one |
| P2: buffered lines | a write per request costs a syscall under load | tangent: a performance call this goal does not make |
| Verdict | ● Plumb |
|---|---|
| Stop | Range 2 landed - read one real request's line before the timing and the docs build on it |
| Next Up | Step 4 on Sonnet - feat(http): log how long each request took |
| Range 3 on Sonnet: /plumbbob:run (steps 4-5) |
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.
The same five-step plan, three ranges and one blocker, driven three ways after the plan is approved:
| MOMENT | WITH RUNS | TYPED RANGES | A 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.
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.
Everything is downstream of three rules. When you wonder why the contract refuses something, it's one of these.
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 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.
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.
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.
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).
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.
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.
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.
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 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.
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.
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 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.