subagent-driven-development

サブエージェント主導の開発

タスクごとに新しい実装担当サブエージェントを割り当て、各タスクの後にタスクレビュー（仕様への準拠とコード品質）を実施し、最後にブランチ全体を包括的にレビューして計画を実行します。

サブエージェントを使う理由： 専門性のあるエージェントに、コンテキストを分離してタスクを委任できます。指示とコンテキストを正確に作成することで、エージェントの集中を保ち、タスクを成功させられます。エージェントに現在のセッションのコンテキストや履歴を引き継がせてはいけません。必要なものだけを用意します。これにより、調整作業に使う自分のコンテキストも確保できます。

基本原則： タスクごとに新しいサブエージェントを割り当てる ＋ タスクレビュー（仕様と品質）を行う ＋ 最後に包括的なレビューを行う ＝ 高品質かつ迅速な反復

進捗の説明： ツール呼び出しの合間に伝えるのは、短い一文までにします。記録は台帳とツールの実行結果に残ります。

継続的な実行： タスクの合間に人間のパートナーへ確認のために立ち止まってはいけません。以下に挙げる4つの理由に該当する場合、またはすべてのタスクが完了した場合を除き、計画のすべてのタスクを停止せずに実行します。「続けますか？」という確認や進捗の要約は時間の無駄です。相手は計画の実行を依頼したのですから、そのとおりに実行します。

停滞ではなく判断を。 実行中の計画を人間の返答待ちにしてはいけません。矛盾、曖昧さ、計画の不備、超過を求めようとした上限があれば、自分で判断します。仕様を最優先の基準とし、計画はその根拠と捉え、どちらにも答えがない場合は自分の判断で決定します。すべての判断を台帳にRuling: <what you decided> — <why> — <what it costs if wrong>の形式で記録し、作業を続けます。判断が誤っていれば、人間のパートナーが確認して取り消せる手戻りが生じます。一方、質問を保留したままセッションを止めると、相手の一日を無駄にし、何の価値も生みません。

作業を止めて確認を求めるべきなのは、次の4つの場合だけです。取り消し不能または破壊的な操作、セキュリティに関わる操作、この作業ツリーの外部で行う副作用のうち、通常は事前確認が必要なもの（マージ、共有ブランチへのプッシュ、公開など）、そして、どの進め方を選んでも推測に頼らざるを得ないほど計画に重大な不備がある場合です。それ以外は停止せずに進めます。

使用する場面

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Partner chose inline, or no subagent tool?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Partner chose inline, or no subagent tool?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Partner chose inline, or no subagent tool?" -> "executing-plans" [label="yes"];
    "Partner chose inline, or no subagent tool?" -> "subagent-driven-development" [label="no"];
}

インラインで計画を実行する場合との比較：

• すべてのタスクを1つのコンテキストで実行する代わりに、タスクごとに新しいサブエージェントを割り当てるため、コンテキストが汚染されません
• 最後だけでなく、各タスクの後にレビューを行い、仕様への準拠とコード品質を確認します
• タスクとレビューのたびに新しいコンテキストを使います。インライン方式では1つのコンテキストと最後のレビュアーだけで済みます
• どちらの方式でもこのセッション内で実行し、同じ計画ワークスペースと台帳を共有し、タスクの合間に停止しません

