/orchestrator

name: orchestrator
description: Use Orchestrator as a CLI-backed skill to delegate and coordinate work across Claude Code, Codex, Copilot, Grok, Pi, shell, and custom runtimes. Use when an agent should launch one or many sub-agents, choose runtimes or models, apply the user's orchestration preferences, inspect background work, collect results, resume sessions, or stop stale work.

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:

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:

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:

{
  "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."
    }
  ]
}

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:

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

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 wo