SMITHY AGENT
v1.16.0 Install

01 / THE CREW

The six agents

Five core agents — prospector, draftsman, inspector, smith, judge — run every /smithy. A sixth, questmaster, joins only during /smithy-quest. Same agent definitions on pi and prime-agent: under prime, their file/shell work flows through the persistent ipython kernel.

Agent Role Tools Handoff
01 prospector

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

14 tools passes findings
02 draftsman

Produces the plan. Read-only.

13 tools hands plan
03 inspector

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

13 tools APPROVE → build
04 smith

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

24 tools hands work → verify
05 judge

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

22 tools —
06 questmaster conditional

Assesses whether the quest goal is met. Fresh instance — did NOT do the work. Returns QUEST_COMPLETE / QUEST_CONTINUE / QUEST_SATURATED.

16 tools —

01 / prospector

14 tools

The prospector. Reads the repo and returns the small set of files and line ranges that matter for the goal — never writes. When the knowledge-base bridge is connected, prospector queries the code graph via the tome trio (tome_search / tome_describe / tome_call — injected into its session from the parent bridge) and falls back to grep/ast_grep when it isn't.

Role
Finds the relevant files and lines. Read-only, fast.
Runs when
When the goal touches code the parent model has not already loaded into context — i.e. the case where reading the whole repo would burn the budget before planning starts.
Handoff
passes findings

Tools

  • read
  • grep
  • find
  • ls
  • ast_grep
  • lsp_query
  • comment_check
  • web (2)
  • cached (2)
  • tome trio (3)

Example

reads repo → returns ["src/calc.js:12-48", "src/format.js:5-22", "package.json:scripts.test"]

02 / draftsman

13 tools

Turns prospector's findings into a numbered, executable plan and hands it back to the parent. Read-only — draftsman edits neither your code nor the ledger; the harness ledger observer persists the plan to `.smithy/plan.md`. The plan also names the polish tiers the change touches — `## Polish plan`, one line per tier with a concrete acceptance check or a labelled `n/a` — so smith builds to them instead of learning them from a review round. Forces itself into the loop for any open-ended goal or 3+-file change so the build has a blueprint to follow.

Role
Produces the plan. Read-only.
Runs when
Always for open-ended goals and 3+-file changes. Skipped only when the goal is trivial enough that a one-line fix doesn't need a plan ceremony.
Handoff
hands plan

Tools

  • read
  • grep
  • find
  • ls
  • ast_grep
  • lsp_query
  • web (2)
  • cached (2)
  • tome trio (3)

Example

findings + goal → 5-step .smithy/plan.md with checkboxes, file paths, and a short rationale per step

03 / inspector

13 tools

A fresh-instance critic (no shared context with draftsman — eliminates self-review bias). Re-reads the relevant code and the plan, then issues a verdict in `## Adversarial Reviews`: `approve` / `request changes` / `block`. Required check 6 verifies the `## Polish plan` tiers — a UI change with no proving test tier, especially no e2e journey, comes back as `request changes` before a single line is built. A `block` sends you back to planning instead of wasting a build.

Role
Fresh-instance adversarial review of draftsman's plan. Gates smith until APPROVE. Read-only.
Runs when
Auto-runs on any non-trivial plan (the kind that warrants a second pair of eyes). You can also ask for a re-review in plain prose — the model re-runs the inspector on request.
Handoff
APPROVE → build

Tools

  • read
  • grep
  • find
  • ls
  • ast_grep
  • lsp_query
  • web (2)
  • cached (2)
  • tome trio (3)

Example

fresh-context read of .smithy/plan.md + repo → "VERDICT: approve" (or request changes / block with concrete follow-ups)

04 / smith

24 tools

The only writer. Under `/smithy`, smith auto-runs in its own git worktree so concurrent builds never race on the same files; on success the branch merges back, on conflict an interactive chooser (judge-auto-fix, manual, or abort). Emits `[DONE:n]` markers so the orchestrator can track progress against the plan. Once done, judge verifies (not draftsman — see Option A in the docs).

Role
Builds. Executes the approved plan. Emits [DONE:n] progress markers.
Runs when
Once inspector has approved the plan. Skipped for trivial goals where planning is overkill — smith handles the one-line fix directly.
Handoff
hands work → verify

Tools

  • read
  • grep
  • find
  • ls
  • edit
  • write
  • bash
  • apply_patch
  • ast_grep
  • lsp_query
  • comment_check
  • todos (2)
  • hashline (2)
  • web (2)
  • typecheck
  • tome trio (3)
  • MCP trio (3)

Example

reads approved plan → applies edits → emits [DONE:1] … [DONE:5] → commits on branch

05 / judge

22 tools

Runs your test suite and type-checker against the current tree — for the post-`/smithy` judge, smith's branch has already merged so the parent tree IS the verified code. Emits a verdict in `## Verification`: `APPROVE` / `REQUEST CHANGES` / `REJECT`. Step 4.8 also runs a polish pass against the shared `POLISH_BAR` — UI consistency, UX journeys, codebase fit and test-tier coverage — and routes any gap back as a follow-up smith implements. Each run appends to the ledger, so the history of audit accumulates. Ask for a re-check in plain prose any time.

Role
Verifies smith's work against the plan (runs tests/type-checks). Returns APPROVE / REQUEST CHANGES / REJECT.
Runs when
Automatically after smith finishes a multi-step plan. You can also ask for a re-verification in plain prose at any time.
Handoff
—

Tools

  • read
  • grep
  • find
  • ls
  • bash
  • ast_grep
  • lsp_query
  • comment_check
  • todo_read
  • hashline_read
  • web (2)
  • cached (2)
  • typecheck
  • test_finder
  • tome trio (3)
  • MCP trio (3)

Example

runs npm test + tsc --noEmit → emits "VERDICT: APPROVE" (or REQUEST CHANGES with concrete follow-ups)

06 / questmaster conditional

16 tools

A /smithy-quest-only agent. After each judge APPROVE, the questmaster (a fresh instance — it did NOT do the work) reads git diff --stat and the .smithy/quest.md history to assess progress. It returns EXACTLY one verdict on its final line: QUEST_COMPLETE (goal met — emit [DONE]), QUEST_CONTINUE: <specific next focus> (loop with a concrete next-iteration target the parent will use as the new goal), or QUEST_SATURATED (diminishing returns — emit [DONE:saturation]). The next-focus contract is what keeps iterations from drifting.

Role
Assesses whether the quest goal is met. Fresh instance — did NOT do the work. Returns QUEST_COMPLETE / QUEST_CONTINUE / QUEST_SATURATED.
Runs when
Only during /smithy-quest, after each judge APPROVE. Decides whether the quest loops for another iteration or terminates.
Handoff
—

Tools

  • read
  • grep
  • find
  • ls
  • bash
  • ast_grep
  • lsp_query
  • hashline_read
  • web (2)
  • cached (2)
  • test_finder
  • tome trio (3)

Example

reads git diff --stat + .smithy/quest.md → "QUEST_CONTINUE" (more valuable work remains)