プロセス

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer implements, tests, commits, self-reviews" [shape=box];
        "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
        "Spec ✅ and quality approved?" [shape=diamond];
        "Finding conflicts with plan text?" [shape=diamond];
        "Rule on the conflict, ledger the ruling" [shape=box];
        "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
        "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
        "All findings addressed?" [shape=diamond];
        "R = 5?" [shape=diamond];
        "Adjudicate each open finding" [shape=box];
        "Any load-bearing finding?" [shape=diamond];
        "Rule and continue; stop only if every path forward is a guess" [shape=box];
        "Park findings in ledger with rulings" [shape=box];
        "Append completion to ledger, mark todo complete" [shape=box];
    }

    "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
    "Final review clean: delete this plan's workspace" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
    "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
    "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
    "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
    "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
    "Spec ✅ and quality approved?" -> "Append completion to ledger, mark todo complete" [label="yes"];
    "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
    "Finding conflicts with plan text?" -> "Rule on the conflict, ledger the ruling" [label="yes"];
    "Rule on the conflict, ledger the ruling" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
    "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
    "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
    "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
    "All findings addressed?" -> "Append completion to ledger, mark todo complete" [label="yes"];
    "All findings addressed?" -> "R = 5?" [label="no"];
    "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
    "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
    "Adjudicate each open finding" -> "Any load-bearing finding?";
    "Any load-bearing finding?" -> "Rule and continue; stop only if every path forward is a guess" [label="yes"];
    "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
    "Park findings in ledger with rulings" -> "Append completion to ledger, mark todo complete";
    "Append completion to ledger, mark todo complete" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
    "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
    "Final review clean: delete this plan's workspace" -> "Use superpowers:finishing-a-development-branch";
}

セットアップ

作業は必ず隔離されたワークスペースで行ってください。superpowers:using-git-worktrees を使って作成するか、既存のワークスペースを確認してください。 人間のパートナーから明示的な同意を得ずに、main/master ブランチで実装を開始してはいけません。

会話の記憶はコンテキストの圧縮後には保持されません。実際のセッションでは、作業の進捗を見失ったコントローラーが、すでに完了したタスクの一連の作業全体を再度割り当てることがあります。これは、これまでに確認された失敗の中で最も大きなコストを伴うものです。TODO だけでなく、台帳ファイルで進捗を管理してください。

• 各計画は専用のワークスペースを持ちます。スキルの開始時に、このスキルの bash scripts/sdd-workspace PLAN_FILE を実行してください。計画に必要なすべての成果物（台帳、ブリーフ、レポート、レビュー用パッケージ）を格納する、Git の追跡対象外ディレクトリ（<repo-root>/.superpowers/sdd/ の下）が表示されます。別の計画のディレクトリを読み書きしてはいけません。
• <workspace>/progress.md にこの計画の台帳があるか確認してください。先頭行に計画ファイルが記載されている場合、Task <N>: complete の行があるタスクは完了済みです。再度割り当てず、まだその行がない最初のタスクから再開してください。最後の行が修正ラウンドであるタスクは、ループの途中です。次のラウンドから再開してください。台帳の先頭行に別の計画ファイルが記載されている場合、または旧来のフラットなパス .superpowers/sdd/progress.md に台帳がある場合は、それは別の計画の進捗です。そのまま残し、この計画用に新しい台帳を作成してください。
• 台帳は、識別情報を先頭行に記載して作成してください。 # SDD ledger — plan: <plan file path>.
• 台帳は復旧用の記録です。台帳に記載されたコミットは、作成したことをコンテキストが覚えていなくても Git に存在します。コンテキスト圧縮後は、自分の記憶より台帳と git log を信頼してください。
• git clean -fdx を実行すると、ワークスペース（Git の追跡対象外の作業用領域）が削除されます。その場合は git log から復旧してください。

計画を一度読み、背景情報と全体的な制約を確認して、タスクごとに TODO を作成してください。計画に仕様書が記載されている場合は、それも読んでください。仕様書は計画が根拠とする基準であり、計画内で矛盾がある場合は仕様書を優先します。参照できる仕様書がない計画については、その旨を台帳に記載してください。仕様書なしで下した判断は暫定的なものです。

Task 1 を割り当てる前に、計画を一度確認して矛盾を洗い出し、確認した内容をその都度書き留めてください。

• タスク同士、またはタスクと計画の全体的な制約との矛盾
• 計画で明示的に求められているものの、レビューの評価基準では不備とみなされる事項（何も検証しないテスト、ロジックブロックの逐語的な重複など）

