execute-blueprint

Blueprint スキルの実行

目的

専用のサブエージェントを使用して、厳格なビルド、レビュー、検証のサイクルを各ステップで実施し、Blueprint の計画を実行します。レビューや検証で不具合が見つかった場合は、修正用のサブエージェントが修正し、そのステップを再度レビューおよび検証します。ユーザーに確認するのは、ユーザー自身の判断が本当に必要な場合に限られます。メインの会話は、ユーザーとサブエージェントの間の調整役です。このスキルで定められた質問をユーザーに行い、作業をサブエージェントに割り当て、結果を報告し、ユーザーが選択したモードに従って git を操作します。メインの会話は、ビルド、レビュー、修正、検証の作業を自ら行うことはありません。

ビルド、レビュー、修正、検証をすべてサブエージェントに任せることで、長期にわたる複数のマイルストーンを含む計画でも、このスキルを実用的に使い続けられます。トークンコストの大部分を占めるソースファイルの読み込み、ツールの実行、出力全体の取得は、サブエージェント内で行われます。サブエージェントが戻ると、そのコンテキストは直ちに解放されます。コーディネーターのコンテキストに保持されるのは計画と、各サブエージェントから報告される要約だけであり、ファイルの内容やツールの出力は含まれません。そのため、計画がどれほど大きくなっても、コンテキストを軽量に保てます。

鉄則

これらのルールは、すべての実行セッションに適用されます。手を抜くことを示唆するローカルな判断よりも優先されます。

**メインの会話では、ビルド、レビュー、修正、検証を一切行いません。**

すべてのビルド、レビュー、修正、検証は、Claude Code の Agent ツールを介してサブエージェントに委任します。メインの会話で行うのは、次のことだけです。

• 以下で定義するゲートの質問をユーザーに尋ねます。
• references/subagent-prompts.md のテンプレートを使ってサブエージェントに作業を委任します。
• 結果、指摘事項、修正内容、エスカレーションについてユーザーに報告します。
• ユーザーが選択したモードに従って git を扱います。
• 計画ファイルの進捗を更新します。

このルールは、計画の規模、ステップの大きさ、見かけ上の些細さにかかわらず適用されます。1 行の設定変更でもビルド用サブエージェントに委任し、レビューでの指摘に対する 1 文字の修正でも修正用サブエージェントに委任します。ステップの実行中に、メインの会話がソースファイルを編集したり、テストを実行したり、リンターを直接実行したりすることはありません。実行中にメインの会話で使用できるツールは、計画の読み取り、「進捗の追跡」で定義する形式固有の変更による計画への進捗マーカーの書き込み、エージェントへの作業の委任、スキル管理モードでの git コミットの作成に限られます。

これが絶対である理由： 重い作業をすべてサブエージェントに任せることで、コーディネーターのコンテキストウィンドウを軽く保ちます。メインの会話がソースファイルを読んだり、ツールの出力を直接取り込んだりすると、その情報がコンテキストに蓄積され、長い計画ではスキルの品質が低下します。サブエージェントのコンテキストは一時的なもので、サブエージェントが要約を返した時点で解放されます。そのため、コーディネーターが負担するのは、作業そのものではなく、要約された結果だけです。

**フェーズ 1～3 は順番に通過する必須ゲートです。このセッションでフェーズ 1、2、3 が完了するまで、フェーズ 4（ステップの実行）は開始しません。**

各ゲートの最後にユーザーへ質問し、回答を待ちます。ゲートの質問をほかの出力とまとめてはいけません。前回のセッションでの回答を前提にしてはいけません。同じ計画を以前に実行した場合でも、新しい実行セッションのたびにゲートの質問を改めて行います。

**ステップがコミットされるのは、最終状態でレビューと検証の両方に合格した後だけです。**

修正によってコードが変更されると、それ以前に行ったレビューと検証の結果は古くなります。最後の変更後のコードに対して、完全なレビューと完全な検証の両方が成功して初めて、ステップは完了となります。コミットにはその状態を記録します。途中の試行、未解決の指摘があるステップ、修正が完了していない作業ツリーを記録してはいけません。

これはどちらの git モードでも同じです。スキル管理モードでは、ステップの修正中、または未解決のエスカレーションがある間は、自動コミットを作成しません。ユーザー管理モードでは、ステップが問題なく合格するまで、コミット可能な状態としてユーザーに提示しません。

労力の水準

各フェーズを、正しく仕上げる唯一の機会として扱います。ビルドは草案ではなく、完全な実装にしてください。レビューは徹底的に批判的な視点で行います。検証ではすべてのツールを実行し、結果をすべて確認します。修正にも同じ基準を適用します。指摘を解消するだけでなく、原因を修正してください。ステップに合格した時点で、そのコードは本番環境で使用できる状態になっていなければなりません。

実行フェーズ

実行は、以下のフェーズを厳密な順序で進めます。フェーズ 1〜3 はゲートであり、フェーズ 4 を開始する前に完了する必要があります。

1. 計画の確認 — 計画ファイルを見つけるか確認し、ここまでの進捗を報告して、続行するかどうかを尋ねます。
2. Git モードのゲート — ユーザー管理またはスキル管理のどちらで Git を扱うか、ユーザーに選択してもらいます。必須のゲートです。
3. 実行間隔のゲート (条件付き) — ユーザーがスキル管理を選択し、かつ計画が複雑（複数のマイルストーンがある）な場合に限り、マイルストーンの境界で一時停止するか、全自動で実行するかを尋ねます。必須のゲートです。
4. ステップの実行 — 各ステップについて、ビルド、レビュー、検証のサブエージェントを厳密に直列でディスパッチします。対象範囲内の指摘事項は自動的に修正し、それ以外はエスカレーションします。選択したモードに応じて一時停止してコミットし、計画ファイルの進捗を更新します。

フェーズ 1：計画の確認

docs/plans/ で計画ファイルを検索します。計画は Markdown（.md）または HTML（.html）で記述されている場合があります。両方の拡張子を検索し、同等に扱います。単一の .md ファイル、単一の .html ファイル、.md ファイルを含むマイルストーンフォルダー、.html ファイルを含むマイルストーンフォルダーは、いずれも有効な計画構成です。

計画ファイルまたはフォルダーが 1 つだけ存在する場合は、それを使用します。複数存在する場合は、一覧をユーザーに提示し、実行するものを尋ねます。番号付きのステップファイルを含むマイルストーンフォルダーの場合は、完了済みとマークされていない最初のステップから開始します（各形式での完了状態の記録方法については、以下の「進捗の追跡」を参照してください）。ユーザーのリクエストで計画ファイルが直接指定されている場合（例：「01_milestone_name.md を実行」または「01_milestone_name.html を実行」）は、確認せずにそのファイルを使用します。

マイルストーンフォルダー内に .md と .html のステップファイルが混在している場合、これは仕様外です。write-blueprint が混在するフォルダーを生成することはありません。ユーザーに警告し、混在しているファイルを一覧表示したうえで、今回の実行で使用する形式を尋ねます。どちらかの拡張子を黙って選んではいけません。

計画の形式は、ファイルの拡張子から判定します。形式によって変わるのは計画の解析方法と進捗の書き戻し方法だけであり、サブエージェントのディスパッチ方法には影響しません。判定した形式は、セッションの残りの間キャッシュします。

実行を開始する前に、計画ファイル全体をコンテキストに読み込みます。すべてのステップ見出しまたはステップ記事、それぞれのフェーズの指示（フェーズ 1 のビルド、フェーズ 2 のレビュー、フェーズ 3 の検証）、およびステップ間の依存関係を特定します。

• Markdown の計画の場合：ステップ見出し（### Step N: ...）がステップを区切り、フェーズ見出し（#### Phase 1 — Build など）がフェーズを区切ります。
• HTML の計画の場合：<article class="step" data-step="N"> 要素がステップを区切り、<section class="phase phase-build">、<section class="phase phase-review">、<section class="phase phase-verify"> がフェーズを区切ります。

ステップの総数と、完了済みとマークされているステップ数を数え、続行するかどうかを尋ねる前にユーザーに報告します。

ユーザーが特定のステップのみの実行を依頼した場合（例：「ステップ 3〜5 を実行」または「ステップ 2 をスキップ」）は、その依頼に従い、指定されたステップのみを順番に実行し、それ以外はスキップします。スキップするステップに、指定されたステップが必要とする依存関係が含まれる場合は警告します。

計画の構成に基づいて、その複雑さを判定します。

• 単純な計画：単一の計画ドキュメント（.md または .html）。
• 複雑な計画：複数のマイルストーンファイルを含むマイルストーンフォルダー（.md または .html）。

この複雑さの分類は、以下の実行間隔のゲートで使用します。形式は複雑さに影響しません。

フェーズ 2：Git モードの確認

**このフェーズは、Git モードに関する質問で終了します。それ以外は行いません。** 計画を見つけて進捗を報告したら、どの Git モードを使うかをユーザーに尋ね、回答を待ちます。ステップの実行を開始してはいけません。ケイデンスに関する質問はまだしてはいけません。ユーザーが Git モードに回答した後に尋ねます。サブエージェントを起動してはいけません。

ユーザーには、以下の文言または同等の表現で、必ず 2 つの選択肢を提示します。

実行中の Git の扱いは、どのようにしますか？

1. ユーザー管理：各ステップの後に一時停止します。確認、ステージング、コミットはご自身のペースで行ってください。
2. スキル管理（デフォルト）：3 つのフェーズすべてに合格した各ステップの後に、自動でコミットします。

続行する前に、ユーザーの回答を待ちます。実行セッションが新しく始まるたびに、必ずもう一度尋ねます。前回のセッションでの選択を引き継いではいけません。提示するデフォルトの選択肢はスキル管理ですが、セッションごとに必ずこの確認を行います。ユーザーがモードを選択または事前に指定していない状態で、黙って実行を開始してはいけません。

