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.
workflowSame workflow, fully autonomous — no approval gates. Hard 25-turn ceiling (override with SMITHY_AUTO_MAX_TURNS) — runaway-run backstop, not a token budget.
workflowForce sequential (no parallel members).
workflowCap parallel members at N.
workflowArm 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.
workflow02 / 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.
planning03 / 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.
inspectionRe-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.
inspectionShow the AGENTS.md / CLAUDE.md files smithy loaded for this turn.
inspectionShow the rule files smithy loaded for this session. Pass 'full' to include content.
inspectionShow the Claude Code configs smithy loaded for this session. Pass 'full' to include raw content.
inspectionShow loaded Claude Code hooks; pass "on" to enable (env-gated).
inspection04 / Meta
Inspect smithy state: checkpoints, compaction, agents, goals, todos, and the ledger.
Inspect smithy state (model, loops, sessions).
metaReload SMITHY_AGENT_THINKING* env overrides into the live session.
metaShow current token/cost usage.
metaShow bash timeout policy and statistics.
metaList this session's background bash handles, or kill one. bash_bg runs a command detached with output in .smithy/bg/<id>.log.
metaShow compaction config and statistics, or tune: /compaction config toolResultMaxBytes <N>.
metaShow the current todo list.
metaCreate a git checkpoint now (without waiting for next turn).
metaList recent git checkpoints in this session.
metaPick a session to resume — filtered, sorted and rogue-aware. --fork or --info change what the pick does; positional words filter by query.
metaList sessions non-interactively as a markdown table — same filters as /sessions, no picker.
metaShow detailed metadata for a single session.
metaApply the session staleness retention policy — dry-run by default; --apply confirms before deleting.
metaList available agents (prospector, draftsman, inspector, smith, judge, +user-defined).
metaRe-scan the user and project agents directories.
metaShow or add/remove user-level allow/deny rules for tools.
metaManage per-path tool scopes. Subcommands: list, add, remove.
metaPer-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).
metaAttach 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.
metaManage user goals. Subcommands: list, add, done, cancel, remove.
metaShow ember state and unfinished todo count, or force-disengage with /ember off.
metaShow repo update status (smithy-agent + my-pi-agent) and connected MCP servers. Works on pi and prime-agent.
metaPull latest from origin and rebuild if a build script exists (no-op otherwise).
metaWalk the repo and generate AGENTS.md scaffolding at each directory.
meta05 / Quest loop
/smithy-quest onlyQuest-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.