plan

Plan

エージェントツールキットのパイプラインで、plan フェーズを実行しています。Spine フェーズ 3 です。担当するのは、確定済みの architecture.md と decisions.md の決定事項を、plan.md に完全かつ詳細なタスクリストとして分解することです。implement に進む前に、重要な曖昧さをすべて解消してください。

ヘルパースクリプトの実行

このスキルには、独自の scripts/ ディレクトリにあるヘルパースクリプトが含まれています（この SKILL.md と同じ場所にインストールされています）。SKILL_DIR にこのスキルの絶対パスを設定します。このファイルの末尾に このスキルのベースディレクトリ として示されています。その後、プロジェクトのルートディレクトリからスクリプトを実行します（スクリプトは、プロジェクトの .changes/ および CONTEXT.md ファイルを操作します）。

SKILL_DIR="<absolute path to this skill's directory>"

以下に示す node "$SKILL_DIR/scripts/..." コマンドは、すべてこの設定に依存します。packages/build/ は参照しないでください。このパスはツールキットの開発用リポジトリにのみ存在し、インストール済みのスキルにはありません。

取り組み方

ここではアーキテクチャ上の決定を行いません。specify で解決しておくべき曖昧さが見つかった場合は、それを指摘し、ユーザーに specify を再実行するよう伝えてください（差し戻し）。答えを勝手に作らないでください。

計画では、各セクションについて、実装担当者に必要なコンテキスト、観察可能な結果、制約、検証方法を示してください。ただし、非公開の実装メカニズムは決めないでください。

計画は機能仕様であり、実装成果物ではありません。外部から確認できる入力、出力、状態遷移、検証、エラー、不変条件、順序保証、受け入れの証拠を記述してください。非公開の制御フロー、ヘルパーの分割、ローカルデータ構造、内部呼び出し順序、ソースコードの本体、言語に依存した擬似コード、フェンス付きソースコードブロックを指定しないでください。公開済みまたは確定済みのシンボルを示し、decisions.md で契約が確定している場合に限り、1 行のシグネチャを記載してください。非公開、ローカル、可逆的な実装方法は、一般的で慣用的なものを実装担当者が選びます。

前提条件

manifest.yaml を読み込み、以下を確認してください。

• phase が plan である（specify の承認は approved）。
• approvals.plan が pending である。
• architecture.md と decisions.md の両方が存在する。

前提条件を満たさない場合は、問題点をユーザーに伝えてください。

最初に change-brief.md を読み込み、その後、計画に必要な決定事項や接点に限って architecture.md と decisions.md を開いてください。references/engineering-fundamentals.md を読みます。スコープに含まれる言語ごとに、利用可能であれば idioms スキルを使用してください。パックが利用できない場合は、リポジトリの規約とツールを使用してください。このガイダンスは、言語に反する計画を避けるためのものであり、非公開の実装表現を細かく指示するためのものではありません。

フェーズ 1：セクションの分割

実装を論理的なセクションに分割します。ルールは以下のとおりです。

• 各セクションは、単独で実行できる必要があります。実装担当者は、作業対象のセクションだけを読みます。
• セクションはコンポーネント、機能、またはレイヤーに対応させ、任意の行数で分けないでください。
• 各セクションの完了時に、テストがすべて成功する状態にします。セクションごとのリファクタリングは行いません。
• 最後の実装セクションの後に、変更全体を対象とする独立レビューと、動作を変えないリファクタリングを行う レビューセクション を 1 つ設け、その後にドキュメントの整合を行います（必須）。

慣例に沿ったセクション分割は自分で決めてください。分割案の違いが重要性のしきい値を超える場合に限り、ユーザーに確認してください。それ以外の場合、通常の分解について承認を求めないでください。

フェーズ 2：plan.md の作成

各セクションについて、references/templates/plan.md.tmpl に従います。

テストタスク

• このセクションで扱う、確実性が高い接点ごとに、少なくとも 1 つのテストタスクを設けます。ラベルは [seam: <id>, firmness: firm] とします。
• 適宜、確実性の低い接点のテストタスクも設けます。ラベルは [seam: internal, firmness: soft] とします。
• 各セクションでは、テストタスクを実装タスクより先に記載します（レッド・グリーンの規律）。
• 何を検証するテストなのかを具体的に示し、予定するファイルパスを記載します。

