eve-plan-implementation

Eve Plan Implementation（ジョブ）

計画ドキュメントを Eve ジョブに変換し、作業を並列化して、ジョブのフェーズと依存関係を通じてレビューと検証を進めます。

オーケストレーションモデル：ルートエピックはオーケストレーターです。計画を立て、作業を委任して調整しますが、それ自体で大規模な作業を実行することはありません。フェーズジョブは、フェーズをタスクに分割するサブオーケストレーターです。タスクジョブはワーカーです。それぞれが自己完結した説明を受け取り、親のコンテキストにはアクセスせず、独立して実行します。

使用する場面

• 計画／仕様があり、その作業を Eve ジョブとしてオーケストレーションする場合。
• 最初のジョブに「計画を実装するために eve-plan-implementation を使用する」と記載されている場合。

ワークフロー

1）コンテキストを読み込む（オーケストレーター）

• 計画ドキュメントを読み、フェーズ、成果物、ブロッカーを抽出します。
• 存在する場合は、リポジトリ固有のルールを記載した AGENTS.md を読みます。
• 現在のジョブのコンテキストを取得します：

  eve job current --json
  

• 軽量に進めます。オーケストレーターは分解の計画に必要な範囲だけを読みます。 大きなファイルの読み込みやコードの調査など、詳細な分析はワーカージョブに委任します。

2）ルートエピックを作成または確認する（オーケストレーター）

ルートジョブが存在しない場合は、作成します：

eve job create \
  --project $EVE_PROJECT_ID \
  --description "Implement <plan name>" \
  --review human \
  --phase backlog

ルートジョブがすでに存在する場合は、それをオーケストレーターとして使用します。ルートエピックは実装作業を実行しません。フェーズジョブを作成し、依存関係を設定して、待機します。

3）フェーズジョブに分割する（サブオーケストレーター）

計画の各フェーズに対して、子ジョブを1つ作成します。各フェーズジョブはサブオーケストレーターとして機能し、担当範囲をタスクジョブに分割して調整します。

eve job create \
  --project $EVE_PROJECT_ID \
  --parent $EVE_JOB_ID \
  --description "Phase: <name>. Deliverable: <artifact/result>" \
  --phase ready

親ジョブが各フェーズの完了を待つように、依存関係を追加します：

eve job dep add $EVE_JOB_ID $PHASE_JOB_ID --type waits_for

4）各フェーズの下にタスクジョブを作成する（ワーカー）

各フェーズを、成果物が明確な2～6個の細かなタスクに分割します。

フェーズ内のタスクが1つだけの場合は、子ジョブを作成せず、フェーズジョブ内で直接実行します。不要なオーケストレーションのオーバーヘッドを避けます。

複数のタスクがあるフェーズでは、子ワーカージョブを作成します。各ワーカーの説明は自己完結している必要があります。実行するエージェントは、親のコンテキスト、計画ドキュメント、以前の会話にアクセスできません。説明には以下を含めます：

• 目的と成果物
• 関連するファイルパスとモジュール名
• ワーカーが作業を成功させるために必要な制約、規約、コンテキスト

eve job create \
  --project $EVE_PROJECT_ID \
  --parent $PHASE_JOB_ID \
  --description "Task: <objective>. Deliverable: <result>. Files: <paths>. Context: <anything the worker needs>" \
  --phase ready

フェーズがタスクの完了を待つようにします：

eve job dep add $PHASE_JOB_ID $TASK_JOB_ID --type waits_for

5）デフォルトで並列化する

• 独立したタスクには依存関係を設定せず、並列で実行します。
• blocks は、真に順序付けが必要な場合にのみ使用します。

6）タスクを実行してフェーズを更新する

ワーカーはタスクジョブを受け取り、それぞれ独立して実行します。各ワーカーは次の手順を行います。

1. 自身のジョブの説明を読み、作業範囲とコンテキストを把握します。
2. 作業を行います（ファイルの読み込み、コードの作成、テストの実行）。
3. 完了を報告します。

eve job update $TASK_JOB_ID --phase active
# do the work
eve job submit $TASK_JOB_ID --summary "Completed <deliverable>"

レビューが不要な場合：

eve job close $TASK_JOB_ID --reason "Done"

7）検証とレビュー

• 実装タスクの完了後に実行される専用の検証ジョブ（テスト、手動チェック）を追加します。
• すべてのタスクが完了したら、フェーズジョブを提出します。
• すべてのフェーズが完了したら、ルートエピックをレビューに提出します。

8）オーケストレーターの待機シグナル

オーケストレーター（ルートまたはフェーズ）が子ジョブを作成し、依存関係を設定した後は、待機シグナルを返します。これにより、子ジョブが並列実行されている間、オーケストレーターのリソースを解放できます。

{
  "eve": {
    "status": "waiting",
    "summary": "Spawned child jobs and added waits_for relations"
  }
}

コンテキスト管理

オーケストレーターは軽量に保つ必要があります。

• 分解の計画に必要な範囲だけを読みます。コードベース全体を分析しないでください。
• コンテキストを子ジョブの説明に含めます。ファイルパス、規約、制約などを記載します。
• 読み込みと分析をワーカーに委任します。モジュールを理解する必要があるワーカーは、自身でそのモジュールを読みます。
• 作業の重複を避けます。複数のタスクで同じコンテキストが必要な場合は、要約するのではなく、共通の情報源を各説明に記載します。

Beads から Eve のジョブへの最小限のマッピング

• Epic -> ルートジョブ（利用可能な場合は --type で issue_type を指定します）。
• Phase -> Epic 配下の子ジョブ。
• Task -> Phase 配下の子ジョブ。
• bd dep add -> eve job dep add <parent> <child> --type waits_for
• bd ready/blocked -> eve job dep list <id> + eve job list --phase ...

オプション：Git 制御テンプレート

タスクで共有ブランチへのコード変更が必要な場合：

eve job create \
  --project $EVE_PROJECT_ID \
  --description "Task: <objective>" \
  --git-ref main \
  --git-ref-policy explicit \
  --git-branch feature/<name> \
  --git-create-branch if_missing \
  --git-commit required \
  --git-push on_success

すべての変更が 1 つの PR にまとめられるよう、タスク間で Git 制御の内容を統一してください。