create-ai-project 1.20.9 → 1.22.0

package/.claude/commands-ja/prepare-implementation.md

@@ -0,0 +1,191 @@
+---
+description: 実装着手前に readiness を検証しギャップを解消する
+---
+
+**コンテキスト**: 作業計画承認と build/implement フェーズの間に挟む任意の readiness フェーズ。実装が Phase 1 から観測可能であることを確認し、ギャップがあれば Phase 0 タスクで解消する。readiness 基準が既に満たされている場合は no-op で終了するため、本レシピは無条件に呼び出しても安全。
+
+## オーケストレーター定義
+
+**コアアイデンティティ**: 「私はオーケストレーターである。」（subagents-orchestration-guideスキル参照）
+
+**実行プロトコル**:
+1. **全作業をAgentツールでサブエージェントに委譲** — サブエージェント（task-executor / task-executor-frontend / quality-fixer / quality-fixer-frontend）の呼び出し、成果物パスの受け渡し、結果の報告
+2. **自己完結スコープ**: ギャップが見つかった場合、本レシピは解消タスクの生成と、subagents-orchestration-guide「標準フロー」で説明される標準4ステップサイクルでの実行の**両方**を行う。readiness基準がパスするか残存ギャップがエスカレーションされた時点でレシピは完了する。
+3. **No-op終了**: readinessスキャンで失敗基準がない場合、解消タスクは生成せず即座に終了する。本ブランチのファイル変更は作業計画書本体のみ — `Implementation Readiness:`ヘッダを `ready` に昇格し、Readiness Reportセクションを永続化する。コードやテストファイルには触れない。
+
+作業計画書: $ARGUMENTS
+
+## 適用される条件
+
+build/implement フェーズの前に、以下のいずれかが該当する場合に実行する:
+- 作業計画書の検証戦略がコードベースにまだ存在しないコマンド・ファイル・関数・エンドポイントを参照する Design Doc から作成された
+- 作業計画書にE2Eテストスケルトンが含まれる（seed data、auth fixture、環境変数、または外部モックが未対応の可能性あり）
+- 作業計画書がUIコンポーネントに触れるが、それらの視覚状態を描画するfixtureエントリや開発用ルートがない
+- ローカルレーンが本機能領域でエンドツーエンドに動作することをチームが事前に確認していない
+
+いずれにも該当しない場合、Step 2のreadinessスキャンで失敗基準はゼロとなり、レシピはno-opで終了する（冒頭の「コンテキスト」参照）。
+
+## Readiness基準
+
+各基準は `pass` / `fail` / `not_applicable` のいずれかを生成する測定可能なチェックで、根拠を引用する。
+
+| ID | 基準 | パスの根拠 |
+|----|-----|----------|
+| R1 | 検証戦略の参照が解決できる | 作業計画書の検証戦略セクションで参照される全コマンド、ファイルパス、関数、エンドポイント、テストが、コードベースに既存（Glob/Grepで検証）か、本計画内のいずれかのタスクの成果物である |
+| R2 | E2E前提条件への対応 | E2Eスケルトンが存在する場合: スケルトンコメントで言及される全前提条件（seed data、auth fixture、env var、外部モック）が、コードベースに存在するか、本計画のPhase 0タスクでカバーされる |
+| R3 | Phase 1の観測性 | 最初の実装フェーズに、タスク完了時点で実行可能な「動作検証手法」を持つタスクが少なくとも1つ存在する。当該検証は、タスク開始前に存在する成果物（既存コード、先行のPhase 0成果物、または当該タスク自身の出力）のみで実行できる |
+| R4 | UI描画面の存在 | 計画がUIコンポーネントを実装する場合: 影響を受けるコンポーネントを描画するためのfixtureエントリ、開発ルート、Storybookストーリー、またはそれに相当する描画面が存在する、もしくはPhase 0タスクで追加される |
+| R5 | ローカルレーンの手順 | 作業計画書または参照先ドキュメントに、手動検証用のローカル環境起動コマンド（起動コマンド、デフォルトポート、seed手順）が記録されている |
+
+R4とR5は、トリガー信号が作業計画書に現れた場合のみ評価する。それ以外は `not_applicable` をマークする。
+
+## 実行前提条件
+
+```bash
+# 作業計画書の存在確認
+! ls -la docs/plans/*.md | grep -v template | tail -5
+```
+
+**状態チェック**:
+- 作業計画書が存在する → Step 1へ進む
+- 作業計画書がない → 停止して報告: 「承認済みの作業計画書が必要です。先に上流の計画フェーズを完了してから本レシピを再起動してください。」
+
+## 実行フロー
+
+### Step 1: 入力の読み込み
+
+`$ARGUMENTS`で渡された作業計画書のパスを読み込む。以下を抽出する:
+- 検証戦略セクション（正しさの証明方法 + 早期検証ポイント）
+- 品質保証メカニズム表
+- 設計-計画トレーサビリティ表
+- 計画書ヘッダで参照されるテストスケルトン
+- 各フェーズのタスクを含むフェーズ構成
+- 参照されるDesign Doc（複数の場合あり）とUI Spec（存在する場合）
+
+### Step 2: Readinessスキャン
+
+各基準 R1〜R5 について:
+1. Readiness基準で定義されたスキャンを Read / Glob / Grep で実行する
+2. 結果を記録する: `pass` / `fail` / `not_applicable`
+3. 根拠を引用する: `pass`はfile:line、`fail`は未解決の参照、`not_applicable`は不在のトリガー信号
+
+結果に関わらずReadiness Report（出力フォーマット参照）を組み立てる。
+
+### Step 3: No-opチェック
+
+該当する全基準が `pass`（`fail`ゼロ）の場合:
+- 作業計画書のヘッダブロック直後に `## Implementation Readiness Report` セクションを追記（既存なら置換）する。出力フォーマットで定義したReadiness Reportのmarkdownを使用する
+- 作業計画書ヘッダの `Implementation Readiness:` 行を `ready` に更新する（行が無ければ `Related Issue/PR:` の後に挿入する）
+- Readiness Reportをユーザーに提示する
+- `outcome: ready, gaps_resolved: 0` で終了する
+- 本ブランチのファイル変更は上記の作業計画書への変更のみ
+
+`fail`が1件以上ある場合 → Step 4へ進む。
+
+### Step 4: 解消タスクの計画
+
+各 `fail` 基準について:
+1. ギャップを埋める最小単位の具体的タスクを決定する（例: 「ComponentXの loading/empty/error 状態をカバーするfixtureエントリを追加」、「E2Eユーザーfixture用のseedスクリプトを追加」、「ローカル起動コマンドを docs/run/local.md に文書化」）
+2. すべての対象ファイルパスを以下のマーカーに照らしてタスクの**レイヤー**を判定する:
+   - **backend**: 全対象ファイルパスが `**/api/**`、`**/server/**`、`**/services/**`、`**/backend/**`、`**/handlers/**`、`**/repositories/**` のいずれかにマッチする場合
+   - **frontend**: 全対象ファイルパスが `**/components/**`、`**/pages/**`、`**/web/**`、`**/frontend/**`、`**/*.tsx`、`**/*.jsx` のいずれかにマッチする場合
+   - **prep-only**（言語/ランタイムに依存しない、機能実装ではない準備系のタスク）: 全対象ファイルパスが `docs/**`、`scripts/**`、`tests/fixtures/**`、`tests/e2e/data/**`、`tests/e2e/fixtures/**`、ルート直下の設定ファイル（`*.json`、`*.yml`、`*.config.*`）のいずれかにマッチする場合。**backend**のexecutor / quality-fixer（`task-executor` + `quality-fixer`）にルーティングする — Reactに固有の関心事を含まないため
+   - **mixed**（対象ファイルがbackendとfrontendの両方のマーカーをまたぐ、または機能マーカーとprep-onlyマーカーをまたぐことで実装と準備が同居する）→ ユーザーにエスカレーション。レイヤーごとにタスクを分割するよう依頼する
+   - **unrecognized**（上記いずれのマーカーにもマッチしない — 例: プロジェクトが使用する非標準のトップレベルディレクトリ）→ ユーザーにエスカレーション。(a) どのexecutor / quality-fixerが本タスクを実行すべきか判断するか、(b) プロジェクトが異なるパスを使用している場合はマーカーを更新するかを依頼する
+
+   ルールは上記の順で適用する。最初に一致したルールが採用される。`unrecognized` は backend にデフォルトする catch-all ではなく、最後のフォールバックとして機能する。
+3. Phase 0タスクファイルを `docs/plans/tasks/{plan-name}-backend-task-prep-{NN}.md`（backend または prep-only）または `docs/plans/tasks/{plan-name}-frontend-task-prep-{NN}.md`（frontend）として、documentation-criteriaスキルのタスクテンプレートで作成する。`-task-prep-`セグメントは本レシピが prep タスクと実装タスクを区別できるようにし、他レシピで使われる `{plan-name}-{layer}-task-*` マッチャーも維持する。prep-only タスクは Step 5 で backend executor にルーティングされるよう `-backend-task-prep-` のファイル名を使用する
+4. これらのタスクをPhase 0として（Phase 1の前に）作業計画書に挿入する
+
+提案された解消タスクのリストを AskUserQuestion でユーザーに提示する。明示的な承認後にのみ進める — これは本レシピ内で唯一の人間ゲートである。
+
+### Step 5: 解消タスクの実行
+
+各解消タスクについて、`task-executor → エスカレーションチェック → quality-fixer → commit` の4ステップサイクルを実行する（subagents-orchestration-guide「標準フロー」で定義され、レイヤールーティングは「Layer-Aware Agent Routing」に従う）:
+
+1. **Agentツール** — ファイル名のレイヤーセグメントでルーティング（subagents-orchestration-guideのLayer-Aware Agent Routing表に対応）:
+   - `*-backend-task-prep-*` → `subagent_type: "task-executor"`
+   - `*-frontend-task-prep-*` → `subagent_type: "task-executor-frontend"`
+   - 認識可能なレイヤーセグメントが無いファイル名 → エスカレーション（このファイルは存在し得ない。Step 4が防いでいる）
+2. orchestration-guideに従いエスカレーションをチェック
+3. **quality-fixer** — 同じファイル名のレイヤーセグメントでルーティング:
+   - `*-backend-task-prep-*` → `"quality-fixer"`
+   - `*-frontend-task-prep-*` → `"quality-fixer-frontend"`
+4. quality-fixer が `approved` を返したら**コミット**
+
+各サブエージェントプロンプトの末尾に下記の「サブエージェントのスコープ境界」ブロックを必ず付与する。
+
+### Step 6: 再スキャン、Readiness Reportの永続化、ヘッダ更新、クリーンアップ、終了
+
+1. **再スキャン**: 全解消タスクのコミット後、Step 2のreadinessスキャンを再実行する。
+
+2. **Readiness Reportを作業計画書本体に永続化する**: 作業計画書のヘッダブロック直後に `## Implementation Readiness Report` セクションを追記（既存なら置換）する。出力フォーマットで定義したReadiness Reportのmarkdownを使用する。下流のbuild/implementレシピは、ヘッダが `escalated` の場合に本セクションを読み、残存ギャップをユーザーに提示する。
+
+3. **作業計画書ヘッダの更新**: 作業計画書内の `Implementation Readiness: pending` 行を特定し、再スキャンの結果に応じて書き換える:
+
+   | 再スキャン結果 | 新しいヘッダ値 |
+   |--------------|--------------|
+   | 該当する全基準が `pass` | `Implementation Readiness: ready` |
+   | `fail` が1件以上残存 | `Implementation Readiness: escalated` |
+
+   行が存在しない場合（古い作業計画書フォーマット）、`Related Issue/PR:` 行の後に挿入する。
+
+4. **最終クリーンアップ**: 本実行で作成した、現在の `{plan-name}` に該当するprepタスクファイル（`docs/plans/tasks/{plan-name}-backend-task-prep-*.md` および `docs/plans/tasks/{plan-name}-frontend-task-prep-*.md`）と、prepフェーズ用に生成されたフェーズ完了ファイル（`docs/plans/tasks/{plan-name}-phase0-completion.md` が存在する場合。prepタスクはPhase 0に置かれるため）をすべて削除する。他の計画のprepタスクファイルはスコープ外 — 本レシピは現在の実行で作成したものだけを削除する。作業内容はコミット済みで、`docs/plans/`はレシピ実行間で保持しない一時的な作業状態である。作業計画書本体は下流のbuild/implementフェーズのために保持する。
+
+5. **終了**:
+
+   | 再スキャン結果 | アクション |
+   |--------------|----------|
+   | 該当する全基準が `pass` | `outcome: ready, gaps_resolved: N` と最終Readiness Reportを添えて終了する |
+   | `fail` が1件以上残存 | `outcome: escalated` で終了する — 残存する失敗を次のアクションの推奨と共にユーザーに提示する。再スキャンは本レシピにとって終端評価である。さらなる解消には更新された入力でユーザーが本レシピを再起動する必要がある。 |
+
+## サブエージェントのスコープ境界
+
+本レシピから呼び出すサブエージェントプロンプトの末尾に以下のブロックを必ず付与する:
+
+```
+Scope boundary for subagents:
+Operate within the task scope and referenced files in the prompt.
+Use loaded skills to execute that scope.
+Escalate when the required fix or investigation falls outside that scope.
+```
+
+## 出力フォーマット
+
+レシピ終了時にユーザーに提示する最終レポート:
+
+```
+## Implementation Readiness Report
+
+作業計画書: [path]
+結果: ready | escalated
+解消ギャップ数: [N]
+
+### Readiness基準
+
+| ID | 結果 | 根拠 |
+|----|-----|-----|
+| R1 | pass / fail / not_applicable | [file:line または "missing: <未解決の参照>"] |
+| R2 | ... | ... |
+| R3 | ... | ... |
+| R4 | ... | ... |
+| R5 | ... | ... |
+
+### 実行された解消タスク（gaps_resolved > 0 の場合）
+- [タスクファイルパス] — [1行サマリ] — committed
+- ...
+
+### 残存ギャップ（outcome が escalated の場合）
+- [基準ID]: [未解決の参照] — 次のアクション: [推奨]
+```
+
+## 完了基準
+
+- [ ] 作業計画書が読み込まれ、検証戦略 / E2E参照 / フェーズ構成が抽出されている
+- [ ] readinessスキャンが実行され、各基準の結果と根拠が記録されている
+- [ ] 全`pass`の場合のno-op終了、または解消タスクの生成・承認・4ステップサイクル実行のいずれかが行われている
+- [ ] 最後の解消タスクのコミット後に再スキャンが実行されている
+- [ ] `## Implementation Readiness Report` セクションが作業計画書本体に永続化されている
+- [ ] 作業計画書ヘッダの `Implementation Readiness:` 行が `ready` または `escalated` に更新されている
+- [ ] prepタスクファイル（および生成された場合のPhase 0フェーズ完了ファイル）が `docs/plans/tasks/` から削除されている
+- [ ] 最終レポートがユーザーに提示されている

