Adonis0123/adonis-skills / skills/agent-dispatch
agent-dispatch
FlaggedChoose the lightest agent setup for a coding, review, drafting or design-research task: do it yourself, fan out to 2-3 workers with independent parts across the Claude Code, Codex, Grok Build, Cursor or other CLIs and accounts on this machine, run a scoped architecture loop, or send one brief to independent researchers; pick a cross-model reviewer, test budget and cleanup; track dispatched work, external waits and user decisions on a Run Board. Use when work may need delegation, or the user asks to dispatch, fan out, parallelize, run several agents or accounts, get another AI's review or independent design opinions, or asks how dispatched work is going. Chinese triggers: 派活、并行、要不要多开几个 agent、分给多个 Claude 账号 / codex / grok、找另一个 AI 审、对比优秀设计、多方意见、进度看板、派出的任务进行到哪了。Not for unrelated read-only questions, trivial edits, research with no delegation, a single review of an existing diff (agentic-review-handoff), or the machine-wide session list (sideby sessions). Inside another named workflow, only size its workers.
references/launch.md
View on GitHub# Launching, messaging and resuming Workers
Read this before starting any headless Worker, sending a fix round, or resuming a session. Use the `<command>` the probe reports per account (`accounts.md`); through sideby it already ends in `--`, a hand-written accounts-file command may not.
## Headless launch shapes
| Product | One-shot | Next round |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Claude Code | `cd <worktree> && <command> -p "$(cat <spec>)" --output-format stream-json --verbose --allowedTools <list> --settings '{"crossSessionInbound":"accept"}' < /dev/null > <lane>.jsonl 2> err.log` | `<command> --resume <session_id> -p "<delta>" ...` |
| Codex | `<command> exec --json -C <worktree> -s workspace-write -o <out.md> - < <spec> > <lane>.jsonl` | `<command> exec resume <session> ...` |
| Grok Build | `<command> --cwd <worktree> --prompt-file <spec> --output-format streaming-json --allow <rule> ... > <lane>.jsonl` | add `--resume <session>` |
| Antigravity | `<command> -p "$(cat <spec>)" --output-format json --print-timeout 0s` (drafting) | add `--continue` in the same worktree |
Write each Worker's event stream into the Run directory and register it with `lane add --output`; the Board reads the current activity from it. In Orca, prefer a titled Orca terminal handed to `orchestration worker-start --terminal` over a hidden headless run, so the Worker shows in the sidebar the user already watches (`run-board.md` § Orca mode). Grok has no Orca agent id: keep Grok Lanes headless.
## Why each flag is there
- **Never wait on a TTY.** Close stdin, run in the background, and grant the edit/run permissions the worktree needs, or a Worker hangs silently.
- **Claude permissions.** `--permission-mode acceptEdits` is not enough: Bash (`pnpm install`, git, tests) is denied under `-p` and the Lane stalls. Give the narrowest explicit allow list the Lane needs (`--allowedTools "Edit Write Read Bash(pnpm:*) Bash(git:*)"`; Grok `--allow <rule>`). Blanket modes (Claude `--permission-mode bypassPermissions`, Grok `--always-approve`) need the user's explicit authorization for this Run: a worktree only separates Git working files, it does not stop a command from reaching other paths, and the spec's Ownership is an instruction, not a sandbox.
- **Claude messages.** A `-p` session cannot show the approval dialog, so a message from the Coordinator or another session is held and dropped after five minutes unless the session accepts peer messages. `--settings '{"crossSessionInbound":"accept"}'` turns that on for this one Worker (Claude Code's own recommendation for unattended `-p` workers). Prefer it over `sideby messages inbound accept`, which changes the account's settings for every session.
- **Codex prompt on stdin (`-`).** `-i <image>` takes several values and swallows a prompt written after it, so a prompt given as an argument after `-i` is lost. `-o <file>` writes the final message, which is easier than reading the JSONL stream; add `-c tools.web_search=true` for research and `-s read-only` when nothing may change. Under `-s workspace-write` the Worker can write only inside `-C`; when its Return paths are in the Run directory, add `--add-dir <run dir>`. `exec resume <session>` keeps the first round's sandbox and directories.
- **Headless sessions load the user's full skills and global instructions**, which can dwarf a small task's cost: give trivial reviews to the cheapest available product.
## Reading the result
Claude streams JSON events ending in `result` (`session_id`, `result`, `total_cost_usd`, `num_turns`, `is_error`); Codex a JSONL stream whose `item.completed` events carry the messages (the final message is also in `-o`); Grok `streaming-json` events with `text` deltas ending in `end`. Read the task-spec Return block from that text; the Worker's whole summary file, technical lines included, is what the Coordinator reads (`task-spec.md`).
For any other CLI, check its `--help` for a non-interactive mode before dispatching; if it has none, do not use it as a Worker.
## Fix rounds and resumes
A fix round sends only the findings and Coordinator decisions, never the whole conversation. In order of preference:
1. A running interactive Claude Worker: `sideby send <session> "<delta>" --json` after `sideby send --help` succeeds; Orca Workers keep `orchestration reply`. Headless `exec`/`-p` runs cannot take messages: wait for the end, then resume (item 2).
2. A finished Worker: `sideby resume <id> -- -p "<delta>"` (Claude example); verify Host argument pass-through once, else the per-product "Next round" column above.
3. Do not assume any other resume behavior.
A Worker that stopped at a quota or rate limit, or that `show` flags for a long context, is not resumed in the same session: start a fresh session on an account with quota left, picked as in § Side Sessions step 2, give it the original spec plus `<lane>-progress.md` (`task-spec.md` § Progress), and register it as the next round with `lane set --round <n> --account <account> --output <new stream>`. Done steps stay done; nothing restarts from scratch.
Before either, register the round: `B lane set --id <lane> --round <N> --output <run dir>/<lane>-<N>.jsonl`, and redirect the resumed run's stdout to that file.
A fix round soon after the first resumes the same Worker session, so its cached context is reused. After a long gap the cache has expired and a resume rewrites the whole context (one Run, n=1, paid about $4-5 per resume to fix 2-5 findings); for a small delta after a long gap, start a fresh session with the original spec path plus the delta instead.
## Interactive sessions
With a multi-account manager such as sideby, interactive sessions stay the user's to start, with two exceptions. Inside Orca, once the user has authorized dispatch, you may open visible Orca terminals on sideby accounts for Workers, titled `<Lane short name> · <role>` (e.g. `B9 卡片 · 写`); sideby adds the account and id through `accountTitle`. Do not overwrite its Session Label. And a Side Session (next section) is opened without asking. Non-interactive `-p` / `exec` runs (`sideby run <ref> -- -p ...`) are fine when the user has authorized dispatch.
## Side Sessions
A request that arrives mid-task and is unrelated to the current task gets its own session (a Side Session, `../GLOSSARY.md`): no Lane in the current Run, no work on it in this session, and no question to the user first. Observed: sessions that each collected about six unrelated groups of requests were compacted 3-7 times and sent 250k-470k tokens per request, because a session re-reads everything it holds on every turn.
**Unrelated** means all three hold: the request shares no files with the current task, needs no result of the current task that has not landed, and has its own acceptance check. A wider scope for the current task is not unrelated and stays in this session; so does a question you can answer in one reply from what is already in context.
1. **Count.** At most 3 Side Sessions opened by agents are open at once. Name each `side-<slug>` (worktree, branch, terminal title) so they can be counted: `orca worktree list --json` in Orca, else `git worktree list` plus the ones this session started. With 3 open, open nothing and record the request as waiting on the user: `sideby unattended defer "<the request in one sentence>"` when sideby's Unattended Mode is on, else a numbered Ask in your next report. The count is best effort: no tool reports who opened a session.
2. **Account.** Pick it from the probe (`accounts.md`), never around it: the accounts the probe lists under a product are already filtered by the user's allow-list. `<family>` is the Coordinator's own product unless the request needs another. When the probe's `allow` is non-empty, take the listed account of that product whose fullest quota window is lowest (`sideby quota <ref> --json`, `usedPercent`; `SKILL.md` § Spend) and start it with its own `<command>` (`sideby run <ref> --` through sideby; without sideby there is no quota to read, so take any listed account); when the product has no allowed account, start nothing and record the request as in step 1. Only when `allow` is empty may sideby choose: `sideby next <family> --` starts the account with the most quota left (`--dry-run --json` names it without starting, for a headless run); without sideby, use the probe's `<command>`. Below, `<start>` is that command.
3. **Worktree.** Create it first, by the first row of the table below that applies: the brief names its path.
4. **Brief.** Write it from `task-spec.md` to a file outside the repository (`<state>/side/<slug>/brief.md`; `<state>` as in `run-board.md` § Ledger location). It must stand alone: the user's words, the change, the acceptance command and its expected result, the session's own worktree path, and the same limits a Worker has (no push, deploy, publish or message unless the user's request said so). End rule: report to the user in that session; when done, remove your own worktree, but keep it when it holds uncommitted changes and say so as a decision waiting on the user.
5. **Start** the session by the same row, then tell the user in one sentence where it is (the Orca worktree name, or the account and session id) and go back to the current task.
| When | Worktree | Session |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Orca is reachable (`run-board.md` § Three views, one ledger) and the user works in it (this session runs in an Orca terminal, or they said so); sideby on PATH | `orca worktree create --name side-<slug> --no-parent [--repo path:<repo>] --json` | In the first terminal the new worktree already has (`orca terminal list --worktree path:<worktree> --json`): `orca terminal send --terminal <handle> --enter --text "<start> 'Read <brief> and carry it out'" --json`, with step 2's `<start>`: `sideby run <ref> --` for the allowed account, or `sideby next <family> --` when there is no allow-list |
| Orca as above, no sideby | the same command | `orca agent launch --agent <id> --worktree path:<worktree> --surface terminal --prompt "Read <brief> and carry it out" --json`. Keep `--surface terminal`: per its help, without it the launch follows the user's Chat \| CLI setting and can open a chat, and with it the agent CLI always runs in a terminal, so no `terminal send` is needed. It takes Orca's own agent ids and cannot pick an account, so with an allow-list use it only when the probe lists that product under its plain command (what an Orca agent id starts); otherwise send the allowed account's `<start>` with `orca terminal send` as in the row above |
| Otherwise | `git worktree add <path> -b side-<slug>` | A background headless run from § Headless launch shapes with the brief as its spec, on step 2's account (its `<command>` from the probe), its stream kept outside the repository. Its exit wakes you: relay its outcome line to the user, nothing more |
- Pass neither `--activate` nor `--focus`: by default these Orca commands leave the user's active view alone.
- Run on Orca CLI 1.4.259 with sideby 0.38.0: `worktree create`, `terminal list`, `terminal send` with the line used when there is no allow-list, in its dry-run form (`sideby next <family> --dry-run`), and `worktree rm`; the user's active view did not change. Starting a real agent session this way, the `sideby run <ref>` line and `orca agent launch --surface terminal` were not run. Use the worktree's own first terminal rather than `orca terminal create --command`: in a worktree that had never been shown, 2 of 3 terminals created that way became orphaned background handles outside the tab layout. Read the commands' `--help` before the first use; it wins over this page. The text is typed into a shell, so pass the brief as a path, never as inline text.
- Permissions are those of § Why each flag is there: the narrowest allow list for a headless run, and no blanket mode without the user's explicit authorization. A session started in an Orca terminal (the first two rows) is bound by the same limits, which its brief spells out (no push, deploy, publish or message unless the user's request said so), and its start line carries no flag that loosens permissions (no `--permission-mode bypassPermissions`, `--always-approve` or the like).
## Stopping
Stop processes by pid, never by a command-line pattern: a pattern once stopped another Run's background process and a researcher. Orca Workers: `orchestration worker-stop`.
## Reviewer prompts
A reviewer prompt (e.g. for `open-code-review-delegate`) names the range (`<base>..<head>`), a requirement summary, the focus list, 100% file coverage, and "also review the tests and docs OCR excludes". For a merge commit, review the conflict resolution with `git show --remerge-diff <merge>` plus the diff against each parent. A Codex reviewer under `exec -s read-only` cannot run Vitest (no temp dirs): it marks test execution `UNVERIFIED` and the coordinator re-runs the tests.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |