create-ai-project 1.22.0 → 1.23.0

package/.claude/commands-ja/front-design.md

@@ -1,5 +1,5 @@
 ---
-description: 要件分析からフロントエンド設計ドキュメント作成まで実行
+description: コードベース分析からフロントエンド設計ドキュメント作成まで実行
 ---
 
 **コマンドコンテキスト**: このコマンドはフロントエンド設計フェーズ専用です。
@@ -9,105 +9,136 @@ description: 要件分析からフロントエンド設計ドキュメント作
 **コアアイデンティティ**: 「私はオーケストレーターである。」（subagents-orchestration-guideスキル参照）
 
 **実行プロトコル**:
-1. **全ての作業をサブエージェントに委譲** — サブエージェントを呼び出し、データを橋渡しし、結果を報告する
-2. **以下のフロントエンド設計フローに従う**（このコマンドは中規模/大規模のフロントエンドを対象。UI Specはコードベース分析の前に作成する — コンポーネント構造が技術設計に反映されるため）:
-   - 実行: requirement-analyzer → ui-spec-designer → codebase-analyzer → technical-designer-frontend → code-verifier → document-reviewer → design-sync
-   - **`[停止: ...]`マーカーごとに停止** → ユーザー承認を待つ
+1. **全ての作業をサブエージェントに委譲** — サブエージェントを呼び出し、データを橋渡しし、結果を報告する。唯一の例外はStep 1のスコープブートストラップで、シードファイルの特定に限定したレシピ内オーケストレータータスク。
+2. **以下のフロントエンド設計フローを順に実行**（このコマンドは中規模/大規模のフロントエンドを対象） — 分岐のない固定の線形シーケンス:
+   - 実行: スコープブートストラップ → codebase-analyzer → [停止: スコープ確認] → ui-analyzer → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync
+   - technical-designer-frontendは、設計にアーキテクチャ決定が伴う場合（documentation-criteriaに従う）に前提となるADRを作成する。ADRはDesign Docを置き換えない — フローは常にDesign Doc作成と検証チェーン全体を通過する
+   - **`[停止: ...]`マーカーごとに停止** → 次に進む前にユーザー承認を待つ
 3. **スコープ**: 設計ドキュメントの承認をもって完了
 
-**重要**: document-reviewer、design-sync、subagents-orchestration-guideスキルフローで定義された全ての停止ポイントを実行すること — 各ステップが品質ゲートとして機能する。スキップは検出されない不整合のリスクにつながる。
+**subagents-orchestration-guideの利用**: オーケストレーション原則とScale Determination表を参照する。このコマンドは独自の開始順序を定義する — ガイドのrequirement-analyzer起点フローはここでは適用しない。
+
+**重要**: document-reviewer、design-sync（Design Docの場合）、全ての停止ポイントを実行する — 各々が品質ゲートとして機能する。スキップは検出されない不整合のリスクにつながる。
 
 ## ワークフロー概要
 
 ```
-要件 → requirement-analyzer → [停止: 規模判定]
-                                    ↓
-                            ui-spec-designer → [停止: UI Spec承認]
-                                    ↓
-                            codebase-analyzer → technical-designer-frontend
-                                    ↓
-                            code-verifier → document-reviewer
-                                    ↓
-                               design-sync → [停止: 設計承認]
+要件 → スコープブートストラップ → codebase-analyzer → [停止: スコープ確認]
+                                                            ↓
+                                                       ui-analyzer
+                                                            ↓
+                                              ui-spec-designer → [停止: UI Spec承認]
+                                                            ↓
+                                              technical-designer-frontend
+                                                            ↓
+                                              code-verifier → document-reviewer
+                                                            ↓
+                                                 design-sync → [停止: 設計承認]
 ```
 
 ## スコープ境界
 
 **実行内容**:
-- requirement-analyzerによる要件分析
-- codebase-analyzerによるコードベース分析（技術設計の前に実施）
+- スコープブートストラップ: codebase-analyzerが値の入った入力を得られるようシードファイルを特定する
+- codebase-analyzerによるコードベース分析（フロントエンド設計フェーズの入口）
+- codebase-analyzerの所見に基づくユーザーとのスコープ確認
+- ui-analyzerによるUI事実収集
 - ui-spec-designerによるUI Spec作成（プロトタイプコード確認を含む）
-- ADR作成（アーキテクチャ変更、新技術、データフロー変更がある場合）
+- ADR作成（アーキテクチャ変更、新技術、データフロー変更が伴う場合、Design Docの前提として）
 - technical-designer-frontendによるDesign Doc作成
 - code-verifierによるDesign Doc検証（ドキュメントレビューの前に実施）
 - document-reviewerによるドキュメントレビュー
-- design-syncによるDesign Doc横断整合性検証
+- design-syncによるDesign Doc間整合性検証
 
 **責務境界**: このコマンドはフロントエンド設計ドキュメント（UI Spec/ADR/Design Doc）の承認で責務完了。作業計画以降はスコープ外。
 
+## 実行フロー
+
 要件: $ARGUMENTS
 
