| name | subagents-orchestration-guide |
| description | サブエージェントのタスク分担と連携を調整。規模判定と自律実行モードを制御。大規模タスク分割時に使用。 |
サブエージェントを活用してタスクを効率的に処理するための実践的な行動指針。
「私は作業者ではない。オーケストレーターである。」
新しいタスクを受け取ったら、ユーザー要件をrequirement-analyzerに直接渡す。その規模判定結果に基づいてワークフローを決定する。
フロー実行中にユーザーレスポンスで以下を検知したら、フローを停止してrequirement-analyzerへ：
1つでも該当 → 統合要件でrequirement-analyzerから再開
「何を達成するか」「どこで作業するか」を渡す。各サブエージェントは「どう実行するか」を自律的に決定する。
渡す情報（what/where/制約）:
サブエージェントに委ねる判断（how）:
| Bad（howを指定） | Good（whatを指定） | |
|---|---|---|
| quality-fixer | 「lint → test の順でチェックして」 | 「品質チェックと修正をすべて実行して」 |
| task-executor | 「ファイルXにハンドラYを追加して」 | 「タスクファイル: docs/plans/tasks/003-feature.md」 |
出力が矛盾した場合の優先順位:
サブエージェント同士の判断が衝突した場合、またはサブエージェントの出力が期待と異なる場合、上記の優先順位を適用する。リポジトリの客観的状態（3）で検証し、1・2と整合する出力に従う。矛盾がある場合はユーザー指示、次いで設計成果物に従う。
サブエージェントがリポジトリの状態や成果物から実行方法を判断できない場合、blockedステータスでエスカレーションする。その詳細をユーザーに伝える。
task-executorの責務:
quality-fixerの責務:
基本サイクル: task-executor → エスカレーション判定・フォローアップ → quality-fixer → commit の4ステップサイクルを管理。
各タスクごとにこのサイクルを繰り返し、品質を保証。
レイヤー別ルーティング: レイヤー横断機能では、タスクファイル名パターンに基づいてexecutorとquality-fixerを選択（レイヤー横断オーケストレーション参照）。
重要: Sub-agentから他のSub-agentを直接呼び出すことはできない。複数のSub-agentを連携させる場合は、メインAIがオーケストレーターとして動作。
| 規模 | ファイル数 | PRD | ADR | Design Doc | 作業計画書 |
|---|---|---|---|---|---|
| 小規模 | 1-2 | 更新※1 | 不要 | 不要 | task-template 形式の単一タスクファイル（docs/plans/tasks/ 直下、計画書ファイルは別途作成しない） |
| 中規模 | 3-5 | 更新※1 | 条件付き※2 | 必須 | 必須 |
| 大規模 | 6以上 | 必須※3 | 条件付き※2 | 必須 | 必須 |
※1: 該当機能のPRDが存在する場合は更新 ※2: アーキテクチャ変更、新技術導入、データフロー変更がある場合 ※3: 新規作成/既存更新/リバースPRD（既存PRDがない場合）
すべてのサブエージェント呼び出しは Agent ツール を使用し、以下を渡す:
subagent_type: エージェント名（例: "task-executor"）description: 簡潔なタスク記述（3〜5語）prompt: 成果物のパスを含む具体的な指示オーケストレーターは以下のツールのみで作業を統制する:
| ツール | 用途 |
|---|---|
| Agent | サブエージェントの呼び出し |
| AskUserQuestion | ユーザー確認・質問 |
| TaskCreate / TaskUpdate | 進捗追跡 |
| Bash | シェル操作（git commit、ls、検証コマンド） |
| Read | サブエージェント間の情報橋渡しのための成果物ドキュメント参照 |
実装作業（Edit、Write、MultiEdit）はすべてサブエージェントが実施する。オーケストレーター自身は行わない。
サブエージェントはJSON形式で応答。オーケストレーター判断に必要なフィールド：
| Agent | 主要フィールド | 判断ロジック |
|---|---|---|
| requirement-analyzer | scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions | scaleでフローを選択。adrRequiredでADRステップ要否を判断 |
| codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations | focusAreasをtechnical-designerにコンテキストとして渡す |
| ui-analyzer | externalResources (status, per-axis fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], focusAreas[], candidateWriteSet[], limitations | ui-analyzerのJSONをui-spec-designerとtechnical-designer-frontendに渡す。各エージェントは自身の入力宣言に記載されたフィールドを使う |
| code-verifier | status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). 実装前: Design Docの主張を既存コードに対して検証。実装後: 実装のDesign Doc整合性を検証（code_pathsで変更ファイルにスコープ） | discrepanciesをdocument-reviewerに連携 |
| task-executor | 入力: task_file（オーケストレーションフローでは必須）; 任意の Fix Mode シグナル requiredFixes または incompleteImplementations — いずれかが非空の場合、task_already_completed チェックをスキップし、各項目の file_path / location（location は file[:line] として解釈）で許可リストを拡張する。incompleteImplementations[] の各エントリは type: "missing_logic" | "hollow_test" を持ち得て、executor は type で修正アクションを分岐する。出力: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, runnableCheck{level, executed, command, result, substance, substanceIssue, reason}, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain, binding_decision_violation, test_environment_not_ready} | escalation_needed時: escalation_type別に対応 |
| quality-fixer | 入力: task_file（現在のタスクファイルパス — オーケストレーションフローでは常に渡す）、filesModified（上流の実装ステップのレスポンスから抽出 — 当該タスクの書き込み集合を未完成実装検出の主要スコープとして渡す。省略時は git diff HEAD にフォールバック）、runnableCheck（上流の実装ステップのレスポンスから抽出 — substance と substanceIssue を含むテスト実行のエビデンスを渡し、Substance チェックが実行時のシグナルを受け取れるようにする。上流がテストを実行していない場合は省略可）。Status: approved/stub_detected/blocked。stub_detected → incompleteImplementations[] の各エントリは type: "missing_logic" | "hollow_test" を持ち、type で executor 側の修正アクションを分岐させた上で上流の実装ステップに差し戻し、本実装完了後にquality-fixerを再実行。blocked → 下記quality-fixer blockedハンドリング参照 | stub_detected: 実装ステップを再実行。blocked: 下記参照 |
| document-reviewer | approvalReady (true/false) | trueで次ステップへ。falseで修正を依頼 |
| design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | CONFLICTS_FOUND時: 矛盾をユーザーに提示してから進む |
| integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | needs_revision時: 同じ task_file と requiredFixes[] を渡してルーティング先の executor を Fix Mode で再実行 |
| security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | needs_revision時: requiredFixes[].location から影響ファイルパスを抽出して Target Files に投入した統合修正タスクファイルを作成し、その task_file と requiredFixes[] 配列を渡してルーティング先の executor を Fix Mode で起動。続いて quality-fixer を実行し、最後に security-reviewer を再起動して解消を検証する。blocked 時: ブロッキング findings を添えてユーザーにエスカレーション — エージェント層の権限外の修正である |
| acceptance-test-generator | status, generatedFiles.{integration,fixtureE2e,serviceE2e}（レーンごとに path|null）, budgetUsage（レーン別）, e2eAbsenceReason（E2Eレーンごと。出力時は null。reason の enum 定義は acceptance-test-generator と integration-e2e-testing スキルが所有） | 非nullの各 generatedFiles.<lane> パスがディスク上に存在することを確認し、レーン別のパスと不在理由を work-planner に渡す |
quality-fixerが status: "blocked" を返した場合、reasonで判別：
"Cannot determine due to unclear specification" → blockingIssues[]で仕様詳細を確認"Execution prerequisites not met" → missingPrerequisites[]のresolutionStepsをユーザーにアクション可能なステップとして提示docs/plans/tasks/ 直下に task-template 形式の単一タスクファイルを直接出力する。task-executor にはそのパスを task_file として渡す [停止: 一括承認]注: 小規模スケールでも実装ステップは task-executor を介して標準の4ステップサイクル（task-executor → エスカレーション判定 → quality-fixer → commit）で実行する。オーケストレーターによる直接編集は行わない。
Medium / Large規模では、一括承認後、作業計画書のヘッダに Implementation Readiness: 行が含まれる（work-plannerがpendingを出力する。ready または escalated への昇格は外部オーケストレーションの関心事である）。マーカーは以下3値のいずれかを取る:
pending — work-plannerが設定する初期状態ready — readiness検証が完了し残存ギャップなし。タスク実行サイクルを安全に開始できるescalated — readiness検証は完了したが残存ギャップが存在し、実行前にユーザー判断が必要pendingから先へマーカーを昇格させるプロデューサと、task-executor呼び出し前にマーカーを読むコンシューマは、いずれも外部オーケストレーションが所有する。本ガイドはエージェント層の上位にあるオーケストレーターを呼び出さない。エージェントは明示的に依頼された場合にのみマーカーを読み書きする。
requirement-analyzerが複数レイヤー（backend + frontend）にまたがる機能と判定した場合（crossLayerScopeで判断）、以下の拡張を適用。ステップ番号は大規模フロー基準。中規模フローではDesign Doc作成がステップ2から始まるため、同じパターンをステップ2a/2b/3/4として適用する。
標準のDesign Doc作成ステップをレイヤー別作成に置き換え:
| ステップ | エージェント | 目的 |
|---|---|---|
| 8 | codebase-analyzer ×2 | レイヤー別コードベース分析（要件分析結果をレイヤーでフィルタして入力） |
| 9 | technical-designer | バックエンドDesign Doc（バックエンドcodebase-analyzerコンテキスト付き） |
| 10 | code-verifier | バックエンドDesign Docを既存コードに対して検証（結果JSONはステップ12にprior_layer_verificationとして渡す） |
| 11 | document-reviewer | バックエンドDesign Docをレビュー（ステップ10の結果をcode_verification、バックエンドcodebase-analyzer JSONをcodebase_analysisとして入力）[criticalで停止] — ここで構造的欠陥が出た場合はステップ12に進めない |
| 12 | technical-designer-frontend | フロントエンドDesign Doc（フロントエンドcodebase-analyzerコンテキスト + レビュー済みバックエンドDesign Doc + ステップ10のprior_layer_verification + UI Spec付き） |
| 13 | code-verifier | フロントエンドDesign Docを既存コードに対して検証 |
| 14 | document-reviewer | フロントエンドDesign Docをレビュー（ステップ13の結果をcode_verification、フロントエンドcodebase-analyzer JSONをcodebase_analysisとして入力）[criticalで停止] — ここで構造的欠陥が出た場合はステップ15に進めない |
| 15 | design-sync | レイヤー間整合性検証 [停止] |
codebase-analyzer ×2 の呼び出しは並列実行可能。バックエンド経路（ステップ9〜11）はステップ12の前に直列で完了させる。これによりフロントエンドdesignerは、document-reviewerによって構造的欠陥（AC欠落、Fact Disposition Tableの不備、Verification Strategy欠落）が既に検出され、code-verifierによってコード/ドキュメント不整合が既に列挙された状態のバックエンドDesign Docを読む。フロントエンドdesignerは prior_layer_verification.discrepancies[] とステップ11のレビュー指摘から、既知の問題を持つバックエンド契約を識別し、不安定な契約面を迂回した設計ができる（統合点を安定した契約へ切り替える、または依存を「## Cross-Layer Assumptions」に記録する）。
Design Doc作成時のレイヤーコンテキスト指定:
prior_layer_verification.discrepancies[]とレビュー指摘から不安定なバックエンド契約を識別する。検証済みと見なせる主張は検証結果JSONに明示されているものに限定する。未検証のまま依存せざるを得ない契約は、「## Cross-Layer Assumptions」セクションに正当化と検証先を記載する。UI Spec [パス] のコンポーネント構造を参照。対象: コンポーネント階層、状態管理、UI操作、データ取得。」design-sync: フロントエンドDesign Docをソースとして使用。docs/design/内の他のDesign Docを自動検出して比較。
全Design Docをwork-plannerに渡し、垂直スライスで構成を指示:
自律実行中、タスクファイル名パターンに基づいてエージェントを選択:
| ファイル名パターン | Executor | Quality Fixer |
|---|---|---|
*-task-* または *-backend-task-* | task-executor | quality-fixer |
*-frontend-task-* | task-executor-frontend | quality-fixer-frontend |
自律実行モード開始後：
status: escalation_needed または status: blocked → ユーザーにエスカレーションrequiresTestReview が true → integration-test-reviewer を実行
needs_revision → ルーティング先の executor（レイヤー別エージェントルーティング 参照、task-executor または task-executor-frontend）を Fix Mode で再実行（同じ task_file と requiredFixes[] を渡す）approved → quality-fixer へ進む以下の場合に自律実行を停止し、ユーザーにエスカレーション：
サブエージェントからのエスカレーション
status: "escalation_needed" のレスポンス受信時status: "blocked" のレスポンス受信時要件変更検知時
work-planner更新制限に抵触時
ユーザー明示停止時
すべてのサブエージェントプロンプトに以下を含める:
エージェントのInput Parametersセクションと、フロー内のその時点で利用可能な成果物からプロンプトを構成する。
追加の2つのルール:
[placeholder] は Agent ツール呼び出し前にすべて具体値へ置換する。状態管理: 現在のフェーズ、各サブエージェントの状態、次のアクションを把握
情報の橋渡し: サブエージェント間のデータ変換と伝達
codebase-analyzerへの入力: 要件分析JSON出力、PRDパス（存在する場合）、元のユーザー要件 technical-designerへの入力: codebase-analyzerのJSON出力をDesign Doc作成プロンプトの追加コンテキストとして渡す。必須の使い道:
focusAreas → Fact Disposition Tableの正典となるdisposition targetリスト（各focusAreaを1行に展開し、fact_idとevidenceをそのまま引き継ぐ）dataModel、dataTransformationPipelines、qualityAssurance → 「既存コードベース分析」「検証戦略」「品質保証メカニズム」の各セクションに反映code-verifierへの入力: Design Docパス（doc_type: design-doc）。code_pathsは指定を省略する — verifierがドキュメントからコードスコープを独自に発見する。
document-reviewerへの入力: code-verifierのJSON出力をcode_verificationパラメータとして渡す。加えて、designerに渡したものと同じcodebase-analyzerのJSONをcodebase_analysisとして渡す。reviewerはcodebase_analysis.focusAreasを使ってFact Disposition Tableのカバレッジを検証する。
次レイヤーのtechnical-designerへの入力: レビュー済みの前レイヤーDesign Docパスに加えてprior_layer_verification（前レイヤーcode-verifierのJSON）を渡す。シーケンスは「レイヤー横断オーケストレーション」セクションを参照。prior_layer_verification.discrepancies[]と前レイヤーのレビュー指摘を用いて不安定な契約を識別する。検証済みと見なせる主張は検証結果JSONに明示されているものに限定する。verifierで確認されていない主張に設計が依存せざるを得ない場合、フロントエンドDesign Docの「## Cross-Layer Assumptions」セクションに正当化と検証先を記載する（エスカレートする場合は同セクションで 検証先: ユーザーへエスカレーション と記載する — エスカレーションは下流の検証ステップで依存を閉じられない場合のみ選ぶ）。
work-plannerへの入力: Design Docパス。work-plannerがDDの全セクションをスキャンし、Step 5のカテゴリ（impl-target, connection-switching, contract-change, verification, prerequisite）に沿って技術要件を抽出した上で、設計-計画トレーサビリティ表を作成する。
ギャップ発生時の制御（オーケストレーターの責務）: work-plannerがgapを含むドラフト計画書を出力した場合、オーケストレーターは以下を実行する:
acceptance-test-generatorへの入力: Design Doc のパス、UI Spec のパス（存在する場合）。
オーケストレーターの検証: 非nullの各 generatedFiles.<lane> パスがディスク上に存在すること。nullのレーンごとに e2eAbsenceReason.<lane> が存在すること — これは意図的な不在であり、エラーではない。
work-plannerへの入力: 統合テスト / fixture-e2e / service-integration-e2e の各ファイルパス（レーンごとに値またはnull）、レーン別の不在理由、およびタイミングガイダンス — 統合テストは各フェーズ実装と並行して作成、fixture-e2e テストは UI 機能フェーズと並行して作成、service-integration-e2e テストは最終フェーズでのみ実行。
エラー時: status != completed で統合テストファイル生成が予期せず失敗した場合はユーザーにエスカレーションする。E2Eレーンがnullかつ妥当な不在理由がある場合はエラーではない。
ADRステータス管理: ユーザー判断後のADRステータス更新（Accepted/Rejected）
TaskCreateで全体フェーズを登録。各フェーズ完了時にTaskUpdateで更新。
| Verifier | Pass | Fail | Blocked |
|---|---|---|---|
| code-verifier | statusがconsistentまたはmostly_consistent | statusがneeds_reviewまたはinconsistent | — |
| security-reviewer | statusがapprovedまたはapproved_with_notes | statusがneeds_revision | statusがblocked → ユーザーにエスカレーション |
再実行ルール: 修正サイクル後、Failを返した検証エージェントのみ再実行。前回Passした検証エージェントは再実行しない。最大2回の修正サイクル — 2回後も不合格が残る場合、残存する検出事項とともにユーザーにエスカレーション。
Coordinates subagent task distribution and collaboration. Controls scale determination and autonomous execution mode.
PRD、ADR、Design Doc、UI Spec、作業計画書の作成を支援。技術ドキュメントの作成・レビュー時、または「UI Spec/画面設計/コンポーネント分解」が言及された時に使用。
Guides PRD, ADR, Design Doc, UI Spec, and Work Plan creation. Use when creating or reviewing technical documents, or when "UI spec/screen design/component decomposition" is mentioned.
コードの品質問題、アンチパターン、可読性を検査。機能実装、コードレビュー、リファクタリング時に使用。
Detects code smells, anti-patterns, and readability issues. Use when implementing features, reviewing code, or refactoring.
Provides project-specific prerequisites for AI execution accuracy — domain constraints, development phase, directory conventions, external resource access methods. Use when the session starts, when checking project structure, or when a task references domain rules or external resources outside the repository.