create-ai-project 1.22.1 → 1.23.0

package/.claude/commands-en/design.md

@@ -1,5 +1,5 @@
 ---
-description: Execute from requirement analysis to design document creation
+description: Execute from codebase analysis to design document creation
 ---
 
 **Command Context**: This command is dedicated to the design phase.
@@ -9,46 +9,36 @@ description: Execute from requirement analysis to design document creation
 **Core Identity**: "I am not a worker. I am an orchestrator." (see subagents-orchestration-guide skill)
 
 **Execution Protocol**:
-1. **Delegate all work through Agent tool** — invoke sub-agents, pass data between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools")
-2. **Follow subagents-orchestration-guide skill design flow exactly**:
-   - Execute: requirement-analyzer → codebase-analyzer → technical-designer → code-verifier → document-reviewer → design-sync
-   - **ADR-only**: Skip codebase-analyzer and code-verifier (these apply to Design Doc only)
+1. **Delegate all work through Agent tool** — invoke sub-agents, pass data between them, and report results (permitted tools: see subagents-orchestration-guide "Orchestrator's Permitted Tools"). The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files.
+2. **Run the design flow below in order** — a fixed linear sequence, no branches:
+   - Execute: scope bootstrap → codebase-analyzer → [Stop: Scope confirmation] → technical-designer → code-verifier → document-reviewer → design-sync
+   - technical-designer creates a prerequisite ADR when the design involves an architecture decision (per documentation-criteria); the ADR never replaces the Design Doc — the flow always continues through Design Doc creation and the full verification chain
    - **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding
 3. **Scope**: Complete when design documents receive approval
 
-**CRITICAL**: NEVER skip document-reviewer, design-sync, or stopping points defined in subagents-orchestration-guide skill flows.
+**subagents-orchestration-guide usage**: Reference the guide for orchestration principles (Delegation Boundary, Decision precedence, permitted tools) and the Scale Determination table. This command defines its own start order; the guide's requirement-analyzer-origin flow does not apply here.
+
+**CRITICAL**: NEVER skip document-reviewer, design-sync (for Design Docs), or stopping points — each serves as a quality gate.
 
 ## Workflow Overview
 
 ```
-Requirements → requirement-analyzer → [Stop: Scale determination]
-                                           ↓
-                                   codebase-analyzer → technical-designer
-                                           ↓
-                                   code-verifier → document-reviewer
-                                           ↓
-                                      design-sync → [Stop: Design approval]
+Requirements → scope bootstrap → codebase-analyzer → [Stop: Scope confirmation]
+                                                            ↓
+                                                    technical-designer
+                                                            ↓
+                                                    code-verifier → document-reviewer
+                                                            ↓
+                                                       design-sync → [Stop: Design approval]
 ```
 
-Requirements: $ARGUMENTS
-
-Considering the deep impact on design, first engage in dialogue to understand the background and purpose of requirements:
-- What problems do you want to solve?
-- Expected outcomes and success criteria
-- Relationship with existing systems
-
-Once requirements are moderately clarified, analyze with requirement-analyzer and create appropriate design documents according to scale.
-
-Clearly present design alternatives and trade-offs.
-
-Execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer and code-verifier invocations.
-
 ## Scope Boundaries
 
 **Included in this command**:
-- Requirement analysis with requirement-analyzer
-- Codebase analysis with codebase-analyzer (before technical design)
-- ADR creation (if architecture changes, new technology, or data flow changes)
+- Scope bootstrap: locating seed files so codebase-analyzer receives a populated input
+- Codebase analysis with codebase-analyzer (entry point of the design phase)
+- Scope confirmation with the user, grounded in codebase-analyzer findings
+- ADR creation as a prerequisite to the Design Doc, when architecture changes, new technology, or data flow changes are involved
 - Design Doc creation with technical-designer
 - Design Doc verification with code-verifier (before document review)
 - Document review with document-reviewer
@@ -58,29 +48,65 @@ Execute the process below within design scope. Follow subagents-orchestration-gu
 
 ## Execution Flow
 