package/.claude/commands-ja/project-inject.md

@@ -1,86 +1,114 @@
 ---
-description: プロジェクト固有のコンテキストをproject-contextスキルに注入
+description: テンプレート駆動ヒアリングで project-context スキルを設定
 ---
 
-**コマンドコンテキスト**: AIの実行精度を高めるプロジェクト固有の前提情報を収集し、project-context SKILL.mdを更新する。
+**コマンドコンテキスト**: `/project-inject` は AI の実行精度を高めるプロジェクト固有の前提情報を収集し、`project-context` スキルに書き込む。ヒアリングはテンプレート駆動で、セクションカタログは `references/template.md` に格納されており、新しい次元を追加する場合はこのテンプレートを編集する。
 
 ## なぜ必要か
 
-CLAUDE.mdのセッション初期化で`project-context`スキルが毎セッション読み込まれる。ここで収集した情報が、全タスクにおけるAIの判断精度に直接影響する。
+CLAUDE.md のセッション初期化で `project-context/SKILL.md` が毎セッション読み込まれる。ここで収集した情報は全タスクにおける AI の判断精度に直接影響する。設定済み SKILL.md は最小限に保つ — 1 行ごとに毎セッションのコンテキスト予算を消費する。
 
-**AIの実行精度に寄与する情報のみ収集する。**
+## 実行フロー
 