確認結果は結論ではなく、表にしてください。ファイルまたはインターフェースを共有するタスクの組み合わせごとに、各タスクが生成するものと、もう一方のタスクが利用するもの、そして確認結果を1行ずつ記載します。さらに各タスクについて、タスクの記述に矛盾がないかを1行ずつ記載します。具体的には、指定されたテストとコードの整合性、および作成するファイルと後で変更するファイルの整合性を確認します。これらの行を記載せずに「確認で問題はありませんでした」とするのは、確認を実施したことにはなりません。

表を台帳に記録してください。実行を始める前に、計画の記述を根拠として、見つかったすべての事項について判断し、その判断も台帳に記録してください。確認で問題がなければ、コメントせずに進めてください。見つかった矛盾はそれぞれ、仕様書を拘束力のある基準、計画をその解釈として判断し、該当する行の横に記録してから Task 1 を割り当ててください。実装中に初めて生じる矛盾は、レビューのループで対処します。

モデルの選択

コストを抑え、速度を上げるため、それぞれの役割をこなせる範囲で最も能力の低いモデルを使います。

機械的な実装タスク（独立した関数、明確な仕様、1〜2 ファイル）：高速で低コストのモデルを使います。計画が十分に明確であれば、実装タスクの大半は機械的な作業です。

統合や判断が必要なタスク（複数ファイルの調整、パターン照合、デバッグ）：標準的なモデルを使います。

アーキテクチャや設計のタスク：利用可能な中で最も高性能なモデルを使います。 最終的なブランチ全体のレビューもこれに該当します。セッションのデフォルトではなく、利用可能な中で最も高性能なモデルに割り当ててください。

レビュータスク：変更差分の規模、複雑さ、リスクに応じて、同じ判断基準でモデルを選びます。小規模で機械的な変更差分に最も高性能なモデルは不要ですが、微妙な並行処理の変更には必要です。小規模な修正差分を対象とする範囲限定の再レビューには、低〜中位のモデルを使います。

修正ループのエスカレーション（4〜5 ラウンド目）：行き詰まった実装担当より、少なくとも 1 段階上のモデルを使います。

サブエージェントにタスクを割り当てる際は、必ずモデルを明示してください。 モデルを省略すると、セッションのモデルが引き継がれます。多くの場合、最も高性能で最も高コストのモデルが選ばれ、このセクションの意図が気づかないうちに損なわれます。

トークン単価よりターン数を重視してください。 サブエージェントのターン数に応じて、実時間とコンテキストのコストが増加します。低価格モデルは複数ステップの作業でターン数が通常の 2〜3 倍になるため、結果として全体のコストが高くなることがあります。レビュー担当者や、文章による説明に基づいて作業する実装担当者には、中位モデルを最低ラインとして使います。タスクの計画に実装するコードがすべて含まれている場合、実装は転記とテストにあたるため、その実装担当者には最も低価格のモデルを使います。単一ファイルの機械的な修正にも、最も低価格のモデルを使います。

タスクの複雑さを示す要素（実装タスク）：

• 完全な仕様があり、対象が 1〜2 ファイル → 低価格モデル
• 複数ファイルにまたがり、統合上の考慮事項がある → 標準モデル
• 設計上の判断や、コードベース全体への深い理解が必要 → 最も高性能なモデル

タスクの進め方

同じ種類の小規模な作業はまとめてください。 計画に、同じ一行修正、定数の変更、フィールドの追加など、同種の小規模で独立した編集が複数含まれている場合、タスクごとにサブエージェントを割り当てないでください。すべてのファイルと変更内容を列挙した作業指示を 1 つ作成し、まとめて 1 つのサブエージェントに割り当て、その差分全体をひとまとまりとしてレビューします。個別の判断、テスト、レビュー対象が必要な作業に限り、タスクごとに割り当ててください。

割り当て用プロンプトに貼り付けたものも、サブエージェントが出力したものも、セッションの残りの間はコンテキストに保持され、その後のすべてのターンで再読されます。成果物はファイルとして受け渡してください。

