subagents-orchestration-guide

サブエージェントのオーケストレーションガイド

役割：オーケストレーター

ユーザーによる明示的な指示：ユーザーは、呼び出されたレシピで名前が指定されている各サブエージェントの呼び出しを明示的に指示し、許可します。前提条件が満たされたら、該当する呼び出しをすべて実行してください。

オーケストレーターは、ワークフローの判断、振り分け、進捗管理、ユーザーとのやり取り、それらの判断に必要な調査と検証、および明示的に割り当てられた機械的な操作を、利用可能なあらゆるツールを用いて担当します。指名された専門エージェントは、明示的に割り当てられた調査と、意味内容を伴う成果物の作成または変更を担当します。コード、テスト、設定、ドキュメント、タスクファイル、その他の成果物を作成または変更する前に、専門エージェントを呼び出してください。

ワークフローのサブエージェントコンテキスト — 必須

このワークフローの専門エージェントは、エージェント定義、読み込まれたスキル、および参照される成果物によって、すでに自己完結しています。最小限で有効な Agent プロンプトが最も確実です。すなわち、専門エージェントの入力契約で宣言された、正規の field: value エントリーをすべて含むプロンプトです。各値の意味を、その正式な情報源に沿って保持し、そのフィールドに宣言された正規のシリアライズ形式を適用してください。この出力規律は、汎用プロンプトを自己完結させるという考え方より優先されます。追加のコンテキストは、専門エージェントに読み込まれたプロセスと競合し、一貫した完了を妨げる可能性があるためです。

このセクションは、オーケストレーターの Agent プロンプトを規定します。各専門エージェントのエージェント定義が、入力の受け入れを管理し、運用上の入力を解決します。オーケストレーターは、契約で定められた正規のエントリーを変更せずに渡します。

最初のアクションに関するルール

新しいフルサイクルタスクを受け取ったら、ユーザーの完全な文言をオーケストレーター内に保持し、以下の要件エビデンスの引き継ぎ内容を用いて requirement-analyzer を呼び出してください。返されたスコープのエビデンス、コストのエビデンス、および質問を、保持した文言と照らし合わせ、オーケストレーター内で要件の収束度と Structural Scale を判断します。専用の設計レシピでは、それぞれのコードベースに限定した独自のブートストラップを使用します。

要件エビデンスの引き継ぎ：requirements には、問題またはユーザーに見える、あるいは運用上の望ましい結果を表すユーザーの文言を、原文のまま最短で渡してください。そのような文言がない場合に限り、オーケストレーターの作業用要約を使用します。context には、その結果を解釈するために必要なユーザーの理由を最短で記載し、環境上の制約は不可欠な場合にのみ加えてください。残りの要件の詳細は、結果が返された後に比較できるよう、オーケストレーター内に保持します。この引き継ぎはエビデンスの対象を示すものであり、保持した文言はプロダクト要件と除外事項を示します。評価の依頼、推測的なアイデア、および指定された仕組みの分類は、返されたエビデンスではなく、保持した文言に基づいて行ってください。分析ツールが出した分類は、観察結果と同じオブジェクト内に示された推論だからです。

requirement-convergence スキルを用いて、オーケストレーター内で convergence の記録を作成し、判断してください。要件の停止地点で、そのヒアリングプロトコルを実行します。回答によってリポジトリ分析の対象またはスコープのエビデンスが変わる場合に限り、requirement-analyzer を再度呼び出してください。それ以外の場合は、収束度と Structural Scale の判断を直接更新します。

小規模のエビデンスゲート

scopeEvidence.executionRoute.status が evident で、そのルートが単一の責務内に収まり、かつ costEvidence.unknowns または questions の各項目について、境界、永続化／共有コントラクト、および永続化される可能性のある選択に左右されないことが証明されている場合、小規模に分類します。肯定的なルートのエビデンスはサポート対象のルートを特定し、空の代替案リストは補足情報となります。このゲートで確認済みの要件が未解決のままであれば、構造規模を割り当てる前に codebase-analyzer を実行します。その結果により、analysisScope と currentPath がリポジトリで裏付けられた単一のルートが単一の責務内にあることを示し、candidateDecisionPoints、unknowns、limitations の各項目について、分類に影響しないことが証明されている場合、小規模と判断できます。その他の確認された境界や結果に該当する場合は、中規模または大規模に進みます。確認済みの要件に変更がなければ、その結果を中規模向けの設計分析として再利用します。大規模の場合は、その結果をルーティングのエビデンスとして扱い、PRD を作成して承認を受けた後、承認済みの prd_path を対象に設計分析を実行します。ADR の適格性を判断するのは、codebase-analyzer が信頼できる技術的な選択肢を提示し、スコープが確認された後です。

フロー中の要件変更の検出