-## 実行プロセス
+Step 1 を開始する前に以下のステップを TaskCreate で登録し、進捗に応じて各タスクのステータスを更新する。
 
-以下のステップをTaskCreateで登録し、順番に進行する。
+### Step 1: 入力読み込み
 
-### Step 1: 現状把握
+1. `.claude/skills/project-context/SKILL.md` を読み、現在の状態を把握する。本文に含まれるカタログセクション見出し（`## プロジェクト概要`、`## ドメイン制約`、`## 開発フェーズ`、`## ディレクトリ規約`、`## 外部リソース`）の数で 2 つのケースを区別する:
+   - **未設定** — 本文中のカタログセクション見出しが 0 個。
+   - **設定済み** — 本文中のカタログセクション見出しが 1 個以上。
+2. `.claude/skills/project-context/references/template.md` を読み、セクションカタログを取得する。
 
-現在のproject-contextスキルとpackage.jsonを読む：
-- `.claude/skills/project-context/SKILL.md`
-- `package.json`（name、description）
+**チェックポイント**: `template.md` のセクションカタログと、`SKILL.md` の設定済み / 未設定の状態を保持している。
 
-project-contextが設定済み（「未設定」マーカーがない）の場合、上書きか更新かをユーザーに確認する。
+### Step 2: セクション計画の作成
 
