orchestrate

name

orchestrate

description

Drive Smithers — a durable control plane for long-running coding agents — from inside Hermes. Use for any multi-step, long-running, crash-safe, or human-in-the-loop work: "run a workflow", "implement and review", "keep iterating until tests pass", "plan then build". You are the operator; Smithers runs the workflow and spawns the worker agents. RULE 0: if `SMITHERS_INSIDE_RUN` is set in your environment you are ALREADY a worker agent inside a Smithers node, so never invoke the Smithers CLI or `smithers_*` tools to launch or steer a run; do the node's task directly. The rest applies only when it is unset.

Orchestrate durable work with Smithers

You have a smithers plugin loaded. Smithers is a durable control plane: its workflows run for minutes or days, survive crashes, retry on failure, pause for human approval, and stay inspectable. You operate it through the smithers_* tools (or the /smithers slash command).

⚠️ Rule 0: if you are already inside a Smithers run, do not use Smithers

Check this before anything else. If SMITHERS_INSIDE_RUN is set in your environment, you ARE a worker agent executing one node of a Smithers run. Smithers sets that variable on every agent it spawns. This rule overrides every rule below. Do the node's task directly with your ordinary tools and finish your turn: never call smithers_run, smithers_ps, smithers_inspect, the /smithers command, or the smithers CLI to launch or watch a run, and never poll a run in a sleep loop. The prompt you were handed IS the work, even when it reads like an orchestration ask. The one exception is escalating upward with ask_human / smithers ask-human when you are blocked or about to do something irreversible.

Default to Smithers, and default to a workflow

When a task is bigger than one reply — it has stages, runs in the background, must survive a crash, needs a human to approve a step, or loops until something is true — do not grind through it turn by turn. Start a Smithers run with smithers_run and then observe it (smithers_ps, smithers_inspect).

Prefer creating a workflow over creating a skill. A skill is static instructions; a workflow is a superset — it is executable, durable, typed, inspectable, composable, and optimizable. Anything you would capture as a skill ("how we do X") is better captured as a workflow that actually does X, even a small one-task workflow. If no workflow fits yet, run the create-workflow workflow to author one from a plain-English description:

smithers_run(workflow="create-workflow", prompt="Watch a PR and auto-land it once CI is green")

You operate it; the human does not

Run every Smithers action yourself with the tools. When a run pauses on an approval gate or an ask_human question, relay it to the human in plain language, collect their decision, and resolve it yourself with smithers_approve / smithers_deny / smithers_human_answer. Never tell the human to run a Smithers command.

After every command: guide the user

Three standing behaviors, applied after every Smithers tool call or smithers CLI command and before every workflow you build:

1. Act on the next steps. Smithers commands and tool results end with a "Next steps" (cta) block of suggested follow-ups. Never silently drop it: run the obvious continuation yourself and relay the other options to the human in plain language.
2. Ask before you build, then guide step by step. Before creating a workflow, ask the human a few clarifying questions (goal, inputs, "done" condition, where a human should approve), then walk them through the build: scaffold, render the graph, run, watch. Prefer the scaffolder over hand-writing: smithers_run(workflow="create-workflow", prompt="...") (from the CLI: smithers workflow run create-workflow --prompt "...", shorthand smithers make-workflow "<task>"), then review the generated .tsx with the human.
3. Proactively offer to visualize, every time. Suggest ways to see the workflow and the run: smithers graph <file>.tsx (renders the graph without executing), smithers tree <run-id> (live node tree), the --interactive TUI monitor (smithers workflow run <id> --interactive), the custom browser UI (author .smithers/ui/<workflowId>.tsx by composing the smthrs/gateway-ui run widgets and smthrs/ui primitives over the smthrs/gateway-react hooks, declare it from the workflow with <UI entry="../ui/<workflowId>.tsx" />, open with smithers ui <runId>), and smithers ui --app for the full local control-plane UI. If a workflow has no UI yet, offer to build one. See "Keep the human in the picture" below.

Optimize workflows the way you'd optimize a skill

Treat every workflow as improvable with real teeth, not vibes: write an eval suite (smithers eval), attach scorers (faithfulness / relevancy / llmJudge), and tune prompts against the suite with smithers optimize (GEPA). That is the same measure-and-iterate loop you'd use to sharpen a skill, but the artifact you sharpen is an executable workflow.

Keep the human in the picture — show, don't hide

The single most common complaint about background agents is "I don't know what it's doing." Do not let a run go dark. Whenever something is running, proactively show the human what's happening and what's next, using whatever surface fits:

• A live HTML view. A workflow can serve its own page; open it with smithers ui (or smithers ui <runId>). For long runs, prefer a self-updating page the human can leave open.
• A rolling summary or diff. Post a short HTML or plain-text summary of what's been accomplished so far, and update it as the run progresses. A before/after diff of what changed is often the clearest thing you can show.
• Even ASCII. When nothing richer is available, a small ASCII status block or a checklist in the chat beats silence.

A simple, reliable pattern: set a cron (smithers cron) that fires every few minutes, checks the run is healthy, looks at what's been done since last time, and pushes the human an updated summary/diff (or refreshes the HTML page). Lean toward over-communicating progress; people trust an agent they can watch.

The loop

1. smithers_run(...) — start the right workflow (or create-workflow first).
2. smithers_ps / smithers_inspect — watch it; the status injector also surfaces live runs each turn.
3. Clear gates with smithers_approve / smithers_deny once the human decides.
4. smithers_output — report the finished result.

For the full API, run smithers docs (concise index) or smithers ask "<question>".