orchestration

Orca エージェント間オーケストレーション

🧭 ディスパッチバックエンド — コストの低いエージェント／モデルを選択し、複数のワーカーを並列で実行し、opencode/orchestration の構文を確認する場合は、orca-dispatch-reference を参照してください（唯一の正とする情報源です。ここで構文を重複して記載しないでください）。

オーケストレーションは、エージェント間メッセージ、タスクの担当、ディスパッチ状態、ワーカーの完了追跡を行う Orca の構造化された調整レイヤーです。

調整状態が重要な場合は、このスキルを使用してください。簡易なターミナルプロンプトや、基本的なワークツリー／ターミナル／組み込みブラウザーの操作には、orca-cli を使用してください。

使用する場面

• エージェントのターミナル間で、永続的なメッセージを送信／返信／質問する場合。
• 構造化されたタスクをワーカーにディスパッチし、worker_done または escalation を待つ場合。
• 依存関係のあるタスク DAG を追跡する場合。
• コーディネーターのループや意思決定ゲートを実行する場合。

前提条件

• orca status --json で、ランタイムが実行中であることを確認してください。
• orca が PATH に含まれている必要があります（Linux では orca-ide）。
• Settings > Experimental で、オーケストレーションの実験的機能を有効にする必要があります。
• orca orchestration コマンドは、実行中の Orca ランタイムへの RPC 呼び出しです。

所有権

オーケストレーションのメッセージとタスクは、ランタイム全体で共有されます。完了の権限は、アクティブなディスパッチコンテキスト（taskId + dispatchId + 担当者ハンドル）に基づきます。

ライフサイクルメッセージを送信する前に、引き継いだコンテキストを分類してください。

• 調整されたサブタスク：実行中のコーディネーターが DAG を所有し、このディスパッチの完了を待っています。worker_done、ハートビート／ステータス、ask、escalation を含め、前文の指示に正確に従ってください。
• 完全な引き継ぎ：元のアクターが所有権を委譲しており、監視していません。現在のセッションで完了してください。ユーザーから依頼された場合、または新たなサブタスクを意図的に分解する場合に限り、新しいコーディネーターを作成してください。ワーカーを起動する場合は、現在のワークツリーのコーディネーターハンドルと、--worktree active などのセレクターを使用してください。

判断がつかない場合は、ライフサイクルメッセージを送信する前にオーケストレーションの状態を確認してください。

orca orchestration task-list --json
orca terminal list --json
# If inherited context includes a task id:
orca orchestration dispatch-show --task <task_id> --json

メッセージング

orca orchestration send --to <handle|@group> --subject <text> [--from <handle>] [--body <text>] [--type <type>] [--priority <level>] [--thread-id <id>] [--payload <json>] [--json]
orca orchestration check [--terminal <handle>] [--unread] [--types <type,...>] [--inject] [--wait] [--timeout-ms <n>] [--json]
orca orchestration reply --id <msg_id> --body <text> [--from <handle>] [--json]
orca orchestration ask --to <handle> --question <text> [--options <csv>] [--timeout-ms <n>] [--from <handle>] [--json]
orca orchestration inbox [--limit <n>] [--json]

ルール：

• 別のターミナルになりすます場合を除き、--from は省略してください。Orca は現在のターミナルから自動的に解決します。
• ワーカーを手動で監督する場合は、スリープ／ポーリングループの代わりに check --wait --types worker_done,escalation,decision_gate --timeout-ms <n> を使用してください。decision_gate メッセージには orca orchestration reply --id <msg_id> --body <answer> --json で返信してから、待機を続けてください。
• ワーカーがコーディネーターからの回答を待つ必要がある場合は、ask を使用してください。返信を待ち、回答を直接返します。
• check --wait は一度に1件のメッセージを返します。N 個のワーカーが同時に完了する可能性がある場合は、N 回ループし、完了のたびに新たに実行可能になったタスクをディスパッチしてください。
• グループ宛先には @all、@idle、@claude、@codex、@opencode、@gemini、@droid、@worktree:<id> があります。
• メッセージの種類には status、dispatch、worker_done、merge_ready、escalation、handoff、decision_gate、heartbeat があります。

タスクとディスパッチ

タスクは作業項目、ディスパッチはタスクをターミナルに割り当てること、ゲートはコーディネーターまたはユーザーの判断が記録されるまで進行をブロックすることを指します。

orca orchestration task-create --spec <text> [--deps <json_array>] [--parent <task_id>] [--json]
orca orchestration task-list [--status <status>] [--ready] [--json]
orca orchestration task-update --id <task_id> --status <status> [--result <json>] [--json]
orca orchestration dispatch --task <task_id> --to <handle> [--from <handle>] [--inject] [--json]
orca orchestration dispatch-show --task <task_id> [--json]

タスクのステータス：pending、ready、dispatched、completed、failed、blocked。

ディスパッチのルール：

• --inject はタスク仕様と前文を、認識済みのエージェント CLI に送信し、worker_done を報告できるようにします。
• 宛先がシェルのみの場合は --inject を省略し、必要に応じて追跡用にディスパッチしてから、orca terminal send --terminal <handle> --text <prompt> --enter --json でプロンプトを手動送信してください。
• 1 つのタスクで失敗が 3 回連続すると、ディスパッチコンテキストのサーキットブレーカーが作動し、タスクは失敗としてマークされます。

ゲートとコーディネーター