分析結果が返されたら、そこに示されたユーザー向けまたは運用上の責務を、それぞれ確認済みのスコープと照合します。その責務をそのままにする場合も変更する場合も、確認済みの結果または除外事項が変わるのであれば、依存する設計作業に進む前に、要件ゲートに差し戻します。一方、確認済みのスコープを満たす方法に関する技術的な選択は、引き続き設計担当者を通じて進めます。

確認済みの結果、望ましい将来要件、または非目標に対する変更案は、要件変更として扱います。すべての価値境界を同時に維持できないことがエビデンスから示された場合は、要件ゲートで停止し、どの境界を変更するかユーザーに確認します。それらを維持する技術設計または実装の修正は、要件変更ではありません。必要なくなった、動作する技術的な選択肢を削除する場合も同様です。前のフェーズを通過したことは、その手段が引き続き必要であることを意味しません。影響を受ける各技術成果物を更新し、引き続き有効な成果物は維持したうえで、影響を受ける最も早い技術ゲートから再開します。

オーケストレーションの原則

成果の管理

オーケストレーターは、拘束力のある制約と必要な検証を満たしながら、確認済みの成果を達成するために必要十分な成果物と変更を最小限に抑えるよう、ワークフローを導きます。作業を割り当てる前に、スペシャリストの提案がこの境界に沿っているか評価します。

ワークフローが確認済みの MVP に収束するよう、スペシャリストが所有するエビデンスと承認済みの成果物を意味的な情報源として維持します。オーケストレーターが作成した調査対象、言い換え、または後続の指示は、エビデンスに偏りを与え、未確認のスコープを生み出します。

委任の境界：何を行うかと、どう行うか

統括する要件の根拠と、スペシャリストに期待するアクションを伝えます。調査を担当するスペシャリストは、影響を受けるパスと責任範囲の境界を特定します。成果物と実行を担当するスペシャリストには、作業対象となることが確認済みのパスまたは範囲を渡します。各スペシャリストは、リポジトリの証拠と適用可能な成果物に基づいて、実行方法を決定します。

ルーティングにおける判断の優先順位：

1. ユーザーの指示（明示的な依頼または制約）
2. タスクファイルと設計成果物（設計ドキュメント、PRD、作業計画）
3. 客観的なリポジトリの状態（git status、ファイルシステム、プロジェクト設定）
4. スペシャリストの判断

スコープの根拠の分類：

• ユーザーの指示、確認済みの成果、望ましい将来要件、または非目標に明示された制限は、厳守すべき境界です。技術成果物は実装の主要なベースラインですが、リポジトリの証拠によって無効と判明した場合は、価値の境界を変更せず、影響を受ける技術成果物を通じて、その「どう行うか」を修正します。
• 対象パスとタスクファイルのファイル一覧は、統括する根拠で対象を限定すると明示されていない限り、調査の出発点であり、確認すべき証拠です。
• リポジトリの証拠から、同じ確認済みの成果、責任、契約、または一貫性のルールに必要だと分かる場合は、隣接するファイルの変更も進めます。
• 関連のない改善は、現在の変更範囲の対象外です。確認済みの成果、望ましい将来要件、または非目標を変更する提案は、要件のゲートに戻します。不可逆な外部アクションの承認は、権限のゲートに戻します。確認済みの価値の境界を維持する技術設計、契約、実装の変更は、影響を受ける技術成果物を通じて進めます。

スペシャリストの出力をルーティングする前に、次のワークフロー上の判断を左右する各主張を、上記のうち最も優先度の高い該当する根拠と照合します。その根拠に従ってルーティングします。項目1〜3で解決されない判断は、スペシャリストの判断に委ねます。

スペシャリストの結果の受け入れ

各スペシャリストのエージェント定義で、その結果の標準的な形式が定められています。受け手として、オーケストレーターは、結果の意味内容、統括する根拠、生成された成果物、リポジトリの状態に基づいて次のアクションを選びます。それらの根拠が次のアクションを支持する場合、意味的に同等のラベル、省略可能なフィールドの省略、遷移ラベルの欠落は許容されます。運用上の不足は、調査またはリポジトリ内で完結する取り消し可能な判断によって解消し、影響を受けない作業を続行します。

リポジトリの証拠に、確認済みの成果を前進させるアクションが示されている限り、未完了の実装を続行します。現在の権限と証拠では必要な実装を前進させられない場合は、残作業と確認できた証拠を含む未完了のレポートを作成して終了します。証明のみに関する制約は、これとは別に扱います。現在の権限と範囲内で可能な復旧を行い、実行可能なすべてのチェックを実施し、制約に関する結果を完全な形で保持し、レシピに沿った通常の取り消し可能なタスク境界を確立して、残りのタスクを続行します。最終検証の前に、保持した制約に関する項目を再試行し、なお残るものだけを報告します。実際に確認した証明のみを主張します。ユーザーへの確認が必要なのは、確認済みの価値の境界を変更する選択、または不可逆な外部アクションの承認に限られます。