-## 実行フロー
+### Step 1: スコープブートストラップ
+codebase-analyzerは値の入った`requirement_analysis.affectedFiles`を必要とする。そのシードを、軽量なオーケストレーター内タスクで構築する — ファイルの特定のみで、深い読み込みや設計判断は行わない:
+
+1. ユーザー要件から候補キーワード（機能名、ドメイン名詞、識別子）を抽出する。
+2. Bash（`rg`、`rg`が使えない場合は`grep`）で、それらのキーワードに一致するファイルをリポジトリ内で検索する。
+3. 一致したファイルパスをシード`affectedFiles`として収集する。
+4. **検索結果が0件の場合**: 設計対象のファイルまたはモジュールをユーザーに確認し（AskUserQuestion）、その回答を`affectedFiles`とする。関連コードが存在しないとユーザーが確認した場合は、コードベース起点の設計が適用できない旨を報告し、進め方をユーザーと確認する。
+5. **検索結果が約20件を超える場合**: キーワードが広すぎる。最も関連性の高い候補をユーザーに提示し（AskUserQuestion）、シード`affectedFiles`を確認してから進む。
+
+このステップはシードファイルの特定のみを行う。ファイルの全文読み込み、依存関係の追跡、分析はcodebase-analyzerの責務である。
+
+### Step 2: コードベース分析
+- Agentツールで**codebase-analyzer**を呼び出す
+  - `subagent_type: "codebase-analyzer"`, `description: "コードベース分析"`
+  - `prompt`: `requirements`（ユーザー要件の原文）と`requirement_analysis`（`affectedFiles`（Step 1のシード）、`purpose`（ユーザー要件）、`scale`（シードファイル数にScale Determination表を当てた暫定値）、`technicalConsiderations`（`{ constraints: [], risks: [], dependencies: [] }`）を含むJSONオブジェクト）を含める。フロントエンド設計ガイダンスのため既存コードベースを分析する。
 
-### Step 1: 要件分析フェーズ
-設計への影響が深いことを考慮し、まず対話により要件の背景と目的を理解:
-- 何の問題を解決したいか
-- 期待する成果と成功基準
-- 既存システムとの関係
+### Step 3: スコープ確認
+codebase-analyzerが返ったら、設計作業の前にユーザーとスコープを確認する。AskUserQuestionを使う。
 
-ユーザーが上記3つの質問に回答した後、設計スコープ内で以下のプロセスを実行する。codebase-analyzerとcode-verifierの呼び出しはsubagents-orchestration-guideのCall Examplesに従う。
-- Agentツールで**requirement-analyzer**を呼び出す
-  - `subagent_type: "requirement-analyzer"`
-  - `description: "要件分析"`
-  - `prompt: "要件: [ユーザー要件] 要件分析と規模判定を実施してください"`
-- **[停止]**: 要件分析結果を確認し、質問事項に対応
+codebase-analyzerのJSONを出典として以下を提示する:
+- **対象ファイル/モジュール**: `analysisScope.filesAnalyzed`と、それらが属するモジュール
+- **影響を受けるレイヤー**: `analysisScope.categoriesDetected`と`focusAreas`から導出される、影響を受けるレイヤー
+- **不明点/前提**: `limitations`と、codebase-analyzerが記録した前提
+- **設計前の質問事項**: 設計を進める前にユーザーの回答が必要な未解決点
 
-### Step 2: UI Specフェーズ
-要件分析承認後、プロトタイプコードについてユーザーに確認:
+ユーザーに以下から1つを選んでもらう:
+- **このスコープで設計を進める** — Step 4へ進む
+- **スコープを修正して再実行** — 修正したスコープでStep 1に戻る。ユーザーが修正後のファイルまたはモジュールを指定した場合は、検索で導出し直さず、それをStep 1のシードとして直接使う
+- **追加ヒアリングののち進める** — 不足している回答を集めてからStep 4へ進む
+
+ユーザーがスコープを確認したら、確認済みの対象ファイル数を数え、Scale Determination表から規模を設定する。この確認済みの規模はStep 2の暫定値に優先する。
+
+**[停止]**: ユーザーの選択を待ってから進む。
+
+### Step 4: UI事実収集
+- Agentツールで**ui-analyzer**を呼び出す
+  - `subagent_type: "ui-analyzer"`, `description: "UI事実収集"`
+  - `prompt`: `requirements`（ユーザー要件）と`requirement_analysis`（`affectedFiles`（Step 2のcodebase-analyzer出力の`analysisScope.filesAnalyzed`・`analysisScope.tracedDependencies`・`focusAreas[].relatedFiles`のパスの和集合）、`purpose`（ユーザー要件）、`scale`（Step 3の確認済み規模）、`technicalConsiderations`（`{ constraints: [], risks: [], dependencies: [] }`）を含むJSONオブジェクト）を含める。ui-analyzerはproject-contextのExternal Resourcesセクションを読み、宣言されたアクセス手段で外部UIソースを取得し、既存のUIコードベースを分析する。
+
+codebase-analyzerのJSON（Step 2）とui-analyzerのJSON（Step 4）は、ui-spec-designerとtechnical-designer-frontendで再利用される。
+
+### Step 5: UI Specフェーズ
+プロトタイプコードについてユーザーに確認する。
 
 **ユーザーに確認**: 「この機能のプロトタイプコードはありますか？ある場合はコードへのパスを教えてください。プロトタイプはUI Specの参考資料として`docs/ui-spec/assets/`に配置されます。」
 
 - **[停止]**: プロトタイプコードの有無についてユーザーの回答を待つ
 
-UI Specを作成:
+その後、UI Specを作成する:
 - Agentツールで**ui-spec-designer**を呼び出す
-  - `subagent_type: "ui-spec-designer"`
-  - `description: "UI Spec作成"`
-  - PRDあり＋プロトタイプあり: `prompt: "[パス]のPRDからUI Specを作成。プロトタイプコードは[ユーザー提供パス]。プロトタイプをdocs/ui-spec/assets/{feature-name}/に配置"`
-  - PRDあり＋プロトタイプなし: `prompt: "[パス]のPRDからUI Specを作成。プロトタイプコードなし。"`
-  - PRDなし（中規模）: `prompt: "以下の要件に基づいてUI Specを作成: [requirement-analyzerの出力を渡す]。PRDなし。"`（プロトタイプパスがあれば追加）
-- **document-reviewer**でUI Specを検証
+  - `subagent_type: "ui-spec-designer"`, `description: "UI Spec作成"`
+  - 以下を含めてプロンプトを構築する: ソース（この機能の既存PRDが`docs/prd/`にあればそれ。なければ、ユーザー要件にStep 2のcodebase-analyzer JSONとStep 3の確認済みスコープを添えたもの）、`ui_analysis`（Step 4のui-analyzer JSON）、提供された場合のプロトタイプパス。プロトタイプは`docs/ui-spec/assets/{feature-name}/`に配置する。
+- **document-reviewer**でUI Specを検証する
   - `subagent_type: "document-reviewer"`, `description: "UI Specレビュー"`, `prompt: "doc_type: UISpec target: [ui-specパス] 整合性と完全性をレビュー"`
