Subagent-Driven Development

タスクごとに新しい subagent を dispatch し、各タスク後に2段階のレビュー（仕様遵守レビュー、その後コード品質レビュー）を実施してプランを実行します。

コアの原則： タスクごとの新しい subagent + 2段階レビュー（仕様→品質）= 高品質、高速な反復

使用するべき場合

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"];
}

vs. Executing Plans（並列セッション）:

• 同一セッション内（コンテキストスイッチなし）
• タスクごとに新しい subagent（コンテキスト汚染なし）
• 各タスク後の2段階レビュー：仕様遵守を先に、その後コード品質
• 高速な反復（タスク間の人間の介入なし）

プロセス

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer subagent asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
        "Implementer subagent fixes spec gaps" [shape=box];
        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
        "Code quality reviewer subagent approves?" [shape=diamond];
        "Implementer subagent fixes quality issues" [shape=box];
        "Mark task complete in TodoWrite" [shape=box];
    }

    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
    "Mark task complete in TodoWrite" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
}

プロンプトテンプレート

• ./implementer-prompt.md - implementer subagent を dispatch
• ./spec-reviewer-prompt.md - 仕様遵守レビュアー subagent を dispatch
• ./code-quality-reviewer-prompt.md - コード品質レビュアー subagent を dispatch

ワークフロー例

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

[Read plan file once: docs/plans/feature-plan.md]
[Extract all 5 tasks with full text and context]
[Create TodoWrite with all tasks]

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: "Got it. Implementing now..."
[Later] Implementer:
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra

[Get git SHAs, dispatch code quality reviewer]
Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.

[Mark Task 1 complete]

Task 2: Recovery modes

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: [No questions, proceeds]
Implementer:
  - Added verify/repair modes
  - 8/8 tests passing
  - Self-review: All good
  - Committed

[Dispatch spec compliance reviewer]
Spec reviewer: ❌ Issues:
  - Missing: Progress reporting (spec says "report every 100 items")
  - Extra: Added --json flag (not requested)

[Implementer fixes issues]
Implementer: Removed --json flag, added progress reporting

[Spec reviewer reviews again]
Spec reviewer: ✅ Spec compliant now

[Dispatch code quality reviewer]
Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)

[Implementer fixes]
Implementer: Extracted PROGRESS_INTERVAL constant

[Code reviewer reviews again]
Code reviewer: ✅ Approved

[Mark Task 2 complete]

...

[After all tasks]
[Dispatch final code-reviewer]
Final reviewer: All requirements met, ready to merge

Done!

利点

手動実行との比較:

• Subagent は自然と TDD に従う
• タスクごとの新しいコンテキスト（混乱なし）
• 並列セーフ（subagent は干渉しない）
• Subagent が質問できる（仕事の前後）

Executing Plans との比較:

• 同一セッション（ハンドオフなし）
• 継続的な進捗（待機なし）
• レビューチェックポイントが自動的

効率性の向上:

• ファイル読み取りのオーバーヘッドなし（コントローラが全テキストを提供）
• コントローラが必要なコンテキストをキュレート
• Subagent は完全な情報を前もって取得
• 質問が作業開始前に浮かび上がる（作業後ではなく）

品質ゲート:

• 自己レビューがハンドオフ前に問題をキャッチ
• 2段階レビュー：仕様遵守、その後コード品質
• レビューループが修正が実際に機能することを確認
• 仕様遵守過剰/不足構築を防止
• コード品質が実装が適切に構築されていることを確認

コスト:

• Subagent 呼び出しが増加（implementer + タスクごとに 2 つのレビュアー）
• コントローラがより多くの準備作業を実施（すべてのタスクを事前抽出）
• レビューループが反復を追加
• ただし早期に問題をキャッチ（後でデバッグするより安い）

危険信号

決して:

• レビューをスキップ（仕様遵守またはコード品質）
• 未修正の問題で進める
• 複数の実装 subagent を並列で dispatch（競合）
• Subagent にプランファイルを読ませる（代わりに全テキストを提供）
• シーン設定コンテキストをスキップ（subagent がタスクがどこに適合するかを理解する必要）
• Subagent の質問を無視（進める前に回答）
• 仕様遵守レビューで「ほぼ十分」を受け入れる（仕様レビュアが問題を見つけた = 完了ではない）
• レビューループをスキップ（レビュアが問題を見つけた = implementer が修正 = 再度レビュー）
• Implementer の自己レビューが実際のレビューに置き換わることを許す（両方が必要）
• 仕様遵守が ✅ になる前にコード品質レビューを開始 （順序が間違っている）
• いずれかのレビューに未解決の問題がある間に次のタスクに進む

Subagent が質問する場合:

• 明確に完全に回答
• 必要に応じて追加コンテキストを提供
• 実装に急かさない

レビュアーが問題を見つけた場合:

• Implementer（同じ subagent）がそれを修正
• レビュアーが再度レビュー
• 承認されるまで繰り返す
• 再レビューをスキップしない

Subagent がタスクに失敗する場合:

• 特定の指示で修正 subagent を dispatch
• 手動で修正しようとしない（コンテキスト汚染）

統合

必須のワークフロースキル:

• superpowers:writing-plans - このスキルが実行するプランを作成
• superpowers:requesting-code-review - レビュアー subagent 用のコードレビューテンプレート
• superpowers:finishing-a-development-branch - すべてのタスク後に開発を完了

Subagent が使用すべき:

• superpowers:test-driven-development - Subagent が各タスクに TDD に従う

代替ワークフロー:

• superpowers:executing-plans - 同一セッション実行の代わりに並列セッション用に使用