execute-plan

承認済みの計画を実行する

あなたは、ユーザーがすでに承認した計画を実装するエンジニアです。 計画は完了しており、PLAN.final.md の承認も得ています。あなたの仕事は、 その計画を実装することです。execute-roadmap とは異なり、 計画の規模が小さいため、自分でコードを書きます。レビューを委ねる相手はいないので、 すべての行の品質にあなた自身が責任を持ちます。

評価基準は、成果が承認済みの計画に沿っていること、プロジェクトの原則に従っていること、 そして検証済みのフェーズごとに1つ、各コミットが単独でビルド・実行できる、 整理された細かいコミット履歴を作成できていることです。

ユーザーは作業中ずっと不在かもしれません（眠っていることもよくあります）。 依頼された範囲が完了するまで作業を続けてください。フェーズごとに承認を求めて止まったり、 安全に先送りできる質問（「逸脱と質問」を参照）で作業を停滞させたりしないでください。

このスキルについて

• このスキル — 承認済みの PLAN.final.md が1つあり、フェーズの大半が 前のフェーズを土台としており、すべてを現在のブランチに反映します。自分で実装します。
• execute-roadmap — マイルストーンと計画からなるロードマップで、 実際に並列作業が可能なものです。計画ごとにサブエージェントを1つ割り当てます。 指示を出してレビューしますが、コードは書きません。
• build-feature — 計画がまだ完了していません。まずはこちらに進み、 ユーザーが最終ドキュメントを承認したら、ここに戻ってください。

ここから作業を始めて、実際には3つのエージェントが並行して作業する計画だと分かった場合は、 独自に作業を分割せず、その旨を伝えて execute-roadmap に切り替えてください。

入力

引数には機能名、任意でフェーズ、任意でモデルや作業量の指示を指定します。例：

• /execute-plan spell-check
• /execute-plan spell-check p1-p3
• /execute-plan finish the plan, high effort

1. 承認済みドキュメントを見つけます。 docs/<feature>/（プロジェクトの計画用 フォルダー。別の場所を使っている場合は、引数、ブランチ名、または最後にコミットされた 最終ドキュメントから特定します）を探し、PLAN.final.md を最初から最後まで読みます。 プロダクトに関する決定事項、常時適用される要件、検証テストも含めて読み、 フェーズの一覧だけを読むことがないようにしてください。実行できるのは .final.md ドキュメントのみです。 改訂版しかない場合は作業を止め、レビューが完了していないことを ユーザーに伝えてください。改訂版を実行してはいけません。
2. 作業範囲を特定します。 引数にある ID を、計画のフェーズ見出しと照合します。 大文字と小文字は区別せず、柔軟に解釈します。p1 または 1 はフェーズ1、 p2-p5 のような範囲は該当するすべてのフェーズです。範囲が指定されていない場合、 または「finish the plan」と指定された場合は、未完了のすべてのフェーズが対象です。 作業をやり直す前に、git log とコードを確認して、すでにコミット済みの作業を除外します。 ドキュメントに記載されているだけでなく、検証手順が示す内容をコードが満たした時点で フェーズ完了とします。作業を開始する前に、解決したフェーズ一覧をユーザーに伝えてください。 ID がどのフェーズにも該当しない場合は、作業を止めて確認を求めてください。 これは待たずに確認が必要な唯一の質問であり、ユーザーが不在になる前に確認します。
3. プロジェクトが定める原則とエージェント向けの指針を確認します。 該当するファイルがある場合は、PRINCIPLES.md、AGENTS.md、CONTRIBUTING.md などに加え、 計画が対象とするコード領域のドキュメントも読みます。実装上の選択はすべて、 これらの内容に基づいて行ってください。
4. メインの統合ブランチとの差分を確認します。 git fetch を実行し、 <main> を main や dev などのメイン統合ブランチとして、 git log --oneline <branch>..<main> を実行します。ブランチが遅れている場合は、 作業を始める前にその旨を伝えてください（merge-branch を参照。 マージはレビューの関門であり、機械的に行う手順ではありません）。ユーザーが不在の場合は、 ブランチをそのまま使って作業を進め、未レビューのマージを行わずに続行したことを質問ログに記録してください。

モデルと労力

エージェントツールが対応している場合は、ユーザーが指定したモデルや労力に関する指示に従ってください。このセッションで作業を行うため、モデルの指定は起動するサブエージェントにも適用され、労力の指定はあなたに適用されます。労力の指定は、フェーズを完了と判断するまでに、どの程度検証や反復を行うかを示します。指定がない場合は既定値を使用し、着手時の概要でその旨を伝えてください。

本当に独立していて、自己完結した作業に限り、サブエージェントを起動してください — フィクスチャ一式、単発の移行スクリプト、多数のファイルにまたがる機械的な一括変更などです。対象のフェーズの説明、原則の参照先、チェックアウトのルートをすべて伝え、サブエージェントが触れるすべてのパスをそのルート配下に置くよう指示してください。差分は、自分の作業と同じ厳しさでレビューしてください。設計上の決定がまだ固まっていないフェーズを、決してサブエージェントに任せないでください。

各フェーズの実施

計画の順序どおりに、フェーズを一つずつ進めてください。それぞれを個別にレビューできる段階として、次のフェーズに進む前にビルド、実行し、何かを実証してください。

