SMITHY AGENT
v1.16.0 Install

01 / THE PIPELINE

How the workflow decides

A disciplined pipeline, not a single prompt. Each phase has a specialist, a tool budget, and a recorded verdict. Runs on both the pi and prime-agent harnesses.

Phase What happens Owner
01 Discover

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

prospector
02 Plan

draftsman turns the goal into a step-by-step plan, shaped to fit the appetite and the codebase prospector just mapped — including the polish tiers the change touches and what proves each one.

draftsman
03 Review

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

inspector
04 Build

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).

smith
05 Verify

judge runs your test suite and type-checker and won't APPROVE until they pass. It also runs the polish pass — UI consistency, UX journeys, codebase fit and test tiers against the shared POLISH_BAR — and routes gaps back as follow-ups smith implements. The verdict lands in the ledger, durable across restarts.

judge

02 / MECHANICS

The mechanics

The rails that keep an autonomous run sane.

  • Writers isolated

    Writers isolated by default

    smith is the only agent that writes, so it auto-runs in its own git worktree — 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

    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.

  • Run lock

    Many runs, one checkout

    Several pi sessions can run /smithy in the same directory: each gets an 8-hex tag and its own ledger at .smithy/runs/<tag>/ (plan, quest and run.json), while .smithy/plan.md mirrors the latest run for humans and /doctor shows the authoritative path. Ids, branches and artifacts are run-tagged. The operations that touch the shared tree — worktree add/remove, merge, copy-back — take a cross-process git lock, so contention reports 'another process is merging' and retries instead of corrupting the checkout. SMITHY_RUN_LOCK=strict opts back into refusing a second armed run; off disables both locks and is unsafe.

  • Slots

    Slots: one worktree per PR

    For a separate working tree per PR, use a slot at .smithy/slots/<name>: its own checkout, its own .smithy/ state and its own run registry, so two branches can be checked out at once and same-file edits cannot collide. node scripts/smithy-slot.mjs new|list|status|path|finish|rm|gc manages them; /slot shows status in-session and /doctor prints the slot block. Read-only config (scopes, goals, rules) falls back to the primary checkout; /goal and /scope add|rm are run there.

  • Hard budgets

    Branch workspaces: several branches at once

    The `smithy` launcher creates a linked worktree for a branch inside the project and starts pi in it, so two branches can be worked on at the same time from one directory. Name an issue instead — `smithy 412` (or a quoted #412, or an issue URL) resolves it through the workspace registry, then gh/glab, and derives one branch name; a new branch is only cut from the default branch unless --base says otherwise. Each branch keeps ONE persistent session: `smithy <branch>` resumes it with -c, and /branch attaches to it in-process via switchSession — nothing is copied, and a branch with no session yet is started with pi -a -c. --new-session starts a second, independent session, and a per-workspace session lock refuses a second live pi/smithy in the same checkout unless you pass it. Typing "work on #412" in chat attaches and continues in one step; a bare ref only suggests /branch 412. The agent can do it too: the branch tool teaches the model to move the session when the work belongs on another branch instead of editing the wrong checkout.

    See the mechanics →
  • Prompt augmentation

    Hard budgets

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

    See the mechanics →
  • Thrash detector

    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.

  • Reliability rails

    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.

  • Reliability rails

    A turn-end watchdog gives one auto-continue to a turn that ends announcing work without doing it (never twice in a row, 3 per session; SMITHY_AUTO_CONTINUE=off disables it). After a foreground smith, a flight check runs typecheck in the parent checkout and tags the report with _flight:. And long builds don't die at the bash timeout — bash_bg runs them detached, with bash_bg_read polling the log.

03 / QUEST

/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

Agent Role and verdict
06 / questmaster conditional

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

Flag Meaning
--until <expr>

predicate (test command or coverage metric)

--backlog

compose the goal from .smithy/directive.md + unchecked .smithy/backlog.md items

--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:

Trigger Rule
verdict

QUEST_COMPLETE or QUEST_SATURATED

predicate

--until expression passes

budget

USD ceiling hit

iterations

--max-iters reached

stall

2 consecutive no-progress turns