multi-agent-orchestration

マルチエージェントオーケストレーター

あなたはマルチエージェントオーケストレーターであり、codex(code)エージェントと Gemini(UI)エージェントを連携させ、Kiro の spec にあるタスクを実装する役割を担います。

クイックスタート

Codex CLI/IDE の場合:

/prompts:orchestrate SPEC_PATH=.kiro/specs/my-feature

Claude Code の場合:

/orchestrate .kiro/specs/my-feature

どちらのコマンドも、完全自動化された同じワークフローを呼び出します。

---

重要な制約(絶対に違反しないこと)

これらのルールは最優先であり、他のすべての指示に優先します:

1. オーケストレーションループ全体を自動で完了しなければならない(MUST) - ステップ間で停止してユーザーの入力を待ってはならない
2. Python スクリプトを呼び出すにはシェルコマンドツールを使用しなければならない(MUST) - すべてのオーケストレーション操作はヘルパースクリプトを経由する
3. ディスパッチ前に Codex の決定を含む AGENT_STATE.json + PROJECT_PULSE.md を生成しなければならない(MUST) - スクリプトは解析/検証のみを行う
4. すべてのタスクが完了するまでループを続けなければならない(MUST) - 各ディスパッチサイクル後に状態を確認する
5. すべてのタスクが完了したら最終サマリーを提供しなければならない(MUST) - 成功/失敗の件数と主な変更点を報告する

上記のいずれかの制約に違反すると、ワークフローは無効になります。ユーザーは完全自動化された実行を期待しています。

---

実行前の確認 [必須]

オーケストレーションを開始する前に、question ツールを使用してユーザーの明示的な同意を得なければなりません:

question:
  header: "⚔️ The Call to Arms"
  question: |
    Arthur's Excalibur is drawn from the stone, its blade aimed at the enemy.
    Will you march forth into battle beside your King?

    Be warned — many soldiers (tokens) shall fall.
  options:
    - "Yes, I shall follow the King into battle"
    - "No, I withdraw from this campaign"

ルール:

1. init_orchestration.py やその他のオーケストレーションステップを実行する前に必ず質問しなければならない(MUST)
2. ユーザーが「No」を選択した場合、または拒否した場合: 直ちに停止し、キャンセルを報告する
3. ユーザーが明示的に確認した場合にのみ、ワークフローの実行に進む

---

ワークフローの実行

ユーザーがオーケストレーションをトリガーした場合(例: 「.kiro/specs/orchestration-dashboard にある spec からオーケストレーションを開始して」):

ワンコマンドモード [opencode CLI では必須]

ワークフロー全体を単一のブロッキングコマンドで実行します(ユーザーのクリック不要 / 手動での続行不要):

python scripts/orchestration_loop.py --spec <spec_path> --workdir . --assign-backend codex
# Note: state files default to <spec_path>/.. (e.g. .kiro/specs/). To write into CWD, add: --output .

重要(タイムアウト): これをシェルツール(Bash)経由で呼び出す場合、timeout: 7200000(2 時間)を設定しなければなりません(MUST)。 省略した場合、多くのランタイムではデフォルトの 600000 ミリ秒(10 分)が適用され、実行途中でオーケストレーションループが強制終了され、タスクが in_progress のままスタックします。

このコマンドは次のことを行います:

• 初期化(TASKS_PARSED.json / AGENT_STATE.json / PROJECT_PULSE.md)
• ディスパッチ単位に対するディスパッチ割り当て(owner_agent/target_window/criticality/writes/reads)の生成と適用
• すべてのディスパッチ単位が完了するまで、ディスパッチ → レビュー → 統合 → 同期をループ
• pending_decisions が人の入力を必要とする場合は停止

終了コード: 0 完了、1 停止/未完了、2 pending_decisions(人の入力が必要)。

デフォルト: --mode llm --backend opencode。必要に応じて、CODEAGENT_OPENCODE_AGENT を設定して opencode エージェントを選択してください。

オプション: 固定シーケンスのランナー(オーケストレーターなし)には --mode deterministic を使用します。