事前指定された回答：ユーザーが最初の実行メッセージですでにモードを明確に指定している場合（例：「この計画をスキル管理モードで実行して」「ユーザー管理モードを使って実行して」）は、それをこの確認への回答として受け入れ、続行します。形式的な確認を再度求めてはいけません。この確認の目的は、ユーザーが選択したことを確かめることであり、質問そのものを行うことではありません。表現が曖昧な場合（例：「自分で管理して」）は、確認の質問をします。

ユーザー管理モード

• 3 つのフェーズ（ビルド、レビュー、検証）をすべて完了した各ステップの後に一時停止します。
• ユーザーは変更を確認し、ファイルをステージングして、任意のタイミングでコミットします。
• コミットを自動作成してはいけません。
• ユーザーが続行を明示するまで、実行を再開してはいけません。
• ユーザー管理モードでは、計画の複雑さにかかわらずステップごとに必ず一時停止するため、ケイデンスの確認は省略します。

スキル管理モード

• 3 つのフェーズすべてに合格した各ステップの後に、自動でコミットを作成します。
• 修正対応中のステップや、未解決のエスカレーションがあるステップは、決してコミットしてはいけません。<PASS-BEFORE-COMMIT> の規則に従い、ステップの最終状態に対するレビューと検証の両方に合格した場合に限り、コミットします。部分的なステップは決してコミットしてはいけません。
• 計画ファイルの進捗更新（Markdown の計画では ✅ 付きの見出しとチェック済みのチェックボックス、HTML の計画では data-status="complete"、バッジのテキスト、✅ 付きの見出し、checked 属性）は、ステップの実装変更と同じコミットに含めます。計画の進捗だけを別にコミットしてはいけません。
• ステップを明記した、明確で内容がわかるコミットメッセージを、Conventional Commits 形式で作成します。
• コミットメッセージに Claude Code や AI による帰属情報を含めてはいけません。Co-authored-by の行、ボットの署名、AI への言及は、いかなる種類のものも含めてはいけません。
• 一時停止のケイデンスは、以下のケイデンス確認によって決まります。

フェーズ 3：実行ペースのゲート（スキル管理モードのみ）

このゲートは条件付きです。次の両方に該当する場合にのみ適用してください。

• ユーザーがフェーズ 2 でスキル管理モードを選択した。
• 計画が複雑である（複数のマイルストーンを含むフォルダー）。

ユーザーがユーザー管理モードを選択した場合は、このゲートを完全にスキップしてフェーズ 4 に進んでください。ユーザー管理モードでは、常に各ステップで一時停止します。

ユーザーがスキル管理モードを選択し、計画が単純（単一ドキュメント）である場合は、このゲートをスキップして連続実行します。一時停止せずにすべてのステップを実行し、計画の完了時に最終サマリーを提示してください。

ユーザーがスキル管理モードを選択し、計画が複雑である場合は、以下のゲートを実行してください。

**このフェーズは実行ペースに関する質問で終了します。それ以外は行わないでください。** どの実行ペースで一時停止するかをユーザーに尋ね、回答を待ってください。ステップの実行を開始しないでください。

次の文言、または同等の文言で、ユーザーにちょうど 2 つの選択肢を提示してください。

計画には複数のマイルストーンがあります。一時停止のペースを選択してください。

1. マイルストーンごとに一時停止 (デフォルト)：各マイルストーンのドキュメントが完了するたびに一時停止し、次に進むかどうかを尋ねます。
2. 完全自動：マイルストーンの境界で一時停止せず、計画全体を実行して最終サマリーを提示します。

続行する前に、ユーザーの回答を待ってください。

事前に示された回答：ユーザーの最初の実行メッセージ（または Git モードゲートへの回答）で、実行ペースがすでに明確に指定されている場合（例：「スキル管理モード、完全自動」「マイルストーンごとに一時停止」）は、その指定をゲートへの回答として受け入れて続行してください。形式的な確認を再度求めないでください。

マイルストーンごとに一時停止

• 各マイルストーンのドキュメントが完了するたびに、マイルストーンのサマリーを提示し、続行するかどうかを尋ねてください。
• マイルストーン内ではすべてのステップを連続して実行し、一時停止するのはマイルストーンの境界のみです。

完全自動

• すべてのマイルストーンにわたる全ステップを、一時停止せずに連続して実行してください。
• 計画の完了時に最終サマリーを提示してください。

フェーズ 4：サブエージェントによるステップ実行

両方のゲートが終了したら、ステップの実行を開始してください。このフェーズの作業はすべて、メインの会話からディスパッチされるサブエージェントによって行われます。

サブエージェントのディスパッチ

Claude Code の Agent ツールを使用して、サブエージェントをディスパッチします。正確なプロンプトテンプレートについては、references/subagent-prompts.md を参照してください。ディスパッチする前に、プレースホルダーを実際の値に置き換えてください。

プランからのプレースホルダー内容の抽出：Markdown のプランでは、該当する見出しの下の内容をそのままコピーします。HTML のプランでは、該当するセクションの内側の内容を抽出します（目的には <p class="step-objective">、受け入れ基準には <section class="acceptance-criteria">、フェーズ 1 の指示には <section class="phase phase-build">、フェーズ 2 には <section class="phase phase-review">、フェーズ 3 には <section class="phase phase-verify">）。意味を持つマークアップ（<ul>、<ol>、<pre>、<code>、<p>、<a>）は保持し、外側のラッパータグは取り除きます。サブエージェントは HTML をそのまま読み取れるため、リストやコードブロックをプレーンテキストに平坦化しないでください。

