SMITHY AGENT
v1.16.0 Install

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.

  1. 01

    prospector

    Finds the relevant files and lines. Read-only, fast.

    14 tools

  2. 02

    draftsman

    Produces the plan. Read-only.

    13 tools

  3. 03

    inspector

    Fresh-instance adversarial review of draftsman's plan. Gates smith until APPROVE. Read-only.

    13 tools

  4. 04

    smith

    Builds. Executes the approved plan. Emits [DONE:n] progress markers.

    24 tools

  5. 05

    judge

    Verifies smith's work against the plan (runs tests/type-checks). Returns APPROVE / REQUEST CHANGES / REJECT.

    22 tools

06

questmaster

/smithy-quest only

Assesses 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

.smithy/plan.md
# 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

6 / 6
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.

04 / INSTALL

Install in one paste

One prompt, both harnesses. Node 20 or newer.

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