SMITHY AGENT
v1.16.0 Install

01 / REFERENCE

Commands

All commands run inside the pi or prime-agent TUI once the smithy-core extension is registered. Commands colliding with prime built-ins (/usage, /context, /goal) register as /smithy-usage, /smithy-context, /smithy-goal there.

01 / Workflow

The multi-agent pipeline — collaborative (/smithy, you approve), autonomous (/smithy-auto, hands-off), or quest-driven.

Multi-agent workflow (prospector → draftsman → inspector → smith → judge). Collaborative.

workflow

Same workflow, fully autonomous — no approval gates. Hard 25-turn ceiling (override with SMITHY_AUTO_MAX_TURNS) — runaway-run backstop, not a token budget.

workflow

Force sequential (no parallel members).

workflow

Cap parallel members at N.

workflow

Arm the workflow in the current checkout even when the goal names an issue that belongs on another branch. The preflight normally refuses and points at /branch <issue>; --here is the deliberate override.

workflow

02 / Planning

Plan with prospector/draftsman/inspector; approve, revise, or cancel in plain prose.

Plan mode: a freeform interview (no multiple-choice prompts, no [ACTION: …] markers), a ## Brief checkpoint (Goal / Acceptance / Non-goals / Constraints / Assumptions) you answer with `go` or correct, then the model drives prospector → draftsman → inspector via task(), saves the plan to the run ledger and asks for plain-prose approval before smith → judge. --no-questions skips the interview and states the Assumptions: line (composable with --review). --review stops after the inspector APPROVEs and archives the plan without implementing; /plan approve leaves review mode. A second /plan approve after smith has built is refused — /plan revise <feedback> re-drafts instead.

planning

03 / Inspection

Review plans, verify work, and inspect what smithy loaded.

Standalone polish pass: UI consistency, UX journeys, codebase fit and test-tier coverage (unit → integration → feature → e2e), verified against the repo's own patterns and fixed in place. Shares POLISH_BAR with smith and judge; /smithy enforces the same bar via Q-polish.

inspection

Re-run only the read-only gates (inspector, judge) against a finished run's archived plan and diff the fresh verdicts against the recorded ones — verdict stability, writes nothing. Blind (recorded reviews, verifications, environment reports and findings are stripped first), write-free and comparable-gated: a dirty tree, a failed probe or a non-silent recorded run skips both spawns with one labelled reason. 'n/a' is not a pass — a non-comparable artefact reports 'not-compared', never a flip. Refuses while /smithy, /smithy-quest or /plan is active.

inspection

Show the AGENTS.md / CLAUDE.md files smithy loaded for this turn.

inspection

Show the rule files smithy loaded for this session. Pass 'full' to include content.

inspection

Show the Claude Code configs smithy loaded for this session. Pass 'full' to include raw content.

inspection

Show loaded Claude Code hooks; pass "on" to enable (env-gated).

inspection

04 / Meta

Inspect smithy state: checkpoints, compaction, agents, goals, todos, and the ledger.

Inspect smithy state (model, loops, sessions).

meta

Reload SMITHY_AGENT_THINKING* env overrides into the live session.

meta

Show current token/cost usage.

meta

Show bash timeout policy and statistics.

meta

List this session's background bash handles, or kill one. bash_bg runs a command detached with output in .smithy/bg/<id>.log.

meta

Show compaction config and statistics, or tune: /compaction config toolResultMaxBytes <N>.

meta

Show the current todo list.

meta

Create a git checkpoint now (without waiting for next turn).

meta

List recent git checkpoints in this session.

meta

Pick a session to resume — filtered, sorted and rogue-aware. --fork or --info change what the pick does; positional words filter by query.

meta

List sessions non-interactively as a markdown table — same filters as /sessions, no picker.

meta

Show detailed metadata for a single session.

meta

Apply the session staleness retention policy — dry-run by default; --apply confirms before deleting.

meta

List available agents (prospector, draftsman, inspector, smith, judge, +user-defined).

meta

Re-scan the user and project agents directories.

meta

Show or add/remove user-level allow/deny rules for tools.

meta

Manage per-path tool scopes. Subcommands: list, add, remove.

meta

Per-PR linked worktrees. list/status/path are read-only; new/rm print the slot CLI command (scripts/smithy-slot.mjs in a source checkout, the smithy-slot bin in an installed package).

meta

Attach this session to a branch workspace — a linked worktree under .smithy/workspaces/ created on demand. An issue (412, a quoted '#412', or a URL) resolves through the workspace registry first, then gh/glab. The branch's own session is resumed in-process; a branch with no session yet is started with pi -a -c. --new-session starts a second, independent session; --cancel clears a pending switch; --prepare only prepares it.

meta

Manage user goals. Subcommands: list, add, done, cancel, remove.

meta

Show ember state and unfinished todo count, or force-disengage with /ember off.

meta

Show repo update status (smithy-agent + my-pi-agent) and connected MCP servers. Works on pi and prime-agent.

meta

Pull latest from origin and rebuild if a build script exists (no-op otherwise).

meta

Walk the repo and generate AGENTS.md scaffolding at each directory.

meta

05 / Quest loop

/smithy-quest only

Quest-only commands used by the autonomous /smithy-quest loop, not the core /smithy workflow. The quest loop runs repeatedly — the parent model orchestrates prospector→draftsman→inspector→smith→judge→questmaster until the questmaster decides the goal is met, a backstop fires, or a user-supplied predicate passes.

Goal-driven autonomous LOOP (model-orchestrated). Repeats prospector→draftsman→inspector→smith→judge→questmaster until the goal is met, --until predicate passes, budget runs out, or --max-iters is hit. Questmaster (a fresh-instance critic) decides QUEST_COMPLETE / QUEST_CONTINUE <next focus> / QUEST_SATURATED between iterations.

quest

Every smithy slash command registered through pi.registerCommand, grouped by surface. Click any signature to copy it.

Legacy: /smithy_loop and its alias /ulw still dispatch but emit a one-time deprecation notice pointing to /smithy (collaborative) or /smithy-auto (autonomous). For parallel fan-out, use /smithy --concurrency=N or --sequential.