oma-orchestration

オーケストレーション - マルチエージェントの自動調整

スケジューリング

目標

タスクの分解、ネイティブ／フォールバックのディスパッチ、メモリの調整、進捗の監視、検証、QA による相互レビュー、再試行、結果の収集を行い、マルチエージェントの実行を自動でオーケストレーションします。

インテントシグネチャ

• オーケストレーション、並列実行、マルチエージェント実行の自動化、またはフルスタック作業のエンドツーエンドでの調整をユーザーが求めている。
• 複数の専門エージェントと、継続的なレビュー／修正ループを必要とするタスクである。

使用する場面

• 複雑な機能に、複数の専門エージェントによる並列作業が必要な場合
• エージェントを手動で起動せずに自動実行したい場合
• バックエンド、フロントエンド、モバイル、QA にまたがるフルスタックの実装
• ユーザーが「自動で実行して」「並列で実行して」など、自動化を求めている場合

使用しない場面

• 単純で単一領域のタスク → 該当するエージェントを直接使用します
• ユーザーが段階ごとの手動制御を希望している場合 → oma-coordination を使用します
• 迅速なバグ修正や小規模な変更

想定される入力

• 複雑な機能またはワークフローの依頼
• プロジェクト設定、モデル／ベンダーのルーティング、エージェントの種類、タスクの制約、ワークスペース／セッションの要件
• 受け入れ基準と検証に関する要件

想定される出力

• オーケストレーターのセッション状態、タスクボード、進捗ファイル、結果ファイル、最終概要
• 機械的なチェック、自動検証、QA による相互レビューを経た専門エージェントの出力
• ループが失敗した場合のレビュー履歴と再試行／修正の状況

依存関係

• .agents/oma-config.yaml、.codex/agents/*.toml、.gemini/agents/*.md、またはフォールバックの oma agent spawn
• メモリプロバイダーの設定、サブエージェントのプロンプトテンプレート、スクリプト、タスクテンプレート、検証スクリプト、セッション指標

制御フローの機能

• ベンダー／ネイティブディスパッチの利用可否、優先度ティア、エージェントの完了／失敗、検証ステータス、QA 判定、再試行の上限、未解決の判断事項に応じて分岐します
• プロセス／エージェントを起動し、メモリ／結果ファイルを読み書きします
• 制限付きの復旧処理が停止した際、未解決の根拠情報を保持します

構造的なフロー

開始

1. エージェントのベンダールーティングと実行時のディスパッチ経路を解決します。
2. 依頼を優先度ティア別のタスクに分解します。
3. 各タスクについて、インストール済みの各 .agents/skills/oma-*/SKILL.md の Intent signature ブロックとの照合に基づいて、1 つ以上の domain_tags に分類します。どのドメインにも確信を持って分類できないタスクには、親機能のタグの和集合を継承させます。
4. 各タスクに必要なリファレンスを選択します。1 つのスキルに確信を持って分類できる場合はそれで十分です。分類が不確かな場合や、依存関係によって別のドメインが必要な場合は、選択範囲を広げます。
5. 選択したドメイン、リファレンス、フォールバックを選択した理由があれば、それをタスクボードに記録します。これらはコーディネーターのメモであり、ランチャーが強制する公開フィールドではありません。有効なディスパッチ経路でサポートされているリファレンス／コンテキスト制御のみを使用します。
6. ディスパッチ前に共通のコラボレーションポリシーを適用します。編集の担当者、相互連絡の経路、結果の取りまとめ担当者を割り当てます。

フェーズ

1. PREPARE：計画を立て、セッション ID を設定し、メモリファイルを初期化します。
2. ACT：並列実行の上限内で、優先度ティアごとにエージェントを起動します。
3. VERIFY：セルフチェック、oma verify、QA による相互レビューのループを実行します。
4. RECOVER：上限内であれば、レビュー履歴を添えて失敗したエージェントを再試行します。
5. FINALIZE：検証済みの報告を収集し、概要をまとめ、進捗の成果物を保持します。

