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.
prospector reads the codebase — files, symbols, references — and returns only what matters. Read-only, so nothing changes underfoot while the plan is being shaped.
prospectordraftsman 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.
draftsmanA fresh inspector instance stress-tests the plan adversarially. Nothing builds until the plan passes review — a gating handoff, not a courtesy glance.
inspectorsmith 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).
smithjudge 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.
judge02 / 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
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
predicate (test command or coverage metric)
compose the goal from .smithy/directive.md + unchecked .smithy/backlog.md items
hard USD ceiling (default 25)
hard cap on iterations (default 20)
open one PR at end aggregating all iterations
predicate evaluation timeout (ms)
Termination
Questmaster (or backstops) decide when to stop:
QUEST_COMPLETE or QUEST_SATURATED
--until expression passes
USD ceiling hit
--max-iters reached
2 consecutive no-progress turns