plumb

Files (143)

• marketplace.json · .claude-plugin/
• plugin.json · .claude-plugin/
• plugin.json · .codex-plugin/
• plumb-bulk.toml · .codex/agents/
• plumb-explorer.toml · .codex/agents/
• plumb-judge.toml · .codex/agents/
• plumb-pr-blindspot.toml · .codex/agents/
• plumb-pr-cutover.toml · .codex/agents/
• plumb-pr-diff-reader.toml · .codex/agents/
• plumb-pr-invariant.toml · .codex/agents/
• plumb-pr-refuter.toml · .codex/agents/
• plumb-pr-repro.toml · .codex/agents/
• plumb-worker.toml · .codex/agents/
• config.toml · .codex/
• .gitignore
• .gitignore · .plumb/
• codex-path-free-install.md · .plumb/history/
• software-factory-remaining-levers.md · .plumb/history/
• codex-path-free-install.md · .plumb/specs/
• harness-audit-2026-09-05.md · .plumb/specs/
• measured-efficiency.md · .plumb/specs/
• software-factory-remaining-levers.md · .plumb/specs/
• AGENTS.md
• CHANGELOG.md
• LICENSE
• NOTICE
• README.md
• SKILL.md
• pr-blindspot.md · agents/
• pr-cutover.md · agents/
• pr-diff-reader.md · agents/
• pr-invariant.md · agents/
• pr-refuter.md · agents/
• pr-repro.md · agents/
• plumb-banner-dark.png · assets/
• plumb-banner.png · assets/
• pr.json · bench/corpus/00001-00004/
• truth.json · bench/corpus/00001-00004/
• plumb-bench-extract · bin/
• plumb-bench-score · bin/
• plumb-check · bin/
• plumb-codex-install · bin/
• plumb-config · bin/
• plumb-decision-log · bin/
• plumb-doctor · bin/
• plumb-host-shots · bin/
• plumb-isolate-pollution · bin/
• plumb-lead-grade · bin/
• plumb-path · bin/
• plumb-pr-drift · bin/
• plumb-prompt-weight · bin/
• plumb-selftest · bin/
• plumb-session-audit · bin/
• plumb-statusline-cost · bin/
• plumb-trigger-eval · bin/
• plumb-worktree-audit · bin/
• artifact-lifecycle.md · docs/
• codex-implementation-graph.md · docs/
• harness-audit-2026-09-05.md · docs/
• openai-runtime.md · docs/
• …and 83 more

SKILL.md (first lines)

# 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.

## Apply only the relevant workflow

Use the requested outcome, existing authorization, and task risk to select one playbook below. Short, well-defined work can proceed directly. Read a principle in full when its decision criterion applies; name it alongside the decision it changes, without narrating every rule.

The current session remains responsible for integration. Runtime role mapping is in `docs/role-map.md`; read it when assigning roles. For non-trivial plumb work, keep one visible judge line: run the configured independent review or record `skip: <reason>`. A skip does not stop safe, authorized work or establish independent verification.

Continue through the requested deliverable and relevant checks. Ask only for unresolved choices that change scope, permissions, or the result. Existing approval remains valid; a playbook does not authorize external publication or messages. An explicit plan/review gate requested by the user still applies.

## The playbook index

If your work has one of the shapes below, **read that playbook in full before you start**.
Playbooks name principles; read a named principle in full when you apply it.

### Investigate (changes no code)

| Job | Playbook |
|---|---|
| How does this work, why is it this way, is it really safe, which of the two do we take | `playbooks/investigation.md` |
| A live process leaks, spins, or runs slow | `playbooks/runtime-forensics.md` |
| Read a profile / trace / spindump / heapsnapshot someone handed you | `playbooks/trace-forensics.md` |

### Change

| Job | Playbook |
|---|---|
| **Fix a bug** (it crashes, it is flaky, it came back after you fixed it) | `playbooks/fixing-a-bug.md` |
| Fix one slow thing, once | `playbooks/perf-issue.md` |
| Push one metric down, continuously | `playbooks/hillclimb.md` |
| Change the structure without changing the behavior | `playbooks/refactoring.md` |
| **Decide the shape of something you have not built yet** (what to build is still open) | `playbooks/shaping-the-work.md` |
| **Turn an approved shape into steps someone else can execute** | `playbooks/writing-a-plan.md` |
| **Land those steps, one task at a time** | `playbooks/running-a-plan.md` |
| Write tests, or repair existing ones | `playbooks/writing-tests.md` |
| Buy a design decision with an implementation you throw away | `playbooks/prototype.md` |
| Hand independent work out to parallel roles | `playbooks/fan-out.md` |
| Call a tool that needs several calls per answer, or the same call over many items | `playbooks/batching-chatty-tools.md` |

### Ship

| Job | Playbook |
|---|---|
| **Close out a branch** (decide between merge / PR / leave it) | `playbooks/closing-a-branch.md` |
| Open a PR | `playbooks/opening-a-pr.md` |
| Get it green and land it | `playbooks/landing-a-stack.md` |

### Keep going

| Job | Playbook |
|---|---|
| **Work a queue as the coordinator** (review the open PRs; implement the assigned issues one by one) | `plumb:lead` |
| Keep it running overnight; run until it is done | `playbooks/autonomous-run.md` |
| Stop safely; compaction is close | `playbooks/pause-safely.md` |
| Pick up where another session left off | `playbooks/session-pickup.md` |
| Set up an isolated workspace | `playbooks/worktree-setup.md` |
| Clean up worktrees and disk | `playbooks/worktree-cleanup.md` |

### Look, and hold the line

| Job | Playbook |
|---|---|
| Review a PR (as the one who approves it) | `plumb:pr-review` |
| **Ask for review and answer what comes back** (as the author) | `playbooks/being-reviewed.md` |
| Add a different model family's axis to that review | `plumb:interrogate` |
| Check whether the environment plumb claims still exists | `plumb:doctor` |
| See what a session spent its context on | `plumb-session-audit` |
| Decide which configuration of a playbook to run, with a number | `playbooks/evaluating-an-agent.md` |

### Decide, and design

| Job | Playbook |
|---|---|
| Coordinate dependencies, parallel work, or multiple sources of truth with an execution graph | `plumb:graph` |
| **Hand a branching decision back to the owner** (2+ options, and the choice changes what gets built) | `plumb:decision-brief` |

### 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.

| Job | Where |
|---|---|
| **Write or repair a skill** | Claude Code's skill-authoring conventions -> `claude plugin validate` -> `plumb:doctor` |
| Who to hand it to | `docs/role-map.md` |
| Driving panes and other agents | whatever `pane.driver` points at (unset: run it in the foreground) |
| The wake-up mechanism (when you wake) | `/loop` and `ScheduleWakeup`. **The discipline lives in `playbooks/autonomous-run.md`** |

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

## Artifact paths

When writing or retiring a spec, plan, or run ledger, read `docs/artifact-lifecycle.md`. Resolve paths with `plumb-path`; do not create a second source of truth.

## 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

From Haruki1090/plumb, MIT.

More from Haruki1090/plumb