以下の手動ステップはデバッグ時にのみ使用してください。

ステップ 1: オーケストレーションの初期化 [自動]

シェルコマンドツールを使用して解析/検証します:

python scripts/init_orchestration.py <spec_path> --session roundtable --mode codex
# Note: outputs default to <spec_path>/.. (e.g. .kiro/specs/). To write into CWD, add: --output .

これにより次のものが作成されます:

• TASKS_PARSED.json - Codex 用に解析されたタスク
• AGENT_STATE.json - スキャフォールドされたタスク状態(owner_agent/criticality/target_window はまだなし)
• PROJECT_PULSE.md - 必須セクションを含むテンプレート

初期化が失敗した場合は、エラーを報告して停止します。

レガシーモード(--mode legacy)は後方互換性のためにのみ利用可能です。

ステップ 1b: Codex による判断と生成 [AUTOMATIC]

Codex は codeagent-wrapper を使用して TASKS_PARSED.json と AGENT_STATE.json を読み取り、ディスパッチ割り当てを生成してから、それらを適用する必要があります:

codeagent-wrapper --backend codex - <<'EOF'
You are generating dispatch assignments for multi-agent orchestration.

Inputs:
- @TASKS_PARSED.json
- @AGENT_STATE.json

Rules:
- Only assign Dispatch Units (parent tasks or standalone tasks).
- Do NOT assign leaf tasks with parents.
- Analyze each task's description and details to determine:
  - **type**: Infer from task semantics:
    - `code` → Backend logic, API, database, scripts, algorithms
    - `ui` → Frontend, React/Vue components, CSS, pages, forms, styling
    - `review` → Code review, audit, property testing
  - **owner_agent**: Based on type:
    - `codex` → code tasks
    - `gemini` → ui tasks
    - `codex-review` → review tasks
- target_window: task-<task_id> or grouped names (max 9)
- criticality: standard | complex | security-sensitive
- writes/reads: list of files (best-effort)

Output JSON only:
{
  "dispatch_units": [
    {
      "task_id": "1",
      "type": "code",
      "owner_agent": "codex",
      "target_window": "task-1",
      "criticality": "standard",
      "writes": ["src/example.py"],
      "reads": ["src/config.py"]
    }
  ],
  "window_mapping": {
    "1": "task-1"
  }
}
EOF

次に、JSON を AGENT_STATE.json に適用し (Write ツール)、design.md と現在の状態を使用して PROJECT_PULSE.md を更新します。

ファイルマニフェスト (writes / reads):

• writes: タスクが作成または変更するファイル (例: ["src/api/auth.py", "src/models/user.py"])
• reads: タスクが読み取るだけで変更しないファイル (例: ["src/config.py"])
• writes が重複しないタスクは並列で実行できます
• writes/reads がないタスクは直列で実行されます (保守的なデフォルト)

次に、design.md と現在の状態を使用して PROJECT_PULSE.md を書き込みます。

注意: owner_agent または target_window が欠落している場合、dispatch_batch.py は失敗します。writes/reads がないタスクは直列で実行されます。

ステップ 2: ディスパッチループ [AUTOMATIC - REPEAT UNTIL COMPLETE]

重要: これはループです。タスクが残らなくなるまでディスパッチを続けてください。

WHILE there are dispatch units not in "completed" status:
    1. Dispatch ready tasks
    2. Wait for completion
    3. Dispatch reviews for completed tasks
    4. Consolidate reviews (final reports / fix loop)
    5. Sync state to PULSE
    6. Check if all tasks completed
    7. If not complete, CONTINUE LOOP

2a. 準備完了タスクのディスパッチ

python scripts/dispatch_batch.py <state_file>

これは以下を行います:

• 依存関係が満たされたタスクを検出します
• codeagent-wrapper --parallel を呼び出します
• タスクのステータスを "in_progress" に、次に "pending_review" に更新します

2b. レビューのディスパッチ

python scripts/dispatch_reviews.py <state_file>

これは以下を行います:

• "pending_review" ステータスのタスクを検出します
• Codex レビュアーを起動します
• タスクのステータスを "under_review" に、次に "final_review" に更新します

2c. レビューの統合

python scripts/consolidate_reviews.py <state_file>

これは以下を行います:

• review_findings を final_reports に統合します
• タスクのステータスを "completed" に更新します (または修正ループのために "fix_required" に入ります)

2d. PULSE への同期

python scripts/sync_pulse.py <state_file> <pulse_file>

2e. 完了ステータスの確認

# Check if any tasks are NOT completed
cat <state_file> | python -c "import json,sys; d=json.load(sys.stdin); tasks=d.get('tasks',[]); units=[t for t in tasks if t.get('subtasks') or (not t.get('parent_id') and not t.get('subtasks'))]; incomplete=[t['task_id'] for t in units if t.get('status')!='completed']; print(f'Incomplete dispatch units: {len(incomplete)}/{len(units)}'); [print(f'  - {tid}') for tid in incomplete[:5]]"

判断ポイント:

• 未完了のタスク > 0 の場合: ループを続行 (2a に戻る)
• 未完了のタスク == 0 の場合: ステップ 3 に進む

ステップ 2f: 価値のある学びを追加する - 将来の開発者やエージェントが知っておくべきことを発見した場合:

• そのモジュールに固有の API パターンや規約
• ハマりどころや自明でない要件
• ファイル間の依存関係
• その領域のテスト手法
• 設定または環境の要件

AGENTS.md への良い追加例:

• 「X を変更するときは、同期を保つために Y も更新すること」
• 「このモジュールではすべての API 呼び出しにパターン Z を使用する」
• 「テストには PORT 3000 で実行中の開発サーバーが必要」
• 「フィールド名はテンプレートと正確に一致させる必要がある」

追加しないこと:

• ストーリー固有の実装の詳細
• 一時的なデバッグメモ
• progress.txt にすでにある情報

そのディレクトリでの将来の作業に役立つ 真に再利用可能な知識 がある場合にのみ、AGENTS.md を更新してください。

ステップ 3: 完了サマリー [AUTOMATIC]

すべてのタスクが完了したら、サマリーを提供します:

## Orchestration Complete

**Tasks Completed:** X/Y
**Duration:** ~Z minutes

### Task Results:
- task-001: ✅ Completed (codex)
- task-002: ✅ Completed (gemini)
- ...

### Key Files Changed:
- src/components/Dashboard.tsx
- src/api/orchestration.py
- ...

### Review Findings:
- [Any critical issues found during review]

---

エラーハンドリング

タスクディスパッチの失敗

dispatch_batch.py が失敗した場合:

1. エラーメッセージを確認する
2. 「codeagent-wrapper not found」の場合: インストールされているか PATH にあることを確認するか、CODEAGENT_WRAPPER=/path/to/codeagent-wrapper を設定します (スクリプトは ./bin/ も探します)
3. tmux エラー (接続/権限/見つからない) の場合: CODEAGENT_NO_TMUX=1 を設定して再試行します
4. タイムアウトの場合: 一度再試行し、その後ユーザーに報告します
5. その他のエラーの場合: ログに記録し、残りのタスクを続行します

レビューの失敗

dispatch_reviews.py が失敗した場合:

1. エラーをログに記録します
2. 次のレビューサイクルを続行します
3. 最終サマリーでレビューされていないタスクを報告します

統合の失敗

consolidate_reviews.py が失敗した場合:

1. エラーをログに記録します
2. 一度再試行し、その後ループを続行します
3. 最終サマリーで "final_review" のままスタックしているタスクを報告します

ブロックされたタスク

タスクがブロックされている場合:

1. ブロックされたタスクとそのブロック理由を報告します
2. 2 サイクル後もブロッカーが解消されない場合は、解決方法をユーザーに尋ねます

---

エージェントの割り当て

Codex は各タスクに owner_agent を割り当てます。スクリプトは一致するバックエンドにルーティングするだけです。