割り当てたサブエージェントの応答を待つとき： 短いタイムアウトで待機インターフェースを何度も確認したり、無言のまま期限のない待機を続けたりしないでください。手元でできる作業（台帳の更新、次のレビューの準備、報告書の確認など）がある間は作業を続けてください。子エージェントの結果は自動的に届きます。実際に待機する必要があるときは、可能な環境では 5〜10 分の範囲で待機し、その間にステータスを 1 行投稿して、実行中の子エージェントを確認してください。子エージェントを一覧表示し、完了したのに報告していないものがあれば、その結果を確認します。一定時間ごとの待機にすることで、長時間の待機の効率をほぼ維持しながら、停止したり結果が失われたりした子エージェントをセッションの終わりではなく数分以内に見つけられます。

1. 実装担当者を割り当てる

割り当てる前に BASE（git rev-parse HEAD）を記録してください。レビュー用パッケージと修正ラウンドの差分で必要になります。

• タスク概要： 実装担当者を割り当てる前に、このスキルの bash scripts/task-brief PLAN_FILE N を実行してください。タスクの全文を一意の名前のファイルに抽出し、そのパスを出力します。要件の唯一の情報源として概要が保たれるように、割り当て内容を作成してください。割り当てには、次の内容を含めてください。（1）このタスクがプロジェクトのどこに当てはまるかを示す1行、（2）「まずこれを読んでください — 要件と、逐語的に使用する正確な値が記載されています」という導入文を添えた概要のパス、（3）概要では把握できない、以前のタスクで決定したインターフェースや判断、（4）概要で気付いた曖昧さへの対応、（5）レポートファイルのパスとレポートの要件。正確な値（数値、マジック文字列、シグネチャ、テストケース）は概要にのみ記載してください。サブエージェントに計画ファイル全体を読ませてはいけません。
• レポートファイル： 実装担当者のレポートファイルは概要にちなんだ名前にしてください（概要が …/task-N-brief.md なら、レポートは …/task-N-report.md）。割り当てプロンプトにそのパスを記載してください。実装担当者はそこに完全なレポートを書き、ステータス、コミット、テストの概要1行、懸念事項のみを返します。
• 割り当てプロンプトでは、セッションの経緯ではなく、1つのタスクを説明してください。以前のタスクの要約を蓄積したもの（「タスク1～3の後の状態」など）を、後続の割り当てに貼り付けてはいけません。実際のセッションでは、貼り付けた履歴が99％を占める42,000文字の割り当てが発生しました。新しいサブエージェントに必要なのは、対象タスク、関連するインターフェース、全体的な制約だけです。それ以外は不要です。
• 割り当てには、実装担当者向けテンプレートに記載されているサブエージェント禁止の契約を含めてください。実装担当者はサブエージェントを割り当ててはいけません。補助担当者もレビュアーも割り当ててはいけません。レビューはレポートの提出後に、あなたが行います。実際のセッションでは、作業者が起動したレビュアーは、コントローラーが割り当てたタスクレビューを重複して行い、タスクごとにレビュー担当が余分に1名必要になりました。
• 以前のタスクで、今回のタスクが触れる領域に関する指摘が保留されている場合は、その台帳エントリへの参照を割り当てに含めてください。
• 割り当て結果から実装担当者のエージェント ID を記録してください。修正ループの第1～3ラウンドでは、このエージェントを再開します。
• 複数の実装サブエージェントを同時に割り当ててはいけません（競合を防ぐため）。

テンプレート：implementer-prompt.md

2. レポートに対応する

実装担当のサブエージェントは、次の4つのステータスのいずれかを報告します。それぞれ適切に対応してください。

DONE： レビューパッケージを生成し（このスキルのディレクトリから bash scripts/review-package PLAN_FILE BASE HEAD を実行します。書き込んだ一意のファイルパスが出力されます。BASE には実装担当者の割り当て前に記録したコミットを指定してください。HEAD~1 は、複数コミットのタスクで最後のコミット以外をすべて黙って除外してしまうため、絶対に使用しないでください）、出力されたパスをタスクレビュアーに渡してください。

