executing-plans

計画の実行

フェーズベースのオーケストレーションを通じて、作成済みの実装計画を実行します：計画レビュー → タスク作成 → バッチごとのコーディネーターへの割り当てと検証 → Git コミット → 完了。各バッチは新しいサブエージェント（Agent ツール）で実行されるため、メインエージェントのコンテキストにバッチ実行の記録が蓄積されることはありません。実行は複数のターンにわたって複数のバッチを進めます。実行する際は、Claude Code 組み込みの /goal でラップすることを推奨します（以下を参照）。

推奨：/goal でラップして実行する

Claude Code 組み込みの /goal（v2.1.139 以降）の下で起動し、バッチの後で停止せず、実行が完了するまで継続させます：

/goal "Claude has emitted the Phase 6 completion message 'Plan execution complete. All N tasks verified and committed' AND has reported the final commit hash from Phase 5 in the transcript" /superpowers:executing-plans <plan>

/goal はユーザーが入力する外側のラッパーです。呼び出しの前に付ける必要があり、スキルが実行途中で有効にすることはできません。評価者はトランスクリプト内で Claude が述べた内容のみを判定します（ファイルを読み取ったり、コマンドを実行したりはしません）。そのため、条件はファイルシステムの状態ではなく、ナレーションされた出力に基づいて指定してください。注：executing-plans は、すべてのバッチが完了した後の Phase 5 で一度だけコミットします。「バッチごとのコミットハッシュ」を条件にしないでください。条件に一致しなくなります。バッチごとの評価者の判定は進捗を示すものであり、完了を示すものではありません。セマンティクスの全体と条件の指定方法については、../../skills/references/goal-wrapper.md を参照してください。スキル本体は単一ターン駆動で、各ターンの冒頭に bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" を実行して状況を確認します（以下のステップ 1 を参照）。

各イテレーションのステップ 1 — batch-progress.sh で状況を確認する

ほかの作業を始める前に、次を実行します：

bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" <plan-path>

このスクリプトは計画ディレクトリを読み取り、sprint-contract-batch-*.md と handoff-summary-*.md のファイル数を数えて、「Batch 3 active — Agent next」／「Batch 2 closed — TaskList then commit-or-next-batch」／「Batch 4 not yet started — Phase 3 steps 0-1-2」といった、次のアクションを正確に指示します。出力を、現在の状況を示す信頼できる指標として読み、指示に従ってください。これにより、以前のループで行っていた、イテレーションごとのファイルシステムのスキャンと情報の注入が置き換えられます。同じデータを、このスキルの範囲内で扱います。

初回の呼び出しでは、まだ計画パスが解決されていないため、このステップをスキップし、以下の「最初のアクション」に進んでください。

重要：中断条件の確認（初回の呼び出し時のみ、最初に実行）

_index.md を読み取ります。「Execution Plan」YAML に含まれるタスクが単一バッチ内で 5 件未満の場合は、ここで中断します。コーディネーターとスプリント契約はスキップし、タスクをインラインで実行してコミットしてください。$ARGUMENTS に --force トークンが含まれている場合は、この条件を無視します。応答テンプレートについては ./references/bail-out.md を参照してください。そのインライン作業で「条件 X が成立するまで続ける」という単純なループが必要な場合は、/goal を直接使用してください。

最初のアクション — 計画パスを解決する

計画パスを解決してから、状況を確認します。

