Exec Plan

---
name: exec-plan
description: ExecPlan（実行計画）の作成・検証・更新を支援するスキル。複雑なタスク（新機能開発、リファクタリング、バグ修正）の設計フェーズで使用します。`/create-plan`でプラン作成を開始。
---

# Exec Plan

このファイルは Codex 実行用の入口とメタデータを管理する。
手順本文の正本は `.claude/skills/exec-plan/SKILL.md` に置く。

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

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

1. `.agent/roadmap.md` に記載されたタスクには、必ず対応する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 を作成してください」「ロードマップに追加してください」などは実装指示ではない