-- **[停止]**: UI Specをユーザーに提示し承認を取得
-
-### Step 3: 設計ドキュメント作成フェーズ
-まず既存コードベースを分析:
-- Agentツールで**codebase-analyzer**を呼び出す
-  - `subagent_type: "codebase-analyzer"`, `description: "コードベース分析"`, `prompt: "requirement_analysis: [Step 1のJSON]. requirements: [ユーザー要件]. フロントエンド設計ガイダンスのため既存コードベースを分析。"`
+- **[停止]**: UI Specをユーザーに提示し承認を取得する
 
-規模判定に応じて適切な設計ドキュメントを作成。technical-designer-frontendは技術選択・データフロー設計について少なくとも2つの選択肢をトレードオフとともに提示:
-- Agentツールで**technical-designer-frontend**を呼び出す
-  - ADRの場合: `subagent_type: "technical-designer-frontend"`, `description: "ADR作成"`, `prompt: "[技術決定]のADRを作成。少なくとも2つの選択肢をトレードオフとともに提示。"`
-  - Design Docの場合: `subagent_type: "technical-designer-frontend"`, `description: "Design Doc作成"`, `prompt: "要件に基づいてDesign Docを作成。コードベース分析: [codebase-analyzerのJSON]。UI Specは[ui-specパス]。UI Specのコンポーネント構造と状態設計を継承。少なくとも2つのアーキテクチャ選択肢をトレードオフとともに提示。"`
-- **（Design Docのみ）** **code-verifier**でDesign Docを既存コードに対して検証。ADRの場合はスキップ。
+### Step 6: 設計ドキュメント作成フェーズ
+- Agentツールで**technical-designer-frontend**を呼び出し、設計ドキュメントを作成する。documentation-criteriaに従いDesign Docを作成する。設計にアーキテクチャ決定（アーキテクチャ変更、新技術、データフロー変更）が伴う場合は、前提となるADRを先に作成する。
+  - `subagent_type: "technical-designer-frontend"`, `description: "設計ドキュメント作成"`, `prompt: "この要件の設計ドキュメントを作成。documentation-criteriaに従いDesign Docを作成し、設計にアーキテクチャ決定が伴う場合は前提となるADRを先に作成。要件: [ユーザー要件の原文]。コードベース分析: [Step 2のcodebase-analyzer JSON]。UI分析: [Step 4のui-analyzer JSON]。UI Specは[ui-specパス]。UI Specのコンポーネント構造と状態設計を継承。少なくとも2つのアーキテクチャ選択肢をトレードオフとともに提示。"`
+- **code-verifier**でDesign Docを既存コードに対して検証する。
   - `subagent_type: "code-verifier"`, `description: "Design Doc検証"`, `prompt: "doc_type: design-doc document_path: [Design Docパス] mode: pre-implementation (code_paths省略 — verifierがドキュメントからスコープを発見). Design Docを既存コードに対して検証。"`
-- **document-reviewer**で整合性検証（Design Docの場合はcode-verifier結果を渡す。ADRの場合は省略）
-  - `subagent_type: "document-reviewer"`, `description: "ドキュメントレビュー"`, `prompt: "doc_type: DesignDoc target: [ドキュメントパス] mode: composite code_verification: [code-verifierのJSON]（Design Docのみ） 整合性と完全性をレビュー。"`
-### Step 4: 設計整合性検証
-- Agentツールで**design-sync**を呼び出す
+- technical-designer-frontendが作成した各ドキュメント（Design Doc、および作成された場合のADR）に対して**document-reviewer**を呼び出す。
+  - Design Doc: `subagent_type: "document-reviewer"`, `description: "ドキュメントレビュー"`, `prompt: "doc_type: DesignDoc target: [Design Docパス] mode: composite codebase_analysis: [Step 2のcodebase-analyzer JSON] code_verification: [code-verifierのJSON]. 整合性と完全性をレビュー。"`
+  - ADR（作成された場合）: `subagent_type: "document-reviewer"`, `description: "ADRレビュー"`, `prompt: "doc_type: ADR target: [ADRパス] mode: composite. 整合性と完全性をレビュー。"`
+- ADRレビューで修正が必要になった場合、technical-designer-frontend(update)がADRを修正し、修正後のADRに合わせてDesign Docを再整合させる — Design Docは未レビューまたは古いADRの上に立ってはならない。この再整合でDesign Docが変わった場合は、更新後のDesign Docに対してcode-verifierとDesign Docのdocument-reviewerを再実行し、検証が最終内容を反映するようにする。
+
+### Step 7: 設計整合性検証
+- Agentツールで**design-sync**を呼び出す。
   - `subagent_type: "design-sync"`, `description: "設計整合性チェック"`, `prompt: "docs/design/配下の全Design Doc間の整合性をチェック。矛盾と重複を報告。"`
-- **[停止]**: 設計ドキュメントとdesign-sync結果を提示し、ユーザー承認を取得
+- **[停止]**: 設計ドキュメント（Design Docの場合はdesign-sync結果も）を提示し、ユーザー承認を取得する
 
 ## 完了条件
 
