eve-orchestration

Eve Orchestration

このスキルでは、子ジョブを作成し、依存関係を管理し、深度の上限を守りながら並列実行を最大化することで、Eve Horizon における複雑な作業をオーケストレーションする方法を説明します。

基本原則

1. 親は目標深度を設定し、子に引き継ぎます。
2. 各ジョブは、スコープと深度に応じて独自に作業を分解します。
3. タスクが独立して進められる場合は、原則として並列化します。
4. 関係は、希望ではなく実際の依存関係を表すために使用します。
5. リーフジョブは実行し、親ジョブはオーケストレーションして完了を待ちます。
6. オーケストレーターの役割は軽量に保ちます。作業を割り当て、抱え込まないでください。

オーケストレーションするか、直接実行するか

すべてのジョブを分解する必要はありません。次の目安を使ってください。

• 直接実行するのは、作業が単一のエージェントのコンテキストと能力に無理なく収まる、独立した小規模なものである場合です。例：単一のバグを修正する、文書のセクションを1つ書く、診断チェックを実行する。
• オーケストレーションするのは、並列化が有効な独立したサブパートがある場合、スコープが単一のエージェントが一度にコンテキスト内で扱うべき範囲を超える場合、またはパートごとに異なるスキルやツールへのアクセスが必要な場合です。
• 原則として直接実行します。 オーケストレーションには、ジョブの作成、待機、再開などのオーバーヘッドがあります。並列化やスコープの都合で本当に必要な場合にのみ分解してください。

必ずコンテキストを最初に確認する

何かを決める前に、現在のジョブコンテキストを取得してください。

eve job current --json
# or explicit
eve job current $EVE_JOB_ID --json

コンテキストを使って、次の項目を確認してください。

• job.depth（現在の深度）
• children（既存のサブジョブ）
• relations（依存関係）
• blocked / waiting / effective_phase

環境と ID

識別子を推測せずに済むよう、環境を利用してください。

• EVE_JOB_ID：現在のジョブ
• EVE_PROJECT_ID：ジョブを所有するプロジェクト
• EVE_ATTEMPT_ID：現在の試行
• EVE_REPO_PATH：ワークスペースのパス
• EVE_AGENT_ID：エージェント識別子（任意）

深度の引き継ぎ

親は目標深度を決定し、子に引き継ぎます（子の説明またはデータで指定します）。 各子は同じ目標深度を読み取り、それに従う必要があります。

子の説明に含めるサンプルスニペット：

Target depth: 3 (EPIC). Current depth: 1.
If current depth < target, you may create child jobs and use waits_for relations to parallelize.
If current depth >= target, execute directly.

深度のデフォルトルール

• EPIC：目標深度 = 3

  • ルートは子をオーケストレーションします
  • 子は孫をオーケストレーションできます
  • 孫は実行します

• Story：目標深度 = 2

  • ルートは子をオーケストレーションします
  • 子は実行します

目標深度が指定されていない場合、スコープから明らかに EPIC と判断できる場合を除き、Story の深度（2）をデフォルトとします。

コンテキスト管理

オーケストレーターにとって最も貴重なリソースはコンテキストウィンドウです。大切に使いましょう。

• オーケストレーターで大きなファイルやデータセットを読まないでください。 分析が必要な場合は、読み取りと結果の要約を行う子ジョブを作成してください。
• オーケストレーターの役割は、計画、作業の割り当て、結果の統合に限定してください。 オーケストレーターは、何をすべきか、どう分割するかを決め、その実作業を委任します。
• 子の出力をインラインで蓄積しないでください。 子の完了後に再開する際は、完了確認に必要な要約や結果だけを読み、子の成果物をすべて読み込まないでください。
• 作業を分解するための検討を先に行ってください。 子がやり直すことになる部分的な作業ではなく、コンテキストを分解計画に使ってください。

適切に運用されたオーケストレーターは、コンテキストの予算を大半残したまま作業を終えられるはずです。

ジョブごとのオーケストレーションの流れ

1. コンテキストを取得します（eve job current --json）。
2. 深度を決定します。
   • 引き継がれた目標深度を確認します。
   • current_depth >= target_depth の場合は、直接実行します。
3. 分解するかどうかを決定します。
   • 作業の規模が大きい、または並列化できる場合は、子ジョブを作成します。
   • 各子には同じ目標深度を引き継ぎます。
4. 自己完結した子の説明を記述します（以下のテンプレートを参照）。
5. 関係を追加します。
   • 標準的なゲートには waits_for を使います。
   • 厳密な順序制約がある場合にのみ blocks を使います。
6. 関係を設定した後、待機シグナルを返します。
7. 子の完了後に再開し、要約を読み、確認してから続行します。

子ジョブの作成

eve job create に --parent を指定して子ジョブを作成します。各子ジョブの説明は 完全に自己完結している必要があります。子エージェントは親の会話、コンテキスト、推論にアクセスできません。作業に必要な情報はすべて説明に記載してください。

# Create two child jobs in parallel
eve job create --project $EVE_PROJECT_ID \
  --parent $EVE_JOB_ID \
  --description $'Target depth: 3 (EPIC). Current depth: 1.\nScope: Research sources\nDeliverable: Annotated bibliography' \
  --phase ready

eve job create --project $EVE_PROJECT_ID \
  --parent $EVE_JOB_ID \
  --description $'Target depth: 3 (EPIC). Current depth: 1.\nScope: Draft outline\nDeliverable: Structured outline' \
  --phase ready