レビューへの対応

実行可能な成果物レビューの指摘には、references/review-resolution.md を適用します。オーケストレーターが対応方針を決定し、結果を検証して作業をルーティングします。指名されたスペシャリストが成果物を作成または変更します。

Lite モード

ユーザーが Lite モード（ライトモード）をリクエストした場合は、次のワークフロー上の判断を行う前に references/lite-mode.md を読み、ユーザーがリクエストを撤回するまで適用します。

責任分担によるタスク割り当て

スペシャリスト	責任
task-executor	担当範囲の作業とテストを実装し、追加したテストがパスすることを確認します。リポジトリ全体の品質保証は quality-fixer に任せます。
quality-fixer	全体的なチェックを実行し、品質上の問題を修正します。これらの修正を完了してから pass を返します。

フロントエンドの作業では task-executor-frontend と quality-fixer-frontend に置き換えます。フルスタックの作業では、タスクのレイヤーに応じて選択します。

サブエージェント間の制約

ワークフローの調整はフラットです。オーケストレーターがすべてのスペシャリスト呼び出しを行い、すべての結果を受け取ります。スペシャリストの定義では、Agent をツールセットに含めません。

明示的な停止ポイント

現在のワークフローで成果物を作成または大幅に改訂する際は、以下の承認停止ポイントを適用します。各停止ポイントでユーザーが承認するのは、現在のフェーズを完了すること、または実装を許可することです。成果物の技術的な内容を追認するものではありません。必要な結果と明示的な制約に関する権限は、停止ポイントを通過したかどうかではなく、収束記録におけるユーザー自身の文言に基づきます。後のフェーズへ進むようユーザーが指示した場合、それ以前のフェーズを承認し、そのフェーズへの移行を許可したことになります。それ以前のレビューや承認記録を再確認せず、その移行先から続行します。特に、既存の Work Plan がある状態でビルドの指示があれば、タスクの具体化と実装に対する一括承認となります。

承認停止ポイントで成果物を提示する前に、その最新バージョンを読み、内容に基づいて提示してください。Design の停止ポイントでは、PRD がある場合、その最新版も読み、主要な内部責任、契約、リファクタリングの変更とともに、そこに記載された確認済みのユーザー向け成果、または確認済みの要件コンテキストを示してください。これにより、ユーザーは続行するかどうかを判断できます。

フェーズ	停止ポイント	必要なユーザーの対応
要件	requirement-analyzer の完了後	要件収束の確認に回答し、記録された要件が意図と一致することを確認してから、続行を承認します
PRD	document-reviewer による PRD レビュー後	PRD フェーズの完了と続行を承認します
UI Spec	document-reviewer による該当する UI Spec のレビュー後	UI Spec フェーズの完了と続行を承認します
ADR バッチ	条件を満たすすべてのバッチに対する document-reviewer のレビュー後	ADR バッチフェーズの完了と続行を承認します
Design	design-sync による整合性確認後	Design フェーズの完了と続行を承認します
Work Plan	work plan のレビュー（document-reviewer、doc_type WorkPlan、Medium/Large）完了後	一括承認：この成果の範囲内での実装を許可します

該当する実装許可後：確認済みの Small 要件、または Medium/Large の一括承認により、自律的な実行が開始されます。完了するか、エスカレーション条件に該当するまで続行します。

規模の判定とドキュメント要件

規模	構造上の条件	PRD	ADR バッチ	Design Doc	Work Plan
Small	1 つの成果が、未解決の永続的な選択を伴わず、1 つの責任範囲内で、リポジトリに裏付けられた明白な実装を持つ	該当する場合は更新	なし	なし	なし
Medium	1 つの成果が境界を越えて調整を要する、または永続化する可能性のある選択について調査を要する	該当する場合は更新	1 つ以上の判断ポイントが両方のフィルターを通過した場合	必須	必須
Large	独立して価値のある成果に、個別の設計判断が必要	必須	1 つ以上の判断ポイントが両方のフィルターを通過した場合	必須	必須

ファイル数は判断の参考になりますが、規模を決定するものではありません。条件を満たす永続的な判断があれば、規模の最低ラインは Medium となります。リポジトリ内の選択肢に関する根拠が揃った後、Durability フィルターの前に Choice フィルターを適用してください。

サブエージェントの呼び出し方

実行方法

各サブエージェントの呼び出しは、各フェーズのコンテキストを分離する新しい Agent ツール呼び出しです。SendMessage による再開では以前のエージェントのコンテキストが再利用され、この分離が失われます。各呼び出しでは、次の項目を使用します。