ビルドサブエージェントのディスパッチ：

• プランにあるステップの目的のテキストをそのまま {{STEP_OBJECTIVE}} に渡します。
• プランにあるステップの受け入れ基準リストをそのまま {{ACCEPTANCE_CRITERIA}} に渡します。
• プランにあるステップのフェーズ 1 の指示をそのまま {{PHASE_1_INSTRUCTIONS}} に渡します。
• ビルドサブエージェントには、ファイルの読み取りと書き込みに対する完全なファイルシステムアクセス権があります。
• サブエージェントの応答から、構造化されたビルド概要を取得します。

レビューサブエージェントのディスパッチ：

• プランにあるステップの受け入れ基準リストをそのまま {{ACCEPTANCE_CRITERIA}} に渡します。
• 取得したビルド概要を {{BUILD_SUMMARY}} に渡します。修正後に再レビューする場合は、元のビルド概要に続けて、このステップで作成されたすべての修正概要を順番に渡します。
• プランにあるステップのフェーズ 2 の指示をそのまま {{PHASE_2_INSTRUCTIONS}} に渡します。
• レビューサブエージェントはディスクから独自にファイルを読み取ります。ビルド概要は状況把握と重点確認のために提供されるものであり、信頼できる情報源として扱うものではありません。
• レビューの応答を解析し、ブロッキングの指摘事項と、レビュー担当者がそれぞれに割り当てた修正クラスを特定します。

検証サブエージェントのディスパッチ：

• プランにあるステップのフェーズ 3 のチェックリストをそのまま {{PHASE_3_CHECKLIST}} に渡します。
• プロジェクトのツールチェーン設定（テストランナー、リンター、型チェッカーのコマンド）を {{TOOL_CHAIN_CONFIG}} に渡します。ツールチェーンはプランの「Tool Chain」テーブルから抽出します。この内容は計画時にユーザーが確認したものであり、正しい情報源です。HTML のプランでは、テーブルは <section id="tool-chain"> 内にあります。プランに「Tool Chain」テーブルがない場合は、フォールバックとしてプロジェクトの設定ファイル（pyproject.toml、package.json、Makefile など）から検出します。解決した設定はキャッシュし、プランでツールチェーンの要件が明示的に変更されない限り、以降の検証ディスパッチでも再利用します。
• 検証サブエージェントは実際のツールを実行し、チェックリスト項目ごとに合否を報告します。
• 検証の応答を解析し、失敗を特定します。チェックが 1 つでも失敗した場合、検証フェーズ全体が失敗となります。

修正サブエージェントのディスパッチ：

• 「失敗時の対応：修正またはエスカレーション」に記載されたルールで許可されている場合に限り、ディスパッチします。
• プランにあるステップの受け入れ基準リストをそのまま {{ACCEPTANCE_CRITERIA}} に渡し、フェーズ 1 の指示をそのまま {{PHASE_1_INSTRUCTIONS}} に渡します。この 2 つで、ステップの意図された範囲を定義します。
• ビルド概要に記載されたファイルリストに、このステップで以前の修正サイクルによって変更されたファイルがあれば、それらも追加して {{STEP_SCOPE}} に渡します。
• 正確な不具合を {{FINDINGS_TO_FIX}} に渡します。対象は、file:line 参照を含むブロッキングのレビュー指摘事項、または完全なエラー出力を含む検証チェックの失敗です。いずれも省略せず、そのまま渡します。
• 修正サブエージェントには完全なファイルシステムアクセス権があります。範囲内で対応可能な問題を修正し、対応できない問題はエスカレーションとして返します。
• 構造化された修正概要を取得し、次にディスパッチする内容を決める前に、その判定を確認します。

実行順序

手順は厳密に順番どおりに、一度に1つずつ実行してください。手順 A は、ビルド、レビュー、検証、および各フェーズで必要となる修正を含む全サイクルを完了し、合格してから、手順 B のビルドフェーズを開始する必要があります。すべての手順で、実行順序は常に次のとおりです。

1. ビルドサブエージェント → 2. レビューサブエージェント → 3. 検証サブエージェント。

レビューまたは検証に失敗した場合は、修正サブエージェントが問題を修正し、レビューと検証の両方を再度実行します。詳しくは、以下の「失敗への対応：修正またはエスカレーション」を参照してください。最終状態に対するレビューと検証の両方に完全に合格した場合にのみ、手順は完了となります。

前の手順のレビュー、修正、または検証がまだ保留中の間は、次の手順のビルドを開始しないでください。複数の手順のビルド（またはレビュー、検証）を同時に実行しないでください。手順内では各フェーズが次のフェーズの開始条件となり、各手順が次の手順の開始条件となります。コーディネーターは一度に1つのサブエージェントだけをディスパッチし、そのサブエージェントから返される構造化された要約だけを保持します。ファイルの内容やツールの出力は保持しません。これにより、長い計画でもコンテキストを簡潔に保てます。