orca orchestration gate-create --task <task_id> --question <text> [--options <json_array>] [--json]
orca orchestration gate-resolve --id <gate_id> --resolution <text> [--json]
orca orchestration gate-list [--task <task_id>] [--status <status>] [--json]
orca orchestration run --spec <text> [--from <handle>] [--poll-interval-ms <n>] [--max-concurrent <n>] [--worktree <selector>] [--json]
orca orchestration run-stop [--json]

run は実行 ID を返してすぐに終了します。進捗は task-list で確認してください。ワーカーからコーディネーターへの質問には ask を使用します。これにより decision_gate メッセージが作成され、コーディネーターが reply で回答します。gate-create はコーディネーターが管理するタスク DAG の判断にのみ使用し、ワーカーの ask への回答には使用しないでください。

復旧時のみ：orca orchestration reset --tasks|--messages|--all --json は、ランタイム全体のオーケストレーション状態を消去します。明示的にその状態を放棄する場合を除き、調整作業の進行中には実行しないでください。

ワーカーのターミナル

追跡対象のオーケストレーション作業では、プロンプトを指定せずにワーカーを作成し、アイドル状態になるまで待ってから --inject で指示を送信します。

orca worktree create --name <task-name> --agent codex --json
orca terminal list --worktree id:<newWorktreeId> --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <task_id> --to <handle> --inject --json

worktree create の出力から新しい worktree ID を確認し、terminal list でエージェントのターミナルハンドルを取得します。Orca 管理の worktree 内で実行している場合に限り --repo を省略できます。それ以外の場合は --repo <selector> を指定してください。--agent は新しい worktree を表示し、最初のターミナルで選択したエージェントを起動するため、別途起動用のターミナルを作成しないでください。セットアップの動作を指定する場合は --setup run|skip|inherit を使用し、独立した作業には --no-parent を使用します。

追跡対象外の軽量なプロンプトには、orca worktree create --prompt ... または orca terminal send ... のみを使用してください。これらの方法では taskId／dispatchId が紐付けられないため、プロンプトに有効なオーケストレーション用の前文が含まれていない限り、ワーカーはライフサイクルメッセージを送信しないでください。

コーディネーターが必要とすることの多い、その他のターミナルコマンド：

orca terminal list [--worktree <selector>] [--json]
orca terminal create [--worktree <selector>] [--title <text>] [--command <cmd>] [--json]
orca terminal split --terminal <handle> [--direction horizontal|vertical] [--command <cmd>] [--json]
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms <n> --json
orca terminal read --terminal <handle> --json
orca terminal send --terminal <handle> --text <text> --enter --json

古い CLI で worktree create --agent が拒否される場合は、通常どおり worktree を作成してから、orca terminal create --worktree <selector> --command "codex" --json または --command "claude" を実行してください。

指示を送る前に tui-idle を待ってください。必ず --timeout-ms を指定してください。実際のコーディングタスクには 15～60 分かかることがあります。check --wait が worker_done または escalation のないままタイムアウトした場合は、terminal wait --for tui-idle を実行してから terminal read に切り替えてください。

エージェント向けガイダンス

• 有効で進行中の前文を受け取ったワーカーは、失敗した場合も含め、必ず worker_done を 1 回だけ送信してください： orca orchestration send --to <coordinator_handle> --type worker_done --subject "<short status>" --body "<3-sentence summary: what you did, what you found, what's left>" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","filesModified":["path/a"],"reportPath":"<optional>"}' --json
• 長時間かかるタスクでは、前文で求められた場合にのみ、両方の ID を含めてハートビート／ステータスを送信してください： orca orchestration send --to <coordinator_handle> --type heartbeat --subject "alive" --payload '{"taskId":"<task_id>","dispatchId":"<dispatch_id>","phase":"implementing"}' --json
• 完了前に行き詰まった場合は ask を使用してください。所有権が有効で、コーディネーターの介入が必要な場合にのみ escalation を使用してください。
• ターミナル履歴または完全な引き継ぎを通じて継承された前文は、現在のプロンプトでそのコーディネーターが引き続き関与すると明示されていない限り、古いものとして扱ってください。
• コーディネーターは外部記憶として task-list --ready を使用し、並列の作業波を割り当て、依存関係の連鎖が 3～4 ステップを超えないようにしてください。
• 並列実装には worktree 間のワーカーを優先してください。同じファイルを編集しない補完的なタスクに限り、1 つの worktree 内で分割ペインを使用してください。

例

orca worktree create --name login-css-worker --agent claude --json
orca terminal list --worktree id:<newWorktreeId> --json
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration task-create --spec "Fix the login button CSS" --json
orca orchestration dispatch --task <task_id> --to <handle> --inject --json
orca orchestration check --wait --types worker_done,escalation,decision_gate --timeout-ms 300000 --json

次のアクション

コーディネーター：orca status --json を確認し、状態を引き継ぐ場合は task-list／dispatch-show を調べてから、手動ループ（task-create -> ワーカー -> dispatch --inject -> check --wait）または orchestration run のいずれかを選択してください。

ワーカー：現在のプロンプトに有効なディスパッチ前文が含まれている場合は、タスクを実行し、進行を妨げる質問には ask を使用して、必要なペイロードとともに worker_done を 1 回送信してください。前文が古いか存在しない場合は、ライフサイクルメッセージを送信せず、状態を確認するか、通常の引き継ぎとしてプロンプトに対応してください。