subagent-driven-development

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

タスクごとに新しいサブエージェントを割り当てて計画を実行し、各タスクの後に2段階のレビューを行います。まず仕様への準拠を確認し、次にコードの品質を確認します。

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

基本原則： タスクごとに新しいサブエージェントを割り当て、仕様確認、品質確認の2段階でレビューすることで、高品質な成果を素早く反復できます。

継続的な実行： タスクの合間に作業を止めて人間のパートナーに確認を求めないでください。計画の全タスクを中断せずに実行します。停止するのは、以下に挙げる4つの条件に当てはまる場合か、すべてのタスクが完了した場合のみです。「続けてもよいですか？」という確認や進捗の要約は、相手の時間を無駄にします。計画の実行を依頼されたのですから、実行してください。

停止ではなく判断を。 実行中の計画を人間の判断待ちにしてはいけません。矛盾、曖昧さ、計画の不備、あるいは超過を確認しようとしていた上限があれば、自分で判断します。仕様を最優先の基準とし、計画は仕様に対する解釈として扱い、どちらからも答えが得られない場合は自分の判断を下します。判断を誤れば、人間のパートナーが確認して元に戻せる手戻りが発生します。質問をしたままセッションを止めれば、相手の一日を奪うだけで何も得られません。

停止して確認を求めるのは、次の4つの場合のみです。取り消せない操作や破壊的な操作、セキュリティに関わる操作、一般に事前確認が必要とされる、この作業ツリーの範囲外への副作用（マージ、共有ブランチへのプッシュ、公開など）、そしてどの方法を選んでも推測に頼らざるを得ないほど計画が破綻している場合です。