-### Step 2: プロジェクトコンテキストの収集
+カタログの全セクションを対象に、セクションごとの計画（`add` / `keep` / `update` / `remove` / `skip`）を作成する。
 
-AskUserQuestionで段階的に収集する。
+**未設定の場合**:
+- プロジェクト概要: `add`（必須。このセクションの採用ルールは「常に」）。
+- 残りのカタログセクションそれぞれについて、AskUserQuestion: 「`<セクション名>` セクションを追加するか？」 選択肢: 「はい、追加する」 / 「いいえ、スキップ」。回答に応じて `add` または `skip` を割り当てる。
 
-**ラウンド1: プロジェクトの本質**
-- このプロジェクトは何をするものか？（1-2文）
-- どのドメインに属するか？（例：金融、ヘルスケア、開発者ツール、EC）
+**設定済みの場合**:
+- 内容が記入されているセクションそれぞれについて、AskUserQuestion: 「既存の `<セクション名>` セクションへのアクションは？」 選択肢: 「現状維持」（`keep` を割り当て） / 「更新 — 既存内容を置き換え」（`update` を割り当て） / 「削除 — 再構築する SKILL.md から除外」（`remove` を割り当て）。
+- 既存 SKILL.md でまだ空のままのカタログセクションそれぞれについて、AskUserQuestion: 「`<セクション名>` セクションを追加するか？」 選択肢: 「はい、追加する」（`add` を割り当て） / 「いいえ、スキップ」（`skip` を割り当て）。
 
-**ラウンド2: ドメイン制約**（ラウンド1の回答に基づいて質問）
-- AIが必ず守るべきドメイン固有のルールはあるか？ラウンド1のドメインに応じた例を提示する（例：金融なら「全ての変更操作に監査ログ必須」、ヘルスケアなら「ログ出力は匿名化された患者IDを使用」）。
-- 最大3つ。AIが無視するとバグやコンプライアンス違反になるもののみ。
+**チェックポイント**: 全カタログセクションが `add`、`keep`、`update`、`remove`、`skip` のいずれか 1 つの区分を持つ。
 
-**ラウンド3: 開発コンテキスト**
-- 開発フェーズ：プロトタイプ / 本番開発 / 運用中
-- AIが従うべきディレクトリ規約やファイル配置ルールはあるか？（なければスキップ）
+### Step 3: セクションごとのヒアリング実行
 
-### Step 3: 生成と書き込み
+`add` または `update` 区分のセクションそれぞれについて、`template.md` がそのセクション向けに定義するヒアリングプロトコルを実行する。カタログには各軸の AskUserQuestion 文と選択肢、採用ルール、セクションごとの出力構造が記述されている。
 
-収集した情報からproject-context SKILL.mdを生成する。以下の原則に従う：
+**外部リソースセクション**: `template.md` § 外部リソース のルーティングプロトコルに従う。当該セクションがドメインのマルチセレクト、ドメインとファイルの対応、軸ごとの出力スキーマを所有しており、このコマンドはそれに委譲する。
 