遷移

• 現在のランタイム／ベンダーでネイティブディスパッチが利用できる場合は、それを使用します。
• ベンダーが異なる場合、またはネイティブ経路を利用できない場合は、フォールバックの spawn を使用します。
• 検証または QA に失敗した場合は、フィードバックを実装エージェントに返します。
• 復旧の上限を超えた場合は、レビュー履歴を保持して partial または failed を返します。完了を強制してはいけません。
• 復旧時に、必要なドメインリファレンスが不足していたことが判明した場合は、凍結された受け入れ条件を変更せずにタスクのリファレンス選択を更新し、サポートされているコンテキストの仕組みを通じてそれを提供します。

失敗と復旧

• 失敗したエージェントを、設定された上限まで再試行します。
• レビューループが上限に達した場合は、レビュー履歴を引き継いで再起動します。
• 重大な修正を記録した後は、独立した作業を続行します。重大な判断が不足している場合に限り、確認を求めます。

終了

• 成功：すべてのタスクが完了し、検証とレビューに合格して、結果が要約されています。
• 部分的な成功：エージェントの失敗、上限に達したレビューループ、または未実施の検証が明示されています。

論理的な操作

アクション

アクション	SSL プリミティブ	根拠
設定とタスクのコンテキストを読み取る	READ	oma の設定、ルーティング、リクエスト
タスクをドメインタグに分類する	INFER	タスクのテキストと各スキルのIntent signatureの比較
タスクの参照情報を選択する	SELECT	確度の高いドメイン一致、依存関係、サポートされているコンテキスト制御
ディスパッチ経路を選択する	SELECT	ネイティブまたはフォールバック
セッションの状態を書き込む	WRITE	タスクボードとメモリーファイル
エージェントを起動する	CALL_TOOL	公開されているネイティブのロールサブエージェントツール、またはoma agent spawn
進行状況を確認する	READ	進行状況／結果ファイル
検証を実行する	CALL_TOOL	oma verify、テスト、QA
再試行の状態を更新する	UPDATE_STATE	ループカウンターとCDメトリクス
最終結果を報告する	NOTIFY	まとめた要約

ツールと手段

• 公開されているネイティブのロールサブエージェントツール、フォールバック用の起動スクリプト、メモリーツール、検証スクリプト、QAエージェント
• セッションメトリクス、プロンプトテンプレート、タスクテンプレート

標準のコマンド経路

oma agent spawn <agent-type> <prompt-file> <session-id> --task-id <task.id> -w <workspace>
oma verify agent <agent-type> --workspace <workspace> --json

ネイティブのランタイムディスパッチが利用可能な場合は、oma agent spawnにフォールバックする前に、このスキルに記載されているランタイム固有のネイティブ経路を優先してください。

リソースの範囲

範囲	リソースの対象
LOCAL_FS	セッション、タスクボード、進行状況、結果、設定ファイル
PROCESS	エージェントのCLIプロセスと検証スクリプト
MEMORY	セッションの状態と未解決の判断事項
CODEBASE	起動したエージェントが所有するワークスペース

前提条件

• タスクを専門エージェントの作業に分割できること。
• ランタイム／ベンダーのディスパッチ経路、またはフォールバックが利用可能であること。

効果と副作用

• エージェントを起動し、セッション／進行状況／結果の成果物を書き込みます。
• 専門エージェントを通じてコードが変更される場合があります。
• 反復レビューと再試行が発生する場合があります。

ガードレール