使用するタイミング

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [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?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

「計画の実行」（並行セッション）との違い：

• 同じセッションで実行（コンテキストの切り替えなし）
• タスクごとに新しいサブエージェントを割り当て（コンテキストの混入なし）
• 各タスクの後に2段階のレビューを実施：まず仕様への準拠を確認し、次にコードの品質を確認
• タスクの合間に人間の確認を挟まないため、反復が速い

プロセス

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, TaskUpdate: mark task completed" [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-extended-cc: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, TaskUpdate: mark task completed" [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, TaskUpdate: mark task completed" [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, TaskUpdate: mark task completed";
    "Append completion to ledger, TaskUpdate: mark task completed" -> "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-extended-cc:finishing-a-development-branch";
}

セットアップ

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

会話の記憶は、コンパクション後には保持されません。実際のセッションでは、作業箇所を見失ったコントローラーが、完了済みのタスク一式を再度割り当ててしまうことがあります。これは、確認されている中で最もコストの高い失敗です。進捗はタスクリストだけでなく、台帳ファイルにも記録してください。

• 各プランはそれぞれ専用のワークスペースを持ちます。スキルの開始時に、このスキルの scripts/sdd-workspace PLAN_FILE を実行します。プランの Git 除外対象ディレクトリ （<repo-root>/.superpowers/sdd/<plan-basename>/）が出力されます。ここには、このプラン専用の すべての成果物（台帳、ブリーフ、レポート、レビュー用パッケージ）が置かれます。 別のプランのディレクトリを読み書きしてはいけません。
• このプランの台帳が <workspace>/progress.md にあるか確認します。1 行目にこのプランファイルの 名前があれば、Task <N>: complete の行があるタスクは完了しています。再度ディスパッチせず、 その行がない最初のタスクから再開します。最後の行が修正ラウンドを示すタスクはループの途中です。 次のラウンドからループを再開します。1 行目に別のプランファイルの名前がある台帳、または以前の フラットなパス .superpowers/sdd/progress.md に残っている台帳は、別のプランの進捗です。 そのまま残し、自分用の新しい台帳を作成します。
• 台帳の最初の行には、その識別情報を記載します。 # SDD ledger — plan: <plan file path>。
• 台帳は復旧マップです。台帳に記載されたコミットは、作成した記憶がコンテキストから失われても Git に存在します。コンテキストが圧縮された後は、自分の記憶より台帳と git log を信頼します。
• git clean -fdx を実行すると、Git 除外対象の作業用ディレクトリであるワークスペースが 削除されます。その場合は git log から復旧します。
• 台帳に記録するのは状態であり、推論ではありません。記載するのは、このスキルで定められた 1 行形式（dispatch、fix round、complete、minor、parked、BLOCKED）です。1 つのイベントにつき 1 行とし、3 行まで記載できるのは parked の裁定のみです。手法の説明、レビュアーへの称賛、 自己修正についての長文、以前の記載事項の言い直しは書きません。余分な行は、後続のターンごとに 読み直すことになります。自分の作業プロセスに関する教訓は状態ではありません。最終レポートに 記載して人間のパートナーに伝えてください。Finish 時にこのファイルを含むワークスペースは 削除されるため、ここに書いた内容はすべて一緒に消えます。
• 台帳への追記には Edit ツールではなく、シェルの追記 （cat >> progress.md <<'EOF'）を使います。Edit はファイルの成長に伴って長くなる アンカーテキストを再送し、追記のたびに権限確認を表示するためです。

プランを一度読み、コンテキストと Global Constraints を確認します。プランに Spec が記載されている 場合は、それも読みます。Spec はプランが根拠とする権威ある文書であり、プラン内の矛盾は Spec に 照らして解決します。参照可能な Spec がないプランでは、その旨を台帳に記録します。Spec なしで 行う裁定は暫定的なものです。

Task 1 をディスパッチする前に、プランを一度確認して、矛盾の有無を調べながら確認内容を 記録します。

• 相互に矛盾するタスク、または Global Constraints と矛盾するタスク
• プランが明示的に必須としている内容のうち、レビュー基準で欠陥とされるもの （何も検証しないテスト、ロジックブロックの逐語的な重複など）

確認結果は判定ではなく表にします。同じファイルまたはインターフェースを共有するタスクの 各組について、1 行ずつ記載します。2 つのタスクと、一方が生成し他方が消費するもの、 確認結果を記載します。また、各タスクについても 1 行ずつ記載します。タスク内の記述に 一貫性があるか、具体的には、指定されたテストと指定されたコードの整合性、作成するファイルと 後で操作するファイルの整合性を記載します。各行がないまま「確認に問題なし」としても、 確認を実施したことにはなりません。

表を台帳に記録します。実行を始める前に、見つかったすべての事項について、必須としている プランの記述と照らして裁定し、その裁定を台帳に記録します。確認で何も見つからなければ、 コメントなしで次に進みます。見つかった矛盾はそれぞれ裁定します。Spec が拘束力のある権威であり、 プランはその根拠を示すものです。裁定を該当する行の横に記録し、各プランタスクについて、全文を 含むタスクを TaskCreate で作成します。

メタデータを使用したディスパッチ

実装担当のサブエージェントをディスパッチする場合：

1. TaskGet を使ってタスクの説明を読みます。メタデータは末尾の json:metadata コードフェンスに埋め込まれています
2. メタデータ JSON を解析し、各フィールド（files、acceptanceCriteria、verifyCommand）を実装担当者向けプロンプトの各セクションに割り当てます
3. 実装担当者には構造化データをすべて渡します。文章から解析させないでください
4. ユーザー確認が必要なタスクでは、計画で決定済みの内容を再検討しないでください。計画後に重要な条件の変化（異なるフィクスチャ／ブランチ、新たなブロッカー、計画の前提の破綻）がない限り、決定済みの検証内容を記載どおりにディスパッチします。条件が変わっていないのに決定済みの方針を再確認するのは、確認ゲートの回避です。

モデルの選択

コストを抑え、速度を上げるために、各役割を担える範囲で最も能力の低いモデルを使用します。

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

統合と判断を伴うタスク（複数ファイルの調整、パターン照合、デバッグ）：標準モデルを使用します。

アーキテクチャ、設計、レビューのタスク：利用可能な中で最も高性能なモデルを使用します。

レビュータスク：差分のサイズ、複雑さ、リスクに応じて調整しつつ、同等の判断力を持つモデルを選びます。小規模で機械的な差分に最も高性能なモデルは不要ですが、微妙な並行処理の変更には必要です。小規模な修正差分の範囲を絞った再レビューには、低～中価格帯のモデルを使用します。

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

サブエージェントをディスパッチする際は、必ずモデルを明示します。 モデルを省略すると、セッションのモデル（多くの場合、最も高性能で最も高価なモデル）が引き継がれ、この項の意図が知らないうちに損なわれます。

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

タスクの複雑さを示す指標（実装タスク）：

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

タスクの進め方

同じ形式の小規模な作業はまとめます。 計画に、同じ種類の小規模で独立した編集（同じ 1 行修正、定数変更、複数ファイルにわたる同じフィールドの追加など）が複数含まれている場合、タスクごとに 1 つのサブエージェントをディスパッチしないでください。すべてのファイルと変更内容を列挙したディスパッチ用の指示を 1 つ作成し、まとめて単一のサブエージェントに送信します。その差分を一括でレビューします。個別の判断、テスト、またはレビュー範囲が必要な作業には、タスクごとに 1 回のディスパッチを行います。

ディスパッチ用プロンプトに記載した内容も、サブエージェントからの出力も、セッション終了までコンテキストに残り、以降のターンごとに再読み込みされます。成果物はファイルとして引き渡してください。

ディスパッチしたサブエージェントの完了待ち： 短いタイムアウトで待機インターフェースをポーリングしてはいけません。また、無言のまま期限を設けずに待機してはいけません。ローカルでできる作業（台帳の更新、次のレビューの準備、レポートの確認など）がある間は作業を続けます。子エージェントの結果は自動的に届きます。実際に手が空いている場合は、時間を区切って（プラットフォームで可能な場合は 5～10 分）待機し、各待機の間に状況を 1 行で報告し、稼働中の子エージェントを確認します。一覧を取得し、完了しているのに報告していないエージェントには連絡します。待機時間に上限を設けることで、長時間待機の効率をほぼ維持しながら、停止または応答を失った子エージェントをセッション終了時ではなく数分以内に検知できます。

1. 実装担当者へのタスク割り当て

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

• タスク概要： 実装担当者に割り当てる前に、このスキルの scripts/task-brief PLAN_FILE N を実行します。タスクの全文を一意のファイル名で保存し、そのパスを出力します。要件の唯一の参照元が概要になるように、割り当て内容を作成してください。割り当てには、次の内容を含めてください。（1）このタスクがプロジェクト内でどの位置づけにあるかを示す一文。（2）「まずこれを読んでください — ここに要件と、そのまま使用する正確な値が記載されています」という文言を添えた概要ファイルのパス。（3）概要では把握できない、以前のタスクで決まったインターフェースと決定事項。（4）概要内で気づいた曖昧さの解釈。（5）レポートファイルのパスとレポートの要件。正確な値（数値、マジック文字列、シグネチャ、テストケース）は概要にのみ記載します。サブエージェントにはプランファイル全体を読ませないでください。
• レポートファイル： 実装担当者のレポートファイルには概要にちなんだ名前を付けます（概要が …/task-N-brief.md なら、レポートは …/task-N-report.md）。割り当てプロンプトにレポートのパスを記載します。実装担当者はレポート全文をそのファイルに書き、ステータス、コミット、テストの概要一文、懸念事項のみを返します。
• 割り当てプロンプトには1つのタスクのみを記載し、セッションの履歴は含めません。以前のタスクの要約を蓄積して後続の割り当てに貼り付けないでください。実際のセッションでは、割り当ての42k文字のうち99%が貼り付けられた履歴でした。新しいサブエージェントに必要なのは、タスク、そのタスクが関わるインターフェース、全体的な制約だけです。それ以外は不要です。
• 割り当てには、実装担当者がサブエージェントを使わないという契約を含めます（実装担当者のテンプレートに記載されています）。実装担当者は、ヘルパーとしてもレビュー担当者としてもサブエージェントを割り当ててはいけません。レビューはレポートの提出後に、あなたが行います。実際のセッションでは、実装担当者が起動したレビュー担当者は、コントローラーが割り当てたタスクレビューを重複して行っていました。タスクごとにレビュー担当が丸々1人追加されていたことになります。
• 以前のタスクで、このタスクが扱う領域に関する指摘が保留されている場合は、割り当てにその台帳項目への参照を含めます。
• 割り当ての結果から、実装担当者のエージェント ID を記録します。修正ループの第1〜第3ラウンドでは、このエージェントを再開します。
• 複数の実装サブエージェントを並行して割り当ててはいけません（競合を避けるため）。

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

2. レポートに対応する

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

DONE： レビューパッケージ（このスキルのディレクトリから scripts/review-package PLAN_FILE BASE HEAD を実行）を生成し、出力されたパスを使ってタスクレビュアーに依頼します。スクリプトは、書き出した一意のファイルパスを表示します。BASE は実装担当をディスパッチする前に記録したコミットです。複数コミットのタスクで最後のコミット以外をひそかにすべて除外してしまう HEAD~1 は、決して使わないでください。パッケージを生成するのは実装担当のレポートが届いた後だけにしてください。作業中に生成すると、差分が変化し続けるため、事前に生成したパッケージは古くなります。

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

NEEDS_CONTEXT： 実装担当は、提示されていない情報を必要としています。不足している情報を提供し、再ディスパッチしてください。

BLOCKED： 実装担当はタスクを完了できません。阻害要因を評価してください。

1. コンテキストの問題であれば、情報を補足し、同じモデルに再ディスパッチします。
2. タスクにさらに深い推論が必要であれば、より高性能なモデルに再ディスパッチします。
3. タスクの規模が大きすぎる場合は、小さなタスクに分割します。
4. 計画自体に誤りがある場合は、修正の判断を下して台帳に記録し、その判断を引き継いで再ディスパッチします。

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

実装担当が質問をした場合は、作業の開始前でも途中でも、明確かつ十分に回答してください。必要に応じて情報を補足し、急いで実装に進ませないでください。

人間のパートナーへの質問のエスカレーション

実行時に AskUserQuestion を使う前は必ず、計画スクリプトによる質問でも、実装担当から引き継いだ質問でも、次の手順に従ってください。

1. 計画ヘッダーの「User decisions (already made)」を読み直します。記録済みの判断で質問に答えられる場合は、質問せず、その回答を使ってください。
2. 質問する場合は、計画に記載された事実に基づき、成果物とその役割／状態を明示してください。成果物名だけでは不十分です。また、各選択肢の説明では、何が変わり、何が変わらないのかを示してください。人間のパートナーが計画の内容をすべて把握しているとは限りません。前提のない推奨は、新たな提案のように受け取られてしまいます。

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

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

• レビュアーには、差分をファイルとして渡します。このスキルの 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 を欠陥として扱わないで」「軽微以下」「計画で選択した」などが含まれている場合は、いったん止めてください。先回りした判断であり、通常はレビューのやり取りを避けるためのものです。 タスクレビュアーから「⚠️ 差分からは検証できません」という項目が報告されることがあります。これは、変更されていないコードに存在する要件や、複数のタスクにまたがる要件を指します。これらはレビュー全体を妨げるものではありませんが、タスクを完了とする前に、自分で各項目を解決する必要があります。レビュアーにはない、計画とタスク間のコンテキストを持っているのはあなたです。実際の欠落だと確認した場合は、仕様レビューの不合格として扱い、他の指摘とともに修正ループに加えてください。

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

4. 修正ループ

レビューで仕様 ❌、重要度が Critical または Important の指摘、あるいは実際の欠落だと確認した ⚠️ 項目が報告された場合、ループが始まります。

ループを始める前に、次の 2 つの対応を行うことで、ループに入らずに済みます。

• 軽微な指摘は、判明した時点で進捗台帳に記録します （Task <N>: minor (deferred): <one-liner>）。最終的なブランチ全体レビューでは、その一覧を示し、マージ前に修正が必要なものを選別できるようにしてください。誰も読まない集約記録は、指摘を黙って破棄するのと同じです。軽微な指摘はループに入りません。
• 計画で必須とされている指摘、または計画の記述と矛盾する指摘については、自分で判断します。計画の記述に照らして指摘を検討し、拘束力を持つ仕様に基づいて判断してから、対応する前にその判断を台帳に記録してください。計画で必須とされているからといって指摘を退けてはならず、判断を記録せずに計画と矛盾する修正を割り当ててはなりません。 それ以外はすべてループに入ります。修正ラウンドは、修正の割り当て 1 回と、それに範囲を絞った再レビュー 1 回で構成されます。タスクあたり最大 5 ラウンドです。 ラウンド 1〜3 — 元の実装者を再開させます。 未解決の指摘をそのまま送信します。そのコンテキストは保持されています。タスク、コード、そして自身の選択を把握しています。ハーネスが稼働中のサブエージェントに別のメッセージを送信できない場合は、ブリーフのパス、レポートファイルのパス、および指摘を携えた新しい実装者を派遣してください。いずれの場合もレポートファイルが永続的な記憶となります。

ラウンド 4〜5 — より高性能なモデルで新しい実装者を派遣します（Model Selection に従ってください）。ブリーフのパス、レポートファイルのパス、未解決の指摘、そして次のフレーミングを渡します。「以前の実装者がこのタスクを [N] 回試みました。今はあなたが担当します。何が試されたかはレポートファイルを読んでください。」3 回の再開を経ても解消しないループは、通常、実装者が自身の問題を認識できていないことを意味します。新鮮な視点と能力の引き上げを一度に行うのです。

どのラウンドでも、いずれの場合も: 実装者は修正し、修正したコードをカバーするテストを再実行し、修正レポートを同じレポートファイルに追記し、短い契約を返します。レビュアーを再派遣する前に、修正レポートにカバレッジテスト、実行したコマンド、および出力が含まれていることを確認してください。この 3 つがすべて揃った時点で再レビューを派遣します。修正メッセージにはカバレッジテストのファイル名を記載してください。1 行の修正にスイート全体は必要ありません。

再レビューはスコープが限定されます。 scripts/review-package PLAN_FILE FIX_BASE HEAD を実行します。ここで FIX_BASE は前回のレビューが見たヘッドです。そして 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>。最終レビューは両方の立場を確認します。
• 実際に存在するが、それに依存する下流のものがない: 同様に保留にし、それが実在し繰り延べられたことを述べる裁定を付けます。
• 実在し、かつ重要（load-bearing） — 後続のタスクがそれに依存している、またはプランの欠陥を明らかにする場合: 依存する作業をブロック解除する最小の変更を裁定し、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)

続いて TaskUpdate でタスクを完了にし、次に進みます。同じ TaskUpdate で、説明を Goal: の行と Complete — see ledger. のみに短縮してください。セッション中、定期リマインダーではハーネスがすべてのタスクの説明全文を再注入します。また、完了したタスクの詳細はプラン、概要、およびステータス同期で説明が変更されない .tasks.json に残ります。例外として、メタデータに userGate: true または user-gate タグがあるタスクは、説明全文を残してください。完了時の再検証フックがその説明を読み取ります。

レビューに、修正も上限での裁定もされていない Critical／Important の指摘が残っている間は、次のタスクに進まないでください。

最終レビュー

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

ブランチ全体の最終レビューで指摘があった場合は、指摘ごとに修正用サブエージェントを立ち上げるのではなく、指摘の完全な一覧を渡して修正用サブエージェントを1つだけ立ち上げてください。指摘ごとに修正用サブエージェントを立ち上げると、それぞれがコンテキストを再構築し、テストスイートを再実行します。実際のセッションでは、最終レビュー後の修正作業だけで、そのセッションの全タスクを合わせたよりも多くのコストがかかりました。その後、修正範囲だけを対象に、修正作業分の再レビューを正確に1回実行します（修正範囲に対して scripts/review-package PLAN_FILE FIX_BASE HEAD を実行し、re-review-prompt.md を使用）。残った指摘は、タスクループのブレーカーと同様に判断してください。裁定を付けて保留にするか、根幹に関わる指摘について判断を示し、その判断を台帳に記録します。ここで作業を止めるのは、前述の4種類の指摘だけです。修正作業を2回行うことはありません。残った根幹に関わる指摘は、finishing-a-development-branch が選択肢を提示する際に、人間のパートナーに引き継がれます。