-**記述の原則：**
-1. AI判断可能：測定・検証可能な基準のみ（「迅速に」→「5秒以内」）
-2. 曖昧さの排除：具体的な数値・条件・例示を含める
-3. 肯定形：「〜しない」より「〜する」の形で記述
-4. 最小限：AIの実行精度に影響するもののみ
+**曖昧ルールの差し戻し**（`add` および `update` 区分の全セクションに適用）: ユーザー提供のルールが主観的な表現の場合（例: 「パフォーマンスに気をつける」）、フォローアップで尋ねる: 「AI はこのルールが pass か fail かをどのように検証できるか？ 測定可能なチェックに書き換える、または 'drop' と返答すれば省略する。」 測定可能な形で届いたルールはそのまま採用し、主観的なものはユーザーが書き換えた版で置き換え、'drop' の場合はそのルールを省略する。
 
-**出力先**（両方更新する）：
-1. `.claude/skills/project-context/SKILL.md`（アクティブ、Claudeが読む方）
-2. 対応する`skills-{lang}/project-context/SKILL.md`（`.claudelang`で現在の言語を確認）
+**チェックポイント**: `add` および `update` 区分の各セクションで収集した内容と、`keep` 区分のセクションの原文をそのまま保持している。
 
-**構造：**
-```markdown
----
-name: project-context
-description: AIの実行精度に必要なプロジェクト固有の前提情報を提供。プロジェクト構成確認時に使用。
----
+### Step 4: SKILL.md の組み立てと書き込み
+
+再構築する SKILL.md を以下の順序で連結して構築する:
+
+1. フロントマター — 以下の正本ブロックをそのまま書き込む:
+   ```
+   ---
+   name: project-context
+   description: AIの実行精度に必要なプロジェクト固有の前提情報を提供 — ドメイン制約、開発フェーズ、ディレクトリ規約、外部リソースのアクセス方法。セッション開始時、プロジェクト構成確認時、またはタスクがドメインルールやリポジトリ外の外部リソースを参照する時に使用。
+   ---
+   ```
+2. `# プロジェクトコンテキスト` 見出し。
+3. 各セクションをカタログ順（プロジェクト概要 → ドメイン制約 → 開発フェーズ → ディレクトリ規約 → 外部リソース）で配置する。出力に含まれるのは区分が `add`、`keep`、`update` のいずれかであり、かつ採用ルールを満たすセクションのみ。本文は採用された次のセクションへ直接進む。
+
+組み立てた内容を `.claude/skills/project-context/SKILL.md` に書き込む。このパスが Claude が毎セッション読み込むランタイムの正本となる。
+
+### Step 5: 検証
+
+再構築した `.claude/skills/project-context/SKILL.md` に対して以下のチェックを順に適用する:
+
+- [ ] フロントマターが Step 4 の正本ブロックと逐語一致する。
+- [ ] 本文の全セクション見出しの直後に、ヒアリングで収集した具体内容（具体値、リスト、サブブロック）が続く。
+- [ ] 内容が記入されている各セクションが、`template.md` で定義された出力構造に一致する。
+- [ ] 本文に含まれる各セクションは区分が `add`、`keep`、`update` のいずれかであり、かつ採用ルールを満たす。
+- [ ] ドメイン制約の文が pass / fail で評価可能である（例: 「ログ出力は匿名化された ID を使用」は pass、「ログをきれいに保つ」はこのチェックに失敗する）。
+- [ ] プロジェクトコンテキストの内容は制約・フェーズ・規約・外部リソースに限られる。技術スタックの詳細は `technical-spec` スキルの責務、実装原則は `coding-standards` スキルの責務である。
 
-# プロジェクトコンテキスト
+いずれかのチェックで失敗した場合、該当行を特定してユーザーに報告し、対象セクションの再ヒアリングまたは手動編集を提案する。修正後に Step 5 を再実行する。
 
-## プロジェクト概要
-- **このプロジェクトが何をするか**: [簡潔な説明]
-- **ドメイン**: [ドメイン]
+### Step 6: 結果の提示
 
-## ドメイン制約
-1. [AIの判断に影響する測定可能な制約]
-2. [検証可能な要件]
+再構築した SKILL.md をユーザーに提示し、変更内容（追加 / 更新 / 削除 / 維持されたセクション）を列挙し、完了を確認する。
 
-## 開発フェーズ
-- **フェーズ**: [現在のフェーズ]
+## 出力例
 
-## ディレクトリ規約
-[ファイル配置ルール、またはなければ「特になし」]
+**未設定スキルへの初回実行**（全セクションを新規収集）:
+
+```
+project-context 設定完了:
+- 維持されたセクション: （なし — 初回実行のため）
+- 更新されたセクション: （なし — 初回実行のため）
+- 追加されたセクション: プロジェクト概要、ドメイン制約（2 ルール収集）、開発フェーズ、ディレクトリ規約（1 ルール）、外部リソース（バックエンドドメイン — データベーススキーマソース、シークレットストア）
+- 削除されたセクション: （なし）
+- 書き込み先ファイル: .claude/skills/project-context/SKILL.md
+```
+
+**設定済みスキルへの軽微な更新**（1 セクションを編集、他は保持）:
+
+```
+project-context 更新完了:
+- 維持されたセクション: プロジェクト概要、開発フェーズ、ディレクトリ規約
+- 更新されたセクション: ドメイン制約（3 ルール収集）
+- 追加されたセクション: （なし）
+- 削除されたセクション: （なし）
+- 書き込み先ファイル: .claude/skills/project-context/SKILL.md
 ```
 
