multi-agent-handoff

マルチエージェントの引き継ぎ

複数のエージェントがコンテキストを失わずに順番に作業を実行できるよう、作業を構成します。

使用する場面

• 大規模なタスクを調査担当、実装担当、レビュー担当のエージェントに分割する場合
• フォアマン／ワーカー、または親／サブエージェントのパターンを使う場合
• チャットセッションやツール間で、文書による引き継ぎが必要な場合

引き継ぎドキュメントのテンプレート

HANDOFF.md（またはタスクの Issue 内のセクション）を作成または更新して、次を記載します。

## Goal
{one sentence outcome}

## Done
- {completed items}

## Next
1. {ordered steps for the receiving agent}

## Constraints
- {tech stack, style, files not to touch}

## Verification
- {commands or checks that must pass}

## Validation status
- {commands run}
- {commands skipped or blocked, with reason}
- {blocked JSON explained with `steward blocked explain --input <path> --json`, when available}
- {schema/output drift checked with `steward schema check-outputs --json`, when machine-readable output is part of the handoff}
- {claims not proven because validation was skipped or blocked}

## Partial results
- {missing, partial, superseded, or timed-out agents/lenses}

## Context links
- {paths, PRs, prior decisions}

## Artifact capture
- {ADR, FAQ, skill, evidence note, test, validator, generator, or check that should absorb durable learning}

並列バッチの契約

幅広く分解可能な作業では、親エージェントは新しい計画形式の代わりに、一時的なバッチセクションを使用できます。安全に進めるために必要な契約だけを残します。

• 当初の目標とユーザーによる受け入れ確認事項。
• デフォルトのネイティブゲートと集約ゲート。
• 主な成果物へのプロダクト影響の確認。特にリポジトリがアプリ、ライブラリ、CLI／ツール、プラグイン、またはプロトタイプである場合。
• 迂回できる範囲と停止条件。
• 統合能力、マージ順序、競合時のポリシー。
• レーンの出力を比較する方法。
• 最終的な証拠の範囲、主張の上限、主張しない事項。
• 3 つのフィールドを含む高速化メモ：Saved、Cost/duplication、Future hot path。
• 検証または比較作業を繰り返す場合の、ホットパスへの昇格確認。

並列レーンを割り当てる前に、この簡潔な形式を使用します。

## Parallel Batch
Original goal: {user-visible outcome}
Acceptance check: {how the parent will know the original goal is satisfied}
Product impact check: {source-owned product behavior/API/UI/perf/doc-user workflow that must change or be proven unchanged}
Default native gate: {repo-native command or reason none exists}
Aggregate gate: {final validation before claiming completion}
Detour budget: {when to stop repairing tools and return to the goal}
Claim ceiling: {strongest claim allowed if all lanes pass}
Non-claims: {adjacent claims this batch cannot prove}
Acceleration note:
- Product impact line: {recognized prefix plus proof; use support_only: Steward scaffolding only when no product surface moved}
- Saved: {time, uncertainty, or risk reduced by running lanes in parallel}
- Cost/duplication: {duplicated work, integration cost, or coordination drag caused or avoided}
- Future hot path: {command, check, skill, script, deletion, or native route created for the next run}

| Lane | Agent/role | Scope | Write set | Forbidden paths | Native gate | Direct fix? | Terminal state |
|------|------------|-------|-----------|-----------------|-------------|-------------|----------------|
| L1 | {owner} | {bounded work} | `{paths}` | `{paths}` | `{command}` | yes/no | pending |

統合後は、レビュー成果物として残す場合を除き、このバッチセクションを削除するか、簡潔にまとめます。レーンマップをプロジェクト管理の状態として残さないでください。

親レーンの契約

親が割り当てたレーン契約だけが、書き込み権限の範囲を定めます。助言目的のエコロジールート dispatch_lane_candidates、MoE の調査結果、A2A のメモ、レビュー担当者のコメントは、いずれも入力にすぎません。