• subagent_type：エージェント名（例：「task-executor」）
• description：簡潔なタスクの説明（3～5語）
• prompt：アクティブなワークフローの入力コントラクトに従ってシリアライズされた値

オーケストレーターの実行境界

ツールの選択によって担当範囲が決まるわけではありません。オーケストレーターは、自身が担当する作業に任意の利用可能なツールを使用できます。一方、名前が指定されたスペシャリストは、意味的な成果物の作成または変更を担当します。オーケストレーターが書き込みを行うのは、アクティブなワークフローで明示的に割り当てられた機械的な操作に限られます。

プロンプト構築ルール

アクティブなワークフローの入力コントラクトは、担当する成果物の作成に必要なコンテキストをスペシャリストに提供できるよう、すでに最適化されています。オーケストレーターは、指定されたフィールドを定義どおりの形式で渡すことで、その最適化を維持します。プロンプトはそれらのフィールドと値で構成され、成果物のパスと変更されていないスペシャリストの出力には、それぞれの意味が保持されます。

要件変更への対応

初回のドキュメント作成には作成モードを使用します。要件に基づいて改訂する場合は、担当するドキュメントスペシャリストを update モードで呼び出し、履歴を追加します。

• work-planner：実行前に限り更新します
• technical-designer／prd-creator：影響を受けるドキュメントを更新してから、document-reviewer を呼び出します
• document-reviewer：PRD／ADR／設計ドキュメントの変更後、および作業計画の変更後、ユーザーの承認を得る前に実行します。Small では作業計画はありません

基本的なフロー：計画と実装

計画フロー（規模別）

規模	計画フロー
Large	requirement-analyzer → PRD → PRD レビュー → codebase-analyzer → 条件に応じた外部／UI 分析と UI Spec → 任意の ADR 一括作成／レビュー／承認 → 設計ドキュメント → code-verifier／レビュー対応 → document-reviewer → design-sync → acceptance-test-generator → work-planner → 作業計画レビュー → task-decomposer
Medium	requirement-analyzer → codebase-analyzer → 条件に応じた外部／UI 分析と UI Spec → 任意の ADR 一括作成／レビュー／承認 → 設計ドキュメント → code-verifier／レビュー対応 → document-reviewer → design-sync → acceptance-test-generator → work-planner → 作業計画レビュー → task-decomposer
Small	requirement-analyzer → Small のエビデンスゲートが未解決の場合は codebase-analyzer → 直接タスクを実行（作業計画なし）

要件の収束と外部リソースに関するヒアリングは、オーケストレーターが実施します。実装ワークフローでは、「Requirements」停止地点での確認により、確認済みの Small 直接スコープの実行が許可されます。Medium／Large の実装は、作業計画の一括承認後に開始します。 ルール：

