orchestrator

# Orchestrator Use Orchestrator to let the current agent coordinate other agents. The skill is the interface; the `orchestrator` CLI is the deterministic control plane underneath it. ## Start 1. Read `PREFERENCES.md` beside this file. Apply only non-comment content under `User Preferences`. `No preferences set.` means use judgment. 2. Follow an explicit instruction in the current user request before a stored preference. 3. Check the CLI with `orchestrator --help`. If missing and npm is available, install it with `npm install -g @backnotprop/orchestrator-cli`. 4. Run `orchestrator help --json --compact` for the current command contract. 5. Run `orchestrator doctor --json --compact` when runtime availability is uncertain. Choose only from `runtimeSummary.availableIds`. 6. Run `orchestrator models <runtime> --json --compact` before choosing an exact model value. Do not assume a runtime or model exists because it appears in an example. ## Preferences Preferences are routing policy for the calling agent. They may describe: - which runtime or model to use for a type of work; - which fallbacks to use and in what order; - when to fan out or keep work with one agent; - what to do when provider usage is exhausted. Use this precedence: 1. explicit instructions in the current request; 2. `PREFERENCES.md`; 3. live runtime and provider facts; 4. your best judgment. Map preference names to configured runtime and model values when unambiguous. If the mapping is consequential and unclear, ask the user once. Preferences do not grant permission for unrelated work and do not override task safety. When preferences depend on usage, run `orchestrator limits --json --compact`. Treat unavailable limit data as unknown, not exhausted. Follow configured fallbacks only when the preferred choice is unavailable, exhausted, or fails clearly. If the policy says to pause when all choices are exhausted, launch nothing and notify the user. ## Choose Models Omit `--model` when the user has no model requirement. The installed runtime then chooses its current default. Before passing an exact model value, run: ```sh orchestrator models <runtime> --json --compact ``` - Match user requests and preference labels against `models[].id` or `models[].displayName`; pass the matched `id` to `--model`. - Resolve "latest" or "best" through a returned `defaultModel`, `alias`, or `router`. Do not sort version-like names or guess from memory. - Treat `partial` as useful but incomplete discovery. Claude Code, for example, exposes current family aliases instead of an exact catalog. - If discovery is unavailable, omit `--model` unless the request requires an exact choice. - Do not silently replace an unavailable exact model unless the current request or preferences define a fallback. - Run the returned `fullModels.args` when descriptions or capabilities matter. Model values remain provider-native and are passed through unchanged. ## Delegate One Job Use a named task and keep its returned id: ```sh orchestrator launch codex --name "inspect store" --json --compact --brief "Inspect the task store." orchestrator read <task-id|prefix> --wait --json --compact ``` Use `shell` for exact local commands. Use an AI runtime for review, implementation, research, exploration, or analysis. ## Fan Out Launch separate tasks for independent work. Use a manifest when several tasks should start together: ```json { "schemaVersion": 1, "tasks": [ { "runtime": "claude-code", "name": "review tests", "task": "Find the highest-risk missing tests." }, { "runtime": "grok", "name": "inspect api", "task": "Inspect the API boundary for bugs." } ] } ``` ```sh orchestrator launch -f agents.json --json --compact --brief orchestrator ps --json --compact --active --brief orchestrator read <task-id> <task-id> --wait --json --compact ``` Do not collapse several task ids into one quoted string. ## Let Orchestrator Coordinate Use the parent agent when the user wants Orchestrator itself to plan and manage delegation: ```sh orchestrator run --background --name "repo work" --json --compact "Delegate independent work, wait for every child, then synthesize the result." ``` If compact doctor returns `parent.canRun: true`, append the request to `parent.run.argsPrefix` or `parent.run.backgroundArgsPrefix`. ## Operate The Work ```sh orchestrator ps --json --compact --active --brief orchestrator ps -A --json --compact --active --brief orchestrator watch <task-id> --agent-only --json orchestrator read <task-id>... --wait --json --compact orchestrator logs <task-id> --follow orchestrator events <task-id> --agent-only --json --compact orchestrator resume <task-id> --json --compact "Continue from the prior result." orchestrator interrupt <task-id> --json --compact --reason "no longer needed" ``` - Prefer portable `commands.*.args` and `stop.args` returned in JSON. - Treat returned argument arrays as argv arrays. - Use `read --wait` instead of repeated polling when the next step needs the result. - Use `watch` for normalized live events and `logs` for raw provider output. - Resume only finished tasks with stored provider metadata and runtime resume support. - Stop stale, duplicated, or no-longer-needed work. - Report task id, runtime, model, and status when handing work back. ## Runtime Notes Built-in launch targets include `claude-code`, `codex`, `codex-app-server`, `copilot`, `grok`, `pi`, and `shell`. Config may disable built-ins or add custom runtime ids. Use `codex` for one-shot Codex work. Prefer `codex-app-server --session` when Codex work needs repeated messages, native goals, steering, or a persistent provider thread: ```sh orchestrator launch codex-app-server --session --name "deep worker" --json --compact --brief orchestrator send <task-id> --wait --json --compact "Inspect the current bottlenecks." orchestrator goal start <task-id> --wait --json --compact "Improve the system." ``` Do not set a goal token budget unless the user wants a hard cap. ## Cleanup Scope Prefer exact task ids. Use workspace-wide cleanup only when intentional: ```sh orchestrator interrupt --active --json --compact --reason "cleanup" ``` Use all-workspace cleanup only when the user explicitly requests it: ```sh orchestrator interrupt -A --active --yes --json --compact --reason "cleanup" ```