子ジョブを作成したら、親が子ジョブの完了を待つように依存関係を追加します。

eve job dep add $EVE_JOB_ID $CHILD_A_ID --type waits_for
eve job dep add $EVE_JOB_ID $CHILD_B_ID --type waits_for

並列分解のガイダンス

• 大きな子ジョブを1つ作成するより、複数の小さな独立した子ジョブを優先してください。
• タスクを並列で実行できる場合は、子ジョブを作成し、親がすべてを待つようにします。
• ある子ジョブの出力が次の子ジョブに実際に必要な場合を除き、子ジョブを連鎖させないでください。
• 各子ジョブは同じ判断プロセスを繰り返し、深さが許す場合は孫ジョブを作成できます。
• 適切な分解では、各子ジョブの範囲を、コンテキストウィンドウを使い切らずに1つのエージェントが完了できる程度に絞ります。

依存関係と関連付け

CLI の依存関係コマンドを使って関連付けを表現します。

eve job dep add $PARENT_JOB_ID $CHILD_JOB_ID --type waits_for
eve job dep add $CHILD_JOB_ID $OTHER_JOB_ID --type blocks
eve job dep list $JOB_ID

関連付けのガイダンス：

• waits_for：親が子ジョブの完了を待つ標準的な設定
• blocks：厳密な順序制約
• conditional_blocks：依存関係が条件付きの場合にのみ使用します

待機中の制御シグナルを返す前に、関連付けを追加してください。

制御シグナル（json-result）

子ジョブを作成して関連付けを設定したら、待機シグナルを使って親を一時停止します。

{
  "eve": {
    "status": "waiting",
    "summary": "Spawned 3 parallel child jobs; waiting on waits_for relations"
  }
}

ルール：

• 依存関係が存在する場合にのみ waiting を返します。
• waiting を返すと、ジョブは ready に再登録され、関連付けによってブロックされた状態が続きます。
• ブロッカーなしで waiting を返すと、短いバックオフが発生するため避けてください。
• 作業が完了したら success を使用します。
• failed は回復不能な結果の場合にのみ使用します。

レビューの仕組み（任意）

デフォルトでは、親またはプロジェクトの設定で明示的に求められない限り、レビューは行いません。

レビューが必要な場合：

• 指定されたレベル（最上位のみ、すべての階層、またはなし）で適用します。
• waiting を返すときにレビューを申請しないでください。
• ジョブが完了した場合にのみレビューを申請してください。

eve job submit $EVE_JOB_ID --summary "Completed work and ready for review"

子ジョブの作業に対する親のレビュー

子ジョブの完了後に親が再開したら：

• 子ジョブの作業成果物全体ではなく、要約と結果を読みます。コンテキストを保護してください。
• 子ジョブの出力全体で親の作業範囲を満たしていることを確認します。
• レビューが必要な場合は、確認後に親のレビューを申請します。
• レビューが不要な場合は、子ジョブの結果をまとめて親の要約を作成し、完了します。

失敗への対応

子ジョブが失敗した場合：

• コンテキストを再確認し、再試行、置き換え、または中止のいずれかを判断します。
• 計画が変わった場合は、関連付けを削除または調整します。
• 親が恒久的に失敗した子ジョブを待ち続ける状態にしないでください。

子ジョブの説明テンプレート

各子ジョブの説明は自己完結している必要があります。子エージェントは何も知らない状態で開始し、親の会話、読み込んだファイル、推論にはアクセスできません。必要な情報をすべて含めてください。

Target depth: 3 (EPIC). Current depth: 1.
If current depth < target, you may create child jobs and use waits_for relations to parallelize.
If current depth >= target, execute directly.

Context: <why this work exists — enough background for the child to act without asking>
Scope: <concise child objective — what to do>
Inputs: <specific file paths, data references, or prior outputs the child needs>
Deliverable: <clear, verifiable outcome — what "done" looks like>
Constraints: <boundaries, standards, or requirements to honor>

子ジョブの説明に関する主なルール：

• 具体的なファイル名とパスを記載します。「認証モジュールを更新する」では曖昧です。「トークン更新ロジックを追加するために /src/auth/handler.ts を更新する」なら実行可能です。
• **すでに決定した関連事項を含めます。**親が方針を選択した場合は、子にその決定を伝え、もう一度判断させないでください。
• 成果物を検証可能な条件として示します。「テストが通る」や「ファイルがパス X に存在する」は、「機能 Y を実装する」より明確です。
• **子が親の意図を理解できると決めつけないでください。**迷った場合は、詳細に記載してください。

ナレッジワークの例（ソフトウェア開発以外）

• 調査：並列での文献レビュー、データ収集、統合
• 執筆：アウトライン作成、セクションの並列執筆、統合
• 運用：並列チェック（メトリクス、ログ、ステータス）、その後に要約
• 戦略：並列での SWOT 分析、ステークホルダー分析、リスク評価

クイックチェックリスト

• コンテキストと深度を確認する
• 対象となる深度とレベルを決定する
• 直接実行するか、オーケストレーションするかを判断する（作業が単一で完結する場合は、直接実行をデフォルトとします）
• オーケストレーションする場合：分割計画を立ててから、自己完結した説明を添えて子タスクを作成する
• 逐次的な連鎖より、並列の子タスクを優先する
• シグナルを送る前に関係を追加する
• json-result を待機する（子タスクが存在する場合）
• 再開時：子タスクの概要（完全な出力ではなく）を読み、検証して完了する