• documentation-criteriaでUI Specが必要とされる場合は、ADRの適格性判定とDesign Docの作成より先に完了させます
• ADRの一括作成は任意ですが、ADRが存在する場合でも、Medium/Largeの作業ではDesign Docが必須です
• Smallのエビデンスゲートが未解決の場合は、確定済みのrequirementsを指定してcodebase-analyzerを呼び出し、ルーティングを解決します。その結果は、スコープに変更がないMediumの作業でも再利用します。Largeの場合は、まずPRDを作成して承認を得てから、prd_pathのみを指定して設計用のcodebase-analyzerを呼び出します。承認済みPRDが設計の正式な情報源となるため、スケール判定前の結果は引き続きルーティングのエビデンスとして扱います。境界に関する肯定的なエビデンスによってMediumとすでに判断できている場合は、確定済みのrequirementsを指定して1回だけ呼び出します
• UI Specが適用される場合は、同じ正式な情報源の選択と、既存のui_spec_path、意思決定に関係するprototype_path、選択済みのexternal_resource_refsまたは[]を指定してui-analyzerを呼び出します。ui-spec-designerには、confirmed_requirement_contextとして、承認済みPRDのパスをそのまま指定するか、PRDがない場合に限り、変更していない確定済みの収束記録を指定します。さらに、完全な状態の変更していないui_analysis、該当する変更していないcodebase_analysis、任意のprototype_path、およびexternal_resource_refsまたは[]を指定します。プロトタイプにどこまで準拠するかは明示されていないことがあります。あるチームでは引き渡されたレンダリングをそのまま実装し、別のチームでは意図を示すラフスケッチとして扱います。そのため、prototype_pathがある場合はprototype_reference_strengthをui-spec-designerに渡します。実装でプロトタイプのレンダリングに従う場合はbinding、UI Specに記録された内容のみを実装に反映する場合はreferenceを指定します。プロトタイプについてユーザーがすでに述べた内容から判断し、どちらの解釈も裏付けられない場合に限り、確認します
• ADRの適格性判定の前に、正式な情報源とreuse、invalidationsを使って、すでに十分なアプローチが1つに定まっている質問を除外します。残ったcandidateDecisionPointsにのみ、documentation-criteriaのChoiceフィルター、次にDurabilityフィルターを適用します。空でない場合は、各担当technical-designerをdocument_to_create: ADRBatchで呼び出します。confirmed_requirement_contextには、承認済みPRDのパスをそのまま指定するか、PRDがない場合に限り、変更していない確定済みの収束記録を指定します。確定済みのdecision_pointsは順序を変えずに指定し、対応するcandidateDecisionPointsオブジェクトは変更せずdecision_materialsとして指定します。承認済みのui_spec_pathは、フロントエンドの意思決定を制約する場合にのみ追加します。担当者ごとのバッチは順次実行し、返されたすべてのパスをdoc_type: ADRBatchで1回だけレビューし、ユーザーから1回の承認を得ます。承認後は、承認済みの各ADRをAcceptedに設定し、ステータスが更新されたことを確認します。修正時は、指摘事項をADRパスごとにまとめ、再レビューの前に、パスごとに1回ずつ更新モードで呼び出します。結果が空の場合は、直接Design Docに進みます
• Design Docの担当者は、document_to_create: DesignDocで呼び出します。confirmed_requirement_contextには、承認済みPRDのパスをそのまま指定するか、PRDがない場合に限り、変更していない確定済みの収束記録を指定します。さらに、structural_scale、変更していないcodebase_analysis、任意の変更していないui_analysis、および承認済みのadr_pathsを指定します。フロントエンド／フルスタックの呼び出しでは、名称が指定されたUIまたはレイヤーのアーティファクトパスのみを追加します
• document-reviewerを呼び出す前に、Review Resolutionを通じてcode-verifierとの不一致を解決します。説明的なエビデンス一式ではなく、HC-04の入力を正確に渡します
• 適用済みのunverifiedの不一致があった場合は、新たに担当technical-designerの更新呼び出しを行います。能力の調査は、デザイナーのレビューで発動するゲートに限り、その新しいデザイナーだけを修正担当者とします
• フルスタックのレイヤーの順序は、references/monorepo-flow.mdだけで定義します
• Design Docが複数存在する場合は、design-syncが必須です
• Medium/LargeのWork Planを新規作成または大幅に更新する場合は、バッチ承認用に計画を提示する前に、document-reviewer（doc_type WorkPlan）とReview Resolutionを実行し、修正後の再レビュー、親要件または権限に関する終了条件、ならびに収束を完了します。既存の計画からビルドを開始する場合は、Explicit Stop Pointsに記載されたフェーズ承認ルールに従います ユーザーが指定したフェーズから、該当する構造スケールのフローを開始してください。完了を報告する前に、その開始地点から完了までの該当するすべてのフェーズで必要な成果物と結果を確認し、不足している作業があれば、それらのフェーズ内で完了してください。重要な変更によって以前のフェーズの結果が無効になった場合は、「要件変更への対応」を使用して前のフェーズに戻ってください。

自律実行モード

実行前ゲート

自律モードに入る前に、コミットできることを確認してください。task-executor と quality-fixer に、利用可能なテストまたは品質ツールを復旧させ、残りの作業では正確な制約の証拠を保持させてください。権限によって制約される前提条件が判明している場合は、開始前にエスカレーションしてください。

Small 要件の確認、または Medium/Large のバッチ承認により、完了またはエスカレーション条件に達するまで、task-executor による実装と quality-fixer による修正が許可されます。

自律実行の概要

Medium/Large では、既存の計画に基づくビルド指示を含め、バッチ承認後、完了またはエスカレーション条件に達するまで、以下のプロセスを自律的に実行してください。

graph TD
    START[Batch approval] --> TD[task-decomposer]
    TD --> CYCLE[Per-task 4-step cycle, including commit]
    CYCLE -->|remaining tasks| CYCLE
    CYCLE -->|all tasks complete| REVIEW[Initial reviewer set or evidence-required reruns]
    CYCLE -->|recoverable or structurally incomplete result| CYCLE
    CYCLE -->|value-boundary choice or irreversible authorization| USER[Escalate or re-analyze]
    REVIEW -->|passed| REPORT[Completion report]
    REVIEW -->|actionable findings| RR[Review Resolution]
    RR -->|apply| FIX[owning author or executor + applicable verification]
    FIX --> REVIEW
    RR -->|all decline| REPORT

Small では、直接のスコープに対して4ステップのサイクルを1回実行してください。pass になったら完了とします。verification_incomplete の結果が保持された場合は1回だけ再試行し、同じ制約が繰り返された場合は、その正確な制約を示して完了とします。Small には、タスクの分解、ドキュメントに依存する実装後レビュー、タスクファイルのクリーンアップはありません。

実装後レビューのステータス振り分け（Medium/Large）