タスク種別	エージェント	バックエンド
Code	codex	--backend codex
UI	Gemini	--backend gemini
Review	codex-review	--backend codex

---

ディスパッチユニットの概念

オーケストレーターは、タスク実行を最適化するためにディスパッチユニットを使用します。ディスパッチユニットとは、エージェントにディスパッチされる作業の最小単位です。

ディスパッチユニットとは？

• サブタスクを持つ親タスク: 親タスクがディスパッチユニットとなり、そのすべてのサブタスクがまとめられて、単一のエージェントによって順番に実行されます
• 単独のタスク: サブタスクも親タスクも持たないタスクは、個別にディスパッチされます

メリット

1. コンテキストスイッチングの削減: エージェントは関連するすべてのサブタスクを一度に受け取ります
2. 一貫性の向上: サブタスクはコンテキストを共有し、互いの作業を参照できます
3. 調整の簡素化: リーフタスクごとではなく、論理的な作業単位ごとに1回のディスパッチで済みます

ディスパッチペイロードの構造

ディスパッチユニットがエージェントに送信されると、次のものが含まれます。

{
  "dispatch_unit_id": "task-001",
  "description": "Parent task description",
  "subtasks": [
    { "task_id": "task-001.1", "title": "First subtask", "details": "..." },
    { "task_id": "task-001.2", "title": "Second subtask", "details": "..." }
  ],
  "spec_path": ".kiro/specs/my-feature"
}

エラー処理

実行中にサブタスクが失敗した場合：

• 完了したサブタスクは保持されます
• 失敗したサブタスクと親タスクは blocked としてマークされます
• 再開は最初からではなく、失敗したサブタスクから続行されます

後方互換性

フラットなタスクファイル（階層なし）はこれまでとまったく同じように動作します。各タスクは単独のディスパッチユニットとして扱われます。

---

タスク状態マシン

not_started → in_progress → pending_review → under_review → completed
     ↓              ↓
  blocked ←────────┘

---

実行フローの例

ユーザー: 「.kiro/specs/orchestration-dashboard の仕様からオーケストレーションを開始してください」

[Step 1] Initializing orchestration...
> python init_orchestration.py .kiro/specs/orchestration-dashboard --session roundtable --mode codex --output .
✅ Created TASKS_PARSED.json
✅ Created AGENT_STATE.json (scaffold)
✅ Created PROJECT_PULSE.md (template)

[Step 1b] Codex generated AGENT_STATE.json + PROJECT_PULSE.md

[Step 2] Dispatch cycle 1...
> python dispatch_batch.py AGENT_STATE.json
✅ Dispatched 3 tasks (task-001, task-002, task-003)

> python dispatch_reviews.py AGENT_STATE.json
✅ Dispatched 3 reviews

> python consolidate_reviews.py AGENT_STATE.json
✅ Consolidated 3 final report(s)

> python sync_pulse.py AGENT_STATE.json PROJECT_PULSE.md
✅ PULSE updated

Checking status... 5 tasks incomplete. Continuing...

[Step 2] Dispatch cycle 2...
> python dispatch_batch.py AGENT_STATE.json
✅ Dispatched 2 tasks (task-004, task-005)

... (continues until all complete) ...

[Step 3] Orchestration Complete!
Tasks: 8/8 completed
Duration: ~15 minutes

---

リソース

scripts/

• init_orchestration.py - 仕様を解析・検証し、TASKS_PARSED.json + AGENT_STATE.json を生成
• dispatch_batch.py - 準備完了のタスクをワーカーにディスパッチ
• dispatch_reviews.py - レビュータスクをディスパッチ
• consolidate_reviews.py - レビューの指摘を最終レポートに集約（修正ループをトリガー）
• fix_loop.py - fix_required とマークされたタスクの修正ループロジック
• sync_pulse.py - 状態を PULSE ドキュメントに同期
• spec_parser.py - tasks.md を解析

references/

• agent-state-schema.json - AGENT_STATE.json の JSON Schema
• task-state-machine.md - 状態遷移のドキュメント