Plumb

plumb

Runtime adapter

Claude Code remains the canonical runtime for this harness. When the current session is an OpenAI coding agent, read docs/openai-runtime.md before applying any instruction about roles, agent return values, tools, configuration paths, or command lookup. That document translates the execution surface; it does not replace the playbooks or principles below.

How to use this

When you start non-trivial work, make your first todo "read the principle index below". When the index points you at a principle, read that principle in full before applying it.

When you apply a principle, name it in your reply alongside the specific decision it changed. A citation with no decision attached is treated as evidence you never read the leaf.

Where roles run

docs/role-map.md is the source of truth for where each role runs. Do not write a model name in the body text.

Non-trivial work must open a todo line for the judge role. Open the line before you decide whether to run it.

That line closes exactly two ways:

• it runs
• it stays, carrying skip: <reason>

You cannot get away without opening the line. You cannot delete it either. Skipping is allowed; skipping silently is not. A todo list with no judge line is itself the mark of a breach of discipline.

The playbook index

If your work has one of the shapes below, read that playbook in full before you start. Playbooks name principles. A named principle means you read the leaf in full.

Investigate (changes no code)

Change

Ship

Keep going

Look, and hold the line

Decide, and design

What plumb has no playbook for

Shaping the work, writing the plan, running the plan, fixing a bug and writing tests are all plumb's own playbooks now. Enter through the "Change" section above. Not one line in this router forwards to an outside plugin any more.

Which upstream playbooks were not ported, and why, is in docs/scope.md.

Where the artifacts go

Do not assemble paths. Ask the tool.

plumb-* are thin wrappers in bin/. Claude Code puts every plugin's bin/ on PATH at install time, so you can call them by bare name from anywhere.

plumb-path spec      # approved designs
plumb-path plan      # plans being executed
plumb-path history   # finished plans
plumb-path run       # ledgers, decision logs, briefs
plumb-path spec --mkdir   # create it if it is missing

The default is <repo root>/.plumb/. Override it with PLUMB_ROOT, or with root= in .plumb/config. Spell a path out in prose and one of the two copies goes stale (principle-encode-lessons-in-structure).

spec and plan are not the same rank

"What has to pass for this to be done" is the spec. "Which tests, written how" is the plan. Same tests, two documents: the bar for judging goes in one, the implementation in the other.

run/ is not tracked (.plumb/.gitignore). Ledgers and decision logs are traces of the work, not the source of truth. Conversely, specs and plans are always tracked. A source of truth that disappears with the working tree is not a source of truth.

Retire a finished plan by freezing it

Do not leave a completed plan in plans/. In batch 1, a docs/plan.md frozen back at Task 1 sat 18 lines out of date, still flying a header that said "execute these in order" — and anyone who came along and executed it would have rolled back every fix from that day.

Move it to history/ and put this at the top:

> **This is history. Do not execute it.**
> The current source of truth is <path>. **If this document disagrees with it, the source of
> truth wins.** Do not sync this back up — syncing it revives the second source of truth.

What stops the damage is the header, not the directory name. Moving it is not enough.

An existing docs/superpowers/

Repositories that have used superpowers still carry docs/superpowers/specs|plans. Do not migrate them wholesale. Decide per repository. In a repository you have not migrated, assume the old material is under docs/superpowers/ when you go looking.

The principle index

Principles are not skills. They live in principles/<name>.md as plain documents (principle-prove-it-works is principles/prove-it-works.md).

They are not skills so that they cannot fire on their own. Stopping them with a flag also seals the path that opens them from this index — which is exactly what had happened on 2026-08-29. Stop them with structure instead: this index is the only way in, and it opens.

Read the full text of a principle you are applying. A summary is not enough.

Core

• principle-laziness-protocol — Lean toward deleting and toward the smallest change. When refactoring; when you feel the urge to add an abstraction
• principle-foundational-thinking — Settle the core types and data structures before the logic
• principle-redesign-from-first-principles — Design a new requirement as though it had been a premise since day one
• principle-subtract-before-you-add — Strip the dead weight first, then build on the base that got simpler
• principle-minimize-reader-load — Count the layers between question and answer, and the hidden state the reader has to carry
• principle-outcome-oriented-execution — Converge a migration on the target design. Do not leave a disposable compatibility layer behind
• principle-experience-first — Take the experience of the person using it over what is convenient to implement
• principle-exhaust-the-design-space — On a decision with no precedent, build 2-3 competing options and compare them
• principle-build-the-lever — Do not do it by hand. Build the tool that does it and the tool that proves it. The tool becomes an artifact the reviewer can re-run

Architecture

• principle-model-the-domain — Express the domain in structure, not in conditionals scattered around
• principle-boundary-discipline — Concentrate guards at the boundary. Trust the types inside
• principle-type-system-discipline — Make invalid states unrepresentable: brand your types, parse external data at the boundary, do not lie to the compiler, exhaust your variants, derive from the canonical schema
• principle-make-operations-idempotent — Converge on the same end state even after a half-finished run
• principle-migrate-callers-then-delete-legacy-apis — Migrate the callers and delete the old API in the same wave
• principle-separate-before-serializing-shared-state — Remove the sharing first. Serialize only when there is a real invariant

Verification

• principle-prove-it-works — Verify against the real thing. Do not settle for a proxy or for "the build passed"
• principle-fix-root-causes — Trace a symptom to its root cause. Reproduce it first
• principle-sequence-verifiable-units — Verify each unit before you move to the next. The ordering is itself your proof to the reviewer
• principle-gate-claims-on-evidence — Put a gate immediately before you write "done". If you did not run it, do not claim it
• principle-spend-on-the-outcome — Name the cost term a lever moved, measure it from the session, and state the spend per unit of finished work

Delegation

• principle-guard-the-context-window — When large output, long files, repeat reads, or a fan-out plan are about to fill the context. Push the bulky work to a subagent and keep only the summary in the main session
• principle-never-block-on-the-human — Push reversible work forward, then show the result and let them correct it

Meta

• principle-encode-lessons-in-structure — If you have written the same instruction twice, make it a lint, a check, or a script instead of prose