手順が3つのフェーズすべてに合格したら、選択したモードに従って git を処理し、計画ファイルの進捗を更新してから、一時停止するかどうかを判断します。

• ユーザー管理モード：各手順の後に一時停止し、ユーザーが確認してコミットできるようにします。
• スキル管理モード：マイルストーン一時停止のスケジュールにおいてマイルストーンの境界に達した場合を除き、自動的にコミットして一時停止せず次の手順に進み、その場合は一時停止して確認を求めます。シンプルな計画と完全自動モードでは、最後まで中断せずに進めます。

通常の進行中に一時停止するかどうかは、git モードとマイルストーンによってのみ決まり、固定数の手順ごとにまとめることはありません。問題が見つかっても、デフォルトでは実行を一時停止せず、その場で修正します。エスカレーションが未解決の間は、次の手順のビルドを開始しないでください。

失敗への対応：修正またはエスカレーション

レビューでブロッキングの問題が報告された場合、または検証チェックに失敗した場合、その手順は完了していません。ただし、自動的にユーザーへの確認が必要になるわけではありません。問題の多くは、今回の実行で生じた通常の不具合であり、実行中に修正します。ユーザーへの確認は、判断を本当にユーザーに委ねる必要がある場合にのみ行います。

デフォルト：修正。 ブロッキングのレビュー結果と検証チェックの失敗は、修正サブエージェントが自動的に修正します。その後、その手順のレビューと検証を再度実行します。実行中に生じた不具合の修正について、ユーザーに許可を求めないでください。

例外：エスカレーション。 問題にエスカレーションクラスが付与されている場合、手順の修正回数の上限に達した場合、同じサブシステムで失敗が繰り返される場合、または計画で人によるチェックポイントが指定されている場合は、停止して判断をユーザーに委ねます。

この方針はどちらの git モードでも同じです。ユーザー管理モードでは各手順の後に一時停止して、ユーザーが確認してコミットできますが、すべての問題について確認を求めるわけではありません。

エスカレーションのクラス

クラス	エスカレーションする条件	例
design-decision	計画から正しい動作を判断できません。妥当な修正方法が2つあり、どちらを選ぶかはプロダクトまたは設計上の判断になります。	有効期限切れのトークンについて、受け入れ条件に記載がありません。拒否、更新、再認証のどれにしますか？
scope-expansion	修正が、このステップで指定されたスコープ内に収まりません。新しい依存関係の追加、公開インターフェース、スキーマ、設定の契約の変更、またはこのステップで変更する想定のなかったモジュールの編集が必要です。	ハンドラーのバグを修正するには、ほかの4つのモジュールで使われている共有シリアライザーを変更する必要があります。
destructive-or-external	このステップで変更すべきでない状態を修正によって変更します。既存のデータ、列を削除または書き換えるマイグレーション、このステップで作成していないファイル、Git の履歴、リモートまたは本番環境のシステム、認証情報、あるいは作業ツリー外に副作用を及ぼすものが該当します。	既存の列を削除するマイグレーションを適用しないと、失敗するテストが成功しません。
environment	ツール、サービス、または認証情報が不足しているか、正しく設定されていないために検証チェックが失敗しました。問題はコードにありません。	pytest: command not found。型チェッカーがインストールされていません。必須のサービスに接続できません。

これ以外はすべて in-scope であり、確認を求めずに修正します。

クラスを割り当てる担当者。 レビューサブエージェントは、ブロッキングとなるすべての指摘に、上記のいずれかのクラス、または in-scope を割り当てます。報告された出力に基づき、検証の失敗を分類してください。出力からツールの不足、サービスの利用不可、または認証情報の問題が明らかでない限り、in-scope として扱います。最終判断を下すのは修正サブエージェントです。コードを確認しているため、返された指摘は、最初に割り当てられたラベルにかかわらず、エスカレーションとして扱います。

指摘にエスカレーションのクラスが1つでも含まれている場合は、何も修正せずに停止してください。 先に in-scope の指摘を修正してはいけません。設計上の判断によって正しい修正方法が変わる可能性があり、半端に修正されたツリーは、手を加えていないツリーよりもユーザーにとって状況を把握しにくくなります。

修正サイクル

すべての指摘が in-scope で、予算またはチェックポイントのルールが適用されない場合：

1. 修正する不具合を正確に指定して、修正サブエージェントに依頼します。ブロッキングとなる指摘には file:line の参照を添え、失敗したチェックにはエラー出力全体を添えます。
2. ESCALATE が返された場合は停止します。修正した指摘、エスカレーションした指摘、およびその理由を報告します。
3. それ以外の場合は、レビューサブエージェントと検証サブエージェントを、どちらも最初から再実行します。修正によってレビュー合格後のコードが変わり、修正によって合格していたチェックが失敗する可能性もあります。失敗したチェックだけを再実行してはいけません。
4. 両方に合格した場合、そのステップは完了です。通常どおり、Git の処理と進捗管理に進みます。
5. いずれかが再び失敗した場合は、以下の上限が適用される範囲でステップ1に戻ります。