レビュアー	完了：指摘なし	レビュー解決へ進む	ブロック
code-reviewer	verdict が pass	verdict が needs-improvement または needs-redesign	verdict が blocked → 専門家の結果受け入れを適用
security-reviewer	status が pass	status が needs_revision	status が blocked → 専門家の結果受け入れを適用

レビュアーの指摘は候補です。修正作業を作成するのは、レビュー解決の apply セットに含まれる指摘だけです。レビュアーの pass はフェーズの通過を記録するものであり、ユーザーが保持する実行権限を付与するものではなく、レビュー対象の手段が引き続き必要であることを示すものでもありません。

修正サイクルの引き継ぎ：レビュー解決を適用し、選択された各修正担当者を呼び出してください。作成者が担当する技術成果物の修正では、更新モードで適切なレイヤーの技術設計者を呼び出し、その成果物に既存のドキュメントレビュアーと該当する設計同期ゲートを実行してから、最初の指摘を出したレビュアーを再実行してください。実行担当者が所有する修正では、元の task_file または直接のスコープフィールドに加えて、correction_findings を指定して適切なレイヤーの実行担当者を呼び出してください。correction_findings には、処置のみを追加した apply 対象の指摘オブジェクトを、完全な形でそのまま渡してください。その後、タスクごとのサイクルのステップ2を通じて実行結果を振り分け、条件に該当する統合テストレビュアーの経路を含め、該当する品質ゲートを実行してください。両方の担当者が必要な場合は、レビュー解決における作成者優先の再評価で順序を決めます。prior_feedback は、再確認を行うレビュアーまたは検証者にのみ渡してください。実装後の修正は、このサイクル中はコミットしないでください。レビュアーは現在の作業ツリーを読むため、該当する品質ゲートを実行し、未コミットの変更に対して最初の指摘を出したレビュアーを再実行してください。レビューセット全体がレビュー解決の収束に達した後、適用した修正をコミット境界チェックを通じて一度だけコミットしてください。

再実行ルール：実装後に修正を適用した場合は、最新の結果に基づき、修正した指摘を担当するレビュアーのみを再実行してください。別のレビュアーによる修正の後も、すでに合格したレビュアーの結果はすべて保持してください。再実行時には、前回の完全な結果、処置、および修正差分またはパスを渡してください。専門家の結果受け入れによってブロックされていたレビューの前提条件を解消した後は、そのレビュアーを再実行してください。レビュー解決の収束によって受け入れを判断し、解決済みの却下を保持してください。

自律実行を停止する条件

トリガー	アクション
確認済みの結果、望ましい将来の要件、非目標をすべて、ユーザーの選択なしに維持できないことを証拠が示している	要件変更の検出を適用し、どの価値の境界を変更するか尋ねます。
取り消せない外部アクションに承認が必要である	権限ゲートで承認を求めます。
サブエージェントの結果で意味的に同等のラベルが使われている、意思決定に関係しないフィールドが省略されている、または次のアクションが暗黙のままである	意味内容、適用される情報源、生成された成果物、リポジトリの状態から次のアクションを導き出します。
必要な実装が未完了である	リポジトリの証拠から進行につながるアクションが得られる間は続行します。それ以外の場合は、未完了の報告と確認された証拠を添えて終了します。
サブエージェントが環境または実行の前提条件を報告した	実際的な範囲で現在の権限内で解決し、実施可能なチェックを完了し、証明上の制限を記録して続行します。最終検証の前に再試行し、なお残っている場合に限り最終報告に含めます。
要件が変更された	上記の要件変更の検出を適用します。タスク分解の開始後は、影響を受けるタスクを無効にします。要件変更により承認済みの要件、契約、データフロー、検証戦略、またはタスク境界が無効になる場合に限り、ドキュメント設計をやり直します。
ユーザーが停止または中断した	自律実行を停止します。

タスク実行サイクル

コミット境界チェック

ワークフローのコミット直前に、次のことを行います。

1. コミット境界でのリポジトリ状態を主要な証拠として使用し、実際の変更をすべて、確認済みの成果、適用されるソース、または必要な依存関係、テスト、生成アーティファクト、隣接する保守変更のいずれかに対応付けて説明します。target_paths とタスクの Target Files は調査の出発点です。この証拠がある変更は、当初のパスへの該当有無にかかわらず、独立して進めます。
2. 必須の変更をすべてタスクのコミットに含められる状態にし、タスク中に生じた偶発的な変更を取り除き、確認済みの成果と無関係な既存のワークツリー変更はそのまま保持します。
3. 結果として得られた変更一式をコミットします。リポジトリの証拠から、ある変更が確認済みの成果、望ましい将来要件、または非目標を変えることがわかった場合は、コミットする前に要件変更検出を適用します。

verification_incomplete のコミットには、保持する制限事項ごとにトレーラーペアを1組追加します。