-- [ ] requirement-analyzerを実行し規模を判定
-- [ ] codebase-analyzerを実行し結果をtechnical-designer-frontendに渡した
-- [ ] ui-spec-designerでUI Specを作成（該当時）
-- [ ] technical-designer-frontendで適切な設計ドキュメント（ADRまたはDesign Doc）を作成
-- [ ] Design Docに対してcode-verifierを実行し結果をdocument-reviewerに渡した（ADRのみの場合はスキップ）
-- [ ] document-reviewerを実行しフィードバックに対応
-- [ ] design-syncで整合性検証を実行
-- [ ] 設計ドキュメントのユーザー承認を取得
+- [ ] Step 1のスコープブートストラップのシードを構築した（または検索結果が0件のときユーザーから対象ファイルを取得した）
+- [ ] 値の入った`requirement_analysis`でcodebase-analyzerを実行した
+- [ ] ユーザーと設計スコープを確認し、確認済みの対象ファイルから規模を設定した
+- [ ] ui-analyzerを実行した。codebase-analyzer（Step 2）とui-analyzer（Step 4）の出力はui-spec-designerとtechnical-designer-frontendで再利用される
+- [ ] ui-spec-designerでUI Specを作成した
+- [ ] technical-designer-frontendでDesign Docを作成した。設計にアーキテクチャ決定が伴う場合は前提となるADRを先に作成した
+- [ ] Design Docに対してcode-verifierを実行し、結果をdocument-reviewerに渡した
+- [ ] 作成した各ドキュメント（Design Doc、および作成された場合のADR）に対してdocument-reviewerを実行し、フィードバックに対応した
+- [ ] design-syncで整合性検証を実行した
+- [ ] 設計ドキュメントのユーザー承認を取得した
 
 ## 出力例
 フロントエンド設計フェーズ完了。

package/.claude/skills-en/coding-standards/SKILL.md

@@ -29,6 +29,7 @@ Immediately stop and reconsider design when detecting the following patterns:
 
 - **Aggressive Refactoring** - Prevent technical debt and maintain health
 - **No Unused "Just in Case" Code** - Violates YAGNI principle (Kent Beck)
+- **Minimum Surface for Required Coverage** - When introducing maintenance-surface-bearing elements (persistent state, public-contract elements or cross-boundary fields/props, behavioral modes/flags/variants, reusable abstractions, or component splits), select the smallest design surface that covers current user-visible requirements and accepted technical constraints (audit, data integrity, compatibility, security, performance, accessibility). Adoption is justified by naming a current requirement or constraint that smaller alternatives fail to cover; value-based arguments (reusable, future-ready, convenient for implementation) serve as tiebreakers only. Distinct from YAGNI: YAGNI is a time-axis check (refuse work for future-only needs); this principle constrains surface area at a fixed coverage point.
 
 ## Comment Writing Rules
 

package/.claude/skills-en/documentation-criteria/SKILL.md

@@ -120,6 +120,7 @@ description: Guides PRD, ADR, Design Doc, UI Spec, and Work Plan creation. Use w
 - **Code inspection evidence** (inspected files/functions during investigation)
 - **Field propagation map** (when fields cross component boundaries)
 - **Data representation decision** (when introducing new structures)
+- **Minimal Surface Alternatives** (when introducing persistent state, public-contract elements or cross-boundary fields, behavioral modes/flags, or reusable abstractions/component splits — see design-template.md for the 5-step output format)
 - **Applicable standards** (explicit/implicit classification)
 - **Prerequisite ADRs** (including common ADRs)
 - **Verification Strategy** (required)

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

@@ -30,7 +30,7 @@ unknowns:
 
 ### Prerequisite ADRs
 
-- [ADR File Name]: [Related decision items]
+- [docs/adr/ADR-XXXX.md]: [Related decision items]
 - Reference common technical ADRs when applicable
 
 ### Agreement Checklist
@@ -185,6 +185,49 @@ Evaluate existing structures: semantic fit, responsibility fit, lifecycle fit, b
 
 **Decision**: [reuse / extend / new] — [rationale]
 
