Smith
This session is the orchestrator. It never writes task code itself. It creates workers, sends them prompts, watches them, and brings their questions to the user. Workers do the work in their own worktree and tab.
Workers are Smith's copies, named after their task type and task: code-<id> for an issue or slug (code-101) and review-<id> for a PR (review-5737). The same name is the address and what the sidebar, toasts and reports show. This orchestrator's own tab is SMITH-ORC<n>, where <n> is its terminal address from the first digit on, uppercased (t7 gives SMITH-ORC7). Older runs keep the names recorded in run.json (smith-<id>, i<id>).
Prompt templates are in references/prompts.md. Backend-specific steps are in references/<backend>.md; this file points at their sections as "references/<backend>.md § <name>".
0. Pick the backend
| Condition | Backend |
|---|---|
HERDR_ENV=1 |
herdr |
HC_TERMINAL_ID set and hc server status succeeds |
herdr-app |
| Both | Ask the user once which one to use |
| Neither | Say "smith needs a Herdr TUI pane or the Herdr app", and stop |
Read references/<backend>.md now and use its sections wherever this file says § <name>. Read references/gotchas.md (the Common section plus your backend's section) before the first run in a session. Read each reference file with your file-read tool, or one cat per file, never several joined by echo separators: zsh expands a word that starts with = (echo ======), fails, and the rest of the command never runs.
Agent support
See references/<backend>.md § Agent support. Worker kinds come from Herdr, and tasks in one run can use different kinds.
1. Preflight
- Run
references/<backend>.md§ Preflight. It checks the environment, finds your own kind, settles worker kinds and creates or reuses the run directory~/.smith/runs/<repo>-<YYYY-MM-DD>(-appis added on herdr-app). - If a project or global rule forbids worktrees, tell the user this skill needs them and ask once. Record a scoped exception in your memory or notes if they agree.
2. Pick the tasks and the setup
Tasks. Use the IDs the user gave. Classify each ID before anything else, since a PR number and an issue number look the same:
| Check | Task type | Gates | Spawn |
|---|---|---|---|
gh pr view <id> --json state,author,url succeeds and state is OPEN |
review | findings / posted |
spawn.sh <id> - - (no worktree, runs in the repo root), Review kickoff |
| Anything else (an issue, a slug, a merged or closed PR) | code | spec / implemented / pr |
as below, Kickoff |
A full PR URL is a review task for that PR, even in another repo. Keep the URL as the task ID everywhere (gh pr view <url>, spawn.sh <url> - -, the kickoff, send.sh, close.sh): a bare number would point at this repo. Worker names shorten it to review-<repo>-<number>.
Show the type per ID in the setup table. A run can mix both types. If a code-task issue already has an open PR (gh pr list --search "<id> in:title,body" --state open), ask whether to review that PR, resume its worker for review fixes (§ 8), or start a fresh code task. If they asked you to choose ("pick 3"), list open candidates (e.g. with gh issue list), read each one's blockers and dependencies, and choose tasks that can run in parallel without depending on each other's unmerged code. Show a table of the choices and why.
Setup. Detect each value from the repo's instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursor/rules and similar), your memory or notes, and recent branches and PRs (gh pr list --state all --limit 10 --json headRefName,baseRefName). Ask only for what you can't find:
| Setting | Where to look |
|---|---|
| Base ref for new branches (code tasks) | Project rules, epic or feature-branch notes, recent PR bases |
| PR base | Same as above (often the base ref's branch) |
| Branch name format | Branch-creation rules, recent branch names |
| Commit format | Commit workflow rules |
| Ship flow | A ship skill, or the project's PR rules |
| Pre-ship review | A self-review or preflight skill, if the project has one (else none) |
| Review skill (review tasks) | A PR review skill for the project (e.g. thrive-review-pr), else a plain gh pr diff review with findings only |
| Test and lint commands | Instruction files, package.json / composer.json / Makefile |
| Worker kind per task | Your own kind |
| Worktree root | ~/<repo>-wt/<branch> (override with WT_ROOT) |
| Gates | Default spec / implemented / pr |
Show the detected setup as one table and confirm it with the user before spawning anything. Use your structured question tool if you have one, otherwise ask in plain text.
Skills and slash commands differ between agents. When a step uses a skill (a ship or fix-PR flow), give workers the skill's file path ("follow <path>/SKILL.md") rather than a slash command, unless the worker kind is known to load that skill itself.
Dependencies within the run. If task B needs task A's unmerged code, cut B from A's branch (a stacked branch). Otherwise cut every task from the base ref. When two tasks will touch the same shared entry (a docs section, error-code list or registry), decide now which one owns it.
3. Spawn workers
Spawn each worker and deliver the Kickoff prompt (code tasks) or the Review kickoff (review tasks) from references/prompts.md, with your backend's gate instruction: references/<backend>.md § Spawn.
4. Watch
After every prompt that starts work, arm the watcher: references/<backend>.md § Watch. It reports one of:
- GATE: the worker reached a gate (spec, implemented, pr, or a question).
- BLOCKED: a dialog or escalation is waiting.
- STOPPED: no gate, and the worker has gone quiet.
- GONE: the agent exited.
5. When a watcher reports
- Read the worker:
references/<backend>.md§ Read a worker. - Report to the user based on what fired:
- GATE spec: the approach in a few lines, deviations from the task, and the worker's open questions as a table with your recommendation for each. Point out conflicts with sibling workers (same method, same docs section).
- GATE implemented: the commit hash, message and changed files (in the user's commit-report format if they have one), test and lint results, anything the worker changed from the approved spec, and new shared-environment problems.
- GATE findings: the worker's picker output verbatim (findings table with default picks, questions, coverage gaps), then ask for the picks and the post decision with the same options the review skill gives. Relay them with the Review picks template.
- GATE posted: the review URL, or that it wasn't posted.
- GATE question / pr: the exact question or draft text (thread replies, issue comments), verbatim.
- BLOCKED: what the dialog asks.
- STOPPED / GONE: what the screen shows, and whether to nudge, resume or drop the task.
- Ask for decisions, batching pending decisions across workers. Then relay them:
references/<backend>.md§ Relay answers. - Before you say "shipped", check the PR yourself: base, reviewers, labels, resolved threads and file list.
- After handling each report, run
RUN=<run> S/done.sh --ask. When it exits 0, every open worker has reached its last gate (prfor code tasks,postedfor review tasks) or is gone. End your report with one question: "All N workers are done. Close their tabs, their watchers and this orchestrator tab?" A yes runs § 7. A no closes nothing, and you don't ask again:done.sh --askexits 3 until new work starts (a spawn or a send). Exit 1 means some workers are still busy; say nothing about cleanup.
Keep a status table in every report: references/<backend>.md § Board.
6. Ship
Code tasks only. Only on the user's go-ahead per task, using the Ship template. Pre-answer the ship flow's routine questions with the user's standing answers (for example: local automated QA No because the dev site points at the main checkout, staging skipped from a worktree, default reviewer). Ask once whether those answers apply to all workers in the run.
Ship stacked tasks as stacked PRs (see Stacked ship in the templates). After a parent PR merges, the child needs a rebase and its PR switched to the real base.
7. Wrap up
On a yes to the § 5 question, or whenever the user says "close everything", run one command: RUN=<run> S/close.sh --all --self on herdr, RUN=<run> S/app/close.sh --all --self on herdr-app (details in references/<backend>.md § Wrap up). It closes the worker tabs and stops their watchers. Then, once your current turn ends, it closes your own orchestrator tab too. Report what it closed and any warnings in that same turn, and make it your last message: the tab goes right after. If a worker didn't close cleanly, the orchestrator tab stays open so you can sort it out.
Leave out --self when the user wants only the workers closed ("close the workers but keep this tab"), or when closing some tasks by id.
It keeps the worktrees, branches and run.json, since review fixes resume from them. The orchestrator's conversation can be picked up again with the agent's own resume (claude --resume). Clean up only what this run created, and only when the user agrees. When everything has merged, offer separately to remove the worktrees, delete the local branches and archive the run directory.
8. Resume a run
For review feedback, a follow-up or a session that lost track of a run ("resume yesterday's smith run"). A resume skips § 1 to 3: no new run directory.
- Find the run with
ls -t ~/.smith/runs/and read itsrun.json. Resume a run only with its own backend (run.jsonbackend, none = herdr). If it differs from the current one, say so and stop. - Restart or reuse each worker in its old conversation:
references/<backend>.md§ Resume. If that isn't possible, start a fresh worker and send a short catch-up prompt (issue, PR, current gate, decisions so far). - Send the follow-up prompt, e.g. "<reviewer> reviewed PR <n>. Follow <fix-PR skill path>, stop with the fixes and draft replies for approval." Then watch as usual.
- Stacked children: once the parent's fixes are pushed, tell the child to rebase onto the parent branch. After the parent merges, rebase it onto the real base and switch the PR's base.
Rules
- The user approves every spec, every ship and every text posted to GitHub or anywhere else. Workers never decide for the user, and neither do you. Relay, recommend, wait.
- Workers stop at each gate and ask in plain text, never through an interactive dialog. The kickoff tells them this.
- Never focus or close tabs, terminals or worktrees you didn't create. Never stop the Herdr server.
- Your own replies to the user follow the user's normal reporting rules.
Install for other agents
The skill is a plain folder in the Agent Skills format. Symlink it into each agent's skills directory so it updates in one place:
ln -s ~/.claude/skills/smith ~/.agents/skills/smith # shared dir (Codex, OpenCode, Pi and others read it)
ln -s ~/.claude/skills/smith ~/.codex/skills/smith # CodexFor an agent without skill support, point it at this file: "Read ~/.claude/skills/smith/SKILL.md and follow it."