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>"`.