-### Step 4: 検証
+**セクション削除のみの実行**（既存セクションを削除、新規追加なし）:
 
-- [ ] 生成ファイルにプレースホルダーテキスト（「要設定」等）が残っていないこと
-- [ ] 全てのドメイン制約が測定・検証可能であること（曖昧な記述がない）
-- [ ] 技術スタック情報が含まれていないこと（technical-specスキルの責務）
-- [ ] 実装原則が含まれていないこと（coding-standardsスキルの責務）
-- [ ] 両方の出力先が更新されていること
-- [ ] 結果をユーザーに提示して確認を得ること
+```
+project-context 更新完了:
+- 維持されたセクション: プロジェクト概要、ドメイン制約、開発フェーズ
+- 更新されたセクション: （なし）
+- 追加されたセクション: （なし）
+- 削除されたセクション: ディレクトリ規約
+- 書き込み先ファイル: .claude/skills/project-context/SKILL.md
+```

package/.claude/commands-ja/review.md

@@ -8,11 +8,10 @@ description: Design Doc準拠検証とセキュリティ検証、必要に応じ
 
 - 準拠検証 → code-reviewerが実行
 - セキュリティ検証 → security-reviewerが実行
-- 修正実装 → task-executorが実行
-- 品質チェック → quality-fixerが実行
-- 再検証 → code-reviewer / security-reviewerが実行
+- **コード側修正パス**: 修正実装 → task-executor、品質チェック → quality-fixer、再検証 → code-reviewer / security-reviewer
+- **設計側更新パス**: DD改訂 → technical-designer（updateモード）、DDレビュー → document-reviewer、複数DDの整合性 → design-sync（複数DD存在時のみ）、再検証 → code-reviewer
 
-オーケストレーターはサブエージェントを呼び出し、構造化JSONを渡します。
+オーケストレーターはサブエージェントを呼び出し、構造化JSONを渡す。設計側パスは、コードが正しいのにDesign Docが古くなっていた不整合（コードがDDに違反したケースではない）に適用される。
 
 Design Doc（省略時は直近のもの）: $ARGUMENTS
 
@@ -57,7 +56,24 @@ Agent toolでsecurity-reviewerを呼び出す:
 - `approved` または `approved_with_notes` → 合格
 - `needs_revision` → 不合格
 
-**両方の結果をサブエージェントの出力フィールドのみを使用して独立に報告**（サブエージェントのレスポンスにないフィールドを追加しない）:
+**両方の結果をサブエージェントの出力フィールドのみを使用して独立に報告**（サブエージェントのレスポンスにないフィールドを追加しない）。
+
+**早期終了（ルーティング対象なし）**: code-reviewer の `verdict` が `pass` かつ `acceptanceCriteria[]` のすべてのエントリが `status: "fulfilled"` かつ `identifierMismatches[]` が空かつ `qualityFindings[]` が空かつ security-reviewer の `findings[]` が空の場合、Steps 5-10 をスキップして直接 Step 11 へ進む — ルーティング対象がないため。クリーンな結果をユーザーに提示する。
+
+それ以外の場合、ユーザー提示の前に、オーケストレーターは以下のルールで finding ごとに推奨ルートを計算する（このルール自体は内部用 — ユーザー向けプロンプトには含めない）。ルールは code-reviewer の既存構造化フィールドのみを参照する。「DDの意図」のような解釈は不安定な推論を避けるため意図的に行わない:
+
+| Finding ソース | 既存フィールドから検出可能なパターン | 推奨ルート |
+|---------------|----------------------------------|----------|
+| `acceptanceCriteria[]` で `status: "partially_fulfilled"` または `"unfulfilled"` | 引用された `gap` から、コードがACを満たしていないことが示される — 追加実装が必要 | `c`（コード側修正） |
+| `acceptanceCriteria[]` で `status: "partially_fulfilled"` または `"unfulfilled"` | 引用された `gap` から、ACテキスト自体が実装済み（チームが受け入れた）挙動から乖離していることが示される — 実装が要件を満たしていないのではなく、DDのAC文言が誤った意図を捉えているケース（ACを読み、引用された `location` と比較して検証する） | `d`（設計側更新 — ACテキストが古い） |
+| `identifierMismatches[]` | `codeValue` が `designDocValue` のリネームとして妥当（camelCase ↔ kebab-case ↔ snake_case、略語の展開/省略、同じ概念を指す意味的なリネーム）— 引用された `location` を確認してコードが新名称を一貫して使用していることを検証 | `d`（設計側更新 — DDが古い可能性が高い） |
+| `identifierMismatches[]` | それ以外の identifier mismatch（型違い、cardinality違い、完全欠落など） | `c`（コード側修正） |
+| `qualityFindings[]` | 全カテゴリ（`dd_violation`、`maintainability`、`reliability`、`coverage_gap`） | `c`（コード側修正） |
+| security-reviewer `findings[]` | 全カテゴリ（`confirmed_risk`、`defense_gap`、`hardening`、`policy`） | `c`（コード側修正） |
+
+各 finding に対しユーザーが推奨を上書き可能。`status: "fulfilled"` の AC 項目はルーティング対象外（対応不要）。
+
+ユーザーへの提示形式（finding ごとに推奨ルートをラベル付け、ルートでグルーピング）:
 
 ```
 Code Compliance: [code-reviewerのcomplianceRate]
@@ -65,30 +81,57 @@ Code Compliance: [code-reviewerのcomplianceRate]
   Identifier Match Rate: [code-reviewerのidentifierMatchRate]
   Acceptance Criteria:
   - [fulfilled] [item] (confidence: [high/medium/low])
-  - [partially_fulfilled] [item]: [gap] — [suggestion]
-  - [unfulfilled] [item]: [gap] — [suggestion]
+  - [partially_fulfilled] [item]: [gap] — [suggestion] [recommended: c | d]
+  - [unfulfilled] [item]: [gap] — [suggestion] [recommended: c | d]
   Identifier Mismatches:
-  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location]
+  - [identifier]: DD=[designDocValue] Code=[codeValue] at [location] [recommended: c | d]
   Quality Findings:
-  - [category] [location]: [description] — [rationale]
+  - [category] [location]: [description] — [rationale] [recommended: c]
 
 Security Review: [security-reviewerのstatus]
   Findings by category:
-  - [confirmed_risk] [location]: [description] — [rationale]
-  - [defense_gap] [location]: [description] — [rationale]
-  - [hardening] [location]: [description] — [rationale]
-  - [policy] [location]: [description] — [rationale]
+  - [confirmed_risk] [location]: [description] — [rationale] [recommended: c]
+  - [defense_gap] [location]: [description] — [rationale] [recommended: c]
+  - [hardening] [location]: [description] — [rationale] [recommended: c]
+  - [policy] [location]: [description] — [rationale] [recommended: c]
   Notes: [security-reviewerのnotes、存在する場合]
 
-修正を実行しますか？ (y/n):
+不整合の解消 — finding ごとに推奨ルートを承認または上書きする:
+  c) コード側修正  — コードがDesign Docに違反; コードを修正して合わせる
+  d) 設計側更新   — コードは正しい; Design Docが古いので改訂する
+  s) スキップ     — 現状を受け入れて変更しない
 ```
 