実装タスク

• 各タスクは、具体的で範囲が定まった成果を 1 つ扱います。ファイル名または確認済みの契約を示しますが、実装者が使う非公開のヘルパー、型、トレイト、分解方法を作り出してはいけません。
• 対象ファイルのパスを含めます。
• 必要な成果を特定するために十分なコンテキストを含めます。対象パス、確認済みの契約（該当する場合）、観測可能な動作、関連する状態遷移、検証／エラーの意味、保証事項、受け入れの証拠を記載します。
• 非公開のヘルパー、ローカル表現、制御フロー、同等の慣用的な実装方法は、implement に任せます。
• 実装する決定または受け入れ基準を参照します：（implements [SEAM-]) または (per decisions.md Q)。

たとえば、永続化タスクでは、検証済みの入力、原子性または順序の保証、承認済みのエラー契約、観測可能な結果を記載します。非公開のヘルパー、7 段階の制御フロー手順、関数本体を指定してはいけません。慣用的なソース表現は implement が決定します。

検証タスク（各セクション）

• [ ] テストを実行 — セクションがグリーンベースラインに到達する

レビューセクションのタスク（全セクションの後に 1 回）

• [ ] 新しい監査担当者が、適用可能な広範な探索を 1 回実施し、カテゴリ、証拠、影響、代替案を含む、統合された RV-NNN ブロッカー／重大指摘バッチを記録する
• [ ] バッチ全体に対し、動作を維持する修正を 1 件適用する（ファームシームのテストは引き続きグリーン）
• [ ] 修正後にテストスイート全体がグリーンになる
• [ ] 新しい別の検証担当者が元の RV ID のみを確認する。対象を絞った修正／再検証は最大 1 回とし、review-log.mjs で承認を記録する

フェーズ 3：トレーサビリティチェック

最終確定の前に、次を確認します。

1. architecture.md と decisions.md の各受け入れ基準が、少なくとも 1 つのタスクに対応していること。
2. 各ファームシームに、少なくとも 1 つのファームシームテストタスクがあること。
3. architecture.md で承認された各リファクタリングに、明示的なタスクがあること。

plan.md のトレーサビリティ表に記入します。対応していない基準がある場合は、不足するタスクを追加します。

フェーズ 4：差し戻しチェック

計画作成によって重大な決定の不足が 1 つ以上明らかになった場合は、それらをまとめて作業を停止します。ユーザーに次のように伝えます。

"決定事項に曖昧さがあり、本来 specify で解決されているべきでした：[説明]。これについて信頼できる計画タスクを作成できません。続行する前に specify を実行して解決してください。"

差し戻しを記録します。

  node "$SKILL_DIR/scripts/kickback-log.mjs" --id <id> --type defect --phase plan --impact specify --missed "<description>"

重大な決定が不足している場合は --impact specify を使用します。チェックリストのトレーサビリティまたはタスクの詳細のみを変更する必要がある場合は --impact plan を使用します。これにより specify の承認が維持されます。回答を作り出したり、影響を受ける成果物が解決される前に続行したりしてはいけません。

フェーズ 5：ファイルを書き込む

書き込み先：.changes/active/<id>/plan.md

フェーズ 6：承認

セクション数、タスクの合計数、ファームシームテスト数、トレーサビリティチェックの結果を提示します。次のように尋ねます。

"トレーサビリティチェックに合格しました。すべてのファームシームにテストタスクがあります。承認前に決定論的な成果物検証を実行します。計画の承認を許可しますか？（これにより implement に進みます。）"

承認された場合：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval plan --approve

ユーザーに 次に implement を実行してください。 と伝えます。

参考ファイル

• references/seam-and-test-taxonomy.md — ファームネスモデル、テストタスクのラベル付け規則
• references/manifest-schema.md — 差し戻しの記録
• references/change-lifecycle.md — implement が想定する内容
• references/adversarial-review.md — 範囲を限定したレビューサイクルと RV-* 指摘事項
• references/templates/plan.md.tmpl
• idioms スキル — 対象範囲に含まれるすべての利用可能なパックを読み込む
• references/engineering-fundamentals.md — 言語をまたぐデータ、状態、抽象化、リソース制限のガイダンス