subagents-orchestration-guide-f00f6f — independently scanned and version-tracked by SaferSkills.
SaferSkills independently audited subagents-orchestration-guide-f00f6f (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
ユーザーの明示的な指示: ユーザーは、呼び出されたレシピで名前が挙げられたすべてのサブエージェント呼び出しを明示的に指示し、承認している。各呼び出しの前提条件を満たした時点で、該当する呼び出しを実行する。
新規のフルサイクルタスクを受け取ったら、ユーザー要件をrequirement-analyzerに渡し、ユーザーの文言はオーケストレーターが保持する。返ってきたスコープ・コスト・質問のエビデンスをその文言と照らし合わせて要件収束を実行し、構造スケールを割り当てる。評価の依頼、推測的なアイデア、手段の指定は、アナライザの出力ではなくユーザーの文言から分類する。どちらの判定もオーケストレーターが持つ。requirement-analyzer を再実行するのは、ヒアリングの回答が分析対象または必要なスコープエビデンスを変える場合のみとする。
ワークフローの開始時または再開時に呼び出しを振り分ける前に、ユーザーの明示的なモード指定、ロード済みのルートCLAUDE.mdのWorkflow Mode指示の順にモードを解決する。どちらもなければNormalモードとする。セッションでの明示指定はユーザーが変更するまで適用し、リポジトリの既定値より優先する。
以下のフローはNormalモードを記述する。Liteモードではreferences/lite-mode.mdを読み、その呼び出し集合と品質境界を適用する。省略されない呼び出しを実行し、実際に生成された結果だけを使用する。ユーザー承認の停止点と権限境界は、どちらのモードにも適用する。
確認済みの成果、将来状態の要件、対象外の変更案を要件変更として扱う。これらを同時には維持できないことをエビデンスが示す場合は、要件ゲートで停止し、どれを変更するかユーザーに確認する。これらを維持する技術設計または実装の修正は要件変更ではなく、機能しているが不要になった技術的な選択の削除もこれに含まれる。前のフェーズを通過したことは、そのフェーズで選んだ手段が引き続き必要であることを示さない。影響を受ける技術成果物をそれぞれ更新し、なお有効な出力を維持したまま、影響を受ける最も早い技術ゲートから再開する。
「何を達成するか」「どこで作業するか」を渡す。各サブエージェントは「どう実行するか」を自律的に決定する。
渡す情報（what/where/制約）:
サブエージェントに委ねる判断（how）:
| Bad（howを指定） | Good（whatを指定） | |
|---|---|---|
| quality-fixer | 「lint → test の順でチェックして」 | 「品質チェックと修正をすべて実行して」 |
| task-executor | 「ファイルXにハンドラYを追加して」 | 「タスクファイル: docs/plans/tasks/003-feature.md」 |
出力が矛盾した場合の優先順位:
ユーザー指示にある明示的な制約と、確認済みの成果、将来状態の要件、対象外は必ず守る。技術成果物は主要な実装基準だが、これらを変えずにリポジトリのエビデンスが技術的な実現方法を否定する場合は、影響を受ける技術成果物を修正する。対象パスとタスクファイルのファイル一覧は、正典にそれらだけが対象であると明示されていない限り、調査の開始地点である。関係のない改善は現在の変更に含めない。
各専門エージェントの定義が、正規の結果形式を定める。受け手であるオーケストレーターは、結果が示す意味、正典、作成された成果物、リポジトリの状態から次の行動を決める。それらから次の行動を判断できる場合は、意味が同じラベル、省略された任意フィールド、遷移ラベルの欠落を受け入れる。運用上の不足は、調査またはリポジトリ内で完結する可逆な判断によって解消し、影響を受けない作業を続ける。
リポジトリのエビデンスから確認済みの成果へ進む行動を導ける間は、未完了の実装を続ける。現在の権限とエビデンスでは必要な実装を進められない場合は、残作業と観測したエビデンスを未完了報告に記載して終了する。証明だけが不足する場合は別に扱う。現在の権限とスコープで可能な回復を行い、利用可能なチェックをすべて実行し、証明不足の結果を省略せず保持したうえで、レシピ本来の可逆な境界から残りの作業を続ける。最終検証の前に、同じスコープと対象チェックで該当するquality-fixerを1回だけ再実行する。passなら証明不足を解消し、stub_detectedならincompleteImplementationsを通じて実装へ戻し、verification_incompleteが再度返った場合だけ報告する。観測できた証明だけを完了根拠にする。ユーザーに確認するのは、確認済みの成果、将来状態の要件、対象外のどれを変えるか選ぶ場合、または不可逆な外部操作を承認する場合に限る。
対応可能な成果物レビューの検出事項には references/review-resolution.md を適用する。処理方針の決定、結果の検証、作業のルーティングはオーケストレーターが行い、成果物の作成・変更は指名した専門エージェントが行う。検出事項単位の修正ループ — 処理方針の割り当て、apply の逐語ハンドオフ、prior_feedback による再レビュー、収束とエスカレーションの条件 — は、この参照ドキュメントが最初から最後まで定める。
task-executorの責務:
quality-fixerの責務:
タスクサイクル: 各タスクの実装結果と必要な統合/E2Eレビューを受理し、選択したモードの品質境界を適用して、レシピのコミットポイントで完了済みタスクをコミットする。Normalモードはタスクごとにquality-fixerを実行し、Liteモードは最終品質チェックを使用する。各タスクで対象を絞った検証は維持する。
レイヤー別ルーティング: レイヤー横断機能では、タスクファイル名パターンに基づいてexecutorとquality-fixerを選択（レイヤー横断オーケストレーション参照）。
ワークフローの連携はフラットに保つ。各専門エージェントの呼び出しと結果の受け取りはすべてオーケストレーターが行い、専門エージェントの定義では Agent をツールセットに含めない。
オーケストレーターは、収束した成果とリポジトリのエビデンスに documentation-criteria を適用する。スケールは判断負荷に従う: 小規模は1つの責務境界の中に明白な実装が1つ、中規模は境界をまたいだ調整または後続作業に長く影響しうる選択を含み、大規模は別個の設計判断を要する独立した成果を複数含む。ファイル数は補助的なエビデンスにとどまる。
| スケール | PRD | ADR | Design Doc | 作業計画書 |
|---|---|---|---|---|
| 小規模 | プロダクトスコープが変わる場合は更新 | 不要 | 不要 | 不要 — task-executor が明示プロンプトから実行する |
| 中規模 | プロダクトスコープが変わる場合は更新 | ADRの両フィルタを通過した決定ポイントのみ | 必須 | 必須 |
| 大規模 | 必須 — 新規作成・更新・リバースPRDのいずれか | ADRの両フィルタを通過した決定ポイントのみ | 必須 | 必須 |
適格なADRが存在する場合、スケールは最低でも中規模に引き上げられる。適格なADRはすべて1つのバッチとしてレビューし、受理した決定を Design Doc 作成前に Accepted にする。
すべてのサブエージェント呼び出しは Agent ツール を使用し、以下を渡す:
subagent_type: エージェント名（例: "task-executor"）description: 簡潔なタスク記述（3〜5語）prompt: 成果物のパスを含む具体的な指示オーケストレーターは以下のツールのみで作業を統制する:
| ツール | 用途 |
|---|---|
| Agent | サブエージェントの呼び出し |
| AskUserQuestion | ユーザー確認・質問 |
| Bash | シェル操作（git commit、ls、検証コマンド） |
| Read | サブエージェント間の情報橋渡しのための成果物ドキュメント参照 |
実装作業（Edit、Write、MultiEdit）はすべてサブエージェントが実施する。オーケストレーター自身は行わない。
各エージェントが自身の入出力契約を宣言する。呼び出しを構成する際にその契約を読み、返された結果には、ここで別のルーティングスキーマを要求せず「専門エージェントの結果の受理」を適用する。
オーケストレーターが担うエージェント間の受け渡し: quality-fixer には、未追跡・削除・リネームを含む現在の未コミットのワークツリー全体を調べるよう依頼する。実装ステップの runnableCheck を引き継ぎ、レシピまたは technical-spec がプロジェクトの正典となる品質コマンドを示している場合は qualityCommand として渡す。
quality-fixer は、実行できなかったチェックと無関係と確認済みの既存失敗を、既存のチェック結果に記録する。今回の変更に関係する実行可能なチェックがパスした後は、pass として通常のルーティングを続ける。今回の変更が原因の失敗、または受け入れ済みの成果に必要な依存の失敗は、元のタスクにそのパスがなくても修正対象とする。
新機能や変更要求を受け取ったら、まず要件のエビデンスを収集し、要件を収束させ、構造スケールを割り当てる。
ADRBatch モードで実行 → document-reviewer によるバッチレビュー → 検出事項への対応 → 承認したADRを Accepted にする [停止]DesignDoc モードで実行 → code-verifier → document-reviewer → design-sync → Design Doc承認 [停止]ADRBatch モードで実行 → document-reviewer によるバッチレビュー → 検出事項への対応 → 承認したADRを Accepted にする [停止]DesignDoc モードで実行 → code-verifier → document-reviewer → design-sync → Design Doc承認 [停止]小規模では作業計画書もタスクファイルも作成しない。新たに適格なADRが判明した場合は中規模へ移行し、それ以外では計画ドキュメントを導入しない。
該当するStructural Scaleフローは、ユーザーが求めたフェーズから開始する。その指示は先行するフェーズを受理したことを意味するため、先行するレビューや承認の記録を再確認せず、その開始点から続行する。完了を報告する前に、開始点以降の該当フェーズが必要とする成果物と結果を検証し、不足している作業はそのフェーズの中で完了させる。より前のフェーズへ戻るのは、重大な変更がその成果を無効化した場合に限り、要件変更検知を適用する。
オーケストレーターが scopeEvidence.affectedLayers から、機能が backend と frontend にまたがると判断した場合、単一のコードベース分析とDesign Docの区間を、以下のbackend先行・frontend後続の順序に置き換える。
標準のDesign Doc作成ステップをレイヤー別作成に置き換え:
| ステップ | エージェント | 目的 |
|---|---|---|
| 8 | codebase-analyzer | 確認済みのレイヤー横断スコープ全体を分析する。出典ソースは prd_path または requirements のちょうど1つを渡す |
| 9 | technical-designer | バックエンドDesign Doc（ステップ8のうちバックエンドに関係するエビデンスを使用） |
| 10 | code-verifier（Normalモード） | バックエンドDesign Docを既存コードに対して検証（結果JSONはステップ12にprior_layer_verificationとして渡す） |
| 11 | document-reviewer | バックエンドDesign Docをレビュー（ステップ10を実行した場合はverification_evidence、ステップ8のJSONはcodebase_analysisとして入力）。判定はレビュー対応の判定ゲートに従って処理する |
| 12 | technical-designer-frontend | フロントエンドDesign Doc（ステップ8のうちフロントエンドに関係するエビデンス、レビュー済みバックエンドDesign Doc、UI Spec、ステップ10を実行した場合のprior_layer_verificationを使用） |
| 13 | code-verifier（Normalモード） | フロントエンドDesign Docを既存コードに対して検証 |
| 14 | document-reviewer | フロントエンドDesign Docをレビュー（ステップ13を実行した場合はverification_evidence、ステップ8のJSONはcodebase_analysisとして入力）。判定はレビュー対応の判定ゲートに従って処理する |
| 15 | design-sync（Normalモード） | レイヤー間整合性検証の後、両モードでDesign Doc承認 [停止] |
ステップ8は1回だけ実行し、そのJSON全体を両方のdesignerがそのまま再利用する。各designerは自身のレイヤーに関係するエビデンスだけを使う。省略されないバックエンドのステップはステップ12の前に直列で完了させる。これによりフロントエンドdesignerは、レビュー済みのバックエンド契約と、検証が実行された場合はそのリポジトリ上の検証結果を受け取る。
Design Doc作成時のレイヤーコンテキスト指定:
maintained のレビュー issue のみを不安定な契約として扱う。UI Spec [パス] のコンポーネント構造を参照。対象: コンポーネント階層、状態管理、UI操作、データ取得。」design-sync: フロントエンドDesign Docをソースとして使用。docs/design/内の他のDesign Docを自動検出して比較。
レビュー済みDesign Docの全パスと、提供されたテストスケルトンのパスをwork-plannerに渡す。work-plannerは、選択済みの実装アプローチ、依存関係、最も早い実行可能な検証境界に従ってタスクを定義する。
自律実行中、タスクファイル名パターンに基づいてエージェントを選択する。この表は、作業計画書のタスクエントリが選ぶ2つの Executor lane も定義している:
| Executor lane | ファイル名パターン | Executor | Quality Fixer |
|---|---|---|---|
backend | *-task-* または *-backend-task-* | task-executor | quality-fixer |
frontend | *-frontend-task-* | task-executor-frontend | quality-fixer-frontend |
作業計画書のタスクエントリは lane をちょうど1つ記録する。タスクファイル生成時はその値をコピーし、対象パスからレイヤーを推論するのではなく、この表からファイル名を選ぶ。
自律実行モード開始後：
status: escalation_needed または status: blocked → 専門エージェントの結果の受理を適用requiresTestReview が true → integration-test-reviewer を実行status が needs_revision → レビュー対応を適用し、同じtask_fileとapplyのquality-issueオブジェクト一式を、correction_findingsとして逐語でルーティング先のexecutor（レイヤー別エージェントルーティング参照、task-executorまたはtask-executor-frontend）へ渡すstatus が blocked → 移動・リネームされた変更テストパスを解決してレビュアーを1回だけ再実行する。requiresTestReview: trueにもかかわらず変更されたテストが存在しない場合は、そのexecutor出力の欠陥をcorrection_findingsとしてルーティング先のexecutorに差し戻す。再実行でもblockedが返る場合はレビュー未実施を記録して、選択したモードの品質/コミット境界へ進むstatus が pass → 選択したモードの品質/コミット境界へ進む| トリガー | 対応 |
|---|---|
| 確認済みの成果、将来状態の要件、対象外を、ユーザーの選択なしには同時に維持できないことをエビデンスが示す | 要件変更検知を適用し、どれを変更するか確認する。 |
| 不可逆な外部操作に承認が必要 | 権限ゲートで承認を求める。 |
| 必要な実装が未完了 | リポジトリのエビデンスから前進できる作業を導ける間は続ける。それ以外は、未完了の内容と観測したエビデンスを報告して終了する。 |
| サブエージェントが環境または実行上の前提不足を報告 | 「専門エージェントの結果の受理」にある証明不足の回復と再試行を適用する。 |
| 要件が変わる | 上記の要件変更検知を適用する。task-decomposer開始後は影響するタスクを無効にする。要件変更によって承認済みの要件、契約、データフロー、検証戦略、タスク境界が成立しなくなる場合に限り、ドキュメント設計から再開する。 |
| ユーザーが停止または割り込む | 自律実行を停止する。 |
すべてのサブエージェントプロンプトに以下を含める:
エージェントのInput Parametersセクションと、フロー内のその時点で利用可能な成果物からプロンプトを構成する。
追加の2つのルール:
[placeholder] は Agent ツール呼び出し前にすべて具体値へ置換する#### 収束記録 → 引き継ぎ先エージェント
渡すもの: オーケストレーターが判定した convergence 記録を、引き継ぎ先エージェントへ渡す。内容は変更せず、各フィールドの readiness ラベルも一緒に渡す。
outcome は 成功基準 に、ユーザーが挙げた nonGoals は Out of Scope に残す。PRDには確認済みの要件と境界だけを残し、評価依頼、推測的なアイデア、未選択の実装手段は要件確認前の収束コンテキストに留めるRequirement Convergence へ記録し、weak-but-explicit のまま残ったフィールドも必ずそこへ残すnonGoals を受け取る。未選択の候補からUI Specの内容を作らないprototype_path がある場合は prototype_reference_strength も渡す。プロトタイプの表示に従って実装するなら binding、UI Specに記録した内容だけを実装へ渡すなら reference とする。ユーザーがプロトタイプについて述べた内容から判断し、どちらとも判断できない場合に限り確認するnonGoals は全タスクエントリから除外し、未選択の候補から計画上の作業を作らない。小規模では作業計画書を作らないため、weak-but-explicit のフィールドは保存プロトコルに従いオーケストレーター自身のコンテキストに留め、executorのプロンプトをブロックする項目にはしない#### codebase-analyzer → technical-designer
codebase-analyzerへの入力: 出典ソースちょうど1つ — 承認済みPRDが存在する場合はそのパス、存在しない場合は確認済み要件 technical-designerへの入力: codebase-analyzerのJSON出力をDesign Doc作成プロンプトの追加コンテキストとして渡す。必須の使い道:
focusAreas → Fact Disposition Tableの正典となるdisposition targetリスト（各focusAreaを1行に展開し、fact_idとevidenceをそのまま引き継ぐ）simplifications → 記録された条件が成立するエントリは新規実装の範囲を減らす材料として扱う。オーケストレーターはスコープ確認の停止点でその一覧を提示し、内容を変えずに渡すdataModel、dataTransformationPipelines、qualityAssurance → 「既存コードベース分析」「検証戦略」の各セクションに反映#### code-verifier → document-reviewer（Design Docレビュー）
code-verifierへの入力: Design Docパス（doc_type: design-doc）。code_pathsは指定を省略する — verifierがドキュメントからコードスコープを独自に発見する。 document-reviewerへの入力: 検証が実行された場合のみ、最新のcode-verifier結果と記録したレビュー対応の処理方針をあわせてverification_evidenceとして渡す。それ以外はこの入力を省略する。designerに渡したものと同じcodebase-analyzerのJSONをcodebase_analysisとして、出典ソースをconfirmed_requirement_contextとして常に渡す。該当する場合は元の依頼をrequirements_verbatimとして渡す。reviewerはcodebase_analysis.focusAreasでFact Disposition Tableのカバレッジを検証し、確認済み要件のコンテキストでドキュメントの成果と契約を検証する。
#### apply 対象の設計エビデンス finding → technical-designer
担当designerへの入力: 新規の update 呼び出しに、既存のDesign Docパスと、apply の処理方針だけを加えてそれ以外はそのままコピーした correction_findings 全体を渡す。承認済み要件、承認済みの決定、従来のエビデンス、影響を受けない設計コンテキストは既存成果物が保持するため、オーケストレーターが設計指示を追加しない。designer はレビューを起点とする範囲限定セルフ検証ゲートを適用し、確立済みのエビデンスに基づいて成果物を更新する。起点となった verifier または reviewer を再実行するのは、update が完了した場合だけとする。
#### code-verifier + document-reviewer → 次レイヤーのtechnical-designer（レイヤー横断フロー時のみ）
次レイヤーのtechnical-designerへの入力: レビュー済みの前レイヤーDesign Docパスを渡し、前レイヤーのcode-verifierを実行した場合のみprior_layer_verificationも渡す。シーケンスは「レイヤー横断オーケストレーション」セクションを参照。利用可能な検証discrepancyと前レイヤーのレビュー指摘を用いて不安定な契約を識別する。検証済みと見なせる主張は、実際のエビデンスが示すものに限定する。未検証の主張に設計が依存する場合は、フロントエンドDesign Docの「## Cross-Layer Assumptions」セクションに根拠と検証先を記載する。エスカレーションは、下流の検証ステップで依存を閉じられない場合のみ選ぶ。
#### technical-designer → work-planner
work-plannerへの入力: Design Docパス。work-plannerは出典セクションとACを実装タスクへマッピングする。選択済みなのにカバーされていない義務は修正すべき計画の漏れであり、作業計画書はカバー漏れや設計内容の不足をユーザー確認項目に変換しない。
#### *1 acceptance-test-generator → work-planner
acceptance-test-generatorへの入力: Design Doc のパス、UI Spec のパス（存在する場合）。
オーケストレーターの検証: generatedFiles[] の各パスがディスク上に存在すること。空のリストも有効な生成結果である。
work-plannerへの入力: 生成されたパス。work-plannerが各スケルトンを、実行可能になる最も早いタスクへ割り当てる。
passまたはverification_incompleteの結果が必要である。Liteモードのタスクコミットは、executorの結果と必要なテストレビューの結果を受理した後に行い、実装後レビューの前に最終品質チェックを実行する。コミットは呼び出したレシピが定めるポイントでのみ行う| Reviewer | 完了: 検出事項が空 | レビュー対応へ進む | Blocked |
|---|---|---|---|
| code-reviewer | verdictがpass | verdictがneeds-improvementまたはneeds-redesign | verdictがblocked → 専門エージェントの結果の受理を適用 |
| security-reviewer | statusがpass | statusがneeds_revision | statusがblocked → 専門エージェントの結果の受理を適用 |
レビュアーの検出事項は候補である。修正作業は、レビュー対応でapplyとなった集合からだけ作成する。
修正サイクルのハンドオフ: レビュー対応を適用し、そこで選ばれた各修正担当を呼び出す。authorが所有する技術成果物の修正では、レイヤーに応じたtechnical designerをupdateモードで呼び出し、その成果物に既存のdocument-reviewerと該当するdesign-syncのゲートを実行した後、起点のレビュアーを再実行する。executorが所有する修正では、レイヤーに応じたexecutorへ、元のtask_fileまたはdirect scopeのフィールドと、applyの検出事項オブジェクト一式に処理方針だけを加えたcorrection_findingsを逐語で渡し、その後、タスクサイクルのステップ2（条件付きのintegration-test-reviewerの経路を含む）でexecutorの結果に応じて分岐し、該当する品質ゲートを実行する。両方の担当が必要な場合は、レビュー対応にあるauthorを先に修正して再評価する順序に従う。prior_feedbackは照合を行うレビュアーにだけ渡す。
再実行ルール: レビュアーが返したpassingの結果はそのまま有効とする。再実行するのは、最新結果の検出事項に修正を適用したレビュアーだけとする。その際は記録した処理方針をprior_feedbackとして、再導出した実装ファイル一式とともに渡し、修正後の状態に対して照合させる。レビューの前提不足を回復した後は、そのレビュアーを再実行する。受け入れ可否はレビュー対応の収束条件で判断し、解決済みの却下を維持する。
references/review-resolution.md: 検出事項の処理方針、修正、収束references/lite-mode.md: Liteモードの呼び出し集合と最終品質チェック~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.