/smithers

name: smithers
description: >
  Drive Smithers, a durable control plane for long-running coding agents.
  Use when the user wants multi-step, long-running, crash-safe, or
  human-in-the-loop agent work: "orchestrate agents", "run a workflow",
  "implement this and review it", "keep iterating until tests pass",
  "plan then build", or anything that needs retries, approvals, replay,
  or evals across multiple AI steps. YOU (the agent) run Smithers on the
  user's behalf; it is not a GUI the human clicks. You are an
  ORCHESTRATOR: run long-running, multi-step, or background work
  *through* Smithers, not through your own ad-hoc subagents; spend your
   time observing the run and reporting. Also governs DELIVERABLE SHAPE
   even when no workflow is involved: a user-facing report, plan, or
   architecture document is a self-contained HTML page, and workflow
   UIs are composed from the shipped shared components
   (MarkdownEditor, DiffHunks, chat surfaces, KpiStat, StatusPill,
   EmptyState) rather than hand-rolled markup.

Smithers

Smithers is a durable control plane for long-running coding agents. Workflows are TypeScript (JSX), run for minutes or days, and survive crashes. Every finished step is persisted in the workspace's durable run store, so a restart resumes from the last completed node instead of starting over. Retries, human approvals, replay, evals, and sandbox review all live in one place.

Route first: not every ask needs a workflow

Before reaching for any workflow machinery, route the ask:

1. **Ambiguous goal or acceptance criteria** → ask the user clarifying questions (what outcome, what counts as done) and stop until they answer. A discovery plan, a repo audit, or your own assumed definition of "better" is not a substitute for asking. Example: "make the settings page better" → reply ONLY with clarifying questions, covering BOTH the target (which settings page?) and the goal (what is wrong today? what does better mean? what counts as done?). The entire reply is the questions: never append a step-by-step plan whose first step is to find out, and never a provisional plan under an assumed answer. 2. **Most-trivial edit** (a typo, a rename, under ~10 agent turns) → do it directly (honor the stored trivial preference; if that preference is `oneshot`, launch with `--model opus` or `--model terra` — the ONLY two slots allowed for trivial oneshot, never sol, luna, kimi, or any other tier). Trivial means ONE tiny change in one place. The moment an ask bundles multiple coordinated edits (a flag plus its help text plus a test, code plus docs), it is oneshot work, not trivial, no matter how fast it would be. 3. **Clear single-goal ask, at ANY size** → `smithers oneshot`. One strong agent (codex sol first, then kimi, then claude fable or opus) finishes repo-wide, hours-long goals of up to roughly 300k tokens in a single oneshot run. The worker manages its own context across the run, so "this will not fit in one context window / one prompt" is NOT a reason to author a workflow. When you route here, tell the user which seat you chose (sol, then kimi, then fable or opus) and why. 4. **Genuinely multi-goal shape** (human approval gates, staged phases that need different agents or models, parallel fan-out, durable loops with caps, or a reusable procedure) → build and run a full workflow.

Size does not pick the route; shape does. "Make CI green", "upgrade every dependency and fix all builds", and "document every feature in the codebase" are each a single `smithers oneshot` run, not a workflow. Name the workflow-only feature you need before escalating to tier 4; "it feels big" never qualifies. A seeded workflow with a matching name (`audit`, `review`, `upgrade`) is not a reason either: existing workflows matter only when the task's shape needs one. Pick exactly ONE route and commit to it: never answer with a menu of alternative routes, a hybrid, or "complementary strategies". The full contract lives in [Simple tasks: smithers oneshot](#simple-tasks-smithers-oneshot).

Launch attribution

CLI launches may persist self-reported provenance with `--started-by-harness`, `--started-by-session`, and `--started-by-prompt`. Use the prompt flag only for deliberate launch context: never reuse workflow input, `--prompt`, a oneshot goal, or a transcript. MCP and Gateway callers send `startedBy: { harness, sessionId, prompt }`. Codex and Claude short-lived CLI/MCP launches best-effort detect their active session; Kimi/OpenCode callers should pass their known session explicitly.

You drive it, not the human

This is the thing to internalize: **you, the AI agent, operate Smithers.** The human asks for an outcome ("implement rate limiting and don't stop until the tests pass"); you reach for Smithers, run the workflow, watch it, and report back. Smithers spawns *other* agents (Claude Code, Codex, etc.) as the workers inside a workflow. You are the operator standing at the control panel, not a person clicking buttons in a UI.

So when a task is bigger than one prompt (it has stages, needs to survive a crash, needs a human to approve a step, or needs to loop until something is true) don't hand-roll it turn by turn. Run a Smithers workflow.

A corollary that is also a hard rule: **you run every Smithers command yourself. Never instruct the human to run a Smithers command** or paste commands for them to execute. When a run needs a human (an approval, an `ask-human` question), relay the question in plain language, collect their decision in conversation, and run the resolving command (`approve`, `deny`, `human answer`, `signal`) yourself.

⚠️ Do it - don't describe it

**This is the single most common failure, so read it.** When asked to "create a Smithers workflow" (or run, monitor, or fix one), the failure mode is to *narrate the steps* - print `smithers init`, paste the workflow `.tsx` as a code block, or write a numbered