-1. requirement-analyzer → Requirement analysis
-2. codebase-analyzer → Codebase analysis (pass requirement-analyzer output)
-3. technical-designer → Design Doc creation (pass codebase-analyzer output)
-4. code-verifier → Verify Design Doc against existing code
-5. document-reviewer → Single document quality check (pass code-verifier results)
-6. User approval (WAIT for approval)
-7. design-sync → Design Doc consistency verification
+Requirements: $ARGUMENTS
+
+### Step 1: Scope Bootstrap
+codebase-analyzer requires a populated `requirement_analysis.affectedFiles`. Build that seed with a lightweight, orchestrator-local pass — locating files only, with no deep reading and no design decisions:
+
+1. Extract candidate keywords from the user requirements (feature names, domain nouns, identifiers).
+2. Search the repository with Bash (`rg`, or `grep` when `rg` is unavailable) for files matching those keywords.
+3. Collect the matched file paths as the seed `affectedFiles`.
+4. **When the search returns no files**: ask the user which files or modules the design targets (AskUserQuestion), and use that answer as `affectedFiles`. If the user confirms no related code exists, report that codebase-grounded design does not apply and confirm with the user how to proceed.
+5. **When the search returns more than ~20 files**: the keywords are too broad. Present the most relevant candidates to the user (AskUserQuestion) and confirm the seed `affectedFiles` before proceeding.
+
+This step locates seed files only. Reading files in full, tracing dependencies, and analysis remain codebase-analyzer's responsibility.
+
+### Step 2: Codebase Analysis
+- Invoke **codebase-analyzer** using Agent tool
+  - `subagent_type: "codebase-analyzer"`, `description: "Codebase analysis"`
+  - `prompt`: include `requirements` (the user requirements verbatim) and `requirement_analysis` — a JSON object with `affectedFiles` (Step 1 seed), `purpose` (the user requirements), `scale` (provisional value from the Scale Determination table applied to the seed file count), `technicalConsiderations` (`{ constraints: [], risks: [], dependencies: [] }`)
+
+### Step 3: Scope Confirmation
+After codebase-analyzer returns, confirm the design scope with the user before any design work. Use AskUserQuestion.
+
+Present, sourced from the codebase-analyzer JSON:
+- **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to
+- **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas`
+- **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded
+- **Questions before design**: open points that need a user answer before design proceeds
+
+Ask the user to choose one:
+- **Proceed to design with this scope** — continue to Step 4
+- **Correct the scope and re-run** — return to Step 1 with the corrected scope; when the user names the corrected files or modules, use those directly as the Step 1 seed
+- **Hold additional hearing, then proceed** — gather the missing answers, then continue to Step 4
+
+After the user confirms the scope, count the confirmed target files and set the scale from the Scale Determination table. This confirmed scale supersedes the Step 2 provisional value.
+
+**[STOP]**: Wait for the user's choice before proceeding.
+
+### Step 4: Design Document Creation
+1. **technical-designer** → create the design documentation. Pass the user requirements (verbatim), the codebase-analyzer JSON, and the confirmed scope. Per documentation-criteria this is a Design Doc, preceded by a prerequisite ADR when the design involves an architecture decision. Present at least two design alternatives with trade-offs for each.
+2. **code-verifier** → Verify the Design Doc against existing code.
+3. **document-reviewer** → Quality check of each document technical-designer produced. For the Design Doc: `doc_type: DesignDoc`, pass `codebase_analysis` (the codebase-analyzer JSON) and the code-verifier results. For the ADR (when one was created): `doc_type: ADR`, pass `codebase_analysis`; code-verifier results apply to the Design Doc only. When the ADR review requires changes, technical-designer(update) revises the ADR **and** re-aligns the Design Doc with the corrected ADR — the Design Doc must not stand on an unreviewed or superseded ADR. When this re-alignment changes the Design Doc, re-run code-verifier and the Design Doc document-reviewer on the updated Design Doc so its verification reflects the final content.
+4. **design-sync** → Design Doc consistency verification.
    - IF conflicts found → Report to user → Wait for fix instructions → Fix with technical-designer(update)
-   - IF no conflicts → End
+   - IF no conflicts → proceed
+5. User approval — present the Design Doc together with the design-sync results, and WAIT for approval.
 
 ## Completion Criteria
 
-- [ ] Executed requirement-analyzer and determined scale
-- [ ] Executed codebase-analyzer and passed results to technical-designer
-- [ ] Created appropriate design document (ADR or Design Doc) with technical-designer
-- [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only)
-- [ ] Executed document-reviewer and addressed feedback
+- [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none)
+- [ ] Executed codebase-analyzer with a populated `requirement_analysis`
+- [ ] Confirmed the design scope with the user and set the scale from the confirmed target files
+- [ ] Created the Design Doc with technical-designer, preceded by a prerequisite ADR when the design involved an architecture decision
+- [ ] Executed code-verifier on the Design Doc and passed results to document-reviewer
+- [ ] Executed document-reviewer on each produced document (Design Doc, and ADR when created) and addressed feedback
 - [ ] Executed design-sync for consistency verification
-- [ ] Obtained user approval for design document
+- [ ] Obtained user approval for the design document
 
 ## Output Example
 Design phase completed.
 - Design document: docs/design/[document-name].md
 - Consistency: No conflicts with other Design Docs (or fixes completed)
 
-**Responsibility Boundary**: This command ends with design approval + consistency verification. Work planning and beyond are outside scope.
+**Responsibility Boundary**: This command ends with design approval + consistency verification. Work planning and beyond are outside scope.

package/.claude/commands-en/front-build.md

@@ -160,10 +160,12 @@ Before the completion report, delete the implementation task files this recipe c
 
 If task files cannot be deleted (filesystem error), report the failure but do not block the completion report.
 
-## Output Example
-Frontend implementation phase completed.
-- Task decomposition: Generated under docs/plans/tasks/
-- Implemented tasks: [number] tasks
-- Quality checks: All passed
-- Commits: [number] commits created
-- Cleanup: Task files removed from docs/plans/tasks/
+## Completion Report Contract
+
+Final report must include:
+- Task decomposition status
+- Implemented task count
+- Quality check result
+- Commit count
+- Cleanup result
+- Escalation or blocking summary, if any

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

@@ -1,5 +1,5 @@
 ---
-description: Execute from requirement analysis to frontend design document creation
+description: Execute from codebase analysis to frontend design document creation
 ---
 
 **Command Context**: This command is dedicated to the frontend design phase.
@@ -9,35 +9,42 @@ description: Execute from requirement analysis to frontend design document creat
 **Core Identity**: "I am an orchestrator." (see subagents-orchestration-guide skill)
 
 **Execution Protocol**:
-1. **Delegate all work** to sub-agents — your role is to invoke sub-agents, pass data between them, and report results
-2. **Follow the frontend design flow below** (this command covers medium/large frontend; UI Spec is created before codebase analysis so that component structure informs the technical design):
-   - Execute: requirement-analyzer → ui-spec-designer → codebase-analyzer → technical-designer-frontend → code-verifier → document-reviewer → design-sync
+1. **Delegate all work** to sub-agents — your role is to invoke sub-agents, pass data between them, and report results. The one exception is the Step 1 scope bootstrap, a recipe-local orchestrator task limited to locating seed files.
+2. **Run the frontend design flow below in order** (this command covers medium/large frontend) — a fixed linear sequence, no branches:
+   - Execute: scope bootstrap → codebase-analyzer → [Stop: Scope confirmation] → ui-analyzer → ui-spec-designer → technical-designer-frontend → code-verifier → document-reviewer → design-sync
+   - technical-designer-frontend creates a prerequisite ADR when the design involves an architecture decision (per documentation-criteria); the ADR never replaces the Design Doc — the flow always continues through Design Doc creation and the full verification chain
    - **Stop at every `[Stop: ...]` marker** → Wait for user approval before proceeding
 3. **Scope**: Complete when design documents receive approval
 
-**CRITICAL**: Execute document-reviewer, design-sync, and all stopping points defined in subagents-orchestration-guide skill flows — each serves as a quality gate. Skipping any step risks undetected inconsistencies.
+**subagents-orchestration-guide usage**: Reference the guide for orchestration principles and the Scale Determination table. This command defines its own start order; the guide's requirement-analyzer-origin flow does not apply here.
+
+**CRITICAL**: Execute document-reviewer, design-sync (for Design Docs), and all stopping points — each serves as a quality gate. Skipping any step risks undetected inconsistencies.
 
 ## Workflow Overview
 
 ```
