oma-orchestrator

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

スケジューリング

目標

タスクの分解、ネイティブ／フォールバックのディスパッチ、メモリの調整、進捗の監視、検証、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. タスクごとに、名前が domain_tags に含まれるスキルを exposed_skill_set として構成します。分類後の |exposed_skill_set| < 2 の場合は、インストール済みの全スキルセットにフォールバックして（フラットに公開）、タスクボードに exposure_fallback: true を記録します。
5. タスクごとの exposed_skill_set と exposure_fallback を含めて、セッションメモリとタスクボードを作成します。

シーン

1. PREPARE：計画を立て、セッション ID を設定し、メモリファイルを初期化します。
2. ACT：並列実行数の上限内で、優先度階層ごとにエージェントを起動します。
3. VERIFY：セルフチェック、oma verify、QA の相互レビューループを実行します。
4. RECOVER：上限に達していなければ、レビュー履歴を引き継いで失敗したエージェントを再試行します。
5. FINALIZE：結果ファイルを収集し、サマリーを作成して、進捗ファイルをクリーンアップします。

遷移

• 現在のランタイム／ベンダーでネイティブディスパッチを利用できる場合は、それを使用します。
• ベンダーが異なる場合、またはネイティブ経路を利用できない場合は、フォールバックで起動します。
• 検証または QA が失敗した場合は、フィードバックを実装エージェントに戻します。
• レビューループの上限を超えた場合は、レビュー履歴と品質に関する警告を報告します。
• 復旧した失敗から、タスクの exposed_skill_set に必要なスキルが含まれていなかったと判明した場合は、タスクを再分類し、元の狭いスキルセットで再試行するのではなく、拡張したセットで再ディスパッチします。

失敗と復旧

• 設定された上限まで、失敗したエージェントを再試行します。
• レビューループの上限に達した場合は、レビュー履歴を引き継いで再起動します。
• 確認事項の未解決度がしきい値を超えた場合は、一時停止するか、仕様の再提示を求めます。

終了

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

論理演算

アクション

アクション	SSL プリミティブ	エビデンス
設定とタスクのコンテキストを読み取る	READ	oma の設定、ルーティング、リクエスト
タスクをドメインタグに分類する	INFER	タスクのテキストと各スキルの Intent signature を照合
公開するスキルセットを計算する	SELECT	ドメインタグとインストール済みスキルの共通部分
ディスパッチ経路を選択する	SELECT	ネイティブまたはフォールバック
セッション状態を書き込む	WRITE	タスクボードとメモリファイル
エージェントを起動する	CALL_TOOL	ネイティブ CLI または oma agent:spawn
進捗を確認する	READ	進捗／結果ファイル
検証を実行する	CALL_TOOL	oma verify、テスト、QA
再試行状態を更新する	UPDATE_STATE	ループカウンターと CD メトリクス
最終結果を報告する	NOTIFY	まとめたサマリー

ツールと手段

• ネイティブ CLI のサブエージェントディスパッチ、フォールバック起動スクリプト、メモリツール、検証スクリプト、QA エージェント
• セッションメトリクス、プロンプトテンプレート、タスクテンプレート

標準コマンド経路

oma agent:spawn <agent-type> "<task>" <session-id> -w <workspace>
oma verify <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. 実行中は、セッション状態、タスクボードの状態、進捗ファイル、結果ファイルの整合性を保ってください。
6. ドメインによる絞り込みはソフトに行います。より絞り込んだ exposed_skill_set を優先しますが、分類の信頼度が低い場合は、必要な専門エージェントがタスクから除外されないよう、フラットな公開にフォールバックしてください。

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