予算

修正サブエージェントを起動する前に、以下のチェックを順番に適用します。最初に該当した時点で処理を終了します。

1. エスカレーション区分 — 指摘事項に in-scope ではないものがある → 停止してエスカレーションします。
2. ステップ予算 — このステップですでに修正サイクルを2回実施している → 停止してエスカレーションします。コードを読んだエージェントが重点的に2回試みてもステップを解決できなかった場合、3回目で解決することはほとんどありません。実際の問題は、表面上そう見える局所的な欠陥ではないことがほとんどです。
3. サブシステム予算 — 今回のセッションで、この指摘事項が属するサブシステムが、異なる2つのステップからの修正サイクルをすでに2回受けている → 停止して、修正の許可ではなくアーキテクチャ上の判断を求めます。サブシステム名を挙げ、ステップ間で見られるパターンを示し、繰り返し発生している指摘事項に共通する点を述べます。2つのステップという条件があることで、単に1つのステップが頑固に行き詰まっている状態ではなく、パターンであると判断できます。同じ箇所で1つのステップが何度も試行錯誤する場合は、すでにステップ予算の対象です。

どれにも該当しなければ、起動します。

サブシステムカウンターの追跡。 指摘事項に記載されたファイルのうち、プロジェクトルートより下で最も近い共通の親ディレクトリ（src/auth/、app/models/）を基準にします。記載されたファイルにルート以下の共通の親ディレクトリがない場合は、最初のブロッキング指摘事項のディレクトリを基準にします。起動した修正サイクルごとに1回カウントを増やし、各サイクルの元となったステップを記録します。2つのステップという条件の判定に必要なためです。このカウンターは人が設計を確認すべきというシグナルであり、正確性を保証する仕組みではないため、基準はおおよそで構いません。

どちらの予算もセッション単位です。新しい実行セッションの開始時にリセットされます。また、ユーザーがエスカレーションに対応し、続行を求めた時点で、該当するカウンターをリセットします。その指示は新たな情報であり、それ以前の試行はステップ予算やサブシステム予算に加算されなくなるためです。

手動チェックポイント

計画自体が人による確認を求めている場合は、一時停止します。たとえば、コードを読んだりツールを実行したりするだけでは判断できず、明示的に確認、承認、許可、または手動検証を求めているステップが該当します。必要な確認内容を正確に提示し、返答を待ちます。これは git モードとは独立しており、ユーザー管理モードで各ステップ後に一時停止する動作とも別です。

エスカレーションの提示

すべてのエスカレーションで、ユーザーに次の4点を伝えます。

• ステップと、失敗したフェーズ。
• すべての指摘事項（file:line の参照を含む）。検証失敗の場合は、確認に必要なエラー出力全体を省略せず提示します。
• 修正せずに実行を停止した理由（エスカレーション区分、使い切った予算、サブシステムのパターン、またはチェックポイント）。
• このステップ中にディスク上で変更した内容があれば、その内容。これにより作業ツリーの状態を明確にします。

その後、返答を待ちます。ユーザーは次のいずれかを選べます。

• 判断や指示を伝え、それを反映して修正を再実行するよう求める。
• 自分で問題を修正し、レビューと検証を再実行するよう求める。
• 計画を修正し、ステップを再実行する。
• ステップをスキップする（完了ではなく、スキップとして記録する）。
• 実行を中止する。

どの方法であっても、ユーザーがステップの続行を選んだ場合は、最終状態に対する完全なレビューと完全な検証の両方に合格するまで、そのステップを完了扱いにしたりコミットしたりしてはいけません。一部の確認しか通っていない状態でコミットしたり、次のステップに進んだりしてはいけません。

参考指摘事項

参考指摘事項は処理をブロックせず、修正もしません。これを修正するのは、勤勉さを装ったスコープクリープです。ステップとともに報告し、重要かどうか、いつ対応するかはユーザーに委ねます。

修正サブエージェントが異議を唱える指摘事項、つまり実際の欠陥ではないと主張するものも、失敗とはみなしません。次のレビューで判断します。新たなレビュアーが同じ指摘事項を再び挙げた場合は、通常どおりサイクルを進め、予算を適用します。ステップが合格した場合でも、異議があったことをステップの報告に記載し、どのような反論があったかをユーザーに伝えます。

失敗してもロールバックされない

すでに合格し、完了としてマークされたステップは、その後に何が起きても完了マーカーを保持します。ステップ B の失敗によってステップ A が取り消されることはありません。エスカレーションが未解決のままステップがセッションを終了する場合は、failed（HTML プラン）として記録するか、マークを付けないままにします（Markdown プラン）。完了としてマークしてはいけません。

進捗の追跡

ステップの最終状態がレビューと検証の両方に合格したら、直ちにプランファイル上で完了としてマークします。具体的な変更方法は、フェーズ 1 で判定したプランの形式によって異なります。

Markdown プラン（.md）：次の 2 つの更新を適用します。