各レーンには次を記載します。

• lane_id、割り当てられたエージェント／役割、範囲、厳密な write_set、および forbidden_paths。
• 継承するリポジトリのルール、必須の影響確認、権限確認、ネイティブゲート、集約ゲートの責任。
• direct_fix_allowed: true|false、主張の上限、主張しない事項、エスカレーションの条件。
• 終端状態：integrated_to_owner、rejected、blocked_to_current_ledger、promoted_to_durable_owner、deleted、reported_to_parent、accepted_as_input、partial、timed_out、または superseded。

direct_fix_allowed: true を設定できるのは親レーン契約だけです。直接修正は、厳密な書き込み範囲、明示された禁止パス、継承する安全ルール、必須の影響確認と権限確認、利用可能な検証を伴う、範囲の限定された低リスクの作業でなければなりません。検証を省略または実行できない場合、結果は blocked または recommendation に格下げされ、integrated_to_owner とはなりません。

A2A 成果物は、書き込みを許可したり、範囲を拡大したり、レーンを承認／却下したり、スチュワードの判断を取り繕ったりするものではありません。承認、統合、最終的な主張、範囲変更の責任は、親エージェントまたは明示的な A2Human チェックポイントが担います。

反映フェーズ

レーンが一時クローン、フォーク、ワークツリー、または外部チェックアウトで修正を実証しても、オーナーのチェックアウトに最小限のソース管理対象の差分を適用し、ネイティブゲートを再実行するまでは、その証明は accepted_as_input です。デフォルトでは、一時環境での証明をリポジトリが所有する証拠として扱わないでください。

レーンが統合されたと主張する前に、次を行います。

1. 一時環境またはワーカーの結果から、最小限のソース管理対象の差分を切り分けます。
2. その差分だけをオーナーのチェックアウトに適用します。
3. オーナーのチェックアウトで、レーンのネイティブゲートを再実行します。
4. 主張が変わった場合に限り、現在の台帳または証拠メモを更新します。
5. source_owner_status を temp_only、owner_landed_pending_gate、owner_gate_passed、または blocked_owner_dirty に設定します。
6. 終端状態を integrated_to_owner、blocked_to_current_ledger、accepted_as_input、または rejected に設定します。

ソースのチェックアウトに未コミットの変更がある場合、または差分を安全に適用できない場合は、一時環境での証明を候補として記録し、より強いソース管理対象の主張は未証明のままにします。範囲を限定した反映を 1 回試みた後、同じ未反映の結果について別の証明パケットを作るのではなく、レーンをブロックまたは却下として終了します。

ワークフロー

1. 分解 — 可能な場合は、目標を独立した単位に分けます。
2. 役割の割り当て — 例：調査（読み取り専用）、実装（書き込み）、レビュー（読み取り専用の批評）。
3. 引き継ぎメモの作成 — テンプレートを埋め、「Next」は具体的な手順を7つ以内にします。並行作業では、割り当て前に簡潔なバッチ表を記載します。
4. 1つの単位を実行 — 引き継ぎを受けたエージェントは「Next」の内容だけを実行し、「Done」を更新します。
5. 証拠を記録 — 完了を宣言する前に、検証状況を更新します。チェックの省略や、ブロックされたジェネレーターは証拠にならず、黙って成功扱いにもできません。
6. ソース所有の変更を取り込む — 一時的な証拠や作業担当者の証拠をオーナーのチェックアウトに反映し、主張の確度を高める前に、ネイティブのゲートを再実行します。
7. すべてのレーンを終了する — タイムアウト、ブロック、後続作業による置き換えを含め、各レーンまたは視点に終端状態を割り当てます。
8. 高速化を測定する — 高速化メモに、何が削減できたか、どのような重複作業や調整コストが発生したか、今後使えるコマンド、チェック、ホットパスが何かを記入します。削減できたものがなければ、その旨を記し、主張の上限を低く保ちます。
9. プロダクトへの影響を確認する — プロダクトのリポジトリでは、ソース所有のプロダクト差分、または到達したプロダクト固有のゲートを明記します。バッチで改善したのが Steward の足場、証拠アーティファクト、またはツールを扱うツールだけの場合は、プロダクトの高速化ではなく、方向づけやハーネスの保守のみを主張します。 プロダクトへの影響を示すプレフィックスを1つ使用します：runtime_behavior:、public_api:、product_native_gate:、visual_capture:、performance_metric:、release_path:、developer_workflow:、command_output:、plugin_install:、またはsupport_only:。 Cost/duplicationが、削減できた不確実性、リスク、または反復作業を下回らない場合は、デフォルトでleave_native、rejected、または確信度の低いサポート関連の主張を選びます。
10. 長期的に活用できる知見を記録する — 今後の作業に影響する発見は、ADR、FAQ、スキル、証拠ノート、バリデーター、ジェネレーター、テスト、またはチェックに反映します。
11. 再度引き継ぐ — 更新したHANDOFF.mdを次のエージェントまたはサブエージェントに渡します。
12. 終了する — 目標が検証できたら、引き継ぎファイルを削除するか、アーカイブします。

