Exec Plan

.agent/PLANS.md の仕様に準拠した ExecPlan を作成・管理するワークフロー。 コーディング規約・ドキュメントマップは AGENTS.md を参照。

ロードマップ連携（必須）

1. .agent/roadmap.md に記載された実装タスクには、対応するExecPlanを持たせる（ExecPlan: なし は調査・単純作業タスクのみ許容）。
2. /create-plan でロードマップ対象のExecPlanを新規作成した場合は、対応タスクの ExecPlan: 行を反映する（未記載または なし の場合）。
3. 実装と検証が完了した時点では、まず「ExecPlanの実装と検証が完了した」ことを明示し、完了処理はまだ行わない。
4. 着手した時点で Status を WIP に更新し、着手予定日 が 未定 なら当日を設定する。
5. ロードマップ上で対応タスクを一意に特定できない場合は、推測で更新せずエンジニアへ確認する。
6. 完了処理は .agent/PLANS.md の「完了処理プロトコル」を正本として、ユーザーの確認後にのみ行う。

コミット提案（必須）

1. 実装開始前に、想定されるコミット分割を粗く定義する。粒度は「1コミットで意味が説明でき、レビューしやすい単位」を基準とする。
2. 実装中は、マイルストーン完了や差分の意味が閉じた時点で、ユーザーが判断しなくても次に切るべきコミットを提案する。
3. 各提案には少なくとも以下を含める。
   • 目的の短い説明
   • 対象ファイルまたは変更範囲
   • Conventional Commits 準拠の日本語コミットメッセージ案
4. 変更がまだ混在していてコミット粒度が悪い場合は、そのまま提案せず、どこまで整理してから切るべきかを先に示す。
5. コミット提案は実行の強制ではないが、ExecPlan進行中の標準出力として自律的に提示する。

コマンド

/create-plan <タスク概要>

1. AGENTS.md のドキュメントマップから関連ドキュメント・コードを探索
2. プラン案の骨子を提示（重点: Purpose / Context / Plan of Work / Concrete Steps / Validation） 複雑タスクはマイルストーン分割（目標→作業→成果→検証の物語構造、PoCを先行）
3. エンジニアと設計方針を確認し、非交渉要件（自己完結・初心者実行可能・動作する成果物・用語定義）を検討
4. .agent/PLANS.md テンプレートに従い .agent/plans/YYYY-MM-DD-task-name.md を作成 全12セクション記載、Progress以外は散文、CMS用語を定義、Validationは観察可能な動作で定義 空セクションは見出しのみ残す（プレースホルダ説明は書かない）
5. ロードマップ対象タスクの場合のみ、.agent/roadmap.md の対応タスクの ExecPlan: 行を反映する（未記載または なし の場合）。Status や着手予定日は変更しない（実装着手はユーザーの明示指示後）
6. /validate-plan を自動実行
7. プラン作成完了をユーザーに伝えて停止する。「実装してください」「着手してください」「/work」など実装を明示する指示があるまで、コード変更・ブランチ作成・コミット・PR 作成は行わない。想定コミット単位は Artifacts and Notes に記録するに留める

トークン効率の原則（精度優先）:

• 実装精度・再現性を落とさない範囲で簡潔に書く（必要十分な情報量を維持）
• 同一趣旨の説明を複数セクションに重複記載しない
• 長大なコード全文は原則避け、変更意図・対象箇所・確認コマンドに集約する
• Concrete Steps は「編集対象ファイル / 実行コマンド / 期待観測結果」を基本フォーマットにする

探索の重点: assets/docs/architecture.md（処理フロー）、assets/docs/events-and-plugins.md（フック）、assets/docs/core-issues.md（既知の課題）、対象ファイルの既存パターン

移行タスクでは追加で: 旧API使用箇所のGrep棚卸し、旧→新の置換パターン表、モジュール単位の分割

補助ツール（CLI導入済みの場合）

php evo config:show [key] / db:tables [--pattern] / db:describe <table> / db:count <table> [--where]

/validate-plan [path]

references/quality-checklist.md に基づき品質チェック: 必須12セクション、非交渉要件・アンチパターンを検出し改善提案

/update-plan [path]

各マイルストーン完了時・中断時にこまめに呼び出す:

1. Progress をタイムスタンプ付きで更新（完了チェック、新規項目追加）
2. Surprises & Discoveries に追記（観察+根拠）
3. Decision Log に日付・著者・根拠・代替案を記録
4. 完了マイルストーンの Progress 詳細を1行の要約に圧縮（トークン節約）
5. コア側の課題（UI結合・設計上の制約・技術的負債等）を発見した場合は assets/docs/core-issues.md に追記（発見日・発見元・ファイル・課題・改善案・関連ロードマップ）
6. 差分の意味が閉じた時点で、次に推奨するコミット単位とコミットメッセージ案を提示する
7. 当該ExecPlanがロードマップ対象で未完了なら、.agent/roadmap.md の対応タスクを Status: WIP に維持し、必要なら 最終更新 を更新する
8. 当該ExecPlanが完了条件を満たした場合は、実装と検証の完了を明示し、「完了処理を進めてよいか」を必ず確認する
9. ユーザー確認後にのみ、.agent/PLANS.md の「完了処理プロトコル」に従って完了処理を行う
10. 対応タスクを一意に特定できない場合は、推測で完了処理を進めず確認を求める
11. 完了処理が終わったら、ロードマップ同期とアーカイブ完了を明示して完了を告げる
12. スキル自己成長対象タスクでは、完了同期後に .agent/PLANS.md の「完了処理プロトコル」step 8 に従う。skill:complete 実行後は learning.json / proposal.json の内容を要約し、この学びをスキルへ反映しますか？ はい・いいえ と確認してから次へ進む

意思決定の閾値

自律判断可能: コードベース探索、関連ドキュメント読み込み、プランのフォーマット整形

要相談: 設計方針の選定、影響範囲の判断、実装の優先順位、代替案のトレードオフ

明示指示が必要（推測・間接指示で着手しない）: コード変更、ブランチ作成、コミット、PR 作成など実装に関わる一切の操作。「PR を作成してください」「ロードマップに追加してください」などは実装指示ではない