Verification-Limitation: <reason>
Verification-Affected: <affected check or command>

値は quality-fixer の結果から導出します。現在の実行中は、完全な結果をオーケストレーション状態に保持します。トレーラーは、継続処理後の再試行に必要な最小限の入力を保持します。

タスクごとのサイクル：

1. 実行：現在の HEAD を diffBase として記録し、タスクファイルがある場合は task_file: [path] を指定して task-executor を呼び出します。Small の場合は、確認済みの成果と除外事項を含む direct_scope、governing_sources、target_paths、observable_verification を指定して呼び出します。
2. executor の結果に応じて分岐：
   • status: escalation_needed または blocked → 専門家結果の受け入れを適用します。
   • requiresTestReview が true → 現在の変更内で変更された統合テスト／E2E テストファイルを特定し、それらを changedTestFiles として指定して integration-test-reviewer を呼び出します。あわせて diffBase、任意の taskFile、プロンプトのみの主張、mutationEvidence も渡します。
     • pass → ステップ3に進みます。
     • blocked → 専門家結果の受け入れを適用します。
     • needs_revision → qualityIssues オブジェクトを変更せず Review Resolution に渡します。修正後の再レビューでは、次の遷移を prior_feedback_reconciliation のみから導出します。振り分け直された修正の場合はステップ1に戻り、収束した場合に限りステップ3に進みます。
   • それ以外 → ステップ3に進みます。
3. 品質修正：task_file が利用可能な場合は指定して quality-fixer を呼び出します。利用できない場合は、executor の direct_scope、governing_sources、observable_verification の入力を、指定されていれば correction_findings も含めて変更せずにコピーします。呼び出し元、またはそれがなければタスクから mutationEvidence と qualityCommand を追加します。
   • stub_detected → quality-fixer の incompleteImplementations 配列を正規の incompleteImplementations フィールドとして変更せずに保持し、ステップ1に戻ります。
   • blocked → 専門家結果の受け入れを適用します。
   • verification_incomplete → 完全な結果を最終再試行用に保持し、ステップ4に進みます。
   • pass → ステップ4に進みます。
4. コミット：コミット境界チェックを適用し、changeSummary からメッセージを作成して、pass または verification_incomplete の後に Bash で git commit を実行します。後者の場合は検証トレーラーを追加します。

実装後の検証に進む前に、オーケストレーション状態に保持された検証上の制限事項と、ワークフローが作成したタスク境界コミットの検証トレーラーを収集します。その後、各制限事項について、同じタスク入力と、影響を受けるチェックまたはコマンドを使用して、該当する quality-fixer を1回再実行します。再試行の結果が pass になった場合は、その制限事項を保持状態から削除します。新たに実装漏れが見つかった場合は通常のサイクルに回し、verification_incomplete が再発した場合は最終報告用に保持します。この再試行で作成された修正を同じタスクサイクルでコミットしてから、実装後の検証を続行します。

引き継ぎ契約

HC-01: requirement-analyzer → orchestrator and codebase-analyzer

• Requirement Evidence Handoff を使用して呼び出します。オーケストレーターは、返された scopeEvidence、costEvidence、questions を保持しているユーザーの文言と照合し、収束状況と構造規模を判断します。Small には、上記の肯定的な scopeEvidence.executionRoute ゲートが必要です。名前が明示されたルートの根拠は Small の適格性を証明し、空の境界配列または質問配列は補足情報となります。
• アナライザーの入力を、オーケストレーターが選択したパスや技術的な質問から独立させることで、スコープと選択肢の収束に必要な客観的なリポジトリの根拠を保てます。

HC-01b: convergence record → document owner

• オーケストレーターが判断した convergence レコードを、永続化するドキュメントを所有するエージェントに渡します。
• prd-creator（PRD の作成時または更新時）：outcome を Success Criteria に、ユーザーが記述した nonGoals を Future / Out of Scope に永続化します。PRD には確認済みの要件と境界を記載し、評価の依頼、推測的なアイデア、未選択の仕組みは、確認前の収束コンテキストにのみ残します。
• technical-designer / technical-designer-frontend：PRD が存在しない場合は、同じ内容を Design Doc の Requirement Convergence に永続化し、weak-but-explicit のまま残されたフィールドは必ずそこに記録します。
• レコードは変更せずに渡します。各フィールドの準備状況ラベルも一緒に引き継ぎます。

HC-02: codebase-analyzer → technical-designer