1. ステップ見出しの先頭にチェックマークを追加します。たとえば、### Step 1: Auth middleware を ### ✅ Step 1: Auth middleware に変更します。
2. 完了したステップ内のすべての Markdown チェックボックスについて、- [ ] を - [x] に変更します。対象は、そのステップのフェーズ 3 検証チェックリスト内（およびステップ内のその他の箇所）のすべてのチェックボックスです。

HTML プラン（.html）：ステップの <article class="step" data-step="N"> 要素に、次の 3 つの更新を適用します。

1. data-status 属性を現在の値（通常は pending）から complete に変更します。これは正規の機械可読状態であり、再開時の検出基準となります。
2. <header class="step-header"> 内にあるステップの <h3> 要素のテキストの先頭に ✅ を追加します。たとえば、<h3>Step 1: Auth middleware</h3> を <h3>✅ Step 1: Auth middleware</h3> に変更します。これは人が確認できる状態表示です。
3. ステータスバッジのテキストを更新し、検証チェックボックスに checked 属性を追加します。
   • <span class="status-badge">Pending</span> を <span class="status-badge">Complete</span> に変更します（バッジの色はインライン CSS によって自動的に更新されます）。
   • そのステップの <section class="phase phase-verify"> 内にあるすべての <input type="checkbox" disabled> に checked 属性を追加します → <input type="checkbox" disabled checked>。他のステップに属するチェックボックスは変更しないでください。

これらの変更には Edit（または同等の、対象を絞った文字列置換）を使用します。ファイル全体を書き換えてはいけません。write-blueprint スキルの references/step-template-html.md で定義されている HTML の骨組みでは、安定した ID（id="step-N"）とクラス名が使われているため、対象を絞った編集が容易です。

進捗をセッション間で保持できるよう、すべての変更をディスク上のプランファイルに書き込みます。再開時：

• Markdown プランでは、✅ が先頭に付いていない最初のステップ見出しを探します。
• HTML プランでは、data-status が complete ではない最初の <article class="step"> を探します（通常は pending、または以前のセッションで問題が発生している場合は failed／skipped）。

その他の終端状態（failed、skipped）にも、適切な data-status 値とバッジテキストを使って同じ変更パターンを適用します。完了以外の終端状態では、✅ を先頭に追加しないでください。

ユーザーが以前に実行を一時停止していた場合（ユーザー管理の Git モード）、再開前にプランファイル全体を読み直します。一時停止中にユーザーがプランを編集し、ステップの追加、削除、並べ替え、指示の変更を行っている可能性があります。再開時点のプランファイルの内容に従ってください。

再開時のプラン変更

実行を再開する際は、必ずディスクからプランファイルを読み直してください。前回のセッションや会話の早い段階でキャッシュされたプランを参照してはいけません。ユーザーが次の変更を行っている可能性があります。

• レビュー結果に基づいてステップの指示を編集した。
• 既存のステップの間に新しいステップを追加した。
• 不要になったステップを削除した。
• 依存関係を考慮してステップの順序を変更した。
• 受け入れ基準や検証チェックリストを変更した。

再開時点のプランをそのまま受け入れてください（ただし、ステップの依存関係が壊れているように見える場合（例：削除されたステップで作成される成果物を参照している場合）は除きます）。変更について警告したり、問いただしたりしないでください。

新しい実行セッションでは、ゲートフェーズ（フェーズ 2、および該当する場合はフェーズ 3）も再実行します。進行中のプランを再開する場合も、ゲートを省略してはいけません。ユーザーの Git モードと実行頻度の設定はセッション単位であり、プラン単位ではありません。

ステップレポート

各ステップの完了後に、ステップレポートを提示します。自動修正の内容は、ユーザーに見える状態を保つ必要があります。自動修正された内容を確認できなければ、ユーザーはそれを信頼できるかどうか判断できません。詳細度は実行モードによって異なります。

• ユーザー管理モード（各ステップ後に一時停止）：ステップラベルとステータス、変更されたファイル数、ブロッキングとアドバイザリーの指摘数（アドバイザリーの指摘がある場合は簡潔に列挙）、実行された修正サイクルと各サイクルで修正した内容、異議のある指摘、検証結果の概要（N/N 件のチェックに合格）、実行した git 操作（一時停止してユーザーに確認）を含む完全なステップレポートを提示します。
• スキル管理の継続モード（シンプルな計画、または完全自動）：各ステップレポートは、ステップラベル、ステータス、変更されたファイル数、修正サイクル数、検証結果、コミットハッシュを含む 1 行にまとめます。実行の最後に包括的な概要を提示します。
• スキル管理のマイルストーン一時停止：マイルストーン内の各ステップには、簡潔な 1 行形式を使用します。一時停止のたびに、完全なマイルストーン概要を提示します。

各マイルストーン概要と実行終了時の概要には、修正内容の総括を含めます。どのステップで修正が必要だったか、各サイクルで何を修正したか、異議のある指摘を記載し、自動修正された作業をステップごとの記録から再構成しなくても、まとめて確認できるようにします。

危険信号 — 停止してこのスキルを読み直す

次のような考えが浮かんだ場合、このスキルに違反しようとしています。続行する前に、停止して方針を修正してください。