+### Minimal Surface Alternatives (When Introducing Maintenance-Surface Elements)
+
+One entry per new in-scope element (persistent state / public-contract element or cross-boundary field or prop / behavioral mode/flag/variant / reusable abstraction or component split). Records the 5-step output produced by the invoking designer agent. Reference: `coding-standards` skill, "Minimum Surface for Required Coverage".
+
+#### Element 1: [name of the new element]
+
+**Step 1 — Fixed Requirements**
+- [AC reference — AC ID, AC heading, EARS clause, or constraint ID]: [requirement / constraint text]
+- [AC reference]: [requirement / constraint text]
+
+References may point to the Design Doc, referenced PRD, or referenced UI Spec.
+
+**Steps 2–3 — Alternatives Compared**
+
+Adapt the column names below to the design context: backend Design Docs use "Crosses module/service boundary" and "New concept / mode / flag"; frontend Design Docs use "Crosses component boundary" and "New props / modes / variants" (and add the "client or server" qualifier to the persistent-state column).
+
+| Alternative | Current requirements covered (AC reference) | New persistent state introduced (count) | New concept / mode / flag / prop / variant (count) | Crosses module/service or component boundary (yes/no) | Breaking change or migration required (yes/no) | Subjective cost notes |
+|---|---|---|---|---|---|---|
+| [The added element as proposed] | | | | | | |
+| [Subtractive alternative — derive / compute on demand / keep at caller / reuse existing / introduce no new state] | | | | | | |
+| [Optional third alternative] | | | | | | |
+
+Subjective cost notes accepts: maintainability concerns, naming clarity, perceived implementation effort, future-readiness sentiment, and similar judgment-level remarks.
+
+**Resolution priority for selecting "smallest"** (later columns are tiebreakers when earlier are equal):
+1. New persistent state introduced (lower = smaller)
+2. Crosses module/service or component boundary (no = smaller)
+3. New concept / mode / flag / prop / variant (lower = smaller)
+4. Breaking change or migration required (no = smaller)
+5. Subjective cost notes
+
+**Step 4 — Selected Alternative and Rationale**
+- **Selected**: [alternative name]
+- **Rationale**:
+  - When selected = smallest alternative considered: state "smallest alternative considered; no further reduction available"
+  - When selected > smallest: name the current requirement(s) from Step 1 that smaller alternatives fail to satisfy
+
+**Step 5 — Rejected Alternatives Log**
+- [Alternative name]: [1-2 lines on what it was and why rejected]
+- [Alternative name]: [1-2 lines on what it was and why rejected]
+
+Repeat the Element block above for each additional in-scope element. Mark the whole section N/A with brief rationale when the design introduces no in-scope elements.
+
 ### Type Definitions
 
 ```typescript
@@ -351,6 +394,16 @@ Mark as N/A with brief rationale when the design introduces entirely new behavio
 - **Disadvantages**: [Disadvantages]
 - **Reason for Rejection**: [Why it wasn't adopted]
 
+## Future Extensibility
+
+This section records capabilities **excluded** from the current design surface. Limit entries to capabilities tied to a current requirement, a current consumer, or a documented constraint; route purely speculative future plans into a separate proposal document.
+
+Distinguish from "Minimal Surface Alternatives → Step 5 (Rejected Alternatives)": Step 5 records element-level alternatives that were compared and rejected within a single in-scope element; this section records capability-level items not bound to a single element (broader scope considered but excluded).
+
+- **Deferred possibilities**: [Capabilities considered during design and explicitly excluded from the current design surface. Each entry names the current requirement it would have served]
+- **Intentional limitations**: [What was deliberately kept small and why]
+- **Extension points (existing, with current consumers)**: [Interfaces or hooks already in use by named current consumers. Each entry names a current consumer]
+
 ## Risks and Mitigation
 
 | Risk | Impact | Probability | Mitigation |

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

@@ -39,10 +39,10 @@ Adopted quality gates for the change area. Each task in this plan must satisfy t
 
 Maps each Design Doc technical requirement to the covering task(s). One row per extracted item. Every row must have at least one covering task, or an explicit gap justification.
 
-| DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes |
-|---|---|---|---|---|---|
-| [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | |
-| Security Considerations | Input validation for API | prerequisite | — | gap | Deferred to Phase 2 per user decision |
+| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes |
+|---|---|---|---|---|---|---|
+| [docs/design/XXX.md — one of the Related Documents above] | [Section name from DD] | [Specific item] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X Task Y] | covered | |
+| docs/design/XXX.md | Security Considerations | Input validation for API | prerequisite | — | gap | Deferred to Phase 2 per user decision |
 
 **Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work)
 
@@ -60,6 +60,18 @@ Include this section when a UI Spec is among the inputs. Maps each component doc
 
 **Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval)
 
+## ADR Bindings
+
+Include this section when ADRs are provided as input or listed in the Design Doc's "Prerequisite ADRs" section. Maps each implementation-binding ADR decision to the task(s) it constrains. Omit the section when no ADR applies.
+
+A decision is **implementation-binding** when it constrains code placement, dependency direction, contract/schema shape, data flow, or persistence. Acceptance criteria and required behaviors are recorded in the Design Doc; this table covers only structural constraints from ADRs.
+
+| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) |
+|---|---|---|---|---|
+| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [One implementation-binding decision sentence, copied or condensed from the named section] | [Phase X Task Y] |
+
+One row per binding decision. A single ADR can contribute multiple rows. A single task can appear in multiple rows.
+
 ## 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.

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

@@ -17,8 +17,17 @@ Metadata:
 Files to read before starting implementation (file path, with optional search hint):
 - [e.g., src/orders/checkout (processOrder function) — determined during task decomposition based on task nature]
 
+## Binding Decisions
+(Include this section when the work plan's ADR Bindings table covers this task. Omit otherwise.)
+
+Each row is an ADR decision the implementation in this task must comply with.
+
+| Source | Axis | Decision | Compliance Check |
+|---|---|---|---|
+| [docs/adr/ADR-XXXX.md (§ <Source Section>) — substitute the section name (`Decision` or `Implementation Guidance`) from the matching work plan row] | [Axis value copied verbatim from the work plan's ADR Bindings row] | [Binding decision copied from the work plan's ADR Bindings row] | [Y/N-answerable positive predicate that evaluates whether the planned/final implementation satisfies the decision] |
+
 ## Investigation Notes
-(Implementation observations are appended here before implementation begins.)
+(Implementation observations are appended here before implementation begins. When Binding Decisions exist, record the planned implementation approach and each Compliance Check result here.)
 
 ## Implementation Steps (TDD: Red-Green-Refactor)
 ### 1. Red Phase
@@ -51,6 +60,7 @@ Files to read before starting implementation (file path, with optional search hi
 - [ ] All added tests pass
 - [ ] Operation verified per Operation Verification Methods above
 - [ ] Deliverables created (for research/design tasks)
+- [ ] (When Binding Decisions exist) Every Compliance Check evaluates to `Y` against the final implementation, with evidence recorded in Investigation Notes (file:line, test result, or command output)
 
 ## Notes
 - Impact scope: [Areas where changes may propagate]

package/.claude/skills-en/subagents-orchestration-guide/SKILL.md

@@ -53,6 +53,7 @@ When receiving a new task, pass user requirements directly to requirement-analyz
 13. **code-verifier**: Verify document-code consistency. Pre-implementation: Design Doc claims against existing codebase. Post-implementation: implementation against Design Doc
 14. **design-sync**: Design Doc consistency verification (detects explicit conflicts only)
 15. **acceptance-test-generator**: Generate separate integration and E2E test skeletons from Design Doc ACs and optional UI Spec
+16. **ui-analyzer**: Gather UI facts (external sources + existing UI code) for frontend design preparation — read-only
 
 ## My Orchestration Principles
 
@@ -153,8 +154,9 @@ Subagents respond in JSON format. Key fields for orchestrator decisions:
 |-------|-----------|----------------|
 | requirement-analyzer | scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions | Select flow by scale; check adrRequired for ADR step |
 | codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations | Pass focusAreas to technical-designer as context |
+| ui-analyzer | externalResources (status, per-axis fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], focusAreas[], candidateWriteSet[], limitations | Pass the ui-analyzer JSON to ui-spec-designer and technical-designer-frontend; each consumes the fields named in its own input declaration |
 | code-verifier | status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). Pre-implementation: verifies Design Doc claims against existing codebase. Post-implementation: verifies implementation consistency against Design Doc (pass `code_paths` scoped to changed files) | Flag discrepancies for document-reviewer |
-| task-executor | Input: `task_file` (required in orchestrated flows); optional Fix Mode signals `requiredFixes` or `incompleteImplementations` — when either is non-empty, skip `task_already_completed` and extend allowed list with each item's `file_path` / `location` (parse `location` as `file[:line]`). Output: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain}. | On escalation_needed: handle by escalation_type |
+| task-executor | Input: `task_file` (required in orchestrated flows); optional Fix Mode signals `requiredFixes` or `incompleteImplementations` — when either is non-empty, skip `task_already_completed` and extend allowed list with each item's `file_path` / `location` (parse `location` as `file[:line]`). Output: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain, binding_decision_violation}. | On escalation_needed: handle by escalation_type |
 | quality-fixer | Input: `task_file` (path to current task file — always pass this in orchestrated flows), `filesModified` (extract from the upstream implementation step's response — passes the task's write set as the primary scope for stub-detection; falls back to `git diff HEAD` when omitted). Status: approved/stub_detected/blocked. `stub_detected` → route back to the implementation step with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → see quality-fixer blocked handling below | On stub_detected: re-invoke the implementation step. On blocked: see handling below |
 | document-reviewer | approvalReady (true/false) | Proceed to next step on true; request fixes on false |
 | design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | On CONFLICTS_FOUND: present conflicts to user before proceeding |

package/.claude/skills-ja/coding-standards/SKILL.md

@@ -29,6 +29,7 @@ description: コードの品質問題、アンチパターン、可読性を検
 
 - **積極的なリファクタリング** - 技術的負債を防ぎ、健全性を維持
 - **使われない「念のため」のコード禁止** - YAGNI原則（Kent Beck）に反する
+- **Minimum Surface for Required Coverage** - 保守対象の要素（永続状態、公開コントラクト要素または境界を越えるフィールド/Props、振る舞いモード/フラグ/バリアント、再利用可能な抽象、コンポーネント分割）を導入する場合、現在のユーザー観察可能な要件と受容済み技術制約（監査、データ整合性、互換性、セキュリティ、パフォーマンス、アクセシビリティ）をカバーする最小の設計面を選ぶ。採用の正当化は「より小さい代替案では満たせない現要件・制約を名指す」形で行い、価値ベースの議論（再利用可能、将来対応、実装が楽）はタイブレーカーのみに用いる。YAGNI との違い: YAGNI は時間軸の判断（将来のためだけの作業はしない）、本原則は固定されたカバレッジ点での設計面を制約する。
 
 ## コメント記述ルール
 

package/.claude/skills-ja/documentation-criteria/SKILL.md

@@ -120,6 +120,7 @@ description: PRD、ADR、Design Doc、UI Spec、作業計画書の作成を支
 - **コード調査エビデンス**（調査時に確認したファイル/関数）
 - **フィールド伝播マップ**（フィールドがコンポーネント境界を越える場合）
 - **データ構造の採用判断**（新規構造導入時）
+- **Minimal Surface Alternatives**（永続状態、公開コントラクト要素または境界を越えるフィールド、振る舞いモード/フラグ、再利用可能な抽象/コンポーネント分割を導入する場合 — design-template.md の5ステップ出力フォーマットを参照）
 - **適用基準**（explicit/implicit分類）
 - **前提となるADR**（共通ADR含む）
 - **検証戦略**（必須）

package/.claude/skills-ja/documentation-criteria/references/design-template.md

@@ -30,7 +30,7 @@ unknowns:
 
 ### 前提となるADR
 
-- [ADRファイル名]: [関連する決定事項]
+- [docs/adr/ADR-XXXX.md]: [関連する決定事項]
 - 共通技術ADRも該当する場合は参照
 
 ### 合意事項チェックリスト
@@ -185,6 +185,49 @@ unknowns:
 
 **判断**: [再利用 / 拡張 / 新規] — [根拠]
 
+### Minimal Surface Alternatives（保守対象の要素を導入する場合）
+
+新規に導入する適用対象要素（永続状態 / 公開コントラクト要素または境界を越えるフィールド・Props / 振る舞いモード・フラグ・バリアント / 再利用可能な抽象またはコンポーネント分割）ごとに1エントリ。設計者エージェントが実行した5ステップの結果を記録する。参照: `coding-standards` スキル「Minimum Surface for Required Coverage」。
+
+#### Element 1: [新規要素の名前]
+
+**ステップ1 — 確定要件**
+- [AC 参照 — AC ID、AC見出し、EARS節、または制約ID]: [要件・制約の文言]
+- [AC 参照]: [要件・制約の文言]
+
+参照先は Design Doc、参照 PRD、参照 UI Spec のいずれでもよい。
+
+**ステップ2〜3 — 比較した代替案**
+
+下記の列名は設計コンテキストに合わせて適用する。バックエンド Design Doc では「モジュール/サービス境界を越えるか」「新規の概念 / モード / フラグ」を使用、フロントエンド Design Doc では「コンポーネント境界を越えるか」「新規の Props / モード / バリアント」を使用（永続状態列には「クライアントまたはサーバー」の修飾を加える）。
+
+| 代替案 | カバーする現要件（AC 参照） | 新規の永続状態（件数） | 新規の概念 / モード / フラグ / Props / バリアント（件数） | モジュール/サービスまたはコンポーネント境界を越えるか（はい/いいえ） | 破壊的変更または移行が必要か（はい/いいえ） | 主観的コストノート |
+|---|---|---|---|---|---|---|
+| [提案された追加要素そのもの] | | | | | | |
+| [削減的代替案 — 既存から導出 / オンデマンド計算 / 呼び出し側に留める / 既存を再利用 / 新規状態を導入しない] | | | | | | |
+| [任意の第3案] | | | | | | |
+
+主観的コストノートに記載できる内容: 保守性の懸念、命名の分かりやすさ、体感的な実装労力、将来対応への期待、その他の判断レベルのコメント。
+
+**「最小」選定のための解決優先順位**（左の列が同点のとき右の列でタイブレーク）:
+1. 新規の永続状態の件数（少ない＝小さい）
+2. モジュール/サービスまたはコンポーネント境界を越えるか（いいえ＝小さい）
+3. 新規の概念 / モード / フラグ / Props / バリアントの件数（少ない＝小さい）
+4. 破壊的変更または移行の要否（いいえ＝小さい）
+5. 主観的コストノート
+
+**ステップ4 — 選定した代替案と根拠**
+- **選定**: [代替案の名前]
+- **根拠**:
+  - 選定が検討した中で最小の代替案である場合: 「検討した中で最小の代替案であり、これ以上の縮減余地なし」と記載
+  - 選定が最小でない場合: ステップ1から、より小さい代替案では満たせない現要件を名指す
+
+**ステップ5 — 不採用案の記録**
+- [代替案の名前]: [何だったか・なぜ不採用かを1〜2行]
+- [代替案の名前]: [何だったか・なぜ不採用かを1〜2行]
+
+新規に導入する各適用対象要素について上記のエレメントブロックを繰り返す。適用対象要素を導入しない場合は、本セクション全体を簡潔な理由とともに N/A とする。
+
 ### 型定義
 
 ```typescript