-Requirements → requirement-analyzer → [Stop: Scale determination]
-                                           ↓
-                                   ui-spec-designer → [Stop: UI Spec approval]
-                                           ↓
-                                   codebase-analyzer → technical-designer-frontend
-                                           ↓
-                                   code-verifier → document-reviewer
-                                           ↓
-                                      design-sync → [Stop: Design approval]
+Requirements → scope bootstrap → codebase-analyzer → [Stop: Scope confirmation]
+                                                            ↓
+                                                       ui-analyzer
+                                                            ↓
+                                              ui-spec-designer → [Stop: UI Spec approval]
+                                                            ↓
+                                              technical-designer-frontend
+                                                            ↓
+                                              code-verifier → document-reviewer
+                                                            ↓
+                                                 design-sync → [Stop: Design approval]
 ```
 
 ## Scope Boundaries
 
 **Included in this command**:
-- Requirement analysis with requirement-analyzer
-- Codebase analysis with codebase-analyzer (before technical design)
+- Scope bootstrap: locating seed files so codebase-analyzer receives a populated input
+- Codebase analysis with codebase-analyzer (entry point of the frontend design phase)
+- Scope confirmation with the user, grounded in codebase-analyzer findings
+- UI fact gathering with ui-analyzer
 - UI Specification creation with ui-spec-designer (prototype code inquiry included)
-- ADR creation (if architecture changes, new technology, or data flow changes)
+- ADR creation as a prerequisite to the Design Doc, when architecture changes, new technology, or data flow changes are involved
 - Design Doc creation with technical-designer-frontend
 - Design Doc verification with code-verifier (before document review)
 - Document review with document-reviewer
@@ -45,26 +52,53 @@ Requirements → requirement-analyzer → [Stop: Scale determination]
 
 **Responsibility Boundary**: This command completes with frontend design document (UI Spec/ADR/Design Doc) approval. Work planning and beyond are outside scope.
 
+## Execution Flow
+
 Requirements: $ARGUMENTS
 
-## Execution Flow
+### Step 1: Scope Bootstrap
+codebase-analyzer requires a populated `requirement_analysis.affectedFiles`. Build that seed with a lightweight, orchestrator-local pass — locating files only, with no deep reading and no design decisions:
+
+1. Extract candidate keywords from the user requirements (feature names, domain nouns, identifiers).
+2. Search the repository with Bash (`rg`, or `grep` when `rg` is unavailable) for files matching those keywords.
+3. Collect the matched file paths as the seed `affectedFiles`.
+4. **When the search returns no files**: ask the user which files or modules the design targets (AskUserQuestion), and use that answer as `affectedFiles`. If the user confirms no related code exists, report that codebase-grounded design does not apply and confirm with the user how to proceed.
+5. **When the search returns more than ~20 files**: the keywords are too broad. Present the most relevant candidates to the user (AskUserQuestion) and confirm the seed `affectedFiles` before proceeding.
+
+This step locates seed files only. Reading files in full, tracing dependencies, and analysis remain codebase-analyzer's responsibility.
+
+### Step 2: Codebase Analysis
+- Invoke **codebase-analyzer** using Agent tool
+  - `subagent_type: "codebase-analyzer"`, `description: "Codebase analysis"`
+  - `prompt`: include `requirements` (the user requirements verbatim) and `requirement_analysis` — a JSON object with `affectedFiles` (Step 1 seed), `purpose` (the user requirements), `scale` (provisional value from the Scale Determination table applied to the seed file count), `technicalConsiderations` (`{ constraints: [], risks: [], dependencies: [] }`). Analyze the existing codebase for frontend design guidance.
+
+### Step 3: Scope Confirmation
+After codebase-analyzer returns, confirm the design scope with the user before any design work. Use AskUserQuestion.
+
+Present, sourced from the codebase-analyzer JSON:
+- **Target files/modules**: `analysisScope.filesAnalyzed` and the modules they belong to
+- **Affected layers**: layers touched, derived from `analysisScope.categoriesDetected` and `focusAreas`
+- **Unknowns/assumptions**: `limitations` plus any assumptions codebase-analyzer recorded
+- **Questions before design**: open points that need a user answer before design proceeds
+
+Ask the user to choose one:
+- **Proceed to design with this scope** — continue to Step 4
+- **Correct the scope and re-run** — return to Step 1 with the corrected scope; when the user names the corrected files or modules, use those directly as the Step 1 seed
+- **Hold additional hearing, then proceed** — gather the missing answers, then continue to Step 4
 
-### Step 1: Requirement Analysis Phase
-Considering the deep impact on design, first engage in dialogue to understand the background and purpose of requirements:
-- What problems do you want to solve?
-- Expected outcomes and success criteria
-- Relationship with existing systems
+After the user confirms the scope, count the confirmed target files and set the scale from the Scale Determination table. This confirmed scale supersedes the Step 2 provisional value.
 
-Once the user has answered the three dialogue questions above, execute the process below within design scope. Follow subagents-orchestration-guide Call Examples for codebase-analyzer and code-verifier invocations.
+**[STOP]**: Wait for the user's choice before proceeding.
 
-- Invoke **requirement-analyzer** using Agent tool
-  - `subagent_type: "requirement-analyzer"`
-  - `description: "Requirement analysis"`
-  - `prompt: "Requirements: [user requirements] Execute requirement analysis and scale determination"`
-- **[STOP]**: Review requirement analysis results and address question items
+### Step 4: UI Fact Gathering
+- Invoke **ui-analyzer** using Agent tool
+  - `subagent_type: "ui-analyzer"`, `description: "UI fact gathering"`
+  - `prompt`: include `requirements` (the user requirements) and `requirement_analysis` — a JSON object with `affectedFiles` (the union of `analysisScope.filesAnalyzed`, `analysisScope.tracedDependencies`, and the `focusAreas[].relatedFiles` paths from the Step 2 codebase-analyzer output), `purpose` (the user requirements), `scale` (the Step 3 confirmed scale), `technicalConsiderations` (`{ constraints: [], risks: [], dependencies: [] }`). ui-analyzer reads the project-context External Resources section, fetches external UI sources via the declared access methods, and analyzes the existing UI codebase.
 
-### Step 2: UI Specification Phase
-After requirement analysis approval, ask the user about prototype code:
+The codebase-analyzer JSON (Step 2) and the ui-analyzer JSON (Step 4) are reused by ui-spec-designer and technical-designer-frontend.
+
+### Step 5: UI Specification Phase
+Ask the user about prototype code.
 
 **Ask the user**: "Do you have prototype code for this feature? If so, please provide the path to the code. The prototype will be placed in `docs/ui-spec/assets/` as reference material for the UI Spec."
 
@@ -72,44 +106,39 @@ After requirement analysis approval, ask the user about prototype code:
 
 Then create the UI Specification:
 - Invoke **ui-spec-designer** using Agent tool
-  - `subagent_type: "ui-spec-designer"`
-  - `description: "UI Spec creation"`
-  - If PRD exists and prototype provided: `prompt: "Create UI Spec from PRD at [path]. Prototype code is at [user-provided path]. Place prototype in docs/ui-spec/assets/{feature-name}/"`
-  - If PRD exists and no prototype: `prompt: "Create UI Spec from PRD at [path]. No prototype code available."`
-  - If no PRD (medium scale): `prompt: "Create UI Spec based on the following requirements: [pass requirement-analyzer output]. No PRD available."` (add prototype path if provided)
+  - `subagent_type: "ui-spec-designer"`, `description: "UI Spec creation"`
+  - Build the prompt by including: the source (an existing PRD in `docs/prd/` when one exists for this feature; otherwise the user requirements with the Step 2 codebase-analyzer JSON and the Step 3 confirmed scope), `ui_analysis` (ui-analyzer JSON from Step 4), and the prototype path when provided. Place prototype in `docs/ui-spec/assets/{feature-name}/`.
 - Invoke **document-reviewer** to verify UI Spec
   - `subagent_type: "document-reviewer"`, `description: "UI Spec review"`, `prompt: "doc_type: UISpec target: [ui-spec path] Review for consistency and completeness"`
 - **[STOP]**: Present UI Spec for user approval
 
-### Step 3: Design Document Creation Phase
-First, analyze the existing codebase:
-- Invoke **codebase-analyzer** using Agent tool
-  - `subagent_type: "codebase-analyzer"`, `description: "Codebase analysis"`, `prompt: "requirement_analysis: [JSON from Step 1]. requirements: [user requirements]. Analyze existing codebase for frontend design guidance."`
-
-Create appropriate design documents according to scale determination. technical-designer-frontend presents at least two architecture alternatives (technology selection, data flow design) with trade-offs for each:
-- Invoke **technical-designer-frontend** using Agent tool
-  - For ADR: `subagent_type: "technical-designer-frontend"`, `description: "ADR creation"`, `prompt: "Create ADR for [technical decision]. Present at least two alternatives with trade-offs."`
-  - For Design Doc: `subagent_type: "technical-designer-frontend"`, `description: "Design Doc creation"`, `prompt: "Create Design Doc based on requirements. Codebase analysis: [JSON from codebase-analyzer]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Present at least two architecture alternatives with trade-offs."`
-- **(Design Doc only)** Invoke **code-verifier** to verify Design Doc against existing code. Skip for ADR.
+### Step 6: Design Document Creation Phase
+- Invoke **technical-designer-frontend** using Agent tool to create the design documentation. Per documentation-criteria it produces a Design Doc; when the design involves an architecture decision (architecture change, new technology, or data flow change) it first creates the prerequisite ADR.
+  - `subagent_type: "technical-designer-frontend"`, `description: "Design documentation creation"`, `prompt: "Create the design documentation for this requirement. Per documentation-criteria, produce a Design Doc; when the design involves an architecture decision, first create the prerequisite ADR. Requirements: [user requirements verbatim]. Codebase analysis: [codebase-analyzer JSON from Step 2]. UI analysis: [ui-analyzer JSON from Step 4]. UI Spec is at [ui-spec path]. Inherit component structure and state design from UI Spec. Present at least two architecture alternatives with trade-offs."`
+- Invoke **code-verifier** to verify the Design Doc against existing code.
   - `subagent_type: "code-verifier"`, `description: "Design Doc verification"`, `prompt: "doc_type: design-doc document_path: [Design Doc path] mode: pre-implementation (code_paths omitted — verifier discovers scope from document). Verify Design Doc against existing code."`
-- Invoke **document-reviewer** to verify consistency (pass code-verifier results for Design Doc; omit for ADR)
-  - `subagent_type: "document-reviewer"`, `description: "Document review"`, `prompt: "doc_type: DesignDoc target: [document path] mode: composite code_verification: [JSON from code-verifier] (Design Doc only). Review for consistency and completeness."`
+- Invoke **document-reviewer** for each document technical-designer-frontend produced — the Design Doc, and the ADR when one was created.
+  - Design Doc: `subagent_type: "document-reviewer"`, `description: "Document review"`, `prompt: "doc_type: DesignDoc target: [Design Doc path] mode: composite codebase_analysis: [codebase-analyzer JSON from Step 2] code_verification: [JSON from code-verifier]. Review for consistency and completeness."`
+  - ADR (when created): `subagent_type: "document-reviewer"`, `description: "ADR review"`, `prompt: "doc_type: ADR target: [ADR path] mode: composite. Review for consistency and completeness."`
+- When the ADR review requires changes, technical-designer-frontend(update) revises the ADR and re-aligns the Design Doc with the corrected ADR — the Design Doc must not stand on an unreviewed or superseded ADR. When this re-alignment changes the Design Doc, re-run code-verifier and the Design Doc document-reviewer on the updated Design Doc so its verification reflects the final content.
 
-### Step 4: Design Consistency Verification
-- Invoke **design-sync** using Agent tool
+### Step 7: Design Consistency Verification
+- Invoke **design-sync** using Agent tool.
   - `subagent_type: "design-sync"`, `description: "Design consistency check"`, `prompt: "Check consistency across all Design Docs in docs/design/. Report conflicts and overlaps."`
-- **[STOP]**: Present design documents and design-sync results, obtain user approval
+- **[STOP]**: Present the design document, plus design-sync results for a Design Doc, and obtain user approval
 
 ## Completion Criteria
 
-- [ ] Executed requirement-analyzer and determined scale
-- [ ] Executed codebase-analyzer and passed results to technical-designer-frontend
-- [ ] Created UI Specification with ui-spec-designer (when applicable)
-- [ ] Created appropriate design document (ADR or Design Doc) with technical-designer-frontend
-- [ ] Executed code-verifier on Design Doc and passed results to document-reviewer (skip for ADR-only)
-- [ ] Executed document-reviewer and addressed feedback
+- [ ] Built the Step 1 scope bootstrap seed (or obtained target files from the user when the search returned none)
+- [ ] Executed codebase-analyzer with a populated `requirement_analysis`
+- [ ] Confirmed the design scope with the user and set the scale from the confirmed target files
+- [ ] Executed ui-analyzer; codebase-analyzer (Step 2) and ui-analyzer (Step 4) outputs reused by ui-spec-designer and technical-designer-frontend
+- [ ] Created the UI Specification with ui-spec-designer
+- [ ] Created the Design Doc with technical-designer-frontend, preceded by a prerequisite ADR when the design involved an architecture decision
+- [ ] Executed code-verifier on the Design Doc and passed results to document-reviewer
+- [ ] Executed document-reviewer on each produced document (Design Doc, and ADR when created) and addressed feedback
 - [ ] Executed design-sync for consistency verification
-- [ ] Obtained user approval for design document
+- [ ] Obtained user approval for the design document
 
 ## Output Example
 Frontend design phase completed.

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

@@ -179,13 +179,15 @@ Escalate when the required fix or investigation falls outside that scope.
 
 タスクファイルを削除できない場合（ファイルシステムエラー）、失敗を報告するが完了レポートをブロックしない。
 
-## 出力例
-実装フェーズが完了しました。
-- タスク分解: docs/plans/tasks/ 配下に生成
-- 実装されたタスク: [タスク数]件
-- 品質チェック: すべて通過
-- コミット: [コミット数]件作成
-- クリーンアップ: docs/plans/tasks/ からタスクファイルを削除済み
+## 完了レポートコントラクト
+
+最終レポートには以下を含めること:
+- タスク分解のステータス
+- 実装したタスク数
+- 品質チェック結果
+- コミット数
+- クリーンアップ結果
+- エスカレーションまたはブロッキングの要約（あれば）
 
 **責務境界**:
 - スコープ内: タスク分解から実装完了まで

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

@@ -1,5 +1,5 @@
 ---
-description: 要件分析から設計書作成まで実行
+description: コードベース分析から設計書作成まで実行
 ---
 
 **コマンドコンテキスト**: このコマンドは設計フェーズ専用です。
@@ -9,46 +9,36 @@ description: 要件分析から設計書作成まで実行
 **コアアイデンティティ**: 「私は作業者ではない。オーケストレーターである。」（subagents-orchestration-guideスキル参照）
 
 **実行プロトコル**:
-1. **全作業をAgentツールでサブエージェントに委譲** — サブエージェントの呼び出し、データの受け渡し、結果の報告（許可ツール: subagents-orchestration-guideスキル「オーケストレーターの許可ツール」参照）
-2. **subagents-orchestration-guideスキルの設計フローに厳密に従う**:
-   - 実行: requirement-analyzer → codebase-analyzer → technical-designer → code-verifier → document-reviewer → design-sync
-   - **ADRのみの場合**: codebase-analyzerとcode-verifierはスキップ（Design Docにのみ適用）
+1. **全作業をAgentツールでサブエージェントに委譲** — サブエージェントの呼び出し、データの受け渡し、結果の報告（許可ツール: subagents-orchestration-guideスキル「オーケストレーターの許可ツール」参照）。唯一の例外はStep 1のスコープブートストラップで、シードファイルの特定に限定したレシピ内オーケストレータータスク。
+2. **以下の設計フローを順に実行** — 分岐のない固定の線形シーケンス:
+   - 実行: スコープブートストラップ → codebase-analyzer → [停止: スコープ確認] → technical-designer → code-verifier → document-reviewer → design-sync
+   - technical-designerは、設計にアーキテクチャ決定が伴う場合（documentation-criteriaに従う）に前提となるADRを作成する。ADRはDesign Docを置き換えない — フローは常にDesign Doc作成と検証チェーン全体を通過する
    - **`[停止: ...]`マーカーで必ず停止** → 次に進む前にユーザー承認を待つ
 3. **スコープ**: 設計書が承認されたら完了
 
-**重要**: document-reviewer、design-sync、subagents-orchestration-guideスキルで定義された停止ポイントは必ず実行する。
+**subagents-orchestration-guideの利用**: オーケストレーション原則（Delegation Boundary、Decision precedence、許可ツール）とScale Determination表を参照する。このコマンドは独自の開始順序を定義する — ガイドのrequirement-analyzer起点フローはここでは適用しない。
+
+**重要**: document-reviewer、design-sync（Design Docの場合）、停止ポイントは決してスキップしない — 各々が品質ゲートとして機能する。
 
 ## ワークフロー概要
 
 ```
