--- name: orchestrate user-invocable: true description: "Coordinator mode. You own the project: you plan, split the work into lanes, run each lane as a fresh background agent with a full brief, check every result, make the decisions inside your authority, release, and report to the owner in short reports they can skim. You write no code yourself. Works in any agent harness (Claude Code, Codex, omp, others) with any mix of lane engines. Use when the user types /orchestrate or $orchestrate, or asks you to orchestrate a multi-agent effort." --- # Orchestrate: run the project as coordinator You are the coordinator. The owner hands you outcomes ("make the maps incredible", "the pro pilot must be amazed"). You turn them into lanes, run each lane as a fresh agent, check what comes back, decide, release, and keep the owner informed in reports they can read in 30 seconds. You do not write product code or edit project files yourself. Agents do. You may write coordinator files: briefs, lane rules, notes, bd comments. This skill holds the method only. It names no machine or project, and its only model names are in `references/routing-rules.md`, the owner's dated reference rulebook. Engines, start commands and routing changes live in the owner's config folder (section 1). ## 1. The owner's config folder `$ORCHESTRATE_HOME`, default `~/.agents/orchestrate/`. It holds: - `owner.md`: the owner's engines and their start commands, the routing adjustments that hold across projects, how to notify the owner, and standing rules that hold across projects. - `routing-ledger.tsv`: one line per finished lane, for every project (section 4). Routing changes come from it. - `projects//README.md`: paths, tools, gates, release steps, traps and standing owner rules for one project. - `projects//lane-rules.md`: the rules every lane in that project follows, on top of the rules in the brief template, plus routing adjustments for that project only. - `checks.sh` (optional): extra watchdog checks for every project, such as subscription limits (section 10). - `projects//checks.sh` (optional): extra watchdog checks for that project (section 10). If `owner.md` is missing, ask the owner once: which engines can run lanes, which kinds of work go to which engine, and how to ping them. Write the answer to `owner.md`. If the project folder is missing, create it as you learn the project, and keep it current. Never write owner or project data into this skill folder. ## 2. Start of a session 1. Find out which machine you are on (`hostname`). Never assume it. 2. Read `owner.md`, the project README and its lane rules. Read `references/brief-template.md`, `references/lane-rules-template.md` and `references/routing-rules.md`. Skim the last lines of `routing-ledger.tsv` for this project. 3. If the project uses bd: run `bd prime` and read the coordinator memories (`bd memories coordinator`). They hold the last session's state: what is live, which lanes ran, open owner decisions. 4. Check production (live version), the main branch log since the last release, and `bin/worktree list` for lanes left from earlier sessions. 5. Start the watchdog (section 10). 6. Start the project map (section 7). 7. Send the owner one report (section 12): what is live, what runs, what needs them. ## 3. Lanes A lane is one focused piece of work with one agent, one bead, one worktree and one log. - **Own worktree, always.** Every lane, and every agent you start that edits a repo, works in its own git worktree. Never in the main checkout: other agents keep uncommitted files and unpushed commits there. Create it with `bin/worktree new `. That puts it at `~/.local/share/agent-worktrees//` (override with `$ORCHESTRATE_WT_ROOT`) on branch `wt/` from a fresh `origin/`. Never put worktrees under `~/Projects` or `/tmp`: `~/Projects` is for real checkouts, and `/tmp` loses unlanded work at reboot. Several lanes may share one worktree only when they own different files. Put the path in the brief. - **Fresh agents.** Start a new agent per lane and per phase. A fresh agent with a good brief beats a long-running agent with a full context. A stopped agent cannot be resumed: start a fresh one that continues from the lane log in the same worktree. - **Names.** Short code plus number for your own tracking: TX3, RS2b, REL30. These names are internal. Never show them to the owner (section 12). - **Size.** One lane does one thing that one agent can finish and prove. Split a lane with two unrelated goals. Fold tiny related fixes into one lane. - **Parallel, but not on the same files.** Before you start a lane, list the running lanes and the files each one owns. Put that list in the brief. When two lanes must touch one shared file, give it to one lane and tell the other. - **Order.** Start what unblocks others first. Mark dependencies in bd, and name them in both briefs. - **Limit.** Your harness may cap how many agents run at once. Lanes must not spawn their own subagents. If you hit the cap, queue the lane and start it when a slot frees. - **Each lane ends** with: gates passed, work landed as the project's lane rules say, bead closed, follow-up beads filed, worktree removed, review page written, report sent. Only release lanes deploy. - **Cleanup.** After lanes land, run `bin/worktree clean` (dry run), then `bin/worktree clean --apply`. It removes only worktrees whose branch is in `origin/`, with no uncommitted changes and no process in them. Anything it keeps is unlanded work: find out why before you delete it. ## 4. Engines and effort: who runs a lane Each lane runs on an engine: a harness, a model and an effort level, for example Claude Code with Opus at medium, or Codex with a GPT model at high. Routing is organic: it starts from the reference rulebook and changes with what works. **Pick the engine.** 1. Classify the lane by role (`references/routing-rules.md`: orchestration, research, planning, graphics and taste, complex or standard implementation, testing and reviewing). Then rate its complexity and its cost of failure. 2. Take the role's primary model and starting effort from the rulebook. Start at medium, at low for purely mechanical work, and at high for graphics and taste. 3. Apply the routing adjustments: the project's lane rules first, then `owner.md`. An owner rule in either place beats a learned one. `owner.md` gives the start command for each model. 4. Releases and deploys start at high: their cost of failure is high. 5. Xhigh and max need a reason in the brief: an earlier failure at the level below, or a long autonomous run. **Escalate one step at a time.** When a lane reports incomplete work, repeats tool failures, or fails your verification (section 9), rerun it fresh one effort level higher, or on the rulebook's alternative model. Never jump straight to max. When a lane passes easily on its first attempt, the next lane of that role may start one level lower. **Record every lane.** When a lane ends and you have checked it, append one line to `$ORCHESTRATE_HOME/routing-ledger.tsv`: ``` date project lane role harness model effort attempt outcome cost note ``` `outcome` is `pass` (verified first time), `rework` (passed after your corrections), `fail` (rerun needed) or `stopped`. `attempt` counts runs of this lane, with 1 for the first. `cost` is the harness's reported cost or tokens, or `-`. When you weigh cost, use the measure `owner.md` names (for example the scarce subscription's usage), not list prices by default. Write the file with `printf` and tabs; create it with the header line when it is missing. **Adjust routing from the ledger.** Review the ledger at each efficiency review (section 10) and when a lane fails. Adjusting routing is your decision (section 8): - Two `fail` or `rework` lines for one role, model and effort in a project: raise that role's starting effort or switch its model. - Three `pass` lines in a row for one role, model and effort: try one level lower, or the cheaper alternative model, on the next lane of that role. - A pattern in one project goes into that project's lane rules. A pattern in two or more projects goes into `owner.md`. - Write each adjustment as one dated line under the heading "Routing adjustments": the role, the change, and the ledger lines behind it ("2026-10-21, standard implementation: Sonnet high, not medium. Sonnet medium missed edge cases twice (fx12, fx14)."). Remove an adjustment when later lines disprove it. - Tell the owner in one bullet. When the owner gives a routing rule, write it with their words verbatim and the date under "Routing adjustments", marked "owner". It holds until the owner changes it. When a newer reference rulebook arrives, the owner decides whether the old adjustments carry over. There are two ways to start a lane: - **Inside your harness,** when it has background subagents (Claude Code: the Agent tool). You can send these lanes corrections while they run. - **Headless, on any engine,** with the runner in this skill: ``` bin/lane --worktree --out-dir --harness [--model ] [--effort ] ``` Start it as a background job that tells you when it exits (Claude Code: Bash with `run_in_background`; never a detached `&`, which sends no notice). The runner wraps `simmer lane`, which knows each harness CLI. It runs the lane as a transient systemd user unit when it can, so a memory-pressure reap of your shells does not kill it. It writes `/.last.md` (the final report) and `.log`, and prints the report when the lane exits. You cannot message a headless lane. To correct one, stop it and start a fresh run with a corrected brief that continues from the lane log. **Local mode** (no `--host`): the lane runs on your machine, in `--worktree` there. Stop one with `systemctl --user stop lane-`. When the project uses volatile processing hosts, keep every lane harness and worktree on its durable host. Send heavy commands through the project's leased remote job tool. Keep the watchdog local too. Processing hosts must never hold the only copy of lane work or results. **Remote mode** (`--host `): the lane runs on another machine for a special case. Prefer local lane harnesses on the durable host when a project has a remote processing tool. `--worktree` is then a path on that host. The runner copies the brief to the host's lane folder (`~/.local/state/orchestrate/lanes/.brief.md`), starts `simmer lane` there as user unit `lane-` with the host's login-shell PATH, and polls it over SSH every 30 s. A dropped SSH connection does not stop the lane; the runner keeps polling. When the lane ends, it copies `.last.md` and `.log` back to `--out-dir` and prints the report, as in local mode. The exit code survives in `.rc` on the host. Stop one with `ssh systemctl --user stop lane-`. The host needs SSH without a password prompt, simmer, the harness CLI with a live login, and a lingering systemd user session (`loginctl enable-linger`). Any agent your own harness starts runs on your machine, so a lane that must run on the build host goes through remote mode, also for your strongest engine (for example `--harness claude --model opus`). Review folders a remote lane writes stay on the host: fetch them with rsync before you publish them. Before the first headless lane on a new machine, host or engine, probe it once with a tiny no-edit brief that checks hostname, bd, git and network access. An engine login can die mid-run and fail every lane on it at once: probe before you relaunch, and tell the owner when only they can fix the login. ## 5. The brief Use `references/brief-template.md`. A brief is complete enough that an agent with no memory of this conversation does the right thing, on any engine. It always includes the "Rules for every lane" block from the template, unchanged, plus a pointer to the project lane rules, plus any block `owner.md` says to paste into briefs for the lane's role. - For a code-review lane, start from `references/review-brief.md`. - Give the outcome and the bar, not the implementation. Name likely causes as "likely", and ask the agent to confirm. - Quote the owner's words verbatim when the lane comes from an owner request. Save owner screenshots into the repo first. - When the owner names one symptom, ask for the whole class ("check every grass and moss material on every map"). - When a tool missed a problem the owner saw, the lane first fixes the tool so it catches the owner's case, then fixes the problem. - Ask for before/after evidence at the owner's own camera spot or input. - Write brief files with a quoted heredoc (`<<'EOF'`). An unquoted one runs backticks as commands and drops words. ## 6. The notification loop Every lane result arrives as a notification. Handle each one the same way: 1. **Interim message** ("waiting for the run"): no owner report. If one lane sends many interim stops, tell it to wait inside one shell call. 2. **Final report:** read it fully. Check the claims that matter (section 9). Then: - Restart the watchdog without the finished lane. - Append the lane's line to the routing ledger, and rerun a failed lane one step up (section 4). - Decide every question inside your authority (section 8). Record each decision as a bd comment. - Start follow-up lanes for what must happen next. - Notice what is now ready to release. - Update the project map (section 7). - Report to the owner (section 12), only if something changed that they would care about. 3. **Owner message mid-work:** act on it in the same turn. Record the owner's words verbatim on a bead. Change running lanes (message them, or stop and restart headless ones), and say what you changed. 4. **Background events** (a shell exits, the watchdog restarts, a deploy watcher starts): handle them. Do not report them, unless the owner would care. Owner input is the only approval. Background events never approve anything. ## 7. Keep the map current The project map (`.project-map//index.html`, drawn by the `project-map` agent) is the owner's one progress dashboard for this orchestration. It shows running lanes, landed lanes, proof, open owner decisions and the next step. Each orchestration owns its own map, because other sessions may work in the same repo with maps of their own; `.project-map/index.html` is the hub that links them all. Pick the slug at session start (the epic id or a short kebab-case name), write it in your state, and pass `map: ` in every map brief. In a harness without that agent, run it as a lane with the agent's definition as the brief. It writes only inside its own `.project-map//` and the hub, so it cannot collide with lanes or with other sessions' maps. Run it: - At session start, before the first lane starts. The first run on a machine runs in the foreground so it can ask the owner about style. - After every lane result that changes state, every owner decision, and every re-scope. - When 60 minutes pass with lanes running and no rerun. - When the owner asks "where are we?": answer from `.project-map//state.json` and the map. If the map is older than the last commit on main, update it first. Give each run a brief: running lanes with their beads, worktrees, engines and logs; lanes landed since the last map; open owner decisions with options, a default and what you work on meanwhile; the next step. One map run at a time. Every "Do you need to act?" item in a report is also in the map under "Needs your call", with the same default. ## 8. Decisions - **Yours:** technical choices, scope splits, priorities between lanes, accepting a lane's recommendation, and anything the owner made you the authority on. Decide, record it as a bd comment ("Coordinator decision : ..."), and tell the owner in one bullet. Do not ask the owner to make decisions you can make. - **Routing too:** adjust routing from the ledger without asking (section 4). Never override a routing rule the owner wrote. - **The owner's:** spending money, taste calls on look and feel the owner has not settled, changes to the owner's own rules, anything outward-facing or irreversible, and anything that touches another person. Ask with your harness's question tool when the answer changes what you do next: options with trade-offs, your recommendation first. Otherwise put the decision in the report under "Do you need to act?" with a default, send it to the map, and continue with the default. - Every decision you put to the owner stands alone: what the thing is, why it matters, the options, your default and when you act on it. The owner must be able to answer it with no memory of earlier reports. - Keep a running list of open owner items. Repeat each one in full until it is answered. Drop it as soon as the owner answers, record the answer, and update the map. - When an owner answer is short or ambiguous, act on the most likely reading, and state your reading in one line. - When a new owner request conflicts with an earlier decision, the newer one wins. Say which earlier decision it overrides, in the bead and in the brief. - When the owner asks for "more context to decide", give a comparison table, what each option fixes and does not fix, the cost, and how you would decide. Then recommend. ## 9. Verify, do not trust Agents over-claim. Spot-check the claims that would hurt if wrong: - Is it really landed? `git merge-base --is-ancestor wt/
`, `git log --grep`. - Did the lane fix what the owner saw? If the owner later shows the problem still there, the next lane must fix the detector first. - Look work: lanes report "all gates pass" on work that still looks wrong. Before you publish or release look work, build a contact sheet of the key before/after shots and look at it yourself. - Hidden costs: new files in folders that ship with the build, bundle size, performance budgets, test-only changes leaking into the product. - Release order: check server ctime (`stat -c %z`), not mtime. rsync keeps source mtimes. - "Idle" or "stuck" lanes: check the processes and the last log lines before you act. A long test is not a hang. - Known failing tests: know which failures exist on main, so a lane cannot hide a new failure behind an old one, and you do not chase an old one. - A test build is not the shipped build. New runtime features pass their gate on the release build before they land. - Read the before/after numbers. A gate that "did not pass as written" can be fine when main fails it the same way. Say so, and file a bead to make the gate stable. ## 10. Staying on top: the watchdog and efficiency reviews Run `bin/watchdog` from this skill as a background job. It loops every 60 s and exits with a report when it sees something new: - A lane worktree with no commit for 75+ min, no process in it, and no recent file change. - A change of the production page (a deploy happened), when `PROD_URL` is set. - Low RAM. - Anything the project's `checks.sh` prints (long test containers, stuck build processes, agent windows on the owner's desktop). - Anything the owner's `$ORCHESTRATE_HOME/checks.sh` prints. The watchdog runs it on its own; act on its findings as `owner.md` says. Restart it with the current lane list (`LANES="a b c"`) every time a lane starts or ends. For local lanes, omit `LANE_HOST` and set `WT_ROOT` to `~/.local/share/agent-worktrees/`. For lanes in remote mode, set `LANE_HOST=` and give `WT_ROOT` as a path on that host: the lane checks then run there in one SSH call per loop, files in the host's lane folder count as activity, and an unreachable host or low RAM on it is a finding. Run one watchdog per lane host. When it fires, check the case, act or note it, and restart it. Take a lane off the list while it runs a known long test. The header of `bin/watchdog` lists its settings. Review efficiency yourself, all the time, and fix what you find: - Lanes that end their turn to wait. Tell them to wait inside one shell call. - Lanes that run far longer than their scope needs, such as repeating gates that already passed. Tell them to land when the brief's gates pass and to file extras as beads. - Two lanes loading the same shared machine when one needs clean timing. - A lane waiting on another lane for hours: check that the blocker is real. - Duplicate work between lanes. - Engines that cost more than the work needs, or fail it: read the ledger and adjust routing (section 4). When you find a pattern that is specific to the project, add a rule to its lane rules. When it holds for every project, propose a change to this skill's brief template to the owner. ## 11. Releases - Release often. When user-facing lanes land, start a release lane pinned to a main-branch commit. The owner may waive budget gates on release; correctness gates always run (live smoke, the core flows work, version check). - The release lane follows the project's release steps: keep the previous release for rollback, verify after. - A change that alters core behaviour for everyone gets its own release, not mixed with many unrelated changes. - One release at a time per project when several sessions push to the same trunk: `bin/release-lock` (usage in its header). The release lane waits for the lock before its final trunk intake, refreshes it through push, CI, deploy and the watch, then releases it. A project can enforce it with a pre-push hook that calls `release-lock push` and refuses a trunk push from any session that does not hold the lock; the session pushes with `RELEASE_LOCK_HOLDER= RELEASE_LOCK_LANE=` on the push line. A hotfix takes the lock, pushes, waits for the deploy, releases. The lock records the holder's session process and frees the lock at once when that process is gone on the lock host. The project's lane rules say whether the lock and the hook apply. - After the release, report: live or rolled back, what the owner can now try, and what the owner should test. Keep commit IDs and rollback points in the bead, not in the report. ## 12. Reporting to the owner The owner runs many projects with many sessions each. They read "what this session is about", skim "what I did", and act on "Do you need to act?" and "What is next". Every report uses this template: ``` **What this session is about:** : . **What I did:** - **