終了

何かを削除する前に、台帳にある Ruling: を含むすべての行を集め、最終メッセージの「私が下した裁定」に、裁定した順に記載してください。それぞれ、誤っていた場合の影響も添えてください。一覧には漏れがないようにします。台帳に裁定が記録されていれば、一覧にも必ず含めてください。人間のパートナーに代わって下した判断が伝わるのは、この一覧だけです。相手は一覧を読み、判断が誤っていた場合は修正します。ワークスペースとともに消えてしまう裁定は、秘密裏に下した判断と同じです。

ブランチ全体の最終レビューで問題がなく、修正もマージされたら、このプランのワークスペースを削除します（rm -rf <workspace>）。この時点からは git の履歴が記録になります。ほかのプランに属する兄弟ディレクトリには手を加えないでください。

superpowers-extended-cc:finishing-a-development-branch を使用します。

よくある合理化

言い訳	実態
「仕様への準拠はおおむね十分」	レビュー担当者が仕様との不整合を見つけたなら、未完了です。修正するか、上限に達して裁定するかのどちらかしかありません。
「自分で直します。ディスパッチは余計な手間です」	コントローラーが修正するとコンテキストが汚染され、レビューも省略されます。実装担当者を再開してください。
「もう一度繰り返せば収束するはずです」	上限を超えると、繰り返しても収束しません。失敗は構造的なものです。裁定して振り分けてください。
「レビュー担当者はどうせまた新しいことを見つけます」	範囲を限定した再レビューでは、修正を検証します。範囲外には及びません。未変更のコードに関する新たな指摘は、ループではなく台帳に記録します。
「この指摘は明らかに間違っているので、取り下げます」	裁定できるのは上限に達したときだけで、すべての判断を台帳に記録します。黙って破棄することは禁止です。
「修正は小さいので、再レビューは省略します」	未レビューの修正は、リグレッションの原因になります。各ラウンドの最後には、必ず範囲を限定した再レビューを行います。
「レビューがあるとループが遅くなります」	レビューのないループは、検証されない作業の繰り返しにすぎません。レビューはループのブレーキであり、ステアリングです。
「台帳の記録は余計な手間です」	コンパクション後にも残るのが台帳です。台帳のないコントローラーは、完了済みのタスク一連の流れを丸ごと再ディスパッチしたことがあります。
「台帳には自分の推論を記録すべきです」	台帳は復旧用のマップです。状態は一行で記録します。推論は日記であり、後続のあらゆるターンでコンテキストを消費します。
「プロセス上の教訓を台帳に書いておきます」	Finish 時にワークスペースは削除されるため、教訓もそこで失われます。代わりに最終レポートに記載してください。
「実装担当者が自分でレビュアーを起動しました。追加の安心材料になります」	同じ差分をレビューする重複した担当者であり、ゲートとなるのはタスクレビューです。ワーカーが起動したレビュアーは、厳密さではなく、指摘すべき欠陥です。