-両方合格でユーザーが`n`を選択: Steps 5-10をスキップし、Step 11へ。
+AskUserQuestionを使用する。デフォルト提示は **「すべての推奨ルートを承認」** — オーケストレーターの推奨が正しい典型ケース向けの単一確認。ユーザーが上書きしたい場合は finding ごとに c/d/s を収集する。すべてに対し `s` を選択した場合: Steps 5-10をスキップしてStep 11へ進む。
 
 ### 5. タスクテンプレートの読み込み
 
 documentation-criteriaスキルを読み込み、Step 6用のタスクファイルテンプレート（references/task-template.md）を取得。
 
+### 5d. 設計側更新
+
+ユーザーが少なくとも1つのfindingを `d` にルーティングした場合のみ、本ステップを実行する。すべてのルートが `c` または `s` の場合は、Step 6 へ直接スキップする。
+
+1. Agent tool で technical-designer を update モードで呼び出す:
+   - `subagent_type`: "technical-designer"
+   - `description`: "レビューfindingsからのDesign Doc更新"
+   - `prompt`: "[path]のDesign Docをupdateモードで更新する。実装は以下の点で乖離しており、チームはコード側ではなく設計側で受け入れる判断をした: [`d` ルートのfindingsを $STEP_2_OUTPUT の codeLocation と designDocValue 付きでリスト化]。該当セクションに現在のコードの挙動を反映し、履歴エントリを追加する。"
+
+2. document-reviewer を呼び出して更新後の Design Doc を検証する:
+   - `subagent_type`: "document-reviewer"
+   - `description`: "更新後Design Docのレビュー"
+   - `prompt`: "[path]の更新後Design Docの整合性と完成度をレビュー。"
+
+3. 複数のDesign Docが存在する場合（`ls docs/design/*.md | grep -v template | wc -l > 1`）、design-syncを呼び出す:
+   - `subagent_type`: "design-sync"
+   - `description`: "DD間整合性チェック"
+   - `prompt`: "source_design: [更新後DDのパス]。更新後の全Design Doc間の矛盾を検出。"
+   - `sync_status: conflicts_found` の場合: 矛盾をユーザーに提示し、影響を受けるDDに対して technical-designer を再起動して解消する。
+
+4. Step 5d 完了後:
+   - ユーザーが選択した `c` ルートがゼロの場合（すべて `d`、すべて `s`、または `c` を含まない `d` + `s` の混在）→ Steps 6-8 をスキップし、Step 9 で再検証へ進む
+   - `d` と `c` の両方が選択された場合 → 更新後のDDに対して `c` ルートのfindingsを再評価し、DD改訂で満たされたものは除外する。残った `c` ルートのfindings で Step 6 へ進む
+
 ### 6. タスクファイル作成
 
 `docs/plans/tasks/review-fixes-YYYYMMDD.md` にタスクファイルを作成。
@@ -113,7 +156,7 @@ Agent toolでquality-fixerを呼び出す:
 Agent toolでcode-reviewerを呼び出す:
 - `subagent_type`: "code-reviewer"
 - `description`: "準拠の再検証"