@@ -357,6 +400,16 @@ unknowns:
 - **デメリット**: [欠点]
 - **不採用理由**: [採用しなかった理由]
 
+## 将来の拡張性
+
+本セクションは現在の設計面から**除外した**機能・能力を記録する。エントリは現要件、現在のコンシューマー、または記録された制約に結び付くものに限定し、純粋な将来構想は別途の提案ドキュメントに送る。
+
+「Minimal Surface Alternatives → ステップ5（不採用案）」との区別: ステップ5 は単一の適用対象要素内で比較・棄却した要素レベルの代替案を記録する。本セクションは個別の要素に結び付かない、より粒度の大きな能力レベルの項目（検討したが今回の設計面に含めなかった機能や能力）を記録する。
+
+- **先送りした機能・能力**: [設計時に検討したが現在の設計面から明示的に除外した機能・能力。各エントリには、これが満たしたはずの現要件を名指して記載する]
+- **意図的な限定**: [意図的に小さく抑えた範囲とその理由]
+- **拡張ポイント（既存・現在のコンシューマーあり）**: [現在のコンシューマーがすでに利用している既存のインターフェースやフック。各エントリには現在のコンシューマーを名指して記載する]
+
 ## リスクと対策
 
 | リスク | 影響度 | 発生確率 | 対策 |

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