DONE_WITH_CONCERNS： 実装担当者は作業を完了しましたが、懸念を示しています。先に懸念事項を確認してください。正しさやスコープに関する懸念であれば、レビューに進む前に対処してください（「このファイルは大きくなってきている」などの所見であれば、記録してレビューに進んでください）。

NEEDS_CONTEXT： 実装担当者は、提供されていない情報を必要としています。不足している情報を提供し、再割り当てしてください。

BLOCKED： 実装担当者は作業を完了できません。ブロッカーを評価してください。

1. コンテキスト不足が原因であれば、情報を追加して同じモデルに再割り当てします。
2. タスクにより高度な推論が必要であれば、より高性能なモデルに再割り当てします。
3. タスクの規模が大きすぎる場合は、より小さなタスクに分割します。
4. 計画自体に誤りがある場合は、修正方針を決定して台帳に記録し、その決定内容を割り当てに含めて再割り当てします。

エスカレーションを無視したり、変更を加えずに同じモデルへ再試行させたりしてはいけません。実装担当者が行き詰まったと報告した場合は、何かを変更する必要があります。

実装担当者から質問があった場合は、作業の開始前でも途中でも、明確かつ十分に回答し、必要に応じて追加のコンテキストを提供してください。実装を急がせてはいけません。

3. タスクをレビューする

タスクごとのレビューは、タスク単位で適用されるゲートです。包括的なレビューは、ブランチ全体の最終レビューで一度だけ行います。タスクレビューを決して省略せず、どちらかの判定が欠けている報告は決して受け入れないでください。仕様への準拠とタスクの品質の両方が必要です。実装者による自己レビューはタスクレビューの代わりにはなりません。両方が必要です。

• レビュアーには差分をファイルとして渡します。このスキルの bash scripts/review-package PLAN_FILE BASE HEAD を実行し、出力されたファイルパスを レビュアーに渡してください（bash を使わない場合は、対象範囲の git log --oneline、git diff --stat、 git diff -U10 を、リダイレクトして一意の名前を付けた 1 つの ファイルにまとめます）。出力があなた自身のコンテキストに入ることはなく、レビュアーはコミット一覧、統計情報の概要、コンテキスト付きの完全な差分を、1 回の Read 呼び出しで確認できます。実装者に作業を割り当てる前に記録した BASE を使ってください。複数コミットのタスクを気付かれないまま途中で切り詰めてしまう HEAD~1 は決して使わないでください。差分ファイルなしでタスクレビュアーに作業を割り当ててはいけません。
• レビュアーへの入力： タスクレビュアーには、同じ概要ファイル、報告ファイル、レビュー用パッケージの 3 つのパスに加え、そのタスクに適用される全体的な制約を渡します。
• レビュアーに渡す全体制約ブロックは、注意を向ける対象を示すものです。プランの Global Constraints セクションまたは仕様から、拘束力のある要件をそのままコピーしてください。具体的な値、形式、コンポーネント間の関係（「X と同じレイアウト」、「Y と一致」）を正確に含めます。レビュアーのテンプレートにはすでにプロセス上のルール（YAGNI、テストの衛生、レビュー方法）が含まれています。制約ブロックには、このプロジェクトの仕様が求める内容を記載してください。
• 具体的でタスク固有の理由がない限り、「すべての使用箇所を確認する」や「必要ならレーステストを実行する」といった、範囲の曖昧な指示を追加しないでください。
• 実装者が同じコードに対してすでに実行したテストを、レビュアーに再実行するよう求めないでください。テストの証拠は実装者の報告に記載されています。
• レビュアーの指摘を先回りして判断しないでください。特定の問題を無視する、または指摘しないようレビュアーに指示してはいけません。指摘が誤検出だと思う場合は、レビュアループでレビュアーに指摘させたうえで判断してください。作成中のプロンプトに「指摘しないでください」、「X を欠陥と見なさないでください」、「重大度は Minor 以下にしてください」、「プランで選択した」といった文言が含まれている場合は、いったん止めてください。先回りした判断であり、通常はレビューループを避けるためのものです。