-- `prompt`: "修正後のDesign Doc準拠を再検証。Design Doc: [path]. Implementation files: [file list]. 前回の準拠問題: $STEP_2_OUTPUT。各問題が解決されたことを確認。"
+- `prompt`: "修正後のDesign Doc準拠を再検証。Design Doc: [path]. Implementation files: [file list]. 前回の準拠問題: $STEP_2_OUTPUT。各問題が解決されたこと（コード側または設計側いずれかで）を確認。"
 
 ### 10. security-reviewer再検証
 
@@ -122,7 +165,15 @@ Agent toolでsecurity-reviewerを呼び出す（セキュリティ修正が実
 - `description`: "セキュリティの再検証"
 - `prompt`: "修正後のセキュリティを再検証。前回の検出結果: $STEP_3_OUTPUT。Design Doc: [path]. Implementation files: [file list]。"
 
-### 11. 最終レポート
+### 11. 最終クリーンアップとレポート
+
+本レシピが作成したreview-fix用タスクファイル（存在すれば）を削除する。作業内容はコミット済みで、`docs/plans/`はレシピ実行間で保持しない一時的な作業状態である:
+
+- `docs/plans/tasks/review-fixes-YYYYMMDD.md` が存在すれば削除する
+
+タスクファイルを削除できない場合（ファイルシステムエラー）、失敗を報告するが最終レポートをブロックしない。
+
+その後、最終レポートを提示する:
 
 ```
 Code Compliance:
@@ -136,9 +187,11 @@ Security Review:
 
 残存課題:
 - [手動対応が必要な項目]
+
+クリーンアップ: review-fixesタスクファイルを削除済み
 ```
 
-## 自動修正可能な項目
+## 自動修正可能な項目（コード側パス）
 - 単純な未実装の受入条件
 - エラーハンドリング追加
 - 型定義の修正
@@ -148,10 +201,16 @@ Security Review:
 ## 自動修正不可能な項目
 - ビジネスロジックの根本的変更
 - アーキテクチャレベルの修正
-- Design Doc自体の不備
 - コミット済みシークレット（blocked → 人間の判断が必要）
 
-**スコープ**: Design Doc準拠検証、セキュリティレビュー、自動修正まで。
+## 設計側更新の対象
+設計側パスに適した不整合（コードが正しく、DDが古くなったケース）:
+- 新しい命名がチームの現行命名を反映している identifier rename
+- 元の要件意図に対し、DDが捉えた挙動より実装の方が合致している挙動変更
+- 新しい構造が妥当で、DDが旧構造を文書化していたままのコンポーネント分割・統合
+- 実装は既に満たしているがDDに列挙されていなかった新規AC
+
+**スコープ**: Design Doc準拠検証、セキュリティレビュー、コード側自動修正、および設計側更新ルーティング。
 
 ## サブエージェントのスコープ境界
 

package/.claude/skills-en/documentation-criteria/references/plan-template.md

@@ -4,6 +4,8 @@ Created Date: YYYY-MM-DD
 Type: feature|fix|refactor
 Estimated Impact: X files
 Related Issue/PR: #XXX (if any)
+<!-- The line below is medium / large only — small scale uses task-template instead of this plan-template. Keep the value line free of trailing comments so downstream parsers can extract the bare status (pending | ready | escalated). -->
+Implementation Readiness: pending
 
 ## Related Documents
 - Design Doc(s):
@@ -46,6 +48,26 @@ Maps each Design Doc technical requirement to the covering task(s). One row per
 
 **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval)
 
+## UI Spec Component → Task Mapping
+
+Include this section when a UI Spec is among the inputs. Maps each component documented in the UI Spec to the task(s) that implement it. task-decomposer reads this table to populate each task's Investigation Targets with the corresponding UI Spec section. Omit the section when no UI Spec exists.
+
+| UI Spec Component (section heading) | States to Cover | Covered By Task(s) | Gap Status | Notes |
+|---|---|---|---|---|
+| [Use the UI Spec heading exactly as written, e.g., "§ Component: AlertCard"] | [default / loading / empty / error / partial — list the states the implementation must produce] | [Phase X Task Y] | covered | |
+
+**Reference key rule**: The component identifier in column 1 is the UI Spec section heading (verbatim). ui-spec-designer enforces unique component headings so this reference resolves to exactly one section.
+
+**Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval)
+
+## Connection Map
+
+Include this section when the implementation crosses more than one package, service, or process boundary. Document each boundary so task-decomposer can propagate boundary context to the implementation tasks on each side. Omit the section when the implementation stays within a single package.
+
+| Boundary | Owner (left side) | Owner (right side) | Expected Signal | Covered By Task(s) |
+|---|---|---|---|---|
+| [e.g., "web client → API gateway"] | [module/package on the request side] | [module/package on the response side] | [Observable evidence the boundary works — e.g., "HTTP 200 with response matching ContractA", "row inserted in tableB", "message published to topicC"] | [Phase X Task Y on each side] |
+
 ## Objective
 [Why this change is necessary, what problem it solves]
 

package/.claude/skills-en/documentation-criteria/references/ui-spec-template.md

@@ -59,6 +59,8 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro
 
 ### Component: [ComponentName]
 
+> Component heading uniqueness: every `Component: [ComponentName]` heading must be unique within this UI Spec. work-planner and task-decomposer reference components by exact heading text — duplicate names or paraphrased headings break the propagation to implementation tasks.
+
 #### State x Display Matrix
 
 | State | Default | Loading | Empty | Error | Partial |