From e4f9c2496fe69a2ed865b0a3016d3f6255174fc6 Mon Sep 17 00:00:00 2001 From: Jinwoo Hong <73622457+Jinwoo-H@users.noreply.github.com> Date: Tue, 28 Apr 2026 13:25:16 -0700 Subject: [PATCH] feat(skills): add standalone orchestration skill (#1227) Co-authored-by: Orca --- skills/orchestration/SKILL.md | 196 ++++++++++++++++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 skills/orchestration/SKILL.md diff --git a/skills/orchestration/SKILL.md b/skills/orchestration/SKILL.md new file mode 100644 index 000000000..5de160740 --- /dev/null +++ b/skills/orchestration/SKILL.md @@ -0,0 +1,196 @@ +--- +name: orchestration +description: Use the Orca CLI to coordinate multiple coding agents via inter-agent messaging, task DAGs, dispatch with preamble injection, decision gates, and coordinator loops. Use when an agent needs to send or check inter-agent messages; create, dispatch, or track orchestration tasks; coordinate multi-agent workflows; or act as a coordinator dispatching work across terminals. Triggers include "orchestrate agents", "dispatch task", "send message to agent", "check inbox", "coordinate agents", "multi-agent", "create task DAG", "worker_done", "escalation", or any task involving inter-agent coordination through Orca. +--- + +# Orca Inter-Agent Orchestration + +Use this skill when the task involves coordinating multiple coding agents through Orca's orchestration system. For basic terminal and worktree management, use the `orca-cli` skill instead. + +## When To Use + +- You need to send messages between agent terminals +- You need to decompose a spec into parallel subtasks with dependencies +- You need to dispatch tasks to worker agents with structured feedback +- You need to act as a coordinator managing a multi-agent workflow +- You need to create decision gates for human-in-the-loop checkpoints + +## Preconditions + +- Orca must be running (`orca status --json` should return `runtime: true`). +- The `orca` CLI must be on PATH (installed via Settings > Browser > Enable Orca CLI). +- The orchestration experimental feature must be enabled in Settings > Experimental. +- All `orca orchestration` commands are RPC calls to the running Orca runtime — they require an active Orca session. + +## Command Surface + +### Messaging + +Inter-agent messaging via persistent SQLite-backed mail store. Messages are delivered automatically when the recipient agent goes idle (push-on-idle). + +```bash +orca orchestration send --to --subject [--from ] [--body ] [--type ] [--priority ] [--thread-id ] [--payload ] [--json] +orca orchestration check [--terminal ] [--unread] [--types ] [--inject] [--wait] [--timeout-ms ] [--json] +orca orchestration reply --id --body [--from ] [--json] +orca orchestration inbox [--limit ] [--json] +``` + +Why: `--from` auto-resolves via the `ORCA_TERMINAL_HANDLE` environment variable injected into every Orca-managed terminal. Omit it unless impersonating another terminal. + +Why: `--inject` formats messages as readable banners with priority indicators (`[HIGH]`, `[URGENT]`) for agent prompt injection. Use `--json` for machine-readable output. + +Why: `--wait` blocks until a matching message arrives or the timeout expires (default 2 minutes). This replaces sleep+poll loops. If unread messages already exist, returns immediately. Combine with `--types` to wait for specific message types (e.g. `--wait --types worker_done --timeout-ms 120000`). + +**Message types**: `status` (general), `dispatch` (assign work), `worker_done` (signal completion), `merge_ready` (branch ready for merge), `escalation` (issue requiring attention), `handoff` (pass work to another agent), `decision_gate` (human-in-the-loop). + +**Priority levels**: `normal`, `high`, `urgent`. + +**Group addresses** resolve to terminal handles: + +| Group | Resolves To | +|-------|------------| +| `@all` | All terminal handles except sender | +| `@idle` | Handles where the agent is currently idle | +| `@claude` | Handles running Claude Code | +| `@codex` | Handles running Codex | +| `@opencode` | Handles running OpenCode | +| `@gemini` | Handles running Gemini | +| `@worktree:` | All handles in a specific worktree | + +Group messages fan out: one message per recipient, shared `thread_id`, independent read tracking. + +### Tasks + +Task tracking with DAG dependencies. A task becomes `ready` when all tasks in its `deps` array are `completed`. + +```bash +orca orchestration task-create --spec [--deps ] [--parent ] [--json] +orca orchestration task-list [--status ] [--ready] [--json] +orca orchestration task-update --id --status [--result ] [--json] +``` + +**Task statuses**: `pending` (waiting on deps), `ready` (deps met, dispatchable), `dispatched` (assigned to a terminal), `completed`, `failed`, `blocked` (waiting on a decision gate). + +Why: when a task is marked `completed`, the runtime automatically promotes any pending tasks whose deps are now all satisfied to `ready`. This is the DAG resolution step. + +### Dispatch + +Dispatch assigns a ready task to a terminal. Optionally injects the task spec + preamble into the terminal so the agent knows how to communicate back. + +```bash +orca orchestration dispatch --task --to [--from ] [--inject] [--json] +orca orchestration dispatch-show --task [--json] +``` + +Why: `--inject` sends a preamble that teaches the agent how to use `orca orchestration send --type worker_done` to report completion. All agents have `orca` on PATH and can execute shell commands. The preamble maximizes structured feedback but the system works without it (coordinator falls back to idle detection + output reading). + +Why: `--inject` requires a recognized agent CLI (e.g. Claude Code) running in the target terminal. If the terminal is a bare shell, omit `--inject` and send the prompt manually with `terminal send`. + +Why: dispatch contexts are separate from tasks (sling pattern). A task can be dispatched, fail, and be re-dispatched to a different terminal — the task stays clean while dispatch contexts track retry state. + +**Circuit breaker**: After 3 consecutive failures on a task, the dispatch context is marked `circuit_broken`. The task is marked `failed` to prevent infinite retry loops. + +### Decision Gates + +Human-in-the-loop decision points that block a task until resolved. + +```bash +orca orchestration gate-create --task --question [--options ] [--json] +orca orchestration gate-resolve --id --resolution [--json] +orca orchestration gate-list [--task ] [--status ] [--json] +``` + +Why: creating a gate blocks the task and completes its active dispatch. Resolving a gate sets the task back to `ready` with the resolution context included in the next dispatch preamble. + +**Gate statuses**: `pending`, `resolved`, `timeout`. + +### Coordinator + +Start an automated coordinator loop that dispatches ready tasks, processes `worker_done`/`escalation` messages, and advances the task DAG. + +```bash +orca orchestration run --spec [--from ] [--poll-interval-ms ] [--max-concurrent ] [--worktree ] [--json] +orca orchestration run-stop [--json] +``` + +Why: `run` returns immediately with a run ID. The coordinator loop runs in the background inside the Orca runtime. Query progress via `orca orchestration task-list`. Only one coordinator can run at a time. + +**Coordinator phases**: `decomposing` → `dispatching` → `monitoring` → `merging` → `done`. + +### Lifecycle + +```bash +orca orchestration reset [--all] [--tasks] [--messages] [--json] +``` + +Why: `--all` is the default if no flags provided. `--tasks` clears tasks, dispatch contexts, decision gates, and coordinator runs but preserves messages. + +### Terminal Commands for Coordinators + +Coordinators need these terminal commands to spawn agents, monitor progress, and read output. Full terminal documentation lives in the `orca-cli` skill — this is the subset required for orchestration workflows. + +```bash +orca terminal list [--worktree ] [--json] +orca terminal create [--worktree ] [--title ] [--command ] [--json] +orca terminal split --terminal [--direction horizontal|vertical] [--command ] [--json] +orca terminal read [--terminal ] [--json] +orca terminal send [--terminal ] --text [--enter] [--json] +orca terminal wait [--terminal ] --for [--timeout-ms ] [--json] +orca terminal show --terminal [--json] +orca terminal stop [--terminal ] [--json] +orca terminal close [--terminal ] [--json] +``` + +Why: `--terminal` is optional for most commands. When omitted, Orca auto-resolves to the active terminal in the current worktree. + +Why: `--command "claude"` launches Claude Code in the new terminal. After creating a `--command` terminal, use `terminal wait --for tui-idle` to wait for the agent to boot before dispatching. + +Why: `--for tui-idle` detects the working→idle OSC title transition for recognized agent CLIs (Claude Code, Gemini, Codex, etc.). Always pass `--timeout-ms` — real coding tasks routinely take 15-60 minutes. + +Why: `--direction horizontal` splits left/right (new pane to the right). `--direction vertical` splits top/bottom (new pane below). Default is horizontal. + +Why: terminal handles are runtime-scoped. If Orca restarts, handles go stale. Re-acquire with `terminal list`. + +Why: the 120-line terminal output buffer (`terminal read`) is for status monitoring, not result extraction. Prefer structured `worker_done` payloads over parsing terminal output. + +## Agent Guidance + +- When dispatched with a preamble, **always run the `worker_done` command when done**. This is the primary feedback mechanism — it keeps the coordinator's context window clean. +- If blocked or unable to complete a task, send an `escalation` message to the coordinator instead of silently stalling. +- Use `orca orchestration check` to read incoming messages from the coordinator or other agents. Messages are delivered automatically when you go idle, but you can also poll explicitly. +- Treat `orca orchestration` commands the same way you treat `git` or `npm` — they are CLI tools available in your shell. +- The coordinator uses `orca orchestration task-list --ready` as its external memory. Prefer querying orchestration state over tracking it in your context window. +- For multi-agent coordination, prefer the **inter-worktree** pattern (each agent in its own worktree) for parallel implementation tasks. Use **intra-worktree** (split panes, shared files) for complementary tasks where agents don't edit the same files. +- When acting as coordinator: discover existing agents with `terminal list`, create tasks with `task-create`, dispatch with `dispatch --inject`, and wait for `worker_done` messages via `check --wait --types worker_done,escalation --timeout-ms 300000`. +- When acting as coordinator: prefer `check --wait` over sleep+poll loops. `--wait` blocks until a message arrives, eliminating wasted time. Always pass `--timeout-ms` as a safety net. If the wait times out with no messages, fall back to `terminal wait --for tui-idle` and then reading terminal output. +- `check --wait` returns one message at a time. If N workers finish near-simultaneously, call `check --wait` N times in a loop to collect all results. After each return, mark the task complete (which auto-promotes dependents) and dispatch the next wave before looping back to wait. +- After receiving `worker_done` from a terminal, that terminal is guaranteed idle — skip the `terminal wait --for tui-idle` round-trip and dispatch the next task immediately. +- Terminal handles are ephemeral and runtime-scoped. If Orca restarts mid-workflow, all handles go stale. Re-acquire them with `terminal list` before continuing. +- Keep dependency chains to 3-4 steps maximum. Prefer parallel waves of independent tasks over deep sequential chains. +- Insert decision gates (`gate-create`) between phases for human oversight on risky operations. + +## Coordinator Worked Example + +Dispatch a task to a fresh Claude Code terminal and wait for completion: + +```bash +# 1. Create a terminal running Claude Code +orca terminal create --worktree active --title "worker-1" --command "claude" --json +# → handle: term_abc123 + +# 2. Wait for Claude Code to boot (tui-idle fires when the prompt appears) +orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json + +# 3. Create and dispatch a task with preamble injection +orca orchestration task-create --spec "Fix the login button CSS" --json +# → id: task_def456 +orca orchestration dispatch --task task_def456 --to term_abc123 --inject --json + +# 4. Block until the worker reports back (no sleep loops needed) +orca orchestration check --wait --types worker_done,escalation --timeout-ms 300000 --json +# → returns immediately when worker sends worker_done + +# 5. If --wait timed out with no messages, fall back to idle detection +orca terminal wait --terminal term_abc123 --for tui-idle --timeout-ms 60000 --json +orca terminal read --terminal term_abc123 --json +```