1. エージェントを起動する前に、プロジェクト設定に従ってエージェントごとのディスパッチを調整してください。
2. target_vendor === current_runtime_vendorであり、ランタイムに検証済みのネイティブ経路がある場合は、ネイティブディスパッチを使用してください。
3. それ以外の場合は、oma agent spawnにフォールバックしてください。
4. 設定された並列度や復旧の合計予算を超えないでください。通常の再試行と探索仮説は、どちらも予算を消費します。
5. セッションの状態、タスクボードの状態、進行状況ファイル、申し立て、受領記録の整合性を保ってください。すべての起動経路およびネイティブの開始／終了経路で、計画タスクIDを使用してください。
6. タスクの必要性と確度に基づいて参照情報を選択してください。1つのスキルが一致しただけで、すべてのスキルに範囲を広げないでください。また、タスクボードのメタデータによってランタイムへの公開が保証されると想定しないでください。

現在のネイティブ実行経路：

• Claude Code：.claude/agents/{agent}.mdの定義を使用するAgentツール（1つのメッセージで複数のAgentツール呼び出しを行うと並列実行されます。結果は同期的に返されるため、ポーリングは不要です）
• OpenCode：subagent_type: {agent-id}を指定したネイティブのtaskツール。同じセッションのOpenCode作業では、ネイティブの子タスクとして表示されないため、oma agent spawnを使用しないでください。
• Codex：サポートされている場合は、.codex/agents/*.tomlから解決したカスタムロールを使い、現在のセッションで公開されているネイティブのサブエージェントツールを使用します。それ以外の場合は、oma agent spawnを使用してください。
• Gemini：サポートされている場合は、解決したロールを使い、現在のセッションで公開されているネイティブのロールサブエージェントツールを使用します。それ以外の場合は、oma agent spawnを使用してください。

codex execとgemini -pは、外部のCLIセッションを開始します。プロンプト内の@agentという文字列では、ネイティブディスパッチは確立されず、カスタムロールの規約も適用されません。

Configuration

設定	デフォルト	説明
MAX_PARALLEL	3	同時に実行できるサブエージェントの最大数
MAX_RECOVERY_ATTEMPTS	3	元の試行を含む、タスクごとの再試行と探索仮説の合計数
POLL_INTERVAL	bounded backoff	完了通知を利用できない場合にのみ使用するフォールバック
ターンガイダンス	role-specific	チェックポイント／再開のシグナルであり、強制終了や承認の境界ではありません

これらはワークフローのデフォルト設定です。モデル／ベンダー、並列実行、予算の設定はプロジェクト構成から解決してください。config/cli-config.yaml はベンダーのトランスポートレジストリを提供しますが、アクティブなベンダーを選択したり、実行時の設定を上書きしたりするものではありません。

メモリの設定

メモリプロバイダーとツール名は .agents/mcp.json で設定できます（リポジトリルートの .mcp.json は Claude Code MCP サーバーの設定であり、対象外です）：

{
  "memoryConfig": {
    "provider": "file",
    "basePath": ".agents/state/memories",
    "tools": {
      "read": "Read",
      "write": "Write",
      "edit": "Edit"
    }
  }
}

ワークフローのフェーズ

PHASE 1 - 計画：現在有効な計画を再利用するか、リクエストを分解します。注入されたセッション／タスク／実行 ID は保持してください。 PHASE 1.5 - リファレンス：Entry の説明に従ってタスクのリファレンスを選択します。実行時に強制されると想定せず、不確実性と範囲を広げる理由を記録してください。 PHASE 2 - セットアップ：現在の ID と選択したリファレンスを使って、セッション／タスクボードの成果物を作成します。 PHASE 3 - 実行：対応しているネイティブまたはフォールバックのコンテキスト制御を使い、MAX_PARALLEL の範囲内で準備の整ったタスクをディスパッチします。 PHASE 4 - 監視：完了通知を優先します。利用できない場合は、調整役を 1 つに絞り、上限付きのポーリングバックオフを使います。共通の期限、キャンセル、リソース所有権、シャットダウンのルールについては ../_shared/core/execution-policy.md に従ってください。キャンセルまたは期限切れになった場合は、検証の前にディスパッチと復旧を停止します。 PHASE 4.5 - 検証：完了した各エージェントに対して機械的なチェックを実行します。oma verify agent {agent-type} は backend、frontend、mobile、qa、debug、pm に対してのみ実行し、その後、完了した実装すべてに対して QA のクロスレビューを実行します。 PHASE 5 - 収集：チェックに合格した計画タスクについて、申告内容と実行単位のレポートを読み、証拠を削除せずに概要をまとめます。

メモリファイルの所有権

ファイル	所有者	その他
orchestrator-session-{sessionId}.md	オーケストレーター	読み取り専用
task-board-{sessionId}.md	オーケストレーター	読み取り専用
progress-{agentId}-{taskId}-{runId}-{sessionId}.md	その実行	オーケストレーターが読み取る
result-{agentId}-{taskId}-{runId}-{sessionId}.md	その実行	オーケストレーターが読み取る

エージェント間レビューのループ（PHASE 4.5）

各エージェントの完了後、1 回限りの検証ではなく、反復的なレビューループに入ります。

ループの流れ

Agent completes work
    ↓
[1] Mechanical Self-Check: lint, type-check, tests, diff scope
    ↓
[2] Verify: For supported types, run `oma verify agent {agent-type} --workspace {workspace}`
    Unsupported (`db`, `refactor`, `architecture`, `tf-infra`, `docs`) → record SKIP and continue
    ↓ FAIL → Agent receives feedback, fixes, back to [1]
    ↓ PASS
[3] Cross-Review: QA agent reviews the changes
    ↓ FAIL → Agent receives review feedback, fixes, back to [1]
    ↓ PASS
Accept result

ステップの詳細

[1] 機械的なセルフチェック（旧称「セルフレビュー」）： 外部レビューを依頼する前に、実装エージェントは次を実施する必要があります。

• ワークスペースでリンター、型チェック、テストを実行する
• 予定されていたファイルのみが変更されたことを確認する（差分範囲のチェック）
• 機械的な問題（コンパイルエラー、テスト失敗）を修正する

このステップでは品質の判断を行いません。 設計品質、アーキテクチャとの整合性、受け入れ基準の達成度は、QA エージェントが [3] クロスレビューでのみ評価します。 理由：自己評価バイアスにより、エージェントは自身の成果を一貫して過大評価するためです （参考：Anthropic のハーネス設計に関する研究）。

[2] 自動検証：

oma verify agent {agent-type} --workspace {workspace} --json

• backend、frontend、mobile、qa、debug、pm に対してのみ実行します。
• db、refactor、architecture、tf-infra、docs では、自動検証がサポートされていないことを記録し、機械的なチェックの後に QA クロスレビューへ進みます。
• PASS（終了コード 0）：クロスレビューへ進みます
• FAIL（終了コード 1）：検証結果を修正の参考情報としてエージェントに渡します

[3] クロスレビュー：QA エージェントを起動して変更をレビューします。

• QA エージェントは差分を読み、チェックを実行し、受け入れ基準に照らして評価します

• docs/CODE-REVIEW.md が存在する場合、QA エージェントはそれをレビューのチェックリストとして使用します

• QA エージェントの出力：PASS（任意の軽微な指摘を含む）または FAIL（具体的な問題を含む）

• FAIL の場合：問題点を実装エージェントに渡して修正します

ループの上限

カウンター	最大回数	上限超過時の対応
セルフチェックと修正のサイクル	3	いずれの場合もクロスレビューに進む
クロスレビューでの却下	2	レビュー履歴とともにユーザーに報告する
ループの合計反復回数	5	復旧を停止し、失敗したチェックを保持して partial または failed を返す

レビューフィードバックの形式

レビュー結果を実装エージェントに渡す場合：

## Review Feedback (iteration {n}/{max})
**Reviewer**: {self / verify / qa-agent}
**Verdict**: FAIL
**Issues**:
1. {specific issue with file and line reference}
2. {specific issue}
**Fix instruction**: {what to change}

これにより、単一パスの検証を置き換えます。「細かすぎる指摘」の大半はエージェント間で解決する必要があります。引き継ぎ前に、関連する自動チェックを解決してください。次のアクションが既存の承認範囲外である場合にのみ、承認を求めてください。

復旧予算（レビューループ終了後）

ワークフローの系統および論理的な目標ごとに、attempts_used、attempts_remaining、設定されているコスト上限を管理します。最初の試行、通常の再試行、各探索仮説は、それぞれ試行回数を 1 回消費します。復旧を開始する前に、次のアクション全体に必要な予算を確保してください。予算を超過したり、不完全な探索ラウンドを開始したりしないでください。

../_shared/runtime/result-contract.md にある計画の固定された lineage_id とタスクの goal_id を使用します。新しいタスク、実行、セッションの ID によって予算をリセットしないでください。最初のディスパッチ時に完全な JSON 計画を固定し、再帰的な計画／レビュータスクと、ディスパッチ後の計画改訂を拒否します。契約を変更するには、明確に分離された新しいセッションと系統が必要です。

再試行する前に、失敗を分類します。PRODUCT_FAILURE は残りの製品復旧予算に従います。WORKFLOW_EVIDENCE_FAILURE は、現在の製品チェックは通過したものの、完了の主張またはバインディングに失敗した状態を意味します。証拠のみを再実行する自動再開は停止します。既存のタスクと固定済みの計画のもとで、メタデータのみの修復を最大 1 回まで許可し、同じ予算を消費します。解決できない場合は、部分的な引き継ぎで停止します。証拠の失敗に対して、PM タスクを作成したり、製品計画を再実行したり、別のワークフローの計画レビューのループを取り込んだりしないでください。

• 最初に残っている試行：レビュー履歴を添えて再起動します。
• それ以降の試行：試行回数とコストに余裕がある場合に限り、異なる再試行を 1 回行うか、2～3 個の仮説を検証するラウンドを実施します。
• 上限に達した場合は、すべてのチェック、レビューの指摘、未解決の作業を保持します。 タスクの状態は completed ではなく、partial または failed とします。

セッションの根拠

重要な修正やレビューでの指摘については、原因、影響、根拠を既存のタスク成果物に記録してください。振り返りや個別のセッション要約が役立つ場合は、../_shared/core/session-metrics.md を使用してください。カウンターを根拠に、確認の質問を採点したり、RCA を必須にしたりしないでください。該当する作業を解決し、重要な判断が不足している場合に限って確認してください。

参考資料

• 並行ワーカーとの連携：../_shared/core/collaboration-policy.md（並行作業を割り当てる前、またはピア間の課題、担当の引き継ぎ、結果の収集を調整する前に確認してください）
• プロンプトテンプレート：resources/subagent-prompt-template.md
• メモリースキーマ：resources/memory-schema.md
• スクリプト：scripts/spawn-agent.sh、scripts/parallel-run.sh、scripts/verify.sh
• タスクテンプレート：templates/
• スキルとエージェントの対応表：../_shared/core/skill-routing.md
• 検証：scripts/verify.sh <agent-type>
• セッションメトリクス：../_shared/core/session-metrics.md
• API コントラクトテンプレート（SSOT）：../_shared/core/api-contracts/template.md。生成されたコントラクトは、.agents/results/api-contracts/（実行時の成果物）または docs/plans/contracts/（永続的な仕様）から読み取ってください。
• コンテキストの読み込み：../_shared/core/context-loading.md
• タスクの分解：../_shared/core/difficulty-guide.md（スコープや依存関係が未解決の場合）
• 確認プロトコル：../_shared/core/clarification-protocol.md
• コンテキスト予算：../_shared/core/context-budget.md
• コードインテリジェンス：../_shared/core/code-intelligence.md
• 実行時の教訓：../_shared/core/lessons-learned.md（繰り返し発生する失敗、または振り返りを求められた場合）