create-ai-project 1.20.4 → 1.20.6

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

@@ -1,6 +1,6 @@
 ---
 name: documentation-criteria
-description: Guides PRD, ADR, Design Doc, and Work Plan creation. Use when creating or reviewing technical documents.
+description: Guides PRD, ADR, Design Doc, UI Spec, and Work Plan creation. Use when creating or reviewing technical documents, or when "UI spec/screen design/component decomposition" is mentioned.
 ---
 
 # Documentation Creation Criteria
@@ -53,6 +53,7 @@ description: Guides PRD, ADR, Design Doc, and Work Plan creation. Use when creat
 - Success metrics and KPIs (each metric specifies a numeric target, measurement method, and timeframe)
 - User stories and use cases
 - MoSCoW prioritization (Must/Should/Could/Won't)
+- Acceptance criteria with sequential IDs (AC-001, AC-002, ...) for downstream traceability
 - MVP and Future phase separation
 - User journey diagram (required)
 - Scope boundary diagram (required)

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

@@ -120,6 +120,12 @@ No Ripple Effect:
   - [Explicitly specify unaffected features]
 ```
 
+### Interface Change Matrix
+
+| Existing | New | Conversion Required | Compatibility Method |
+|----------|-----|--------------------|--------------------|
+| [Function/method/operation name] | [Function/method/operation name] | [Yes/No] | [Approach: adapter, wrapper, deprecation, etc.] |
+
 ### Architecture Overview
 
 [How this feature is positioned within the overall system]
@@ -132,10 +138,10 @@ No Ripple Effect:
 
 ### Integration Points List
 
-| Integration Point | Location | Old Implementation | New Implementation | Switching Method |
-|-------------------|----------|-------------------|-------------------|------------------|
-| Integration Point 1 | [Class/Function] | [Existing Process] | [New Process] | [DI/Factory etc.] |
-| Integration Point 2 | [Another Location] | [Existing] | [New] | [Method] |
+| Integration Point | Location | Old Implementation | New Implementation | Switching Method | Verification Method |
+|-------------------|----------|-------------------|-------------------|------------------|-------------------|
+| Integration Point 1 | [Class/Function] | [Existing Process] | [New Process] | [DI/Factory etc.] | [How to verify this switching works] |
+| Integration Point 2 | [Another Location] | [Existing] | [New] | [Method] | [Verification approach] |
 
 ### Main Components
 

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

@@ -24,6 +24,19 @@ Related Issue/PR: #XXX (if any)
 - **Success criteria**: [extracted from Design Doc]
 - **Failure response**: [extracted from Design Doc]
 
+## Design-to-Plan Traceability
+
+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 |
+
+**Category values**: `impl-target` (implementation target), `connection-switching` (connection/switching/registration), `contract-change` (contract change and propagation), `verification` (verification requirement), `prerequisite` (prerequisite work)
+
+**Gap Status values**: `covered` (task exists), `gap` (no task — requires justification in Notes, user confirmation required before plan approval)
+
 ## Objective
 [Why this change is necessary, what problem it solves]
 

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

@@ -50,13 +50,14 @@ C4Context
 
 ### Must Have (P1 - MVP)
 - [ ] Requirement 1: [Detailed description]
-  - AC: [Acceptance criteria - Given/When/Then format or measurable standard]
+  - AC-001: [Acceptance criteria - Given/When/Then format or measurable standard]
+  - AC-002: [Acceptance criteria]
 - [ ] Requirement 2: [Detailed description]
-  - AC: [Acceptance criteria]
+  - AC-003: [Acceptance criteria]
 
 ### Should Have (P2)
 - [ ] Requirement 1: [Detailed description]
-  - AC: [Acceptance criteria]
+  - AC-004: [Acceptance criteria]
 
 ### Could Have (P3)
 - [ ] Requirement 1: [Detailed description]

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

@@ -28,7 +28,7 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro
 
 | AC ID | AC Summary | Screen / State | Prototype Reference (element ID / path) | Adoption Decision |
 |-------|-----------|----------------|----------------------------------------|-------------------|
-| AC-01 | [EARS AC summary] | [Screen / state name] | [element or file reference] | Adopted / Not adopted / On hold |
+| AC-001 | [EARS AC summary] | [Screen / state name] | [element or file reference] | Adopted / Not adopted / On hold |
 
 ## Screen List and Transitions
 
@@ -63,13 +63,13 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro
 
 | State | Default | Loading | Empty | Error | Partial |
 |-------|---------|---------|-------|-------|---------|
-| Display | [Normal display] | [Skeleton / spinner] | [Empty state + CTA] | [Error message + recovery action] | [Cached / partial display] |
+| Display | [Normal display] | [Specific pattern: e.g., Skeleton of `ExistingComponent` / Spinner from `ui/Spinner`] | [Empty state message + CTA: e.g., "No items yet" + `Button` "Create first item"] | [Error message + recovery: e.g., `Alert` variant="error" + `Button` "Retry"] | [Cached display + `Banner` "Connection lost, showing cached data"] |
 
 #### Interaction Definition
 
 | AC ID | EARS Condition | User Action | System Response | State Transition | Error Handling |
 |-------|---------------|-------------|-----------------|-----------------|----------------|
-| AC-01 | When [trigger] | [Click / input / etc.] | [Expected behavior] | [From state -> To state] | [Retry / Reset / Fallback] |
+| AC-001 | When [trigger] | [Click / input / etc.] | [Expected behavior] | [From state -> To state] | [Retry / Reset / Fallback] |
 
 ### Component: [ComponentName2]
 
@@ -78,10 +78,18 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro
 ## Design Tokens and Component Map
 
 ### Environment Constraints
+
 - Target browsers: [e.g., Chrome 120+, Safari 17+]
-- Responsive breakpoints: [e.g., 768px, 1024px, 1280px]
 - Theme support: [e.g., light/dark, system preference]
 
+#### Responsive Behavior
+
+| Breakpoint | Width | Key Changes |
+|-----------|-------|-------------|
+| Mobile | [e.g., < 768px] | [e.g., single column, hamburger nav, 14px body text] |
+| Tablet | [e.g., 768px - 1023px] | [e.g., 2-column grid, collapsed sidebar] |
+| Desktop | [e.g., ≥ 1024px] | [e.g., full layout, expanded nav, sidebar visible] |
+
 ### Existing Component Reuse Map
 
 | UI Element | Decision | Existing Component | Notes |
@@ -92,10 +100,56 @@ Map PRD acceptance criteria to prototype references. Skip this section if no pro
 
 ### Design Tokens
 
+#### Color Roles
+
+| Role | Token | Value | Usage |
+|------|-------|-------|-------|
+| Background Surface | [bg-primary] | [e.g., #FFFFFF] | [Page background] |
+| Background Surface | [bg-secondary] | [e.g., #F9FAFB] | [Card, section background] |
+| Text | [text-primary] | [e.g., #111827] | [Headings, body text] |
+| Text | [text-secondary] | [e.g., #6B7280] | [Captions, placeholders] |
+| Brand / Accent | [color-brand] | [e.g., #1A73E8] | [Primary actions, links] |
+| Status | [color-success] | [e.g., #22C55E] | [Success states, confirmations] |
+| Status | [color-error] | [e.g., #EF4444] | [Error states, destructive actions] |
+| Border | [border-primary] | [e.g., #E5E7EB] | [Card borders, dividers] |
+
+#### Typography Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing |
+|------|------|------|--------|-------------|----------------|
+| Heading 1 | [e.g., Inter] | [e.g., 30px] | [e.g., 700] | [e.g., 1.2] | [e.g., -0.02em] |
+| Heading 2 | [e.g., Inter] | [e.g., 24px] | [e.g., 600] | [e.g., 1.3] | [e.g., -0.01em] |
+| Body | [e.g., Inter] | [e.g., 16px] | [e.g., 400] | [e.g., 1.5] | [e.g., 0] |
+| Caption | [e.g., Inter] | [e.g., 12px] | [e.g., 400] | [e.g., 1.4] | [e.g., 0.01em] |
+| Monospace | [e.g., JetBrains Mono] | [e.g., 14px] | [e.g., 400] | [e.g., 1.6] | [e.g., 0] |
+
+#### Spacing Scale
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| [spacing-xs] | [e.g., 4px] | [Inline element gaps] |
+| [spacing-sm] | [e.g., 8px] | [Compact padding] |
+| [spacing-md] | [e.g., 16px] | [Default component padding] |
+| [spacing-lg] | [e.g., 24px] | [Section spacing] |
+| [spacing-xl] | [e.g., 40px] | [Page section separation] |
+
+#### Elevation (Depth)
+
+| Level | Treatment | Usage |
+|-------|-----------|-------|
+| 0 (Flat) | [e.g., none] | [Inline elements, text] |
+| 1 (Raised) | [e.g., 0 1px 2px rgba(0,0,0,0.05)] | [Cards, buttons] |
+| 2 (Floating) | [e.g., 0 4px 12px rgba(0,0,0,0.1)] | [Dropdowns, popovers] |
+| 3 (Overlay) | [e.g., 0 8px 24px rgba(0,0,0,0.15)] | [Modals, dialogs] |
+
+#### Border Radius Scale
+
 | Token | Value | Usage |
 |-------|-------|-------|
-| [color-primary] | [value] | [Primary actions] |
-| [spacing-md] | [value] | [Component spacing] |
+| [radius-sm] | [e.g., 4px] | [Badges, chips] |
+| [radius-md] | [e.g., 8px] | [Cards, inputs] |
+| [radius-lg] | [e.g., 12px] | [Modals, panels] |
+| [radius-full] | [e.g., 9999px] | [Avatars, pills] |
 
 ## Visual Acceptance
 

package/.claude/skills-en/integration-e2e-testing/SKILL.md

@@ -57,16 +57,57 @@ Each test MUST include the following annotations.
 // fast-check: fc.property(fc.[arbitrary], (input) => [invariant])
 ```
 
+## Multi-Step User Journey Definition
+
+A feature qualifies as containing a **multi-step user journey** when ALL of the following are true:
+
+1. **2+ distinct interaction boundaries** are traversed in sequence to complete a user goal. What counts as a boundary depends on the system type:
+   - Web: distinct routes/pages
+   - Mobile native: distinct screens/views
+   - CLI: distinct command invocations or interactive prompts
+   - API: distinct API calls forming a transaction (e.g., create → confirm → finalize)
+2. **State carries across steps** — data produced or actions taken in one step affect what the next step accepts or displays
+3. **The journey has a completion point** — a final state the user or caller reaches (e.g., confirmation page, saved record, API success response, completed workflow)
+
+### User-Facing vs Service-Internal Journeys
+
+Multi-step journeys are further classified for E2E budget decisions:
+
+| Classification | Condition | E2E Reserved Slot | Example |
+|---|---|---|---|
+| **User-facing** | A human user directly triggers and observes the steps (via UI, CLI, or direct API interaction) | Eligible | Web checkout flow, CLI setup wizard, mobile onboarding |
+| **Service-internal** | Steps are triggered by backend services without direct user interaction | Not eligible for reserved slot | Async job pipeline, service-to-service saga, scheduled batch processing |
+
+**Scope of this classification**:
+- **Reserved E2E slot**: Only user-facing journeys qualify. Service-internal journeys are excluded from the reserved slot.
+- **Normal ROI > 50 path**: Both user-facing and service-internal journeys compete for the additional E2E slot (up to 1) on ROI merit alone. Classification does not affect this path.
+- **E2E Gap Check**: Only user-facing journeys trigger the gap warning. Service-internal journeys do not.
+
 ### ROI Calculation
 
+ROI is used to **rank candidates within the same test type** (integration candidates against each other, E2E candidates against each other). Cross-type comparison is unnecessary because integration and E2E budgets are selected independently.
+
 ```
-ROI = (Business Value x Frequency + Legal Requirement x 10 + Defect Detection) / Total Cost
+ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection
+              (range: 0–120)
 ```
 
-| Type | Total Cost | E2E Generation Condition |
-|------|------------|-------------------------|
-| Integration | 11 | - |
-| E2E | 38 | ROI > 50 |
+Higher ROI Score = higher priority within its test type. No normalization or capping is applied — the raw score is used directly for ranking. Deduplication is a separate step that removes candidates entirely; it does not modify scores.
+
+### ROI Threshold for E2E
+
+E2E tests have high ownership cost (creation, execution, and maintenance are each 3-10× higher than integration tests). To justify creation, an E2E candidate (beyond the must-keep reserved slot) requires **ROI Score > 50**.
+
+### ROI Calculation Examples
+
+| Scenario | BV | Freq | Legal | Defect | ROI Score | Test Type | Selection Outcome |
+|----------|----|------|-------|--------|-----------|-----------|-------------------|
+| Core checkout flow | 10 | 9 | true | 9 | 109 | E2E | Selected (reserved slot: user-facing multi-step journey) |
+| Payment error handling | 8 | 3 | false | 7 | 31 | E2E | Below threshold (31 < 50), not selected |
+| Profile save flow | 7 | 6 | false | 6 | 48 | E2E | Below threshold (48 < 50), not selected |
+| DB persistence check | 8 | 8 | false | 8 | 72 | Integration | Selected (rank 1 of 3) |
+| Error message display | 5 | 3 | false | 4 | 19 | Integration | Selected (rank 2 of 3) |
+| Optional filter toggle | 3 | 4 | false | 2 | 14 | Integration | Not selected (rank 4, budget full) |
 
 ## Implementation Rules
 

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

@@ -134,12 +134,12 @@ Subagents respond in JSON format. Key fields for orchestrator decisions:
 | codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations | Pass focusAreas to technical-designer as context |
 | 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 | status (escalation_needed/completed), escalation_type, testsAdded, requiresTestReview | On escalation_needed: handle by escalation_type (design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file) |
-| quality-fixer | status (approved/blocked), reason, blockingIssues[], missingPrerequisites[] | On blocked: see quality-fixer blocked handling below |
+| quality-fixer | status (approved/stub_detected/blocked). `stub_detected` → route back to task-executor with `incompleteImplementations[]` details for completion, then re-run quality-fixer. `blocked` → see quality-fixer blocked handling below | On stub_detected: re-invoke task-executor. On blocked: see handling below |
 | document-reviewer | approvalReady (true/false) | Proceed to next step on true; request fixes on false |
-| design-sync | sync_status (synced/conflicts_found) | On conflicts_found: present conflicts to user before proceeding |
+| design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | On CONFLICTS_FOUND: present conflicts to user before proceeding |
 | integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | On needs_revision: pass requiredFixes back to task-executor |
 | security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | On needs_revision: pass requiredFixes back to task-executor |
-| acceptance-test-generator | status, generatedFiles | Pass generatedFiles to work-planner |
+| acceptance-test-generator | status, generatedFiles (integration: path\|null, e2e: path\|null), budgetUsage, e2eAbsenceReason (null when E2E emitted, otherwise: no_multi_step_journey\|below_threshold_user_confirmed) | Verify files exist, pass to work-planner with absence reason |
 
 ### quality-fixer Blocked Handling
 
@@ -301,7 +301,13 @@ Construct the prompt from the agent's Input Parameters section and the deliverab
 
    #### technical-designer → work-planner
 
-   **Pass to work-planner**: Design Doc path. Work-planner extracts Verification Strategy from the Design Doc and includes it in the work plan header.
+   **Pass to work-planner**: Design Doc path. Work-planner scans all DD sections and extracts technical requirements per its Step 5 categories (impl-target, connection-switching, contract-change, verification, prerequisite), then produces a Design-to-Plan Traceability table.
+
+   **Gap handling (orchestrator responsibility)**: If work-planner outputs a draft plan containing `gap` entries, the orchestrator MUST:
+   1. Present the gap entries to the user with justifications
+   2. Keep the plan in draft status until the user confirms each gap
+   3. Do NOT pass the plan to downstream agents (task-decomposer, etc.) until all gaps are resolved or confirmed
+   Unjustified gaps are errors — return to work-planner to add covering tasks or justification.
 
    #### *1 acceptance-test-generator → work-planner
 
@@ -310,14 +316,16 @@ Construct the prompt from the agent's Input Parameters section and the deliverab
    - UI Spec: [path] (if exists)
 
    **Orchestrator verification items**:
-   - Verify integration test file path retrieval and existence
-   - Verify E2E test file path retrieval and existence
+   - Verify `generatedFiles.integration` is a valid path (when not null) and the file exists
+   - Verify `generatedFiles.e2e` is a valid path (when not null) and the file exists
+   - When `generatedFiles.e2e` is null, verify `e2eAbsenceReason` is present — this is intentional absence, not an error
 
    **Pass to work-planner**:
    - Integration test file: [path] (create and execute simultaneously with each phase implementation)
-   - E2E test file: [path] (execute only in final phase)
+   - E2E test file: [path] or null (execute only in final phase, when provided)
+   - E2E absence reason: [reason] (when E2E is null — pass this so work-planner can skip E2E Gap Check for intentional absence)
 
-   **On error**: Escalate to user if files are not generated
+   **On error**: Escalate to user if integration file generation failed unexpectedly (status != completed). E2E being null with a valid absence reason is not an error.
 3. **ADR Status Management**: Update ADR status after user decision (Accepted/Rejected)
 
 ## Important Constraints

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

@@ -1,6 +1,6 @@
 ---
 name: documentation-criteria
-description: PRD、ADR、Design Doc、作業計画書の作成を支援。技術ドキュメントの作成・レビュー時に使用。
+description: PRD、ADR、Design Doc、UI Spec、作業計画書の作成を支援。技術ドキュメントの作成・レビュー時、または「UI Spec/画面設計/コンポーネント分解」が言及された時に使用。
 ---
 
 # ドキュメント作成基準
@@ -53,6 +53,7 @@ description: PRD、ADR、Design Doc、作業計画書の作成を支援。技術
 - 成功指標とKPI（各指標に数値目標、測定方法、期間を明記）
 - ユーザーストーリーとユースケース
 - MoSCoW法による優先順位（Must/Should/Could/Won't）
+- 受入基準に連番ID（AC-001, AC-002, ...）を付与し、下流でのトレーサビリティを確保
 - MVPとFutureフェーズの分離
 - ユーザージャーニー図（必須）
 - スコープ境界図（必須）

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

@@ -120,6 +120,12 @@ unknowns:
   - [明示的に影響を受けない機能]
 ```
 
+### インターフェース変更マトリクス
+
+| 既存 | 新規 | 変換要否 | 互換方式 |
+|------|------|---------|---------|
+| [関数/メソッド/操作名] | [関数/メソッド/操作名] | [Yes/No] | [手法: adapter, wrapper, deprecation等] |
+
 ### アーキテクチャ概要
 
 [この機能がシステム全体の中でどのように位置づけられるか]
@@ -132,10 +138,10 @@ unknowns:
 
 ### 統合ポイント一覧
 
-| 統合ポイント | 箇所 | 旧実装 | 新実装 | 切替方式 |
-|------------|-----|-------|-------|---------|
-| 統合ポイント1 | [クラス/関数] | [既存処理] | [新処理] | [DI/Factoryなど] |
-| 統合ポイント2 | [別の箇所] | [既存] | [新規] | [方式] |
+| 統合ポイント | 箇所 | 旧実装 | 新実装 | 切替方式 | 検証方式 |
+|------------|-----|-------|-------|---------|---------|
+| 統合ポイント1 | [クラス/関数] | [既存処理] | [新処理] | [DI/Factoryなど] | [この切替が動作することの検証方法] |
+| 統合ポイント2 | [別の箇所] | [既存] | [新規] | [方式] | [検証方法] |
 
 ### 主要コンポーネント
 

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

@@ -24,6 +24,19 @@
 - **成功基準**: [Design Docから抽出]
 - **失敗時の対応**: [Design Docから抽出]
 
+## 設計-計画トレーサビリティ
+
+Design Docの各技術要件をカバーするタスクへのマッピング。抽出した項目ごとに1行。各行には対応タスクが少なくとも1つ必要。タスクがない場合は明示的なギャップ理由が必要。
+
+| DDセクション | DD項目 | カテゴリ | カバーするタスク | ギャップステータス | 備考 |
+|---|---|---|---|---|---|
+| [DDのセクション名] | [具体的な項目] | impl-target / connection-switching / contract-change / verification / prerequisite | [Phase X タスクY] | covered | |
+| セキュリティ考慮事項 | APIの入力バリデーション | prerequisite | — | gap | ユーザー判断によりPhase 2に延期 |
+
+**カテゴリ値**: `impl-target`（実装対象）、`connection-switching`（接続/切替/登録）、`contract-change`（コントラクト変更と伝搬）、`verification`（検証要件）、`prerequisite`（前提作業）
+
+**ギャップステータス値**: `covered`（タスクあり）、`gap`（タスクなし — 備考に理由必須、計画承認前にユーザー確認が必要）
+
 ## 目的
 [なぜこの変更が必要か、何を解決するか]
 

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

@@ -50,13 +50,14 @@ C4Context
 
 ### Must Have (P1 - MVP)
 - [ ] 要件1: [詳細説明]
-  - AC: [受入条件 - Given/When/Then形式または測定可能な基準]
+  - AC-001: [受入条件 - Given/When/Then形式または測定可能な基準]
+  - AC-002: [受入条件]
 - [ ] 要件2: [詳細説明]
-  - AC: [受入条件]
+  - AC-003: [受入条件]
 
 ### Should Have (P2)
 - [ ] 要件1: [詳細説明]
-  - AC: [受入条件]
+  - AC-004: [受入条件]
 
 ### Could Have (P3)
 - [ ] 要件1: [詳細説明]

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

@@ -28,7 +28,7 @@ PRDの受入条件をプロトタイプの参照先にマッピング。プロ
 
 | AC ID | AC概要 | 画面 / 状態 | プロトタイプ参照先（要素ID / パス） | 採用判定 |
 |-------|--------|------------|----------------------------------|---------|
-| AC-01 | [EARS AC概要] | [画面名 / 状態名] | [要素またはファイルの参照先] | 採用 / 不採用 / 保留 |
+| AC-001 | [EARS AC概要] | [画面名 / 状態名] | [要素またはファイルの参照先] | 採用 / 不採用 / 保留 |
 
 ## 画面リストと遷移
 
@@ -62,14 +62,14 @@ PRDの受入条件をプロトタイプの参照先にマッピング。プロ
 #### 状態×表示マトリクス
 
 | 状態 | デフォルト | ローディング | Empty | エラー | 部分表示 |
-|------|----------|------------|-------|-------|---------|
-| 表示 | [通常表示] | [スケルトン / スピナー] | [Empty状態 + CTA] | [エラーメッセージ + 回復アクション] | [キャッシュ / 部分表示] |
+|------|---------|---------|-------|-------|---------|
+| 表示 | [通常表示] | [具体パターン: 例 `ExistingComponent`のSkeleton / `ui/Spinner`] | [Emptyメッセージ + CTA: 例 "データがありません" + `Button` "新規作成"] | [エラーメッセージ + 回復: 例 `Alert` variant="error" + `Button` "再試行"] | [キャッシュ表示 + `Banner` "接続が切断されました。キャッシュデータを表示中"] |
 
 #### インタラクション定義
 
 | AC ID | EARS条件 | ユーザーアクション | システムレスポンス | 状態遷移 | エラーハンドリング |
 |-------|---------|-----------------|------------------|---------|-----------------|
-| AC-01 | When [トリガー] | [クリック / 入力 / 等] | [期待される動作] | [遷移元状態 → 遷移先状態] | [リトライ / リセット / フォールバック] |
+| AC-001 | When [トリガー] | [クリック / 入力 / 等] | [期待される動作] | [遷移元状態 → 遷移先状態] | [リトライ / リセット / フォールバック] |
 
 ### コンポーネント: [ComponentName2]
 
@@ -78,10 +78,18 @@ PRDの受入条件をプロトタイプの参照先にマッピング。プロ
 ## デザイントークンとコンポーネントマップ
 
 ### 環境制約
+
 - 対象ブラウザ: [例: Chrome 120+, Safari 17+]
-- レスポンシブBreakpoint: [例: 768px, 1024px, 1280px]
 - テーマ対応: [例: ライト/ダーク、システム設定に追従]
 
+#### レスポンシブ動作
+
+| ブレークポイント | 幅 | 主な変更点 |
+|----------------|-----|-----------|
+| モバイル | [例: < 768px] | [例: シングルカラム、ハンバーガーナビ、本文14px] |
+| タブレット | [例: 768px - 1023px] | [例: 2カラムグリッド、サイドバー折りたたみ] |
+| デスクトップ | [例: ≥ 1024px] | [例: フルレイアウト、ナビ展開、サイドバー表示] |
+
 ### 既存コンポーネント再利用マップ
 
 | UI要素 | 判定 | 既存コンポーネント | 備考 |
@@ -92,10 +100,56 @@ PRDの受入条件をプロトタイプの参照先にマッピング。プロ
 
 ### デザイントークン
 
+#### Color Roles
+
+| ロール | トークン | 値 | 用途 |
+|--------|---------|-----|------|
+| Background Surface | [bg-primary] | [例: #FFFFFF] | [ページ背景] |
+| Background Surface | [bg-secondary] | [例: #F9FAFB] | [カード、セクション背景] |
+| Text | [text-primary] | [例: #111827] | [見出し、本文] |
+| Text | [text-secondary] | [例: #6B7280] | [キャプション、プレースホルダー] |
+| Brand / Accent | [color-brand] | [例: #1A73E8] | [プライマリアクション、リンク] |
+| Status | [color-success] | [例: #22C55E] | [成功状態、確認] |
+| Status | [color-error] | [例: #EF4444] | [エラー状態、破壊的アクション] |
+| Border | [border-primary] | [例: #E5E7EB] | [カードボーダー、区切り線] |
+
+#### Typography Hierarchy
+
+| ロール | フォント | サイズ | ウェイト | 行間 | 字間 |
+|--------|---------|--------|---------|------|------|
+| Heading 1 | [例: Inter] | [例: 30px] | [例: 700] | [例: 1.2] | [例: -0.02em] |
+| Heading 2 | [例: Inter] | [例: 24px] | [例: 600] | [例: 1.3] | [例: -0.01em] |
+| Body | [例: Inter] | [例: 16px] | [例: 400] | [例: 1.5] | [例: 0] |
+| Caption | [例: Inter] | [例: 12px] | [例: 400] | [例: 1.4] | [例: 0.01em] |
+| Monospace | [例: JetBrains Mono] | [例: 14px] | [例: 400] | [例: 1.6] | [例: 0] |
+
+#### Spacing Scale
+
+| トークン | 値 | 用途 |
+|---------|-----|------|
+| [spacing-xs] | [例: 4px] | [インライン要素間のギャップ] |
+| [spacing-sm] | [例: 8px] | [コンパクトなパディング] |
+| [spacing-md] | [例: 16px] | [デフォルトのコンポーネントパディング] |
+| [spacing-lg] | [例: 24px] | [セクション間隔] |
+| [spacing-xl] | [例: 40px] | [ページセクション間の分離] |
+
+#### Elevation（Depth）
+
+| レベル | 値 | 用途 |
+|--------|-----|------|
+| 0 (Flat) | [例: none] | [インライン要素、テキスト] |
+| 1 (Raised) | [例: 0 1px 2px rgba(0,0,0,0.05)] | [カード、ボタン] |
+| 2 (Floating) | [例: 0 4px 12px rgba(0,0,0,0.1)] | [ドロップダウン、ポップオーバー] |
+| 3 (Overlay) | [例: 0 8px 24px rgba(0,0,0,0.15)] | [モーダル、ダイアログ] |
+
+#### Border Radius Scale
+
 | トークン | 値 | 用途 |
 |---------|-----|------|
-| [color-primary] | [値] | [プライマリアクション] |
-| [spacing-md] | [値] | [コンポーネント間隔] |
+| [radius-sm] | [例: 4px] | [バッジ、チップ] |
+| [radius-md] | [例: 8px] | [カード、入力フィールド] |
+| [radius-lg] | [例: 12px] | [モーダル、パネル] |
+| [radius-full] | [例: 9999px] | [アバター、ピル] |
 
 ## ビジュアル受入条件
 

package/.claude/skills-ja/integration-e2e-testing/SKILL.md

@@ -59,16 +59,56 @@ it.todo('[AC番号]: [テスト名]')
 it.todo('[AC番号]-property: [不変条件記述]')
 ```
 
+## マルチステップユーザージャーニーの定義
+
+以下の3条件を**すべて**満たす場合、その機能にはマルチステップユーザージャーニーが含まれる:
+
+1. **2つ以上の異なるインタラクション境界**をユーザーゴール達成のために順番に通過する。何が境界に該当するかはシステムタイプによる:
+   - Web: 異なるルート/ページ
+   - モバイルネイティブ: 異なる画面/ビュー
+   - CLI: 異なるコマンド呼び出しまたは対話型プロンプト
+   - API: トランザクションを形成する異なるAPI呼び出し（例: 作成 → 確認 → 確定）
+2. **ステップ間で状態が伝搬する** — あるステップで生成されたデータや実行されたアクションが、次のステップの受け入れや表示に影響する
+3. **ジャーニーに完了ポイントがある** — ユーザーまたは呼び出し元が到達する最終状態（例: 確認ページ、保存されたレコード、API成功レスポンス、完了したワークフロー）
+
+### ユーザー向け vs サービス内部の分類
+
+マルチステップジャーニーはE2E予算判断のためにさらに分類される:
+
+| 分類 | 条件 | E2E予約スロット | 例 |
+|------|------|----------------|-----|
+| **ユーザー向け** | 人間のユーザーが直接ステップをトリガーし結果を観察する（UI、CLI、または直接的なAPIインタラクション経由） | 対象 | Web購入フロー、CLIセットアップウィザード、モバイルオンボーディング |
+| **サービス内部** | バックエンドサービスがユーザーの直接操作なしにステップをトリガーする | 予約スロット対象外 | 非同期ジョブパイプライン、サービス間saga、スケジュールバッチ処理 |
+
+**この分類のスコープ**:
+- **E2E予約スロット**: ユーザー向けジャーニーのみが対象。サービス内部ジャーニーは予約スロットから除外される。
+- **通常のROI > 50パス**: ユーザー向け・サービス内部の両方が追加E2Eスロット（最大1件）をROI実績で競う。この分類はこのパスに影響しない。
+- **E2Eギャップチェック**: ユーザー向けジャーニーのみがgap警告をトリガーする。サービス内部ジャーニーはトリガーしない。
+
 ### ROI計算
 
 ```
-ROI = (ビジネス価値 × 頻度 + 法的要件 × 10 + 欠陥検出) / 総コスト
+ROI Score = Business Value × User Frequency + Legal Requirement × 10 + Defect Detection（範囲: 0–120）
 ```
 
-| 種別 | 総コスト | E2E生成条件 |
-|------|---------|------------|
-| 統合 | 11 | - |
-| E2E | 38 | ROI > 50 |
+ROI Scoreは**同一テスト種別内での優先順位付け**に使用する（統合テスト同士、E2Eテスト同士）。テスト種別間の比較には使用しない。統合とE2Eの予算は独立して選択されるため、種別間比較は不要。
+
+ROI Scoreが高い = 同一テスト種別内での優先度が高い。正規化やキャッピングは適用しない — 生のスコアをそのままランキングに使用する。重複排除は候補自体を除外する別のステップであり、スコアは変更しない。
+
+#### E2EのROI閾値
+
+E2Eテストは所有コストが高い（作成・実行・保守それぞれが統合テストの3〜10倍）。予約スロット（ユーザー向けマルチステップジャーニー）を超える追加E2Eスロットには **ROI Score > 50** が必要。
+
+#### ROI計算例
+
+| シナリオ | BV | Freq | Legal | Defect | ROI Score | テスト種別 | 選択結果 |
+|----------|----|------|-------|--------|-----------|-----------|---------|
+| コア決済フロー | 10 | 9 | true | 9 | 109 | E2E | 選択（予約スロット: ユーザー向けマルチステップジャーニー） |
+| 決済エラー処理 | 8 | 3 | false | 7 | 31 | E2E | 閾値未満（31 < 50）、不選択 |
+| プロフィール保存フロー | 7 | 6 | false | 6 | 48 | E2E | 閾値未満（48 < 50）、不選択 |
+| DB永続化チェック | 8 | 8 | false | 8 | 72 | 統合 | 選択（3件中ランク1位） |
+| エラーメッセージ表示 | 5 | 3 | false | 4 | 19 | 統合 | 選択（3件中ランク2位） |
+| 任意フィルタ切替 | 3 | 4 | false | 2 | 14 | 統合 | 不選択（ランク4位、上限到達） |
 
 ## 実装ルール
 

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

@@ -132,12 +132,12 @@ description: サブエージェントのタスク分担と連携を調整。規
 | codebase-analyzer | analysisScope.categoriesDetected, dataModel.detected, focusAreas[], existingElements count, limitations | focusAreasをtechnical-designerにコンテキストとして渡す |
 | 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 | status (escalation_needed/completed), escalation_type, testsAdded, requiresTestReview | escalation_needed時: escalation_type別に対応（design_compliance_violation, similar_function_found, similar_component_found, investigation_target_not_found, out_of_scope_file） |
-| quality-fixer | status (approved/blocked), reason, blockingIssues[], missingPrerequisites[] | blocked時: 下記quality-fixer blockedハンドリング参照 |
+| quality-fixer | status (approved/stub_detected/blocked), reason, blockingIssues[], missingPrerequisites[] | approved: コミット可。stub_detected: スタブ実装を検出、task-executorに差し戻して本実装を完了させる。blocked: 下記quality-fixer blockedハンドリング参照 |
 | document-reviewer | approvalReady (true/false) | trueで次ステップへ。falseで修正を依頼 |
-| design-sync | sync_status (synced/conflicts_found) | conflicts_found時: 矛盾をユーザーに提示してから進む |
+| design-sync | sync_status (NO_CONFLICTS/CONFLICTS_FOUND) | CONFLICTS_FOUND時: 矛盾をユーザーに提示してから進む |
 | integration-test-reviewer | status (approved/needs_revision/blocked), requiredFixes | needs_revision時: requiredFixesをtask-executorに戻す |
 | security-reviewer | status (approved/approved_with_notes/needs_revision/blocked), findings, notes, requiredFixes | needs_revision時: requiredFixesをtask-executorに戻す |
-| acceptance-test-generator | status, generatedFiles | generatedFilesをwork-plannerに渡す |
+| acceptance-test-generator | status, generatedFiles { integration: string, e2e: string | null }, e2eAbsenceReason: string | null | generatedFiles.integrationとgeneratedFiles.e2e（nullable）をwork-plannerに渡す。e2eがnullの場合、e2eAbsenceReasonが妥当であればエラーではない |
 
 ### quality-fixer blockedハンドリング
 
@@ -297,7 +297,13 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
 
    #### technical-designer → work-planner
 
-   **work-plannerへの入力**: Design Docパス。work-plannerがDesign Docから検証戦略を抽出し、作業計画書ヘッダーに記載する。
+   **work-plannerへの入力**: Design Docパス。work-plannerがDDの全セクションをスキャンし、Step 5のカテゴリ（impl-target, connection-switching, contract-change, verification, prerequisite）に沿って技術要件を抽出した上で、設計-計画トレーサビリティ表を作成する。
+
+   **ギャップ発生時の制御（オーケストレーターの責務）**: work-plannerが`gap`を含むドラフト計画書を出力した場合、オーケストレーターは以下を実行する:
+   1. ギャップ項目と理由をユーザーに提示する
+   2. ユーザーが各ギャップを確認するまで計画書をドラフト状態に保つ
+   3. 全ギャップの解消または確認が完了するまで、後続エージェント（task-decomposer等）に計画書を渡さない
+   理由なしのギャップはエラーとして扱い、work-plannerに差し戻してカバーするタスクの追加または理由の記載を求める。
 
    #### *1 acceptance-test-generator → work-planner
 
@@ -306,14 +312,16 @@ requirement-analyzerが複数レイヤー（backend + frontend）にまたがる
    - UI Spec: [パス]（存在する場合）
 
    **オーケストレーター確認項目**:
-   - 統合テストファイルパスの取得と存在確認
-   - E2Eテストファイルパスの取得と存在確認
+   - `generatedFiles.integration`が有効なパスであり（nullでない場合）、ファイルが存在すること
+   - `generatedFiles.e2e`が有効なパスであり（nullでない場合）、ファイルが存在すること
+   - `generatedFiles.e2e`がnullの場合、`e2eAbsenceReason`が存在すること — これは意図的な不在であり、エラーではない
 
    **work-plannerへの入力**:
    - 統合テストファイル: [パス]（各フェーズの実装と同時に作成・実行）
-   - E2Eテストファイル: [パス]（最終フェーズでのみ実行）
+   - E2Eテストファイル: [パス]またはnull（提供された場合のみ最終フェーズで実行）
+   - E2E不在理由: [理由]（E2Eがnullの場合 — work-plannerがE2Eギャップチェックをスキップするために渡す）
 
-   **エラー時**: ファイルが生成されない場合はユーザーにエスカレーション
+   **エラー時**: 統合テストファイル生成が予期せず失敗した場合（status != completed）はユーザーにエスカレーション。E2Eがnullかつ不在理由が妥当な場合はエラーではない。
 3. **ADRステータス管理**: ユーザー判断後のADRステータス更新（Accepted/Rejected）
 
 ## 重要な制約