/kyoshi-command

name: kyoshi-command
description: Suki's command of the Kyoshi Warriors for a standing program. She holds the island for days, writes every order, and reads every report, and she never picks up a fan herself. Use for orchestrate, "run this whole project", "own this migration until it lands", or a multi-day program of many stacked PRs and dozens to hundreds of subagents under one coordinator chat with minimal human turns.

Suki's Kyoshi command

When Suki commands the island's defense, she does not fight on the beach. She writes clear orders, posts warriors where they belong, reads every runner's report at set times, and keeps the front line holding. You own the program, never the code. Author briefs, drain the queue, keep the frontier green, and decide.

This skill is for a whole project handed to one standing coordinator chat. It runs for days, spans many stacked PRs, and uses dozens to hundreds of subagents, with the human checking in twice a day instead of every five minutes. One task driven to a predicate belongs to `night-watch`. One ambitious run that needs a bespoke workflow belongs to `day-of-black-sun`. Route here only when the work outlives any single agent. Work one agent could finish inside the session's budget is not a program, however program-shaped the request sounds.

Prove behavior with the project's verify skill (see `vital-signs`), or with Claude Code's `run` skill when the repo has none. Every brief names the resolved skill path or the exact commands.

On Codex, read [avatar-mode/references/codex.md](../avatar-mode/references/codex.md) for tool equivalents.

Ceremony must scale with the program. On cheap, near-identical units, collapse it as each section directs.

Three rules carry the rest.

• Completions are queue events, not interrupts.
• Every spawn and every resume carries the standing orders verbatim.
• The brief is the product. A vague brief fails quietly, because a worker cannot ask you a question.

Roles and placement

• **Coordinator (this chat).** Frames, authors briefs, drains the inbox, owns the human report, and makes judgment calls. It never authors or edits code. Conflicted merges, chain rebases, and code changes are always tasks. Mechanically landing a verified unit (a fast-forward or clean cherry-pick of a worker's commit, then a push) is bookkeeping the coordinator may do itself on repos where local git is cheap. Queueing finished work behind an idle stacker is how a deadline harvests nothing. The loop is agentic end to end. Agents are spawned and drained only through the Agent tool. Pick each subagent's character, model, and reasoning effort for the job, as the dispatch rules in `avatar-mode` describe. State reads and writes go through the `orch` CLI at drain points, one command in and one line out. The CLI never spawns, waits, or wakes anything.
• **Sub-coordinator.** Durable, one per track, and only when the program exceeds what one coordinator's drains can manage. A track the coordinator can drain itself needs no middle layer. Each nested layer re-pays a full orientation preamble, and a blocking sub-coordinator hides its children while the parent idles. It owns its track's units and boards, authors its workers' briefs, and spawns its own workers and verifiers where the runtime lets a subagent spawn one. Where it cannot, it owns its track's units directly with the same review separation. It rolls up aggregates at wave boundaries and never forwards raw child reports. Cap in-flight children at what one drain can process, roughly ten, as a rolling window. Never use blocking batches, which cost the slowest child of every batch.
• **Worker and verifier.** Background subagents (`run_in_background: true`), each dispatched as the character whose discipline fits the unit (`team-avatar:<character>`). Claude Code has no remote worker environment, so isolation is a worktree or branch per writer, not a separate machine. A subagent never sees this chat, so its brief inlines what it needs or points at repo and store paths. Prefer fewer, broader workers. Keep one writer per worktree or branch, so no two actors share a file. Run a unit's verifier on a different model family from its worker, taking the family from the avatar-setup sheet's `panel` line.

Depth stays at coordinator, track, worker. Author the track decomposition per project. Build, landing, and verification are common cuts, not a required shape. Hard-coded formation trees were tried and parked as too rigid.

The orch CLI

`orch` is `bun ../../tools/orch/orch.ts` from this file, under the installed plugin. It keeps the store's plain TSV and JSON files, which stay readable without the CLI. Pass the store with `--store <dir>` or the `ORCH_STORE` environment variable. Commands:

| Command | Does | |---------|------| | `orch init` | Create the store files. | | `orch standing show`, `orch standing add <line>` | Read or append the standing orders. | | `orch unit add <id>`, `orch unit set <id>`, `orch unit get <id>`, `orch unit list`, `orch unit counts` | Keep `units.tsv`. | | `orch ledger record <pr> <sha> <verdict> [--evidence PATH] [--verifier NAME]`, `orch ledger check <pr> <sha>`, `orch ledger summary` | Keep `ledger.tsv`. | | `orch inbox push <agent> <unit> <status> [--report PATH]`, `orch inbox drain`, `orch inbox count` | Queue completion pointers. | | `orch gate park <id>`, `orch gate list`, `orch gate resolve <id>` | Park human gates. | | `orch frontier set --repo <dir> [--forge gh\|origin] [--prs <n,...>]`, `orch frontier show` | Compute the merge frontier. | | `orch status` | Regenerate `status.md` and print a three-line summary. |

Run `orch <command> --help` for every option. Add `--json` for complete rows.

Store layout

Create `${CLAUDE_CONFIG_DIR:-~/.claude}/orchestrate/<project-slug>/` (on Codex, `${CODEX_HOME:-~/.codex}/orchestrate/<project-slug>/`), outside the repo and outside the session. The store has to outlive this chat. The program runs for days, a session restart