---
name: droid-orchestration
description: Structured multi-agent coordination of Droid agents
disable-model-invocation: true
---

## Load the full guide before running Orca commands

```text
orca skills get orchestration
```

That prints the complete, version-matched guide for the exact binary that will handle your
next commands — task creation and dispatch, injected lifecycle preambles, worker_done
authority, decision gates, and coordinator loops. Read it first, then run the specific
command you need.

Don't guess subcommands or flags from memory or from a cached copy of this stub. They
change between Orca releases, and this file deliberately no longer lists them. Confirm the
app is up with `orca status --json` (start it with `orca open --json` if needed), and
prefer `--json` for agent-driven calls.

## Model routing (allowed workers only)

When decomposing work across droid workers, pick from this ladder only. Most
intelligent first.

| Rank | Name | Overlay `model` | Overlay `reasoningEffort` | Use for |
| --- | --- | --- | --- | --- |
| 1 | DroidProxy Opus 5 High | `custom:droidproxy:opus-5` | `high` | Hard tickets: protocol, host/main, Android lifecycle, anything that can poison dependents |
| 2 | DroidProxy Grok 4.6 Extra-high | `custom:droidproxy:grok-4.6` | `xhigh` | Next fallback. Also fine as a first pick for long-context / cross-file work |
| 3 | Muse Spark 1.2 Extra-high | `custom:meta:muse-spark-1.2` | `xhigh` | Next fallback after Grok |
| 4 | DroidProxy Gemini 3.7 Flash High | `custom:droidproxy:gemini-3.7-flash-high` | `high` | Easy tickets: CI YAML, copy, persistence, confirm sheets, polish. Default cheap model |

Slugs are `customModels[].id` from `~/.factory/settings.json`. Do not invent ids. Re-check that file if a spawn prints `Invalid model`.

**How to route.** Start each ticket on the weakest model that can still do it:
Gemini 3.7 Flash High for easy/chore/polish, Opus 5 High for hard or
foundational work. Grok and Muse are not first-line defaults; they are the
failover rungs.

**Failover.** If a worker fails to start, the overlay is rejected, the footer
shows the wrong model, or the worker `worker_done --outcome failed` because the
model could not do the job, do not retry the same model. Release that worker,
write a new overlay for the next-smarter row, spawn a fresh terminal, and
dispatch again. Order: Gemini → Muse Spark → Grok 4.6 → Opus 5 when you started
cheap; Opus → Grok → Muse Spark → Gemini when the chosen model itself will not
launch. After rank 1 is exhausted, escalate to the user.

Always pin `reasoningEffort` to the value in the table. "Opus 5 High" is
`high`, not `xhigh`. "Grok 4.6 extra-high" / "Muse Spark extra-high" is `xhigh`.
Gemini's display name already includes High; still set `reasoningEffort` to
`high`.

## Spawning a droid worker on a specific model (e.g. a DroidProxy custom model)

`ORCA orchestration worker-start --model` only supports Claude, Codex, and Cursor.
For `--agent droid` it fails with `Agent droid does not support launch-time model
selection.` Interactive `droid` also has no `-m` flag (only `droid exec` does). The
working pattern, verified 2026-08-08:

1. Use only a slug from the Model routing table above. Confirm it still exists
   under `customModels[].id` in `~/.factory/settings.json` if spawn fails.
2. Write a one-off settings overlay; `droid --settings <path>` merges it for that
   process only, so the global default model is untouched. `reasoningEffort` in the
   same block sets the reasoning level. Example: Gemini 3.7 Flash High (the cheap
   default) is `model: custom:droidproxy:gemini-3.7-flash-high` plus
   `reasoningEffort: "high"`. Allowed values: `none`, `dynamic`, `off`,
   `minimal`, `low`, `medium`, `high`, `xhigh`, `max` (which of these a given model
   honors depends on the model; DroidProxy Claude models use low/medium/high/xhigh):

   ```json
   {
     "sessionDefaultSettings": {
       "model": "custom:droidproxy:gemini-3.7-flash-high",
       "reasoningEffort": "high",
       "autonomyLevel": "high",
       "autonomyMode": "auto-high"
     },
     "commandDenylist": ["__yolo_denylist_disabled__"]
   }
   ```

   Always include that `commandDenylist` line when spawning workers. Auto (High)
   auto-approves everything except deny-listed commands (`rm -rf` variants,
   `shutdown`, `mkfs`, ...), which "always require manual approval" and stall an
   unattended worker mid-task. Replacing the list with one unmatchable dummy entry
   disables those pings; an empty `[]` is ignored and falls back to the defaults,
   so the dummy entry is required. `--skip-permissions-unsafe` is `droid exec`
   only; passing it to interactive `droid` is silently consumed as the initial
   prompt text, so an alias like `droid --skip-permissions-unsafe` does not work.
   A ready-made overlay for the no-model-override case lives at
   `~/.factory/droid-yolo.json` (aliased as `droid-yolo` in `~/.zshrc`).

3. Launch the terminal yourself (worker-start is not usable here), then dispatch:

   ```bash
   # 1. Ensure an active Run exists (if no Run is bound yet):
   orca orchestration run-create --objective "Review recent changes" --json

   # 2. Create the orchestration task:
   orca orchestration task-create --spec "<task description>" --json

   # 3. Launch terminal with overlay:
   orca terminal create --worktree current --title "opus5-worker" \
     --command "droid --settings /tmp/opus5-settings.json" --json

   # 4. Wait for TUI to be idle:
   orca terminal wait --terminal <terminal_handle> --for tui-idle --timeout-ms 60000 --json

   # 5. Dispatch task with prompt injection:
   orca orchestration dispatch --task <task_id> --to <terminal_handle> --inject --json

   # 6. If interactive droid is waiting at the prompt, trigger submission:
   orca terminal send --terminal <terminal_handle> --text "<task prompt>" --enter --json

   # 7. Supervise worker completion:
   orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
   ```

   The injected worker reports `worker_done` normally; the droid footer shows the
   custom model (e.g. "DroidProxy: Opus 5 (High)"), which confirms the overlay
   took effect.

   After every accepted `worker_done`, account for the terminal: reuse it for a
   fresh Dispatch, or release it. `worker-release` takes `--dispatch <dispatch_id>`
   (the `ctx_…` value from step 5), **not** `--terminal`. An accepted `worker_done`
   auto-settles the dispatch, so `worker-release` after completion returns
   `dispatch_not_found` — that is harmless, not an error. To close the terminal
   pane itself, use `orca terminal close --terminal <handle> --json`.

   A worker that sends `worker_done` twice will have its second message rejected
   with `dispatch_capability_invalid` ("Dispatch … capability is revoked"). That
   is expected Orca behavior, not a failure — the first `worker_done` already
   settled the dispatch.