• Claude Code：claude --agent <agent>
• Codex CLI：.codex/agents/*.toml を使用する codex exec "@agent ..."
• Gemini CLI：.gemini/agents/*.md を使用する gemini -p "@agent ..."

フォールバック CLI の実行では、ベンダー固有の実行プロトコルが自動的に挿入されます。

設定

設定	デフォルト	説明
MAX_PARALLEL	3	同時実行できるサブエージェントの最大数
MAX_RETRIES	2	失敗したタスクの再試行回数
POLL_INTERVAL	30s	ステータス確認の間隔
MAX_TURNS (impl)	20	バックエンド／フロントエンド／モバイルのターン上限
MAX_TURNS (review)	15	QA／デバッグのターン上限
MAX_TURNS (plan)	10	PM のターン上限

メモリ設定

メモリプロバイダーとツール名は mcp.json で設定できます：

{
  "memoryConfig": {
    "provider": "serena",
    "basePath": ".serena/memories",
    "tools": {
      "read": "read_memory",
      "write": "write_memory",
      "edit": "edit_memory"
    }
  }
}

ワークフローのフェーズ

フェーズ 1 - 計画：リクエストを分析 -> タスクを分解 -> セッション ID を生成
フェーズ 1.5 - ドメインゲート：各タスクについて、インストール済みスキル間で Intent signature の一致を交差させ、exposed_skill_set を導出します。交差が有用な結果を得るには小さすぎて、代わりにフラットライブラリを使用する場合は、exposure_fallback: true を記録します。
フェーズ 2 - セットアップ：メモリ書き込みツールを使用して orchestrator-session.md と task-board.md を作成します（各タスクに exposed_skill_set を含めます）。
フェーズ 3 - 実行：優先度の階層に従ってエージェントを起動します（MAX_PARALLEL を超えてはなりません）。各サブエージェントが利用できる専門家リストには、exposed_skill_set のみを挿入します。
フェーズ 4 - 監視：POLL_INTERVAL ごとにポーリングし、完了／失敗／クラッシュしたエージェントに対処します。
フェーズ 4.5 - 検証：完了したエージェントごとに oma verify {agent-type} を実行します。
フェーズ 5 - 収集：すべての result-{agent}-{sessionId}.md を読み込み、概要をまとめ、進捗ファイルをクリーンアップします。

プロンプトの作成については resources/subagent-prompt-template.md を参照してください。
メモリファイルの形式については resources/memory-schema.md を参照してください。

メモリファイルの所有権

ファイル	所有者	その他
orchestrator-session.md	オーケストレーター	読み取り専用
task-board.md	オーケストレーター	読み取り専用
progress-{agent}[-{sessionId}].md	該当エージェント	オーケストレーターが読み込み
result-{agent}[-{sessionId}].md	該当エージェント	オーケストレーターが読み込み

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

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

ループの流れ

Agent completes work
    ↓
[1] Mechanical Self-Check: lint, type-check, tests, diff scope
    ↓
[2] Verify: Run `oma verify {agent-type} --workspace {workspace}`
    ↓ 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-type} --workspace {workspace} --json

• 合格（終了コード 0）：クロスレビューに進みます。
• 不合格（終了コード 1）：検証結果を修正コンテキストとしてエージェントに渡します。

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

• QA エージェントは差分を読み込み、チェックを実行し、受け入れ基準に照らして評価します。
• docs/CODE-REVIEW.md が存在する場合、QA エージェントはそれをレビュー用チェックリストとして使用します。
• QA エージェントは、合格（任意で軽微な指摘を含む）または不合格（具体的な問題点を含む）を出力します。
• 不合格の場合、問題点を実装エージェントに渡して修正します。

ループの上限

カウンター	最大	超過時の対応
セルフチェックと修正のサイクル	3	いずれの場合もクロスレビューに進みます
クロスレビューでの却下	2	レビュー履歴とともにユーザーに報告します
ループの合計反復回数	5	品質に関する警告を付けて強制的に完了します

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

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

## 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}

これは単発の検証に代わるものです。細かな指摘の多くは、エージェント間で行う必要があります。
人によるレビューは最終承認のために行い、リンターエラーの発見には使用しません。

再試行ロジック（レビューループの上限到達後）

• 1 回目の再試行：レビュー履歴全体をコンテキストとして、エージェントを再起動します。
• 2 回目の再試行：「別のアプローチを試してください」とレビュー履歴を添えて、エージェントを再起動します。
• 最終的に失敗した場合：完全なレビュー履歴とともにユーザーに報告し、続行するか中止するかを尋ねます。

明確化の負債（CD）の監視

セッション実行中のユーザーによる訂正を追跡します。プロトコルの全容については ../_shared/core/session-metrics.md を参照してください。

イベントの分類

セッション中にユーザーからフィードバックが届いた場合：

• 明確化（+10）：ユーザーがエージェントの質問に回答する
• 訂正（+25）：ユーザーがエージェントの誤解を正す
• やり直し（+40）：ユーザーが作業を却下し、最初からやり直すよう求める

しきい値アクション

CD Score	アクション
CD >= 50	RCA 必須：QA エージェントは lessons-learned.md にエントリーを追加する必要があります
CD >= 80	セッションの一時停止：ユーザーに要件の再指定を依頼します
redo >= 2	スコープのロック：続行する前に、明示的な許可リストの確認を依頼します

記録

ユーザーによる修正イベントのたびに：

[EDIT]("session-metrics.md", append event to Events table)

セッション終了時に CD >= 50 の場合：

1. 最終レポートに CD の概要を含める
2. QA エージェントによる RCA の生成を実行する
3. lessons-learned.md を予防策で更新する

参考資料

• プロンプトテンプレート：resources/subagent-prompt-template.md
• メモリスキーマ：resources/memory-schema.md
• 設定：config/cli-config.yaml
• スクリプト：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 コントラクト：../_shared/core/api-contracts/
• コンテキストの読み込み：../_shared/core/context-loading.md
• 難易度ガイド：../_shared/core/difficulty-guide.md
• 推論テンプレート：../_shared/core/reasoning-templates.md
• 明確化プロトコル：../_shared/core/clarification-protocol.md
• コンテキスト予算：../_shared/core/context-budget.md
• 学習事項：../_shared/core/lessons-learned.md