1. 計画パスを解決します：
   • $ARGUMENTS でパスが指定されている場合（例：docs/plans/YYYY-MM-DD-topic-plan/）、そのパスを使用します
   • 指定されていない場合は、YYYY-MM-DD-*-plan/ の下で、ベース名をソートしたときに最後になる *-plan/ フォルダーを選びます。つまり、ファイルシステムの更新日時ではなく、名前に含まれる日付プレフィックスが最も新しいものを選びます。ls -1d docs/plans/*-plan/ 2>/dev/null | sort | tail -1 を使用してください（ls -t／ls -1dt は使用しないでください。古いフォルダー内のファイルを編集するとディレクトリの更新日時が変わり、新しく作成されたフォルダーより上位に並ぶ場合があります）。確認は求めず、結果をそのまま使用します。
   • 計画フォルダーが見つからない場合は、中断し、想定されるパスのパターンを明記したわかりやすいエラーメッセージを返します
2. bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" <plan-path> を実行して、現在のバッチの状態を表示します。裸のパス scripts/batch-progress.sh は解決されません。このスキルはプラグインのディレクトリではなく計画のリポジトリの cwd で実行されるため、スクリプトには絶対パスであるプラグインのパスを指定する必要があります。バッチがすでに存在する場合は、スクリプトの指示にそのまま従ってください（Phase 1／2 は前のターンで実行済みのためスキップします）。存在しない場合は、初期化に進みます。

初期化（最初のターンのみ）

1. 計画の確認：フォルダーに「Execution Plan」セクションを含む _index.md があることを確認します。バッチを開始する前に、ドキュメントインデックスを参照してください：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" show <plan-path>。該当行のステータスが expired: の場合は、作業を拒否してください。レトロスペクティブによって計画が無効化され、権威ある情報ではなくなっています。どのレトロスペクティブによって無効化されたかをユーザーに伝え、停止してください。ステータスが implemented:<old-sha>（リリース後の再作業）の場合は、バッチ 1 を開始する前に bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status <plan-path> "wip" を実行し、計画が再び作業中であることをインデックスに反映してください。その後、メモリを参照します：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active を実行し、Phase 1「計画のレビュー」の前に、関連性の高い上位の項目を読んでください。
2. コンテキスト：_index.md を最後まで読みます。これは実行における信頼できる情報源です。

背景知識

基本原則：実行前のレビュー、バッチごとの検証、ブロッカーの明示、証拠に基づくアプローチ。

必須スキル：実行モードにかかわらず、superpowers:behavior-driven-development を読み込む必要があります。

重要 — 2 つの内部ゲートスキルは作業の成否を左右するものであり、任意ではありません。 実装を担当するすべてのサブエージェントへのプロンプトでは、作業完了を報告する前に superpowers:verification-before-completion を読み込むよう指示する必要があります（完了を主張する場合は、最新の検証証拠を返信に貼り付けなければなりません）。また、バッチコーディネーターは、評価者からの REWORK 判定に対応する前に superpowers:receiving-code-review を読み込む必要があります（各再作業項目をコードベースで検証し、盲目的に実装してはいけません）。どちらかをコーディネーターのプロンプトから省くと、プロトコル違反になります。詳細は ./references/batch-execution-playbook.md（エージェントプロンプトのテンプレート＋再作業ループ）を参照してください。

完了の定義

./references/definition-of-done.md を参照してください（必須事項。他のすべてのガイダンスに優先します）。

Phase 1：計画のレビューと理解

1. 計画を読む：_index.md を読み、範囲とアーキテクチャ上の決定を把握し、「Execution Plan」セクション内の YAML タスクメタデータを抽出します。
2. プロジェクトを理解する：計画に関連するコードベースの構造、主要ファイル、パターンを調べます。
3. ブロッカーを確認する：./references/blocker-and-escalation.md を参照してください。
4. 事前の競合スキャン（Phase 2 の前に一度だけ実施）：各タスクの明示的な指示と、解決済みの code-v{N}.md チェックリストを照合し、矛盾がないか確認します（例：チェックリストで禁止されているスタブや重複ロジックをタスクで必須としている場合）。該当する矛盾がなければ何も行いません。./references/preflight-conflict-scan.md を参照してください。

Phase 2：タスクの作成（必須）

./references/phase-2-task-creation.md を参照してください。

Phase 3：バッチ実行ループ（コンテキストリセット方式）

./references/phase-3-orchestration.md と ./references/batch-execution-playbook.md を参照してください。

重要 — サブエージェントを呼び出すたびにモデルを指定してください。 Agent ツールでバッチコーディネーターまたはレビュー担当者を起動するときは、必ず明示的に model（通常の実装・検証には sonnet、難しい推論や最終的なブランチ全体のレビューには opus、機械的な一括処理には haiku）を渡してください。model を指定しないと、セッションで最も高価なモデル層が暗黙に継承されます。選択を委ねると呼び出しが最上位モデル層に偏り、予算を浪費します。作業に対応できる最も低コストのモデル層を選び、既定値に任せないでください。

重要 — ネイティブの Workflow ツールは、明示的なオプトインがある場合のみ使用できます。 ユーザーがマルチエージェントオーケストレーションを明示的に選択している（「ワークフローを使う」などと述べている、または ultracode が有効になっている）場合を除き、Workflow を呼び出してはいけません。/goal の実行で、バックグラウンドエージェントを暗黙に多数起動してはいけません。オプトインがない場合は、既定の制限付き Agent ツール呼び出しラウンドを使い、選択肢を一文で提示してください。オプトインのルールとタスクの割り当てについては ../../skills/references/workflow-orchestration.md を参照してください。

Phase 4：検証とフィードバック

./references/phase-4-verification.md を参照してください。

フェーズ 5：Git コミット

git-agent を使用して実装変更をコミットします（失敗した場合は git にフォールバックします）。

アクション：

1. 次を実行します：git-agent commit --intent "<feature description>" --co-author "Claude <Model> <Version> <[email protected]>"
2. 認証エラーが発生した場合は、--free フラグを付けて再試行します
3. フォールバック：git-agent を利用できない、または失敗した場合は、Skill ツールを使用して /git:commit スキルを呼び出します。手順の全体像は ../../skills/references/git-commit.md を参照してください

重要 — コミット後、計画の docs-index 行を必ず更新してください（先送り禁止）。 実装コミットが作成されたら、計画のインデックス行を implemented に更新します：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status <plan-path> "implemented:$(git rev-parse --short HEAD)"。その後、インデックスの更新を独立した小規模なコミットとして記録します：git-agent commit --no-stage --intent "mark <plan> implemented in docs index"。--amend は絶対に使用しないでください。履歴が書き換えられ、Stop フックによる completion_commit の検出が混乱するためです（フックは、計画の変更ファイルセットに含まれるファイルを変更した先端コミットを基準にします。amend された先端コミットは、その参照先をひそかに変更してしまいます）。

重要 — 条件付きのメモリ書き込み手順は、上記のフォローアップコミットに含めて実行してください（先送り禁止）。 既存の計画内学習における variety-gap シグナル（references/intra-plan-learning.md:54 — バッチ内のすべてのチェックリスト項目が PASS になるまでに、2 回以上の手戻りラウンドが必要だった場合）を条件とします。今回の実行でこのシグナルに該当したバッチがあれば、繰り返し発生した手戻りの原因をまとめた docs/memory/pitfall_<slug>.md も作成し、bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<path> --status active --summary "<one-line>" --category pitfall を実行して、上記で作成した専用のフォローアップコミットに含めます。これに対する別のコミットは作成しないでください。この variety-gap のトリガーは、batch-execution-playbook.md:165 にある別個のハードアボート上限（エスカレーションまでの手戻りラウンド数の最大値は 2 回）とは明確に異なります。これはメモリ書き込みのトリガーではなく、手戻りループの強制停止を制御するものです。variety-gap シグナルに該当するバッチがなければ、この手順は何もしません。

手順、テンプレート、要件については ../../skills/references/git-commit.md を参照してください。すべてのタスクが完了してからコミットします。機能の範囲がわかる、適切なコミットメッセージを使用してください。

フェーズ 6：完了

すべてのタスクが完了していることを確認し、完了サマリーを出力します。

1. 最終タスク監査：TaskList を使用して、すべてのタスクのステータスが completed であることを確認します。in_progress または pending のタスクがある場合は、先に進まず、フェーズ 3 に戻って残りのタスクを完了します。
2. サマリーメッセージ：「計画の実行が完了しました。全 [N] 件のタスクを確認し、コミットしました。」（ユーザー向け。機械的なトリガーではありません。以下の注記を参照してください）。

完了ログは自動で記録されます。 docs/retros/plans-completed.jsonl は自分で書き込みません。プラグインの単一の Stop フック（hooks/stop-state-sync.sh）が、ディスク上に永続化された状態（引き継がれたすべてのバッチ（handoff-summary-* の数がバッチ数以上）と、handoff-state.md の変更ファイルセットに触れた git コミット）から計画の完了を検出し、plan_completed イベントを機械的に追記します。これは初回完了時に限られます。検出は状態に基づき、出力した文言には依存しないため、言い換えたりサマリーを省略したりしても記録されます。このログから、/superpowers:retrospective のフェーズ 5a は completion_commit を読み取ります。行の形式については、../retrospective/references/evolution-protocol.md の §Plan Completion Log Schema を参照してください。

終了条件

すべてのタスクを実行・検証し、証拠を記録し、ブロッカーがなく、最終検証に合格し、git コミットが完了していること。このスキルは完全に自律して実行され、ユーザーの承認を求める手順はありません。無人で複数ターンにわたって継続する場合は、/goal でラップしてください（ファイルの先頭を参照）。

参考資料

• ./references/blocker-and-escalation.md - ブロッカーの特定と対処に関するガイド
• ./references/preflight-conflict-scan.md - フェーズ 2 の前にタスクとチェックリストの矛盾を確認するフェーズ 1 のスキャン
• ./references/batch-execution-playbook.md - バッチ実行のパターン
• ./references/definition-of-done.md - 妥協できない完了ルール
• ./references/phase-2-task-creation.md - TaskCreate／依存関係の階層ワークフロー
• ./references/phase-3-orchestration.md - メインエージェントのバッチループとコーディネーターの起動
• ./references/phase-4-verification.md - エビデンス、引き継ぎ、計画内での学習
• ../../skills/references/git-commit.md - Git コミットのパターンと要件（複数スキルで共有するリソース）
• ../../skills/references/goal-wrapper.md - /goal ラッパーのセマンティクスと条件の表現（複数スキルで共有するリソース）
• ../../skills/references/workflow-orchestration.md - 大規模な並列バッチ向けのネイティブ Workflow エスカレーション（オプトインのルールとタスクのマッピング）
• ./references/evaluation-file-formats.md - 評価ファイル形式の定義（スプリント契約、評価レポート、引き継ぎサマリー）
• ./references/sprint-contract-template.md - スプリント契約のテンプレートと交渉プロトコル
• ./references/handoff-template.md - 長期計画向け引き継ぎサマリーのテンプレート
• ./references/intra-plan-learning.md - パターンスキャン、バッチの引き継ぎ、チェックリストの進化に関する形式
• ./scripts/batch-progress.sh - ファイルシステムから導出するバッチ進捗の把握（各イテレーションのステップ 1 として実行）
• ../../lib/task-brief.sh - 1 件のタスクのテキストをファイルに抽出し、実装担当者がディスクから読み込めるようにします（diff／タスクテキストのファイル化）
• ../../lib/review-package.sh - 評価担当者がディスクから読み込む、差分全体のレビューパッケージファイルを生成します
• ../../lib/task-ledger.sh - タスクごとの永続的な完了台帳。ディスパッチ前に確認し、PASS の後に追記します