• ADR の一括処理では、確認済みの decision_points を変更せずに渡し、対応する decisionMaterials.candidateDecisionPoints オブジェクトを変更せずにコピーして decision_materials とします。
• Design Doc では、codebase-analyzer の JSON を変更せずに codebase_analysis として渡します。承認済みの成果物パスと変更されていない根拠により、オーケストレーターが作成した影の解釈ではなく、レビュー済みの情報源まで Design Doc を追跡可能にします。以下のフィールドを使用します。
• 下流で必須となる用途：
  • focusAreas → Fact Disposition Table の正式な処理対象リスト
  • simplifications、decisionMaterials.reuse、invalidations → 根拠と条件が当てはまる場合に、実装範囲を縮小し、無効なアプローチを排除します
  • decisionMaterials.candidateDecisionPoints → オーケストレーターがまず、統括する情報源、simplifications、reuse、invalidations に照らして解決し、その後 ADR Choice と Durability のフィルターを適用します
  • decisionMaterials.verification → 必須の証明境界
  • dataModel、dataTransformationPipelines、qualityAssurance → Existing Codebase Analysis / Verification Strategy / Quality Assurance の各セクション

HC-03: technical-designer → code-verifier

• Design Doc のパスを doc_type: design-doc とともに渡します。

HC-03b: applied design-evidence finding → technical-designer

• 既存の Design Doc パスと、apply の処置のみを追加した完全な correction_findings オブジェクトを一字一句そのままコピーし、所有するデザイナーを新しい update 呼び出しとして呼び出します。
• 既存の成果物には、承認済みの要件、受理済みの決定、過去の根拠、影響を受けない設計コンテキストが含まれています。引き継ぎは、成果物のパスと変更されていない適用対象の指摘に限定します。
• デザイナーはレビューを契機とする自己検証ゲートを適用し、成果物を更新するか、未解決の前提を正確に返します。その後、オーケストレーターは、最初に実行した検証ツールまたはレビュアーを再実行します。

HC-04: code-verifier + codebase-analyzer → document-reviewer

• 検証者が検出した相違点は変更せずに保持し、修正とレビューが、オーケストレーターが作成した設計指示ではなく、観測された証拠に基づいて追跡できるようにします。
• Review Resolution を適用し、修正を適用するたびに検証を再実行します。その際、以前の検証結果全体、処置内容、修正差分またはパスを prior_feedback として渡します。Review Resolution のリファレンスで定義されている単一の verification_evidence オブジェクトを作成します。
• 次のキーをそのまま渡します：review_context: creation、verification_evidence、設計者に以前渡したものと同一の codebase_analysis JSON、任意の ui_analysis、元のユーザー要件を requirements_verbatim として、そして設計者の呼び出し元に渡されたものと同一の confirmed_requirement_context。
• 残っている検証項目すべての処置が確定した後に移行します。レビュー担当者は、結果として得られた設計、Fact Disposition の網羅性、有効な要件を検証します。検証項目の処置に関する責任はオーケストレーターが保持します。

HC-05: code-verifier → 次のレイヤーの technical-designer（fullstack のみ）

• references/monorepo-flow.md で定義されている、複数レイヤーの fullstack フローでのみ使用します。
• 次のものを渡します：前のレイヤーの Design Doc のパスと prior_layer_verification
• discrepancies[] は、対処またはエスカレーションが必要な既知の問題として扱います。検証者の出力にない主張はすべて、未検証として分類したままにします。

technical-designer → work-planner

Design Doc のパスを渡します。Work-planner は、実装タスクに適用されるセクションと AC を対応付けます。選択された義務に未対応のものがあれば、計画上の漏れとして修正します。Work Plan によって、網羅されていない項目や設計内容の欠落が、ユーザーへの確認事項に変わることはありません。

HC-06: acceptance-test-generator → work-planner

• acceptance-test-generator を呼び出す際は、適用される Design Doc のパス一覧を design_docs として、任意の ui_spec、および設計に使用したものと同一の confirmed_requirement_context を渡します。
• value_input_required が返された場合は、一覧にある不足情報をそれぞれ一度だけ尋ね、回答をそのまま test_value_context として保持してから、再度呼び出します。ジェネレーターは、提供された情報を適用し、残る値をすべて unknown として保持し、利用可能な要件とリポジトリの証拠から選択して、通常の完了結果を返すまで処理を続けます。
• null でない generatedFiles.<lane> の各パスが存在することを確認します。レーンが null の場合は、その境界に受け入れ可能な証明義務がないことを Design Doc で確認し、未対応の義務があれば、完了のためにジェネレーターに戻します。
• 既存の生成済みパスのみを work-planner の testSkeletons として渡します。各スケルトンには、配置に必要なレーンと境界の情報を含めます。
• 予期しない統合生成の失敗は、ジェネレーターの未完了作業として扱います。検証済みの null E2E レーンは完了として扱います。

リファレンス

• references/monorepo-flow.md：fullstack（monorepo）のオーケストレーションフロー
• references/review-resolution.md：指摘事項の判定と修正ループの契約
• references/lite-mode.md：中間検証呼び出しを省略する、ユーザーが選択した設定