Smithy Agent

UNDER THE HOOD

How the workflow decides

A disciplined pipeline, not a single prompt. Each phase has a specialist, a tool budget, and a recorded verdict.

  1. Discover · prospector

    prospector reads the codebase — files, symbols, references — and returns only what matters. Read-only, so nothing changes underfoot while the plan is being shaped.

  2. Plan · draftsman

    draftsman turns the goal into a step-by-step plan, shaped to fit the appetite and the codebase prospector just mapped.

  3. Review · inspector

    A fresh inspector instance stress-tests the plan adversarially. Nothing builds until the plan passes review — a gating handoff, not a courtesy glance.

  4. Build · smith

    smith executes the approved plan in an isolated git worktree — the only agent that writes. On conflict you get an interactive chooser (judge-auto-fix, manual, or abort).

  5. Verify · judge

    judge runs your test suite and type-checker and won't APPROVE until they pass. The verdict lands in the ledger, durable across restarts.

The mechanics

The rails that keep an autonomous run sane.

Writers isolated by default

Under /smithy, smith (the only agent that writes) auto-runs in its own git worktree so concurrent builds never race on the same files. On success the branch merges back; on conflict you get an interactive chooser (judge-auto-fix, manual, or abort). Read-only agents (prospector / draftsman / inspector / judge) share the parent, which already reflects smith's merged work.

Parallel when it pays off

When work splits cleanly, /smithy spins up parallel members across isolated git worktrees and resolves merge conflicts with feedback-driven retries. When it doesn't, it stays sequential. Force sequential with --sequential, or cap with --concurrency=N.

Hard budgets

Every run accepts a { tokens?, usd? } ceiling. Hit it and the loop stops cleanly with [DONE:budget].

See the mechanics →

Prompt augmentation

Each smithy-aware slash command injects a system-prompt augmentation that teaches the model the workflow — when to spawn each specialist, how to read the ledger, how the worktree isolation rules apply. The model decides when to delegate; the harness keeps the receipts.

Thrash detector + echo-loop coalescer

A thrash detector disengages on stalls / repeats so autonomous runs don't spiral. An echo-loop coalescer accumulates the subagent's streamed output in memory and emits a single post-run message — the model never replies to its own subagent's stream mid-turn.

separate workflow

/smithy-quest

A goal-driven autonomous LOOP, distinct from the core /smithy pipeline above. The parent model orchestrates repeated passes — prospector → draftsman → inspector → smith → judge → questmaster — until the questmaster decides the goal is met, a hard backstop fires, or a user-supplied predicate passes. No human approval, no mid-run input.

The sixth agent: questmaster 🏆

After each judge APPROVE, the model spawns questmaster — a fresh-instance critic that did NOT participate in the work. Questmaster reads git diff --stat and .smithy/quest.md history, then emits one verdict on its final line:

  • QUEST_COMPLETE — emit [DONE]
  • QUEST_CONTINUE — loop for another iteration
  • QUEST_SATURATED — emit [DONE:saturation] (no more worthwhile work)

Flags

  • --until <expr> predicate (test command or coverage metric)
  • --budget-usd <n> hard USD ceiling (default 25)
  • --max-iters <n> hard cap on iterations (default 20)
  • --pr open one PR at end aggregating all iterations
  • --predicate-timeout predicate evaluation timeout (ms)

Termination

Questmaster (or backstops) decide when to stop:

  • verdict: QUEST_COMPLETE or QUEST_SATURATED
  • predicate: --until expression passes
  • budget: USD ceiling hit
  • iterations: --max-iters reached
  • stall: 2 consecutive no-progress turns

vs the core /smithy pipeline

/smithy/smithy-auto/smithy-quest
passes one one many (loops)
human-in-loop yes no no
stops when pass completes pass / budget questmaster / predicate / budget / stall / --max-iters
questmaster — — ✓ 6th agent