opencode-ensemble

OpenCode Ensemble

OpenCode Ensemble は、判断を避けるための近道ではなく、調整システムとして使用してください。並列エージェントが最も効果を発揮するのは、リードが作業の分解、順序付け、レビュー、マージ、検証を担う場合です。

このリポジトリには、タグ v0.14.2（b6bc7f706c13aa42d32e836ea647677d0b14c2f7）の上流 hueyexe/opencode-ensemble スキルがベンダーとして含まれており、この OpenCode のセットアップに合わせてモデルに関するガイダンスを調整しています。チームメイトは、デフォルトでリポジトリが管理する OpenCode エージェントのバリエーションを継承する必要があります。明確なモデルの上書きが必要なタスクに限り、team_spawn.model を明示的に渡してください。

基本原則

独立していて、検証可能な作業に限りチームメイトを起動してください。優れた Ensemble チームは、担当範囲が狭く、依存関係が明確で、リードが意図を持って結果を統合します。

振り分け表

ユーザーのリクエストに応じて $ARGUMENTS を振り分けます。

$ARGUMENTS パターン	モード	アクション
parallel、team、ensemble、delegate、teammate	チーム計画	Ensemble が適切か判断し、有用であればリードが所有するチームを 1 つ作成します。
waves、parallel teams、subagents、fan out	ウェーブ計画	ロールグループ、タスクの依存関係、リードが所有するゲートを備えた 1 つのチームとして作業をモデル化します。
review teammate output、merge team、finish team	統合	結果を確認し、チームメイトを終了し、team_merge でマージして、差分を調べ、検証します。
models、model pool、which model	モデルガイダンス	明確な team_spawn.model の上書きが妥当でない限り、リポジトリのデフォルトを継承します。
空または曖昧	適合性の確認	Ensemble が役立つ場面を説明し、範囲が小さい場合はスカウトを 1 人使うか、インラインで作業することを優先します。

正規の用語

用語	意味
リード	team_create を呼び出し、作業の分解、起動、マージ、検証を担うセッションです。
チームメイト	team_spawn で作成された、リードが起動する OpenCode セッションです。
ウェーブ	依存関係が完了した後に実行できる、段階的なタスクグループです。
ロールグループ	api-*、ui-*、qa-*、review-* など、1 つのチーム内の関連するチームメイトの集まりです。
ゲート	次のウェーブを開始する前に設ける、リードが所有するチェックポイントです。
チームメイトのサブエージェント	チームメイトが作成する子セッションです。team_* ツールは使用できません。

並列ウェーブ

役割グループと段階的なウェーブを使い、リードが所有する1つの Ensemble チームとして並列チームをモデル化します。team_tasks_add.depends_on でウェーブの DAG を定義し、team_spawn.claim_task でチームメイトを実際のタスク ID に割り当てます。また、ウェーブの間にはリードが所有するゲートを設け、統合、マージ、検証を行います。

サポートされる構成：

1. ウェーブ 0 では、スカウトが agent: "explore" と worktree: false を使って境界とリスクを調査します。
2. リードがスカウトの結果を要約し、その後に独立したビルダーだけを起動します。
3. ビルダーは分離されたワークツリーで、重複しない範囲を並列に作業します。
4. リードが結果を確認してチームメイトを終了し、マージして差分を検査してから、QA やレビュアーの作業を開始できるようにします。
5. QA とレビュアーは、実装ブランチを統合した後に作業します。

1つのリードセッションが所有できるアクティブな Ensemble チームは1つだけです。本当に別々のチームが必要な場合は、リードセッションを分けてください。それ以外の場合は、同じチーム内に役割グループを設け、タスクの内容でウェーブを明確に示します。

チームメイトが作成したサブエージェントに、team_* ツールを使った連携を依頼しないでください。Ensemble では、チームメイトの子孫によるチームツールの使用が意図的にブロックされるため、チーム連携に参加する必要があるチームメイトは、すべてリードが起動する必要があります。

Ensemble を使う場合

• 作業を独立した調査、実装、テスト、レビューの範囲に分割できる場合。
• 編集を始める前に、読み取り専用のスカウトが不慣れなコードを調査できる場合。
• 所有範囲が重複しない複数のファイルやサブシステムを変更できる場合。
• リスクの高い変更で、編集前に plan_approval: true による承認が有益な場合。
• 別のブランチを作成せずに、最終レビュアーがマージ済みの変更を確認できる場合。
• 後続の各ウェーブが、先行するウェーブで完了したタスク ID に依存する段階的なウェーブとして作業を表現できる場合。

Ensemble を使わない場合

• 1人のエージェントがすぐに完了できるほど小さなタスクの場合。
• 作業の結び付きが強く、チームメイト全員が同じファイルを必要とする場合。
• リードが各チームメイトの成果物と成功基準を説明できない場合。
• 並列調査ではなく、ユーザーが一貫した1つの設計上の決定を必要としている場合。
• 作業が難しく感じられるという理由だけで、分割できないのにエージェントを起動しようとしている場合。
• 1つのリードセッションで複数のアクティブなチームを同時に実行する必要がある場合。
• チームメイトのサブエージェントに、連携のための team_* ツールを使わせる必要がある場合。

リードのワークフロー