-要件 → requirement-analyzer → [停止: 規模判定]
-                                    ↓
-                            codebase-analyzer → technical-designer
-                                    ↓
-                            code-verifier → document-reviewer
-                                    ↓
-                               design-sync → [停止: 設計承認]
+要件 → スコープブートストラップ → codebase-analyzer → [停止: スコープ確認]
+                                                            ↓
+                                                    technical-designer
+                                                            ↓
+                                                    code-verifier → document-reviewer
+                                                            ↓
+                                                       design-sync → [停止: 設計承認]
 ```
 
-要件: $ARGUMENTS
-
-設計への影響を深く考慮し、まず要件の背景と目的を理解するため対話を行い:
-- どのような問題を解決したいか
-- 期待される成果と成功基準
-- 既存システムとの関係性
-
-適度に要件が明確になったら、requirement-analyzerで分析し、規模に応じた適切な設計書を作成します。
-
-設計の代替案とトレードオフを明確に提示します。
-
-subagents-orchestration-guideのCall Examplesに従い、codebase-analyzerとcode-verifierを呼び出す。
-
 ## スコープ境界
 
 **実行内容**:
-- requirement-analyzerによる要件分析
-- codebase-analyzerによるコードベース分析（技術設計の前に実施）
-- ADR作成（アーキテクチャ変更、新技術、データフロー変更がある場合）
+- スコープブートストラップ: codebase-analyzerが値の入った入力を得られるようシードファイルを特定する
+- codebase-analyzerによるコードベース分析（設計フェーズの入口）
+- codebase-analyzerの所見に基づくユーザーとのスコープ確認
+- ADR作成（アーキテクチャ変更、新技術、データフロー変更が伴う場合、Design Docの前提として）
 - technical-designerによるDesign Doc作成
 - code-verifierによるDesign Doc検証（ドキュメントレビューの前に実施）
 - document-reviewerによるドキュメントレビュー
@@ -58,25 +48,61 @@ subagents-orchestration-guideのCall Examplesに従い、codebase-analyzerとcod
 
 ## 実行フロー
 
-1. requirement-analyzer → 要件分析
-2. codebase-analyzer → コードベース分析（要件分析結果を入力）
-3. technical-designer → Design Doc作成（codebase-analyzer出力を入力）
-4. code-verifier → Design Docを既存コードに対して検証
-5. document-reviewer → 単一ドキュメント品質チェック（code-verifier結果を入力）
-6. ユーザー承認（承認を待つ）
-7. design-sync → 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 3: スコープ確認
+codebase-analyzerが返ったら、設計作業の前にユーザーとスコープを確認する。AskUserQuestionを使う。
+
+codebase-analyzerのJSONを出典として以下を提示する:
+- **対象ファイル/モジュール**: `analysisScope.filesAnalyzed`と、それらが属するモジュール
+- **影響を受けるレイヤー**: `analysisScope.categoriesDetected`と`focusAreas`から導出される、影響を受けるレイヤー
+- **不明点/前提**: `limitations`と、codebase-analyzerが記録した前提
+- **設計前の質問事項**: 設計を進める前にユーザーの回答が必要な未解決点
+
+ユーザーに以下から1つを選んでもらう:
+- **このスコープで設計を進める** — Step 4へ進む
+- **スコープを修正して再実行** — 修正したスコープでStep 1に戻る。ユーザーが修正後のファイルまたはモジュールを指定した場合は、検索で導出し直さず、それをStep 1のシードとして直接使う
+- **追加ヒアリングののち進める** — 不足している回答を集めてからStep 4へ進む
+
+ユーザーがスコープを確認したら、確認済みの対象ファイル数を数え、Scale Determination表から規模を設定する。この確認済みの規模はStep 2の暫定値に優先する。
+
+**[停止]**: ユーザーの選択を待ってから進む。
+
+### Step 4: 設計書作成
+1. **technical-designer** → 設計書を作成する。ユーザー要件（原文）、codebase-analyzerのJSON、確認済みスコープを渡す。documentation-criteriaに従い、これはDesign Docであり、設計にアーキテクチャ決定が伴う場合は前提となるADRを先に作成する。少なくとも2つの設計選択肢をトレードオフとともに提示する。
+2. **code-verifier** → Design Docを既存コードに対して検証する。
+3. **document-reviewer** → technical-designerが作成した各ドキュメントの品質チェック。Design Docの場合: `doc_type: DesignDoc`、`codebase_analysis`（codebase-analyzerのJSON）とcode-verifier結果を渡す。ADR（作成された場合）の場合: `doc_type: ADR`、`codebase_analysis`を渡す。code-verifier結果はDesign Docにのみ適用する。ADRレビューで修正が必要になった場合、technical-designer(update)がADRを修正し、**かつ**修正後のADRに合わせてDesign Docを再整合させる — Design Docは未レビューまたは古いADRの上に立ってはならない。この再整合でDesign Docが変わった場合は、更新後のDesign Docに対してcode-verifierとDesign Docのdocument-reviewerを再実行し、検証が最終内容を反映するようにする。
+4. **design-sync** → Design Doc間整合性検証。
    - 矛盾あり → ユーザーに報告 → 修正指示待ち → technical-designer(update)で修正
-   - 矛盾なし → 終了
+   - 矛盾なし → 次へ進む
+5. ユーザー承認 — Design Doc を design-sync の結果とともに提示し、承認を待つ。
 
 ## 完了条件
 
-- [ ] requirement-analyzerを実行し規模を判定した
-- [ ] codebase-analyzerを実行し結果をtechnical-designerに渡した
-- [ ] technical-designerで適切な設計書（ADRまたはDesign Doc）を作成した
-- [ ] code-verifierでDesign Docを検証し結果をdocument-reviewerに渡した（ADRのみの場合はスキップ）
-- [ ] document-reviewerを実行しフィードバックに対応した
+- [ ] Step 1のスコープブートストラップのシードを構築した（または検索結果が0件のときユーザーから対象ファイルを取得した）
+- [ ] 値の入った`requirement_analysis`でcodebase-analyzerを実行した
+- [ ] ユーザーと設計スコープを確認し、確認済みの対象ファイルから規模を設定した
+- [ ] technical-designerでDesign Docを作成した。設計にアーキテクチャ決定が伴う場合は前提となるADRを先に作成した
+- [ ] Design Docに対してcode-verifierを実行し、結果をdocument-reviewerに渡した
+- [ ] 作成した各ドキュメント（Design Doc、および作成された場合のADR）に対してdocument-reviewerを実行し、フィードバックに対応した
 - [ ] design-syncで整合性検証を実行した
-- [ ] ユーザーから設計書の承認を取得した
+- [ ] 設計書のユーザー承認を取得した
 
 ## 出力例
 設計フェーズが完了しました。

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

@@ -160,10 +160,12 @@ Escalate when the required fix or investigation falls outside that scope.
 
 タスクファイルを削除できない場合（ファイルシステムエラー）、失敗を報告するが完了レポートをブロックしない。
 
-## 出力例
-フロントエンド実装フェーズ完了。
-- タスク分解: docs/plans/tasks/ 配下に生成
-- 実装タスク: [件数] タスク
-- 品質チェック: 全てパス
-- コミット: [件数] コミット作成
-- クリーンアップ: docs/plans/tasks/ からタスクファイルを削除済み
+## 完了レポートコントラクト
+
+最終レポートには以下を含めること:
+- タスク分解のステータス
+- 実装したタスク数
+- 品質チェック結果
+- コミット数
+- クリーンアップ結果
+- エスカレーションまたはブロッキングの要約（あれば）