@@ -39,10 +39,10 @@ Implementation Readiness: pending
 
 Design Docの各技術要件をカバーするタスクへのマッピング。抽出した項目ごとに1行。各行には対応タスクが少なくとも1つ必要。タスクがない場合は明示的なギャップ理由が必要。
 
-| DDセクション | DD項目 | カテゴリ | カバーするタスク | ギャップステータス | 備考 |
-|---|---|---|---|---|---|
-| [DDのセクション名] | [具体的な項目] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X タスクY] | covered | |
-| セキュリティ考慮事項 | APIの入力バリデーション | prerequisite | — | gap | ユーザー判断によりPhase 2に延期 |
+| Design Doc | DDセクション | DD項目 | カテゴリ | カバーするタスク | ギャップステータス | 備考 |
+|---|---|---|---|---|---|---|
+| [docs/design/XXX.md — 上記の関連ドキュメントのいずれか] | [DDのセクション名] | [具体的な項目] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X タスクY] | covered | |
+| docs/design/XXX.md | セキュリティ考慮事項 | APIの入力バリデーション | prerequisite | — | gap | ユーザー判断によりPhase 2に延期 |
 
 **カテゴリ値**: `impl-target`（実装対象）、`connection-switching`（接続/切替/登録）、`contract-change`（コントラクト変更と伝搬）、`verification`（検証要件）、`prerequisite`（前提作業）
 
@@ -60,6 +60,18 @@ Design Docの各技術要件をカバーするタスクへのマッピング。
 
 **ギャップステータス値**: `covered`（タスクあり）、`gap`（タスクなし — 備考に理由必須、計画承認前にユーザー確認が必要）
 
+## ADR Bindings
+
+ADRが入力として与えられた場合、またはDesign Docの「Prerequisite ADRs」セクションに記載されている場合に本セクションを記載する。実装を拘束する各ADR決定を、それが制約するタスクへマッピングする。該当するADRがない場合は本セクションを省略する。
+
+決定が**実装拘束的**であるのは、コード配置、依存方向、コントラクト/スキーマ形状、データフロー、または永続化を制約する場合である。受入基準と必要な振る舞いはDesign Docに記録される。本表はADR由来の構造的制約のみを扱う。
+
+| ADR | Source Section | Axis | Binding Decision | Covered By Task(s) |
+|---|---|---|---|---|
+| [docs/adr/ADR-XXXX.md] | Decision / Implementation Guidance | placement \| dependency_direction \| contract_schema \| data_flow \| persistence | [実装拘束的な決定文を1つ、該当セクションからコピーまたは要約] | [Phase X タスクY] |
+
+バインディング決定ごとに1行。1つのADRが複数行に寄与しうる。1つのタスクが複数行に現れうる。
+
 ## Connection Map
 
 実装が複数のパッケージ、サービス、またはプロセス境界をまたがる場合のみ本セクションを記載する。各境界を文書化することで、task-decomposerは境界の文脈を両側の実装タスクに伝播できる。実装が単一パッケージ内に収まる場合は本セクションを省略する。