タスクレビュアーが「⚠️ 差分からは検証できません」と報告することがあります。これは、変更されていないコード内にある要件や、複数タスクにまたがる要件を指します。これらは残りのレビューを妨げませんが、タスクを完了とする前に、それぞれ自分で解決する必要があります。レビュアーにはない、プランとタスク間の文脈をあなたは把握しているためです。実際の不備だと確認した場合は、仕様レビューの不合格として扱い、他の指摘とともに修正ループに含めてください。

テンプレート：task-reviewer-prompt.md

4. 修正ループ

レビューで仕様 ❌、Critical または Important の指摘、あるいは実際の不備だと確認した ⚠️ 項目が報告された場合、修正ループが開始されます。

ループの開始前に、ループを即座に終了する 2 つの方法があります。

• Minor の指摘は、進捗台帳に随時記録してください （Task <N>: minor (deferred): <one-liner>）。また、ブランチ全体の最終レビューで、マージ前に修正が必要なものを振り分けられるよう、その一覧を参照先として示してください。誰も確認しない集約リストは、気付かれないまま破棄されます。Minor の指摘がループに入ることはありません。
• プランで必須とされている指摘、またはプランの記述に矛盾する指摘については、自分で判断します。プランの文面に照らして指摘を評価し、仕様を拘束力のある基準として判断したうえで、対応する前にその判断を台帳に記録してください。プランで必須とされていることを理由に指摘を退けてはいけません。また、記録された判断なしに、プランと矛盾する修正を指示してはいけません。

それ以外はすべてループに入ります。修正ラウンドは、修正の割り当て 1 回と、対象を限定した再レビュー 1 回で構成されます。タスクごとに最大 5 ラウンドです。 ラウンド 1～3 — 元の実装者を再開します。 未解決の指摘をそのまま送ります。コンテキストは保持されており、タスク、コード、実装時の判断を把握しています。ハーネスから稼働中のサブエージェントに再度メッセージを送れない場合は、ブリーフのパス、レポートファイルのパス、指摘を引き継いだ新しい実装者をディスパッチします。いずれの場合も、レポートファイルが永続的なメモリーになります。

ラウンド 4～5 — より高性能なモデルを使い、新しい実装者をディスパッチします（「モデルの選択」に従います）。ブリーフのパス、レポートファイルのパス、未解決の指摘を渡し、次の説明を添えます。「前の実装者はこのタスクを[N]回試みました。今度はあなたが担当します。試した内容についてはレポートファイルを読んでください。」3回の再開を経てもループが続く場合、実装者が自分の問題を把握できていない可能性が高いため、新たな視点とモデルの性能向上を一度に取り入れます。

どのラウンドでも共通: 実装者は修正を行い、修正したコードを対象とするテストを再実行し、同じレポートファイルに修正レポートを追記して、簡潔な契約を返します。レビュー担当者を再ディスパッチする前に、修正レポートに対象テスト、実行したコマンド、その出力が記載されていることを確認します。3つすべてがそろったら、再レビューをディスパッチします。修正メッセージには対象テストファイル名を記載します。1行の修正であれば、テストスイート全体を実行する必要はありません。

再レビューの範囲は限定されます。 bash scripts/review-package PLAN_FILE FIX_BASE HEAD を実行します。FIX_BASE は前回のレビューで確認された HEAD です。また、指摘一覧、ブリーフ、レポートファイル、出力された差分のパスとともに、re-review-prompt.md をディスパッチします。再レビュー担当者は各指摘を ADDRESSED または NOT ADDRESSED と判定し、修正差分内で発生した新たな不具合のみを指摘します。修正差分内の新たな Critical／Important の不具合は、未解決の指摘一覧に追加します。範囲外の所見は、延期する軽微な問題として台帳に記録します。これによってループを延長することはありません。