1. 並列化が妥当かどうかを判断します。
2. team_create でチームを作成します。
3. team_tasks_add でタスクを追加し、順序付けには depends_on を使います。
4. team_spawn でチームメイトを1人ずつ起動します。起動後、チームメイトは非同期に並列で実行されます。
5. 読み取り専用の explore チームメイトには worktree: false を使います。
6. リスクの高い実装作業には plan_approval: true を使います。
7. 依存するウェーブを開始する前に、リードによる統合ゲートを設けます。
8. ステータスを繰り返しポーリングするのではなく、チームメイトからのメッセージを待ちます。
9. メッセージが省略されている場合や結果が重要な場合は、team_results で結果全体を確認します。
10. 完了したチームメイトを team_shutdown で終了します。
11. team_merge でブランチをマージし、その結果を信頼する前に差分を確認します。
12. 完了を宣言する前に、team_cleanup を実行する前に、プロジェクトの検証を実行します。

ロールのデフォルト設定

ロール	エージェント	ワークツリー	モデルのガイダンス	用途
Scout	explore	false	リポジトリの高優先度デフォルトを継承	コードベースの把握、リスクの発見、ファイルの担当計画
Builder	build	true	リポジトリの高優先度デフォルトを継承	範囲を限定した実装
QA	build	true	リポジトリの高優先度デフォルトを継承	テスト、フィクスチャ、リグレッションのカバレッジ
Reviewer	explore	false	リポジトリの高優先度デフォルトを継承	差分レビュー、リスクレビュー、テスト漏れの確認

まず、チームメイトを2〜3人で開始します。このマシンでは、システムリソースと API クォータが許す場合、実質的な独立作業には5〜8人が妥当な上限です。作業にアクティブなチームメイトより多くの独立した作業範囲がある場合にのみ人数を増やし、最初から大人数を投入するより、追加の作業を段階的に進めてください。

参照ファイル一覧

ファイル	読み込むタイミング
references/coordination-patterns.md	チーム構成、作業の波の構成、ロールグループ、またはリードの個別セッションを選ぶとき。
references/prompt-recipes.md	Scout、Builder、QA、Reviewer、または作業の波ごとのチームメイト用プロンプトを作成するとき。
references/lead-checklists.md	起動前、作業の波、マージ、クリーンアップ、検証の各ゲートを実施するとき。
references/anti-patterns.md	計画の並列化が過剰でないか、裏付けがないか、やり取りが多すぎないか確認するとき。
references/eval-scenarios.md	このスキルの動作チェックを作成または改善するとき。

重要なルール

1. 生成されたタスク ID を記録します。team_tasks_add は ID を生成します。depends_on または claim_task を設定するときは、以前の呼び出しで返された ID を使います。
2. チームメイトへのプロンプトは簡潔にします。プラグインによって、チームのロール、許可されたツール、ワークツリーのコンテキスト、必須のタスク結果形式がすでに挿入されます。
3. 曖昧な委任は避けます。「バグを修正する」や「テストに取り組む」といったプロンプトでは、作業が重複し、検証できなくなります。
4. リード専用ツールはリードが使用します。チームメイトに team_spawn、team_shutdown、team_merge、team_cleanup、team_view を使うよう依頼しないでください。
5. チームメイトのサブエージェントをチームの調整から切り離します。意図的に team_* へのアクセスを許可していません。
6. 依存する作業の波にはゲートを設けます。必要なタスク ID が完了し、リードによる統合が済むまで、依存する作業の波を開始しないでください。
7. team_message による結果報告を必須にします。チームメイトにプレーンテキストのみで報告するよう指示しないでください。
8. マージ前にレビューします。結果を読み、差分を確認せずにチームメイトのブランチをマージしないでください。
9. 完了を宣言する前に検証します。リポジトリの検証コマンドを実行するか、妨げとなっている問題を明確に報告してください。

検証の要件

Ensemble ワークフローが成功したと宣言する前に、以下を確認してください。

• 作業を分割できた理由をリードが説明できること。
• 起動した各チームメイトに、明確な担当領域と該当する場合は割り当てられたタスク ID があること。
• 依存する作業の波が、実際の depends_on ID を使用していること。
• 読み取り専用のロールが agent: "explore" および worktree: false を使用していること。
• 結果が省略されている場合や重要な判断に関わる場合、チームメイトの結果を team_results で読んでいること。
• マージしたブランチをプロジェクトの差分で確認していること。
• リポジトリ固有の検証コマンドが成功しているか、妨げとなっている問題が報告されていること。

このスキルを変更する場合は、編集の完了を宣言する前に python scripts/check.py と uv run pytest tests/test_distribution_metadata.py tests/test_sync_agent_stack.py -q を実行します。

最小限の例

team_create({ name: "checkout-idempotency" });

team_tasks_add({
  tasks: [
    { content: "Map checkout webhook flow and risky files", priority: "high" },
    {
      content: "Implement duplicate-webhook idempotency guard",
      priority: "high",
    },
  ],
});
// Record returned IDs, for example: task_abc123 for scout and task_def456 for builder.

team_tasks_add({
  tasks: [
    {
      content: "Add duplicate-webhook regression tests",
      priority: "high",
      depends_on: ["task_def456"],
    },
  ],
});
// Record returned QA task ID, for example: task_ghi789.

team_tasks_add({
  tasks: [
    {
      content: "Review merged diff for correctness and missed tests",
      priority: "medium",
      depends_on: ["task_def456", "task_ghi789"],
    },
  ],
});

team_spawn({
  name: "scout",
  agent: "explore",
  worktree: false,
  claim_task: "task_abc123",
  prompt:
    "Trace the checkout webhook flow. Report files, data model, existing tests, risks, and a smallest-safe-change plan. Do not edit files.",
});

team_spawn({
  name: "api-dev",
  agent: "build",
  plan_approval: true,
  claim_task: "task_def456",
  prompt:
    "Use scout's findings to implement only the idempotency guard. Commit your work and send a task-result message with files changed and tests run.",
});