agent-plumb

A stupidly simple, agent-driven workflow for building real software with AI without the AI making stuff up. The state file is the program. The playbook is the questioning agent. The filesystem is the retrieval system. No orchestrator, no database, no RAG, no magic.

📖 Read the v1.0 → v1.9 walkthrough → — single-page entry-point with an interactive architecture diagram, three reader-driven foundation-validation checks, and a review mode you can use to flag sections and export feedback. Best opened in a browser. Current as of v1.8.3 + v1.9 ship-batch (multi-model adapter, auto-advance steps, MCP-doctrine sentinel, /sdd-verify-stack post-wizard reality check, /ship CR convergence gate, lego-style model-tier-per-action, specialised subagents).

What this solves

If you've used Claude Code, Cursor, Lovable, or any other AI coding tool, you've probably had this happen:

• You asked for X, the AI built X plus a fake "47 founders on the wait list" counter you never wanted.
• The AI shipped something that technically works but misunderstood your intent.
• The agent quietly softened a section you'd already approved to make verification easier.
• Six months later you can't remember why the AI picked one tech over another.
• Documentation drifted. Schema drifted. Tests skipped.

Agent Plumb makes the wrong path mechanically checked at every commit, not just discouraged. With Agent Plumb configured (hooks active, manifest pinned, no --no-verify bypass), the agent cannot commit code that drifts from its spec — git pre-commit hooks refuse the commit. The "moat" hook re-runs your verification checks on every commit and blocks any "the agent claims it works" assertion that doesn't match what fresh tests actually report. (Honest caveat: a determined human with --no-verify or a misconfigured project can route around any check; the framework's discipline is "every committed atom is mechanically verified," not "physically impossible to drift.")

You bring the what (in plain English). The agent proposes the how (with tradeoffs you can react to). Every decision is captured in markdown files you can read, share with an investor, hand to a future engineer, or rebuild in a different stack.

What Agent Plumb is — and isn't (explicit tradeoff)

Agent Plumb is opinionated. It optimises for some things and gives up others. Knowing the trade upfront prevents misunderstanding:

Agent Plumb optimises for:

• Honest review over fast iteration. Every step's content + commit shape is reviewable. Re-approval ceremony for changed approved sections. Append-only audit log. Mutation-verified tests.
• Plain English over technical precision. Non-technical users drive specs; jargon gets translated on first use; status output reads in 30 seconds.
• Explicit over clever. Each step declares its tag, its touches, its triggers. No magic. No discovery.
• Predictability over flexibility. Same 4-step inner loop every iteration. Same commit shape. Customisation = adding rows in the standard format, not changing the format.

Agent Plumb explicitly gives up:

• Power-user ergonomics. Engineer-comfortable shorthand isn't here.
• One-shot speed. A SPEC takes 30–90 minutes the first time. The wrong choice for "I want it built right now."
• Technical-precision in prose. Hook stderr says "the database can't be reached so the form shows 'please try again'" — not "DB unreachable, returning 503."
• Free-form architecture. Side-stepping the rubric isn't allowed. Skip a section explicitly with a reason or stay in the discipline.

The 3-phase spine (v0.9)

SPEC → BUILD → SHIP → SHIPPED
  ↑              ↓
  └── (bug task) ← CI fail

Each phase has its own actions (small focused steps). You can never skip a phase. You can never advance while the current phase has unanswered [ ] blockers — the safety net (the pre-commit-rules.sh enforcer with state_rules) refuses the commit.