package/.claude/skills-ja/documentation-criteria/references/task-template.md

@@ -17,8 +17,17 @@ Metadata:
 実装開始前に読むべきファイル（ファイルパス、任意でサーチヒント付き）:
 - [例: src/orders/checkout (processOrder関数) — タスクの性質に基づきタスク分解時に決定]
 
+## Binding Decisions
+（作業計画書のADR Bindings表がこのタスクをカバーする場合に本セクションを記載する。それ以外は省略する。）
+
+各行は、このタスクの実装が準拠すべきADR決定である。
+
+| Source | Axis | Decision | Compliance Check |
+|---|---|---|---|
+| [docs/adr/ADR-XXXX.md (§ <Source Section>) — 対応する作業計画書の行のセクション名（`Decision` または `Implementation Guidance`）に置き換える] | [作業計画書のADR Bindings行から逐語コピーしたAxis値] | [作業計画書のADR Bindings行からコピーしたバインディング決定] | [計画中/最終の実装が決定を満たすかをY/Nで判定できる肯定述語] |
+
 ## Investigation Notes
-（実装観察事項を実装開始前にここへ追記する。）
+（実装観察事項を実装開始前にここへ追記する。Binding Decisionsがある場合、計画した実装アプローチと各Compliance Check結果をここに記録する。）
 
 ## Implementation Steps (TDD: Red-Green-Refactor)
 ### 1. Red Phase
@@ -51,6 +60,7 @@ Metadata:
 - [ ] 追加した全テストがパス
 - [ ] Operation Verification Methods に基づく動作確認完了
 - [ ] 成果物作成完了（調査・設計タスクの場合）
+- [ ] （Binding Decisionsがある場合）全てのCompliance Checkが最終実装に対して`Y`と評価され、根拠（file:line、テスト結果、またはコマンド出力）がInvestigation Notesに記録されている
 
 ## Notes
 - 影響範囲: [変更が波及する可能性のある領域]

package/.claude/skills-ja/subagents-orchestration-guide/SKILL.md

@@ -53,6 +53,7 @@ description: サブエージェントのタスク分担と連携を調整。規
 13. **code-verifier**: ドキュメントとコードの整合性を検証。実装前: Design Docの主張を既存コードベースに対して検証。実装後: 実装がDesign Docに準拠しているか検証
 14. **design-sync**: Design Doc間の整合性検証（明示的矛盾のみ検出）
 15. **acceptance-test-generator**: Design DocのACとUI Spec（任意）から統合テストとE2Eテストのスケルトン生成
+16. **ui-analyzer**: フロントエンド設計準備のためUI事実（外部ソース＋既存UIコード）を収集 — 読み取り専用
 
 ## オーケストレーション原則
 
@@ -151,8 +152,9 @@ description: サブエージェントのタスク分担と連携を調整。規
 |-------|---------------|-------------|
 | requirement-analyzer | scale, confidence, adrRequired, crossLayerScope, scopeDependencies, questions | scaleでフローを選択。adrRequiredでADRステップ要否を判断 |
 | codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, qualityAssurance (mechanisms[], domainConstraints[]), focusAreas[], existingElements count, limitations | focusAreasをtechnical-designerにコンテキストとして渡す |
+| ui-analyzer | externalResources (status, per-axis fetch_status), componentStructure[], propsPatterns[], cssLayout[], stateDisplay[], focusAreas[], candidateWriteSet[], limitations | ui-analyzerのJSONをui-spec-designerとtechnical-designer-frontendに渡す。各エージェントは自身の入力宣言に記載されたフィールドを使う |
 | code-verifier | status (consistent/mostly_consistent/needs_review/inconsistent), consistencyScore, discrepancies[], reverseCoverage (dataOperationsInCode, testBoundariesSectionPresent). 実装前: Design Docの主張を既存コードに対して検証。実装後: 実装のDesign Doc整合性を検証（`code_paths`で変更ファイルにスコープ） | discrepanciesをdocument-reviewerに連携 |
-| task-executor | 入力: `task_file`（オーケストレーションフローでは必須）; 任意の Fix Mode シグナル `requiredFixes` または `incompleteImplementations` — いずれかが非空の場合、`task_already_completed` チェックをスキップし、各項目の `file_path` / `location`（`location` は `file[:line]` として解釈）で許可リストを拡張する。出力: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain} | escalation_needed時: escalation_type別に対応 |
+| task-executor | 入力: `task_file`（オーケストレーションフローでは必須）; 任意の Fix Mode シグナル `requiredFixes` または `incompleteImplementations` — いずれかが非空の場合、`task_already_completed` チェックをスキップし、各項目の `file_path` / `location`（`location` は `file[:line]` として解釈）で許可リストを拡張する。出力: status (escalation_needed/completed), filesModified[], testsAdded, requiresTestReview, escalation_type ∈ {task_file_not_found, task_already_completed, target_files_missing, design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file, dependency_version_uncertain, binding_decision_violation} | escalation_needed時: escalation_type別に対応 |
 | quality-fixer | 入力: `task_file`（現在のタスクファイルパス — オーケストレーションフローでは常に渡す）、`filesModified`（上流の実装ステップのレスポンスから抽出 — 当該タスクの書き込み集合を未完成実装検出の主要スコープとして渡す。省略時は `git diff HEAD` にフォールバック）。Status: approved/stub_detected/blocked。`stub_detected` → 上流の実装ステップに `incompleteImplementations[]` の詳細を添えて差し戻し、本実装完了後にquality-fixerを再実行。`blocked` → 下記quality-fixer blockedハンドリング参照 | stub_detected: 実装ステップを再実行。blocked: 下記参照 |
 | document-reviewer | approvalReady (true/false) | trueで次ステップへ。falseで修正を依頼 |
 | design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | CONFLICTS_FOUND時: 矛盾をユーザーに提示してから進む |