考え	実際
「この計画は短いから、Git に関する質問は省略します。」	計画の規模にかかわらず、フェーズ 2 は毎回のセッションで実行します。質問してください。
「ユーザーはたった今『進めて』と言ったので、スキル管理モードだと判断します。」	ゲートは毎回のセッションで提示します。スキル管理モードはデフォルトの選択肢ですが、ユーザーがまだ見ていないゲートへの「進めて」は回答ではありません。ゲートについて質問していない場合は、質問してください。
「前回ユーザーはスキル管理モードを選んだから、今回もそれを使います。」	モードの選択は計画単位ではなく、セッション単位です。新しいセッションごとに再度質問してください。
「これは単純な 1 行の編集だから、そのままインラインで変更します。」	いいえ。ビルドのサブエージェントに委任してください。指摘への修正であれば、修正のサブエージェントに委任してください。サブエージェントのみを使うという規則に、規模による例外はありません。
「自分でテストを実行して確認します。そちらのほうが速いので。」	いいえ。検証は検証のサブエージェントで実行します。メインのチャットでは、ステップの実行中にテストを実行しません。
「ビルドのサブエージェントの要約で十分だから、レビューのサブエージェントは省略します。」	いいえ。すべてのステップで 3 つのフェーズをすべて実行します。レビューでは、ファイルをディスクから独立して読み込みます。
「まずすべてのビルドをまとめて実行してから、すべてのレビューを実行します。」	いいえ。ステップは厳密に順番どおりに実行します。各ステップで、次のステップのビルドを開始する前に、ビルド → レビュー → 検証を最後まで完了させます。
「計画にはマイルストーンが 2 つしかないから、実行ペースに関する質問は省略します。」	スキル管理モードでは、複雑な（複数マイルストーンの）計画すべてで実行ペースのゲートが適用されます。マイルストーンが 2 つでも対象です。
「マイルストーンのある計画でユーザー管理モードを選んだ場合も、実行ペースについて質問する必要があります。」	いいえ。実行ペースのゲートが適用されるのは、スキル管理モードの場合のみです。ユーザー管理モードでは、常にステップごとに一時停止します。
「差分をすっきりさせるため、計画の進捗を別のコミットにまとめます。」	いいえ。計画の進捗マーカー（Markdown のチェックボックス、または HTML の data-status／バッジ／チェックボックスの属性）は、ステップの実装と同じコミットに含めます。
「ステップ B の検証に失敗しましたが、ステップ A は合格したので、A をロールバックします。」	いいえ。完了したステップの完了マーカーはそのまま残します。失敗した場合は以降の進行を止めますが、前の進捗を取り消すことはありません。
「レビューで本当のバグが見つかったので、どう対処するかユーザーに尋ねます。」	いいえ。この実行で作り込まれた対象範囲内の不具合は、自動的に修正します。ユーザーに尋ねるのは、エスカレーション対象の種類、予算の超過、サブシステムに見られるパターン、または計画上のチェックポイントに限られます。
「2 件の指摘はエスカレーション対象ですが、残り 3 件は簡単なので、先にそれらを修正します。」	いいえ。1 件でもエスカレーション対象があれば、修正を始める前に停止します。ユーザーの判断によって、適切な修正方法が変わる可能性があります。
「修正で問題が直り、検証も合格したので、再レビューは省略します。」	いいえ。修正によって、レビューに合格したコードが変更されています。レビューと検証を両方とも最初から最後まで再実行してください。
「失敗したのはチェック #4 だけなので、#4 だけ再実行します。」	いいえ。修正によってほかのチェックでリグレッションが発生する可能性があります。毎回、検証チェックリスト全体を再実行してください。
「このテストは間違っているので、ステップを合格させるために xfail にします。」	決してしてはいけません。テストを弱めたり、アサーションを緩めたり、リントルールを緩和して成功させるのは、合格を装ったステップの失敗です。代わりにエスカレーションしてください。
「修正には users テーブルからカラムを削除する必要がありますが、それしか方法がありません。」	エスカレーションしてください。どれほど明らかな修正に見えても、破壊的な変更や外部状態への変更を自動的に行ってはいけません。
「src/auth での 3 回目の修正サイクルです。もう 1 回試せば解決するはずです。」	いいえ。同じサブシステムでの 3 回目のサイクルは、追加のパッチではなく、アーキテクチャ上の判断が必要です。停止して、このパターンを提示してください。
「修正のサブエージェントがエスカレーションしましたが、答えはわかるので自分で指示します。」	いいえ。エスカレーションの判断は、その定義上、ユーザーが行うものです。内容を提示して、返答を待ってください。
「アドバイザリーの指摘は、作業中に簡単に直せます。」	いいえ。アドバイザリーの指摘は決して修正しません。報告して、次に進んでください。
「このステップはほぼ完了しているので、今コミットして、次のステップで整理します。」	いいえ。<PASS-BEFORE-COMMIT>：コミットには、レビューと検証の両方に完全に合格した状態を記録してください。それ以外は認められません。

これらはすべて、停止して該当するフェーズまたは規則を読み直し、記載どおりに従うことを意味します。