ワークフローの例

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: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[TaskCreate for each task with full description]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + 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

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + 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-extended-cc:finishing-a-development-branch.

範囲を限定した並列ディスパッチ

禁止されているのは並列処理そのものではなく、書き込みの競合です。上記の「複数の実装サブエージェントを並列でディスパッチしない（競合するため）」は、逐次ループにおけるデフォルトの動作です。実行中の各エージェントが、すべて独立性テストに合格する場合は、同時にディスパッチしてください。

• 読み取り専用エージェントは常に並列実行しても安全です：監査、ログ分析、検証ゲート、長時間実行するテストスイート（実装を続けている間に利用できる、無料のローカルエージェントタイプにも最適です）。
• 実装担当者を同時に実行できるのは、タスクの files リストに共通するパスがなく、かつ、どちらのタスクも相手の blockedBy チェーンに含まれない場合のみです。files メタデータがテストそのものです。重複がなければ競合はありません。
• 同じファイルに複数の書き込み担当者を割り当ててはいけません。また、レビューを省略するために並列処理を使ってはいけません。各タスクには、完了時に個別のタスクレビューを行います。
• 並列タスクはすべて、エージェントをディスパッチする前に in_progress に設定してください。モデルのルーティングは、進行中のティアの集合に基づいて各ディスパッチ先を解決します。タスクをマークしないままディスパッチすると、誤ったティアに対する処理としてブロックされます。
• 競合の有無が不確かな場合は、逐次実行してください。上記のタスクごとの逐次ループが引き続きデフォルトであり、並列処理は最適化であって、基本形ではありません。

タスクの永続化の同期

TaskUpdate で各タスクを完了としてマークした後、同期を保つために .tasks.json ファイルも更新してください。

1. <plan-path>.tasks.json を読み込みます
2. タスクの "status" を "completed" に設定します
3. "lastUpdated" を現在の ISO タイムスタンプに設定します
4. ファイルを書き戻します

これにより、セッションをまたいだ再開が正しく機能します。これを行わないと、新しいセッションで .tasks.json を読み込んだ際、完了済みのタスクが "pending" として表示されます。