**各ラウンドの後、**台帳に次を追記します。 Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)

コントローラーのセッションでは、指摘を自分で修正しないでください。コンテキストを調整に集中させ、コントローラーによる修正がレビューを経ずに済んでしまうことを防ぎます。

打ち切り時の判断。 ラウンド 5 の再レビュー後も指摘が残っている場合は、ディスパッチを停止します。プランとタスク横断のコンテキストを持ち、レビュー担当者にはない情報を把握しているあなた自身が、未解決の指摘をそれぞれ判断します。

• レビュー担当者の指摘が誤り、または見解が分かれる点である場合: 保留にします。 Task <N>: parked — <finding> — Ruling: <why the code stands> 最終レビューでは、双方の見解が確認されます。
• 指摘は正しいが、後続の作業に影響しない場合: 同じ形式で保留にし、正しい指摘だが対応は延期すると判断した旨を記録します。
• 指摘が正しく、後続の作業の前提となる場合（後続タスクがそれを基に構築される場合、またはプランの欠陥が明らかになった場合）: 依存する作業の妨げを取り除く最小限の変更を判断し、次の形式で台帳に記録します。 Task <N>: Ruling: <finding> — <what you decided and why> そのうえで、次のタスクのディスパッチに引き継ぎます。構造的な不具合を黙って保留にすると、依存するすべてのタスクがその不具合の上に構築されてしまいます。すべての進行経路が推測に頼らざるを得なくなる場合にのみ停止します。

上限に達した場合に限り、判断を下してください。ループを終わらせるために早い段階で判断を下すのは、別の名目で先走って決めつけることです。判断はすべて台帳に記録してください。黙って破棄することは禁止です。

5. タスクを完了する

レビューで問題がなくなった場合、または上限に達した時点で未解決の指摘すべてが判断付きで保留になった場合は、他の記録と同じメッセージで、台帳に完了行を追記します。

• Task <N>: complete (commits <base7>..<head7>, review clean)
• 打ち切り後の場合: Task <N>: complete (commits <base7>..<head7>, <K> parked)

その後、ToDo を完了として次に進みます。Critical／Important の未解決問題が修正されるか、上限に達した時点で判断付きで保留されるまでは、次のタスクに進んではいけません。

最終レビュー

ブランチ全体の最終レビューにもパッケージを用意します。次を実行し、 bash scripts/review-package PLAN_FILE MERGE_BASE HEAD（MERGE_BASE はブランチの開始元のコミットです。例：git merge-base main HEAD）、出力されたパスを最終レビューのディスパッチに含めてください。これにより、最終レビュアーは git コマンドでブランチの差分を再導出せずに、1 つのファイルを読むだけで済みます。利用可能な最も高性能なモデルを使ってディスパッチし（モデルの選択を参照）、superpowers:requesting-code-review の code-reviewer.md を使用します。台帳の保留中の軽微な項目と先送りした項目を示し、マージ前にどれを修正すべきかトリアージできるようにしてください。

ブランチ全体の最終レビューで指摘事項が返された場合は、指摘事項ごとに修正サブエージェントを立てるのではなく、指摘事項の完全な一覧を渡して修正サブエージェントを 1 つだけディスパッチしてください。 指摘事項ごとに修正担当を立てると、そのたびにコンテキストを再構築し、テストスイートを再実行することになります。実際のセッションでは、最終レビューの修正ラウンドにかかったコストは、すべてのタスクを合わせたコストを上回りました。 その後、修正ラウンドの範囲に対して、範囲を限定した再レビューをちょうど 1 回だけ実行します （修正範囲に対して bash scripts/review-package PLAN_FILE FIX_BASE HEAD を実行します。 re-review-prompt.md）。 残った指摘事項は、タスクループのブレーカーと同様に裁定します。判断内容を記して先送りするか、重要な指摘事項について判断し、決定内容を台帳に記録してください。ここで止めるのは、上記の 4 つのクラスだけです。2 回目の修正ラウンドはありません。残った重要な指摘事項は、finishing-a-development-branch が選択肢を提示する際に、人間のパートナーに明らかにされます。