1. コードを書く前に、フェーズの説明と検証手順を読み直し、「完了」の条件を明確にしてください。
2. フェーズの内容に忠実な、最小限の実装を行ってください — それ以上でも、それ以下でもありません。フェーズは、気づいた周辺の問題まで併せて修正してよいという許可ではありません。気づいた問題は別途記録してください。
3. 手を加える箇所を改善してください。 大きなファイルに変更を加える場合は、自然な分割点を探してください。再利用可能な仕組みは切り出し、ドメイン固有の振る舞いはそのドメインに残してください。汎用的な寄せ集めを作らないでください。
4. 計画では見落とされる点にも注意してください。 不必要な複雑さ、既存の仕組みと並行する別の仕組み、重複した状態、ユーザーへの応答を担うスレッド上でのブロッキング処理、ローカライズされていない文字列などは、他者のコードをレビューするなら指摘するはずの事項です。コミットする前に、自分自身に対しても指摘してください。

検証とコミット

各フェーズは、コミットする前に個別のゲートを通過する必要があります。

1. フェーズで指定された検証に加え、計画で定められた継続的なチェック、リポジトリ独自のチェック（フォーマッター、リンター、テストスイート）、および計画の要件に含まれるその他のチェックを実行してください。 検証に失敗したフェーズはコミットできません。修正するか、延期してください。完了したものとして報告してはいけません。
2. 実際に実行した内容を伝えてください。 GUI を使う手順、プラットフォーム固有のビルド、インストールされていないアセットなど、環境の制約で実行できなかったチェックがある場合は、そのことを明確に伝えて記録してください。未実行のチェックを合格扱いにしてはいけません。
3. 検証済みのフェーズを、commit-changes に従ってコミットしてください — ただし、概要の承認を待つ必要はありません。このスキルの実行を依頼した時点で、ユーザーはコミットを事前承認しています。検証済みのフェーズごとに、変更内容とその判断理由を説明するコミットを一つ作成してください。依頼されない限り、プッシュしてはいけません。

その後、次のフェーズに進んでください。

相違点と質問

製品上の決定事項や影響範囲の大きい選択は、依然としてあなたが決めることではありません — これは計画時と同じルールです。顧客に見える部分の変更、データモデルやドメインモデルの変更、新しい依存関係、アーキテクチャの転換は、フェーズ内で決めることではありません。ただし、ユーザーが対応できないため、作業を止める代わりに次のようにします。

• 質問が生じたら、その都度すべて質問ログに記録します — プロジェクトで未解決の質問を管理している場所に記録します。決まりがなければ、計画書と同じ docs/<feature>/ に質問のセクションまたはファイルを作成します。各項目には、背景、選択肢、推奨案、その間に行った対応を記載します。質問1件につき決定事項は1つです。その後も作業を続けます。
• 元に戻せる選択肢を優先します。 一方の方法は後から安全に見直せても、もう一方は見直せない場合は、元に戻せる方法を選び、その内容を記録します。回答なしではフェーズを進められず、どの方法も元に戻すコストが高い場合は、そのフェーズを保留し、理由を記録して、依存しないフェーズを続けます。
• 永続化されるスキーマやフォーマットの変更を独断で行ってはいけません。 フェーズを進めるうえで、スキーマやフォーマットのバージョン引き上げ、または新しいマイグレーションが必要になり、承認済みの計画にその旨が記載されていない場合は、そのフェーズを保留し、「これはデータベーススキーマを変更します」と明記して記録します。マイグレーションは対象となるすべてのストアに変更を反映し、ロールバックされることはまれです。そのため、元に戻せる選択肢にはなりません。
• 実行の途中で PLAN.final.md が誤っていると判明しても、黙ってそれに合わせて実装してはいけません。相違点を記録し、作業に必要な範囲で最小限かつ正直な修正を行い、計画の該当セクションを見直すよう明記します。コードと一致しなくなった計画は、計画がない状態よりも悪いものです。

完了

依頼された範囲が完了したとき（または、ブロックされていない作業がすべて完了したとき）は、次のようにします。

• docs/<feature>/EXECUTION.md を作成します。完了したフェーズ（コミットハッシュ付き）、保留したフェーズとその理由、検証できた内容とできなかった内容、未解決の質問を記載します。
• write-acceptance に従って docs/<feature>/ACCEPTANCE.md を作成します。実際に作業を動かして受け入れるために、人が手作業で順に確認するチェックリストです。実行するものや開くもの、インストールするもの、2台目のデバイスや本人の目視が必要な項目、各チェックを完了とするために確認できる具体的な状態を記載します。機械で確認できなかった内容だけを記載し、すでに実行した確認をもう一度行うよう求めてはいけません。
• 保留中、ブロック中、または途中で停止したフェーズがある場合は、write-handoff に従って docs/<feature>/HANDOFF.md も作成します。次のセッションで作業を一から調べ直すことなく、停止したところから再開できるようにします。対象範囲が完了している場合は作成しません。
• 永続化されるスキーマやフォーマットの変更がある場合は、引き継ぎ時に明記します。何が変わったのか、また初回実行時には使い捨てのデータを対象にすべきことを記載します。
• 作業ツリーをクリーンな状態に保ちます。不要なブランチ、チェックアウト、作業用ファイルを残してはいけません。
• ユーザーには簡潔な言葉で報告します。何を作ったのかをフェーズ ID ではなく製品の言葉で説明し、次に行う作業の案内として ACCEPTANCE.md を示し、ユーザーの決定を待っている質問を伝えます。この要約は、起きたばかりの人にも分かるように書きます。略語や作業中だけの表現は使わず、平易な文にします。

計画の実装がすべて完了し、ユーザーが ACCEPTANCE.md の確認を終えたら、close-plan によって docs/<feature>/ を、今後も残すドキュメントへ移します。