アンチパターン

• ファイルパスや受け入れ基準を示さず、「Xの作業を続ける」と曖昧に指示すること
• 1画面を超える引き継ぎ（references/または課題に分割します）
• 親エージェントと子エージェント間で、重複して矛盾する指示を出すこと
• 矛盾、古くなった前提、証拠の不足、より小さく削除可能な設計を探さず、親の計画を繰り返すサブエージェント
• 検証が省略、ブロック、または手作業による推測にとどまっているのに、完了したかのように見える最終引き継ぎ
• ランディングしてオーナーのチェックアウトでネイティブのゲートを再実行する前に、一時的な検証結果をソース所有の採用成果として提示すること
• 長時間実行された、または応答がなくなったサブエージェントを、partial、timed_out、blocked、supersededのいずれかの終端状態を付けずに、親の統合に黙って含めること
• 削減できた不確実性、重複作業、作成された今後のコマンド、チェック、ホットパスを示さずに、並行作業によって高速化したと主張すること
• Steward のゲートはすべて成功したものの、プロダクト差分、プロダクト固有のゲート、スクリーンショットやパフォーマンスの証拠、API の動作変更、ユーザー向けワークフローの改善がないバッチで、プロダクトを高速化したと主張すること

サブエージェントのヒント（Codex / Cursor / Zed）

• 調査やレビューには読み取り専用のエージェントを使用してください
• 引き継ぎブロックはサブエージェントのプロンプトにそのまま渡してください
• 呼び出されたときにのみ実行する必要があるスキルには、disable-model-invocation: true を優先してください
• 並行作業では、エージェントの担当範囲が重複しないようにし、実装前に書き込みの担当範囲を明確にしてください。
• 有用なレビュアーの役割には、Repo Truth Verifier、Boundary Leak Reviewer、Evidence Ladder Reviewer、Doc Collapse Reviewer、Harness QA Reviewer、Stale External Assumption Reviewer があります。
• Codex のカスタムエージェントは .codex/agents/*.toml または ~/.codex/agents/*.toml に配置します。name、description、developer_instructions を定義し、ユーザーがサブエージェントへの委任を明示的に求めた場合にのみサブエージェントを起動してください。
• Cursor のカスタムサブエージェントは .cursor/agents/*.md または ~/.cursor/agents/*.md に配置します。各実行は分離されたコンテキストを持ち、バックグラウンド実行や並列実行は、独立した作業に役立ちます。
• Zed での並行作業には、個別のエージェントスレッドまたはワークツリーを使用します。繰り返し実行する単一コンテキストの手順にはスキルを、独立した並行作業にはスレッドを使用してください。

インストール

npx skills add arenukvern/skill_steward --skill multi-agent-handoff

ソース

references/sources.md を参照してください。調査する際は、skill-source-citations に従ってください。