完了

何かを削除する前に、Ruling: を含む台帳のすべての行を集めてください。事前確認での判断、先送りした指摘事項、ブレーカーでの裁定など、すべてが対象です。それらを、判断した順に、それぞれ誤っていた場合のコストとともに、「私が下した判断」という見出しの下に最終メッセージとして記載します。この一覧に漏れがあってはいけません。台帳に判断があれば、一覧にも必ず記載してください。人間のパートナーに代わって下した決定が相手に伝わるのは、この一覧だけです。相手はこれを読み、誤った判断があれば修正します。作業環境とともに消えてしまう判断は、秘密裏に下された判断です。

ブランチ全体の最終レビューで問題がなく、修正もマージされたら、この計画の作業環境を削除します（rm -rf <workspace>）。これ以降は git の履歴が記録になります。 他の計画に属する兄弟ディレクトリには触れないでください。

superpowers:finishing-a-development-branch を使用してください。

よくある正当化

言い訳	実際
「仕様への準拠は十分でしょう」	レビュアーが仕様上の不足を見つけたなら、完了ではありません。修正するか上限に達して裁定するか、それ以外に終了方法はありません。
「自分で直せばいい。ディスパッチは手間がかかる」	コントローラーが修正するとコンテキストが汚染され、レビューも省略されます。実装担当を再開してください。
「もう 1 回やれば収束する」	上限を超えた後は、ラウンドを重ねても収束しません。失敗は構造的なものです。裁定して振り分けてください。
「レビュアーはどうせまた何か新しいことを見つける」	範囲を限定した再レビューは修正を検証するもので、範囲外に広がることはありません。未変更のコードに関する新たな指摘事項は、ループではなく台帳に記録します。
「この指摘は明らかに間違いだから、無視しておこう」	裁定するのは上限に達したときだけです。また、判断はすべて台帳のエントリーになります。黙って破棄することは禁止されています。
「修正は小さかったから、再レビューは省こう」	未レビューの修正が回帰を引き起こします。すべてのラウンドの最後に、範囲を限定した再レビューを行います。
「レビューでループが遅くなる」	レビューなしのループは、検証されない変更を繰り返すだけです。レビューはループのブレーキであり、舵取り役です。
「台帳の記録は余計な手間だ」	圧縮後にも残るのが台帳です。台帳のないコントローラーは、完了済みのタスク手順全体を再ディスパッチすることになります。
「実装担当が自分でレビュアーを起動した。追加の保証が無料で得られる」	同じ差分をレビューする重複した担当者です。タスクレビューがゲートになります。ワーカーが起動したレビュアーは、厳密さではなく、指摘すべき不備です。

ワークフローの例

You: I'm using Subagent-Driven Development to execute this plan.

[Setup: worktree verified]
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Resolve workspace: bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Create todos for all tasks]

Task 1: Hook installation script

[Run task-brief for Task 1; dispatch implementer with brief + report paths + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: [Later]
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
Task reviewer: Spec ✅ - all requirements met, nothing extra.
  Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.

[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]

Task 2: Recovery modes

[Run task-brief for Task 2; dispatch implementer with brief + report paths + context]

Implementer: [No questions]
  - Added verify/repair modes
  - 8/8 tests passing
  - Committed

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
Task reviewer: Spec ❌:
  - Missing: Progress reporting (spec says "report every 100 items")
  Issues (Important): Magic number (100)

[Fix round 1: resume the implementer with both findings]
Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
  Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.

[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
  Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
  Verdict: all findings addressed.

[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]

...

[After all tasks]
[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
Final reviewer: All requirements met. Deferred minors triaged: none block merge.

[Delete this plan's workspace — the record now lives in git]

Done! Using superpowers:finishing-a-development-branch.