Multi-agent orchestration
A six-agent crew that plans, builds, and verifies.
The chain: prospector → draftsman → inspector → smith → judge, with a ledger you can read at any time.
Runs under pi and prime-agent. MIT.
01 / THE CREW
The pipeline
Five stages run in order. Each has a narrow job, a fixed tool budget, and a handoff you can read.
- 01
prospector
Finds the relevant files and lines. Read-only, fast.
14 tools
- 02
draftsman
Produces the plan. Read-only.
13 tools
- 03
inspector
Fresh-instance adversarial review of draftsman's plan. Gates smith until APPROVE. Read-only.
13 tools
- 04
smith
Builds. Executes the approved plan. Emits [DONE:n] progress markers.
24 tools
- 05
judge
Verifies smith's work against the plan (runs tests/type-checks). Returns APPROVE / REQUEST CHANGES / REJECT.
22 tools
questmaster
/smithy-quest onlyAssesses whether the quest goal is met. Fresh instance — did NOT do the work. Returns QUEST_COMPLETE / QUEST_CONTINUE / QUEST_SATURATED.
conditional
02 / EVIDENCE
The proof is on disk
The ledger records what happened. The gates define what APPROVE has to mean.
The ledger
# Plan
Status: done
## Steps
[x] 1. Add assertFiniteNumber() in src/validate.ts
[x] 2. Gate add()/div() args in src/calc.ts
[x] 3. Add test/index.test.ts
[ ] 4. (skipped) changelog entry
## Adversarial Reviews
### APPROVE (2026-06-24T15:58:51Z)
VERDICT: approve
## Verification
### APPROVE (2026-06-24T15:59:02Z)
tests pass, typecheck clean
VERDICT: APPROVE The gates
- Files exist
- Every file named in the plan is on disk.
- Tests added
- New behavior ships with tests, not promises.
- Test substance
- Tests assert outcomes, not plumbing.
- Edge cases
- Empty, malformed, and boundary inputs are covered.
- Evidence matches
- Cited output matches what the run produced.
- Typecheck / lint
- The compiler and linter come back clean.
03 / WHY IT'S DIFFERENT
Built for work you can audit
Most agent harnesses hand a single model a single toolset and say "go." smithy-agent runs a disciplined workflow and keeps the receipts.
-
Ledger
A plan you can actually see
Every plan, adversarial critique, and judge verdict persists to a per-run ledger at .smithy/runs/<tag>/plan.md (with .smithy/plan.md mirroring the latest) — human-readable, durable across restarts, and safe to read mid-run, diff, or grep.
-
Adversarial review
Plans get stress-tested first
Non-trivial plans are auto-reviewed by inspector — a fresh-instance critic — before anything builds.
Learn the mechanics → -
Verification
Work gets verified, not just produced
judge runs your test suite and type-checker and won't APPROVE until they pass.
Learn the mechanics → -
No spiral
It won't spiral
A thrash detector disengages on stalls and repeats; an echo-loop guard stops the model replying to its own subagent's stream. Autonomous runs stay sane.
-
Budgets
Hard budgets
Every run accepts a { tokens?, usd? } ceiling. Hit it and the loop stops cleanly with [DONE:budget] — no surprise invoices, no half-finished plans.
Learn the mechanics → -
Many runs
Many runs, one checkout
Several pi sessions can work in one checkout at once: each owns .smithy/runs/<tag>/ ledgers while .smithy/plan.md mirrors the latest, and a cross-process git lock serializes worktree add/remove, merge and copy-back. SMITHY_RUN_LOCK=strict opts back into refusing a second armed run. For several BRANCHES at once, a branch workspace gives each one its own linked worktree and its own persistent session: name an issue (`smithy 412`, a quoted #412, or an issue URL) or a branch, resume that branch with -c, and attach mid-session with /branch — in-process, nothing copied. A per-workspace session lock keeps one live session per checkout unless --new-session says otherwise, and "work on #412" in chat dispatches automatically.
Learn the mechanics → -
Code-graph memory
Optional code-graph memory
Register smithy-mcp-bridge and every agent gets tome — a code-graph server behind three tools (tome_search / tome_describe / tome_call). Agents query the graph when the bridge is up and fall back to grep when it isn't.
Install and configure the smithy-agent extension (works under both the pi and prime-agent harnesses) by following the guide here:
https://smithy-agent.netlify.app/install-guide.md