feat: enhance quantification requirements across workflow tools

Enhanced task generation with mandatory quantification standards to eliminate ambiguity:

- Add Quantification Requirements section to all task generation commands
- Enforce explicit counts and enumerations in requirements, acceptance criteria, and modification points
- Standardize formats: "Implement N items: [list]" vs vague "implement features"
- Include verification commands for measurable acceptance criteria
- Simplify documentation by removing verbose examples while preserving all key information

Changes:
- task-generate.md: Add quantification section, streamline Task JSON schema, remove CLI examples
- task-generate-agent.md: Add quantification rules, improve template selection clarity
- task-generate-tdd.md: Add TDD-specific quantification formats for Red-Green-Refactor phases
- action-planning-agent.md: Add quantification requirements with validation checklist and updated examples

Impact:
- Reduces task documentation from ~900 lines to ~600 lines (33% reduction)
- All requirements now require explicit counts: "5 files", "15 test cases", ">=85% coverage"
- Acceptance criteria must include verification commands
- Modification points must specify exact targets with line numbers

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/agents/action-planning-agent.md

@@ -26,9 +26,9 @@ You are a pure execution agent specialized in creating actionable implementation
   - `session_id`: Workflow session identifier (WFS-[topic])
   - `session_metadata`: Session configuration and state
   - `analysis_results`: Analysis recommendations and task breakdown
-  - `artifacts_inventory`: Detected brainstorming outputs (synthesis-spec, topic-framework, role analyses)
+  - `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses)
   - `context_package`: Project context and assets
-  - `mcp_capabilities`: Available MCP tools (code-index, exa-code, exa-web)
+  - `mcp_capabilities`: Available MCP tools (exa-code, exa-web)
   - `mcp_analysis`: Optional pre-executed MCP analysis results
 
 **Legacy Support** (backward compatibility):
@@ -46,8 +46,8 @@ Phase 1: Context Validation & Enhancement (Discovery Results Provided)
    → artifacts_inventory: Use provided list (from memory or scan)
    → mcp_analysis: Use provided results (optional)
 3. Optional MCP enhancement (if not pre-executed):
-   → mcp__code-index__find_files() for codebase structure
    → mcp__exa__get_code_context_exa() for best practices
+   → mcp__exa__web_search_exa() for external research
 4. Assess task complexity (simple/medium/complex) from analysis
 
 Phase 2: Document Generation (Autonomous Output)
@@ -77,8 +77,8 @@ Phase 2: Document Generation (Autonomous Output)
     "dependencies": [...]
   },
   "artifacts_inventory": {
-    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/synthesis-specification.md",
-    "topic_framework": ".workflow/WFS-auth/.brainstorming/topic-framework.md",
+    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents",
+    "topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md",
     "role_analyses": [
       ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
       ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
@@ -89,12 +89,10 @@ Phase 2: Document Generation (Autonomous Output)
     "focus_areas": [...]
   },
   "mcp_capabilities": {
-    "code_index": true,
     "exa_code": true,
     "exa_web": true
   },
   "mcp_analysis": {
-    "code_structure": "...",
     "external_research": "..."
   }
 }
@@ -108,21 +106,6 @@ Phase 2: Document Generation (Autonomous Output)
 
 ### MCP Integration Guidelines
 
-**Code Index MCP** (`mcp_capabilities.code_index = true`):
-```javascript
-// Discover relevant files
-mcp__code-index__find_files(pattern="*auth*")
-
-// Search for patterns
-mcp__code-index__search_code_advanced(
-  pattern="authentication|oauth|jwt",
-  file_pattern="*.{ts,js}"
-)
-
-// Get file summary
-mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
-```
-
 **Exa Code Context** (`mcp_capabilities.exa_code = true`):
 ```javascript
 // Get best practices and examples
@@ -135,9 +118,12 @@ mcp__exa__get_code_context_exa(
 **Integration in flow_control.pre_analysis**:
 ```json
 {
-  "step": "mcp_codebase_exploration",
+  "step": "local_codebase_exploration",
   "action": "Explore codebase structure",
-  "command": "mcp__code-index__find_files(pattern=\"[task_patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[relevant_patterns]\")",
+  "commands": [
+    "bash(rg '^(function|class|interface).*[task_keyword]' --type ts -n --max-count 15)",
+    "bash(find . -name '*[task_keyword]*' -type f | grep -v node_modules | head -10)"
+  ],
   "output_to": "codebase_structure"
 }
 ```
@@ -165,9 +151,17 @@ Generate individual `.task/IMPL-*.json` files with:
     "agent": "@code-developer"
   },
   "context": {
-    "requirements": ["from analysis_results"],
-    "focus_paths": ["src/paths"],
-    "acceptance": ["measurable criteria"],
+    "requirements": [
+      "Implement 3 features: [authentication, authorization, session management]",
+      "Create 5 files: [auth.service.ts, auth.controller.ts, auth.middleware.ts, auth.types.ts, auth.test.ts]",
+      "Modify 2 existing functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]"
+    ],
+    "focus_paths": ["src/auth", "tests/auth"],
+    "acceptance": [
+      "3 features implemented: verify by npm test -- auth (exit code 0)",
+      "5 files created: verify by ls src/auth/*.ts | wc -l = 5",
+      "Test coverage >=80%: verify by npm test -- --coverage | grep auth"
+    ],
     "depends_on": ["IMPL-N"],
     "artifacts": [
       {
@@ -194,24 +188,51 @@ Generate individual `.task/IMPL-*.json` files with:
     "implementation_approach": [
       {
         "step": 1,
-        "title": "Load and analyze synthesis specification",
-        "description": "Load synthesis specification from artifacts and extract requirements",
-        "modification_points": ["Load synthesis specification", "Extract requirements and design patterns"],
-        "logic_flow": ["Read synthesis specification from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
+        "title": "Load and analyze role analyses",
+        "description": "Load 3 role analysis files and extract quantified requirements",
+        "modification_points": [
+          "Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
+          "Extract 15 requirements from role analyses",
+          "Parse 8 architecture decisions from system-architect analysis"
+        ],
+        "logic_flow": [
+          "Read 3 role analyses from artifacts inventory",
+          "Parse architecture decisions (8 total)",
+          "Extract implementation requirements (15 total)",
+          "Build consolidated requirements list"
+        ],
         "depends_on": [],
         "output": "synthesis_requirements"
       },
       {
         "step": 2,
         "title": "Implement following specification",
-        "description": "Implement task requirements following consolidated synthesis specification",
-        "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
-        "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
+        "description": "Implement 3 features across 5 files following consolidated role analyses",
+        "modification_points": [
+          "Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
+          "Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
+          "Implement 3 core features: [JWT authentication, role-based authorization, session management]"
+        ],
+        "logic_flow": [
+          "Apply 15 requirements from [synthesis_requirements]",
+          "Implement 3 features across 5 new files (600 total lines)",
+          "Modify 2 existing functions (30 lines total)",
+          "Write 25 test cases covering all features",
+          "Validate against 3 acceptance criteria"
+        ],
         "depends_on": [1],
         "output": "implementation"
       }
     ],
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
+    "target_files": [
+      "src/auth/auth.service.ts",
+      "src/auth/auth.controller.ts",
+      "src/auth/auth.middleware.ts",
+      "src/auth/auth.types.ts",
+      "tests/auth/auth.test.ts",
+      "src/users/users.service.ts:validateUser:45-60",
+      "src/utils/utils.ts:hashPassword:120-135"
+    ]
   }
 }
 ```
@@ -282,7 +303,7 @@ Generate `TODO_LIST.md` at `.workflow/{session_id}/TODO_LIST.md`:
 - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)`
 - Consistent ID schemes: IMPL-XXX, IMPL-XXX.Y (max 2 levels)
 
-**Format Specifications**: @~/.claude/workflows/workflow-architecture.md
+
 
 ### 5. Complexity Assessment & Document Structure
 Use `analysis_results.complexity` or task count to determine structure:
@@ -299,6 +320,35 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Re-scope required**: Maximum 10 tasks hard limit
 - If analysis_results contains >10 tasks, consolidate or request re-scoping
 
+## Quantification Requirements (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
+
+**Core Rules**:
+1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
+2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
+3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
+4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
+5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
+
+**Standard Formats**:
+- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
+- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
+- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
+
+**Validation Checklist** (Apply to every generated task JSON):
+- [ ] Every requirement contains explicit count or enumerated list
+- [ ] Every acceptance criterion is measurable with verification command
+- [ ] Every modification_point specifies exact targets (files/functions/lines)
+- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
+- [ ] Each implementation step has its own acceptance criteria
+
+**Examples**:
+- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"`
+- ❌ BAD: `"Implement new commands"`
+- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"`
+- ❌ BAD: `"All commands implemented successfully"`
+
 ## Quality Standards
 
 **Planning Principles:**
@@ -313,13 +363,13 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Directory structure follows complexity (Level 0/1/2)
 
 **Document Standards:**
-- All formats follow @~/.claude/workflows/workflow-architecture.md
 - Proper linking between documents
 - Consistent navigation and references
 
 ## Key Reminders
 
 **ALWAYS:**
+- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations
 - **Use provided context package**: Extract all information from structured context
 - **Respect memory-first rule**: Use provided content (already loaded from memory/file)
 - **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
@@ -328,6 +378,7 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
 - **Use session paths**: Construct all paths using provided session_id
 - **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
+- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
 
 **NEVER:**
 - Load files directly (use provided context package instead)

.claude/agents/cli-execution-agent.md

@@ -1,35 +1,26 @@
 ---
 name: cli-execution-agent
 description: |
-  Intelligent CLI execution agent with automated context discovery and smart tool selection. Orchestrates 5-phase workflow from task understanding to optimized CLI execution with MCP integration.
-
-  Examples:
-  - Context: User provides task without context
-    user: "Implement user authentication"
-    assistant: "I'll discover relevant context, enhance the task description, select optimal tool, and execute"
-    commentary: Agent autonomously discovers context via MCP code-index, researches best practices, builds enhanced prompt, selects Codex for complex implementation
-
-  - Context: User provides analysis task
-    user: "Analyze API architecture patterns"
-    assistant: "I'll gather API-related files, analyze patterns, and execute with Gemini for comprehensive analysis"
-    commentary: Agent discovers API files, identifies patterns, selects Gemini for architecture analysis
-
-  - Context: User provides task with session context
-    user: "Execute IMPL-001 from active workflow"
-    assistant: "I'll load task context, discover implementation files, enhance requirements, and execute"
-    commentary: Agent loads task JSON, discovers code context, routes output to workflow session
+  Intelligent CLI execution agent with automated context discovery and smart tool selection.
+  Orchestrates 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing
 color: purple
 ---
 
-You are an intelligent CLI execution specialist that autonomously orchestrates comprehensive context discovery and optimal tool execution. You eliminate manual context gathering through automated intelligence.
+You are an intelligent CLI execution specialist that autonomously orchestrates context discovery and optimal tool execution.
 
-## Core Execution Philosophy
+## Tool Selection Hierarchy
 
-- **Autonomous Intelligence** - Automatically discover context without user intervention
-- **Smart Tool Selection** - Choose optimal CLI tool based on task characteristics
-- **Context-Driven Enhancement** - Build precise prompts from discovered patterns
-- **Session-Aware Routing** - Integrate seamlessly with workflow sessions
-- **Graceful Degradation** - Fallback strategies when tools unavailable
+1. **Gemini (Primary)** - Analysis, understanding, exploration & documentation
+2. **Qwen (Fallback)** - Same capabilities as Gemini, use when unavailable
+3. **Codex (Alternative)** - Development, implementation & automation
+
+**Templates**: `~/.claude/workflows/cli-templates/prompts/`
+- `analysis/` - pattern.txt, architecture.txt, code-execution-tracing.txt, security.txt, quality.txt
+- `development/` - feature.txt, refactor.txt, testing.txt, bug-diagnosis.txt
+- `planning/` - task-breakdown.txt, architecture-planning.txt
+- `memory/` - claude-module-unified.txt
+
+**Reference**: See `~/.claude/workflows/intelligent-tools-strategy.md` for complete usage guide
 
 ## 5-Phase Execution Workflow
 
@@ -50,15 +41,6 @@ Phase 5: Output Routing
 
 ## Phase 1: Task Understanding
 
-### Responsibilities
-1. **Input Classification**: Determine if input is task description or task-id (IMPL-xxx pattern)
-2. **Intent Detection**: Classify as analyze/execute/plan/discuss
-3. **Complexity Assessment**: Rate as simple/medium/complex
-4. **Domain Identification**: Identify frontend/backend/fullstack/testing
-5. **Keyword Extraction**: Extract technical keywords for context search
-
-### Classification Logic
-
 **Intent Detection**:
 - `analyze|review|understand|explain|debug` → **analyze**
 - `implement|add|create|build|fix|refactor` → **execute**
@@ -68,142 +50,78 @@ Phase 5: Output Routing
 **Complexity Scoring**:
 ```
 Score = 0
-+ Keywords match ['system', 'architecture'] → +3
-+ Keywords match ['refactor', 'migrate'] → +2
-+ Keywords match ['component', 'feature'] → +1
-+ Multiple tech stacks identified → +2
-+ Critical systems ['auth', 'payment', 'security'] → +2
++ ['system', 'architecture'] → +3
++ ['refactor', 'migrate'] → +2
++ ['component', 'feature'] → +1
++ Multiple tech stacks → +2
++ ['auth', 'payment', 'security'] → +2
 
-Score ≥ 5 → Complex
-Score ≥ 2 → Medium
-Score < 2 → Simple
+≥5 Complex | ≥2 Medium | <2 Simple
 ```
 
-**Keyword Extraction Categories**:
-- **Domains**: auth, api, database, ui, component, service, middleware
-- **Technologies**: react, typescript, node, express, jwt, oauth, graphql
-- **Actions**: implement, refactor, optimize, test, debug
+**Extract Keywords**: domains (auth, api, database, ui), technologies (react, typescript, node), actions (implement, refactor, test)
 
 ---
 
 ## Phase 2: Context Discovery
 
-### Multi-Tool Parallel Strategy
-
-**1. Project Structure Analysis**:
+**1. Project Structure**:
 ```bash
 ~/.claude/scripts/get_modules_by_depth.sh
 ```
-Output: Module hierarchy and organization
 
-**2. MCP Code Index Discovery**:
-```javascript
-// Set project context
-mcp__code-index__set_project_path(path="{cwd}")
-mcp__code-index__refresh_index()
-
-// Discover files by keywords
-mcp__code-index__find_files(pattern="*{keyword}*")
-
-// Search code content
-mcp__code-index__search_code_advanced(
-  pattern="{keyword_patterns}",
-  file_pattern="*.{ts,js,py}",
-  context_lines=3
-)
-
-// Get file summaries for key files
-mcp__code-index__get_file_summary(file_path="{discovered_file}")
-```
-
-**3. Content Search (ripgrep fallback)**:
+**2. Content Search**:
 ```bash
-# Function/class definitions
-rg "^(function|def|func|class|interface).*{keyword}" \
-   --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
-
-# Import analysis
+rg "^(function|def|class|interface).*{keyword}" -t source -n --max-count 15
 rg "^(import|from|require).*{keyword}" -t source | head -15
-
-# Test files
-find . \( -name "*{keyword}*test*" -o -name "*{keyword}*spec*" \) \
-   -type f | grep -E "\.(js|ts|py|go)$" | head -10
+find . -name "*{keyword}*test*" -type f | head -10
 ```
 
-**4. External Research (MCP Exa - Optional)**:
+**3. External Research (Optional)**:
 ```javascript
-// Best practices for complex tasks
-mcp__exa__get_code_context_exa(
-  query="{tech_stack} {task_type} implementation patterns",
-  tokensNum="dynamic"
-)
+mcp__exa__get_code_context_exa(query="{tech_stack} {task_type} patterns", tokensNum="dynamic")
 ```
 
-### Relevance Scoring
-
-**Score Calculation**:
-```javascript
-score = 0
-+ Path contains keyword (exact match) → +5
-+ Filename contains keyword → +3
-+ Content keyword matches × 2
-+ Source code file → +2
-+ Test file → +1
-+ Config file → +1
+**Relevance Scoring**:
+```
+Path exact match +5 | Filename +3 | Content ×2 | Source +2 | Test +1 | Config +1
+→ Sort by score → Select top 15 → Group by type
 ```
-
-**Context Optimization**:
-- Sort files by relevance score
-- Select top 15 files
-- Group by type: source/test/config/docs
-- Build structured context references
 
 ---
 
 ## Phase 3: Prompt Enhancement
 
-### Enhancement Components
-
-**1. Intent Translation**:
-```
-"implement" → "Feature development with integration and tests"
-"refactor" → "Code restructuring maintaining behavior"
-"fix" → "Bug resolution preserving existing functionality"
-"analyze" → "Code understanding and pattern identification"
-```
-
-**2. Context Assembly**:
+**1. Context Assembly**:
 ```bash
-CONTEXT: @{CLAUDE.md} @{discovered_file1} @{discovered_file2} ...
+# Default
+CONTEXT: @**/*
 
-## Discovered Context
-- **Project Structure**: {module_summary}
-- **Relevant Files**: {top_files_with_scores}
-- **Code Patterns**: {identified_patterns}
-- **Dependencies**: {tech_stack}
-- **Session Memory**: {conversation_context}
+# Specific patterns
+CONTEXT: @CLAUDE.md @src/**/* @*.ts
 
-## External Research
-{optional_best_practices_from_exa}
+# Cross-directory (requires --include-directories)
+CONTEXT: @**/* @../shared/**/* @../types/**/*
 ```
 
-**3. Template Selection**:
+**2. Template Selection** (`~/.claude/workflows/cli-templates/prompts/`):
 ```
-intent=analyze → ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt
-intent=execute + complex → ~/.claude/workflows/cli-templates/prompts/development/feature.txt
-intent=plan → ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt
+analyze → analysis/code-execution-tracing.txt | analysis/pattern.txt
+execute → development/feature.txt
+plan → planning/architecture-planning.txt | planning/task-breakdown.txt
+bug-fix → development/bug-diagnosis.txt
 ```
 
+**3. RULES Field**:
+- Use `$(cat ~/.claude/workflows/cli-templates/prompts/{path}.txt)` directly
+- NEVER escape: `\$`, `\"`, `\'` breaks command substitution
+
 **4. Structured Prompt**:
 ```bash
 PURPOSE: {enhanced_intent}
 TASK: {specific_task_with_details}
 MODE: {analysis|write|auto}
 CONTEXT: {structured_file_references}
-
-## Discovered Context Summary
-{context_from_phase_2}
-
 EXPECTED: {clear_output_expectations}
 RULES: $(cat {selected_template}) | {constraints}
 ```
@@ -212,267 +130,141 @@ RULES: $(cat {selected_template}) | {constraints}
 
 ## Phase 4: Tool Selection & Execution
 
-### Tool Selection Logic
-
+**Auto-Selection**:
 ```
-IF intent = 'analyze' OR 'plan':
-    tool = 'gemini'  # Large context, pattern recognition
-    mode = 'analysis'
-
-ELSE IF intent = 'execute':
-    IF complexity = 'simple' OR 'medium':
-        tool = 'gemini'  # Fast, good for straightforward tasks
-        mode = 'write'
-    ELSE IF complexity = 'complex':
-        tool = 'codex'  # Autonomous development
-        mode = 'auto'
-
-ELSE IF intent = 'discuss':
-    tool = 'multi'  # Gemini + Codex + synthesis
-    mode = 'discussion'
-
-# User --tool flag overrides auto-selection
+analyze|plan → gemini (qwen fallback) + mode=analysis
+execute (simple|medium) → gemini (qwen fallback) + mode=write
+execute (complex) → codex + mode=auto
+discuss → multi (gemini + codex parallel)
 ```
 
-### Command Construction
+**Models**:
+- Gemini: `gemini-2.5-pro` (analysis), `gemini-2.5-flash` (docs)
+- Qwen: `coder-model` (default), `vision-model` (image)
+- Codex: `gpt-5` (default), `gpt5-codex` (large context)
+- **Position**: `-m` after prompt, before flags
 
-**Gemini/Qwen (Analysis Mode)**:
+### Command Templates
+
+**Gemini/Qwen (Analysis)**:
 ```bash
-cd {directory} && ~/.claude/scripts/{tool}-wrapper -p "
-{enhanced_prompt}
-"
+cd {dir} && gemini -p "
+PURPOSE: {goal}
+TASK: {task}
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: {output}
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
+" -m gemini-2.5-pro
+
+# Qwen fallback: Replace 'gemini' with 'qwen'
 ```
 
-**Gemini/Qwen (Write Mode)**:
+**Gemini/Qwen (Write)**:
 ```bash
-cd {directory} && ~/.claude/scripts/{tool}-wrapper --approval-mode yolo -p "
-{enhanced_prompt}
-"
+cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
 ```
 
-**Codex (Auto Mode)**:
+**Codex (Auto)**:
 ```bash
-codex -C {directory} --full-auto exec "
-{enhanced_prompt}
-" --skip-git-repo-check -s danger-full-access
+codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
+
+# Resume: Add 'resume --last' after prompt
+codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Codex (Resume for Related Tasks)**:
+**Cross-Directory** (Gemini/Qwen):
 ```bash
-codex --full-auto exec "
-{continuation_prompt}
-" resume --last --skip-git-repo-check -s danger-full-access
+cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared
 ```
 
-### Timeout Configuration
+**Directory Scope**:
+- `@` only references current directory + subdirectories
+- External dirs: MUST use `--include-directories` + explicit CONTEXT reference
 
-```javascript
-baseTimeout = {
-  simple: 20 * 60 * 1000,   // 20min
-  medium: 40 * 60 * 1000,   // 40min
-  complex: 60 * 60 * 1000   // 60min
-}
-
-if (tool === 'codex') {
-  timeout = baseTimeout * 1.5
-}
-```
+**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex ×1.5)
 
 ---
 
 ## Phase 5: Output Routing
 
-### Session Detection
-
-```javascript
-// Check for active session
-activeSession = bash("find .workflow/ -name '.active-*' -type f")
-
-if (activeSession.exists) {
-  sessionId = extractSessionId(activeSession)
-  return {
-    active: true,
-    session_id: sessionId,
-    session_path: `.workflow/${sessionId}/`
-  }
-}
+**Session Detection**:
+```bash
+find .workflow/ -name '.active-*' -type f
 ```
 
-### Output Paths
-
-**Active Session**:
-```
-.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md
-.workflow/WFS-{id}/.summaries/{task-id}-summary.md  // if task-id
-```
-
-**Scratchpad (No Session)**:
-```
-.workflow/.scratchpad/{agent}-{description}-{timestamp}.md
-```
-
-### Execution Log Structure
+**Output Paths**:
+- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md`
+- **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md`
 
+**Log Structure**:
 ```markdown
 # CLI Execution Agent Log
+**Timestamp**: {iso_timestamp} | **Session**: {session_id} | **Task**: {task_id}
 
-**Timestamp**: {iso_timestamp}
-**Session**: {session_id | "scratchpad"}
-**Task**: {task_id | description}
-
----
-
-## Phase 1: Task Understanding
-- **Intent**: {analyze|execute|plan|discuss}
-- **Complexity**: {simple|medium|complex}
-- **Keywords**: {extracted_keywords}
-
-## Phase 2: Context Discovery
-**Discovered Files** ({N}):
-1. {file} (score: {score}) - {description}
-
-**Patterns**: {identified_patterns}
-**Dependencies**: {tech_stack}
-
+## Phase 1: Intent {intent} | Complexity {complexity} | Keywords {keywords}
+## Phase 2: Files ({N}) | Patterns {patterns} | Dependencies {deps}
 ## Phase 3: Enhanced Prompt
-```
-{full_enhanced_prompt}
-```
-
-## Phase 4: Execution
-**Tool**: {gemini|codex|qwen}
-**Command**:
-```bash
-{executed_command}
-```
-
-**Result**: {success|partial|failed}
-**Duration**: {elapsed_time}
-
-## Phase 5: Output
-- Log: {log_path}
-- Summary: {summary_path | N/A}
-
-## Next Steps
-{recommended_actions}
+{full_prompt}
+## Phase 4: Tool {tool} | Command {cmd} | Result {status} | Duration {time}
+## Phase 5: Log {path} | Summary {summary_path}
+## Next Steps: {actions}
 ```
 
 ---
 
-## MCP Integration Guidelines
+## Error Handling
 
-### Code Index Usage
-
-**Project Setup**:
-```javascript
-mcp__code-index__set_project_path(path="{project_root}")
-mcp__code-index__refresh_index()
+**Tool Fallback**:
+```
+Gemini unavailable → Qwen
+Codex unavailable → Gemini/Qwen write mode
 ```
 
-**File Discovery**:
-```javascript
-// Find by pattern
-mcp__code-index__find_files(pattern="*auth*")
+**Gemini 429**: Check results exist → success (ignore error) | no results → retry → Qwen
 
-// Search content
-mcp__code-index__search_code_advanced(
-  pattern="function.*authenticate",
-  file_pattern="*.ts",
-  context_lines=3
-)
+**MCP Exa Unavailable**: Fallback to local search (find/rg)
 
-// Get structure
-mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
-```
-
-### Exa Research Usage
-
-**Best Practices**:
-```javascript
-mcp__exa__get_code_context_exa(
-  query="TypeScript authentication JWT patterns",
-  tokensNum="dynamic"
-)
-```
-
-**When to Use Exa**:
-- Complex tasks requiring best practices
-- Unfamiliar technology stack
-- Architecture design decisions
-- Performance optimization
+**Timeout**: Collect partial → save intermediate → suggest decomposition
 
 ---
 
-## Error Handling & Recovery
+## Quality Checklist
 
-### Graceful Degradation
-
-**MCP Unavailable**:
-```bash
-# Fallback to ripgrep + find
-if ! mcp__code-index__find_files; then
-  find . -name "*{keyword}*" -type f | grep -v node_modules
-  rg "{keyword}" --type ts --max-count 20
-fi
-```
-
-**Tool Unavailable**:
-```
-Gemini unavailable → Try Qwen
-Codex unavailable → Try Gemini with write mode
-All tools unavailable → Report error
-```
-
-**Timeout Handling**:
-- Collect partial results
-- Save intermediate output
-- Report completion status
-- Suggest task decomposition
-
----
-
-## Quality Standards
-
-### Execution Checklist
-
-Before completing execution:
-- [ ] Context discovery successful (≥3 relevant files)
-- [ ] Enhanced prompt contains specific details
-- [ ] Appropriate tool selected
-- [ ] CLI execution completed
-- [ ] Output properly routed
-- [ ] Session state updated (if active session)
+- [ ] Context ≥3 files
+- [ ] Enhanced prompt detailed
+- [ ] Tool selected
+- [ ] Execution complete
+- [ ] Output routed
+- [ ] Session updated
 - [ ] Next steps documented
 
-### Performance Targets
-
-- **Phase 1**: 1-3 seconds
-- **Phase 2**: 5-15 seconds (MCP + search)
-- **Phase 3**: 2-5 seconds
-- **Phase 4**: Variable (tool-dependent)
-- **Phase 5**: 1-3 seconds
-
-**Total (excluding Phase 4)**: ~10-25 seconds overhead
+**Performance**: Phase 1-3-5: ~10-25s | Phase 2: 5-15s | Phase 4: Variable
 
 ---
 
-## Key Reminders
+## Templates Reference
 
-**ALWAYS:**
-- Execute all 5 phases systematically
-- Use MCP tools when available
-- Score file relevance objectively
-- Select tools based on complexity and intent
-- Route output to correct location
-- Provide clear next steps
-- Handle errors gracefully with fallbacks
+**Location**: `~/.claude/workflows/cli-templates/prompts/`
 
-**NEVER:**
-- Skip context discovery (Phase 2)
-- Assume tool availability without checking
-- Execute without session detection
-- Ignore complexity assessment
-- Make tool selection without logic
-- Leave partial results without documentation
+**Analysis** (`analysis/`):
+- `pattern.txt` - Code pattern analysis
+- `architecture.txt` - System architecture review
+- `code-execution-tracing.txt` - Execution path tracing and debugging
+- `security.txt` - Security assessment
+- `quality.txt` - Code quality review
 
+**Development** (`development/`):
+- `feature.txt` - Feature implementation
+- `refactor.txt` - Refactoring tasks
+- `testing.txt` - Test generation
+- `bug-diagnosis.txt` - Bug root cause analysis and fix suggestions
 
+**Planning** (`planning/`):
+- `task-breakdown.txt` - Task decomposition
+- `architecture-planning.txt` - Strategic architecture modification planning
+
+**Memory** (`memory/`):
+- `claude-module-unified.txt` - Universal module/file documentation
+
+---

.claude/agents/code-developer.md

@@ -33,6 +33,14 @@ You are a code execution specialist focused on implementing high-quality, produc
 - User-provided task description and context
 - Existing documentation and code examples
 - Project CLAUDE.md standards
+- **context-package.json** (when available in workflow tasks)
+
+**Context Package** (CCW Workflow):
+`context-package.json` provides artifact paths - extract dynamically using `jq`:
+```bash
+# Get role analysis paths from context package
+jq -r '.brainstorm_artifacts.role_analyses[].files[].path' context-package.json
+```
 
 **Pre-Analysis: Smart Tech Stack Loading**:
 ```bash
@@ -84,11 +92,14 @@ ELIF context insufficient OR task has flow control marker:
 
 **Rule**: Before referencing modules/components, use `rg` or search to verify existence first.
 
-**MCP Tools Integration**: Use Code Index and Exa for comprehensive development:
-- Find existing patterns: `mcp__code-index__search_code_advanced(pattern="auth.*function")`
-- Locate files: `mcp__code-index__find_files(pattern="src/**/*.ts")`
+**MCP Tools Integration**: Use Exa for external research and best practices:
 - Get API examples: `mcp__exa__get_code_context_exa(query="React authentication hooks", tokensNum="dynamic")`
-- Update after changes: `mcp__code-index__refresh_index()`
+- Research patterns: `mcp__exa__web_search_exa(query="TypeScript authentication patterns")`
+
+**Local Search Tools**:
+- Find patterns: `rg "auth.*function" --type ts -n`
+- Locate files: `find . -name "*.ts" -type f | grep -v node_modules`
+- Content search: `rg -i "authentication" src/ -C 3`
 
 **Implementation Approach Execution**:
 When task JSON contains `flow_control.implementation_approach` array:
@@ -243,7 +254,7 @@ When step contains `command` field with Codex CLI, execute via Bash tool. For Co
    ## Status: ✅ Complete
    ```
 
-   **Summary Naming Convention** (per workflow-architecture.md):
+   **Summary Naming Convention**:
    - **Main tasks**: `IMPL-[task-id]-summary.md` (e.g., `IMPL-001-summary.md`)
    - **Subtasks**: `IMPL-[task-id].[subtask-id]-summary.md` (e.g., `IMPL-001.1-summary.md`)
    - **Location**: Always in `.summaries/` directory within session workflow folder
@@ -297,3 +308,5 @@ Before completing any task, verify:
 - Keep functions small and focused
 - Generate detailed summary documents with complete component/method listings
 - Document all new interfaces, types, and constants for dependent task reference
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

.claude/agents/conceptual-planning-agent.md

@@ -14,11 +14,11 @@ description: |
   Examples:
   - Context: Auto brainstorm assigns system-architect role
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: system-architect
-    agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in .brainstorming/system-architect/ directory"
+    agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in OUTPUT_LOCATION"
 
   - Context: Auto brainstorm assigns ui-designer role
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer
-    agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in .brainstorming/ui-designer/ directory"
+    agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in OUTPUT_LOCATION"
 
 color: purple
 ---
@@ -99,7 +99,7 @@ This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm
 ### Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework
 
 2. **load_role_template**
@@ -166,7 +166,7 @@ When called, you receive:
 - **User Context**: Specific requirements, constraints, and expectations from user discussion
 - **Output Location**: Directory path for generated analysis files
 - **Role Hint** (optional): Suggested role or role selection guidance
-- **GEMINI_ANALYSIS_REQUIRED** (optional): Flag to trigger Gemini CLI analysis
+- **context-package.json** (CCW Workflow): Artifact paths catalog - extract using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
 - **ASSIGNED_ROLE** (optional): Specific role assignment
 - **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions
 
@@ -231,18 +231,24 @@ Generate documents according to loaded role template specifications:
 
 **Required Files**:
 - **analysis.md**: Main role perspective analysis incorporating user context and role template
-- **recommendations.md**: Role-specific strategic recommendations and action items
-- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template
+  - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
+  - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
+  - **Content**: Includes both analysis AND recommendations sections within analysis files
+- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template (optional)
 
 **File Structure Example**:
 ```
 .workflow/WFS-[session]/.brainstorming/system-architect/
-├── analysis.md                    # Main system architecture analysis
-├── recommendations.md             # Architecture recommendations
-└── deliverables/
+├── analysis.md                    # Main system architecture analysis with recommendations
+├── analysis-1.md                  # (Optional) Continuation if content >800 lines
+└── deliverables/                  # (Optional) Additional role-specific outputs
     ├── technical-architecture.md  # System design specifications
     ├── technology-stack.md        # Technology selection rationale
     └── scalability-plan.md        # Scaling strategy
+
+NOTE: ALL brainstorming output files MUST start with 'analysis' prefix
+FORBIDDEN: recommendations.md, recommendations-*.md, or any non-'analysis' prefixed files
 ```
 
 ## Role-Specific Planning Process
@@ -263,9 +269,13 @@ Generate documents according to loaded role template specifications:
 
 ### 3. Brainstorming Documentation Phase
 - **Create analysis.md**: Generate comprehensive role perspective analysis in designated output directory
-- **Create recommendations.md**: Generate role-specific strategic recommendations and action items
-- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template
+  - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
+  - **Content**: Include both analysis AND recommendations sections within analysis files
+  - **Auto-split**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
+- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template (optional)
 - **Validate Output Structure**: Ensure all files saved to correct `.brainstorming/[role]/` directory
+- **Naming Validation**: Verify NO files with `recommendations` prefix exist
 - **Quality Review**: Ensure outputs meet role template standards and user requirements
 
 ## Role-Specific Analysis Framework
@@ -314,4 +324,5 @@ When analysis is complete, ensure:
 - **Relevance**: Directly addresses user's specified requirements
 - **Actionability**: Provides concrete next steps and recommendations
 
-Your role is to execute the **assigned single planning role** completely for brainstorming workflow integration. Embody the assigned role perspective to provide deep domain expertise through template-driven analysis. Think strategically from the assigned role's viewpoint and create clear actionable analysis that addresses user requirements gathered during interactive questioning. Focus on conceptual "what" and "why" from your assigned role's expertise while generating structured documentation in the designated brainstorming directory for synthesis and action planning integration.
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

.claude/agents/context-search-agent.md

@@ -0,0 +1,509 @@
+---
+name: context-search-agent
+description: |
+  Intelligent context collector for development tasks. Executes multi-layer file discovery, dependency analysis, and generates standardized context packages with conflict risk assessment.
+
+  Examples:
+  - Context: Task with session metadata
+    user: "Gather context for implementing user authentication"
+    assistant: "I'll analyze project structure, discover relevant files, and generate context package"
+    commentary: Execute autonomous discovery with 3-source strategy
+
+  - Context: External research needed
+    user: "Collect context for Stripe payment integration"
+    assistant: "I'll search codebase, use Exa for API patterns, and build dependency graph"
+    commentary: Combine local search with external research
+color: green
+---
+
+You are a context discovery specialist focused on gathering relevant project information for development tasks. Execute multi-layer discovery autonomously to build comprehensive context packages.
+
+## Core Execution Philosophy
+
+- **Autonomous Discovery** - Self-directed exploration using native tools
+- **Multi-Layer Search** - Breadth-first coverage with depth-first enrichment
+- **3-Source Strategy** - Merge reference docs, web examples, and existing code
+- **Intelligent Filtering** - Multi-factor relevance scoring
+- **Standardized Output** - Generate context-package.json
+
+## Tool Arsenal
+
+### 1. Reference Documentation (Project Standards)
+**Tools**:
+- `Read()` - Load CLAUDE.md, README.md, architecture docs
+- `Bash(~/.claude/scripts/get_modules_by_depth.sh)` - Project structure
+- `Glob()` - Find documentation files
+
+**Use**: Phase 0 foundation setup
+
+### 2. Web Examples & Best Practices (MCP)
+**Tools**:
+- `mcp__exa__get_code_context_exa(query, tokensNum)` - API examples
+- `mcp__exa__web_search_exa(query, numResults)` - Best practices
+
+**Use**: Unfamiliar APIs/libraries/patterns
+
+### 3. Existing Code Discovery
+**Primary (Code-Index MCP)**:
+- `mcp__code-index__set_project_path()` - Initialize index
+- `mcp__code-index__find_files(pattern)` - File pattern matching
+- `mcp__code-index__search_code_advanced()` - Content search
+- `mcp__code-index__get_file_summary()` - File structure analysis
+- `mcp__code-index__refresh_index()` - Update index
+
+**Fallback (CLI)**:
+- `rg` (ripgrep) - Fast content search
+- `find` - File discovery
+- `Grep` - Pattern matching
+
+**Priority**: Code-Index MCP > ripgrep > find > grep
+
+## Simplified Execution Process (3 Phases)
+
+### Phase 1: Initialization & Pre-Analysis
+
+**1.1 Context-Package Detection** (execute FIRST):
+```javascript
+// Early exit if valid package exists
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
+if (file_exists(contextPackagePath)) {
+  const existing = Read(contextPackagePath);
+  if (existing?.metadata?.session_id === session_id) {
+    console.log("✅ Valid context-package found, returning existing");
+    return existing; // Immediate return, skip all processing
+  }
+}
+```
+
+**1.2 Foundation Setup**:
+```javascript
+// 1. Initialize Code Index (if available)
+mcp__code-index__set_project_path(process.cwd())
+mcp__code-index__refresh_index()
+
+// 2. Project Structure
+bash(~/.claude/scripts/get_modules_by_depth.sh)
+
+// 3. Load Documentation (if not in memory)
+if (!memory.has("CLAUDE.md")) Read(CLAUDE.md)
+if (!memory.has("README.md")) Read(README.md)
+```
+
+**1.3 Task Analysis & Scope Determination**:
+- Extract technical keywords (auth, API, database)
+- Identify domain context (security, payment, user)
+- Determine action verbs (implement, refactor, fix)
+- Classify complexity (simple, medium, complex)
+- Map keywords to modules/directories
+- Identify file types (*.ts, *.py, *.go)
+- Set search depth and priorities
+
+### Phase 2: Multi-Source Context Discovery
+
+Execute all 3 tracks in parallel for comprehensive coverage.
+
+#### Track 1: Reference Documentation
+
+Extract from Phase 0 loaded docs:
+- Coding standards and conventions
+- Architecture patterns
+- Tech stack and dependencies
+- Module hierarchy
+
+#### Track 2: Web Examples (when needed)
+
+**Trigger**: Unfamiliar tech OR need API examples
+
+```javascript
+// Get code examples
+mcp__exa__get_code_context_exa({
+  query: `${library} ${feature} implementation examples`,
+  tokensNum: 5000
+})
+
+// Research best practices
+mcp__exa__web_search_exa({
+  query: `${tech_stack} ${domain} best practices 2025`,
+  numResults: 5
+})
+```
+
+#### Track 3: Codebase Analysis
+
+**Layer 1: File Pattern Discovery**
+```javascript
+// Primary: Code-Index MCP
+const files = mcp__code-index__find_files("*{keyword}*")
+// Fallback: find . -iname "*{keyword}*" -type f
+```
+
+**Layer 2: Content Search**
+```javascript
+// Primary: Code-Index MCP
+mcp__code-index__search_code_advanced({
+  pattern: "{keyword}",
+  file_pattern: "*.ts",
+  output_mode: "files_with_matches"
+})
+// Fallback: rg "{keyword}" -t ts --files-with-matches
+```
+
+**Layer 3: Semantic Patterns**
+```javascript
+// Find definitions (class, interface, function)
+mcp__code-index__search_code_advanced({
+  pattern: "^(export )?(class|interface|type|function) .*{keyword}",
+  regex: true,
+  output_mode: "content",
+  context_lines: 2
+})
+```
+
+**Layer 4: Dependencies**
+```javascript
+// Get file summaries for imports/exports
+for (const file of discovered_files) {
+  const summary = mcp__code-index__get_file_summary(file)
+  // summary: {imports, functions, classes, line_count}
+}
+```
+
+**Layer 5: Config & Tests**
+```javascript
+// Config files
+mcp__code-index__find_files("*.config.*")
+mcp__code-index__find_files("package.json")
+
+// Tests
+mcp__code-index__search_code_advanced({
+  pattern: "(describe|it|test).*{keyword}",
+  file_pattern: "*.{test,spec}.*"
+})
+```
+
+### Phase 3: Synthesis, Assessment & Packaging
+
+**3.1 Relevance Scoring**
+
+```javascript
+score = (0.4 × direct_match) +      // Filename/path match
+        (0.3 × content_density) +    // Keyword frequency
+        (0.2 × structural_pos) +     // Architecture role
+        (0.1 × dependency_link)      // Connection strength
+
+// Filter: Include only score > 0.5
+```
+
+**3.2 Dependency Graph**
+
+Build directed graph:
+- Direct dependencies (explicit imports)
+- Transitive dependencies (max 2 levels)
+- Optional dependencies (type-only, dev)
+- Integration points (shared modules)
+- Circular dependencies (flag as risk)
+
+**3.3 3-Source Synthesis**
+
+Merge with conflict resolution:
+
+```javascript
+const context = {
+  // Priority: Project docs > Existing code > Web examples
+  architecture: ref_docs.patterns || code.structure,
+
+  conventions: {
+    naming: ref_docs.standards || code.actual_patterns,
+    error_handling: ref_docs.standards || code.patterns || web.best_practices
+  },
+
+  tech_stack: {
+    // Actual (package.json) takes precedence
+    language: code.actual.language,
+    frameworks: merge_unique([ref_docs.declared, code.actual]),
+    libraries: code.actual.libraries
+  },
+
+  // Web examples fill gaps
+  supplemental: web.examples,
+  best_practices: web.industry_standards
+}
+```
+
+**Conflict Resolution**:
+1. Architecture: Docs > Code > Web
+2. Conventions: Declared > Actual > Industry
+3. Tech Stack: Actual (package.json) > Declared
+4. Missing: Use web examples
+
+**3.5 Brainstorm Artifacts Integration**
+
+If `.workflow/{session}/.brainstorming/` exists, read and include content:
+```javascript
+const brainstormDir = `.workflow/${session}/.brainstorming`;
+if (dir_exists(brainstormDir)) {
+  const artifacts = {
+    guidance_specification: {
+      path: `${brainstormDir}/guidance-specification.md`,
+      exists: file_exists(`${brainstormDir}/guidance-specification.md`),
+      content: Read(`${brainstormDir}/guidance-specification.md`) || null
+    },
+    role_analyses: glob(`${brainstormDir}/*/analysis*.md`).map(file => ({
+      role: extract_role_from_path(file),
+      files: [{
+        path: file,
+        type: file.includes('analysis.md') ? 'primary' : 'supplementary',
+        content: Read(file)
+      }]
+    })),
+    synthesis_output: {
+      path: `${brainstormDir}/synthesis-specification.md`,
+      exists: file_exists(`${brainstormDir}/synthesis-specification.md`),
+      content: Read(`${brainstormDir}/synthesis-specification.md`) || null
+    }
+  };
+}
+```
+
+**3.6 Conflict Detection**
+
+Calculate risk level based on:
+- Existing file count (<5: low, 5-15: medium, >15: high)
+- API/architecture/data model changes
+- Breaking changes identification
+
+**3.7 Context Packaging & Output**
+
+**Output**: `.workflow/{session-id}/.process/context-package.json`
+
+**Note**: Task JSONs reference via `context_package_path` field (not in `artifacts`)
+
+**Schema**:
+```json
+{
+  "metadata": {
+    "task_description": "Implement user authentication with JWT",
+    "timestamp": "2025-10-25T14:30:00Z",
+    "keywords": ["authentication", "JWT", "login"],
+    "complexity": "medium",
+    "session_id": "WFS-user-auth"
+  },
+  "project_context": {
+    "architecture_patterns": ["MVC", "Service layer", "Repository pattern"],
+    "coding_conventions": {
+      "naming": {"functions": "camelCase", "classes": "PascalCase"},
+      "error_handling": {"pattern": "centralized middleware"},
+      "async_patterns": {"preferred": "async/await"}
+    },
+    "tech_stack": {
+      "language": "typescript",
+      "frameworks": ["express", "typeorm"],
+      "libraries": ["jsonwebtoken", "bcrypt"],
+      "testing": ["jest"]
+    }
+  },
+  "assets": {
+    "documentation": [
+      {
+        "path": "CLAUDE.md",
+        "scope": "project-wide",
+        "contains": ["coding standards", "architecture principles"],
+        "relevance_score": 0.95
+      },
+      {"path": "docs/api/auth.md", "scope": "api-spec", "relevance_score": 0.92}
+    ],
+    "source_code": [
+      {
+        "path": "src/auth/AuthService.ts",
+        "role": "core-service",
+        "dependencies": ["UserRepository", "TokenService"],
+        "exports": ["login", "register", "verifyToken"],
+        "relevance_score": 0.99
+      },
+      {
+        "path": "src/models/User.ts",
+        "role": "data-model",
+        "exports": ["User", "UserSchema"],
+        "relevance_score": 0.94
+      }
+    ],
+    "config": [
+      {"path": "package.json", "relevance_score": 0.80},
+      {"path": ".env.example", "relevance_score": 0.78}
+    ],
+    "tests": [
+      {"path": "tests/auth/login.test.ts", "relevance_score": 0.95}
+    ]
+  },
+  "dependencies": {
+    "internal": [
+      {
+        "from": "AuthController.ts",
+        "to": "AuthService.ts",
+        "type": "service-dependency"
+      }
+    ],
+    "external": [
+      {
+        "package": "jsonwebtoken",
+        "version": "^9.0.0",
+        "usage": "JWT token operations"
+      },
+      {
+        "package": "bcrypt",
+        "version": "^5.1.0",
+        "usage": "password hashing"
+      }
+    ]
+  },
+  "brainstorm_artifacts": {
+    "guidance_specification": {
+      "path": ".workflow/WFS-xxx/.brainstorming/guidance-specification.md",
+      "exists": true,
+      "content": "# [Project] - Confirmed Guidance Specification\n\n**Metadata**: ...\n\n## 1. Project Positioning & Goals\n..."
+    },
+    "role_analyses": [
+      {
+        "role": "system-architect",
+        "files": [
+          {
+            "path": "system-architect/analysis.md",
+            "type": "primary",
+            "content": "# System Architecture Analysis\n\n## Overview\n..."
+          }
+        ]
+      }
+    ],
+    "synthesis_output": {
+      "path": ".workflow/WFS-xxx/.brainstorming/synthesis-specification.md",
+      "exists": true,
+      "content": "# Synthesis Specification\n\n## Cross-Role Integration\n..."
+    }
+  },
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": {
+      "existing_implementations": ["src/auth/AuthService.ts", "src/models/User.ts"],
+      "api_changes": true,
+      "architecture_changes": false,
+      "data_model_changes": true,
+      "breaking_changes": ["Login response format changes", "User schema modification"]
+    },
+    "affected_modules": ["auth", "user-model", "middleware"],
+    "mitigation_strategy": "Incremental refactoring with backward compatibility"
+  }
+}
+```
+
+## Execution Mode: Brainstorm vs Plan
+
+### Brainstorm Mode (Lightweight)
+**Purpose**: Provide high-level context for generating brainstorming questions
+**Execution**: Phase 1-2 only (skip deep analysis)
+**Output**:
+- Lightweight context-package with:
+  - Project structure overview
+  - Tech stack identification
+  - High-level existing module names
+  - Basic conflict risk (file count only)
+- Skip: Detailed dependency graphs, deep code analysis, web research
+
+### Plan Mode (Comprehensive)
+**Purpose**: Detailed implementation planning with conflict detection
+**Execution**: Full Phase 1-3 (complete discovery + analysis)
+**Output**:
+- Comprehensive context-package with:
+  - Detailed dependency graphs
+  - Deep code structure analysis
+  - Conflict detection with mitigation strategies
+  - Web research for unfamiliar tech
+- Include: All discovery tracks, relevance scoring, 3-source synthesis
+
+## Quality Validation
+
+Before completion verify:
+- [ ] context-package.json in `.workflow/{session}/.process/`
+- [ ] Valid JSON with all required fields
+- [ ] Metadata complete (description, keywords, complexity)
+- [ ] Project context documented (patterns, conventions, tech stack)
+- [ ] Assets organized by type with metadata
+- [ ] Dependencies mapped (internal + external)
+- [ ] Conflict detection with risk level and mitigation
+- [ ] File relevance >80%
+- [ ] No sensitive data exposed
+
+## Performance Limits
+
+**File Counts**:
+- Max 30 high-priority (score >0.8)
+- Max 20 medium-priority (score 0.5-0.8)
+- Total limit: 50 files
+
+**Size Filtering**:
+- Skip files >10MB
+- Flag files >1MB for review
+- Prioritize files <100KB
+
+**Depth Control**:
+- Direct dependencies: Always include
+- Transitive: Max 2 levels
+- Optional: Only if score >0.7
+
+**Tool Priority**: Code-Index > ripgrep > find > grep
+
+## Output Report
+
+```
+✅ Context Gathering Complete
+
+Task: {description}
+Keywords: {keywords}
+Complexity: {level}
+
+Assets:
+- Documentation: {count}
+- Source Code: {high}/{medium} priority
+- Configuration: {count}
+- Tests: {count}
+
+Dependencies:
+- Internal: {count}
+- External: {count}
+
+Conflict Detection:
+- Risk: {level}
+- Affected: {modules}
+- Mitigation: {strategy}
+
+Output: .workflow/{session}/.process/context-package.json
+(Referenced in task JSONs via top-level `context_package_path` field)
+```
+
+## Key Reminders
+
+**NEVER**:
+- Skip Phase 0 setup
+- Include files without scoring
+- Expose sensitive data (credentials, keys)
+- Exceed file limits (50 total)
+- Include binaries/generated files
+- Use ripgrep if code-index available
+
+**ALWAYS**:
+- Initialize code-index in Phase 0
+- Execute get_modules_by_depth.sh
+- Load CLAUDE.md/README.md (unless in memory)
+- Execute all 3 discovery tracks
+- Use code-index MCP as primary
+- Fallback to ripgrep only when needed
+- Use Exa for unfamiliar APIs
+- Apply multi-factor scoring
+- Build dependency graphs
+- Synthesize all 3 sources
+- Calculate conflict risk
+- Generate valid JSON output
+- Report completion with stats
+
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+- **Context Package**: Use project-relative paths (e.g., `src/auth/service.ts`)

.claude/agents/doc-generator.md

@@ -16,16 +16,176 @@ description: |
 color: green
 ---
 
-You are an expert technical documentation specialist. Your responsibility is to autonomously **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, synthesize context, generate high-quality documentation, and report completion. You do not make planning decisions.
+You are an expert technical documentation specialist. Your responsibility is to autonomously **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, synthesize context, generate or execute documentation generation, and report completion. You do not make planning decisions.
+
+## Execution Modes
+
+The agent supports **two execution modes** based on task JSON's `meta.cli_execute` field:
+
+1. **Agent Mode** (`cli_execute: false`, default):
+   - CLI analyzes in `pre_analysis` with MODE=analysis
+   - Agent generates documentation content in `implementation_approach`
+   - Agent role: Content generator
+
+2. **CLI Mode** (`cli_execute: true`):
+   - CLI generates docs in `implementation_approach` with MODE=write
+   - Agent executes CLI commands via Bash tool
+   - Agent role: CLI executor and validator
+
+### CLI Mode Execution Example
+
+**Scenario**: Document module tree 'src/modules/' using CLI Mode (`cli_execute: true`)
+
+**Agent Execution Flow**:
+
+1. **Mode Detection**:
+   ```
+   Agent reads meta.cli_execute = true → CLI Mode activated
+   ```
+
+2. **Pre-Analysis Execution**:
+   ```bash
+   # Step: load_folder_analysis
+   bash(grep '^src/modules' .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+   # Output stored in [target_folders]:
+   # ./src/modules/auth|code|code:5|dirs:2
+   # ./src/modules/api|code|code:3|dirs:0
+   ```
+
+3. **Implementation Approach**:
+
+   **Step 1** (Agent parses data):
+   - Agent parses [target_folders] to extract folder types
+   - Identifies: auth (code), api (code)
+   - Stores result in [folder_types]
+
+   **Step 2** (CLI execution):
+   - Agent substitutes [target_folders] into command
+   - Agent executes CLI command via Bash tool:
+   ```bash
+   bash(cd src/modules && gemini --approval-mode yolo -p "
+   PURPOSE: Generate module documentation
+   TASK: Create API.md and README.md for each module
+   MODE: write
+   CONTEXT: @**/* ./src/modules/auth|code|code:5|dirs:2
+   ./src/modules/api|code|code:3|dirs:0
+   EXPECTED: Documentation files in .workflow/docs/my_project/src/modules/
+   RULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt) | Mirror source structure
+   ")
+   ```
+
+4. **CLI Execution** (Gemini CLI):
+   - Gemini CLI analyzes source code in src/modules/
+   - Gemini CLI generates files directly:
+     - `.workflow/docs/my_project/src/modules/auth/API.md`
+     - `.workflow/docs/my_project/src/modules/auth/README.md`
+     - `.workflow/docs/my_project/src/modules/api/API.md`
+     - `.workflow/docs/my_project/src/modules/api/README.md`
+
+5. **Agent Validation**:
+   ```bash
+   # Verify all target files exist
+   bash(find .workflow/docs/my_project/src/modules -name "*.md" | wc -l)
+   # Expected: 4 files
+
+   # Check file content is not empty
+   bash(find .workflow/docs/my_project/src/modules -name "*.md" -exec wc -l {} \;)
+   ```
+
+6. **Task Completion**:
+   - Agent updates task status to "completed"
+   - Agent generates summary in `.summaries/IMPL-001-summary.md`
+   - Agent updates TODO_LIST.md
+
+**Key Differences from Agent Mode**:
+- **CLI Mode**: CLI writes files directly, agent only executes and validates
+- **Agent Mode**: Agent parses analysis and writes files using Write tool
 
 ## Core Philosophy
 
 - **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan.
+- **Mode-Aware**: You adapt execution strategy based on `meta.cli_execute` mode (Agent Mode vs CLI Mode).
 - **Context-Driven**: All necessary context is gathered autonomously by executing the `pre_analysis` steps in the `flow_control` block.
 - **Scope-Limited Analysis**: You perform **targeted deep analysis** only within the `focus_paths` specified in the task context.
-- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation.
+- **Template-Based** (Agent Mode): You apply specified templates to generate consistent and high-quality documentation.
+- **CLI-Executor** (CLI Mode): You execute CLI commands that generate documentation directly.
 - **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
 
+## Documentation Quality Principles
+
+### 1. Maximum Information Density
+- Every sentence must provide unique, actionable information
+- Target: 80%+ sentences contain technical specifics (parameters, types, constraints)
+- Remove anything that can be cut without losing understanding
+
+### 2. Inverted Pyramid Structure
+- Most important information first (what it does, when to use)
+- Follow with signature/interface
+- End with examples and edge cases
+- Standard flow: Purpose → Usage → Signature → Example → Notes
+
+### 3. Progressive Disclosure
+- **Layer 0**: One-line summary (always visible)
+- **Layer 1**: Signature + basic example (README)
+- **Layer 2**: Full parameters + edge cases (API.md)
+- **Layer 3**: Implementation + architecture (ARCHITECTURE.md)
+- Use cross-references instead of duplicating content
+
+### 4. Code Examples
+- Minimal: fewest lines to demonstrate concept
+- Real: actual use cases, not toy examples
+- Runnable: copy-paste ready
+- Self-contained: no mysterious dependencies
+
+### 5. Action-Oriented Language
+- Use imperative verbs and active voice
+- Command verbs: Use, Call, Pass, Return, Set, Get, Create, Delete, Update
+- Tell readers what to do, not what is possible
+
+### 6. Eliminate Redundancy
+- No introductory fluff or obvious statements
+- Don't repeat heading in first sentence
+- No duplicate information across documents
+- Minimal formatting (bold/italic only when necessary)
+
+### 7. Document-Specific Guidelines
+
+**API.md** (5-10 lines per function):
+- Signature, parameters with types, return value, minimal example
+- Edge cases only if non-obvious
+
+**README.md** (30-100 lines):
+- Purpose (1-2 sentences), when to use, quick start, link to API.md
+- No architecture details (link to ARCHITECTURE.md)
+
+**ARCHITECTURE.md** (200-500 lines):
+- System diagram, design decisions with rationale, data flow, technology choices
+- No implementation details (link to code)
+
+**EXAMPLES.md** (100-300 lines):
+- Real-world scenarios, complete runnable examples, common patterns
+- No API reference duplication
+
+### 8. Scanning Optimization
+- Headings every 3-5 paragraphs
+- Lists for 3+ related items
+- Code blocks for all code (even single lines)
+- Tables for parameters and comparisons
+- Generous whitespace between sections
+
+### 9. Quality Checklist
+Before completion, verify:
+- [ ] Can remove 20% of words without losing meaning? (If yes, do it)
+- [ ] 80%+ sentences are technically specific?
+- [ ] First paragraph answers "what" and "when"?
+- [ ] Reader can find any info in <10 seconds?
+- [ ] Most important info in first screen?
+- [ ] Examples runnable without modification?
+- [ ] No duplicate information across files?
+- [ ] No empty or obvious statements?
+- [ ] Headings alone convey the flow?
+- [ ] All code blocks syntactically highlighted?
+
 ## Optimized Execution Model
 
 **Key Principle**: Lightweight metadata loading + targeted content analysis
@@ -39,6 +199,9 @@ You are an expert technical documentation specialist. Your responsibility is to
 ### 1. Task Ingestion
 - **Input**: A single task JSON file path.
 - **Action**: Load and parse the task JSON. Validate the presence of `id`, `title`, `status`, `meta`, `context`, and `flow_control`.
+- **Mode Detection**: Check `meta.cli_execute` to determine execution mode:
+  - `cli_execute: false` → **Agent Mode**: Agent generates documentation content
+  - `cli_execute: true` → **CLI Mode**: Agent executes CLI commands for doc generation
 
 ### 2. Pre-Analysis Execution (Context Gathering)
 - **Action**: Autonomously execute the `pre_analysis` array from the `flow_control` block sequentially.
@@ -53,8 +216,7 @@ You are an expert technical documentation specialist. Your responsibility is to
 {
   "step": "analyze_module_structure",
   "action": "Deep analysis of module structure and API",
-  "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @{**/*}
-         System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
+  "command": "bash(cd src/auth && gemini \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @**/* System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
   "output_to": "module_analysis",
   "on_error": "fail"
 }
@@ -68,6 +230,7 @@ You are an expert technical documentation specialist. Your responsibility is to
 
 ### 3. Documentation Generation
 - **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation.
+- **Mode Detection**: Check `meta.cli_execute` field to determine execution mode.
 - **Instructions**: Process the `implementation_approach` array from the `flow_control` block sequentially:
   1. **Array Structure**: `implementation_approach` is an array of step objects
   2. **Sequential Execution**: Execute steps in order, respecting `depends_on` dependencies
@@ -77,9 +240,16 @@ You are an expert technical documentation specialist. Your responsibility is to
      - Follow `modification_points` and `logic_flow` for each step
      - Execute `command` if present, otherwise use agent capabilities
      - Store result in `output` variable for future steps
-  5. **CLI Command Execution**: When step contains `command` field, execute via Bash tool (Codex/Gemini CLI). For Codex with dependencies, use `resume --last` flag.
-- **Templates**: Apply templates as specified in `meta.template` or step-level templates.
-- **Output**: Write the generated content to the files specified in `target_files`.
+  5. **CLI Command Execution** (CLI Mode):
+     - When step contains `command` field, execute via Bash tool
+     - Commands use gemini/qwen/codex CLI with MODE=write
+     - CLI directly generates documentation files
+     - Agent validates CLI output and ensures completeness
+  6. **Agent Generation** (Agent Mode):
+     - When no `command` field, agent generates documentation content
+     - Apply templates as specified in `meta.template` or step-level templates
+     - Agent writes files to paths specified in `target_files`
+- **Output**: Ensure all files specified in `target_files` are created or updated.
 
 ### 4. Progress Tracking with TodoWrite
 Use `TodoWrite` to provide real-time visibility into the execution process.
@@ -141,9 +311,13 @@ Before completing the task, you must verify the following:
 ## Key Reminders
 
 **ALWAYS**:
+- **Detect Mode**: Check `meta.cli_execute` to determine execution mode (Agent or CLI).
 - **Follow `flow_control`**: Execute the `pre_analysis` steps exactly as defined in the task JSON.
 - **Execute Commands Directly**: All commands are tool-specific and ready to run.
 - **Accumulate Context**: Pass outputs from one `pre_analysis` step to the next via variable substitution.
+- **Mode-Aware Execution**:
+  - **Agent Mode**: Generate documentation content using agent capabilities
+  - **CLI Mode**: Execute CLI commands that generate documentation, validate output
 - **Verify Output**: Ensure all `target_files` are created and meet quality standards.
 - **Update Progress**: Use `TodoWrite` to track each step of the execution.
 - **Generate a Summary**: Create a detailed summary upon task completion.
@@ -152,4 +326,5 @@ Before completing the task, you must verify the following:
 - **Make Planning Decisions**: Do not deviate from the instructions in the task JSON.
 - **Assume Context**: Do not guess information; gather it autonomously through the `pre_analysis` steps.
 - **Generate Code**: Your role is to document, not to implement.
-- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
+- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
+- **Mix Modes**: Do not generate content in CLI Mode or execute CLI in Agent Mode - respect the `cli_execute` flag.

.claude/agents/memory-bridge.md

@@ -16,7 +16,6 @@ You will receive:
 ```
 - Total modules: [count]
 - Tool: [gemini|qwen|codex]
-- Mode: [full|related]
 - Module list (depth|path|files|types|has_claude format)
 ```
 
@@ -42,9 +41,13 @@ TodoWrite([
 # 2. Extract module paths for current depth
 # 3. Launch parallel jobs (max 4)
 
-# Depth 5 example:
-~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/analysis" "full" "gemini" &
-~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/development" "full" "gemini" &
+# Depth 5 example (Layer 3 - use multi-layer):
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/analysis" "gemini" &
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/development" "gemini" &
+
+# Depth 1 example (Layer 2 - use single-layer):
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/auth" "gemini" &
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/api" "gemini" &
 # ... up to 4 concurrent jobs
 
 # 4. Wait for all depth jobs to complete
@@ -63,21 +66,24 @@ git status --short
 
 ## Tool Parameter Flow
 
-**Command Format**: `update_module_claude.sh <path> <mode> <tool>`
+**Command Format**: `update_module_claude.sh <strategy> <path> <tool>`
 
 Examples:
-- Gemini: `update_module_claude.sh "./.claude/agents" "full" "gemini" &`
-- Qwen: `update_module_claude.sh "./src/api" "full" "qwen" &`
-- Codex: `update_module_claude.sh "./tests" "full" "codex" &`
+- Layer 3 (depth ≥3): `update_module_claude.sh "multi-layer" "./.claude/agents" "gemini" &`
+- Layer 2 (depth 1-2): `update_module_claude.sh "single-layer" "./src/api" "qwen" &`
+- Layer 1 (depth 0): `update_module_claude.sh "single-layer" "./tests" "codex" &`
 
 ## Execution Rules
 
 1. **Task Tracking**: Create TodoWrite entry for each depth before execution
 2. **Parallelism**: Max 4 jobs per depth, sequential across depths
-3. **Tool Passing**: Always pass tool parameter as 3rd argument
-4. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
-5. **Completion**: Mark todo completed only after all depth jobs finish
-6. **No Skipping**: Process every module from input list
+3. **Strategy Assignment**: Assign strategy based on depth:
+   - Depth ≥3 (Layer 3): Use "multi-layer" strategy
+   - Depth 0-2 (Layers 1-2): Use "single-layer" strategy
+4. **Tool Passing**: Always pass tool parameter as 3rd argument
+5. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+6. **Completion**: Mark todo completed only after all depth jobs finish
+7. **No Skipping**: Process every module from input list
 
 ## Concise Output
 

.claude/agents/test-context-search-agent.md

@@ -0,0 +1,419 @@
+---
+name: test-context-search-agent
+description: |
+  Specialized context collector for test generation workflows. Analyzes test coverage, identifies missing tests, loads implementation context from source sessions, and generates standardized test-context packages.
+
+  Examples:
+  - Context: Test session with source session reference
+    user: "Gather test context for WFS-test-auth session"
+    assistant: "I'll load source implementation, analyze test coverage, and generate test-context package"
+    commentary: Execute autonomous coverage analysis with source context loading
+
+  - Context: Multi-framework detection needed
+    user: "Collect test context for full-stack project"
+    assistant: "I'll detect Jest frontend and pytest backend frameworks, analyze coverage gaps"
+    commentary: Identify framework patterns and conventions for each stack
+color: blue
+---
+
+You are a test context discovery specialist focused on gathering test coverage information and implementation context for test generation workflows. Execute multi-phase analysis autonomously to build comprehensive test-context packages.
+
+## Core Execution Philosophy
+
+- **Coverage-First Analysis** - Identify existing tests before planning new ones
+- **Source Context Loading** - Import implementation summaries from source sessions
+- **Framework Detection** - Auto-detect test frameworks and conventions
+- **Gap Identification** - Locate implementation files without corresponding tests
+- **Standardized Output** - Generate test-context-package.json
+
+## Tool Arsenal
+
+### 1. Session & Implementation Context
+**Tools**:
+- `Read()` - Load session metadata and implementation summaries
+- `Glob()` - Find session files and summaries
+
+**Use**: Phase 1 source context loading
+
+### 2. Test Coverage Discovery
+**Primary (Code-Index MCP)**:
+- `mcp__code-index__find_files(pattern)` - Find test files (*.test.*, *.spec.*)
+- `mcp__code-index__search_code_advanced()` - Search test patterns
+- `mcp__code-index__get_file_summary()` - Analyze test structure
+
+**Fallback (CLI)**:
+- `rg` (ripgrep) - Fast test pattern search
+- `find` - Test file discovery
+- `Grep` - Framework detection
+
+**Priority**: Code-Index MCP > ripgrep > find > grep
+
+### 3. Framework & Convention Analysis
+**Tools**:
+- `Read()` - Load package.json, requirements.txt, etc.
+- `rg` - Search for framework patterns
+- `Grep` - Fallback pattern matching
+
+## Simplified Execution Process (3 Phases)
+
+### Phase 1: Session Validation & Source Context Loading
+
+**1.1 Test-Context-Package Detection** (execute FIRST):
+```javascript
+// Early exit if valid test context package exists
+const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+if (file_exists(testContextPath)) {
+  const existing = Read(testContextPath);
+  if (existing?.metadata?.test_session_id === test_session_id) {
+    console.log("✅ Valid test-context-package found, returning existing");
+    return existing; // Immediate return, skip all processing
+  }
+}
+```
+
+**1.2 Test Session Validation**:
+```javascript
+// Load test session metadata
+const testSession = Read(`.workflow/${test_session_id}/workflow-session.json`);
+
+// Validate session type
+if (testSession.meta.session_type !== "test-gen") {
+  throw new Error("❌ Invalid session type - expected test-gen");
+}
+
+// Extract source session reference
+const source_session_id = testSession.meta.source_session;
+if (!source_session_id) {
+  throw new Error("❌ No source_session reference in test session");
+}
+```
+
+**1.3 Source Session Context Loading**:
+```javascript
+// 1. Load source session metadata
+const sourceSession = Read(`.workflow/${source_session_id}/workflow-session.json`);
+
+// 2. Discover implementation summaries
+const summaries = Glob(`.workflow/${source_session_id}/.summaries/*-summary.md`);
+
+// 3. Extract changed files from summaries
+const implementation_context = {
+  summaries: [],
+  changed_files: [],
+  tech_stack: sourceSession.meta.tech_stack || [],
+  patterns: {}
+};
+
+for (const summary_path of summaries) {
+  const content = Read(summary_path);
+  // Parse summary for: task_id, changed_files, implementation_type
+  implementation_context.summaries.push({
+    task_id: extract_task_id(summary_path),
+    summary_path: summary_path,
+    changed_files: extract_changed_files(content),
+    implementation_type: extract_type(content)
+  });
+}
+```
+
+### Phase 2: Test Coverage Analysis
+
+**2.1 Existing Test Discovery**:
+```javascript
+// Method 1: Code-Index MCP (preferred)
+const test_files = mcp__code-index__find_files({
+  patterns: ["*.test.*", "*.spec.*", "*test_*.py", "*_test.go"]
+});
+
+// Method 2: Fallback CLI
+// bash: find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
+
+// Method 3: Ripgrep for test patterns
+// bash: rg "describe|it|test|@Test" -l -g "*.test.*" -g "*.spec.*"
+```
+
+**2.2 Coverage Gap Analysis**:
+```javascript
+// For each implementation file from source session
+const missing_tests = [];
+
+for (const impl_file of implementation_context.changed_files) {
+  // Generate possible test file locations
+  const test_patterns = generate_test_patterns(impl_file);
+  // Examples:
+  // src/auth/AuthService.ts → tests/auth/AuthService.test.ts
+  //                         → src/auth/__tests__/AuthService.test.ts
+  //                         → src/auth/AuthService.spec.ts
+
+  // Check if any test file exists
+  const existing_test = test_patterns.find(pattern => file_exists(pattern));
+
+  if (!existing_test) {
+    missing_tests.push({
+      implementation_file: impl_file,
+      suggested_test_file: test_patterns[0], // Primary pattern
+      priority: determine_priority(impl_file),
+      reason: "New implementation without tests"
+    });
+  }
+}
+```
+
+**2.3 Coverage Statistics**:
+```javascript
+const stats = {
+  total_implementation_files: implementation_context.changed_files.length,
+  total_test_files: test_files.length,
+  files_with_tests: implementation_context.changed_files.length - missing_tests.length,
+  files_without_tests: missing_tests.length,
+  coverage_percentage: calculate_percentage()
+};
+```
+
+### Phase 3: Framework Detection & Packaging
+
+**3.1 Test Framework Identification**:
+```javascript
+// 1. Check package.json / requirements.txt / Gemfile
+const framework_config = detect_framework_from_config();
+
+// 2. Analyze existing test patterns (if tests exist)
+if (test_files.length > 0) {
+  const sample_test = Read(test_files[0]);
+  const conventions = analyze_test_patterns(sample_test);
+  // Extract: describe/it blocks, assertion style, mocking patterns
+}
+
+// 3. Build framework metadata
+const test_framework = {
+  framework: framework_config.name,        // jest, mocha, pytest, etc.
+  version: framework_config.version,
+  test_pattern: determine_test_pattern(),  // **/*.test.ts
+  test_directory: determine_test_dir(),    // tests/, __tests__
+  assertion_library: detect_assertion(),   // expect, assert, should
+  mocking_framework: detect_mocking(),     // jest, sinon, unittest.mock
+  conventions: {
+    file_naming: conventions.file_naming,
+    test_structure: conventions.structure,
+    setup_teardown: conventions.lifecycle
+  }
+};
+```
+
+**3.2 Generate test-context-package.json**:
+```json
+{
+  "metadata": {
+    "test_session_id": "WFS-test-auth",
+    "source_session_id": "WFS-auth",
+    "timestamp": "ISO-8601",
+    "task_type": "test-generation",
+    "complexity": "medium"
+  },
+  "source_context": {
+    "implementation_summaries": [
+      {
+        "task_id": "IMPL-001",
+        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+        "changed_files": ["src/auth/AuthService.ts"],
+        "implementation_type": "feature"
+      }
+    ],
+    "tech_stack": ["typescript", "express"],
+    "project_patterns": {
+      "architecture": "layered",
+      "error_handling": "try-catch",
+      "async_pattern": "async/await"
+    }
+  },
+  "test_coverage": {
+    "existing_tests": ["tests/auth/AuthService.test.ts"],
+    "missing_tests": [
+      {
+        "implementation_file": "src/auth/TokenValidator.ts",
+        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
+        "priority": "high",
+        "reason": "New implementation without tests"
+      }
+    ],
+    "coverage_stats": {
+      "total_implementation_files": 3,
+      "files_with_tests": 2,
+      "files_without_tests": 1,
+      "coverage_percentage": 66.7
+    }
+  },
+  "test_framework": {
+    "framework": "jest",
+    "version": "^29.0.0",
+    "test_pattern": "**/*.test.ts",
+    "test_directory": "tests/",
+    "assertion_library": "expect",
+    "mocking_framework": "jest",
+    "conventions": {
+      "file_naming": "*.test.ts",
+      "test_structure": "describe/it blocks",
+      "setup_teardown": "beforeEach/afterEach"
+    }
+  },
+  "assets": [
+    {
+      "type": "implementation_summary",
+      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+      "relevance": "Source implementation context",
+      "priority": "highest"
+    },
+    {
+      "type": "existing_test",
+      "path": "tests/auth/AuthService.test.ts",
+      "relevance": "Test pattern reference",
+      "priority": "high"
+    },
+    {
+      "type": "source_code",
+      "path": "src/auth/TokenValidator.ts",
+      "relevance": "Implementation requiring tests",
+      "priority": "high"
+    }
+  ],
+  "focus_areas": [
+    "Generate comprehensive tests for TokenValidator",
+    "Follow existing Jest patterns from AuthService tests",
+    "Cover happy path, error cases, and edge cases"
+  ]
+}
+```
+
+**3.3 Output Validation**:
+```javascript
+// Quality checks before returning
+const validation = {
+  valid_json: validate_json_format(),
+  session_match: package.metadata.test_session_id === test_session_id,
+  has_source_context: package.source_context.implementation_summaries.length > 0,
+  framework_detected: package.test_framework.framework !== "unknown",
+  coverage_analyzed: package.test_coverage.coverage_stats !== null
+};
+
+if (!validation.all_passed()) {
+  console.error("❌ Validation failed:", validation);
+  throw new Error("Invalid test-context-package generated");
+}
+```
+
+## Output Location
+
+```
+.workflow/{test_session_id}/.process/test-context-package.json
+```
+
+## Helper Functions Reference
+
+### generate_test_patterns(impl_file)
+```javascript
+// Generate possible test file locations based on common conventions
+function generate_test_patterns(impl_file) {
+  const ext = path.extname(impl_file);
+  const base = path.basename(impl_file, ext);
+  const dir = path.dirname(impl_file);
+
+  return [
+    // Pattern 1: tests/ mirror structure
+    dir.replace('src', 'tests') + '/' + base + '.test' + ext,
+    // Pattern 2: __tests__ sibling
+    dir + '/__tests__/' + base + '.test' + ext,
+    // Pattern 3: .spec variant
+    dir.replace('src', 'tests') + '/' + base + '.spec' + ext,
+    // Pattern 4: Python test_ prefix
+    dir.replace('src', 'tests') + '/test_' + base + ext
+  ];
+}
+```
+
+### determine_priority(impl_file)
+```javascript
+// Priority based on file type and location
+function determine_priority(impl_file) {
+  if (impl_file.includes('/core/') || impl_file.includes('/auth/')) return 'high';
+  if (impl_file.includes('/utils/') || impl_file.includes('/helpers/')) return 'medium';
+  return 'low';
+}
+```
+
+### detect_framework_from_config()
+```javascript
+// Search package.json, requirements.txt, etc.
+function detect_framework_from_config() {
+  const configs = [
+    { file: 'package.json', patterns: ['jest', 'mocha', 'jasmine', 'vitest'] },
+    { file: 'requirements.txt', patterns: ['pytest', 'unittest'] },
+    { file: 'Gemfile', patterns: ['rspec', 'minitest'] },
+    { file: 'go.mod', patterns: ['testify'] }
+  ];
+
+  for (const config of configs) {
+    if (file_exists(config.file)) {
+      const content = Read(config.file);
+      for (const pattern of config.patterns) {
+        if (content.includes(pattern)) {
+          return extract_framework_info(content, pattern);
+        }
+      }
+    }
+  }
+
+  return { name: 'unknown', version: null };
+}
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Source session not found | Invalid source_session reference | Verify test session metadata |
+| No implementation summaries | Source session incomplete | Complete source session first |
+| No test framework detected | Missing test dependencies | Request user to specify framework |
+| Coverage analysis failed | File access issues | Check file permissions |
+
+## Execution Modes
+
+### Plan Mode (Default)
+- Full Phase 1-3 execution
+- Comprehensive coverage analysis
+- Complete framework detection
+- Generate full test-context-package.json
+
+### Quick Mode (Future)
+- Skip framework detection if already known
+- Analyze only new implementation files
+- Partial context package update
+
+## Success Criteria
+
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified
+- ✅ Test framework detected and documented
+- ✅ Valid test-context-package.json generated
+- ✅ All missing tests catalogued with priority
+- ✅ Execution time < 30 seconds (< 60s for large codebases)
+
+## Integration Points
+
+### Called By
+- `/workflow:tools:test-context-gather` - Orchestrator command
+
+### Calls
+- Code-Index MCP tools (preferred)
+- ripgrep/find (fallback)
+- Bash file operations
+
+### Followed By
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis
+
+## Notes
+
+- **Detection-first**: Always check for existing test-context-package before analysis
+- **Code-Index priority**: Use MCP tools when available, fallback to CLI
+- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, etc.
+- **Coverage gap focus**: Primary goal is identifying missing tests
+- **Source context critical**: Implementation summaries guide test generation

.claude/agents/test-fix-agent.md

@@ -68,6 +68,7 @@ When task JSON contains implementation_approach array:
 ### 1. Context Assessment & Test Discovery
 - Analyze task context to identify test files and source code paths
 - Load test framework configuration (Jest, Pytest, Mocha, etc.)
+- **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
 - Identify test command from project configuration
 
 ```bash
@@ -212,3 +213,5 @@ All tests pass - code is ready for deployment.
 **Your ultimate responsibility**: Ensure all tests pass. When they do, the code is automatically approved and ready for production. You are the final quality gate.
 
 **Tests passing = Code approved = Mission complete** ✅
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

.claude/agents/ui-design-agent.md

@@ -35,7 +35,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 ### 2. Layout Strategy Generation
 
 **Invoked by**: `consolidate.md` Phase 2.5
-**Input**: Project context from synthesis-specification.md
+**Input**: Project context from role analysis documents
 **Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends)
 
 **Output**: layout-strategies.json with strategy definitions and rationale

.claude/agents/universal-executor.md

@@ -1,5 +1,5 @@
 ---
-name: general-purpose
+name: universal-executor
 description: |
   Versatile execution agent for implementing any task efficiently. Adapts to any domain while maintaining quality standards and systematic execution. Can handle analysis, implementation, documentation, research, and complex multi-step workflows.
 

.claude/commands/cli/analyze.md

@@ -1,6 +1,6 @@
 ---
 name: analyze
-description: Quick codebase analysis using CLI tools (codex/gemini/qwen)
+description: Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection
 argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 ---
@@ -9,143 +9,128 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 
 ## Purpose
 
-Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
+Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 
-**Intent**: Understand code patterns, architecture, and provide insights/recommendations
-**Supported Tools**: codex, gemini (default), qwen
-
-## Core Behavior
-
-1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
-2. **No Code Modification**: Results are recommendations and analysis reports
-3. **Template-Based**: Automatically selects appropriate analysis template
-4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+**Tool Selection**:
+- **gemini** (default) - Best for code analysis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for deep analysis
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
 ## Execution Flow
 
-### Standard Mode (Default)
-
+### Standard Mode
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
-3. Auto-detect analysis type from keywords → select template
-4. Build command with auto-detected file patterns and `MODE: analysis`
-5. Execute analysis (read-only, no code changes)
-6. Return analysis report with insights and recommendations
+2. Optional: enhance with `/enhance-prompt`
+3. Auto-detect file patterns from keywords
+4. Build command with analysis template
+5. Execute analysis (read-only)
+6. Save results
 
-### Agent Mode (`--agent` flag)
+### Agent Mode (`--agent`)
 
-Delegate task to `cli-execution-agent` for intelligent execution with automated context discovery.
+Delegates to agent for intelligent analysis:
 
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Analyze codebase with automated context discovery",
+  description="Codebase analysis",
   prompt=`
     Task: ${analysis_target}
     Mode: analyze
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${enhance_flag ? 'Enhance: true' : ''}
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Enhance: ${enhance_flag || false}
 
-    Agent will autonomously:
-    - Discover relevant files and patterns
-    - Build enhanced analysis prompt
-    - Select optimal tool and execute
-    - Route output to session/scratchpad
+    Agent responsibilities:
+    1. Context Discovery:
+       - Discover relevant files/patterns
+       - Identify analysis scope
+       - Build file context
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Apply analysis template
+       - Include discovered files
+
+    3. Execution & Output:
+       - Execute analysis
+       - Generate insights report
+       - Save to .workflow/.chat/ or .scratchpad/
   `
 )
 ```
 
-The agent handles all phases internally (understanding, discovery, enhancement, execution, routing).
+## Core Rules
+
+- **Read-only**: Analyzes code, does NOT modify files
+- **Auto-pattern**: Detects file patterns from keywords
+- **Template-based**: Auto-selects analysis template
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
 
 ## File Pattern Auto-Detection
 
-Keywords trigger specific file patterns:
-- "auth" → `@{**/*auth*,**/*user*}`
-- "component" → `@{src/components/**/*,**/*.component.*}`
-- "API" → `@{**/api/**/*,**/routes/**/*}`
-- "test" → `@{**/*.test.*,**/*.spec.*}`
-- "config" → `@{*.config.*,**/config/**/*}`
-- Generic → `@{src/**/*}`
+Keywords → file patterns:
+- "auth" → `@**/*auth* @**/*user*`
+- "component" → `@src/components/**/*`
+- "API" → `@**/api/**/* @**/routes/**/*`
+- "test" → `@**/*.test.* @**/*.spec.*`
+- Generic → `@src/**/*`
 
-For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
-
-## Command Template
+## CLI Command Templates
 
+**Gemini/Qwen**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [analysis goal from target]
-TASK: [auto-detected analysis type]
+cd . && gemini -p "
+PURPOSE: [goal]
+TASK: [analysis type]
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
-EXPECTED: Insights, patterns, recommendations (NO code modification)
-RULES: [auto-selected template] | Focus on [analysis aspect]
+CONTEXT: @CLAUDE.md [auto-detected patterns]
+EXPECTED: Insights, recommendations
+RULES: [auto-selected template]
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Analysis (Standard Mode)**:
+**Codex**:
 ```bash
-/cli:analyze "authentication patterns"
-# Executes: Gemini analysis with auth file patterns
-# Returns: Pattern analysis, architecture insights, recommendations
+codex -C . --full-auto exec "
+PURPOSE: [goal]
+TASK: [analysis type]
+MODE: analysis
+CONTEXT: @CLAUDE.md [patterns]
+EXPECTED: Deep insights
+RULES: [template]
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Intelligent Analysis (Agent Mode)**:
-```bash
-/cli:analyze --agent "authentication patterns"
-# Phase 1: Classifies intent=analyze, complexity=simple, keywords=['auth', 'patterns']
-# Phase 2: MCP discovers 12 auth files, identifies patterns
-# Phase 3: Builds enhanced prompt with discovered context
-# Phase 4: Executes Gemini with comprehensive file references
-# Phase 5: Saves execution log with all 5 phases documented
-# Returns: Comprehensive analysis + detailed execution log
-```
+## Output
 
-**Architecture Analysis**:
-```bash
-/cli:analyze --tool qwen "component architecture"
-# Executes: Qwen with component file patterns
-# Returns: Architecture review, design patterns, improvement suggestions
-```
-
-**Performance Analysis**:
-```bash
-/cli:analyze --tool codex "performance bottlenecks"
-# Executes: Codex deep analysis with performance focus
-# Returns: Bottleneck identification, optimization recommendations
-```
-
-**Enhanced Analysis**:
-```bash
-/cli:analyze --enhance "fix auth issues"
-# Step 1: Enhance prompt to expand context
-# Step 2: Analysis with expanded context
-# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
-- **No active session OR one-off analysis**:
-  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
-- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/analyze-[desc]-[timestamp].md`
 
 ## Notes
 
-- Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Scratchpad files can be promoted to workflow sessions if analysis proves valuable
+- See `intelligent-tools-strategy.md` for detailed tool usage and templates

.claude/commands/cli/chat.md

@@ -1,6 +1,6 @@
 ---
 name: chat
-description: Simple CLI interaction command for direct codebase analysis
+description: Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference
 argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
@@ -9,148 +9,117 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
+Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does NOT modify code**.
 
-**Intent**: Ask questions, get explanations, understand codebase structure
-**Supported Tools**: codex, gemini (default), qwen
-
-## Core Behavior
-
-1. **Conversational Analysis**: Direct question-answer interaction about codebase
-2. **Read-Only**: This command ONLY provides information and analysis
-3. **No Code Modification**: Results are explanations and insights
-4. **Flexible Context**: Choose specific files or entire codebase
+**Tool Selection**:
+- **gemini** (default) - Best for Q&A and explanations
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for technical deep-dives
 
 ## Parameters
 
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance inquiry with `/enhance-prompt`
 - `<inquiry>` (Required) - Question or analysis request
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode)
-- `--enhance` - Enhance inquiry with `/enhance-prompt` first
-- `--all-files` - Include entire codebase in context
-- `--save-session` - Save interaction to workflow session
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-### Standard Mode (Default)
-
+### Standard Mode
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
-3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
-4. Execute CLI tool with assembled context (read-only, analysis mode)
-5. Return explanations and insights (NO code changes)
-6. Optionally save to workflow session
+2. Optional: enhance with `/enhance-prompt`
+3. Assemble context: `@CLAUDE.md` + inferred files
+4. Execute Q&A (read-only)
+5. Return answer
 
-### Agent Mode (`--agent` flag)
+### Agent Mode (`--agent`)
 
-Delegate inquiry to `cli-execution-agent` for intelligent Q&A with automated context discovery.
+Delegates to agent for intelligent Q&A:
 
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Answer question with automated context discovery",
+  description="Codebase Q&A",
   prompt=`
     Task: ${inquiry}
-    Mode: analyze (Q&A)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${all_files_flag ? 'Scope: all-files' : ''}
+    Mode: chat (Q&A)
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Enhance: ${enhance_flag || false}
 
-    Agent will autonomously:
-    - Discover files relevant to the question
-    - Build Q&A prompt with precise context
-    - Execute and generate comprehensive answer
-    - Save conversation log
+    Agent responsibilities:
+    1. Context Discovery:
+       - Discover files relevant to question
+       - Identify key code sections
+       - Build precise context
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include discovered context
+       - Apply Q&A template
+
+    3. Execution & Output:
+       - Execute Q&A analysis
+       - Generate detailed answer
+       - Save to .workflow/.chat/ or .scratchpad/
   `
 )
 ```
 
-The agent handles all phases internally.
+## Core Rules
 
-## Context Assembly
+- **Read-only**: Provides answers, does NOT modify code
+- **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
 
-**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
-
-**Optional**:
-- User-explicit files from inquiry keywords
-- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
-
-For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
-
-## Command Template
+## CLI Command Templates
 
+**Gemini/Qwen**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-INQUIRY: [user question]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+cd . && gemini -p "
+PURPOSE: Answer question
+TASK: [inquiry]
 MODE: analysis
-RESPONSE: Direct answer, explanation, insights (NO code modification)
+CONTEXT: @CLAUDE.md [inferred or @**/*]
+EXPECTED: Clear answer
+RULES: Focus on accuracy
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Question (Standard Mode)**:
+**Codex**:
 ```bash
-/cli:chat "analyze the authentication flow"
-# Executes: Gemini analysis
-# Returns: Explanation of auth flow, components involved, data flow
+codex -C . --full-auto exec "
+PURPOSE: Answer question
+TASK: [inquiry]
+MODE: analysis
+CONTEXT: @CLAUDE.md [inferred or @**/*]
+EXPECTED: Detailed answer
+RULES: Technical depth
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Intelligent Q&A (Agent Mode)**:
-```bash
-/cli:chat --agent "how does JWT token refresh work in this codebase"
-# Phase 1: Understands inquiry = JWT refresh mechanism
-# Phase 2: Discovers JWT files, refresh logic, middleware patterns
-# Phase 3: Builds Q&A prompt with discovered implementation details
-# Phase 4: Executes Gemini with precise context for accurate answer
-# Phase 5: Saves conversation log with discovered context
-# Returns: Detailed answer with code references + execution log
-```
+## Output
 
-**Architecture Question**:
-```bash
-/cli:chat --tool qwen "how does React component optimization work here"
-# Executes: Qwen architecture analysis
-# Returns: Component structure explanation, optimization patterns used
-```
-
-**Security Analysis**:
-```bash
-/cli:chat --tool codex "review security vulnerabilities"
-# Executes: Codex security analysis
-# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
-```
-
-**Enhanced Inquiry**:
-```bash
-/cli:chat --enhance "explain the login issue"
-# Step 1: Enhance to expand login context
-# Step 2: Analysis with expanded understanding
-# Returns: Detailed explanation of login flow and potential issues
-```
-
-**Broad Context**:
-```bash
-/cli:chat --all-files "find all API endpoints"
-# Executes: Analysis across entire codebase
-# Returns: List and explanation of API endpoints (NO code generation)
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND query is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No active session OR unrelated query**:
-  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
-- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/chat-[desc]-[timestamp].md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Scratchpad conversations preserved for future reference
+- See `intelligent-tools-strategy.md` for detailed tool usage and templates

.claude/commands/cli/cli-init.md

@@ -1,6 +1,6 @@
 ---
 name: cli-init
-description: Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis
+description: Generate .gemini/ and .qwen/ config directories with settings.json and ignore files based on workspace technology detection
 argument-hint: "[--tool gemini|qwen|all] [--output path] [--preview]"
 allowed-tools: Bash(*), Read(*), Write(*), Glob(*)
 ---
@@ -32,7 +32,7 @@ Creates tool-specific configuration directories:
 - `.gemini/settings.json`:
 ```json
 {
-  "contextfilename": "CLAUDE.md"
+  "contextfilename": ["CLAUDE.md","GEMINI.md"]
 }
 ```
 
@@ -40,7 +40,7 @@ Creates tool-specific configuration directories:
 - `.qwen/settings.json`:
 ```json
 {
-  "contextfilename": "CLAUDE.md"
+  "contextfilename": ["CLAUDE.md","QWEN.md"]
 }
 ```
 
@@ -178,7 +178,7 @@ target/
 /cli:cli-init --tool all --output=.config/
 ```
 
-## EXECUTION INSTRUCTIONS ⚡ START HERE
+## EXECUTION INSTRUCTIONS - START HERE
 
 **When this command is triggered, follow these exact steps:**
 
@@ -209,7 +209,7 @@ bash(find . -name "Dockerfile" | head -1)
 ```bash
 # Create .gemini/ directory and settings.json
 mkdir -p .gemini
-echo '{"contextfilename": "CLAUDE.md"}' > .gemini/settings.json
+Write({file_path: '.gemini/settings.json', content: '{"contextfilename": "CLAUDE.md"}'})
 
 # Create .geminiignore file with detected technology rules
 # Backup existing files if present
@@ -219,7 +219,7 @@ echo '{"contextfilename": "CLAUDE.md"}' > .gemini/settings.json
 ```bash
 # Create .qwen/ directory and settings.json
 mkdir -p .qwen
-echo '{"contextfilename": "CLAUDE.md"}' > .qwen/settings.json
+Write({file_path: '.qwen/settings.json', content: '{"contextfilename": "CLAUDE.md"}'})
 
 # Create .qwenignore file with detected technology rules
 # Backup existing files if present

.claude/commands/cli/codex-execute.md

@@ -1,6 +1,6 @@
 ---
 name: codex-execute
-description: Automated task decomposition and execution with Codex using resume mechanism
+description: Multi-stage Codex execution with automatic task decomposition into grouped subtasks using resume mechanism for context continuity
 argument-hint: "[--verify-git] task description or task-id"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
@@ -130,7 +130,7 @@ git status --short
 codex -C [dir] --full-auto exec "
 PURPOSE: [group goal]
 TASK: [subtask description - first in group]
-CONTEXT: @{relevant_files} @{CLAUDE.md}
+CONTEXT: @{relevant_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [X]: [group name] - Subtask 1 of N in this group
@@ -164,7 +164,7 @@ git add -A
 codex -C [dir] --full-auto exec "
 PURPOSE: [new group goal]
 TASK: [subtask description - first in new group]
-CONTEXT: @{different_files} @{CLAUDE.md}
+CONTEXT: @{different_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [Y]: [new group name] - Subtask 1 of N in this group
@@ -257,12 +257,12 @@ TodoWrite({
 
 **When to Resume vs New Session**:
 ```
-✅ RESUME (same group):
+RESUME (same group):
   - Subtasks share files/modules
   - Logical continuation of previous work
   - Same architectural domain
 
-❌ NEW SESSION (different group):
+NEW SESSION (different group):
   - Independent task area
   - Different files/modules
   - Switching architectural domains
@@ -318,7 +318,7 @@ AskUserQuestion({
 
 **During Execution**:
 ```
-📊 Task Flow Diagram:
+Task Flow Diagram:
 [Group A: Auth Core]
   A1: Create user model ──┐
   A2: Add validation     ─┤─► [resume] ─► A3: Database schema
@@ -331,7 +331,7 @@ AskUserQuestion({
   C1: Unit tests ─────────────► [new session]
   C2: Integration tests ──────► [resume]
 
-📋 Task Decomposition:
+Task Decomposition:
   [Group A] 1. Create user model
   [Group A] 2. Add validation logic [resume]
   [Group A] 3. Implement database schema [resume]
@@ -341,28 +341,28 @@ AskUserQuestion({
   [Group C] 7. Unit tests [new session]
   [Group C] 8. Integration tests [resume]
 
-▶️  [Group A] Executing Subtask 1/8: Create user model
+[Group A] Executing Subtask 1/8: Create user model
   Starting new Codex session for Group A...
   [Codex output]
-  ✅ Subtask 1 completed
+  Subtask 1 completed
 
-🔍 Git Verification:
+Git Verification:
   M  src/models/user.ts
-  ✅ Changes verified
+  Changes verified
 
-▶️  [Group A] Executing Subtask 2/8: Add validation logic
+[Group A] Executing Subtask 2/8: Add validation logic
   Resuming Codex session (same group)...
   [Codex output]
-  ✅ Subtask 2 completed
+  Subtask 2 completed
 
-▶️  [Group B] Executing Subtask 4/8: Create auth endpoints
+[Group B] Executing Subtask 4/8: Create auth endpoints
   Starting NEW Codex session for Group B...
   [Codex output]
-  ✅ Subtask 4 completed
+  Subtask 4 completed
 ...
 
-✅ All Subtasks Completed
-📊 Summary: [file references, changes, next steps]
+All Subtasks Completed
+Summary: [file references, changes, next steps]
 ```
 
 **Final Summary**:
@@ -370,8 +370,8 @@ AskUserQuestion({
 # Task Execution Summary: [Task Description]
 
 ## Subtasks Completed
-1. ✅ [Subtask 1]: [files modified]
-2. ✅ [Subtask 2]: [files modified]
+1. [Subtask 1]: [files modified]
+2. [Subtask 2]: [files modified]
 ...
 
 ## Files Modified
@@ -515,6 +515,5 @@ AskUserQuestion({
 **Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
 
 **Output Details**:
-- Output routing and scratchpad details: see workflow-architecture.md
 - Session management: see intelligent-tools-strategy.md
 - **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

.claude/commands/cli/discuss-plan.md

@@ -1,6 +1,6 @@
 ---
 name: discuss-plan
-description: Orchestrates an iterative, multi-model discussion for planning and analysis without implementation.
+description: Multi-round collaborative planning using Gemini, Codex, and Claude synthesis with iterative discussion cycles (read-only, no code changes)
 argument-hint: "[--topic '...'] [--task-id '...'] [--rounds N]"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
@@ -69,11 +69,11 @@ Gemini analyzes the topic and proposes preliminary plan.
 ```bash
 # Round 1: CONTEXT_INPUT is the initial topic
 # Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round
-~/.claude/scripts/gemini-wrapper -p "
+gemini -p "
 PURPOSE: Analyze and propose a plan for '[topic]'
 TASK: Provide initial analysis, identify key modules, and draft implementation plan
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 INPUT: [CONTEXT_INPUT]
 EXPECTED: Structured analysis and draft plan for discussion
 RULES: Focus on technical depth and practical considerations
@@ -90,7 +90,7 @@ codex --full-auto exec "
 PURPOSE: Critically review technical plan
 TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [relevant files]
+CONTEXT: @CLAUDE.md [relevant files]
 INPUT_PLAN: [Output from Gemini's analysis]
 EXPECTED: Critical review with alternative ideas and risk analysis
 RULES: Focus on architectural soundness and implementation feasibility
@@ -279,11 +279,11 @@ Each round's output is structured as:
 
 | Command | Models | Rounds | Discussion | Implementation | Use Case |
 |---------|--------|--------|------------|----------------|----------|
-| `/cli:mode:plan` | Gemini | 1 | ❌ NO | ❌ NO | Single-model planning |
-| `/cli:analyze` | Gemini/Qwen | 1 | ❌ NO | ❌ NO | Code analysis |
-| `/cli:execute` | Any | 1 | ❌ NO | ✅ YES | Direct implementation |
-| `/cli:codex-execute` | Codex | 1 | ❌ NO | ✅ YES | Multi-stage implementation |
-| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | ✅ **YES** | ❌ **NO** | **Multi-perspective planning** |
+| `/cli:mode:plan` | Gemini | 1 | NO | NO | Single-model planning |
+| `/cli:analyze` | Gemini/Qwen | 1 | NO | NO | Code analysis |
+| `/cli:execute` | Any | 1 | NO | YES | Direct implementation |
+| `/cli:codex-execute` | Codex | 1 | NO | YES | Multi-stage implementation |
+| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | **YES** | **NO** | **Multi-perspective planning** |
 
 ## Best Practices
 
@@ -317,5 +317,4 @@ Each round's output is structured as:
 -   **Priority System**: Ensures Gemini leads analysis, Codex provides critique, Claude synthesizes
 -   **Output Quality**: Multi-perspective discussion produces more robust plans than single-model analysis
 -   Command patterns and session management: see intelligent-tools-strategy.md (loaded in memory)
--   Output routing details: see workflow-architecture.md
 -   For implementation after discussion, use `/cli:execute` or `/cli:codex-execute` separately

.claude/commands/cli/execute.md

@@ -1,6 +1,6 @@
 ---
 name: execute
-description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
+description: Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection
 argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
@@ -27,7 +27,7 @@ Execute implementation tasks with **YOLO permissions** (auto-approves all confir
 ### YOLO Permissions
 Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**⚠️ WARNING**: This command will make actual code changes without manual confirmation
+**WARNING**: This command will make actual code changes without manual confirmation
 
 ### Execution Modes
 
@@ -45,11 +45,11 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar
 
 ### Context Inference
 
-Auto-selects files based on keywords and technology:
-- "auth" → `@{**/*auth*,**/*user*}`
-- "React" → `@{src/**/*.{jsx,tsx}}`
-- "api" → `@{**/api/**/*,**/routes/**/*}`
-- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
+Auto-selects files based on keywords and technology (each @ references one pattern):
+- "auth" → `@**/*auth* @**/*user*`
+- "React" → `@src/**/*.jsx @src/**/*.tsx`
+- "api" → `@**/api/**/* @**/routes/**/*`
+- Always includes: `@CLAUDE.md @**/*CLAUDE.md`
 
 For precise file targeting, use `rg` or MCP tools to discover files first.
 
@@ -111,11 +111,11 @@ Use `resume --last` when current task extends/relates to previous execution. See
 ### Standard Mode (Default)
 ```bash
 # Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+cd . && gemini --approval-mode yolo "
 PURPOSE: [implementation goal]
 TASK: [specific implementation]
 MODE: write
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 EXPECTED: Working implementation with code changes
 RULES: [constraints] | Auto-approve all changes
 "
@@ -158,14 +158,14 @@ The agent handles all phases internally, including complexity-based tool selecti
 
 ## Examples
 
-**Basic Implementation (Standard Mode)** (⚠️ modifies code):
+**Basic Implementation (Standard Mode)** (modifies code):
 ```bash
 /cli:execute "implement JWT authentication with middleware"
 # Executes: Creates auth middleware, updates routes, modifies config
 # Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Intelligent Implementation (Agent Mode)** (⚠️ modifies code):
+**Intelligent Implementation (Agent Mode)** (modifies code):
 ```bash
 /cli:execute --agent "implement OAuth2 authentication with token refresh"
 # Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
@@ -176,7 +176,7 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Complete OAuth2 implementation + detailed execution log
 ```
 
-**Enhanced Implementation** (⚠️ modifies code):
+**Enhanced Implementation** (modifies code):
 ```bash
 /cli:execute --enhance "implement JWT authentication"
 # Step 1: Enhance to expand requirements
@@ -184,7 +184,7 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Complete auth system with MODIFIED code files
 ```
 
-**Task Execution** (⚠️ modifies code):
+**Task Execution** (modifies code):
 ```bash
 /cli:execute IMPL-001
 # Reads: .task/IMPL-001.json for requirements
@@ -192,14 +192,14 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Code changes per task definition
 ```
 
-**Codex Implementation** (⚠️ modifies code):
+**Codex Implementation** (modifies code):
 ```bash
 /cli:execute --tool codex "optimize database queries"
 # Executes: Codex with full file access
 # Result: MODIFIED query code, new indexes, updated tests
 ```
 
-**Qwen Code Generation** (⚠️ modifies code):
+**Qwen Code Generation** (modifies code):
 ```bash
 /cli:execute --tool qwen --enhance "refactor auth module"
 # Step 1: Enhanced refactoring plan
@@ -211,12 +211,11 @@ The agent handles all phases internally, including complexity-based tool selecti
 
 | Command | Intent | Code Changes | Auto-Approve |
 |---------|--------|--------------|--------------|
-| `/cli:analyze` | Understand code | ❌ NO | N/A |
-| `/cli:chat` | Ask questions | ❌ NO | N/A |
-| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
+| `/cli:analyze` | Understand code | NO | N/A |
+| `/cli:chat` | Ask questions | NO | N/A |
+| `/cli:execute` | **Implement** | **YES** | **YES** |
 
 ## Notes
 
 - Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
-- Output routing and scratchpad details: see workflow-architecture.md
-- **⚠️ Code Modification**: This command modifies code - execution logs document changes made
+- **Code Modification**: This command modifies code - execution logs document changes made

.claude/commands/cli/mode/bug-diagnosis.md

@@ -0,0 +1,130 @@
+---
+name: bug-diagnosis
+description: Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
+---
+
+# CLI Mode: Bug Diagnosis (/cli:mode:bug-diagnosis)
+
+## Purpose
+
+Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for bug diagnosis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex bug analysis
+
+## Parameters
+
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance bug description with `/enhance-prompt`
+- `--cd "path"` - Target directory for focused diagnosis
+- `<bug-description>` (Required) - Bug description or error details
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+# Uses gemini by default, or specify explicitly
+--tool gemini
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
+## Execution Flow
+
+### Standard Mode
+1. Parse tool selection (default: gemini)
+2. Optional: enhance with `/enhance-prompt`
+3. Detect directory from `--cd` or auto-infer
+4. Build command with template
+5. Execute diagnosis (read-only)
+6. Save to `.workflow/WFS-[id]/.chat/`
+
+### Agent Mode (`--agent`)
+
+Delegates to agent for intelligent diagnosis:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Bug root cause diagnosis",
+  prompt=`
+    Task: ${bug_description}
+    Mode: bug-diagnosis
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
+
+    Agent responsibilities:
+    1. Context Discovery:
+       - Locate error traces and logs
+       - Find related code sections
+       - Identify data flow paths
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include diagnostic context
+       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt template
+
+    3. Execution & Output:
+       - Execute root cause analysis
+       - Generate fix suggestions
+       - Save to .workflow/.chat/
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Diagnoses bugs, does NOT modify code
+- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` for root cause analysis
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
+
+## CLI Command Templates
+
+**Gemini/Qwen** (default, diagnosis only):
+```bash
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Root cause analysis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Diagnosis, fix plan
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
+"
+# Qwen: Replace 'gemini' with 'qwen'
+```
+
+**Codex** (diagnosis + potential fixes):
+```bash
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Bug diagnosis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Diagnosis, fix suggestions
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+## Output
+
+- **With session**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/bug-diagnosis-[desc]-[timestamp].md`
+
+## Notes
+
+- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

.claude/commands/cli/mode/bug-index.md

@@ -1,164 +0,0 @@
----
-name: bug-index
-description: Bug analysis and fix suggestions using CLI tools
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
-allowed-tools: SlashCommand(*), Bash(*), Task(*)
----
-
-# CLI Mode: Bug Index (/cli:mode:bug-index)
-
-## Purpose
-
-Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bug-fix.md`).
-
-**Supported Tools**: codex, gemini (default), qwen
-**Key Feature**: `--cd` flag for directory-scoped analysis
-
-## Parameters
-
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
-- `--enhance` - Enhance bug description with `/enhance-prompt` first
-- `--cd "path"` - Target directory for focused analysis
-- `<bug-description>` (Required) - Bug description or error message
-
-## Execution Flow
-
-### Standard Mode (Default)
-
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[bug-description]"` first
-3. Parse bug description (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with bug-fix template
-6. Execute analysis (read-only, provides fix recommendations)
-7. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
-
-### Agent Mode (`--agent` flag)
-
-Delegate bug analysis to `cli-execution-agent` for intelligent debugging with automated context discovery.
-
-**Agent invocation**:
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Analyze bug with automated context discovery",
-  prompt=`
-    Task: ${bug_description}
-    Mode: debug (bug analysis)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
-    Template: bug-fix
-
-    Agent will autonomously:
-    - Discover bug-related files and error traces
-    - Build debug prompt with bug-fix template
-    - Execute analysis and provide fix recommendations
-    - Save analysis log
-  `
-)
-```
-
-The agent handles all phases internally.
-
-## Core Rules
-
-1. **Analysis Only**: This command analyzes bugs and suggests fixes - it does NOT modify code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use bug-fix template
-5. **Session Output**: Save analysis results and fix recommendations to session chat
-
-## Analysis Focus (via Template)
-
-- Root cause investigation and diagnosis
-- Code path tracing to locate issues
-- Targeted minimal fix recommendations
-- Impact assessment of proposed changes
-
-## Command Template
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [bug analysis goal]
-TASK: Systematic bug analysis and fix recommendations
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
-"
-```
-
-## Examples
-
-**Basic Bug Analysis (Standard Mode)**:
-```bash
-/cli:mode:bug-index "null pointer error in login flow"
-# Executes: Gemini with bug-fix template
-# Returns: Root cause analysis, fix recommendations
-```
-
-**Intelligent Bug Analysis (Agent Mode)**:
-```bash
-/cli:mode:bug-index --agent "intermittent token validation failure"
-# Phase 1: Classifies as debug task, extracts keywords ['token', 'validation', 'failure']
-# Phase 2: MCP discovers token validation code, middleware, test files with errors
-# Phase 3: Builds debug prompt with bug-fix template + discovered error patterns
-# Phase 4: Executes Gemini with comprehensive bug context
-# Phase 5: Saves analysis log with detailed fix recommendations
-# Returns: Root cause analysis + code path traces + minimal fix suggestions
-```
-
-**Standard Template Example**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Debug authentication null pointer error
-TASK: Identify root cause and provide fix recommendations
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
-"
-```
-
-**Directory-Specific**:
-```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Fix token validation failure
-TASK: Analyze token validation bug in auth module
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation logic analysis, fix recommendation with minimal changes
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
-"
-```
-
-## Bug Investigation Workflow
-
-```bash
-# 1. Find bug-related files
-rg "error_keyword" --files-with-matches
-mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")
-
-# 2. Execute bug analysis with focused context (analysis only, no code changes)
-/cli:mode:bug-index --cd "src/module" "specific error description"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND bug is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
-- **No active session OR quick debugging**:
-  - Save to `.workflow/.scratchpad/bug-index-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-payment-fix`, analyzing payment bug → `.chat/bug-index-20250105-143022.md`
-- No session, quick null pointer investigation → `.scratchpad/bug-index-null-pointer-20250105-143045.md`
-
-## Notes
-
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Template path: `~/.claude/prompt-templates/bug-fix.md`
-- Always uses `--all-files` for comprehensive codebase context

.claude/commands/cli/mode/code-analysis.md

@@ -1,6 +1,6 @@
 ---
 name: code-analysis
-description: Deep code analysis and debugging using CLI tools with specialized template
+description: Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization
 argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
@@ -9,162 +9,129 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`).
+Systematic code analysis with execution path tracing template (`~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for code analysis and tracing
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex analysis tasks
 
-**Supported Tools**: codex, gemini (default), qwen
 **Key Feature**: `--cd` flag for directory-scoped analysis
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+/cli:mode:code-analysis --tool gemini "trace auth flow"
+# OR (default)
+/cli:mode:code-analysis "trace auth flow"
+```
+
+**Qwen** (Fallback):
+```bash
+/cli:mode:code-analysis --tool qwen "trace auth flow"
+```
+
+**Codex** (Alternative):
+```bash
+/cli:mode:code-analysis --tool codex "trace auth flow"
+```
+
 ## Execution Flow
 
 ### Standard Mode (Default)
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first
-3. Parse analysis target (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with code-analysis template
-6. Execute deep analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+1. Parse tool selection (default: gemini)
+2. Optional: enhance analysis target with `/enhance-prompt`
+3. Detect target directory from `--cd` or auto-infer
+4. Build command with template
+5. Execute analysis (read-only)
+6. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
 
 ### Agent Mode (`--agent` flag)
 
-Delegate code analysis to `cli-execution-agent` for intelligent execution path tracing with automated context discovery.
+Delegates to `cli-execution-agent` for intelligent context discovery and analysis.
+
+## Core Rules
+
+- **Read-only**: Analyzes code, does NOT modify files
+- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt` for systematic analysis
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
+
+## CLI Command Templates
+
+**Gemini/Qwen** (default, read-only analysis):
+```bash
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Execution path tracing
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Trace, call diagram
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
+"
+# Qwen: Replace 'gemini' with 'qwen'
+```
+
+**Codex** (analysis + optimization suggestions):
+```bash
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Path analysis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Trace, optimization
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+## Agent Execution Context
+
+When `--agent` flag is used, delegate to agent:
 
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Analyze code execution paths with automated context discovery",
+  description="Code execution path analysis",
   prompt=`
     Task: ${analysis_target}
-    Mode: code-analysis (execution tracing)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
-    Template: code-analysis
+    Mode: code-analysis
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt
 
-    Agent will autonomously:
-    - Discover execution paths and call flows
-    - Build analysis prompt with code-analysis template
-    - Execute deep tracing analysis
-    - Generate call diagrams and save log
+    Agent responsibilities:
+    1. Context Discovery:
+       - Identify entry points and call chains
+       - Discover related files (MCP/ripgrep)
+       - Map execution flow paths
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include discovered context
+       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt template
+
+    3. Execution & Output:
+       - Execute analysis with selected tool
+       - Save to .workflow/WFS-[id]/.chat/
   `
 )
 ```
 
-The agent handles all phases internally.
+## Output
 
-## Core Rules
-
-1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
-2. **Tool Selection**: Use `--tool` value or default to gemini
-3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-5. **Template Required**: Always use code-analysis template
-6. **Session Output**: Save analysis results to session chat
-
-## Analysis Capabilities (via Template)
-
-- **Systematic Code Analysis**: Break down complex code into manageable parts
-- **Execution Path Tracing**: Track variable states and call stacks
-- **Control & Data Flow**: Understand code logic and data transformations
-- **Call Flow Visualization**: Diagram function calling sequences
-- **Logical Reasoning**: Explain "why" behind code behavior
-- **Debugging Insights**: Identify potential bugs or inefficiencies
-
-## Command Template
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [analysis goal]
-TASK: Systematic code analysis and execution path tracing
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Execution trace, call flow diagram, debugging insights
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
-"
-```
-
-## Examples
-
-**Basic Code Analysis (Standard Mode)**:
-```bash
-/cli:mode:code-analysis "trace authentication execution flow"
-# Executes: Gemini with code-analysis template
-# Returns: Execution trace, call diagram, debugging insights
-```
-
-**Intelligent Code Analysis (Agent Mode)**:
-```bash
-/cli:mode:code-analysis --agent "trace JWT token validation from request to database"
-# Phase 1: Classifies as deep analysis, keywords ['jwt', 'token', 'validation', 'database']
-# Phase 2: MCP discovers request handler → middleware → service → repository chain
-# Phase 3: Builds analysis prompt with code-analysis template + complete call path
-# Phase 4: Executes Gemini with traced execution paths
-# Phase 5: Saves detailed analysis with call flow diagrams and variable states
-# Returns: Complete execution trace + call diagram + data flow analysis
-```
-
-**Standard Template Example**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Trace authentication execution flow
-TASK: Analyze complete auth flow from request to response
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Step-by-step execution trace with call diagram, variable states
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
-"
-```
-
-**Directory-Specific Analysis**:
-```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Understand JWT token validation logic
-TASK: Trace JWT validation from middleware to service layer
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation flow diagram, token lifecycle analysis
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
-"
-```
-
-## Code Tracing Workflow
-
-```bash
-# 1. Find entry points and related files
-rg "function.*authenticate|class.*AuthService" --files-with-matches
-mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts")
-
-# 2. Build call graph understanding
-# entry → middleware → service → repository
-
-# 3. Execute deep analysis (analysis only, no code changes)
-/cli:mode:code-analysis --cd "src" "trace execution from entry point"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-- **No active session OR standalone analysis**:
-  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
-- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/code-analysis-[desc]-[timestamp].md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Template path: `~/.claude/prompt-templates/code-analysis.md`
-- Always uses `--all-files` for comprehensive code context
+- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

.claude/commands/cli/mode/plan.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Project planning and architecture analysis using CLI tools
+description: Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis
 argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
@@ -9,160 +9,121 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`).
+Strategic software architecture planning template (`~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`).
 
-**Supported Tools**: codex, gemini (default), qwen
-**Key Feature**: `--cd` flag for directory-scoped planning
+**Tool Selection**:
+- **gemini** (default) - Best for architecture planning
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for implementation planning
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
-- `--enhance` - Enhance topic with `/enhance-prompt` first
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance task with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused planning
-- `<topic>` (Required) - Planning topic or architectural question
+- `<planning-task>` (Required) - Architecture planning task or modification requirements
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-### Standard Mode (Default)
+### Standard Mode
+1. Parse tool selection (default: gemini)
+2. Optional: enhance with `/enhance-prompt`
+3. Detect directory from `--cd` or auto-infer
+4. Build command with template
+5. Execute planning (read-only, no code generation)
+6. Save to `.workflow/WFS-[id]/.chat/`
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[topic]"` first
-3. Parse topic (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with planning template
-6. Execute analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+### Agent Mode (`--agent`)
 
-### Agent Mode (`--agent` flag)
+Delegates to agent for intelligent planning:
 
-Delegate planning to `cli-execution-agent` for intelligent strategic planning with automated architecture discovery.
-
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Create strategic plan with automated architecture discovery",
+  description="Architecture modification planning",
   prompt=`
-    Task: ${planning_topic}
-    Mode: plan (strategic planning)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
-    Template: plan
+    Task: ${planning_task}
+    Mode: architecture-planning
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt
 
-    Agent will autonomously:
-    - Discover project structure and existing architecture
-    - Build planning prompt with plan template
-    - Execute strategic planning analysis
-    - Generate implementation roadmap and save
+    Agent responsibilities:
+    1. Context Discovery:
+       - Analyze current architecture
+       - Identify affected components
+       - Map dependencies and impacts
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include architecture context
+       - Apply ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt template
+
+    3. Execution & Output:
+       - Execute strategic planning
+       - Generate modification plan
+       - Save to .workflow/.chat/
   `
 )
 ```
 
-The agent handles all phases internally.
-
 ## Core Rules
 
-1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use planning template
-5. **Session Output**: Save analysis results to session chat
+- **Planning only**: Creates modification plans, does NOT generate code
+- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt` for strategic planning
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
 
-## Planning Capabilities (via Template)
-
-- Strategic architecture insights and recommendations
-- Implementation roadmaps and suggestions
-- Key technical decisions analysis
-- Risk assessment
-- Resource planning
-
-## Command Template
+## CLI Command Templates
 
+**Gemini/Qwen** (default, planning only):
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [planning goal from topic]
-TASK: Comprehensive planning and architecture analysis
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Architecture planning
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Strategic insights, implementation recommendations, key decisions
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
+CONTEXT: @**/*
+EXPECTED: Modification plan, impact analysis
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Planning Analysis (Standard Mode)**:
+**Codex** (planning + implementation guidance):
 ```bash
-/cli:mode:plan "design user dashboard architecture"
-# Executes: Gemini with planning template
-# Returns: Architecture recommendations, component design, roadmap
-```
-
-**Intelligent Planning (Agent Mode)**:
-```bash
-/cli:mode:plan --agent "design microservices architecture for payment system"
-# Phase 1: Classifies as architectural planning, keywords ['microservices', 'payment', 'architecture']
-# Phase 2: MCP discovers existing services, payment flows, integration patterns
-# Phase 3: Builds planning prompt with plan template + current architecture context
-# Phase 4: Executes Gemini with comprehensive project understanding
-# Phase 5: Saves planning document with implementation roadmap and migration strategy
-# Returns: Strategic architecture plan + implementation roadmap + risk assessment
-```
-
-**Standard Template Example**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Design user dashboard architecture
-TASK: Plan dashboard component structure and data flow
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Architecture planning
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Architecture recommendations, component design, data flow diagram
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
-"
+CONTEXT: @**/*
+EXPECTED: Plan, implementation roadmap
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Directory-Specific Planning**:
-```bash
-cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Plan API refactoring strategy
-TASK: Analyze current API structure and recommend improvements
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
-"
-```
+## Output
 
-## Planning Workflow
-
-```bash
-# 1. Discover project structure
-~/.claude/scripts/get_modules_by_depth.sh
-mcp__code-index__find_files(pattern="*.ts")
-
-# 2. Gather existing architecture info
-rg "architecture|design" --files-with-matches
-
-# 3. Execute planning analysis (analysis only, no code changes)
-/cli:mode:plan "topic for strategic planning"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND planning is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-- **No active session OR exploratory planning**:
-  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
-- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/plan-[desc]-[timestamp].md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Template path: `~/.claude/prompt-templates/plan.md`
-- Always uses `--all-files` for comprehensive project context
+- Template: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

.claude/commands/enhance-prompt.md

@@ -1,6 +1,6 @@
 ---
 name: enhance-prompt
-description: Context-aware prompt enhancement using session memory and codebase analysis
+description: Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection
 argument-hint: "user input to enhance"
 ---
 

.claude/commands/memory/load-skill-memory.md

@@ -0,0 +1,182 @@
+---
+name: load-skill-memory
+description: Activate SKILL package (auto-detect from paths/keywords or manual) and intelligently load documentation based on task intent keywords
+argument-hint: "[skill_name] \"task intent description\""
+allowed-tools: Bash(*), Read(*), Skill(*)
+---
+
+# Memory Load SKILL Command (/memory:load-skill-memory)
+
+## 1. Overview
+
+The `memory:load-skill-memory` command **activates SKILL package** (auto-detect from task or manual specification) and intelligently loads documentation based on user's task intent. The system automatically determines which documentation files to read based on the intent description.
+
+**Core Philosophy**:
+- **Flexible Activation**: Auto-detect skill from task description/paths, or user explicitly specifies
+- **Intent-Driven Loading**: System analyzes task intent to determine documentation scope
+- **Intelligent Selection**: Automatically chooses appropriate documentation level and modules
+- **Direct Context Loading**: Loads selected documentation into conversation memory
+
+**When to Use**:
+- Manually activate a known SKILL package for a specific task
+- Load SKILL context when system hasn't auto-triggered it
+- Force reload SKILL documentation with specific intent focus
+
+**Note**: Normal SKILL activation happens automatically via description triggers or path mentions (system extracts skill name from file paths for intelligent triggering). Use this command only when manual activation is needed.
+
+## 2. Parameters
+
+- `[skill_name]` (Optional): Name of SKILL package to activate
+  - If omitted: System auto-detects from task description or file paths
+  - If specified: Direct activation of named SKILL package
+  - Example: `my_project`, `api_service`
+  - Must match directory name under `.claude/skills/`
+
+- `"task intent description"` (Required): Description of what you want to do
+  - Used for both: auto-detection (if skill_name omitted) and documentation scope selection
+  - **Analysis tasks**: "分析builder pattern实现", "理解参数系统架构"
+  - **Modification tasks**: "修改workflow逻辑", "增强thermal template功能"
+  - **Learning tasks**: "学习接口设计模式", "了解测试框架使用"
+  - **With paths**: "修改D:\projects\my_project\src\auth.py的认证逻辑" (auto-extracts `my_project`)
+
+## 3. Execution Flow
+
+### Step 1: Determine SKILL Name (if not provided)
+
+**Auto-Detection Strategy** (when skill_name parameter is omitted):
+1. **Path Extraction**: Scan task description for file paths
+   - Extract potential project names from path segments
+   - Example: `"修改D:\projects\my_project\src\auth.py"` → extracts `my_project`
+2. **Keyword Matching**: Match task keywords against SKILL descriptions
+   - Search for project-specific terms, domain keywords
+3. **Validation**: Check if extracted name matches `.claude/skills/{skill_name}/`
+
+**Result**: Either uses provided skill_name or auto-detected name for activation
+
+### Step 2: Activate SKILL and Analyze Intent
+
+**Activate SKILL Package**:
+```javascript
+Skill(command: "${skill_name}")  // Uses provided or auto-detected name
+```
+
+**What Happens After Activation**:
+1. If SKILL exists in memory: System reads `.claude/skills/${skill_name}/SKILL.md`
+2. If SKILL not found in memory: Error - SKILL package doesn't exist
+3. SKILL description triggers are loaded into memory
+4. Progressive loading mechanism becomes available
+5. Documentation structure is now accessible
+
+**Intent Analysis**:
+Based on task intent description, system determines:
+- **Action type**: analyzing, modifying, learning
+- **Scope**: specific module, architecture overview, complete system
+- **Depth**: quick reference, detailed API, full documentation
+
+### Step 3: Intelligent Documentation Loading
+
+**Loading Strategy**:
+
+The system automatically selects documentation based on intent keywords:
+
+1. **Quick Understanding** ("了解", "快速理解", "什么是"):
+   - Load: Level 0 (README.md only, ~2K tokens)
+   - Use case: Quick overview of capabilities
+
+2. **Specific Module Analysis** ("分析XXX模块", "理解XXX实现"):
+   - Load: Module-specific README.md + API.md (~5K tokens)
+   - Use case: Deep dive into specific component
+
+3. **Architecture Review** ("架构", "设计模式", "整体结构"):
+   - Load: README.md + ARCHITECTURE.md (~10K tokens)
+   - Use case: System design understanding
+
+4. **Implementation/Modification** ("修改", "增强", "实现"):
+   - Load: Relevant module docs + EXAMPLES.md (~15K tokens)
+   - Use case: Code modification with examples
+
+5. **Comprehensive Learning** ("学习", "完整了解", "深入理解"):
+   - Load: Level 3 (All documentation, ~40K tokens)
+   - Use case: Complete system mastery
+
+**Documentation Loaded into Memory**:
+After loading, the selected documentation content is available in conversation memory for subsequent operations.
+
+## 4. Usage Examples
+
+### Example 1: Manual Specification
+
+**User Command**:
+```bash
+/memory:load-skill-memory my_project "修改认证模块增加OAuth支持"
+```
+
+**Execution**:
+```javascript
+// Step 1: Use provided skill_name
+skill_name = "my_project"  // Directly from parameter
+
+// Step 2: Activate SKILL
+Skill(command: "my_project")
+
+// Step 3: Intent Analysis
+Keywords: ["修改", "认证模块", "增加", "OAuth"]
+Action: modifying (implementation)
+Scope: auth module + examples
+
+// Load documentation based on intent
+Read(.workflow/docs/my_project/auth/README.md)
+Read(.workflow/docs/my_project/auth/API.md)
+Read(.workflow/docs/my_project/EXAMPLES.md)
+```
+
+### Example 2: Auto-Detection from Path
+
+**User Command**:
+```bash
+/memory:load-skill-memory "修改D:\projects\my_project\src\services\api.py的接口逻辑"
+```
+
+**Execution**:
+```javascript
+// Step 1: Auto-detect skill_name from path
+Path detected: "D:\projects\my_project\src\services\api.py"
+Extracted: "my_project"
+Validated: .claude/skills/my_project/ exists ✓
+skill_name = "my_project"
+
+// Step 2: Activate SKILL
+Skill(command: "my_project")
+
+// Step 3: Intent Analysis
+Keywords: ["修改", "services", "接口逻辑"]
+Action: modifying (implementation)
+Scope: services module + examples
+
+// Load documentation based on intent
+Read(.workflow/docs/my_project/services/README.md)
+Read(.workflow/docs/my_project/services/API.md)
+Read(.workflow/docs/my_project/EXAMPLES.md)
+```
+
+## 5. Intent Keyword Mapping
+
+**Quick Reference**:
+- **Triggers**: "了解", "快速", "什么是", "简介"
+- **Loads**: README.md only (~2K)
+
+**Module-Specific**:
+- **Triggers**: "XXX模块", "XXX组件", "分析XXX"
+- **Loads**: Module README + API (~5K)
+
+**Architecture**:
+- **Triggers**: "架构", "设计", "整体结构", "系统设计"
+- **Loads**: README + ARCHITECTURE (~10K)
+
+**Implementation**:
+- **Triggers**: "修改", "增强", "实现", "开发", "集成"
+- **Loads**: Relevant module + EXAMPLES (~15K)
+
+**Comprehensive**:
+- **Triggers**: "完整", "深入", "全面", "学习整个"
+- **Loads**: All documentation (~40K)

.claude/commands/memory/load.md

@@ -1,21 +1,21 @@
 ---
 name: load
-description: Load project memory by delegating to agent, returns structured core content package for subsequent operations
+description: Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context
 argument-hint: "[--tool gemini|qwen] \"task context description\""
 allowed-tools: Task(*), Bash(*)
 examples:
   - /memory:load "在当前前端基础上开发用户认证功能"
-  - /memory:load --tool qwen "重构支付模块API"
+  - /memory:load --tool qwen -p "重构支付模块API"
 ---
 
 # Memory Load Command (/memory:load)
 
 ## 1. Overview
 
-The `memory:load` command **delegates to a general-purpose agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
+The `memory:load` command **delegates to a universal-executor agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
 
 **Core Philosophy**:
-- **Agent-Driven**: Fully delegates execution to general-purpose agent
+- **Agent-Driven**: Fully delegates execution to universal-executor agent
 - **Read-Only Analysis**: Does not modify code, only extracts context
 - **Structured Output**: Returns standardized JSON content package
 - **Memory Optimization**: Package loaded directly into main thread memory
@@ -34,7 +34,7 @@ The `memory:load` command **delegates to a general-purpose agent** to analyze th
 
 ## 3. Agent-Driven Execution Flow
 
-The command fully delegates to **general-purpose agent**, which autonomously:
+The command fully delegates to **universal-executor agent**, which autonomously:
 
 1. **Analyzes Project Structure**: Executes `get_modules_by_depth.sh` to understand architecture
 2. **Loads Documentation**: Reads CLAUDE.md, README.md and other key docs
@@ -94,14 +94,14 @@ The command fully delegates to **general-purpose agent**, which autonomously:
 
 ```javascript
 Task(
-  subagent_type="general-purpose",
+  subagent_type="universal-executor",
   description="Load project memory: ${task_description}",
   prompt=`
 ## Mission: Load Project Memory Context
 
-**Task Context**: "${task_description}"
-**Mode**: Read-only analysis
-**Tool**: ${tool || 'gemini'}
+**Task**: Load project memory context for: "${task_description}"
+**Mode**: analysis
+**Tool Preference**: ${tool || 'gemini'}
 
 ## Execution Steps
 
@@ -121,14 +121,14 @@ Task(
 ### Step 2: Keyword Extraction & File Discovery
 
 1. Extract core keywords from task description
-2. Discover relevant files using MCP code-index or rg:
-   \`\`\`javascript
-   // Prefer MCP tools
-   mcp__code-index__find_files(pattern="*{keyword}*")
-   mcp__code-index__search_code_advanced(pattern="{keyword}", context_lines=2)
+2. Discover relevant files using ripgrep and find:
+   \`\`\`bash
+   # Find files by name
+   find . -name "*{keyword}*" -type f
 
-   // Fallback: use rg
-   bash(rg -l "{keyword}" --type ts --type md)
+   # Search content with ripgrep
+   rg "{keyword}" --type ts --type md -C 2
+   rg -l "{keyword}" --type ts --type md  # List files only
    \`\`\`
 
 ### Step 3: Deep Analysis via CLI
@@ -136,11 +136,11 @@ Task(
 Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens):
 
 \`\`\`bash
-cd . && ~/.claude/scripts/${tool}-wrapper -p "
+cd . && ${tool} -p "
 PURPOSE: Extract project core context for task: ${task_description}
 TASK: Analyze project architecture, tech stack, key patterns, relevant files
 MODE: analysis
-CONTEXT: @{CLAUDE.md,README.md,${discovered_files}}
+CONTEXT: @CLAUDE.md,README.md @${discovered_files}
 EXPECTED: Structured project summary and integration point analysis
 RULES:
 - Focus on task-relevant core information
@@ -212,7 +212,7 @@ Before returning:
 ### Example 2: Using Qwen Tool
 
 ```bash
-/memory:load --tool qwen "重构支付模块API"
+/memory:load --tool qwen -p "重构支付模块API"
 ```
 
 Agent uses Qwen CLI for analysis, returns same structured package.

.claude/commands/memory/skill-memory.md

@@ -0,0 +1,534 @@
+---
+name: skill-memory
+description: 4-phase autonomous orchestrator: check docs → /memory:docs planning → /workflow:execute → generate SKILL.md with progressive loading index (skips phases 2-3 if docs exist)
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Memory SKILL Package Generator
+
+## Orchestrator Role
+
+**Pure Orchestrator**: Execute documentation generation workflow, then generate SKILL.md index. Does NOT create task JSON files.
+
+**Auto-Continue Workflow**: This command runs **fully autonomously** once triggered. Each phase completes and automatically triggers the next phase without user interaction.
+
+**Execution Paths**:
+- **Full Path**: All 4 phases (no existing docs OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 4 (existing docs found AND no `--regenerate` flag)
+- **Phase 4 Always Executes**: SKILL.md index is never skipped, always generated or updated
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - delegates to /memory:docs
+3. **Parse Every Output**: Extract required data from each command output (session_id, task_count, file paths)
+4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool
+7. **No Manual Steps**: User should never be prompted for decisions between phases
+
+---
+
+## 4-Phase Execution
+
+### Phase 1: Prepare Arguments
+
+**Goal**: Parse command arguments and check existing documentation
+
+**Step 1: Get Target Path and Project Name**
+```bash
+# Get current directory (or use provided path)
+bash(pwd)
+
+# Get project name from directory
+bash(basename "$(pwd)")
+
+# Get project root
+bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+**Output**:
+- `target_path`: `/d/my_project`
+- `project_name`: `my_project`
+- `project_root`: `/d/my_project`
+
+**Step 2: Set Default Parameters**
+```bash
+# Default values (use these unless user specifies otherwise):
+# - tool: "gemini"
+# - mode: "full"
+# - regenerate: false (no --regenerate flag)
+# - cli_execute: false (no --cli-execute flag)
+```
+
+**Step 3: Check Existing Documentation**
+```bash
+# Check if docs directory exists
+bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists")
+
+# Count existing documentation files
+bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Output**:
+- `docs_exists`: `exists` or `not_exists`
+- `existing_docs`: `5` (or `0` if no docs)
+
+**Step 4: Determine Execution Path**
+
+**Decision Logic**:
+```javascript
+if (existing_docs > 0 && !regenerate_flag) {
+  // Documentation exists and no regenerate flag
+  SKIP_DOCS_GENERATION = true
+  message = "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  // Force regeneration: delete existing docs
+  bash(rm -rf .workflow/docs/my_project 2>/dev/null || true)
+  SKIP_DOCS_GENERATION = false
+  message = "Regenerating documentation from scratch."
+} else {
+  // No existing docs
+  SKIP_DOCS_GENERATION = false
+  message = "No existing documentation found, generating new documentation."
+}
+```
+
+**Summary Variables**:
+- `PROJECT_NAME`: `my_project`
+- `TARGET_PATH`: `/d/my_project`
+- `DOCS_PATH`: `.workflow/docs/my_project`
+- `TOOL`: `gemini` (default) or user-specified
+- `MODE`: `full` (default) or user-specified
+- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag
+- `REGENERATE`: `false` (default) or `true` if --regenerate flag
+- `EXISTING_DOCS`: Count of existing documentation files
+- `SKIP_DOCS_GENERATION`: `true` if skipping Phase 2/3, `false` otherwise
+
+**Completion & TodoWrite**:
+- If `SKIP_DOCS_GENERATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress
+- If `SKIP_DOCS_GENERATION = false`: Mark phase 1 completed, phase 2 in_progress
+
+**Next Action**:
+- If skipping: Display skip message → Jump to Phase 4 (SKILL.md generation)
+- If not skipping: Display preparation results → Continue to Phase 2 (documentation planning)
+
+---
+
+### Phase 2: Call /memory:docs
+
+**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
+
+**Goal**: Trigger documentation generation workflow
+
+**Command**:
+```bash
+SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]")
+```
+
+**Example**:
+```bash
+/memory:docs /d/my_app --tool gemini --mode full
+/memory:docs /d/my_app --tool gemini --mode full --cli-execute
+```
+
+**Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection.
+
+**Parse Output**:
+- Extract session ID: `WFS-docs-[timestamp]` (store as `docsSessionId`)
+- Extract task count (store as `taskCount`)
+
+**Completion Criteria**:
+- `/memory:docs` command executed successfully
+- Session ID extracted and stored
+- Task count retrieved
+- Task files created in `.workflow/[docsSessionId]/.task/`
+- workflow-session.json exists
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**Next Action**: Display docs planning results (session ID, task count) → Auto-continue to Phase 3
+
+---
+
+### Phase 3: Execute Documentation Generation
+
+**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
+
+**Goal**: Execute documentation generation tasks
+
+**Command**:
+```bash
+SlashCommand(command="/workflow:execute")
+```
+
+**Note**: `/workflow:execute` automatically discovers active session from Phase 2
+
+**Completion Criteria**:
+- `/workflow:execute` command executed successfully
+- Documentation files generated in `.workflow/docs/[projectName]/`
+- All tasks marked as completed in session
+- At minimum: module documentation files exist (API.md and/or README.md)
+- For full mode: Project README, ARCHITECTURE, EXAMPLES files generated
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+**Next Action**: Display execution results (file count, module count) → Auto-continue to Phase 4
+
+---
+
+### Phase 4: Generate SKILL.md Index
+
+**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL index.
+
+**Step 1: Read Key Files** (Use Read tool)
+- `.workflow/docs/{project_name}/README.md` (required)
+- `.workflow/docs/{project_name}/ARCHITECTURE.md` (optional)
+
+**Step 2: Discover Structure**
+```bash
+bash(find .workflow/docs/{project_name} -name "*.md" | sed 's|.workflow/docs/{project_name}/||' | awk -F'/' '{if(NF>=2) print $1"/"$2}' | sort -u)
+```
+
+**Step 3: Generate Intelligent Description**
+
+Extract from README + structure: Function (capabilities), Modules (names), Keywords (API/CLI/auth/etc.)
+
+**Format**: `{Project} {core capabilities} (located at {project_path}). Load this SKILL when analyzing, modifying, or learning about {domain_description} or files under this path, especially when no relevant context exists in memory.`
+
+**Key Elements**:
+- **Path Reference**: Use `TARGET_PATH` from Phase 1 for precise location identification
+- **Domain Description**: Extract human-readable domain/feature area from README (e.g., "workflow management", "thermal modeling")
+- **Trigger Optimization**: Include project path, emphasize "especially when no relevant context exists in memory"
+- **Action Coverage**: analyzing (分析), modifying (修改), learning (了解)
+
+**Example**: "Workflow orchestration system with CLI tools and documentation generation (located at /d/Claude_dms3). Load this SKILL when analyzing, modifying, or learning about workflow management or files under this path, especially when no relevant context exists in memory."
+
+**Step 4: Write SKILL.md** (Use Write tool)
+```bash
+bash(mkdir -p .claude/skills/{project_name})
+```
+
+`.claude/skills/{project_name}/SKILL.md`:
+```yaml
+---
+name: {project_name}
+description: {intelligent description from Step 3}
+version: 1.0.0
+---
+# {Project Name} SKILL Package
+
+## Documentation: `../../../.workflow/docs/{project_name}/`
+
+## Progressive Loading
+### Level 0: Quick Start (~2K)
+- [README](../../../.workflow/docs/{project_name}/README.md)
+### Level 1: Core Modules (~8K)
+{Module READMEs}
+### Level 2: Complete (~25K)
+All modules + [Architecture](../../../.workflow/docs/{project_name}/ARCHITECTURE.md)
+### Level 3: Deep Dive (~40K)
+Everything + [Examples](../../../.workflow/docs/{project_name}/EXAMPLES.md)
+```
+
+**Completion Criteria**:
+- SKILL.md file created at `.claude/skills/{project_name}/SKILL.md`
+- Intelligent description generated from documentation
+- Progressive loading levels (0-3) properly structured
+- Module index includes all documented modules
+- All file references use relative paths
+
+**TodoWrite**: Mark phase 4 completed
+
+**Final Action**: Report completion summary to user
+
+**Return to User**:
+```
+SKILL Package Generation Complete
+
+Project: {project_name}
+Documentation: .workflow/docs/{project_name}/ ({doc_count} files)
+SKILL Index: .claude/skills/{project_name}/SKILL.md
+
+Generated:
+- {task_count} documentation tasks completed
+- SKILL.md with progressive loading (4 levels)
+- Module index with {module_count} modules
+
+Usage:
+- Load Level 0: Quick project overview (~2K tokens)
+- Load Level 1: Core modules (~8K tokens)
+- Load Level 2: Complete docs (~25K tokens)
+- Load Level 3: Everything (~40K tokens)
+```
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
+2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
+3. **Status-Driven Execution**: Check TodoList status after each phase:
+   - If next task is "pending" → Mark it "in_progress" and execute
+   - If all tasks are "completed" → Report final summary
+4. **Phase Completion Pattern**:
+   ```
+   Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
+   ```
+
+### TodoWrite Patterns
+
+#### Initialization (Before Phase 1)
+
+**FIRST ACTION**: Create TodoList with all 4 phases
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "in_progress", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "pending", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+```
+
+**SECOND ACTION**: Execute Phase 1 immediately
+
+#### Full Path (SKIP_DOCS_GENERATION = false)
+
+**After Phase 1**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "in_progress", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 2
+```
+
+**After Phase 2**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "in_progress", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 3
+```
+
+**After Phase 3**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 4
+```
+
+**After Phase 4**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
+]})
+// Report completion summary to user
+```
+
+#### Skip Path (SKIP_DOCS_GENERATION = true)
+
+**After Phase 1** (detects existing docs, skips Phase 2 & 3):
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+// Display skip message: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+// Jump directly to Phase 4
+```
+
+**After Phase 4**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
+]})
+// Report completion summary to user
+```
+
+### Execution Flow Diagrams
+
+#### Full Path Flow
+```
+User triggers command
+  ↓
+[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
+  ↓
+[Execute] Phase 1: Parse arguments
+  ↓
+[TodoWrite] Phase 1 = completed, Phase 2 = in_progress
+  ↓
+[Execute] Phase 2: Call /memory:docs
+  ↓
+[TodoWrite] Phase 2 = completed, Phase 3 = in_progress
+  ↓
+[Execute] Phase 3: Call /workflow:execute
+  ↓
+[TodoWrite] Phase 3 = completed, Phase 4 = in_progress
+  ↓
+[Execute] Phase 4: Generate SKILL.md
+  ↓
+[TodoWrite] Phase 4 = completed
+  ↓
+[Report] Display completion summary
+```
+
+#### Skip Path Flow
+```
+User triggers command
+  ↓
+[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
+  ↓
+[Execute] Phase 1: Parse arguments, detect existing docs
+  ↓
+[TodoWrite] Phase 1 = completed, Phase 2&3 = completed (skipped), Phase 4 = in_progress
+  ↓
+[Display] Skip message: "Documentation already exists, skipping Phase 2 and Phase 3"
+  ↓
+[Execute] Phase 4: Generate SKILL.md (always runs)
+  ↓
+[TodoWrite] Phase 4 = completed
+  ↓
+[Report] Display completion summary
+```
+
+### Error Handling
+
+- If any phase fails, mark it as "in_progress" (not completed)
+- Report error details to user
+- Do NOT auto-continue to next phase on failure
+
+---
+
+## Parameters
+
+```bash
+/memory:skill-memory [path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]
+```
+
+- **path**: Target directory (default: current directory)
+- **--tool**: CLI tool for documentation (default: gemini)
+  - `gemini`: Comprehensive documentation
+  - `qwen`: Architecture analysis
+  - `codex`: Implementation validation
+- **--regenerate**: Force regenerate all documentation
+  - When enabled: Deletes existing `.workflow/docs/{project_name}/` before regeneration
+  - Ensures fresh documentation from source code
+- **--mode**: Documentation mode (default: full)
+  - `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES)
+  - `partial`: Module docs only
+- **--cli-execute**: Enable CLI-based documentation generation (optional)
+  - When enabled: CLI generates docs directly in implementation_approach
+  - When disabled (default): Agent generates documentation content
+
+---
+
+## Examples
+
+### Example 1: Generate SKILL Package (Default)
+
+```bash
+/memory:skill-memory
+```
+
+**Workflow**:
+1. Phase 1: Detects current directory, checks existing docs
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode)
+3. Phase 3: Executes documentation generation via `/workflow:execute`
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 2: Regenerate with Qwen
+
+```bash
+/memory:skill-memory /d/my_app --tool qwen --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Parses target path, detects regenerate flag, deletes existing docs
+2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full`
+3. Phase 3: Executes documentation regeneration
+4. Phase 4: Generates updated SKILL.md
+
+### Example 3: Partial Mode (Modules Only)
+
+```bash
+/memory:skill-memory --mode partial
+```
+
+**Workflow**:
+1. Phase 1: Detects partial mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode)
+3. Phase 3: Executes module documentation only
+4. Phase 4: Generates SKILL.md with module-only index
+
+### Example 4: CLI Execute Mode
+
+```bash
+/memory:skill-memory --cli-execute
+```
+
+**Workflow**:
+1. Phase 1: Detects CLI execute mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode)
+3. Phase 3: Executes CLI-based documentation generation
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 5: Skip Path (Existing Docs)
+
+```bash
+/memory:skill-memory
+```
+
+**Scenario**: Documentation already exists in `.workflow/docs/{project_name}/`
+
+**Workflow**:
+1. Phase 1: Detects existing docs (5 files), sets SKIP_DOCS_GENERATION = true
+2. Display: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+3. Phase 4: Generates or updates SKILL.md index only (~5-10x faster)
+
+---
+
+## Benefits
+
+- **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs
+- **Auto-Continue**: Autonomous 4-phase execution without user interaction
+- **Intelligent Skip**: Detects existing docs and skips regeneration for fast SKILL updates
+- **Always Fresh Index**: Phase 4 always executes to ensure SKILL.md stays synchronized
+- **Simplified**: ~70% less code than previous version
+- **Maintainable**: Changes to /memory:docs automatically apply
+- **Direct Generation**: Phase 4 directly writes SKILL.md
+- **Flexible**: Supports all /memory:docs options (tool, mode, cli-execute)
+
+## Architecture
+
+```
+skill-memory (orchestrator)
+  ├─ Phase 1: Prepare (bash commands, skip decision)
+  ├─ Phase 2: /memory:docs (task planning, skippable)
+  ├─ Phase 3: /workflow:execute (task execution, skippable)
+  └─ Phase 4: Write SKILL.md (direct file generation, always runs)
+
+No task JSON created by this command
+All documentation tasks managed by /memory:docs
+Smart skip logic: 5-10x faster when docs exist
+```

.claude/commands/memory/tech-research.md

@@ -0,0 +1,477 @@
+---
+name: tech-research
+description: 3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists)
+argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
+---
+
+# Tech Stack Research SKILL Generator
+
+## Overview
+
+**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates ALL work to agent. Agent produces files directly.
+
+**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
+
+**Execution Paths**:
+- **Full Path**: All 3 phases (no existing SKILL OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 3 (existing SKILL found AND no `--regenerate` flag)
+- **Phase 3 Always Executes**: SKILL index is always generated or updated
+
+**Agent Responsibility**:
+- Agent does ALL the work: context reading, Exa research, content synthesis, file writing
+- Orchestrator only provides context paths and waits for completion
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **Context Path Delegation**: Pass session directory or tech stack name to agent, let agent do discovery
+3. **Agent Produces Files**: Agent directly writes all module files, orchestrator does NOT parse agent output
+4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+5. **No User Prompts**: Never ask user questions or wait for input between phases
+6. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+7. **Lightweight Index**: Phase 3 only generates SKILL.md index by reading existing files
+
+---
+
+## 3-Phase Execution
+
+### Phase 1: Prepare Context Paths
+
+**Goal**: Detect input mode, prepare context paths for agent, check existing SKILL
+
+**Input Mode Detection**:
+```bash
+# Get input parameter
+input="$1"
+
+# Detect mode
+if [[ "$input" == WFS-* ]]; then
+  MODE="session"
+  SESSION_ID="$input"
+  CONTEXT_PATH=".workflow/${SESSION_ID}"
+else
+  MODE="direct"
+  TECH_STACK_NAME="$input"
+  CONTEXT_PATH="$input"  # Pass tech stack name as context
+fi
+```
+
+**Check Existing SKILL**:
+```bash
+# For session mode, peek at session to get tech stack name
+if [[ "$MODE" == "session" ]]; then
+  bash(test -f ".workflow/${SESSION_ID}/workflow-session.json")
+  Read(.workflow/${SESSION_ID}/workflow-session.json)
+  # Extract tech_stack_name (minimal extraction)
+fi
+
+# Normalize and check
+normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists")
+bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Skip Decision**:
+```javascript
+if (existing_files > 0 && !regenerate_flag) {
+  SKIP_GENERATION = true
+  message = "Tech stack SKILL already exists, skipping Phase 2. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  bash(rm -rf ".claude/skills/${normalized_name}")
+  SKIP_GENERATION = false
+  message = "Regenerating tech stack SKILL from scratch."
+} else {
+  SKIP_GENERATION = false
+  message = "No existing SKILL found, generating new tech stack documentation."
+}
+```
+
+**Output Variables**:
+- `MODE`: `session` or `direct`
+- `SESSION_ID`: Session ID (if session mode)
+- `CONTEXT_PATH`: Path to session directory OR tech stack name
+- `TECH_STACK_NAME`: Extracted or provided tech stack name
+- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
+
+**TodoWrite**:
+- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
+- If not skipping: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Agent Produces All Files
+
+**Skip Condition**: Skipped if `SKIP_GENERATION = true`
+
+**Goal**: Delegate EVERYTHING to agent - context reading, Exa research, content synthesis, and file writing
+
+**Agent Task Specification**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Generate tech stack SKILL: {CONTEXT_PATH}",
+  prompt: "
+Generate a complete tech stack SKILL package with Exa research.
+
+**Context Provided**:
+- Mode: {MODE}
+- Context Path: {CONTEXT_PATH}
+
+**Templates Available**:
+- Module Format: ~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt
+- SKILL Index: ~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt
+
+**Your Responsibilities**:
+
+1. **Extract Tech Stack Information**:
+
+   IF MODE == 'session':
+     - Read `.workflow/{SESSION_ID}/workflow-session.json`
+     - Read `.workflow/{SESSION_ID}/.process/context-package.json`
+     - Extract tech_stack: {language, frameworks, libraries}
+     - Build tech stack name: \"{language}-{framework1}-{framework2}\"
+     - Example: \"typescript-react-nextjs\"
+
+   IF MODE == 'direct':
+     - Tech stack name = CONTEXT_PATH
+     - Parse composite: split by '-' delimiter
+     - Example: \"typescript-react-nextjs\" → [\"typescript\", \"react\", \"nextjs\"]
+
+2. **Execute Exa Research** (4-6 parallel queries):
+
+   Base Queries (always execute):
+   - mcp__exa__get_code_context_exa(query: \"{tech} core principles best practices 2025\", tokensNum: 8000)
+   - mcp__exa__get_code_context_exa(query: \"{tech} common patterns architecture examples\", tokensNum: 7000)
+   - mcp__exa__web_search_exa(query: \"{tech} configuration setup tooling 2025\", numResults: 5)
+   - mcp__exa__get_code_context_exa(query: \"{tech} testing strategies\", tokensNum: 5000)
+
+   Component Queries (if composite):
+   - For each additional component:
+     mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000)
+
+3. **Read Module Format Template**:
+
+   Read template for structure guidance:
+   ```bash
+   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt)
+   ```
+
+4. **Synthesize Content into 6 Modules**:
+
+   Follow template structure from tech-module-format.txt:
+   - **principles.md** - Core concepts, philosophies (~3K tokens)
+   - **patterns.md** - Implementation patterns with code examples (~5K tokens)
+   - **practices.md** - Best practices, anti-patterns, pitfalls (~4K tokens)
+   - **testing.md** - Testing strategies, frameworks (~3K tokens)
+   - **config.md** - Setup, configuration, tooling (~3K tokens)
+   - **frameworks.md** - Framework integration (only if composite, ~4K tokens)
+
+   Each module follows template format:
+   - Frontmatter (YAML)
+   - Main sections with clear headings
+   - Code examples from Exa research
+   - Best practices sections
+   - References to Exa sources
+
+5. **Write Files Directly**:
+
+   ```javascript
+   // Create directory
+   bash(mkdir -p \".claude/skills/{tech_stack_name}\")
+
+   // Write each module file using Write tool
+   Write({ file_path: \".claude/skills/{tech_stack_name}/principles.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/patterns.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/practices.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/testing.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/config.md\", content: ... })
+   // Write frameworks.md only if composite
+
+   // Write metadata.json
+   Write({
+     file_path: \".claude/skills/{tech_stack_name}/metadata.json\",
+     content: JSON.stringify({
+       tech_stack_name,
+       components,
+       is_composite,
+       generated_at: timestamp,
+       source: \"exa-research\",
+       research_summary: { total_queries, total_sources }
+     })
+   })
+   ```
+
+6. **Report Completion**:
+
+   Provide summary:
+   - Tech stack name
+   - Files created (count)
+   - Exa queries executed
+   - Sources consulted
+
+**CRITICAL**:
+- MUST read external template files before generating content (step 3 for modules, step 4 for index)
+- You have FULL autonomy - read files, execute Exa, synthesize content, write files
+- Do NOT return JSON or structured data - produce actual .md files
+- Handle errors gracefully (Exa failures, missing files, template read failures)
+- If tech stack cannot be determined, ask orchestrator to clarify
+  "
+)
+```
+
+**Completion Criteria**:
+- Agent task executed successfully
+- 5-6 modular files written to `.claude/skills/{tech_stack_name}/`
+- metadata.json written
+- Agent reports completion
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Generate SKILL.md Index
+
+**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
+
+**Goal**: Read generated module files and create SKILL.md index with loading recommendations
+
+**Steps**:
+
+1. **Verify Generated Files**:
+   ```bash
+   bash(find ".claude/skills/${TECH_STACK_NAME}" -name "*.md" -type f | sort)
+   ```
+
+2. **Read metadata.json**:
+   ```javascript
+   Read(.claude/skills/${TECH_STACK_NAME}/metadata.json)
+   // Extract: tech_stack_name, components, is_composite, research_summary
+   ```
+
+3. **Read Module Headers** (optional, first 20 lines):
+   ```javascript
+   Read(.claude/skills/${TECH_STACK_NAME}/principles.md, limit: 20)
+   // Repeat for other modules
+   ```
+
+4. **Read SKILL Index Template**:
+
+   ```javascript
+   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt)
+   ```
+
+5. **Generate SKILL.md Index**:
+
+   Follow template from tech-skill-index.txt with variable substitutions:
+   - `{TECH_STACK_NAME}`: From metadata.json
+   - `{MAIN_TECH}`: Primary technology
+   - `{ISO_TIMESTAMP}`: Current timestamp
+   - `{QUERY_COUNT}`: From research_summary
+   - `{SOURCE_COUNT}`: From research_summary
+   - Conditional sections for composite tech stacks
+
+   Template provides structure for:
+   - Frontmatter with metadata
+   - Overview and tech stack description
+   - Module organization (Core/Practical/Config sections)
+   - Loading recommendations (Quick/Implementation/Complete)
+   - Usage guidelines and auto-trigger keywords
+   - Research metadata and version history
+
+6. **Write SKILL.md**:
+   ```javascript
+   Write({
+     file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`,
+     content: generatedIndexMarkdown
+   })
+   ```
+
+**Completion Criteria**:
+- SKILL.md index written
+- All module files verified
+- Loading recommendations included
+
+**TodoWrite**: Mark phase 3 completed
+
+**Final Report**:
+```
+Tech Stack SKILL Package Complete
+
+Tech Stack: {TECH_STACK_NAME}
+Location: .claude/skills/{TECH_STACK_NAME}/
+
+Files: SKILL.md + 5-6 modules + metadata.json
+Exa Research: {queries} queries, {sources} sources
+
+Usage: Skill(command: "{TECH_STACK_NAME}")
+```
+
+---
+
+## Implementation Details
+
+### TodoWrite Patterns
+
+**Initialization** (Before Phase 1):
+```javascript
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "in_progress", "activeForm": "Preparing context paths"},
+  {"content": "Agent produces all module files", "status": "pending", "activeForm": "Agent producing files"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
+]})
+```
+
+**Full Path** (SKIP_GENERATION = false):
+```javascript
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "in_progress", ...},
+  {"content": "Generate SKILL.md index", "status": "pending", ...}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "completed", ...}
+]})
+```
+
+**Skip Path** (SKIP_GENERATION = true):
+```javascript
+// After Phase 1 (skip Phase 2)
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},  // Skipped
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+```
+
+### Execution Flow
+
+**Full Path**:
+```
+User → TodoWrite Init → Phase 1 (prepare) → Phase 2 (agent writes files) → Phase 3 (write index) → Report
+```
+
+**Skip Path**:
+```
+User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
+```
+
+### Error Handling
+
+**Phase 1 Errors**:
+- Invalid session ID: Report error, verify session exists
+- Missing context-package: Warn, fall back to direct mode
+- No tech stack detected: Ask user to specify tech stack name
+
+**Phase 2 Errors (Agent)**:
+- Agent task fails: Retry once, report if fails again
+- Exa API failures: Agent handles internally with retries
+- Incomplete results: Warn user, proceed with partial data if minimum sections available
+
+**Phase 3 Errors**:
+- Write failures: Report which files failed
+- Missing files: Note in SKILL.md, suggest regeneration
+
+---
+
+## Parameters
+
+```bash
+/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool <gemini|qwen>]
+```
+
+**Arguments**:
+- **session-id | tech-stack-name**: Input source (auto-detected by WFS- prefix)
+  - Session mode: `WFS-user-auth-v2` - Extract tech stack from workflow
+  - Direct mode: `"typescript"`, `"typescript-react-nextjs"` - User specifies
+- **--regenerate**: Force regenerate existing SKILL (deletes and recreates)
+- **--tool**: Reserved for future CLI integration (default: gemini)
+
+---
+
+## Examples
+
+**Generated File Structure** (for all examples):
+```
+.claude/skills/{tech-stack}/
+├── SKILL.md           # Index (Phase 3)
+├── principles.md      # Agent (Phase 2)
+├── patterns.md        # Agent
+├── practices.md       # Agent
+├── testing.md         # Agent
+├── config.md          # Agent
+├── frameworks.md      # Agent (if composite)
+└── metadata.json      # Agent
+```
+
+### Direct Mode - Single Stack
+
+```bash
+/memory:tech-research "typescript"
+```
+
+**Workflow**:
+1. Phase 1: Detects direct mode, checks existing SKILL
+2. Phase 2: Agent executes 4 Exa queries, writes 5 modules
+3. Phase 3: Generates SKILL.md index
+
+### Direct Mode - Composite Stack
+
+```bash
+/memory:tech-research "typescript-react-nextjs"
+```
+
+**Workflow**:
+1. Phase 1: Decomposes into ["typescript", "react", "nextjs"]
+2. Phase 2: Agent executes 6 Exa queries (4 base + 2 components), writes 6 modules (adds frameworks.md)
+3. Phase 3: Generates SKILL.md index with framework integration
+
+### Session Mode - Extract from Workflow
+
+```bash
+/memory:tech-research WFS-user-auth-20251104
+```
+
+**Workflow**:
+1. Phase 1: Reads session, extracts tech stack: `python-fastapi-sqlalchemy`
+2. Phase 2: Agent researches Python + FastAPI + SQLAlchemy, writes 6 modules
+3. Phase 3: Generates SKILL.md index
+
+### Regenerate Existing
+
+```bash
+/memory:tech-research "react" --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Deletes existing SKILL due to --regenerate
+2. Phase 2: Agent executes fresh Exa research (latest 2025 practices)
+3. Phase 3: Generates updated SKILL.md
+
+### Skip Path - Fast Update
+
+```bash
+/memory:tech-research "python"
+```
+
+**Scenario**: SKILL already exists with 7 files
+
+**Workflow**:
+1. Phase 1: Detects existing SKILL, sets SKIP_GENERATION = true
+2. Phase 2: **SKIPPED**
+3. Phase 3: Updates SKILL.md index only (5-10x faster)
+
+

.claude/commands/memory/update-full.md

@@ -0,0 +1,333 @@
+---
+name: update-full
+description: Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
+argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
+---
+
+# Full Documentation Update (/memory:update-full)
+
+## Overview
+
+Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback and 3-layer architecture support.
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+- `--path <directory>`: Target specific directory (default: entire project)
+
+**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
+
+## 3-Layer Architecture & Auto-Strategy Selection
+
+### Layer Definition & Strategy Assignment
+
+| Layer | Depth | Strategy | Purpose | Context Pattern |
+|-------|-------|----------|---------|----------------|
+| **Layer 3** (Deepest) | ≥3 | `multi-layer` | Handle unstructured files, generate docs for all subdirectories | `@**/*` (all files) |
+| **Layer 2** (Middle) | 1-2 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+| **Layer 1** (Top) | 0 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+
+**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
+
+**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
+
+### Strategy Details
+
+#### Multi-Layer Strategy (Layer 3 Only)
+- **Use Case**: Deepest directories with unstructured file layouts
+- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
+- **Context**: All files in current directory tree (`@**/*`)
+- **Benefits**: Creates foundation documentation for upper layers to reference
+
+#### Single-Layer Strategy (Layers 1-2)
+- **Use Case**: Upper layers that aggregate from existing documentation
+- **Behavior**: Generates CLAUDE.md only for current directory
+- **Context**: Direct children CLAUDE.md files + current directory code files
+- **Benefits**: Minimal context consumption, clear layer separation
+
+### Example Flow
+```
+src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
+  CONTEXT: @**/* (all files in handlers/ and subdirs)
+  GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
+  ↓
+src/auth/ (depth 2) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md + current code)
+  GENERATES: ./CLAUDE.md only
+  ↓
+src/ (depth 1) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+  ↓
+./ (depth 0) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+```
+
+## Core Execution Rules
+
+1. **Analyze First**: Git cache + module discovery before updates
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
+   - **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
+6. **Safety Check**: Verify only CLAUDE.md files modified
+7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Execution Phases
+
+### Phase 1: Discovery & Analysis
+
+```bash
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+
+# Get module structure
+bash(~/.claude/scripts/get_modules_by_depth.sh list)
+# OR with --path
+bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+**Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
+
+### Phase 2: Plan Presentation
+
+**For <20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 7 modules
+  Execution: Direct parallel (< 20 modules threshold)
+
+  Will update:
+  - ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy
+  - ./core (22 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./models (9 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./utils (12 files) - depth 1 [Layer 2] - single-layer strategy
+  - . (5 files) - depth 0 [Layer 1] - single-layer strategy
+
+  Context Strategy (Auto-Selected):
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Confirm execution? (y/n)
+```
+
+**For ≥20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 31 modules
+  Execution: Agent batch processing (4 modules/agent)
+
+  Will update:
+  - ./src/features/auth (12 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./.claude/commands/cli (6 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./src/utils (8 files) - depth 2 [Layer 2] - single-layer strategy
+  ...
+
+  Context Strategy (Auto-Selected):
+  - Layer 3 (depth ≥3): @**/* (all files)
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+  
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Agent allocation (by LAYER):
+  - Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
+  - Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
+  - Layer 1 (2 modules, depth 0): 1 agent [2]
+
+  Estimated time: ~15-25 minutes
+
+  Confirm execution? (y/n)
+```
+
+### Phase 3A: Direct Execution (<20 modules)
+
+**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
+
+```javascript
+// Group modules by LAYER (not depth)
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+// Process by LAYER (3 → 2 → 1), not by depth
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+
+  for (let batch of batches) {
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        // Auto-determine strategy based on depth
+        let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
+
+        for (let tool of tool_order) {
+          let exit_code = bash(`cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`);
+          if (exit_code === 0) {
+            report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
+            return true;
+          }
+        }
+        report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
+        return false;
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));
+  }
+}
+```
+
+### Phase 3B: Agent Batch Execution (≥20 modules)
+
+**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
+
+```javascript
+// Group modules by LAYER and batch within each layer
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules in Layer ${layer}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, layer)
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);
+}
+```
+
+**Batch Worker Prompt Template**:
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback
+
+TASK: Update documentation for assigned modules using specified strategies.
+
+MODULES:
+{{module_path_1}} (strategy: {{strategy_1}})
+{{module_path_2}} (strategy: {{strategy_2}})
+...
+
+TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
+
+EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
+  - Accepts strategy parameter: multi-layer | single-layer
+  - Tool execution via direct CLI commands (gemini/qwen/codex)
+
+EXECUTION FLOW (for each module):
+  1. Tool fallback loop (exit on first success):
+     for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
+       bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}")
+       exit_code=$?
+
+       if [ $exit_code -eq 0 ]; then
+         report "✅ {{module_path}} updated with $tool"
+         break
+       else
+         report "⚠️  {{module_path}} failed with $tool, trying next..."
+         continue
+       fi
+     done
+
+  2. Handle complete failure (all tools failed):
+     if [ $exit_code -ne 0 ]; then
+       report "❌ FAILED: {{module_path}} - all tools exhausted"
+       # Continue to next module (do not abort batch)
+     fi
+
+FAILURE HANDLING:
+  - Module-level isolation: One module's failure does not affect others
+  - Exit code detection: Non-zero exit code triggers next tool
+  - Exhaustion reporting: Log modules where all tools failed
+  - Batch continuation: Always process remaining modules
+
+REPORTING FORMAT:
+  Per-module status:
+    ✅ path/to/module updated with {tool}
+    ⚠️  path/to/module failed with {tool}, trying next...
+    ❌ FAILED: path/to/module - all tools exhausted
+```
+### Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display status
+bash(git status --short)
+```
+
+**Result Summary**:
+```
+Update Summary:
+  Total: 31 | Success: 29 | Failed: 2
+  Tool usage: gemini: 25, qwen: 4, codex: 0
+  Failed: path1, path2
+```
+
+## Error Handling
+
+**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
+**Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
+**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
+
+## Usage Examples
+
+```bash
+# Full project update (auto-strategy selection)
+/memory:update-full
+
+# Target specific directory
+/memory:update-full --path .claude
+/memory:update-full --path src/features/auth
+
+# Use specific tool
+/memory:update-full --tool qwen
+/memory:update-full --path .claude --tool qwen
+```
+
+## Key Advantages
+
+- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
+- **Resilience**: 3-tier tool fallback per module
+- **Performance**: Parallel batches, no concurrency limits
+- **Observability**: Per-module tool usage, batch-level metrics
+- **Automation**: Zero configuration - strategy auto-selected by directory depth

.claude/commands/memory/update-memory-full.md

@@ -1,330 +0,0 @@
----
-name: update-full
-description: Complete project-wide CLAUDE.md documentation update
-argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
----
-
-# Full Documentation Update (/memory:update-full)
-
-## Coordinator Role
-
-**This command orchestrates project-wide CLAUDE.md updates** using depth-parallel execution strategy with intelligent complexity detection.
-
-**Execution Model**:
-
-1. **Initial Analysis**: Cache git changes, discover module structure
-2. **Complexity Detection**: Analyze module count, determine strategy
-3. **Plan Presentation**: Show user exactly what will be updated
-4. **Depth-Parallel Execution**: Update modules by depth (highest to lowest)
-5. **Safety Verification**: Ensure only CLAUDE.md files modified
-
-**Tool Selection**:
-- `--tool gemini` (default): Documentation generation, pattern recognition
-- `--tool qwen`: Architecture analysis, system design docs
-- `--tool codex`: Implementation validation, code quality analysis
-
-**Path Parameter**:
-- `--path <directory>` (optional): Target specific directory for updates
-- If not specified: Updates entire project from current directory
-- If specified: Changes to target directory before discovery
-
-## Core Rules
-
-1. **Analyze First**: Run git cache and module discovery before any updates
-2. **Scope Control**: Use --path to target specific directories, default is entire project
-3. **Wait for Approval**: Present plan, no execution without user confirmation
-4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
-5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
-6. **Independent Commands**: Each update is a separate bash() call
-7. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
-
-## Execution Workflow
-
-### Phase 1: Discovery & Analysis
-
-**Cache git changes:**
-```bash
-bash(git add -A 2>/dev/null || true)
-```
-
-**Get module structure:**
-
-*If no --path parameter:*
-```bash
-bash(~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-*If --path parameter specified:*
-```bash
-bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-**Example with path:**
-```bash
-# Update only .claude directory
-bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list)
-
-# Update specific feature directory
-bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list)
-```
-
-**Parse Output**:
-- Extract module paths from `depth:N|path:<PATH>|...` format
-- Count total modules
-- Identify which modules have/need CLAUDE.md
-
-**Example output:**
-```
-depth:5|path:./.claude/workflows/cli-templates/prompts/analysis|files:5|has_claude:no
-depth:4|path:./.claude/commands/cli/mode|files:3|has_claude:no
-depth:3|path:./.claude/commands/cli|files:6|has_claude:no
-depth:0|path:.|files:14|has_claude:yes
-```
-
-**Validation**:
-- If --path specified, directory exists and is accessible
-- Module list contains depth and path information
-- At least one module exists
-- All paths are relative to target directory (if --path used)
-
----
-
-### Phase 2: Plan Presentation
-
-**Decision Logic**:
-- **Simple projects (≤20 modules)**: Present plan to user, wait for approval
-- **Complex projects (>20 modules)**: Delegate to memory-bridge agent
-
-**Plan format:**
-```
-📋 Update Plan:
-  Tool: gemini
-  Total modules: 31
-
-  NEW CLAUDE.md files (30):
-    - ./.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
-    - ./.claude/commands/cli/mode/CLAUDE.md
-    - ... (28 more)
-
-  UPDATE existing CLAUDE.md files (1):
-    - ./CLAUDE.md
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-**User Confirmation Required**: No execution without explicit approval
-
----
-
-### Phase 3: Depth-Parallel Execution
-
-**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
-
-**Command structure:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
-```
-
-**Example - Depth 5 (8 modules):**
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/analysis && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/development && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/documentation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/workflows/cli-templates/prompts/implementation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-*Wait for depth 5 completion...*
-
-**Example - Depth 4 (7 modules):**
-```bash
-bash(cd ./.claude/commands/cli/mode && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-```bash
-bash(cd ./.claude/commands/workflow/brainstorm && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-*Continue for remaining depths (3 → 2 → 1 → 0)...*
-
-**Execution Rules**:
-- Each command is separate bash() call
-- Up to 4 concurrent jobs per depth
-- Wait for all jobs in current depth before proceeding
-- Extract path from `depth:N|path:<PATH>|...` format
-- All paths relative to target directory (current dir or --path value)
-
-**Path Context**:
-- Without --path: Paths relative to current directory
-- With --path: Paths relative to specified target directory
-- Module discovery runs in target directory context
-
----
-
-### Phase 4: Safety Verification
-
-**Check modified files:**
-```bash
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
-```
-
-**Expected output:**
-```
-✅ Only CLAUDE.md files modified
-```
-
-**If non-CLAUDE.md files detected:**
-```
-⚠️ Warning: Non-CLAUDE.md files were modified
-Modified files: src/index.ts, package.json
-→ Run: git restore --staged .
-```
-
-**Display final status:**
-```bash
-bash(git status --short)
-```
-
-**Example output:**
-```
-A  .claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
-A  .claude/commands/cli/mode/CLAUDE.md
-M  CLAUDE.md
-... (30 more files)
-```
-
-## Command Pattern Reference
-
-**Single module update:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
-```
-
-**Components**:
-- `cd <module-path>` - Navigate to module (from `path:` field)
-- `&&` - Ensure cd succeeds
-- `update_module_claude.sh` - Update script
-- `"."` - Current directory
-- `"full"` - Full update mode
-- `"<tool>"` - gemini/qwen/codex
-- `&` - Background execution
-
-**Path extraction:**
-```bash
-# From: depth:5|path:./src/auth|files:10|has_claude:no
-# Extract: ./src/auth
-# Command: bash(cd ./src/auth && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
-```
-
-## Complex Projects Strategy
-
-For projects >20 modules, delegate to memory-bridge agent:
-
-```javascript
-Task(
-  subagent_type="memory-bridge",
-  description="Complex project full update",
-  prompt=`
-CONTEXT:
-- Total modules: ${module_count}
-- Tool: ${tool}
-- Mode: full
-
-MODULE LIST:
-${modules_output}
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level
-2. Process depths N→0 sequentially, max 4 parallel per depth
-3. Command: cd "<path>" && update_module_claude.sh "." "full" "${tool}" &
-4. Extract path from "depth:N|path:<PATH>|..." format
-5. Verify all modules processed
-6. Run safety check
-7. Display git status
-`
-)
-```
-
-## Error Handling
-
-- **Invalid path parameter**: Report error if --path directory doesn't exist, abort execution
-- **Module discovery failure**: Report error, abort execution
-- **User declines approval**: Abort execution, no changes made
-- **Safety check failure**: Automatic staging revert, report modified files
-- **Update script failure**: Report failed modules, continue with remaining
-
-## Coordinator Checklist
-
-✅ Parse `--tool` parameter (default: gemini)
-✅ Parse `--path` parameter (optional, default: current directory)
-✅ Execute git cache in current directory
-✅ Execute module discovery (with cd if --path specified)
-✅ Parse module list, count total modules
-✅ Determine strategy based on module count (≤20 vs >20)
-✅ Present plan with exact file paths
-✅ **Wait for user confirmation** (simple projects only)
-✅ Organize modules by depth
-✅ For each depth (highest to lowest):
-  - Launch up to 5 parallel updates
-  - Wait for depth completion
-  - Proceed to next depth
-✅ Run safety check after all updates
-✅ Display git status
-✅ Report completion summary
-
-
-
-## Tool Parameter Reference
-
-**Gemini** (default):
-- Best for: Documentation generation, pattern recognition, architecture review
-- Context window: Large, handles complex codebases
-- Output style: Comprehensive, detailed explanations
-
-**Qwen**:
-- Best for: Architecture analysis, system design documentation
-- Context window: Large, similar to Gemini
-- Output style: Structured, systematic analysis
-
-**Codex**:
-- Best for: Implementation validation, code quality analysis
-- Capabilities: Mathematical reasoning, autonomous development
-- Output style: Technical, implementation-focused
-
-## Path Parameter Reference
-
-**Use Cases**:
-
-**Update configuration directory only:**
-```bash
-/memory:update-full --path .claude
-```
-- Updates only .claude directory and subdirectories
-- Useful after workflow or command modifications
-- Faster than full project update
-
-**Update specific feature module:**
-```bash
-/memory:update-full --path src/features/auth
-```
-- Updates authentication feature and sub-modules
-- Ideal for feature-specific documentation
-- Isolates scope for targeted updates
-
-**Update nested structure:**
-```bash
-/memory:update-full --path .claude/workflows/cli-templates
-```
-- Updates deeply nested directory tree
-- Maintains relative path structure in output
-- All module paths relative to specified directory
-
-**Best Practices**:
-- Use `--path` when working on specific features/modules
-- Omit `--path` for project-wide architectural changes
-- Combine with `--tool` for specialized documentation needs
-- Verify directory exists before execution (automatic validation)

.claude/commands/memory/update-memory-related.md

@@ -1,306 +0,0 @@
----
-name: update-related
-description: Context-aware CLAUDE.md documentation updates based on recent changes
-argument-hint: "[--tool gemini|qwen|codex]"
----
-
-# Related Documentation Update (/memory:update-related)
-
-## Coordinator Role
-
-**This command orchestrates context-aware CLAUDE.md updates** for modules affected by recent changes using intelligent change detection.
-
-**Execution Model**:
-
-1. **Change Detection**: Analyze git changes to identify affected modules
-2. **Complexity Analysis**: Evaluate change count and determine strategy
-3. **Plan Presentation**: Show user which modules need updates
-4. **Depth-Parallel Execution**: Update affected modules by depth (highest to lowest)
-5. **Safety Verification**: Ensure only CLAUDE.md files modified
-
-**Tool Selection**:
-- `--tool gemini` (default): Documentation generation, pattern recognition
-- `--tool qwen`: Architecture analysis, system design docs
-- `--tool codex`: Implementation validation, code quality analysis
-
-## Core Rules
-
-1. **Detect Changes First**: Use git diff to identify affected modules before updates
-2. **Wait for Approval**: Present plan, no execution without user confirmation
-3. **Related Mode**: Update only changed modules and their parent contexts
-4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
-5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
-6. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
-
-## Execution Workflow
-
-### Phase 1: Change Detection & Analysis
-
-**Refresh code index:**
-```bash
-bash(mcp__code-index__refresh_index)
-```
-
-**Detect changed modules:**
-```bash
-bash(~/.claude/scripts/detect_changed_modules.sh list)
-```
-
-**Cache git changes:**
-```bash
-bash(git add -A 2>/dev/null || true)
-```
-
-**Parse Output**:
-- Extract changed module paths from `depth:N|path:<PATH>|...` format
-- Count affected modules
-- Identify which modules have/need CLAUDE.md updates
-
-**Example output:**
-```
-depth:3|path:./src/api/auth|files:5|types:[ts]|has_claude:no|change:new
-depth:2|path:./src/api|files:12|types:[ts]|has_claude:yes|change:modified
-depth:1|path:./src|files:8|types:[ts]|has_claude:yes|change:parent
-depth:0|path:.|files:14|has_claude:yes|change:parent
-```
-
-**Fallback behavior**:
-- If no git changes detected, use recent modules (first 10 by depth)
-
-**Validation**:
-- Changed module list contains valid paths
-- At least one affected module exists
-
----
-
-### Phase 2: Plan Presentation
-
-**Decision Logic**:
-- **Simple changes (≤15 modules)**: Present plan to user, wait for approval
-- **Complex changes (>15 modules)**: Delegate to memory-bridge agent
-
-**Plan format:**
-```
-📋 Related Update Plan:
-  Tool: gemini
-  Changed modules: 4
-
-  NEW CLAUDE.md files (1):
-    - ./src/api/auth/CLAUDE.md [new module]
-
-  UPDATE existing CLAUDE.md files (3):
-    - ./src/api/CLAUDE.md [parent of changed auth/]
-    - ./src/CLAUDE.md [parent context]
-    - ./CLAUDE.md [root level]
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-**User Confirmation Required**: No execution without explicit approval
-
----
-
-### Phase 3: Depth-Parallel Execution
-
-**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
-
-**Command structure:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
-```
-
-**Example - Depth 3 (new module):**
-```bash
-bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for depth 3 completion...*
-
-**Example - Depth 2 (modified parent):**
-```bash
-bash(cd ./src/api && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for depth 2 completion...*
-
-**Example - Depth 1 & 0 (parent contexts):**
-```bash
-bash(cd ./src && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-```bash
-bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-*Wait for all depths completion...*
-
-**Execution Rules**:
-- Each command is separate bash() call
-- Up to 4 concurrent jobs per depth
-- Wait for all jobs in current depth before proceeding
-- Use "related" mode (not "full") for context-aware updates
-- Extract path from `depth:N|path:<PATH>|...` format
-
-**Related Mode Behavior**:
-- Updates module based on recent git changes
-- Includes parent context for better documentation coherence
-- More efficient than full updates for iterative development
-
----
-
-### Phase 4: Safety Verification
-
-**Check modified files:**
-```bash
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
-```
-
-**Expected output:**
-```
-✅ Only CLAUDE.md files modified
-```
-
-**If non-CLAUDE.md files detected:**
-```
-⚠️ Warning: Non-CLAUDE.md files were modified
-Modified files: src/api/auth/index.ts, package.json
-→ Run: git restore --staged .
-```
-
-**Display final statistics:**
-```bash
-bash(git diff --stat)
-```
-
-**Example output:**
-```
-.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md | 45 +++++++++++++++++++++
-src/api/CLAUDE.md                                          | 23 +++++++++--
-src/CLAUDE.md                                              | 12 ++++--
-CLAUDE.md                                                  | 8 ++--
-4 files changed, 82 insertions(+), 6 deletions(-)
-```
-
-## Command Pattern Reference
-
-**Single module update:**
-```bash
-bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
-```
-
-**Components**:
-- `cd <module-path>` - Navigate to module (from `path:` field)
-- `&&` - Ensure cd succeeds
-- `update_module_claude.sh` - Update script
-- `"."` - Current directory
-- `"related"` - Related mode (context-aware, change-based)
-- `"<tool>"` - gemini/qwen/codex
-- `&` - Background execution
-
-**Path extraction:**
-```bash
-# From: depth:3|path:./src/api/auth|files:5|change:new|has_claude:no
-# Extract: ./src/api/auth
-# Command: bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
-```
-
-**Mode comparison:**
-- `"full"` - Complete module documentation regeneration
-- `"related"` - Context-aware update based on recent changes (faster)
-
-## Complex Changes Strategy
-
-For changes affecting >15 modules, delegate to memory-bridge agent:
-
-```javascript
-Task(
-  subagent_type="memory-bridge",
-  description="Complex project related update",
-  prompt=`
-CONTEXT:
-- Total modules: ${change_count}
-- Tool: ${tool}
-- Mode: related
-
-MODULE LIST:
-${changed_modules_output}
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level
-2. Process depths N→0 sequentially, max 4 parallel per depth
-3. Command: cd "<path>" && update_module_claude.sh "." "related" "${tool}" &
-4. Extract path from "depth:N|path:<PATH>|..." format
-5. Verify all ${change_count} modules processed
-6. Run safety check
-7. Display git diff --stat
-`
-)
-```
-
-## Error Handling
-
-- **No changes detected**: Use fallback mode (recent 10 modules)
-- **Change detection failure**: Report error, abort execution
-- **User declines approval**: Abort execution, no changes made
-- **Safety check failure**: Automatic staging revert, report modified files
-- **Update script failure**: Report failed modules, continue with remaining
-
-## Coordinator Checklist
-
-✅ Parse `--tool` parameter (default: gemini)
-✅ Refresh code index for accurate change detection
-✅ Detect changed modules via detect_changed_modules.sh
-✅ Cache git changes to protect current state
-✅ Parse changed module list, count affected modules
-✅ Apply fallback if no changes detected (recent 10 modules)
-✅ Determine strategy based on change count (≤15 vs >15)
-✅ Present plan with exact file paths and change types
-✅ **Wait for user confirmation** (simple changes only)
-✅ Organize modules by depth
-✅ For each depth (highest to lowest):
-  - Launch up to 4 parallel updates with "related" mode
-  - Wait for depth completion
-  - Proceed to next depth
-✅ Run safety check after all updates
-✅ Display git diff statistics
-✅ Report completion summary
-
-## Usage Examples
-
-```bash
-# Daily development update (default: gemini)
-/memory:update-related
-
-# After feature work with specific tool
-/memory:update-related --tool qwen
-
-# Code quality review after implementation
-/memory:update-related --tool codex
-```
-
-## Tool Parameter Reference
-
-**Gemini** (default):
-- Best for: Documentation generation, pattern recognition
-- Use case: Daily development updates, feature documentation
-- Output style: Comprehensive, contextual explanations
-
-**Qwen**:
-- Best for: Architecture analysis, system design
-- Use case: Structural changes, API design updates
-- Output style: Structured, systematic documentation
-
-**Codex**:
-- Best for: Implementation validation, code quality
-- Use case: After implementation, refactoring work
-- Output style: Technical, implementation-focused
-
-## Comparison with Full Update
-
-| Aspect | Related Update | Full Update |
-|--------|----------------|-------------|
-| **Scope** | Changed modules only | All project modules |
-| **Speed** | Fast (minutes) | Slower (10-30 min) |
-| **Use case** | Daily development | Major refactoring |
-| **Mode** | `"related"` | `"full"` |
-| **Trigger** | After commits | After major changes |
-| **Complexity threshold** | ≤15 modules | ≤20 modules |

.claude/commands/memory/update-related.md

@@ -0,0 +1,349 @@
+---
+name: update-related
+description: Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution
+argument-hint: "[--tool gemini|qwen|codex]"
+---
+
+# Related Documentation Update (/memory:update-related)
+
+## Overview
+
+Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (gemini→qwen→codex).
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+
+**Execution Flow**:
+1. Change Detection → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
+
+## Core Rules
+
+1. **Detect Changes First**: Use git diff to identify affected modules
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - <15 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead)
+   - ≥15 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
+6. **Related Mode**: Update only changed modules and their parent contexts
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+## Phase 1: Change Detection & Analysis
+
+```bash
+# Detect changed modules (no index refresh needed)
+bash(~/.claude/scripts/detect_changed_modules.sh list)
+
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+```
+
+**Parse output** `depth:N|path:<PATH>|change:<TYPE>` to extract affected modules.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc).
+
+**Fallback**: If no changes detected, use recent modules (first 10 by depth).
+
+## Phase 2: Plan Presentation
+
+**Present filtered plan**:
+```
+Related Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Changed: 4 modules | Batching: 4 modules/agent
+
+  Will update:
+  - ./src/api/auth (5 files) [new module]
+  - ./src/api (12 files) [parent of changed auth/]
+  - ./src (8 files) [parent context]
+  - . (14 files) [root level]
+
+  Auto-skipped (12 paths):
+  - Tests: ./src/api/auth.test.ts (8 paths)
+  - Config: tsconfig.json (3 paths)
+  - Other: node_modules (1 path)
+
+  Agent allocation:
+  - Depth 3 (1 module): 1 agent [1]
+  - Depth 2 (1 module): 1 agent [1]
+  - Depth 1 (1 module): 1 agent [1]
+  - Depth 0 (1 module): 1 agent [1]
+
+  Confirm execution? (y/n)
+```
+
+**Decision logic**:
+- User confirms "y": Proceed with execution
+- User declines "n": Abort, no changes
+- <15 modules: Direct execution
+- ≥15 modules: Agent batch execution
+
+## Phase 3A: Direct Execution (<15 modules)
+
+**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let modules = modules_by_depth[depth];
+  let batches = batch_modules(modules, 4);  // Split into groups of 4
+
+  for (let batch of batches) {
+    // Execute batch in parallel (max 4 concurrent)
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        let success = false;
+        for (let tool of tool_order) {
+          let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
+          if (exit_code === 0) {
+            report("${module.path} updated with ${tool}");
+            success = true;
+            break;
+          }
+        }
+        if (!success) {
+          report("FAILED: ${module.path} failed all tools");
+        }
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));  // Run batch in parallel
+  }
+}
+```
+
+**Benefits**:
+- No agent startup overhead
+- Parallel execution within depth (max 4 concurrent)
+- Tool fallback still applies per module
+- Faster for small changesets (<15 modules)
+- Same batching strategy as Phase 3B but without agent layer
+
+---
+
+## Phase 3B: Agent Batch Execution (≥15 modules)
+
+### Batching Strategy
+
+```javascript
+// Batch modules into groups of 4
+function batch_modules(modules, batch_size = 4) {
+  let batches = [];
+  for (let i = 0; i < modules.length; i += batch_size) {
+    batches.push(modules.slice(i, i + batch_size));
+  }
+  return batches;
+}
+// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
+```
+
+### Coordinator Orchestration
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let batches = batch_modules(modules_by_depth[depth], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules at depth ${depth}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, "related")
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);  // Batches run in parallel
+}
+```
+
+### Batch Worker Prompt Template
+
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode)
+
+TASK:
+Update documentation for the following modules based on recent changes. For each module, try tools in order until success.
+
+MODULES:
+{{module_path_1}}
+{{module_path_2}}
+{{module_path_3}}
+{{module_path_4}}
+
+TOOLS (try in order):
+1. {{tool_1}}
+2. {{tool_2}}
+3. {{tool_3}}
+
+EXECUTION:
+For each module above:
+  1. cd "{{module_path}}"
+  2. Try tool 1:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
+     → Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
+     → Failure: Try tool 2
+  3. Try tool 2:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
+     → Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
+     → Failure: Try tool 3
+  4. Try tool 3:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
+     → Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
+     → Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module
+
+REPORTING:
+Report final summary with:
+- Total processed: X modules
+- Successful: Y modules
+- Failed: Z modules
+- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
+- Detailed results for each module
+```
+
+### Example Execution
+
+**Depth 3 (new module)**:
+```javascript
+Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related")
+```
+
+**Benefits**:
+- 4 modules → 1 agent (75% reduction)
+- Parallel batches, sequential within batch
+- Each module gets full fallback chain
+- Context-aware updates based on git changes
+
+## Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display statistics
+bash(git diff --stat)
+```
+
+**Aggregate results**:
+```
+Update Summary:
+  Total: 4 | Success: 4 | Failed: 0
+
+  Tool usage:
+  - gemini: 4 modules
+  - qwen: 0 modules (fallback)
+  - codex: 0 modules
+
+  Changes:
+  src/api/auth/CLAUDE.md  | 45 +++++++++++++++++++++
+  src/api/CLAUDE.md       | 23 +++++++++--
+  src/CLAUDE.md           | 12 ++++--
+  CLAUDE.md               | 8 ++--
+  4 files changed, 82 insertions(+), 6 deletions(-)
+```
+
+## Execution Summary
+
+**Module Count Threshold**:
+- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
+- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
+
+**Agent Hierarchy** (for ≥15 modules):
+- **Coordinator**: Handles batch division, spawns worker agents per depth
+- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
+
+## Error Handling
+
+**Batch Worker**:
+- Tool fallback per module (auto-retry)
+- Batch isolation (failures don't propagate)
+- Clear per-module status reporting
+
+**Coordinator**:
+- No changes: Use fallback (recent 10 modules)
+- User decline: No execution
+- Safety check fail: Auto-revert staging
+- Partial failures: Continue execution, report failed modules
+
+**Fallback Triggers**:
+- Non-zero exit code
+- Script timeout
+- Unexpected output
+
+## Tool Reference
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Usage Examples
+
+```bash
+# Daily development update
+/memory:update-related
+
+# After feature work with specific tool
+/memory:update-related --tool qwen
+
+# Code quality review after implementation
+/memory:update-related --tool codex
+```
+
+## Key Advantages
+
+**Efficiency**: 30 modules → 8 agents (73% reduction)
+**Resilience**: 3-tier fallback per module
+**Performance**: Parallel batches, no concurrency limits
+**Context-aware**: Updates based on actual git changes
+**Fast**: Only affected modules, not entire project
+
+## Coordinator Checklist
+
+- Parse `--tool` (default: gemini)
+- Refresh code index for accurate change detection
+- Detect changed modules via detect_changed_modules.sh
+- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
+- Cache git changes
+- Apply fallback if no changes (recent 10 modules)
+- Construct tool fallback order
+- **Present filtered plan** with skip reasons and change types
+- **Wait for y/n confirmation**
+- Determine execution mode:
+  - **<15 modules**: Direct execution (Phase 3A)
+    - For each depth (N→0): Sequential module updates with tool fallback
+  - **≥15 modules**: Agent batch execution (Phase 3B)
+    - For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
+- Wait for depth/batch completion
+- Aggregate results
+- Safety check (only CLAUDE.md modified)
+- Display git diff statistics + summary
+
+## Comparison with Full Update
+
+| Aspect | Related Update | Full Update |
+|--------|----------------|-------------|
+| **Scope** | Changed modules only | All project modules |
+| **Speed** | Fast (minutes) | Slower (10-30 min) |
+| **Use case** | Daily development | Major refactoring |
+| **Mode** | `"related"` | `"full"` |
+| **Trigger** | After commits | After major changes |
+| **Batching** | 4 modules/agent | 4 modules/agent |
+| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
+| **Complexity threshold** | ≤15 modules | ≤20 modules |

.claude/commands/memory/workflow-skill-memory.md

@@ -0,0 +1,517 @@
+---
+name: workflow-skill-memory
+description: Process WFS-* archived sessions using universal-executor agents with Gemini analysis to generate workflow-progress SKILL package (sessions-timeline, lessons, conflicts)
+argument-hint: "session <session-id> | all"
+allowed-tools: Task(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Workflow SKILL Memory Generator
+
+## Overview
+
+Generate SKILL package from archived workflow sessions using agent-driven analysis. Supports single-session incremental updates or parallel processing of all sessions.
+
+**Scope**: Only processes WFS-* workflow sessions. Other session types (e.g., doc sessions) are automatically ignored.
+
+## Usage
+
+```bash
+/memory:workflow-skill-memory session WFS-<session-id>   # Process single WFS session
+/memory:workflow-skill-memory all                        # Process all WFS sessions in parallel
+```
+
+## Execution Modes
+
+### Mode 1: Single Session (`session <session-id>`)
+
+**Purpose**: Incremental update - process one archived session and merge into existing SKILL package
+
+**Workflow**:
+1. **Validate session**: Check if session exists in `.workflow/.archives/{session-id}/`
+2. **Invoke agent**: Call `universal-executor` to analyze session and update SKILL documents
+3. **Agent tasks**:
+   - Read session data from `.workflow/.archives/{session-id}/`
+   - Extract lessons, conflicts, and outcomes
+   - Use Gemini for intelligent aggregation (optional)
+   - Update or create SKILL documents using templates
+   - Regenerate SKILL.md index
+
+**Command Example**:
+```bash
+/memory:workflow-skill-memory session WFS-user-auth
+```
+
+**Expected Output**:
+```
+Session WFS-user-auth processed
+Updated:
+- sessions-timeline.md (1 session added)
+- lessons-learned.md (3 lessons merged)
+- conflict-patterns.md (1 conflict added)
+- SKILL.md (index regenerated)
+```
+
+---
+
+### Mode 2: All Sessions (`all`)
+
+**Purpose**: Full regeneration - process all archived sessions in parallel for complete SKILL package
+
+**Workflow**:
+1. **List sessions**: Read manifest.json to get all archived session IDs
+2. **Parallel invocation**: Launch multiple `universal-executor` agents in parallel (one per session)
+3. **Agent coordination**:
+   - Each agent processes one session independently
+   - Agents use Gemini for analysis
+   - Agents collect data into JSON (no direct file writes)
+   - Final aggregator agent merges results and generates SKILL documents
+
+**Command Example**:
+```bash
+/memory:workflow-skill-memory all
+```
+
+**Expected Output**:
+```
+All sessions processed in parallel
+Sessions: 8 total
+Updated:
+- sessions-timeline.md (8 sessions)
+- lessons-learned.md (24 lessons aggregated)
+- conflict-patterns.md (12 conflicts documented)
+- SKILL.md (index regenerated)
+```
+
+---
+
+## Implementation Flow
+
+### Phase 1: Validation and Setup
+
+**Step 1.1: Parse Command Arguments**
+
+Extract mode and session ID:
+```javascript
+if (args === "all") {
+  mode = "all"
+} else if (args.startsWith("session ")) {
+  mode = "session"
+  session_id = args.replace("session ", "").trim()
+} else {
+  ERROR = "Invalid arguments. Usage: session <session-id> | all"
+  EXIT
+}
+```
+
+**Step 1.2: Validate Archive Directory**
+```bash
+bash(test -d .workflow/.archives && echo "exists" || echo "missing")
+```
+
+If missing, report error and exit.
+
+**Step 1.3: Mode-Specific Validation**
+
+**Single Session Mode**:
+```bash
+# Validate session ID format (must start with WFS-)
+if [[ ! "$session_id" =~ ^WFS- ]]; then
+  ERROR = "Invalid session ID format. Only WFS-* sessions are supported"
+  EXIT
+fi
+
+# Check if session exists
+bash(test -d .workflow/.archives/{session_id} && echo "exists" || echo "missing")
+```
+
+If missing, report error: "Session {session_id} not found in archives"
+
+**All Sessions Mode**:
+```bash
+# Read manifest and filter only WFS- sessions
+bash(cat .workflow/.archives/manifest.json | jq -r '.archives[].session_id | select(startswith("WFS-"))')
+```
+
+Store filtered session IDs in array. Ignore doc sessions and other non-WFS sessions.
+
+**Step 1.4: TodoWrite Initialization**
+
+**Single Session Mode**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Validate session existence", "status": "completed", "activeForm": "Validating session"},
+  {"content": "Invoke agent to process session", "status": "in_progress", "activeForm": "Invoking agent"},
+  {"content": "Verify SKILL package updated", "status": "pending", "activeForm": "Verifying update"}
+]})
+```
+
+**All Sessions Mode**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Read manifest and list sessions", "status": "completed", "activeForm": "Reading manifest"},
+  {"content": "Invoke agents in parallel", "status": "in_progress", "activeForm": "Invoking agents"},
+  {"content": "Verify SKILL package regenerated", "status": "pending", "activeForm": "Verifying regeneration"}
+]})
+```
+
+---
+
+### Phase 2: Agent Invocation
+
+#### Single Session Mode - Agent Task
+
+Invoke `universal-executor` with session-specific task:
+
+**Agent Prompt Structure**:
+```
+Task: Process Workflow Session for SKILL Package
+
+Context:
+- Session ID: {session_id}
+- Session Path: .workflow/.archives/{session_id}/
+- Mode: Incremental update
+
+Objectives:
+
+1. Read session data:
+   - workflow-session.json (metadata)
+   - IMPL_PLAN.md (implementation summary)
+   - TODO_LIST.md (if exists)
+   - manifest.json entry for lessons
+
+2. Extract key information:
+   - Description, tags, metrics
+   - Lessons (successes, challenges, watch_patterns)
+   - Context package path (reference only)
+   - Key outcomes from IMPL_PLAN
+
+3. Use Gemini for aggregation (optional):
+   Command pattern:
+   cd .workflow/.archives/{session_id} && gemini -p "
+   PURPOSE: Extract lessons and conflicts from workflow session
+   TASK:
+   • Analyze IMPL_PLAN and lessons from manifest
+   • Identify success patterns and challenges
+   • Extract conflict patterns with resolutions
+   • Categorize by functional domain
+   MODE: analysis
+   CONTEXT: @IMPL_PLAN.md @workflow-session.json
+   EXPECTED: Structured lessons and conflicts in JSON format
+   RULES: Template reference from skill-aggregation.txt
+   "
+
+3.5. **Generate SKILL.md Description** (CRITICAL for auto-loading):
+
+   Read skill-index.txt template Section: "Description Field Generation"
+
+   Execute command to get project root:
+   ```bash
+   git rev-parse --show-toplevel  # Example output: /d/Claude_dms3
+   ```
+
+   Apply description format:
+   ```
+   Progressive workflow development history (located at {project_root}).
+   Load this SKILL when continuing development, analyzing past implementations,
+   or learning from workflow history, especially when no relevant context exists in memory.
+   ```
+
+   **Validation**:
+   - [ ] Path uses forward slashes (not backslashes)
+   - [ ] All three use cases present
+   - [ ] Trigger optimization phrase included
+   - [ ] Path is absolute (starts with / or drive letter)
+
+4. Read templates for formatting guidance:
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-sessions-timeline.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-lessons-learned.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-conflict-patterns.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-index.txt
+
+   **CRITICAL**: From skill-index.txt, read these sections:
+   - "Description Field Generation" - Rules for generating description
+   - "Variable Substitution Guide" - All required variables
+   - "Generation Instructions" - Step-by-step generation process
+   - "Validation Checklist" - Final validation steps
+
+5. Update SKILL documents:
+   - sessions-timeline.md: Append new session, update domain grouping
+   - lessons-learned.md: Merge lessons into categories, update frequencies
+   - conflict-patterns.md: Add conflicts, update recurring pattern frequencies
+   - SKILL.md: Regenerate index with updated counts
+
+   **For SKILL.md generation**:
+   - Follow "Generation Instructions" from skill-index.txt (Steps 1-7)
+   - Use git command for project_root: `git rev-parse --show-toplevel`
+   - Apply "Description Field Generation" rules
+   - Validate using "Validation Checklist"
+   - Increment version (patch level)
+
+6. Return result JSON:
+   {
+     "status": "success",
+     "session_id": "{session_id}",
+     "updates": {
+       "sessions_added": 1,
+       "lessons_merged": count,
+       "conflicts_added": count
+     }
+   }
+```
+
+---
+
+#### All Sessions Mode - Parallel Agent Tasks
+
+**Step 2.1: Launch parallel session analyzers**
+
+Invoke multiple agents in parallel (one message with multiple Task calls):
+
+**Per-Session Agent Prompt**:
+```
+Task: Extract Session Data for SKILL Package
+
+Context:
+- Session ID: {session_id}
+- Mode: Parallel analysis (no direct file writes)
+
+Objectives:
+
+1. Read session data (same as single mode)
+
+2. Extract key information (same as single mode)
+
+3. Use Gemini for analysis (same as single mode)
+
+4. Return structured data JSON:
+   {
+     "status": "success",
+     "session_id": "{session_id}",
+     "data": {
+       "metadata": {
+         "description": "...",
+         "archived_at": "...",
+         "tags": [...],
+         "metrics": {...}
+       },
+       "lessons": {
+         "successes": [...],
+         "challenges": [...],
+         "watch_patterns": [...]
+       },
+       "conflicts": [
+         {
+           "type": "architecture|dependencies|testing|performance",
+           "pattern": "...",
+           "resolution": "...",
+           "code_impact": [...]
+         }
+       ],
+       "impl_summary": "First 200 chars of IMPL_PLAN",
+       "context_package_path": "..."
+     }
+   }
+```
+
+**Step 2.2: Aggregate results**
+
+After all session agents complete, invoke aggregator agent:
+
+**Aggregator Agent Prompt**:
+```
+Task: Aggregate Session Results and Generate SKILL Package
+
+Context:
+- Mode: Full regeneration
+- Input: JSON results from {session_count} session agents
+
+Objectives:
+
+1. Aggregate all session data:
+   - Collect metadata from all sessions
+   - Merge lessons by category
+   - Group conflicts by type
+   - Sort sessions by date
+
+2. Use Gemini for final aggregation:
+   gemini -p "
+   PURPOSE: Aggregate lessons and conflicts from all workflow sessions
+   TASK:
+   • Group successes by functional domain
+   • Categorize challenges by severity (HIGH/MEDIUM/LOW)
+   • Identify recurring conflict patterns
+   • Calculate frequencies and prioritize
+   MODE: analysis
+   CONTEXT: [Provide aggregated JSON data]
+   EXPECTED: Final aggregated structure for SKILL documents
+   RULES: Template reference from skill-aggregation.txt
+   "
+
+3. Read templates for formatting (same 4 templates as single mode)
+
+4. Generate all SKILL documents:
+   - sessions-timeline.md (all sessions, sorted by date)
+   - lessons-learned.md (aggregated lessons with frequencies)
+   - conflict-patterns.md (recurring patterns with resolutions)
+   - SKILL.md (index with progressive loading)
+
+5. Write files to .claude/skills/workflow-progress/
+
+6. Return result JSON:
+   {
+     "status": "success",
+     "sessions_processed": count,
+     "files_generated": ["SKILL.md", "sessions-timeline.md", ...],
+     "summary": {
+       "total_sessions": count,
+       "functional_domains": [...],
+       "date_range": "...",
+       "lessons_count": count,
+       "conflicts_count": count
+     }
+   }
+```
+
+---
+
+### Phase 3: Verification
+
+**Step 3.1: Check SKILL Package Files**
+```bash
+bash(ls -lh .claude/skills/workflow-progress/)
+```
+
+Verify all 4 files exist:
+- SKILL.md
+- sessions-timeline.md
+- lessons-learned.md
+- conflict-patterns.md
+
+**Step 3.2: TodoWrite Completion**
+
+Mark all tasks as completed.
+
+**Step 3.3: Display Summary**
+
+**Single Session Mode**:
+```
+Session {session_id} processed successfully
+
+Updated:
+- sessions-timeline.md
+- lessons-learned.md
+- conflict-patterns.md
+- SKILL.md
+
+SKILL Location: .claude/skills/workflow-progress/SKILL.md
+```
+
+**All Sessions Mode**:
+```
+All sessions processed in parallel
+
+Sessions: {count} total
+Functional Domains: {domain_list}
+Date Range: {earliest} - {latest}
+
+Generated:
+- sessions-timeline.md ({count} sessions)
+- lessons-learned.md ({lessons_count} lessons)
+- conflict-patterns.md ({conflicts_count} conflicts)
+- SKILL.md (4-level progressive loading)
+
+SKILL Location: .claude/skills/workflow-progress/SKILL.md
+
+Usage:
+- Level 0: Quick refresh (~2K tokens)
+- Level 1: Recent history (~8K tokens)
+- Level 2: Complete analysis (~25K tokens)
+- Level 3: Deep dive (~40K tokens)
+```
+
+---
+
+## Agent Guidelines
+
+### Agent Capabilities
+
+**universal-executor agents can**:
+- Read files from `.workflow/.archives/`
+- Execute bash commands
+- Call Gemini CLI for intelligent analysis
+- Read template files for formatting guidance
+- Write SKILL package files (single mode) or return JSON (parallel mode)
+- Return structured results
+
+### Gemini Usage Pattern
+
+**When to use Gemini**:
+- Aggregating lessons from multiple sources
+- Identifying recurring patterns
+- Classifying conflicts by type and severity
+- Extracting structured data from IMPL_PLAN
+
+**Fallback Strategy**: If Gemini fails or times out, use direct file parsing with structured extraction logic.
+
+---
+
+## Template System
+
+### Template Files
+
+All templates located in: `~/.claude/workflows/cli-templates/prompts/workflow/`
+
+1. **skill-sessions-timeline.txt**: Format for sessions-timeline.md
+2. **skill-lessons-learned.txt**: Format for lessons-learned.md
+3. **skill-conflict-patterns.txt**: Format for conflict-patterns.md
+4. **skill-index.txt**: Format for SKILL.md index
+5. **skill-aggregation.txt**: Rules for Gemini aggregation (existing)
+
+### Template Usage in Agent
+
+**Agents read templates to understand**:
+- File structure and markdown format
+- Data sources (which files to read)
+- Update strategy (incremental vs full)
+- Formatting rules and conventions
+- Aggregation logic (for Gemini)
+
+**Templates are NOT shown in this command documentation** - agents read them directly as needed.
+
+---
+
+## Error Handling
+
+### Validation Errors
+- **No archives directory**: "Error: No workflow archives found at .workflow/.archives/"
+- **Invalid session ID format**: "Error: Invalid session ID format. Only WFS-* sessions are supported"
+- **Session not found**: "Error: Session {session_id} not found in archives"
+- **No WFS sessions in manifest**: "Error: No WFS-* workflow sessions found in manifest.json"
+
+### Agent Errors
+- If agent fails, report error message from agent result
+- If Gemini times out, agents use fallback direct parsing
+- If template read fails, agents use inline format
+
+### Recovery
+- Single session mode: Can be retried without affecting other sessions
+- All sessions mode: If one agent fails, others continue; retry failed sessions individually
+
+
+
+## Integration
+
+### Called by `/workflow:session:complete`
+
+Automatically invoked after session archival:
+```bash
+SlashCommand(command="/memory:workflow-skill-memory session {session_id}")
+```
+
+### Manual Invocation
+
+Users can manually process sessions:
+```bash
+/memory:workflow-skill-memory session WFS-custom-feature  # Single session
+/memory:workflow-skill-memory all                         # Full regeneration
+```

.claude/commands/task/breakdown.md

@@ -1,6 +1,6 @@
 ---
 name: breakdown
-description: Intelligent task decomposition with context-aware subtask generation
+description: Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order
 argument-hint: "task-id"
 ---
 
@@ -10,13 +10,12 @@ argument-hint: "task-id"
 Breaks down complex tasks into executable subtasks with context inheritance and agent assignment.
 
 ## Core Principles
-**Task System:** @~/.claude/workflows/workflow-architecture.md
 **File Cohesion:** Related files must stay in same task
 **10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping)
 
 ## Core Features
 
-⚠️ **CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
+**CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
 
 ### Breakdown Process
 1. **Session Check**: Verify active session contains parent task
@@ -51,7 +50,7 @@ Interactive process:
 Task: Build authentication module
 Current total tasks: 6/10
 
-⚠️  MANUAL BREAKDOWN REQUIRED
+MANUAL BREAKDOWN REQUIRED
 Define subtasks manually (remaining capacity: 4 tasks):
 
 1. Enter subtask title: User authentication core
@@ -60,11 +59,11 @@ Define subtasks manually (remaining capacity: 4 tasks):
 2. Enter subtask title: OAuth integration
    Focus files: services/OAuthService.js, routes/oauth.js
 
-⚠️  FILE CONFLICT DETECTED:
+FILE CONFLICT DETECTED:
    - routes/auth.js appears in multiple subtasks
    - Recommendation: Merge related authentication routes
 
-⚠️  SIMILAR FUNCTIONALITY WARNING:
+SIMILAR FUNCTIONALITY WARNING:
    - "User authentication" and "OAuth integration" both handle auth
    - Consider combining into single task
 
@@ -84,10 +83,10 @@ AskUserQuestion({
 
 User selected: "Proceed with breakdown"
 
-✅ Task IMPL-1 broken down:
-▸ IMPL-1: Build authentication module (container)
-  ├── IMPL-1.1: User authentication core → @code-developer
-  └── IMPL-1.2: OAuth integration → @code-developer
+Task IMPL-1 broken down:
+IMPL-1: Build authentication module (container)
+  ├── IMPL-1.1: User authentication core -> @code-developer
+  └── IMPL-1.2: OAuth integration -> @code-developer
 
 Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 ```
@@ -99,7 +98,7 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 - **Implementation** → `@code-developer`
 - **Testing** → `@code-developer` (type: "test-gen")
 - **Test Validation** → `@test-fix-agent` (type: "test-fix")
-- **Review** → `@general-purpose` (optional)
+- **Review** → `@universal-executor` (optional)
 
 ### Context Inheritance
 - Subtasks inherit parent requirements
@@ -138,7 +137,6 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 
 ## Implementation Details
 
-See @~/.claude/workflows/workflow-architecture.md for:
 - Complete task JSON schema
 - Implementation field structure
 - Context inheritance rules
@@ -169,45 +167,38 @@ See @~/.claude/workflows/workflow-architecture.md for:
 ```bash
 /task:breakdown impl-1
 
-▸ impl-1: Build authentication (container)
-  ├── impl-1.1: Design schema → @planning-agent
-  ├── impl-1.2: Implement logic + tests → @code-developer
-  └── impl-1.3: Execute & fix tests → @test-fix-agent
+impl-1: Build authentication (container)
+  ├── impl-1.1: Design schema -> @planning-agent
+  ├── impl-1.2: Implement logic + tests -> @code-developer
+  └── impl-1.3: Execute & fix tests -> @test-fix-agent
 ```
 
 ## Error Handling
 
 ```bash
 # Task not found
-❌ Task IMPL-5 not found
+Task IMPL-5 not found
 
 # Already broken down
-⚠️ Task IMPL-1 already has subtasks
+Task IMPL-1 already has subtasks
 
 # Wrong status
-❌ Cannot breakdown completed task IMPL-2
+Cannot breakdown completed task IMPL-2
 
 # 10-task limit exceeded
-❌ Breakdown would exceed 10-task limit (current: 8, proposed: 4)
-   Suggestion: Re-scope project into smaller iterations
+Breakdown would exceed 10-task limit (current: 8, proposed: 4)
+Suggestion: Re-scope project into smaller iterations
 
 # File conflicts detected
-⚠️ File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
-   Recommendation: Merge subtasks or redistribute files
+File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
+Recommendation: Merge subtasks or redistribute files
 
 # Similar functionality warning
-⚠️ Similar functions detected: "user login" and "authentication"
-   Consider consolidating related functionality
+Similar functions detected: "user login" and "authentication"
+Consider consolidating related functionality
 
 # Manual breakdown required
-❌ Automatic breakdown disabled. Use manual breakdown process.
+Automatic breakdown disabled. Use manual breakdown process.
 ```
 
-## Related Commands
-
-- `/task:create` - Create new tasks
-- `/task:execute` - Execute subtasks
-- `/workflow:status` - View task hierarchy
-- `/workflow:plan` - Plan within 10-task limit
-
 **System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance

.claude/commands/task/create.md

@@ -1,6 +1,6 @@
 ---
 name: create
-description: Create implementation tasks with automatic context awareness
+description: Generate task JSON from natural language description with automatic file pattern detection, scope inference, and dependency analysis
 argument-hint: "\"task title\""
 ---
 
@@ -37,7 +37,7 @@ Creates new implementation tasks with automatic context awareness and ID generat
 
 Output:
 ```
-✅ Task created: IMPL-1
+Task created: IMPL-1
 Title: Build authentication module
 Type: feature
 Agent: code-developer
@@ -73,7 +73,7 @@ Status: pending
 ### Analysis Triggers
 When implementation details incomplete:
 ```bash
-⚠️ Task requires analysis for implementation details
+Task requires analysis for implementation details
 Suggest running: gemini analysis for file locations and dependencies
 ```
 
@@ -104,7 +104,7 @@ Based on task type and title keywords:
 - **Design/Plan** → @planning-agent
 - **Test Generation** → @code-developer (type: "test-gen")
 - **Test Execution/Fix** → @test-fix-agent (type: "test-fix")
-- **Review/Audit** → @general-purpose (optional, only when explicitly requested)
+- **Review/Audit** → @universal-executor (optional, only when explicitly requested)
 
 ## Validation Rules
 
@@ -117,16 +117,16 @@ Based on task type and title keywords:
 
 ```bash
 # No workflow session
-❌ No active workflow found
-→ Use: /workflow init "project name"
+No active workflow found
+Use: /workflow init "project name"
 
 # Duplicate task
-⚠️ Similar task exists: IMPL-3
-→ Continue anyway? (y/n)
+Similar task exists: IMPL-3
+Continue anyway? (y/n)
 
 # Max depth exceeded
-❌ Cannot create IMPL-1.2.1 (max 2 levels)
-→ Use: IMPL-2 for new main task
+Cannot create IMPL-1.2.1 (max 2 levels)
+Use: IMPL-2 for new main task
 ```
 
 ## Examples
@@ -135,7 +135,7 @@ Based on task type and title keywords:
 ```bash
 /task:create "Implement user authentication"
 
-✅ Created IMPL-1: Implement user authentication
+Created IMPL-1: Implement user authentication
 Type: feature
 Agent: code-developer
 Status: pending
@@ -145,14 +145,8 @@ Status: pending
 ```bash
 /task:create "Fix login validation bug" --type=bugfix
 
-✅ Created IMPL-2: Fix login validation bug
+Created IMPL-2: Fix login validation bug
 Type: bugfix
 Agent: code-developer
 Status: pending
-```
-
-## Related Commands
-
-- `/task:breakdown` - Break into subtasks
-- `/task:execute` - Execute with agent
-- `/context` - View task details
+```

.claude/commands/task/execute.md

@@ -1,15 +1,15 @@
 ---
 name: execute
-description: Execute tasks with appropriate agents and context-aware orchestration
+description: Execute task JSON using appropriate agent (@doc-generator/@implementation-agent/@test-agent) with pre-analysis context loading and status tracking
 argument-hint: "task-id"
 ---
 
-### 🚀 **Command Overview: `/task:execute`**
+## Command Overview: /task:execute
 
--   **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
--   **Core Principles**: @~/.claude/workflows/workflow-architecture.md
+**Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
 
-### ⚙️ **Execution Modes**
+
+## Execution Modes
 
 -   **auto (Default)**
     -   Fully autonomous execution with automatic agent selection.
@@ -19,10 +19,10 @@ argument-hint: "task-id"
     -   Executes step-by-step, requiring user confirmation at each checkpoint.
     -   Allows for dynamic adjustments and manual review during the process.
 -   **review**
-    -   Optional manual review using `@general-purpose`.
+    -   Optional manual review using `@universal-executor`.
     -   Used only when explicitly requested by user.
 
-### 🤖 **Agent Selection Logic**
+## Agent Selection Logic
 
 The system determines the appropriate agent for a task using the following logic.
 
@@ -45,18 +45,18 @@ FUNCTION select_agent(task, agent_override):
             WHEN CONTAINS "Execute tests", "Fix tests", "Validate":
                 RETURN "@test-fix-agent" // type: test-fix
             WHEN CONTAINS "Review code":
-                RETURN "@general-purpose" // Optional manual review
+                RETURN "@universal-executor" // Optional manual review
             DEFAULT:
                 RETURN "@code-developer" // Default agent
         END CASE
 END FUNCTION
 ```
 
-### 🔄 **Core Execution Protocol**
+## Core Execution Protocol
 
-`Pre-Execution` **->** `Execution` **->** `Post-Execution`
+`Pre-Execution` -> `Execution` -> `Post-Execution`
 
-### ✅ **Pre-Execution Protocol**
+### Pre-Execution Protocol
 
 `Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite`
 
@@ -65,7 +65,7 @@ END FUNCTION
 -   **Session Context Injection**: Provides workflow directory paths to agents for TODO_LIST.md and summary management.
 -   **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`.
 
-### 🏁 **Post-Execution Protocol**
+### Post-Execution Protocol
 
 `Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity`
 
@@ -73,7 +73,7 @@ END FUNCTION
 -   Creates a summary in `.summaries/`.
 -   Stores outputs and syncs progress across the entire workflow session.
 
-### 🧠 **Task & Subtask Execution Logic**
+### Task & Subtask Execution Logic
 
 This logic defines how single, multiple, or parent tasks are handled.
 
@@ -99,7 +99,7 @@ FUNCTION execute_task_command(task_id, mode, parallel_flag):
 END FUNCTION
 ```
 
-### 🛡️ **Error Handling & Recovery Logic**
+### Error Handling & Recovery Logic
 
 ```pseudo
 FUNCTION pre_execution_check(task):
@@ -124,7 +124,7 @@ END FUNCTION
 ```
 
 
-### 📄 **Simplified Context Structure (JSON)**
+### Simplified Context Structure (JSON)
 
 This is the simplified data structure loaded to provide context for task execution.
 
@@ -189,7 +189,7 @@ This is the simplified data structure loaded to provide context for task executi
       "pre_analysis": [
         {
           "action": "analyze patterns",
-          "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt",
           "method": "gemini"
         }
       ]
@@ -213,7 +213,7 @@ This is the simplified data structure loaded to provide context for task executi
 }
 ```
 
-### 🎯 **Agent-Specific Context**
+### Agent-Specific Context
 
 Different agents receive context tailored to their function, including implementation details:
 
@@ -236,20 +236,20 @@ Different agents receive context tailored to their function, including implement
 - Error conditions to validate from implementation.context_notes.error_handling
 - Performance requirements from implementation.context_notes.performance_considerations
 
-**`@general-purpose`**:
+**`@universal-executor`**:
 - Used for optional manual reviews when explicitly requested
 - Code quality standards and implementation patterns
 - Security considerations from implementation.context_notes.risks
 - Dependency validation from implementation.context_notes.dependencies
 - Architecture compliance checks
 
-### 🗃️ **Simplified File Output**
+### Simplified File Output
 
 -   **Task JSON File (`.task/<task-id>.json`)**: Updated with status and last attempt time only.
 -   **Session File (`workflow-session.json`)**: Updated task stats (completed count).
 -   **Summary File**: Generated in `.summaries/` upon completion (optional).
 
-### 📝 **Simplified Summary Template**
+### Simplified Summary Template
 
 Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`.
 

.claude/commands/task/replan.md

@@ -1,6 +1,6 @@
 ---
 name: replan
-description: Replan individual tasks with detailed user input and change tracking
+description: Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json
 argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
@@ -24,7 +24,7 @@ Replans individual tasks or batch processes multiple tasks with change tracking
 - **Change Documentation**: Track all modifications
 - **Progress Tracking**: TodoWrite integration for batch operations
 
-⚠️ **CRITICAL**: Validates active session before replanning
+**CRITICAL**: Validates active session before replanning
 
 ## Operation Modes
 
@@ -189,7 +189,7 @@ AskUserQuestion({
 
 User selected: "Yes, rollback"
 
-✅ Task rolled back to version 1.1
+Task rolled back to version 1.1
 ```
 
 ## Batch Processing with TodoWrite
@@ -201,7 +201,7 @@ When processing multiple tasks, automatically creates TodoWrite task list:
 **Batch Replan Progress**:
 - [x] IMPL-002: Add FR-12 draft saving acceptance criteria
 - [x] IMPL-003: Add FR-14 history tracking acceptance criteria
-- [⧗] IMPL-004: Add FR-09 response surface explicit coverage
+- [ ] IMPL-004: Add FR-09 response surface explicit coverage
 - [ ] IMPL-008: Add NFR performance validation steps
 ```
 
@@ -255,9 +255,9 @@ AskUserQuestion({
 
 User selected: "Yes, apply"
 
-✓ Version 1.2 created
-✓ Context updated
-✓ Backup saved to .task/backup/IMPL-1-v1.1.json
+Version 1.2 created
+Context updated
+Backup saved to .task/backup/IMPL-1-v1.1.json
 ```
 
 ### Single Task - File Input
@@ -267,9 +267,9 @@ User selected: "Yes, apply"
 Loading requirements.md...
 Applying specification changes...
 
-✓ Task updated with new requirements
-✓ Version 1.1 created
-✓ Backup saved to .task/backup/IMPL-2-v1.0.json
+Task updated with new requirements
+Version 1.1 created
+Backup saved to .task/backup/IMPL-2-v1.0.json
 ```
 
 ### Batch Mode - From Verification Report
@@ -286,23 +286,23 @@ Found 4 tasks requiring replanning:
 Creating task tracking list...
 
 Processing IMPL-002...
-✓ Backup created: .task/backup/IMPL-002-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-002-v1.0.json
+Updated to v1.1
 
 Processing IMPL-003...
-✓ Backup created: .task/backup/IMPL-003-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-003-v1.0.json
+Updated to v1.1
 
 Processing IMPL-004...
-✓ Backup created: .task/backup/IMPL-004-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-004-v1.0.json
+Updated to v1.1
 
 Processing IMPL-008...
-✓ Backup created: .task/backup/IMPL-008-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-008-v1.0.json
+Updated to v1.1
 
-✅ Batch replan completed: 4/4 successful
-📋 Summary report saved
+Batch replan completed: 4/4 successful
+Summary report saved
 ```
 
 ### Batch Mode - Auto-detection
@@ -320,35 +320,35 @@ Entering batch mode...
 ### Single Task Errors
 ```bash
 # Task not found
-❌ Task IMPL-5 not found
-→ Check task ID with /workflow:status
+Task IMPL-5 not found
+Check task ID with /workflow:status
 
 # Task completed
-⚠️ Task IMPL-1 is completed (cannot replan)
-→ Create new task for additional work
+Task IMPL-1 is completed (cannot replan)
+Create new task for additional work
 
 # File not found
-❌ File requirements.md not found
-→ Check file path
+File requirements.md not found
+Check file path
 
 # No input provided
-❌ Please specify changes needed
-→ Provide text, file, or verification report
+Please specify changes needed
+Provide text, file, or verification report
 ```
 
 ### Batch Mode Errors
 ```bash
 # Invalid verification report
-❌ File does not contain valid verification report format
-→ Check report structure or use single task mode
+File does not contain valid verification report format
+Check report structure or use single task mode
 
 # Partial failures
-⚠️ Batch completed with errors: 3/4 successful
-→ Review error details in summary report
+Batch completed with errors: 3/4 successful
+Review error details in summary report
 
 # No replan recommendations found
-❌ Verification report contains no replan recommendations
-→ Check report content or use /workflow:action-plan-verify first
+Verification report contains no replan recommendations
+Check report content or use /workflow:action-plan-verify first
 ```
 
 ## Batch Mode Integration
@@ -429,16 +429,4 @@ TodoWrite({
 TodoWrite({
   todos: updateTaskStatus(taskId, "completed")
 });
-```
-
-## Related Commands
-
-- `/workflow:status` - View task structure and versions
-- `/workflow:action-plan-verify` - Generate verification report for batch mode
-- `/task:execute` - Execute replanned task
-- `/task:create` - Create new tasks
-- `/task:breakdown` - Break down complex tasks
-
-## Context
-
-$ARGUMENTS
+```

.claude/commands/version.md

@@ -1,6 +1,6 @@
 ---
 name: version
-description: Display version information and check for updates
+description: Display Claude Code version information and check for updates
 allowed-tools: Bash(*)
 ---
 
@@ -152,12 +152,12 @@ bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1)
 
 **Scenario 1: Up to date**
 ```
-✅ You are on the latest stable version (3.2.1)
+You are on the latest stable version (3.2.1)
 ```
 
 **Scenario 2: Upgrade available**
 ```
-⬆️ A newer stable version is available: v3.2.2
+A newer stable version is available: v3.2.2
 Your version: 3.2.1
 
 To upgrade:
@@ -167,7 +167,7 @@ Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-W
 
 **Scenario 3: Development version**
 ```
-✨ You are running a development version (3.4.0-dev)
+You are running a development version (3.4.0-dev)
 This is newer than the latest stable release (v3.3.0)
 ```
 
@@ -252,7 +252,3 @@ ERROR: version.json is invalid or corrupted
 
 ### Timeout Configuration
 All network calls should use `timeout: 30000` (30 seconds) to handle slow connections.
-
-## Related Commands
-- `/cli:cli-init` - Initialize CLI configurations
-- `/workflow:session:list` - List workflow sessions

.claude/commands/workflow/action-plan-verify.md

@@ -1,6 +1,6 @@
 ---
 name: action-plan-verify
-description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
+description: Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation
 argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
 ---
@@ -15,13 +15,13 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Goal
 
-Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`synthesis-specification.md`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
+Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
 
 ## Operating Constraints
 
 **STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
 
-**Synthesis Authority**: The `synthesis-specification.md` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
+**Synthesis Authority**: The `role analysis documents` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
 
 ## Execution Steps
 
@@ -45,13 +45,13 @@ brainstorm_dir = session_dir/.brainstorming
 task_dir = session_dir/.task
 
 # Validate required artifacts
-SYNTHESIS = brainstorm_dir/synthesis-specification.md
+SYNTHESIS = brainstorm_dir/role analysis documents
 IMPL_PLAN = session_dir/IMPL_PLAN.md
 TASK_FILES = Glob(task_dir/*.json)
 
 # Abort if missing
 IF NOT EXISTS(SYNTHESIS):
-    ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
+    ERROR: "role analysis documents not found. Run /workflow:brainstorm:synthesis first"
     EXIT
 
 IF NOT EXISTS(IMPL_PLAN):
@@ -72,7 +72,7 @@ Load only minimal necessary context from each artifact:
 - User's stated goals and objectives
 - User's scope definition
 
-**From synthesis-specification.md**:
+**From role analysis documents**:
 - Functional Requirements (IDs, descriptions, acceptance criteria)
 - Non-Functional Requirements (IDs, targets)
 - Business Requirements (IDs, success metrics)
@@ -210,7 +210,7 @@ Output a Markdown report (no file writes) with the following structure:
 
 **Session**: WFS-{session-id}
 **Generated**: {timestamp}
-**Artifacts Analyzed**: synthesis-specification.md, IMPL_PLAN.md, {N} task files
+**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files
 
 ---
 
@@ -242,10 +242,10 @@ Output a Markdown report (no file writes) with the following structure:
 
 | Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
 |----------------|---------------------|-----------|----------|----------------|-------|
-| FR-01 | User authentication | ✅ Yes | IMPL-1.1, IMPL-1.2 | ✅ Match | Complete |
-| FR-02 | Data export | ✅ Yes | IMPL-2.3 | ⚠️ Mismatch | High req → Med priority task |
-| FR-03 | Profile management | ❌ No | - | - | **CRITICAL: Zero coverage** |
-| NFR-01 | Response time <200ms | ❌ No | - | - | **HIGH: No performance tasks** |
+| FR-01 | User authentication | Yes | IMPL-1.1, IMPL-1.2 | Match | Complete |
+| FR-02 | Data export | Yes | IMPL-2.3 | Mismatch | High req → Med priority task |
+| FR-03 | Profile management | No | - | - | **CRITICAL: Zero coverage** |
+| NFR-01 | Response time <200ms | No | - | - | **HIGH: No performance tasks** |
 
 **Coverage Metrics**:
 - Functional Requirements: 85% (17/20 covered)
@@ -264,7 +264,7 @@ Output a Markdown report (no file writes) with the following structure:
 
 ### Dependency Graph Issues
 
-**Circular Dependencies**: None detected ✅
+**Circular Dependencies**: None detected
 
 **Broken Dependencies**:
 - IMPL-2.3 depends on "IMPL-2.4" (non-existent)
@@ -323,45 +323,41 @@ Output a Markdown report (no file writes) with the following structure:
 #### Action Recommendations
 
 **If CRITICAL Issues Exist**:
-- ❌ **BLOCK EXECUTION** - Resolve critical issues before proceeding
-- Use `/task:create` for missing requirements coverage
+- **BLOCK EXECUTION** - Resolve critical issues before proceeding
+- Use TodoWrite to track all required fixes
 - Fix broken dependencies and circular references
 
 **If Only HIGH/MEDIUM/LOW Issues**:
-- ⚠️ **PROCEED WITH CAUTION** - Fix high-priority issues first
-- Use batch replan mode to apply all task improvements systematically
+- **PROCEED WITH CAUTION** - Fix high-priority issues first
+- Use TodoWrite to systematically track and complete all improvements
 
-#### Batch Remediation
+#### TodoWrite-Based Remediation Workflow
 
 **Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
 
-**Apply All Task Improvements** (Recommended):
-```bash
-# Batch process all task replan recommendations
-/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+**Recommended Workflow**:
+1. **Create TodoWrite Task List**: Extract all findings from report
+2. **Process by Priority**: CRITICAL → HIGH → MEDIUM → LOW
+3. **Complete Each Fix**: Mark tasks as in_progress/completed as you work
+4. **Validate Changes**: Verify each modification against requirements
 
-# Or with auto-confirmation (no prompts)
-/task:replan --batch ACTION_PLAN_VERIFICATION.md --auto-confirm
-```
-
-**Manual Selective Fixes**:
-```bash
-# Fix critical coverage gaps first
-/task:create "Implement user authentication (FR-03)"
-/task:create "Add performance optimization (NFR-01)"
-
-# Then apply task refinements individually
-/task:replan IMPL-1.2 "Add context.artifacts and target_files"
+**TodoWrite Task Structure Example**:
+```markdown
+Priority Order:
+1. Fix coverage gaps (CRITICAL)
+2. Resolve consistency conflicts (CRITICAL/HIGH)
+3. Add missing specifications (MEDIUM)
+4. Improve task quality (LOW)
 ```
 
 **Notes**:
-- Batch mode extracts all `/task:replan` commands from report
-- Processes by priority: CRITICAL → HIGH → MEDIUM → LOW
-- Creates TodoWrite tracking for all modifications
+- TodoWrite provides real-time progress tracking
+- Each finding becomes a trackable todo item
+- User can monitor progress throughout remediation
 - Architecture drift in IMPL_PLAN requires manual editing
 ```
 
-### 7. Save Report and Provide Remediation Options
+### 7. Save Report and Execute TodoWrite-Based Remediation
 
 **Save Analysis Report**:
 ```bash
@@ -369,14 +365,53 @@ report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
 Write(report_path, full_report_content)
 ```
 
-At end of report, provide batch remediation guidance:
+**After Report Generation**:
+
+1. **Extract Findings**: Parse all issues by severity
+2. **Create TodoWrite Task List**: Convert findings to actionable todos
+3. **Execute Fixes**: Process each todo systematically
+4. **Update Task Files**: Apply modifications directly to task JSON files
+5. **Update IMPL_PLAN**: Apply strategic changes if needed
+
+At end of report, provide remediation guidance:
 
 ```markdown
-### 🔧 Remediation Options
+### 🔧 Remediation Workflow
 
-**Recommended Workflow**:
-1. **TodoWrite Tracking**: Create task list for all fixes
-2. **Agent-Based Fixes**: Call action-planning-agent to regenerate task files
-3. **User Confirmation**: Wait for approval before executing fixes
+**Recommended Approach**:
+1. **Initialize TodoWrite**: Create comprehensive task list from all findings
+2. **Process by Severity**: Start with CRITICAL, then HIGH, MEDIUM, LOW
+3. **Apply Fixes Directly**: Modify task.json files and IMPL_PLAN.md as needed
+4. **Track Progress**: Mark todos as completed after each fix
 
-**Note**: All fixes require explicit user confirmation.
+**TodoWrite Execution Pattern**:
+```bash
+# Step 1: Create task list from verification report
+TodoWrite([
+  { content: "Fix FR-03 coverage gap - add authentication task", status: "pending", activeForm: "Fixing FR-03 coverage gap" },
+  { content: "Fix IMPL-1.2 consistency - align with ADR-02", status: "pending", activeForm: "Fixing IMPL-1.2 consistency" },
+  { content: "Add context.artifacts to IMPL-1.2", status: "pending", activeForm: "Adding context.artifacts to IMPL-1.2" },
+  # ... additional todos for each finding
+])
+
+# Step 2: Process each todo systematically
+# Mark as in_progress when starting
+# Apply fix using Read/Edit tools
+# Mark as completed when done
+# Move to next priority item
+```
+
+**File Modification Workflow**:
+```bash
+# For task JSON modifications:
+1. Read(.workflow/WFS-{session}/.task/IMPL-X.Y.json)
+2. Edit() to apply fixes
+3. Mark todo as completed
+
+# For IMPL_PLAN modifications:
+1. Read(.workflow/WFS-{session}/IMPL_PLAN.md)
+2. Edit() to apply strategic changes
+3. Mark todo as completed
+```
+
+**Note**: All fixes execute immediately after user confirmation without additional commands.

.claude/commands/workflow/brainstorm/api-designer.md

@@ -1,6 +1,6 @@
 ---
 name: api-designer
-description: Generate or update api-designer/analysis.md addressing topic-framework discussion points
+description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🔌 **API Designer Analysis Generator**
 
 ### Purpose
-**Specialized command for generating api-designer/analysis.md** that addresses topic-framework.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating api-designer/analysis.md** that addresses guidance-specification.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -51,7 +51,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,20 +78,20 @@ ELSE:
 ```
 
 ### Phase 3: Agent Task Generation
-**Framework-Based Analysis** (when topic-framework.md exists):
+**Framework-Based Analysis** (when guidance-specification.md exists):
 ```bash
 Task(subagent_type="conceptual-planning-agent",
      prompt="Generate API designer analysis addressing topic framework
 
      ## Framework Integration Required
-     **MANDATORY**: Load and address topic-framework.md discussion points
-     **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+     **MANDATORY**: Load and address guidance-specification.md discussion points
+     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
      **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
 
      ## Analysis Requirements
-     1. **Load Topic Framework**: Read topic-framework.md completely
+     1. **Load Topic Framework**: Read guidance-specification.md completely
      2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
-     3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
+     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
      4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
      5. **Structured Response**: Use framework structure for analysis organization
 
@@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
      ```markdown
      # API Designer Analysis: [Topic]
 
-     **Framework Reference**: @../topic-framework.md
+     **Framework Reference**: @../guidance-specification.md
      **Role Focus**: Backend API Design and Contract Definition
 
      ## Core Requirements Analysis
@@ -140,14 +140,14 @@ IF update_mode = "incremental":
 
          ## Current Analysis Context
          **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
-         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
 
          ## Update Requirements
          1. **Preserve Structure**: Maintain existing analysis structure
          2. **Add New Insights**: Integrate new API design insights and recommendations
          3. **Framework Alignment**: Ensure continued alignment with topic framework
          4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
-         5. **Maintain References**: Keep @../topic-framework.md reference
+         5. **Maintain References**: Keep @../guidance-specification.md reference
 
          ## Update Instructions
          - Read existing analysis completely
@@ -163,14 +163,14 @@ IF update_mode = "incremental":
 ### Output Files
 ```
 .workflow/WFS-[topic]/.brainstorming/
-├── topic-framework.md          # Input: Framework (if exists)
+├── guidance-specification.md          # Input: Framework (if exists)
 └── api-designer/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
 ```
 
 ### Analysis Structure
 **Required Elements**:
-- **Framework Reference**: @../topic-framework.md (if framework exists)
+- **Framework Reference**: @../guidance-specification.md (if framework exists)
 - **Role Focus**: Backend API Design and Contract Definition perspective
 - **5 Framework Sections**: Address each framework discussion point
 - **API Design Recommendations**: Endpoint-specific insights and solutions

.claude/commands/workflow/brainstorm/artifacts.md

@@ -1,373 +1,605 @@
 ---
 name: artifacts
-description: Generate role-specific topic-framework.md dynamically based on selected roles
-argument-hint: "topic or challenge description for framework generation"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
+description: Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis
+argument-hint: "topic or challenge description [--count N]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---
 
-# Topic Framework Generator Command
+## Overview
 
-## Usage
-```bash
-/workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
+Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only).
+
+**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
+**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
+**Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates
+
+**Parameters**:
+- `topic` (required): Topic or challenge description (structured format recommended)
+- `--count N` (optional): Number of roles user WANTS to select (system will recommend N+2 options for user to choose from, default: 3)
+
+## Task Tracking
+
+**⚠️ TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite)
+
+**When called from auto-parallel**:
+- Find the artifacts parent task: "Execute artifacts command for interactive framework generation"
+- Mark parent task as "in_progress"
+- APPEND artifacts sub-tasks AFTER the parent task (Phase 0-5)
+- Mark each sub-task as it completes
+- When Phase 5 completes, mark parent task as "completed"
+- **PRESERVE all other auto-parallel tasks** (role agents, synthesis)
+
+**Standalone Mode**:
+```json
+[
+  {"content": "Initialize session (.workflow/.active-* check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
+  {"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"},
+  {"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"},
+  {"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"},
+  {"content": "Phase 3: Generate 3-4 questions per role, output and wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 3 role questions"},
+  {"content": "Phase 4: Detect conflicts, output clarifications, wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 4 conflict resolution"},
+  {"content": "Phase 5: Transform Q&A to declarative statements, write guidance-specification.md", "status": "pending", "activeForm": "Phase 5 document generation"}
+]
 ```
 
-**Recommended Structured Format**:
-```bash
-/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--roles "..."]
-```
+## User Interaction Protocol
 
-## Purpose
-**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas.
+### Question Output Format
 
-**⚠️ User Intent Preservation**: Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle.
+All questions output as structured text (detailed format with descriptions):
 
-## Role-Based Framework Generation
-
-**Dynamic Generation**: Framework content adapts based on selected roles
-- **With roles**: Generate targeted discussion points for specified roles only
-- **Without roles**: Generate comprehensive framework covering all common areas
-
-## Core Workflow
-
-### Topic Framework Generation Process
-
-**Phase 1: Session Management** ⚠️ FIRST STEP
-- **Active session detection**: Check `.workflow/.active-*` markers
-- **Session selection**: Prompt user if multiple active sessions found
-- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists
-- **Framework check**: Check if `topic-framework.md` exists (update vs create mode)
-
-**Phase 2: Role Analysis** ⚠️ NEW
-- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided
-- **Role validation**: Verify each role is valid (matches available role commands)
-- **Store role list**: Save selected roles to session metadata for reference
-- **Default behavior**: If no roles specified, use comprehensive coverage
-
-**Phase 3: Dynamic Topic Analysis**
-- **Scope definition**: Define topic boundaries and objectives
-- **Stakeholder identification**: Identify key users and stakeholders based on selected roles
-- **Requirements gathering**: Extract requirements relevant to selected roles
-- **Context collection**: Gather context appropriate for role perspectives
-
-**Phase 4: Role-Specific Framework Generation**
-- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles**
-- **Role-targeted questions**: Create questions specifically for chosen roles
-- **Framework document**: Generate `topic-framework.md` with role-specific sections
-- **Validation check**: Ensure framework addresses all selected role perspectives
-
-**Phase 5: Metadata Storage**
-- **Save role assignment**: Store selected roles in session metadata
-- **Framework versioning**: Track which roles framework addresses
-- **Update tracking**: Maintain role evolution if framework updated
-
-## Implementation Standards
-
-### Discussion-Driven Analysis
-**Interactive Approach**: Direct conversation and exploration without predefined role constraints
-
-**Process Flow**:
-1. **Topic introduction**: Understanding scope and context
-2. **Exploratory questioning**: Open-ended investigation
-3. **Component identification**: Breaking down into manageable pieces
-4. **Relationship analysis**: Understanding connections and dependencies
-5. **Documentation generation**: Structured capture of insights
-
-**Key Areas of Investigation**:
-- **Functional aspects**: What the topic needs to accomplish
-- **Technical considerations**: Implementation constraints and requirements
-- **User perspectives**: How different stakeholders are affected
-- **Business implications**: Cost, timeline, and strategic considerations
-- **Risk assessment**: Potential challenges and mitigation strategies
-
-### Document Generation Standards
-
-**Always Created**:
-- **discussion-summary.md**: Main conversation points and key insights
-- **component-analysis.md**: Detailed breakdown of topic components
-
-## Document Generation
-
-**Primary Output**: Single structured `topic-framework.md` document
-
-**Document Structure**:
-```
-.workflow/WFS-[topic]/.brainstorming/
-└── topic-framework.md          # ★ STRUCTURED FRAMEWORK DOCUMENT
-```
-
-**Note**: `workflow-session.json` is located at `.workflow/WFS-[topic]/workflow-session.json` (session root), not inside `.brainstorming/`.
-
-## Framework Template Structures
-
-### Dynamic Role-Based Framework
-
-Framework content adapts based on `--roles` parameter:
-
-#### Option 1: Specific Roles Provided
 ```markdown
-# [Topic] - Discussion Framework
+【问题{N} - {短标签}】{问题文本}
+a) {选项标签}
+   说明：{选项说明和影响}
+b) {选项标签}
+   说明：{选项说明和影响}
+c) {选项标签}
+   说明：{选项说明和影响}
 
-## Topic Overview
-- **Scope**: [Topic boundaries relevant to selected roles]
-- **Objectives**: [Goals from perspective of selected roles]
-- **Context**: [Background focusing on role-specific concerns]
-- **Target Roles**: ui-designer, system-architect, subject-matter-expert
-
-## Role-Specific Discussion Points
-
-### For UI Designer
-1. **User Interface Requirements**
-   - What interface components are needed?
-   - What user interactions must be supported?
-   - What visual design considerations apply?
-
-2. **User Experience Challenges**
-   - What are the key user journeys?
-   - What accessibility requirements exist?
-   - How to balance aesthetics with functionality?
-
-### For System Architect
-1. **Architecture Decisions**
-   - What architectural patterns fit this solution?
-   - What scalability requirements exist?
-   - How does this integrate with existing systems?
-
-2. **Technical Implementation**
-   - What technology stack is appropriate?
-   - What are the performance requirements?
-   - What dependencies must be managed?
-
-### For Subject Matter Expert
-1. **Domain Expertise & Standards**
-   - What industry standards and best practices apply?
-   - What regulatory compliance requirements exist?
-   - What domain-specific patterns should be followed?
-
-2. **Technical Quality & Risk**
-   - What technical debt considerations exist?
-   - What scalability and maintenance implications apply?
-   - What knowledge transfer and documentation is needed?
-
-## Cross-Role Integration Points
-- How do UI decisions impact architecture?
-- How does architecture constrain UI possibilities?
-- What domain standards affect both UI and architecture?
-
-## Framework Usage
-**For Role Agents**: Address your specific section + integration points
-**Reference Format**: @../topic-framework.md in your analysis.md
-**Update Process**: Use /workflow:brainstorm:artifacts to update
-
----
-*Generated for roles: ui-designer, system-architect, subject-matter-expert*
-*Last updated: [timestamp]*
+请回答：{N}a 或 {N}b 或 {N}c
 ```
 
-#### Option 2: No Roles Specified (Comprehensive)
+**Multi-select format** (Phase 2 role selection):
 ```markdown
-# [Topic] - Discussion Framework
+【角色选择】请选择 {count} 个角色参与头脑风暴分析
 
-## Topic Overview
-- **Scope**: [Comprehensive topic boundaries]
-- **Objectives**: [All-encompassing goals]
-- **Context**: [Full background and constraints]
-- **Stakeholders**: [All relevant parties]
+a) {role-name} ({中文名})
+   推荐理由：{基于topic的相关性说明}
+b) {role-name} ({中文名})
+   推荐理由：{基于topic的相关性说明}
+...
 
-## Core Discussion Areas
+支持格式：
+- 分别选择：2a 2c 2d (选择第2题的a、c、d选项)
+- 合并语法：2acd (选择a、c、d)
+- 逗号分隔：2a,c,d
 
-### 1. Requirements & Objectives
-- What are the fundamental requirements?
-- What are the critical success factors?
-- What constraints must be considered?
-
-### 2. Technical & Architecture
-- What are the technical challenges?
-- What architectural decisions are needed?
-- What integration points exist?
-
-### 3. User Experience & Design
-- Who are the primary users?
-- What are the key user journeys?
-- What usability requirements exist?
-
-### 4. Security & Compliance
-- What security requirements exist?
-- What compliance considerations apply?
-- What data protection is needed?
-
-### 5. Implementation & Operations
-- What are the implementation risks?
-- What resources are required?
-- How will this be maintained?
-
-## Available Role Perspectives
-Framework supports analysis from any of these roles:
-- **Technical**: system-architect, data-architect, subject-matter-expert
-- **Product & Design**: ui-designer, ux-expert, product-manager, product-owner
-- **Agile & Quality**: scrum-master, test-strategist
-
----
-*Comprehensive framework - adaptable to any role*
-*Last updated: [timestamp]*
+请输入选择：
 ```
 
-## Role-Specific Content Generation
+### Input Parsing Rules
 
-### Available Roles and Their Focus Areas
+**Supported formats** (intelligent parsing):
 
-**Technical Roles**:
-- `system-architect`: Architecture patterns, scalability, technology stack, integration
-- `data-architect`: Data modeling, processing workflows, analytics, storage
-- `subject-matter-expert`: Domain expertise, industry standards, compliance, best practices
+1. **Space-separated**: `1a 2b 3c` → Q1:a, Q2:b, Q3:c
+2. **Comma-separated**: `1a,2b,3c` → Q1:a, Q2:b, Q3:c
+3. **Multi-select combined**: `2abc` → Q2: options a,b,c
+4. **Multi-select spaces**: `2 a b c` → Q2: options a,b,c
+5. **Multi-select comma**: `2a,b,c` → Q2: options a,b,c
+6. **Natural language**: `问题1选a` → 1a (fallback parsing)
 
-**Product & Design Roles**:
-- `ui-designer`: User interface, visual design, interaction patterns, accessibility
-- `ux-expert`: User experience optimization, usability testing, interaction design, design systems
-- `product-manager`: Business value, feature prioritization, market positioning, roadmap
-- `product-owner`: Backlog management, user stories, acceptance criteria, stakeholder alignment
+**Parsing algorithm**:
+- Extract question numbers and option letters
+- Validate question numbers match output
+- Validate option letters exist for each question
+- If ambiguous/invalid, output example format and request re-input
 
-**Agile & Quality Roles**:
-- `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management
-- `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches
+**Error handling** (lenient):
+- Recognize common variations automatically
+- If parsing fails, show example and wait for clarification
+- Support re-input without penalty
 
-### Dynamic Discussion Point Generation
+### Batching Strategy
 
-**For each selected role, generate**:
-1. **2-3 core discussion areas** specific to that role's perspective
-2. **3-5 targeted questions** per discussion area
-3. **Cross-role integration points** showing how roles interact
+**Batch limits**:
+- **Default**: Maximum 10 questions per round
+- **Phase 2 (role selection)**: Display all recommended roles at once (count+2 roles)
+- **Auto-split**: If questions > 10, split into multiple rounds with clear round indicators
 
-**Example mapping**:
+**Round indicators**:
+```markdown
+===== 第 1 轮问题 (共2轮) =====
+【问题1 - ...】...
+【问题2 - ...】...
+...
+【问题10 - ...】...
+
+请回答 (格式: 1a 2b ... 10c)：
+```
+
+### Interaction Flow
+
+**Standard flow**:
+1. Output questions in formatted text
+2. Output expected input format example
+3. Wait for user input
+4. Parse input with intelligent matching
+5. If parsing succeeds → Store answers and continue
+6. If parsing fails → Show error, example, and wait for re-input
+
+**No question/option limits**: Text-based interaction removes previous 4-question and 4-option restrictions
+
+## Execution Phases
+
+### Session Management
+- Check `.workflow/.active-*` markers first
+- Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
+- Parse `--count N` parameter from user input (default: 3 if not specified)
+- Store decisions in `workflow-session.json` including count parameter
+
+### Phase 0: Automatic Project Context Collection
+
+**Goal**: Gather project architecture, documentation, and relevant code context BEFORE user interaction
+
+**Detection Mechanism** (execute first):
 ```javascript
-// If roles = ["ui-designer", "system-architect"]
-Generate:
-- UI Designer section: UI Requirements, UX Challenges
-- System Architect section: Architecture Decisions, Technical Implementation
-- Integration Points: UI↔Architecture dependencies
+// Check if context-package already exists
+const contextPackagePath = `.workflow/WFS-{session-id}/.process/context-package.json`;
+
+if (file_exists(contextPackagePath)) {
+  // Validate package
+  const package = Read(contextPackagePath);
+  if (package.metadata.session_id === session_id) {
+    console.log("✅ Valid context-package found, skipping Phase 0");
+    return; // Skip to Phase 1
+  }
+}
 ```
 
-### Framework Generation Examples
+**Implementation**: Invoke `context-search-agent` only if package doesn't exist
 
-#### Example 1: Architecture-Heavy Topic
-```bash
-/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,subject-matter-expert"
+```javascript
+Task(
+  subagent_type="context-search-agent",
+  description="Gather project context for brainstorm",
+  prompt=`
+You are executing as context-search-agent (.claude/agents/context-search-agent.md).
+
+## Execution Mode
+**BRAINSTORM MODE** (Lightweight) - Phase 1-2 only (skip deep analysis)
+
+## Session Information
+- **Session ID**: ${session_id}
+- **Task Description**: ${task_description}
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
+
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
+
+### Phase 1: Initialization & Pre-Analysis
+1. **Detection**: Check for existing context-package (early exit if valid)
+2. **Foundation**: Initialize code-index, get project structure, load docs
+3. **Analysis**: Extract keywords, determine scope, classify complexity
+
+### Phase 2: Multi-Source Context Discovery
+Execute all 3 discovery tracks:
+- **Track 1**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. Synthesize 3-source data (docs > code > web)
+3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+4. Perform conflict detection with risk assessment
+5. Generate and validate context-package.json
+
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy}
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] File relevance accuracy >80%
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files ≤50 (prioritize high-relevance)
+
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
+)
 ```
-**Generated framework focuses on**:
-- Service architecture and communication patterns
-- Data flow and storage strategies
-- Domain standards and best practices
 
-#### Example 2: User-Focused Topic
-```bash
-/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,ux-expert,product-manager"
+**Graceful Degradation**:
+- If agent fails: Log warning, continue to Phase 1 without project context
+- If package invalid: Re-run context-search-agent
+
+### Phase 1: Topic Analysis & Intent Classification
+
+**Goal**: Extract keywords/challenges to drive all subsequent question generation, **enriched by Phase 0 project context**
+
+**Steps**:
+1. **Load Phase 0 context** (if available):
+   - Read `.workflow/WFS-{session-id}/.process/context-package.json`
+   - Extract: tech_stack, existing modules, conflict_risk, relevant files
+
+2. **Deep topic analysis** (context-aware):
+   - Extract technical entities from topic + existing codebase
+   - Identify core challenges considering existing architecture
+   - Consider constraints (timeline/budget/compliance)
+   - Define success metrics based on current project state
+
+3. **Generate 2-4 context-aware probing questions**:
+   - Reference existing tech stack in questions
+   - Consider integration with existing modules
+   - Address identified conflict risks from Phase 0
+   - Target root challenges and trade-off priorities
+
+4. **User interaction**: Output questions using text format (see User Interaction Protocol), wait for user input
+
+5. **Parse user answers**: Use intelligent parsing to extract answers from user input (support multiple formats)
+
+6. **Storage**: Store answers to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers, project_context_used}`
+
+**Example Output**:
+```markdown
+===== Phase 1: 项目意图分析 =====
+
+【问题1 - 核心挑战】实时协作平台的主要技术挑战？
+a) 实时数据同步
+   说明：100+用户同时在线，状态同步复杂度高
+b) 可扩展性架构
+   说明：用户规模增长时的系统扩展能力
+c) 冲突解决机制
+   说明：多用户同时编辑的冲突处理策略
+
+【问题2 - 优先级】MVP阶段最关注的指标？
+a) 功能完整性
+   说明：实现所有核心功能
+b) 用户体验
+   说明：流畅的交互体验和响应速度
+c) 系统稳定性
+   说明：高可用性和数据一致性
+
+请回答 (格式: 1a 2b)：
 ```
-**Generated framework focuses on**:
-- Onboarding flow and UI components
-- User experience optimization and usability
-- Business value and success metrics
 
-#### Example 3: Agile Delivery Topic
-```bash
-/workflow:brainstorm:artifacts "Optimize sprint delivery process" --roles "scrum-master,product-owner,test-strategist"
+**User input examples**:
+- `1a 2c` → Q1:a, Q2:c
+- `1a,2c` → Q1:a, Q2:c
+
+**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
+
+### Phase 2: Role Selection
+
+**⚠️ CRITICAL**: User MUST interact to select roles. NEVER auto-select without user confirmation.
+
+**Available Roles**:
+- data-architect (数据架构师)
+- product-manager (产品经理)
+- product-owner (产品负责人)
+- scrum-master (敏捷教练)
+- subject-matter-expert (领域专家)
+- system-architect (系统架构师)
+- test-strategist (测试策略师)
+- ui-designer (UI 设计师)
+- ux-expert (UX 专家)
+
+**Steps**:
+1. **Intelligent role recommendation** (AI analysis):
+   - Analyze Phase 1 extracted keywords and challenges
+   - Use AI reasoning to determine most relevant roles for the specific topic
+   - Recommend count+2 roles (e.g., if user wants 3 roles, recommend 5 options)
+   - Provide clear rationale for each recommended role based on topic context
+
+2. **User selection** (text interaction):
+   - Output all recommended roles at once (no batching needed for count+2 roles)
+   - Display roles with labels and relevance rationale
+   - Wait for user input in multi-select format
+   - Parse user input (support multiple formats)
+   - **Storage**: Store selections to `session.selected_roles`
+
+**Example Output**:
+```markdown
+===== Phase 2: 角色选择 =====
+
+【角色选择】请选择 3 个角色参与头脑风暴分析
+
+a) system-architect (系统架构师)
+   推荐理由：实时同步架构设计和技术选型的核心角色
+b) ui-designer (UI设计师)
+   推荐理由：协作界面用户体验和实时状态展示
+c) product-manager (产品经理)
+   推荐理由：功能优先级和MVP范围决策
+d) data-architect (数据架构师)
+   推荐理由：数据同步模型和存储方案设计
+e) ux-expert (UX专家)
+   推荐理由：多用户协作交互流程优化
+
+支持格式：
+- 分别选择：2a 2c 2d (选择a、c、d)
+- 合并语法：2acd (选择a、c、d)
+- 逗号分隔：2a,c,d (选择a、c、d)
+
+请输入选择：
 ```
-**Generated framework focuses on**:
-- Sprint planning and team collaboration
-- Backlog management and prioritization
-- Quality assurance and testing strategies
 
-#### Example 4: Comprehensive Analysis
-```bash
-/workflow:brainstorm:artifacts "Build real-time collaboration feature"
+**User input examples**:
+- `2acd` → Roles: a, c, d (system-architect, product-manager, data-architect)
+- `2a 2c 2d` → Same result
+- `2a,c,d` → Same result
+
+**Role Recommendation Rules**:
+- NO hardcoded keyword-to-role mappings
+- Use intelligent analysis of topic, challenges, and requirements
+- Consider role synergies and coverage gaps
+- Explain WHY each role is relevant to THIS specific topic
+- Default recommendation: count+2 roles for user to choose from
+
+### Phase 3: Role-Specific Questions (Dynamic Generation)
+
+**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges
+
+**Algorithm**:
 ```
-**Generated framework covers** all aspects (no roles specified)
+FOR each selected role:
+  1. Map Phase 1 challenges to role domain:
+     - "real-time sync" + system-architect → State management pattern
+     - "100 users" + system-architect → Communication protocol
+     - "low latency" + system-architect → Conflict resolution
 
-## Session Management ⚠️ CRITICAL
-- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing
-- **Multiple sessions support**: Different Claude instances can have different active sessions
-- **User selection**: If multiple active sessions found, prompt user to select which one to work with
-- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
-- **Session continuity**: MUST use selected active session for all processing
-- **Context preservation**: All discussion and analysis stored in session directory
-- **Session isolation**: Each session maintains independent state
+  2. Generate 3-4 questions per role probing implementation depth, trade-offs, edge cases:
+     Q: "How handle real-time state sync for 100+ users?" (explores approach)
+     Q: "How resolve conflicts when 2 users edit simultaneously?" (explores edge case)
+     Options: [Event Sourcing/Centralized/CRDT] (concrete, explain trade-offs for THIS use case)
 
-## Discussion Areas
+  3. Output questions in text format per role:
+     - Display all questions for current role (3-4 questions, no 10-question limit)
+     - Questions in Chinese (用中文提问)
+     - Wait for user input
+     - Parse answers using intelligent parsing
+     - Store answers to session.role_decisions[role]
+```
 
-### Core Investigation Topics
-- **Purpose & Goals**: What are we trying to achieve?
-- **Scope & Boundaries**: What's included and excluded?
-- **Success Criteria**: How do we measure success?
-- **Constraints**: What limitations exist?
-- **Stakeholders**: Who is affected or involved?
+**Batching Strategy**:
+- Each role outputs all its questions at once (typically 3-4 questions)
+- No need to split per role (within 10-question batch limit)
+- Multiple roles processed sequentially (one role at a time for clarity)
 
-### Technical Considerations
-- **Requirements**: What must the solution provide?
-- **Dependencies**: What does it rely on?
-- **Integration**: How does it connect to existing systems?
-- **Performance**: What are the speed/scale requirements?
-- **Security**: What protection is needed?
+**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format)
 
-### Implementation Factors
-- **Timeline**: When is it needed?
-- **Resources**: What people/budget/tools are available?
-- **Risks**: What could go wrong?
-- **Alternatives**: What other approaches exist?
-- **Migration**: How do we transition from current state?
+**Example Topic-Specific Questions** (system-architect role for "real-time collaboration platform"):
+- "100+ 用户实时状态同步方案?" → Options: Event Sourcing / 集中式状态管理 / CRDT
+- "两个用户同时编辑冲突如何解决?" → Options: 自动合并 / 手动解决 / 版本控制
+- "低延迟通信协议选择?" → Options: WebSocket / SSE / 轮询
+- "系统扩展性架构方案?" → Options: 微服务 / 单体+缓存 / Serverless
 
-## Update Mechanism ⚠️ SMART UPDATES
+**Quality Requirements**: See "Question Generation Guidelines" section for detailed rules
 
-### Framework Update Logic
-```bash
-# Check existing framework
-IF topic-framework.md EXISTS:
-    SHOW current framework to user
-    ASK: "Framework exists. Do you want to:"
-    OPTIONS:
-      1. "Replace completely" → Generate new framework
-      2. "Add discussion points" → Append to existing
-      3. "Refine existing points" → Interactive editing
-      4. "Cancel" → Exit without changes
+### Phase 4: Cross-Role Clarification (Conflict Detection)
+
+**Goal**: Resolve ACTUAL conflicts from Phase 3 answers, not pre-defined relationships
+
+**Algorithm**:
+```
+1. Analyze Phase 3 answers for conflicts:
+   - Contradictory choices: product-manager "fast iteration" vs system-architect "complex Event Sourcing"
+   - Missing integration: ui-designer "Optimistic updates" but system-architect didn't address conflict handling
+   - Implicit dependencies: ui-designer "Live cursors" but no auth approach defined
+
+2. FOR each detected conflict:
+   Generate clarification questions referencing SPECIFIC Phase 3 choices
+
+3. Output clarification questions in text format:
+   - Batch conflicts into rounds (max 10 questions per round)
+   - Display questions with context from Phase 3 answers
+   - Questions in Chinese (用中文提问)
+   - Wait for user input
+   - Parse answers using intelligent parsing
+   - Store answers to session.cross_role_decisions
+
+4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4")
+```
+
+**Batching Strategy**:
+- Maximum 10 clarification questions per round
+- If conflicts > 10, split into multiple rounds
+- Prioritize most critical conflicts first
+
+**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format with background context)
+
+**Example Conflict Detection** (from Phase 3 answers):
+- **Architecture Conflict**: "CRDT 与 UI 回滚期望冲突，如何解决?"
+  - Background: system-architect chose CRDT, ui-designer expects rollback UI
+  - Options: 采用 CRDT / 显示合并界面 / 切换到 OT
+- **Integration Gap**: "实时光标功能缺少身份认证方案"
+  - Background: ui-designer chose live cursors, no auth defined
+  - Options: OAuth 2.0 / JWT Token / Session-based
+
+**Quality Requirements**: See "Question Generation Guidelines" section for conflict-specific rules
+
+### Phase 5: Generate Guidance Specification
+
+**Steps**:
+1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions`
+2. Transform Q&A pairs to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
+3. Generate guidance-specification.md (template below) - **PRIMARY OUTPUT FILE**
+4. Update workflow-session.json with **METADATA ONLY**:
+   - session_id (e.g., "WFS-topic-slug")
+   - selected_roles[] (array of role names, e.g., ["system-architect", "ui-designer", "product-manager"])
+   - topic (original user input string)
+   - timestamp (ISO-8601 format)
+   - phase_completed: "artifacts"
+   - count_parameter (number from --count flag)
+5. Validate: No interrogative sentences in .md file, all decisions traceable, no content duplication in .json
+
+**⚠️ CRITICAL OUTPUT SEPARATION**:
+- **guidance-specification.md**: Full guidance content (decisions, rationale, integration points)
+- **workflow-session.json**: Session metadata ONLY (no guidance content, no decisions, no Q&A pairs)
+- **NO content duplication**: Guidance stays in .md, metadata stays in .json
+
+## Output Document Template
+
+**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
+
+```markdown
+# [Project] - Confirmed Guidance Specification
+
+**Metadata**: [timestamp, type, focus, roles]
+
+## 1. Project Positioning & Goals
+**CONFIRMED Objectives**: [from topic + Phase 1]
+**CONFIRMED Success Criteria**: [from Phase 1 answers]
+
+## 2-N. [Role] Decisions
+### SELECTED Choices
+**[Question topic]**: [User's answer]
+- **Rationale**: [From option description]
+- **Impact**: [Implications]
+
+### Cross-Role Considerations
+**[Conflict resolved]**: [Resolution from Phase 4]
+- **Affected Roles**: [Roles involved]
+
+## Cross-Role Integration
+**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
+
+## Risks & Constraints
+**Identified Risks**: [From answers] → Mitigation: [Approach]
+
+## Next Steps
+**⚠️ Automatic Continuation** (when called from auto-parallel):
+- auto-parallel will assign agents to generate role-specific analysis documents
+- Each selected role gets dedicated conceptual-planning-agent
+- Agents read this guidance-specification.md for framework context
+
+## Appendix: Decision Tracking
+| Decision ID | Category | Question | Selected | Phase | Rationale |
+|-------------|----------|----------|----------|-------|-----------|
+| D-001 | Intent | [Q] | [A] | 1 | [Why] |
+| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] |
+| D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
+```
+
+## Question Generation Guidelines
+
+### Core Principle: Developer-Facing Questions with User Context
+
+**Target Audience**: 开发者（理解技术但需要从用户需求出发）
+
+**Generation Philosophy**:
+1. **Phase 1**: 用户场景、业务约束、优先级（建立上下文）
+2. **Phase 2**: 基于话题分析的智能角色推荐（非关键词映射）
+3. **Phase 3**: 业务需求 + 技术选型（需求驱动的技术决策）
+4. **Phase 4**: 技术冲突的业务权衡（帮助开发者理解影响）
+
+### Universal Quality Rules
+
+**Question Structure** (all phases):
+```
+[业务场景/需求前提] + [技术关注点]
+```
+
+**Option Structure** (all phases):
+```
+标签：[技术方案简称] + (业务特征)
+说明：[业务影响] + [技术权衡]
+```
+
+**MUST Include** (all phases):
+- ✅ All questions in Chinese (用中文提问)
+- ✅ 业务场景作为问题前提
+- ✅ 技术选项的业务影响说明
+- ✅ 量化指标和约束条件
+
+**MUST Avoid** (all phases):
+- ❌ 纯技术选型无业务上下文
+- ❌ 过度抽象的用户体验问题
+- ❌ 脱离话题的通用架构问题
+
+### Phase-Specific Requirements
+
+**Phase 1 Requirements**:
+- Questions MUST reference topic keywords (NOT generic "Project type?")
+- Focus: 用户使用场景（谁用？怎么用？多频繁？）、业务约束（预算、时间、团队、合规）
+- Success metrics: 性能指标、用户体验目标
+- Priority ranking: MVP vs 长期规划
+
+**Phase 3 Requirements**:
+- Questions MUST reference Phase 1 keywords (e.g., "real-time", "100 users")
+- Options MUST be concrete approaches with relevance to topic
+- Each option includes trade-offs specific to this use case
+- Include 业务需求驱动的技术问题、量化指标（并发数、延迟、可用性）
+
+**Phase 4 Requirements**:
+- Questions MUST reference SPECIFIC Phase 3 choices in background context
+- Options address the detected conflict directly
+- Each option explains impact on both conflicting roles
+- NEVER use static "Cross-Role Matrix" - ALWAYS analyze actual Phase 3 answers
+- Focus: 技术冲突的业务权衡、帮助开发者理解不同选择的影响
+
+## Validation Checklist
+
+Generated guidance-specification.md MUST:
+- ✅ No interrogative sentences (use CONFIRMED/SELECTED)
+- ✅ Every decision traceable to user answer
+- ✅ Cross-role conflicts resolved or documented
+- ✅ Next steps concrete and specific
+- ✅ All Phase 1-4 decisions in session metadata
+
+## Update Mechanism
+
+```
+IF guidance-specification.md EXISTS:
+  Prompt: "Regenerate completely / Update sections / Cancel"
 ELSE:
-    CREATE new framework
+  Run full Phase 1-5 flow
 ```
 
-### Update Strategies
+## Governance Rules
 
-**1. Complete Replacement**
-- Backup existing framework as `topic-framework-[timestamp].md.backup`
-- Generate completely new framework
-- Preserve role-specific analysis points from previous version
+**Output Requirements**:
+- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections)
+- Every decision MUST trace to user answer
+- Conflicts MUST be resolved (not marked "TBD")
+- Next steps MUST be actionable
+- Topic preserved as authoritative reference in session
 
-**2. Incremental Addition**
-- Load existing framework
-- Identify new discussion areas through user interaction
-- Add new sections while preserving existing structure
-- Update framework usage instructions
+**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance.
 
-**3. Refinement Mode**
-- Interactive editing of existing discussion points
-- Allow modification of scope, objectives, and questions
-- Preserve framework structure and role assignments
-- Update timestamp and version info
+## Storage Validation
 
-### Version Control
-- **Backup Creation**: Always backup before major changes
-- **Change Tracking**: Include change summary in framework footer
-- **Rollback Support**: Keep previous version accessible
+**workflow-session.json** (metadata only):
+```json
+{
+  "session_id": "WFS-{topic-slug}",
+  "type": "brainstorming",
+  "topic": "{original user input}",
+  "selected_roles": ["system-architect", "ui-designer", "product-manager"],
+  "phase_completed": "artifacts",
+  "timestamp": "2025-10-24T10:30:00Z",
+  "count_parameter": 3
+}
+```
 
-## Error Handling
-- **Session creation failure**: Provide clear error message and retry option
-- **Discussion stalling**: Offer structured prompts to continue exploration
-- **Documentation issues**: Graceful handling of file creation problems
-- **Missing context**: Prompt for additional information when needed
+**⚠️ Rule**: Session JSON stores ONLY metadata (session_id, selected_roles[], topic, timestamps). All guidance content goes to guidance-specification.md.
 
-## Reference Information
+## File Structure
 
-### File Structure Reference
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
-**Session Management**: Standard workflow session protocols
+```
+.workflow/WFS-[topic]/
+├── .active-brainstorming
+├── workflow-session.json              # Session metadata ONLY
+└── .brainstorming/
+    └── guidance-specification.md      # Full guidance content
+```
 
-### Integration Points
-- **Compatible with**: Other brainstorming commands in the same session
-- **Builds foundation for**: More detailed planning and implementation phases
-- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration

.claude/commands/workflow/brainstorm/auto-parallel.md

@@ -1,13 +1,42 @@
 ---
 name: auto-parallel
-description: Parallel brainstorming automation with dynamic role selection and concurrent execution
+description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives
 argument-hint: "topic or challenge description" [--count N]
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
 # Workflow Brainstorm Parallel Auto Command
 
+## Coordinator Role
+
+**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
+
+**Execution Model - Auto-Continue Workflow**:
+
+This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
+
+1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
+2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
+3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
+4. **Phase 3 executes** → Synthesis command → Reports final summary
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status
+- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
+- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
+- Progress updates shown at each phase for visibility
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
+2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
+3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
+6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
+
 ## Usage
+
 ```bash
 /workflow:brainstorm:auto-parallel "<topic>" [--count N]
 ```
@@ -19,360 +48,293 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 **Parameters**:
 - `topic` (required): Topic or challenge description (structured format recommended)
-- `--count N` (optional): Number of roles to auto-select (default: 3, max: 9)
+- `--count N` (optional): Number of roles to select (default: 3, max: 9)
 
-**⚠️ User Intent Preservation**: Topic description is stored in session metadata as authoritative reference throughout entire brainstorming workflow and plan generation.
+## 3-Phase Execution
 
-## Role Selection Logic
-- **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert, subject-matter-expert
-- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
-- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, user-researcher, product-manager, ux-expert, product-owner
-- **Business & Process**: `business|process|workflow|cost|innovation|testing` → business-analyst, innovation-lead, test-strategist
-- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
-- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Multi-role**: Complex topics automatically select N complementary roles (N specified by --count, default 3)
-- **Default**: `product-manager` if no clear match
-- **Count Parameter**: `--count N` determines number of roles to auto-select (default: 3, max: 9)
+### Phase 1: Interactive Framework Generation
 
-**Template Loading**: `bash($(cat "~/.claude/workflows/cli-templates/planning-roles/<role-name>.md"))`
-**Template Source**: `.claude/workflows/cli-templates/planning-roles/`
-**Available Roles**: api-designer, data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")`
 
-**Example**:
+**What It Does**:
+- Topic analysis: Extract challenges, generate task-specific questions
+- Role selection: Recommend count+2 roles, user selects via AskUserQuestion
+- Role questions: Generate 3-4 questions per role, collect user decisions
+- Conflict resolution: Detect and resolve cross-role conflicts
+- Guidance generation: Transform Q&A to declarative guidance-specification.md
+
+**Parse Output**:
+- **⚠️ Memory Check**: If `selected_roles[]` already in conversation memory from previous load, skip file read
+- Extract: `selected_roles[]` from workflow-session.json (if not in memory)
+- Extract: `session_id` from workflow-session.json (if not in memory)
+- Verify: guidance-specification.md exists
+
+**Validation**:
+- guidance-specification.md created with confirmed decisions
+- workflow-session.json contains selected_roles[] (metadata only, no content duplication)
+- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
+
+**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
+- Marking parent task "Execute artifacts..." as in_progress
+- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
+- PRESERVING all other auto-parallel tasks (role agents, synthesis)
+- When artifacts Phase 5 completes, marking parent task as completed
+
+---
+
+### Phase 2: Parallel Role Analysis Execution
+
+**For Each Selected Role**:
 ```bash
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/system-architect.md"))
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute {role-name} analysis for existing topic framework
+
+## Context Loading
+ASSIGNED_ROLE: {role-name}
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/{role}/
+TOPIC: {user-provided-topic}
+
+## Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic discussion framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
+   - Output: topic_framework_content
+
+2. **load_role_template**
+   - Action: Load {role-name} planning template
+   - Command: Read(~/.claude/workflows/cli-templates/planning-roles/{role}.md)
+   - Output: role_template_guidelines
+
+3. **load_session_metadata**
+   - Action: Load session metadata and original user intent
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Output: session_context (contains original user prompt as PRIMARY reference)
+
+## Analysis Requirements
+**Primary Reference**: Original user prompt from workflow-session.json is authoritative
+**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
+**Role Focus**: {role-name} domain expertise aligned with user intent
+**Structured Approach**: Create analysis.md addressing framework discussion points
+**Template Integration**: Apply role template guidelines within framework structure
+
+## Expected Deliverables
+1. **analysis.md**: Comprehensive {role-name} analysis addressing all framework discussion points
+   - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+   - **FORBIDDEN**: Never use `recommendations.md` or any filename not starting with `analysis`
+   - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
+   - **Content**: Includes both analysis AND recommendations sections within analysis files
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
+3. **User Intent Alignment**: Validate analysis aligns with original user objectives from session_context
+
+## Completion Criteria
+- Address each discussion point from guidance-specification.md with {role-name} expertise
+- Provide actionable recommendations from {role-name} perspective within analysis files
+- All output files MUST start with `analysis` prefix (no recommendations.md or other naming)
+- Reference framework document using @ notation for integration
+- Update workflow-session.json with completion status
+"
 ```
 
-## Core Workflow
+**Parallel Execution**:
+- Launch N agents simultaneously (one message with multiple Task calls)
+- Each agent operates independently reading same guidance-specification.md
+- All agents update progress concurrently
 
-### Structured Topic Processing → Role Analysis → Synthesis
-The command follows a structured three-phase approach with dedicated document types:
+**Input**:
+- `selected_roles[]` from Phase 1
+- `session_id` from Phase 1
+- guidance-specification.md path
 
-**Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
-- **Role selection**: Auto-select N roles based on topic keywords and --count parameter (default: 3, see Role Selection Logic)
-- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,...,roleN}"` using SlashCommand tool
-- **Role-specific framework**: Generate framework with sections tailored to selected roles
-- **⚠️ User intent storage**: Topic saved in workflow-session.json as primary reference for all downstream phases
+**Validation**:
+- Each role creates `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
+- If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
+- **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing)
+- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
+- All N role analyses completed
 
-**Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
-- **Parallel execution**: Multiple roles execute simultaneously for faster completion
-- **Independent agents**: Each role gets dedicated conceptual-planning-agent running in parallel
-- **Shared framework**: All roles reference the same topic framework for consistency
-- **Concurrent generation**: Role-specific analysis documents generated simultaneously
-- **Progress tracking**: Parallel agents update progress independently
+**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
 
-**Phase 3: Synthesis Generation** ⚠️ COMMAND EXECUTION
-- **Call synthesis command**: Execute `/workflow:brainstorm:synthesis` using SlashCommand tool
-- **⚠️ User intent injection**: Synthesis loads original topic from session metadata as highest priority reference
-- **Intent alignment**: Synthesis validates all role insights against user's original objectives
+**After Phase 2**: Auto-continue to Phase 3 (synthesis)
 
-## Implementation Standards
+---
 
-### Simplified Command Orchestration ⚠️ STREAMLINED
-Auto command coordinates independent specialized commands:
+### Phase 3: Synthesis Generation
 
-**Command Sequence**:
-1. **Role Selection**: Auto-select N relevant roles based on topic keywords and --count parameter (default: 3)
-2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,...,roleN}"` (stores user intent in session)
-3. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading their specific framework section
-4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis` (loads user intent from session as primary reference)
+**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")`
 
-**SlashCommand Integration**:
-1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
-2. **role agents**: Each agent reads its dedicated section in the role-specific framework
-3. **synthesis command**: Called via SlashCommand tool for final integration with role-targeted insights
-4. **Command coordination**: SlashCommand handles execution and validation
+**What It Does**:
+- Load original user intent from workflow-session.json
+- Read all role analysis.md files
+- Integrate role insights into synthesis-specification.md
+- Validate alignment with user's original objectives
 
-**Role Selection Logic**:
-- **Technical**: `architecture|system|performance|database` → system-architect, data-architect, subject-matter-expert
-- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
-- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, ux-expert, product-manager, product-owner
-- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
-- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Auto-select**: N most relevant roles based on topic analysis (N from --count parameter, default: 3)
+**Input**: `sessionId` from Phase 1
 
-### Parameter Parsing
+**Validation**:
+- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
+- Synthesis references all role analyses
 
-**Count Parameter Handling**:
-```bash
-# Parse --count parameter from user input
+**TodoWrite**: Mark phase 3 completed
+
+**Return to User**:
+```
+Brainstorming complete for session: {sessionId}
+Roles analyzed: {count}
+Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
+
+✅ Next Steps:
+1. /workflow:concept-clarify --session {sessionId}  # Optional refinement
+2. /workflow:plan --session {sessionId}  # Generate implementation plan
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
+  // Role agent tasks added dynamically after Phase 1 based on selected_roles count
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 1 (artifacts completes, roles loaded)
+// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
+TodoWrite({todos: [
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
+  // ... (N role tasks based on --count parameter)
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 2 (all agents launched in parallel)
+TodoWrite({todos: [
+  // ... previous completed tasks
+  {"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  // ... (all N agents in_progress simultaneously)
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 2 (all agents complete)
+TodoWrite({todos: [
+  // ... previous completed tasks
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
+  {"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
+]})
+```
+
+## Input Processing
+
+**Count Parameter Parsing**:
+```javascript
+// Extract --count from user input
 IF user_input CONTAINS "--count":
     EXTRACT count_value FROM "--count N" pattern
     IF count_value > 9:
-        count_value = 9  # Cap at maximum 9 roles
-    END IF
+        count_value = 9  // Cap at maximum 9 roles
 ELSE:
-    count_value = 3  # Default to 3 roles
-END IF
+    count_value = 3  // Default to 3 roles
+
+// Pass to artifacts command
+EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 ```
 
-**Role Selection with Count**:
-1. **Analyze topic keywords**: Identify relevant role categories
-2. **Rank roles by relevance**: Score based on keyword matches
-3. **Select top N roles**: Pick N most relevant roles (N = count_value)
-4. **Ensure diversity**: Balance across different expertise areas
-5. **Minimum guarantee**: Always include at least one role (default to product-manager if no matches)
+**Topic Structuring**:
+1. **Already Structured** → Pass directly to artifacts
+   ```
+   User: "GOAL: Build platform SCOPE: 100 users CONTEXT: Real-time"
+   → Pass as-is to artifacts
+   ```
 
-### Simplified Processing Standards
+2. **Simple Text** → Pass directly (artifacts handles structuring)
+   ```
+   User: "Build collaboration platform"
+   → artifacts will analyze and structure
+   ```
 
-**Core Principles**:
-1. **Minimal preprocessing** - Only workflow-session.json and basic role selection
-2. **Agent autonomy** - Agents handle their own context and validation
-3. **Parallel execution** - Multiple agents can work simultaneously
-4. **Post-processing synthesis** - Integration happens after agent completion
-5. **TodoWrite control** - Progress tracking throughout all phases
+## Session Management
 
-**Implementation Rules**:
-- **Role count**: N roles auto-selected based on --count parameter (default: 3, max: 9) and keyword mapping
-- **No upfront validation**: Agents handle their own context requirements
-- **Parallel execution**: Each agent operates concurrently without dependencies
-- **Synthesis at end**: Integration only after all agents complete
+**⚡ FIRST ACTION**: Check for `.workflow/.active-*` markers before Phase 1
 
-**Agent Self-Management** (Agents decide their own approach):
-- **Context gathering**: Agents determine what questions to ask
-- **Template usage**: Agents load and apply their own role templates
-- **Analysis depth**: Agents determine appropriate level of detail
-- **Documentation**: Agents create their own file structure and content
+**Multiple Sessions Support**:
+- Different Claude instances can have different active brainstorming sessions
+- If multiple active sessions found, prompt user to select
+- If single active session found, use it
+- If no active session exists, create `WFS-[topic-slug]`
 
-### Session Management ⚠️ CRITICAL
-- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before role processing
-- **Multiple sessions support**: Different Claude instances can have different active brainstorming sessions
-- **User selection**: If multiple active sessions found, prompt user to select which one to work with
-- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
-- **Session continuity**: MUST use selected active session for all role processing
-- **Context preservation**: Each role's context and agent output stored in session directory
-- **Session isolation**: Each session maintains independent brainstorming state and role assignments
+**Session Continuity**:
+- MUST use selected active session for all phases
+- Each role's context stored in session directory
+- Session isolation: Each session maintains independent state
 
-## Document Generation
+## Output Structure
 
-**Command Coordination Workflow**: artifacts → parallel role analysis → synthesis
+**Phase 1 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
+- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
 
-**Output Structure**: Coordinated commands generate framework, role analyses, and synthesis documents as defined in their respective command specifications.
+**Phase 2 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
 
+**Phase 3 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
 
-## Agent Prompt Templates
+**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
 
-### Task Agent Invocation Template
+## Available Roles
 
+- data-architect (数据架构师)
+- product-manager (产品经理)
+- product-owner (产品负责人)
+- scrum-master (敏捷教练)
+- subject-matter-expert (领域专家)
+- system-architect (系统架构师)
+- test-strategist (测试策略师)
+- ui-designer (UI 设计师)
+- ux-expert (UX 专家)
 
-```bash
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: {role-name} perspective for {topic}
+**Role Selection**: Handled by artifacts command (intelligent recommendation + user selection)
 
-     ## Role Assignment
-     **ASSIGNED_ROLE**: {role-name}
-     **TOPIC**: {user-provided-topic}
-     **OUTPUT_LOCATION**: .workflow/WFS-{topic}/.brainstorming/{role}/
+## Error Handling
 
-     ## Execution Instructions
-     [FLOW_CONTROL]
-
-     ### Flow Control Steps
-     **AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
-
-     1. **load_topic_framework**
-        - Action: Load structured topic discussion framework
-        - Command: bash(cat .workflow/WFS-{topic}/.brainstorming/topic-framework.md 2>/dev/null || echo 'Topic framework not found')
-        - Output: topic_framework
-
-     2. **load_role_template**
-        - Action: Load {role-name} planning template
-        - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
-        - Output: role_template
-
-     3. **load_session_metadata**
-        - Action: Load session metadata and original user intent
-        - Command: bash(cat .workflow/WFS-{topic}/workflow-session.json 2>/dev/null || echo '{}')
-        - Output: session_metadata (contains original user prompt in 'project' or 'description' field)
-
-     ### Implementation Context
-     **⚠️ User Intent Authority**: Original user prompt from session_metadata.project is PRIMARY reference
-     **Topic Framework**: Use loaded topic-framework.md for structured analysis
-     **Role Focus**: {role-name} domain expertise and perspective aligned with user intent
-     **Analysis Type**: Address framework discussion points from role perspective, filtered by user objectives
-     **Template Framework**: Combine role template with topic framework structure
-     **Structured Approach**: Create analysis.md addressing all topic framework points relevant to user's goals
-
-     ### Session Context
-     **Workflow Directory**: .workflow/WFS-{topic}/.brainstorming/
-     **Output Directory**: .workflow/WFS-{topic}/.brainstorming/{role}/
-     **Session JSON**: .workflow/WFS-{topic}/workflow-session.json
-
-     ### Dependencies & Context
-     **Topic**: {user-provided-topic}
-     **Role Template**: "~/.claude/workflows/cli-templates/planning-roles/{role}.md"
-     **User Requirements**: To be gathered through interactive questioning
-
-     ## Completion Requirements
-     1. Execute all flow control steps in sequence (load topic framework, role template, session metadata with user intent)
-     2. **⚠️ User Intent Alignment**: Validate analysis aligns with original user objectives from session_metadata
-     3. **Address Topic Framework**: Respond to all discussion points in topic-framework.md from role perspective
-     4. **Filter by User Goals**: Prioritize insights directly relevant to user's stated objectives
-     5. Apply role template guidelines within topic framework structure
-     6. Generate structured role analysis addressing framework points aligned with user intent
-     7. Create single comprehensive deliverable in OUTPUT_LOCATION:
-        - analysis.md (structured analysis addressing all topic framework points with role-specific insights filtered by user goals)
-     8. Include framework reference: @../topic-framework.md in analysis.md
-     9. Update workflow-session.json with completion status",
-     description="Execute {role-name} brainstorming analysis")
-```
-
-### Parallel Role Agent调用示例
-```bash
-# Execute N roles in parallel using single message with multiple Task calls
-# (N determined by --count parameter, default 3, shown below with 3 roles as example)
-
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: {role-1} perspective for {topic}...",
-     description="Execute {role-1} brainstorming analysis")
-
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: {role-2} perspective for {topic}...",
-     description="Execute {role-2} brainstorming analysis")
-
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: {role-3} perspective for {topic}...",
-     description="Execute {role-3} brainstorming analysis")
-
-# ... repeat for remaining N-3 roles if --count > 3
-```
-
-### Direct Synthesis Process (Command-Driven)
-**Synthesis execution**: Use SlashCommand to execute `/workflow:brainstorm:synthesis` after role completion
-
-
-## TodoWrite Control Flow ⚠️ CRITICAL
-
-### Workflow Progress Tracking
-**MANDATORY**: Use Claude Code's built-in TodoWrite tool throughout entire brainstorming workflow:
-
-```javascript
-// Phase 1: Create initial todo list for command-coordinated brainstorming workflow
-TodoWrite({
-  todos: [
-    {
-      content: "Initialize brainstorming session and detect active sessions",
-      status: "pending",
-      activeForm: "Initializing brainstorming session"
-    },
-    {
-      content: "Parse --count parameter and select N roles based on topic keyword analysis",
-      status: "pending",
-      activeForm: "Parsing parameters and selecting roles for brainstorming"
-    },
-    {
-      content: "Execute artifacts command with selected roles for role-specific framework",
-      status: "pending",
-      activeForm: "Generating role-specific topic framework"
-    },
-    {
-      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      status: "pending",
-      activeForm: "Executing [role-1] structured framework analysis"
-    },
-    {
-      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      status: "pending",
-      activeForm: "Executing [role-2] structured framework analysis"
-    },
-    // ... repeat for N roles (N determined by --count parameter, default 3)
-    {
-      content: "Execute [role-N] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      status: "pending",
-      activeForm: "Executing [role-N] structured framework analysis"
-    },
-    {
-      content: "Execute synthesis command using SlashCommand for final integration",
-      status: "pending",
-      activeForm: "Executing synthesis command for integrated analysis"
-    }
-  ]
-});
-
-// Phase 2: Update status as workflow progresses - ONLY ONE task should be in_progress at a time
-TodoWrite({
-  todos: [
-    {
-      content: "Initialize brainstorming session and detect active sessions",
-      status: "completed",  // Mark completed preprocessing
-      activeForm: "Initializing brainstorming session"
-    },
-    {
-      content: "Select roles for topic analysis and create workflow-session.json",
-      status: "in_progress",  // Mark current task as in_progress
-      activeForm: "Selecting roles and creating session metadata"
-    },
-    // ... other tasks remain pending
-  ]
-});
-
-// Phase 3: Parallel agent execution tracking (N roles, N from --count parameter)
-TodoWrite({
-  todos: [
-    // ... previous completed tasks
-    {
-      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing [role-1] brainstorming analysis"
-    },
-    {
-      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing [role-2] brainstorming analysis"
-    },
-    // ... repeat for remaining N-2 roles
-    {
-      content: "Execute [role-N] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing [role-N] brainstorming analysis"
-    }
-  ]
-});
-```
-
-**TodoWrite Integration Rules**:
-1. **Create initial todos**: All workflow phases at start
-2. **Mark in_progress**: Multiple parallel tasks can be in_progress simultaneously
-3. **Update immediately**: After each task completion
-4. **Track agent execution**: Include [agent-type] and [FLOW_CONTROL] markers for parallel agents
-5. **Final synthesis**: Mark synthesis as in_progress only after all parallel agents complete
+- **Role selection failure**: artifacts defaults to product-manager with explanation
+- **Agent execution failure**: Agent-specific retry with minimal dependencies
+- **Template loading issues**: Agent handles graceful degradation
+- **Synthesis conflicts**: Synthesis highlights disagreements without resolution
 
 ## Reference Information
 
-### Structured Processing Schema
-Each role processing follows structured framework pattern:
-- **topic_framework**: Structured discussion framework document
-- **role**: Selected planning role name with framework reference
-- **agent**: Dedicated conceptual-planning-agent instance
-- **structured_analysis**: Agent addresses all framework discussion points
-- **output**: Role-specific analysis.md addressing topic framework structure
+**File Structure**:
+```
+.workflow/WFS-[topic]/
+├── .active-brainstorming
+├── workflow-session.json              # Session metadata ONLY
+└── .brainstorming/
+    ├── guidance-specification.md      # Framework (Phase 1)
+    ├── {role-1}/
+    │   └── analysis.md                # Role analysis (Phase 2)
+    ├── {role-2}/
+    │   └── analysis.md
+    ├── {role-N}/
+    │   └── analysis.md
+    └── synthesis-specification.md     # Integration (Phase 3)
+```
 
-### File Structure Reference
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
-**Role Templates**: @~/.claude/workflows/cli-templates/planning-roles/
+**Template Source**: `~/.claude/workflows/cli-templates/planning-roles/`
 
-### Execution Integration
-Command coordination model: artifacts command → parallel role analysis → synthesis command
-
-
-## Error Handling
-- **Role selection failure**: Default to `product-manager` with explanation
-- **Agent execution failure**: Agent-specific retry with minimal dependencies
-- **Template loading issues**: Agent handles graceful degradation
-- **Synthesis conflicts**: Synthesis agent highlights disagreements without resolution
-
-## Quality Standards
-
-### Agent Autonomy Excellence
-- **Single role focus**: Each agent handles exactly one role independently
-- **Self-contained execution**: Agent manages own context, validation, and output
-- **Parallel processing**: Multiple agents can execute simultaneously
-- **Complete ownership**: Agent produces entire role-specific analysis package
-
-### Minimal Coordination Excellence
-- **Lightweight handoff**: Only topic and role assignment provided
-- **Agent self-management**: Agents handle their own workflow and validation
-- **Concurrent operation**: No inter-agent dependencies enabling parallel execution
-- **Reference-based synthesis**: Post-processing integration without content duplication
-- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process

.claude/commands/workflow/brainstorm/data-architect.md

@@ -1,6 +1,6 @@
 ---
 name: data-architect
-description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
+description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points for data architecture perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 📊 **Data Architect Analysis Generator**
 
 ### Purpose
-**Specialized command for generating data-architect/analysis.md** that addresses topic-framework.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -52,7 +52,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -93,7 +93,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -107,17 +107,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from data architecture perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective
 **Role Focus**: Data models, pipelines, governance, analytics platforms
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with data architecture expertise
+- Address each discussion point from guidance-specification.md with data architecture expertise
 - Provide data model designs, pipeline architectures, and governance strategies
 - Include scalability, performance, and quality considerations
 - Reference framework document using @ notation for integration
@@ -136,7 +136,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -164,7 +164,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/data-architect/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -172,11 +172,11 @@ TodoWrite({
 # Data Architect Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Data Architecture perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with data architecture expertise]
+[Address each point from guidance-specification.md with data architecture expertise]
 
 ### Core Requirements (from framework)
 [Data architecture perspective on requirements]
@@ -209,12 +209,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/product-manager.md

@@ -1,6 +1,6 @@
 ---
 name: product-manager
-description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
+description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points for product management perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Product Manager Analysis Generator**
 
 ### Purpose
-**Specialized command for generating product-manager/analysis.md** that addresses topic-framework.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Product Strategy Focus**: User needs, business value, and market positioning
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from product strategy perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective
 **Role Focus**: User value, business impact, market positioning, product strategy
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with product management expertise
+- Address each discussion point from guidance-specification.md with product management expertise
 - Provide actionable business strategies and user value propositions
 - Include market analysis and competitive positioning insights
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/product-manager/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Product Manager Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Product Strategy perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with product management expertise]
+[Address each point from guidance-specification.md with product management expertise]
 
 ### Core Requirements (from framework)
 [Product strategy perspective on user needs and requirements]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/product-owner.md

@@ -1,6 +1,6 @@
 ---
 name: product-owner
-description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
+description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points for product ownership perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Product Owner Analysis Generator**
 
 ### Purpose
-**Specialized command for generating product-owner/analysis.md** that addresses topic-framework.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from product backlog and feature prioritization perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective
 **Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with product ownership expertise
+- Address each discussion point from guidance-specification.md with product ownership expertise
 - Provide actionable user stories and acceptance criteria definitions
 - Include feature prioritization and stakeholder alignment strategies
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/product-owner/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Product Owner Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Product Backlog & Feature Prioritization perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with product ownership expertise]
+[Address each point from guidance-specification.md with product ownership expertise]
 
 ### Core Requirements (from framework)
 [User story formulation and backlog refinement perspective]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/scrum-master.md

@@ -1,6 +1,6 @@
 ---
 name: scrum-master
-description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
+description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points for Agile process perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Scrum Master Analysis Generator**
 
 ### Purpose
-**Specialized command for generating scrum-master/analysis.md** that addresses topic-framework.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from agile process and team collaboration perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective
 **Role Focus**: Sprint planning, team dynamics, process optimization, delivery management
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with scrum mastery expertise
+- Address each discussion point from guidance-specification.md with scrum mastery expertise
 - Provide actionable sprint planning and team facilitation strategies
 - Include process optimization and impediment removal insights
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/scrum-master/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Scrum Master Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Agile Process & Team Collaboration perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with scrum mastery expertise]
+[Address each point from guidance-specification.md with scrum mastery expertise]
 
 ### Core Requirements (from framework)
 [Sprint planning and iteration breakdown perspective]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/subject-matter-expert.md

@@ -1,6 +1,6 @@
 ---
 name: subject-matter-expert
-description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
+description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points for domain expertise perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **Subject Matter Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating subject-matter-expert/analysis.md** that addresses topic-framework.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -32,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -73,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -87,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from domain expertise and technical standards perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective
 **Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with subject matter expertise
+- Address each discussion point from guidance-specification.md with subject matter expertise
 - Provide actionable technical standards and best practices recommendations
 - Include risk assessment and compliance considerations
 - Reference framework document using @ notation for integration
@@ -116,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -144,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/subject-matter-expert/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -152,11 +152,11 @@ TodoWrite({
 # Subject Matter Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Domain Expertise & Technical Standards perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with subject matter expertise]
+[Address each point from guidance-specification.md with subject matter expertise]
 
 ### Core Requirements (from framework)
 [Domain-specific requirements and industry standards perspective]
@@ -189,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/synthesis.md

@@ -1,378 +1,438 @@
 ---
 name: synthesis
-description: Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent
+description: Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent
 argument-hint: "[optional: --session session-id]"
-allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*)
 ---
 
-## 🧩 **Synthesis Document Generator**
+## Overview
 
-### Core Function
-**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights.
+Three-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
 
-**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
+**Phase 1-2 (Main Flow)**: Session detection → File discovery → Path preparation
 
-### Primary Capabilities
-- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime
-- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles
-- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references
-- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points
-- **@ Reference System**: Create structured references to source documents
-- **Update Detection**: Smart updates when new role analyses are added
-- **Flexible Participation**: Supports any subset of available roles (1 to 9+)
+**Phase 3A (Analysis Agent)**: Cross-role analysis → Generate recommendations
 
-### Document Integration Model
-**Three-Document Reference System**:
-1. **topic-framework.md** → Structured discussion framework (input)
-2. **[role]/analysis.md** → Role-specific analyses addressing framework (input)
-3. **synthesis-specification.md** → Complete integrated specification (output)
+**Phase 4 (Main Flow)**: User selects enhancements → User answers clarifications → Build update plan
 
-## ⚙️ **Execution Protocol**
+**Phase 5 (Parallel Update Agents)**: Each agent updates ONE role document → Parallel execution
 
-### ⚠️ Agent Execution with Flow Control
-**Execution Model**: Uses conceptual-planning-agent for synthesis generation with structured file loading.
+**Phase 6 (Main Flow)**: Metadata update → Completion report
 
-**Rationale**:
-- **Autonomous Execution**: Agent independently loads and processes all required documents
-- **Flow Control**: Structured document loading ensures systematic analysis
-- **Complex Cognitive Analysis**: Leverages agent's analytical capabilities for cross-role synthesis
-- **Conceptual Focus**: Agent specializes in conceptual analysis and multi-perspective integration
+**Key Features**:
+- Multi-agent architecture (analysis agent + parallel update agents)
+- Clear separation: Agent analysis vs Main flow interaction
+- Parallel document updates (one agent per role)
+- User intent alignment validation
 
-**Agent Responsibility**: All file reading and synthesis generation performed by conceptual-planning-agent with FLOW_CONTROL instructions.
+**Document Flow**:
+- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata
+- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
+
+## Task Tracking
 
-### 📋 Task Tracking Protocol
-Initialize synthesis task tracking using TodoWrite at command start:
 ```json
 [
-  {"content": "Detect active session and validate topic-framework.md existence", "status": "in_progress", "activeForm": "Detecting session and validating framework"},
-  {"content": "Discover participating role analyses dynamically", "status": "pending", "activeForm": "Discovering role analyses"},
-  {"content": "Check existing synthesis and confirm user action", "status": "pending", "activeForm": "Checking update mechanism"},
-  {"content": "Execute synthesis generation using conceptual-planning-agent with FLOW_CONTROL", "status": "pending", "activeForm": "Executing agent-based synthesis generation"},
-  {"content": "Agent performs cross-role analysis and generates synthesis-specification.md", "status": "pending", "activeForm": "Agent analyzing and generating synthesis"},
-  {"content": "Update workflow-session.json with synthesis completion status", "status": "pending", "activeForm": "Updating session metadata"}
+  {"content": "Detect session and validate analyses", "status": "in_progress", "activeForm": "Detecting session"},
+  {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"},
+  {"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis agent"},
+  {"content": "Present enhancements for user selection", "status": "pending", "activeForm": "Presenting enhancements"},
+  {"content": "Generate and present clarification questions", "status": "pending", "activeForm": "Clarifying with user"},
+  {"content": "Build update plan from user input", "status": "pending", "activeForm": "Building update plan"},
+  {"content": "Execute parallel update agents (one per role)", "status": "pending", "activeForm": "Updating documents in parallel"},
+  {"content": "Update session metadata and generate report", "status": "pending", "activeForm": "Finalizing session"}
 ]
 ```
 
-### Phase 1: Document Discovery & Validation
-```bash
-# Detect active brainstorming session
-IF --session parameter provided:
-    session_id = provided session
-ELSE:
-    CHECK: .workflow/.active-* marker files
-    IF active_session EXISTS:
-        session_id = get_active_session()
-    ELSE:
-        ERROR: "No active brainstorming session found"
-        EXIT
+## Execution Phases
 
-brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+### Phase 1: Discovery & Validation
 
-# Validate required documents
-CHECK: brainstorm_dir/topic-framework.md
-IF NOT EXISTS:
-    ERROR: "topic-framework.md not found. Run /workflow:brainstorm:artifacts first"
-    EXIT
+1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker
+2. **Validate Files**:
+   - `guidance-specification.md` (optional, warn if missing)
+   - `*/analysis*.md` (required, error if empty)
+3. **Load User Intent**: Extract from `workflow-session.json` (project/description field)
 
-# Load user's original prompt from session metadata
-session_metadata = Read(.workflow/WFS-{session}/workflow-session.json)
-original_user_prompt = session_metadata.project || session_metadata.description
-IF NOT original_user_prompt:
-    WARN: "No original user prompt found in session metadata"
-    original_user_prompt = "Not available"
-```
+### Phase 2: Role Discovery & Path Preparation
 
-### Phase 2: Role Analysis Discovery
-```bash
-# Dynamically discover available role analyses
-SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/
-FIND_ANALYSES: [
-    Scan all subdirectories for */analysis.md files
-    Extract role names from directory names
-]
+**Main flow prepares file paths for Agent**:
 
-# Available roles (for reference, actual participation is dynamic):
-# - product-manager
-# - product-owner
-# - scrum-master
-# - system-architect
-# - ui-designer
-# - ux-expert
-# - data-architect
-# - subject-matter-expert
-# - test-strategist
+1. **Discover Analysis Files**:
+   - Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)
+   - Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md
+   - Validate: At least one file exists (error if empty)
 
-LOAD_DOCUMENTS: {
-    "original_user_prompt": original_user_prompt (from session metadata),
-    "topic_framework": topic-framework.md,
-    "role_analyses": [dynamically discovered analysis.md files],
-    "participating_roles": [extract role names from discovered directories],
-    "existing_synthesis": synthesis-specification.md (if exists)
-}
+2. **Extract Role Information**:
+   - `role_analysis_paths`: Relative paths from brainstorm_dir
+   - `participating_roles`: Role names extracted from directory paths
 
-# Note: Not all roles participate in every brainstorming session
-# Only synthesize roles that actually produced analysis.md files
-# CRITICAL: Original user prompt MUST be primary reference for synthesis
-```
+3. **Pass to Agent** (Phase 3):
+   - `session_id`
+   - `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/
+   - `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...]
+   - `participating_roles`: ["product-manager", "system-architect", ...]
 
-### Phase 3: Update Mechanism Check
-```bash
-# Check for existing synthesis
-IF synthesis-specification.md EXISTS:
-    SHOW current synthesis summary to user
-    ASK: "Synthesis exists. Do you want to:"
-    OPTIONS:
-      1. "Regenerate completely" → Create new synthesis
-      2. "Update with new analyses" → Integrate new role analyses
-      3. "Preserve existing" → Exit without changes
-ELSE:
-    CREATE new synthesis
-```
+**Main Flow Responsibility**: File discovery and path preparation only (NO file content reading)
 
-### Phase 4: Agent Execution with Flow Control
-**Synthesis Generation using conceptual-planning-agent**
+### Phase 3A: Analysis & Enhancement Agent
 
-Delegate synthesis generation to conceptual-planning-agent with structured file loading:
+**First agent call**: Cross-role analysis and generate enhancement recommendations
 
 ```bash
 Task(conceptual-planning-agent): "
+## Agent Mission
+Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations
+
+## Input from Main Flow
+- brainstorm_dir: {brainstorm_dir}
+- role_analysis_paths: {role_analysis_paths}
+- participating_roles: {participating_roles}
+
+## Execution Instructions
 [FLOW_CONTROL]
 
-Execute comprehensive synthesis generation from topic framework and role analyses
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation:
 
-## Context Loading
-OUTPUT_FILE: synthesis-specification.md
-OUTPUT_PATH: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md
-SESSION_ID: {session_id}
-ANALYSIS_MODE: cross_role_synthesis
+1. **load_session_metadata**
+   - Action: Load original user intent as primary reference
+   - Command: Read({brainstorm_dir}/../workflow-session.json)
+   - Output: original_user_intent (from project/description field)
 
-## ⚠️ CRITICAL: User Intent Authority
-**ORIGINAL USER PROMPT IS THE PRIMARY REFERENCE**: {original_user_prompt}
-All synthesis MUST align with user's original intent. Topic framework and role analyses are supplementary context.
+2. **load_role_analyses**
+   - Action: Load all role analysis documents
+   - Command: For each path in role_analysis_paths: Read({brainstorm_dir}/{path})
+   - Output: role_analyses_content_map = {role_name: content}
 
-## Flow Control Steps
-1. **load_original_user_prompt**
-   - Action: Load user's original intent from session metadata
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
-   - Extract: project field or description field
-   - Output: original_user_prompt (PRIMARY REFERENCE)
-   - Priority: HIGHEST - This is the authoritative source of user intent
+3. **cross_role_analysis**
+   - Action: Identify consensus themes, conflicts, gaps, underspecified areas
+   - Output: consensus_themes, conflicting_views, gaps_list, ambiguities
 
-2. **load_topic_framework**
-   - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
-   - Output: topic_framework_content
-   - Note: Validate alignment with original_user_prompt
+4. **generate_recommendations**
+   - Action: Convert cross-role analysis findings into structured enhancement recommendations
+   - Format: EP-001, EP-002, ... (sequential numbering)
+   - Fields: id, title, affected_roles, category, current_state, enhancement, rationale, priority
+   - Taxonomy: Map to 9 categories (User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology)
+   - Output: enhancement_recommendations (JSON array)
 
-3. **discover_role_analyses**
-   - Action: Dynamically discover all participating role analysis files
-   - Command: Glob(.workflow/WFS-{session}/.brainstorming/*/analysis.md)
-   - Output: role_analysis_paths, participating_roles
+### Output to Main Flow
+Return JSON array:
+[
+  {
+    \"id\": \"EP-001\",
+    \"title\": \"API Contract Specification\",
+    \"affected_roles\": [\"system-architect\", \"api-designer\"],
+    \"category\": \"Architecture\",
+    \"current_state\": \"High-level API descriptions\",
+    \"enhancement\": \"Add detailed contract definitions with request/response schemas\",
+    \"rationale\": \"Enables precise implementation and testing\",
+    \"priority\": \"High\"
+  },
+  ...
+]
 
-4. **load_role_analyses**
-   - Action: Load all discovered role analysis documents
-   - Command: Read(each path from role_analysis_paths)
-   - Output: role_analyses_content
-   - Note: Filter insights relevant to original_user_prompt
-
-5. **check_existing_synthesis**
-   - Action: Check if synthesis-specification.md already exists
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) [if exists]
-   - Output: existing_synthesis_content [optional]
-
-6. **load_synthesis_template**
-   - Action: Load synthesis role template for structure and guidelines
-   - Command: Read(~/.claude/workflows/cli-templates/planning-roles/synthesis-role.md)
-   - Output: synthesis_template_guidelines
-
-## Synthesis Requirements
-
-### ⚠️ PRIMARY REQUIREMENT: User Intent Alignment
-**User's Original Goal is Supreme**: Synthesis MUST directly address {original_user_prompt}
-**Intent Validation**: Every requirement, design decision, and recommendation must trace back to user's original intent
-**Deviation Detection**: Flag any role analysis points that drift from user's stated goals
-**Refocus Mechanism**: When role discussions diverge, explicitly refocus on original user prompt
-**Traceability**: Each section should reference how it fulfills user's original intent
-
-### Core Integration
-**Cross-Role Analysis**: Integrate all discovered role analyses with comprehensive coverage
-**Framework Integration**: Address how each role responded to topic-framework.md discussion points
-**User Intent Filter**: Prioritize insights that directly serve user's original prompt
-**Decision Transparency**: Document both adopted solutions and rejected alternatives with rationale
-**Process Integration**: Include team capability gaps, process risks, and collaboration patterns
-**Visual Documentation**: Include key diagrams (architecture, data model, user journey) via Mermaid
-**Priority Matrix**: Create quantified recommendation matrix aligned with user's goals
-**Actionable Plan**: Provide phased implementation roadmap addressing user's original objectives
-
-### Cross-Role Analysis Process (Agent Internal Execution)
-Perform systematic cross-role analysis following these steps:
-
-1. **Data Collection**: Extract key insights, recommendations, concerns, and diagrams from each discovered role analysis
-2. **Consensus Identification**: Identify common themes and agreement areas across all participating roles
-3. **Disagreement Analysis**: Document conflicting views and track which specific roles disagree on each point
-4. **Innovation Extraction**: Identify breakthrough ideas and cross-role synergy opportunities
-5. **Priority Scoring**: Calculate multi-dimensional priority scores (impact, feasibility, effort, risk) for each recommendation
-6. **Decision Matrix**: Create comprehensive evaluation matrix and sort recommendations by priority
-
-## Synthesis Quality Standards
-Follow synthesis-specification.md structure defined in synthesis-role.md template:
-- Use template structure for comprehensive document organization
-- Apply analysis guidelines for cross-role synthesis process
-- Include all required sections from template (Executive Summary, Key Designs, Requirements, etc.)
-- Follow @ reference system for traceability to source role analyses
-- Apply quality standards from template (completeness, visual clarity, decision transparency)
-- Validate output against template's output validation checklist
-
-## Expected Deliverables
-1. **synthesis-specification.md**: Complete integrated specification consolidating all role perspectives
-2. **@ References**: Include cross-references to source role analyses
-3. **Session Metadata Update**: Update workflow-session.json with synthesis completion status
-
-## Completion Criteria
-- ⚠️ **USER INTENT ALIGNMENT**: Synthesis directly addresses user's original prompt
-- All discovered role analyses integrated without gaps
-- Framework discussion points addressed across all roles
-- **Intent traceability**: Each major section references user's original goals
-- Controversial points documented with dissenting roles identified
-- Process concerns (team capabilities, risks, collaboration) captured
-- Quantified priority recommendations aligned with user's objectives
-- Actionable implementation plan addressing user's stated goals
-- Comprehensive risk assessment with mitigation strategies
-- **Deviation warnings**: Any significant departures from user intent flagged explicitly
-
-## Execution Notes
-- Dynamic role participation: Only synthesize roles that produced analysis.md files
-- Update mechanism: If synthesis exists, prompt user for regenerate/update/preserve decision
-- Timeout allocation: Complex synthesis task (60-90 min recommended)
-- Reference @intelligent-tools-strategy.md for timeout guidelines
 "
 ```
 
-## 📊 **Output Specification**
+### Phase 4: Main Flow User Interaction
 
-### Output Location
-The synthesis process creates **one consolidated document** that integrates all role perspectives:
+**Main flow handles all user interaction via text output**:
 
-```
-.workflow/WFS-{topic-slug}/.brainstorming/
-├── topic-framework.md          # Input: Framework structure
-├── [role]/analysis.md          # Input: Role analyses (multiple)
-└── synthesis-specification.md  # ★ OUTPUT: Complete integrated specification
+**⚠️ CRITICAL**: ALL questions MUST use Chinese (所有问题必须用中文) for better user understanding
+
+1. **Present Enhancement Options** (multi-select):
+```markdown
+===== Enhancement 选择 =====
+
+请选择要应用的改进建议（可多选）：
+
+a) EP-001: API Contract Specification
+   影响角色：system-architect, api-designer
+   说明：添加详细的请求/响应 schema 定义
+
+b) EP-002: User Intent Validation
+   影响角色：product-manager, ux-expert
+   说明：明确用户需求优先级和验收标准
+
+c) EP-003: Error Handling Strategy
+   影响角色：system-architect
+   说明：统一异常处理和降级方案
+
+支持格式：1abc 或 1a 1b 1c 或 1a,b,c
+请输入选择（可跳过输入 skip）：
 ```
 
-#### synthesis-specification.md Structure
+2. **Generate Clarification Questions** (based on analysis agent output):
+   - ✅ **ALL questions in Chinese (所有问题必须用中文)**
+   - Use 9-category taxonomy scan results
+   - Prioritize most critical questions (no hard limit)
+   - Each with 2-4 options + descriptions
 
-**Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint.
-**Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
+3. **Interactive Clarification Loop** (max 10 questions per round):
+```markdown
+===== Clarification 问题 (第 1/2 轮) =====
 
-**Template Reference**: Complete document structure and content guidelines available in `synthesis-role.md` template, including:
-- Executive Summary with strategic overview
-- Key Designs & Decisions (architecture diagrams, ADRs, user journeys)
-- Controversial Points & Alternatives (decision transparency)
-- Requirements & Acceptance Criteria (Functional, Non-Functional, Business)
-- Design Specifications (UI/UX, Architecture, Domain Expertise)
-- Process & Collaboration Concerns (team skills, risks, patterns, constraints)
-- Implementation Roadmap (high-level phases)
-- Risk Assessment & Mitigation strategies
+【问题1 - 用户意图】MVP 阶段的核心目标是什么？
+a) 快速验证市场需求
+   说明：最小功能集，快速上线获取反馈
+b) 建立技术壁垒
+   说明：完善架构，为长期发展打基础
+c) 实现功能完整性
+   说明：覆盖所有规划功能，延迟上线
 
-**Agent Usage**: The conceptual-planning-agent loads this template to understand expected structure and quality standards.
+【问题2 - 架构决策】技术栈选择的优先考虑因素？
+a) 团队熟悉度
+   说明：使用现有技术栈，降低学习成本
+b) 技术先进性
+   说明：采用新技术，提升竞争力
+c) 生态成熟度
+   说明：选择成熟方案，保证稳定性
 
-## 🔄 **Session Integration**
+...（最多10个问题）
 
-### Streamlined Status Synchronization
-Upon completion, update `workflow-session.json`:
+请回答 (格式: 1a 2b 3c...)：
+```
 
-**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
+Wait for user input → Parse all answers in batch → Continue to next round if needed
 
+4. **Build Update Plan**:
+```
+update_plan = {
+  "role1": {
+    "enhancements": [EP-001, EP-003],
+    "clarifications": [
+      {"question": "...", "answer": "...", "category": "..."},
+      ...
+    ]
+  },
+  "role2": {
+    "enhancements": [EP-002],
+    "clarifications": [...]
+  },
+  ...
+}
+```
+
+### Phase 5: Parallel Document Update Agents
+
+**Parallel agent calls** (one per role needing updates):
+
+```bash
+# Execute in parallel using single message with multiple Task calls
+
+Task(conceptual-planning-agent): "
+## Agent Mission
+Apply user-confirmed enhancements and clarifications to {role1} analysis document
+
+## Agent Intent
+- **Goal**: Integrate synthesis results into role-specific analysis
+- **Scope**: Update ONLY {role1}/analysis.md (isolated, no cross-role dependencies)
+- **Constraints**: Preserve original insights, add refinements without deletion
+
+## Input from Main Flow
+- role: {role1}
+- analysis_path: {brainstorm_dir}/{role1}/analysis.md
+- enhancements: [EP-001, EP-003] (user-selected improvements)
+- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
+- original_user_intent: {from session metadata}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these update steps sequentially:
+
+1. **load_current_analysis**
+   - Action: Load existing role analysis document
+   - Command: Read({brainstorm_dir}/{role1}/analysis.md)
+   - Output: current_analysis_content
+
+2. **add_clarifications_section**
+   - Action: Insert Clarifications section with Q&A
+   - Format: \"## Clarifications\\n### Session {date}\\n- **Q**: {question} (Category: {category})\\n  **A**: {answer}\"
+   - Output: analysis_with_clarifications
+
+3. **apply_enhancements**
+   - Action: Integrate EP-001, EP-003 into relevant sections
+   - Strategy: Locate section by category (Architecture → Architecture section, UX → User Experience section)
+   - Output: analysis_with_enhancements
+
+4. **resolve_contradictions**
+   - Action: Remove conflicts between original content and clarifications/enhancements
+   - Output: contradiction_free_analysis
+
+5. **enforce_terminology_consistency**
+   - Action: Align all terminology with user-confirmed choices from clarifications
+   - Output: terminology_consistent_analysis
+
+6. **validate_user_intent_alignment**
+   - Action: Verify all updates support original_user_intent
+   - Output: validated_analysis
+
+7. **write_updated_file**
+   - Action: Save final analysis document
+   - Command: Write({brainstorm_dir}/{role1}/analysis.md, validated_analysis)
+   - Output: File update confirmation
+
+### Output
+Updated {role1}/analysis.md with Clarifications section + enhanced content
+")
+
+Task(conceptual-planning-agent): "
+## Agent Mission
+Apply user-confirmed enhancements and clarifications to {role2} analysis document
+
+## Agent Intent
+- **Goal**: Integrate synthesis results into role-specific analysis
+- **Scope**: Update ONLY {role2}/analysis.md (isolated, no cross-role dependencies)
+- **Constraints**: Preserve original insights, add refinements without deletion
+
+## Input from Main Flow
+- role: {role2}
+- analysis_path: {brainstorm_dir}/{role2}/analysis.md
+- enhancements: [EP-002] (user-selected improvements)
+- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
+- original_user_intent: {from session metadata}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute same 7 update steps as {role1} agent (load → clarifications → enhancements → contradictions → terminology → validation → write)
+
+### Output
+Updated {role2}/analysis.md with Clarifications section + enhanced content
+")
+
+# ... repeat for each role in update_plan
+```
+
+**Agent Characteristics**:
+- **Intent**: Integrate user-confirmed synthesis results (NOT generate new analysis)
+- **Isolation**: Each agent updates exactly ONE role (parallel execution safe)
+- **Context**: Minimal - receives only role-specific enhancements + clarifications
+- **Dependencies**: Zero cross-agent dependencies (full parallelism)
+- **Validation**: All updates must align with original_user_intent
+
+### Phase 6: Completion & Metadata Update
+
+**Main flow finalizes**:
+
+1. Wait for all parallel agents to complete
+2. Update workflow-session.json:
 ```json
 {
   "phases": {
     "BRAINSTORM": {
-      "status": "completed",
-      "synthesis_completed": true,
+      "status": "clarification_completed",
+      "clarification_completed": true,
       "completed_at": "timestamp",
-      "participating_roles": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
-      "available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
-      "consolidated_output": {
-        "synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md"
+      "participating_roles": [...],
+      "clarification_results": {
+        "enhancements_applied": ["EP-001", "EP-002", ...],
+        "questions_asked": 3,
+        "categories_clarified": ["Architecture", "UX", ...],
+        "roles_updated": ["role1", "role2", ...],
+        "outstanding_items": []
       },
-      "synthesis_quality": {
-        "role_integration": "complete",
+      "quality_metrics": {
+        "user_intent_alignment": "validated",
         "requirement_coverage": "comprehensive",
-        "decision_transparency": "alternatives_documented",
-        "process_risks_identified": true,
-        "implementation_readiness": "ready"
-      },
-      "content_metrics": {
-        "roles_synthesized": "<COUNT(participating_roles)>",
-        "functional_requirements": "<dynamic-count>",
-        "non_functional_requirements": "<dynamic-count>",
-        "business_requirements": "<dynamic-count>",
-        "architecture_decisions": "<dynamic-count>",
-        "controversial_points": "<dynamic-count>",
-        "diagrams_included": "<dynamic-count>",
-        "process_risks": "<dynamic-count>",
-        "team_skill_gaps": "<dynamic-count>",
-        "implementation_phases": "<dynamic-count>",
-        "risk_factors_identified": "<dynamic-count>"
+        "ambiguity_resolution": "complete",
+        "terminology_consistency": "enforced"
       }
     }
   }
 }
 ```
 
-**Example with actual values**:
+3. Generate completion report (show to user):
+```markdown
+## ✅ Clarification Complete
+
+**Enhancements Applied**: EP-001, EP-002, EP-003
+**Questions Answered**: 3/5
+**Roles Updated**: role1, role2, role3
+
+### Next Steps
+✅ PROCEED: `/workflow:plan --session WFS-{session-id}`
+```
+
+## Output
+
+**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
+
+**Updated Structure**:
+```markdown
+## Clarifications
+### Session {date}
+- **Q**: {question} (Category: {category})
+  **A**: {answer}
+
+## {Existing Sections}
+{Refined content based on clarifications}
+```
+
+**Changes**:
+- User intent validated/corrected
+- Requirements more specific/measurable
+- Architecture with rationale
+- Ambiguities resolved, placeholders removed
+- Consistent terminology
+
+## Session Metadata
+
+Update `workflow-session.json`:
+
 ```json
 {
   "phases": {
     "BRAINSTORM": {
-      "status": "completed",
-      "participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"],
-      "content_metrics": {
-        "roles_synthesized": 5,
-        "functional_requirements": 18,
-        "controversial_points": 2
+      "status": "clarification_completed",
+      "clarification_completed": true,
+      "completed_at": "timestamp",
+      "participating_roles": ["product-manager", "system-architect", ...],
+      "clarification_results": {
+        "questions_asked": 3,
+        "categories_clarified": ["Architecture & Design", ...],
+        "roles_updated": ["system-architect", "ui-designer", ...],
+        "outstanding_items": []
+      },
+      "quality_metrics": {
+        "user_intent_alignment": "validated",
+        "requirement_coverage": "comprehensive",
+        "ambiguity_resolution": "complete",
+        "terminology_consistency": "enforced",
+        "decision_transparency": "documented"
       }
     }
   }
 }
 ```
 
-## ✅ **Quality Assurance**
+## Quality Checklist
 
-Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template):
+**Content**:
+- All role analyses loaded/analyzed
+- Cross-role analysis (consensus, conflicts, gaps)
+- 9-category ambiguity scan
+- Questions prioritized
+- Clarifications documented
 
-### Content Completeness
-- [ ] All discovered role analyses integrated without gaps
-- [ ] Key designs documented (architecture diagrams, ADRs, user journeys via Mermaid)
-- [ ] Controversial points captured with alternatives and rationale
-- [ ] Process concerns included (team skills, risks, collaboration patterns)
-- [ ] Requirements documented (Functional, Non-Functional, Business) with sources
+**Analysis**:
+- User intent validated
+- Cross-role synthesis complete
+- Ambiguities resolved
+- Correct roles updated
+- Terminology consistent
+- Contradictions removed
 
-### Analysis Quality
-- [ ] Cross-role synthesis identifies consensus and conflicts
-- [ ] Decision transparency documents both adopted and rejected alternatives
-- [ ] Priority recommendations with multi-dimensional evaluation
-- [ ] Implementation roadmap with phased approach
-- [ ] Risk assessment with mitigation strategies
-- [ ] @ references to source role analyses throughout
+**Documents**:
+- Clarifications section formatted
+- Sections reflect answers
+- No placeholders (TODO/TBD)
+- Valid Markdown
+- Cross-references maintained
 
-## 🚀 **Recommended Next Steps**
 
-After synthesis completion, proceed to action planning:
-
-### Standard Workflow (Recommended)
-```bash
-/workflow:concept-clarify --session WFS-{session-id}  # Optional: Clarify ambiguities
-/workflow:plan --session WFS-{session-id}             # Generate IMPL_PLAN.md and tasks
-/workflow:action-plan-verify --session WFS-{session-id}  # Optional: Verify plan quality
-/workflow:execute --session WFS-{session-id}          # Start implementation
-```
-
-### TDD Workflow
-```bash
-/workflow:concept-clarify --session WFS-{session-id}  # Optional: Clarify ambiguities
-/workflow:tdd-plan --session WFS-{session-id} "Feature description"
-/workflow:action-plan-verify --session WFS-{session-id}  # Optional: Verify plan quality
-/workflow:execute --session WFS-{session-id}
-```

.claude/commands/workflow/brainstorm/system-architect.md

@@ -1,6 +1,6 @@
 ---
 name: system-architect
-description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
+description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🏗️ **System Architect Analysis Generator**
 
 ### Purpose
-**Specialized command for generating system-architect/analysis.md** that addresses topic-framework.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Architecture Focus**: Technical architecture, scalability, and system design perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -51,7 +51,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,20 +78,20 @@ ELSE:
 ```
 
 ### Phase 3: Agent Task Generation
-**Framework-Based Analysis** (when topic-framework.md exists):
+**Framework-Based Analysis** (when guidance-specification.md exists):
 ```bash
 Task(subagent_type="conceptual-planning-agent",
      prompt="Generate system architect analysis addressing topic framework
 
      ## Framework Integration Required
-     **MANDATORY**: Load and address topic-framework.md discussion points
-     **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+     **MANDATORY**: Load and address guidance-specification.md discussion points
+     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
      **Output Location**: {session.brainstorm_dir}/system-architect/analysis.md
 
      ## Analysis Requirements
-     1. **Load Topic Framework**: Read topic-framework.md completely
+     1. **Load Topic Framework**: Read guidance-specification.md completely
      2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective
-     3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
+     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
      4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions
      5. **Structured Response**: Use framework structure for analysis organization
 
@@ -106,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
      ```markdown
      # System Architect Analysis: [Topic]
 
-     **Framework Reference**: @../topic-framework.md
+     **Framework Reference**: @../guidance-specification.md
      **Role Focus**: System Architecture and Technical Design
 
      ## Core Requirements Analysis
@@ -140,14 +140,14 @@ IF update_mode = "incremental":
 
          ## Current Analysis Context
          **Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md
-         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
 
          ## Update Requirements
          1. **Preserve Structure**: Maintain existing analysis structure
          2. **Add New Insights**: Integrate new technical insights and recommendations
          3. **Framework Alignment**: Ensure continued alignment with topic framework
          4. **Technical Updates**: Add new architecture patterns, technology considerations
-         5. **Maintain References**: Keep @../topic-framework.md reference
+         5. **Maintain References**: Keep @../guidance-specification.md reference
 
          ## Update Instructions
          - Read existing analysis completely
@@ -163,14 +163,14 @@ IF update_mode = "incremental":
 ### Output Files
 ```
 .workflow/WFS-[topic]/.brainstorming/
-├── topic-framework.md          # Input: Framework (if exists)
+├── guidance-specification.md          # Input: Framework (if exists)
 └── system-architect/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
 ```
 
 ### Analysis Structure
 **Required Elements**:
-- **Framework Reference**: @../topic-framework.md (if framework exists)
+- **Framework Reference**: @../guidance-specification.md (if framework exists)
 - **Role Focus**: System Architecture and Technical Design perspective
 - **5 Framework Sections**: Address each framework discussion point
 - **Technical Recommendations**: Architecture-specific insights and solutions

.claude/commands/workflow/brainstorm/ui-designer.md

@@ -1,6 +1,6 @@
 ---
 name: ui-designer
-description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
+description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points for UI design perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎨 **UI Designer Analysis Generator**
 
 ### Purpose
-**Specialized command for generating ui-designer/analysis.md** that addresses topic-framework.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **UI/UX Focus**: User experience, interface design, and accessibility perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -53,7 +53,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from UI/UX perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective
 **Role Focus**: User experience design, interface optimization, accessibility compliance
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with UI/UX design expertise
+- Address each discussion point from guidance-specification.md with UI/UX design expertise
 - Provide actionable design recommendations and interface solutions
 - Include accessibility considerations and WCAG compliance planning
 - Reference framework document using @ notation for integration
@@ -137,7 +137,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -165,7 +165,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/ui-designer/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -173,11 +173,11 @@ TodoWrite({
 # UI Designer Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: UI/UX Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with UI/UX expertise]
+[Address each point from guidance-specification.md with UI/UX expertise]
 
 ### Core Requirements (from framework)
 [UI/UX perspective on requirements]
@@ -210,12 +210,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/brainstorm/ux-expert.md

@@ -1,6 +1,6 @@
 ---
 name: ux-expert
-description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
+description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -8,10 +8,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ## 🎯 **UX Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating ux-expert/analysis.md** that addresses topic-framework.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **UX Design Focus**: User interface, interaction patterns, and usability optimization
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -53,7 +53,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -94,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -108,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from user experience and interface design perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective
 **Role Focus**: UI design, interaction patterns, usability optimization, design systems
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with UX design expertise
+- Address each discussion point from guidance-specification.md with UX design expertise
 - Provide actionable interface design and usability optimization strategies
 - Include accessibility considerations and interaction pattern recommendations
 - Reference framework document using @ notation for integration
@@ -137,7 +137,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -165,7 +165,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/ux-expert/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -173,11 +173,11 @@ TodoWrite({
 # UX Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: User Experience & Interface Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with UX design expertise]
+[Address each point from guidance-specification.md with UX design expertise]
 
 ### Core Requirements (from framework)
 [User interface and interaction design requirements perspective]
@@ -210,12 +210,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

.claude/commands/workflow/concept-clarify.md

@@ -1,353 +0,0 @@
----
-name: concept-clarify
-description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
-argument-hint: "[optional: --session session-id]"
-allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
----
-
-## User Input
-
-```text
-$ARGUMENTS
-```
-
-You **MUST** consider the user input before proceeding (if not empty).
-
-## Outline
-
-**Goal**: Detect and reduce ambiguity or missing decision points in planning artifacts before moving to task generation. Supports both brainstorm and plan workflows.
-
-**Timing**:
-- **Brainstorm mode**: Runs AFTER `/workflow:brainstorm:synthesis` and BEFORE `/workflow:plan`
-- **Plan mode**: Runs AFTER Phase 3 (concept-enhanced) and BEFORE Phase 4 (task-generate) within `/workflow:plan`
-
-This serves as a quality gate to ensure conceptual clarity before detailed task planning or generation.
-
-**Execution steps**:
-
-1. **Session Detection & Validation**
-   ```bash
-   # Detect active workflow session
-   IF --session parameter provided:
-       session_id = provided session
-   ELSE:
-       CHECK: .workflow/.active-* marker files
-       IF active_session EXISTS:
-           session_id = get_active_session()
-       ELSE:
-           ERROR: "No active workflow session found. Use --session <session-id> or start a session."
-           EXIT
-
-   # Mode detection: plan vs brainstorm
-   brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
-   process_dir = .workflow/WFS-{session}/.process/
-
-   IF EXISTS(process_dir/ANALYSIS_RESULTS.md):
-       clarify_mode = "plan"
-       primary_artifact = process_dir/ANALYSIS_RESULTS.md
-       INFO: "Plan mode: Analyzing ANALYSIS_RESULTS.md"
-   ELSE IF EXISTS(brainstorm_dir/synthesis-specification.md):
-       clarify_mode = "brainstorm"
-       primary_artifact = brainstorm_dir/synthesis-specification.md
-       INFO: "Brainstorm mode: Analyzing synthesis-specification.md"
-   ELSE:
-       ERROR: "No valid artifact found. Run /workflow:brainstorm:synthesis or /workflow:plan first"
-       EXIT
-
-   # Mode-specific validation
-   IF clarify_mode == "brainstorm":
-       CHECK: brainstorm_dir/topic-framework.md
-       IF NOT EXISTS:
-           WARN: "topic-framework.md not found. Verification will be limited."
-   ```
-
-2. **Load Artifacts (Mode-Aware)**
-   ```bash
-   # Load primary artifact (determined in step 1)
-   primary_content = Read(primary_artifact)
-
-   # Load user's original intent from session metadata
-   session_metadata = Read(.workflow/WFS-{session}/workflow-session.json)
-   original_user_intent = session_metadata.project || session_metadata.description
-   IF NOT original_user_intent:
-       WARN: "No original user intent found in session metadata"
-       original_user_intent = "Not available"
-
-   # Load mode-specific supplementary artifacts
-   IF clarify_mode == "brainstorm":
-       topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists
-       role_analyses = Glob(brainstorm_dir + "/*/analysis.md")
-       participating_roles = extract_role_names(role_analyses)
-   # Plan mode: primary_content (ANALYSIS_RESULTS.md) is self-contained
-   ```
-
-3. **Ambiguity & Coverage Scan**
-
-   Perform structured scan using this taxonomy. For each category, mark status: **Clear** / **Partial** / **Missing**.
-
-   **⚠️ User Intent Alignment** (NEW - HIGHEST PRIORITY):
-   - Primary artifact alignment with original user intent
-   - Goal consistency between artifact and user's stated objectives
-   - Scope match with user's requirements
-   - Success criteria reflects user's expectations
-   - Any unexplained deviations from user intent
-
-   **Requirements Clarity**:
-   - Functional requirements specificity and measurability
-   - Non-functional requirements with quantified targets
-   - Business requirements with success metrics
-   - Acceptance criteria completeness
-
-   **Architecture & Design Clarity**:
-   - Architecture decisions with rationale
-   - Data model completeness (entities, relationships, constraints)
-   - Technology stack justification
-   - Integration points and API contracts
-
-   **User Experience & Interface**:
-   - User journey completeness
-   - Critical interaction flows
-   - Error/edge case handling
-   - Accessibility and localization considerations
-
-   **Implementation Feasibility**:
-   - Team capability vs. required skills
-   - External dependencies and failure modes
-   - Resource constraints (timeline, personnel)
-   - Technical constraints and tradeoffs
-
-   **Risk & Mitigation**:
-   - Critical risks identified
-   - Mitigation strategies defined
-   - Success factors clarity
-   - Monitoring and quality gates
-
-   **Process & Collaboration**:
-   - Role responsibilities and handoffs
-   - Collaboration patterns defined
-   - Timeline and milestone clarity
-   - Dependency management strategy
-
-   **Decision Traceability**:
-   - Controversial points documented
-   - Alternatives considered and rejected
-   - Decision rationale clarity
-   - Consensus vs. dissent tracking
-
-   **Terminology & Consistency**:
-   - Canonical terms defined
-   - Consistent naming across artifacts
-   - No unresolved placeholders (TODO, TBD, ???)
-
-   For each category with **Partial** or **Missing** status, add to candidate question queue unless:
-   - Clarification would not materially change implementation strategy
-   - Information is better deferred to planning phase
-
-4. **Generate Prioritized Question Queue**
-
-   Internally generate prioritized queue of candidate questions (maximum 5):
-
-   **Constraints**:
-   - Maximum 5 questions per session
-   - Each question must be answerable with:
-     * Multiple-choice (2-5 mutually exclusive options), OR
-     * Short answer (≤5 words)
-   - Only include questions whose answers materially impact:
-     * Architecture decisions
-     * Data modeling
-     * Task decomposition
-     * Risk mitigation
-     * Success criteria
-   - Ensure category coverage balance
-   - Favor clarifications that reduce downstream rework risk
-
-   **Prioritization Heuristic**:
-   ```
-   priority_score = (impact_on_planning * 0.4) +
-                    (uncertainty_level * 0.3) +
-                    (risk_if_unresolved * 0.3)
-   ```
-
-   If zero high-impact ambiguities found, proceed to **Step 8** (report success).
-
-5. **Sequential Question Loop** (Interactive)
-
-   Present **EXACTLY ONE** question at a time:
-
-   **Multiple-choice format**:
-   ```markdown
-   **Question {N}/5**: {Question text}
-
-   | Option | Description |
-   |--------|-------------|
-   | A | {Option A description} |
-   | B | {Option B description} |
-   | C | {Option C description} |
-   | D | {Option D description} |
-   | Short | Provide different answer (≤5 words) |
-   ```
-
-   **Short-answer format**:
-   ```markdown
-   **Question {N}/5**: {Question text}
-
-   Format: Short answer (≤5 words)
-   ```
-
-   **Answer Validation**:
-   - Validate answer maps to option or fits ≤5 word constraint
-   - If ambiguous, ask quick disambiguation (doesn't count as new question)
-   - Once satisfactory, record in working memory and proceed to next question
-
-   **Stop Conditions**:
-   - All critical ambiguities resolved
-   - User signals completion ("done", "no more", "proceed")
-   - Reached 5 questions
-
-   **Never reveal future queued questions in advance**.
-
-6. **Integration After Each Answer** (Incremental Update)
-
-   After each accepted answer:
-
-   ```bash
-   # Ensure Clarifications section exists
-   IF primary_content NOT contains "## Clarifications":
-       Insert "## Clarifications" section after first heading
-
-   # Create session subsection
-   IF NOT contains "### Session YYYY-MM-DD":
-       Create "### Session {today's date}" under "## Clarifications"
-
-   # Append clarification entry
-   APPEND: "- Q: {question} → A: {answer}"
-
-   # Apply clarification to appropriate section
-   CASE category:
-       Functional Requirements → Update "## Requirements" or equivalent section
-       Architecture → Update "## Architecture" or "## Design" sections
-       User Experience → Update "## UI/UX" or "## User Experience" sections
-       Risk → Update "## Risks" or "## Risk Assessment" sections
-       Process → Update "## Process" or "## Implementation" sections
-       Data Model → Update "## Data Model" or "## Database" sections
-       Non-Functional → Update "## Non-Functional Requirements" or equivalent
-
-   # Remove obsolete/contradictory statements
-   IF clarification invalidates existing statement:
-       Replace statement instead of duplicating
-
-   # Save immediately to primary_artifact
-   Write(primary_artifact)
-   ```
-
-7. **Validation After Each Write**
-
-   - [ ] Clarifications section contains exactly one bullet per accepted answer
-   - [ ] Total asked questions ≤ 5
-   - [ ] Updated sections contain no lingering placeholders
-   - [ ] No contradictory earlier statements remain
-   - [ ] Markdown structure valid
-   - [ ] Terminology consistent across all updated sections
-
-8. **Completion Report**
-
-   After questioning loop ends or early termination:
-
-   ```markdown
-   ## ✅ Concept Verification Complete
-
-   **Session**: WFS-{session-id}
-   **Mode**: {clarify_mode}
-   **Questions Asked**: {count}/5
-   **Artifacts Updated**: {primary_artifact filename}
-   **Sections Touched**: {list section names}
-
-   ### Coverage Summary
-
-   | Category | Status | Notes |
-   |----------|--------|-------|
-   | Requirements Clarity | ✅ Resolved | Acceptance criteria quantified |
-   | Architecture & Design | ✅ Clear | No ambiguities found |
-   | Implementation Feasibility | ⚠️ Deferred | Team training plan to be defined in IMPL_PLAN |
-   | Risk & Mitigation | ✅ Resolved | Critical risks now have mitigation strategies |
-   | ... | ... | ... |
-
-   **Legend**:
-   - ✅ Resolved: Was Partial/Missing, now addressed
-   - ✅ Clear: Already sufficient
-   - ⚠️ Deferred: Low impact, better suited for planning phase
-   - ❌ Outstanding: Still Partial/Missing but question quota reached
-
-   ### Recommendations
-
-   - ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear
-   - OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items}
-   - OR 🔄 **Run /workflow:concept-clarify Again**: If new information available
-
-   ### Next Steps
-
-   **If Outstanding Items Exist**:
-   1. TodoWrite tracking for outstanding issues
-   2. Call conceptual-planning-agent to fix conceptual gaps
-   3. Wait for user confirmation before proceeding
-
-   **If No Issues**:
-   ```bash
-   /workflow:plan  # Generate IMPL_PLAN.md and task.json
-   ```
-   ```
-
-9. **Update Session Metadata**
-
-   ```bash
-   # Update metadata based on mode
-   IF clarify_mode == "brainstorm":
-       phase_key = "BRAINSTORM"
-   ELSE: # plan mode
-       phase_key = "PLAN"
-
-   # Update session metadata
-   {
-     "phases": {
-       "{phase_key}": {
-         "status": "concept_verified",
-         "concept_verification": {
-           "completed": true,
-           "completed_at": "timestamp",
-           "mode": "{clarify_mode}",
-           "questions_asked": {count},
-           "categories_clarified": [{list}],
-           "outstanding_items": [],
-           "recommendation": "PROCEED" # or "ADDRESS_OUTSTANDING"
-         }
-       }
-     }
-   }
-   ```
-
-## Behavior Rules
-
-- **If no meaningful ambiguities found**: Report "No critical ambiguities detected. Conceptual foundation is clear." and suggest proceeding to `/workflow:plan`.
-- **If synthesis-specification.md missing**: Instruct user to run `/workflow:brainstorm:synthesis` first.
-- **Never exceed 5 questions** (disambiguation retries don't count as new questions).
-- **Respect user early termination**: Signals like "stop", "done", "proceed" should stop questioning.
-- **If quota reached with high-impact items unresolved**: Explicitly flag them under "Outstanding" with recommendation to address before planning.
-- **Avoid speculative tech stack questions** unless absence blocks conceptual clarity.
-
-## Operating Principles
-
-### Context Efficiency
-- **Minimal high-signal tokens**: Focus on actionable clarifications
-- **Progressive disclosure**: Load artifacts incrementally
-- **Deterministic results**: Rerunning without changes produces consistent analysis
-
-### Verification Guidelines
-- **NEVER hallucinate missing sections**: Report them accurately
-- **Prioritize high-impact ambiguities**: Focus on what affects planning
-- **Use examples over exhaustive rules**: Cite specific instances
-- **Report zero issues gracefully**: Emit success report with coverage statistics
-- **Update incrementally**: Save after each answer to minimize context loss
-
-## Context
-
-{ARGS}

.claude/commands/workflow/execute.md

@@ -1,6 +1,6 @@
 ---
 name: execute
-description: Coordinate agents for existing workflow tasks with automatic discovery
+description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking
 argument-hint: "[--resume-session=\"session-id\"]"
 ---
 
@@ -11,6 +11,17 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
 
+## Performance Optimization Strategy
+
+**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| **Initial Load** | All task JSONs (~2,300 lines) | TODO_LIST.md only (~650 lines) | **72% reduction** |
+| **Startup Time** | Seconds | Milliseconds | **~90% faster** |
+| **Memory** | All tasks | 1-2 tasks | **90% less** |
+| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
+
 ## Core Rules
 **Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
 **Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
@@ -63,40 +74,69 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 ### Phase 1: Discovery (Normal Mode Only)
 1. **Check Active Sessions**: Find `.workflow/.active-*` markers
 2. **Select Session**: If multiple found, prompt user selection
-3. **Load Session State**: Read `workflow-session.json` and `IMPL_PLAN.md`
-4. **Scan Tasks**: Analyze `.task/*.json` files for ready tasks
+3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
+4. **DO NOT read task JSONs yet** - defer until execution phase
 
 **Note**: In resume mode, this phase is completely skipped.
 
-### Phase 2: Analysis (Normal Mode Only)
-1. **Dependency Resolution**: Build execution order based on `depends_on`
-2. **Status Validation**: Filter tasks with `status: "pending"` and met dependencies
-3. **Agent Assignment**: Determine agent type from `meta.agent` or `meta.type`
-4. **Context Preparation**: Load dependency summaries and inherited context
+### Phase 2: Planning Document Analysis (Normal Mode Only)
+**Optimized to avoid reading all task JSONs upfront**
+
+1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
+2. **Read TODO_LIST.md**: Get current task statuses and execution progress
+3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
+4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
+
+**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
 
 **Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
 
-### Phase 3: Planning (Resume Mode Entry Point)
+### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
 **This is where resume mode directly enters after skipping Phases 1 & 2**
 
-1. **Create TodoWrite List**: Generate task list with status markers from session state
-2. **Mark Initial Status**: Set first pending task as `in_progress`
+1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
+   - Parse TODO_LIST.md to extract all tasks with current statuses
+   - Identify first pending task with met dependencies
+   - Generate comprehensive TodoWrite covering entire workflow
+2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
 3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
-4. **Prepare Complete Task JSON**: Include pre_analysis and flow control steps for agent consumption
-5. **Validate Prerequisites**: Ensure all required context is available from existing session
+4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
 
 **Resume Mode Behavior**:
-- Load existing session state directly from `.workflow/{session-id}/`
-- Use session's task files and summaries without discovery
-- Generate TodoWrite from current session progress
-- Proceed immediately to agent execution
+- Load existing TODO_LIST.md directly from `.workflow/{session-id}/`
+- Extract current progress from TODO_LIST.md
+- Generate TodoWrite from TODO_LIST.md state
+- Proceed immediately to agent execution (Phase 4)
 
-### Phase 4: Execution
-1. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
-2. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
-3. **Monitor Progress**: Track agent execution and handle errors without user interruption
-4. **Collect Results**: Gather implementation results and outputs
-5. **Continue Workflow**: Automatically proceed to next pending task until completion
+### Phase 4: Execution (Lazy Task Loading)
+**Key Optimization**: Read task JSON **only when needed** for execution
+
+1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
+2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
+3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
+4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
+5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
+6. **Monitor Progress**: Track agent execution and handle errors without user interruption
+7. **Collect Results**: Gather implementation results and outputs
+8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
+9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
+
+**Execution Loop Pattern**:
+```
+while (TODO_LIST.md has pending tasks) {
+  next_task_id = getTodoWriteInProgressTask()
+  task_json = Read(.workflow/{session}/.task/{next_task_id}.json)  // Lazy load
+  executeTaskWithAgent(task_json)
+  updateTodoListMarkCompleted(next_task_id)
+  advanceTodoWriteToNextTask()
+}
+```
+
+**Benefits**:
+- Reduces initial context loading by ~90%
+- Only reads task JSON when actually executing
+- Scales better for workflows with many tasks
+- Faster startup time for workflow execution
 
 ### Phase 5: Completion
 1. **Update Task Status**: Mark completed tasks in JSON files
@@ -108,27 +148,33 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 
 ## Task Discovery & Queue Building
 
-### Session Discovery Process (Normal Mode)
+### Session Discovery Process (Normal Mode - Optimized)
 ```
 ├── Check for .active-* markers in .workflow/
 ├── If multiple active sessions found → Prompt user to select
 ├── Locate selected session's workflow folder
-├── Load selected session's workflow-session.json and IMPL_PLAN.md
-├── Scan selected session's .task/ directory for task JSON files
-├── Analyze task statuses and dependencies for selected session only
-└── Build execution queue of ready tasks from selected session
+├── Load session metadata: workflow-session.json (minimal context)
+├── Read IMPL_PLAN.md (strategy overview and task summary)
+├── Read TODO_LIST.md (current task statuses and dependencies)
+├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
+├── Build execution queue from TODO_LIST.md
+└── Generate TodoWrite from TODO_LIST.md state
 ```
 
-### Resume Mode Process (--resume-session flag)
+**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
+
+### Resume Mode Process (--resume-session flag - Optimized)
 ```
 ├── Use provided session-id directly (skip discovery)
 ├── Validate .workflow/{session-id}/ directory exists
-├── Load session's workflow-session.json and IMPL_PLAN.md directly
-├── Scan session's .task/ directory for task JSON files
-├── Use existing task statuses and dependencies (no re-analysis needed)
-└── Build execution queue from session state (prioritize pending/in-progress tasks)
+├── Read TODO_LIST.md for current progress
+├── Parse TODO_LIST.md to extract task IDs and statuses
+├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
+└── Enter Phase 4 (Execution) with lazy task JSON loading
 ```
 
+**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
+
 ### Task Status Logic
 ```
 pending + dependencies_met → executable
@@ -141,52 +187,72 @@ blocked → skip until dependencies clear
 ### Parallel Execution Algorithm
 **Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
 
-#### Algorithm Steps
+#### Algorithm Steps (Optimized with Lazy Loading)
 ```javascript
 function executeBatchWorkflow(sessionId) {
-  // 1. Build dependency graph from task JSONs
-  const graph = buildDependencyGraph(`.workflow/${sessionId}/.task/*.json`);
+  // 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
+  const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
 
   // 2. Process batches until graph is empty
   while (!graph.isEmpty()) {
     // 3. Identify current batch (tasks with in-degree = 0)
     const batch = graph.getNodesWithInDegreeZero();
 
-    // 4. Check for parallel execution opportunities
-    const parallelGroups = groupByExecutionGroup(batch);
+    // 4. Load task JSONs ONLY for current batch (lazy loading)
+    const batchTaskJsons = batch.map(taskId =>
+      Read(`.workflow/${sessionId}/.task/${taskId}.json`)
+    );
 
-    // 5. Execute batch concurrently
+    // 5. Check for parallel execution opportunities
+    const parallelGroups = groupByExecutionGroup(batchTaskJsons);
+
+    // 6. Execute batch concurrently
     await Promise.all(
       parallelGroups.map(group => executeBatch(group))
     );
 
-    // 6. Update graph: remove completed tasks and their edges
+    // 7. Update graph: remove completed tasks and their edges
     graph.removeNodes(batch);
 
-    // 7. Update TodoWrite to reflect completed batch
+    // 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
+    updateTodoListAfterBatch(batch);
     updateTodoWriteAfterBatch(batch);
   }
 
-  // 8. All tasks complete - auto-complete session
+  // 9. All tasks complete - auto-complete session
   SlashCommand("/workflow:session:complete");
 }
 
-function buildDependencyGraph(taskFiles) {
-  const tasks = loadAllTaskJSONs(taskFiles);
+function buildDependencyGraphFromTodoList(todoListPath) {
+  const todoContent = Read(todoListPath);
+  const tasks = parseTodoListTasks(todoContent);
   const graph = new DirectedGraph();
 
   tasks.forEach(task => {
-    graph.addNode(task.id, task);
-
-    // Add edges for dependencies
-    task.context.depends_on?.forEach(depId => {
-      graph.addEdge(depId, task.id); // Edge from dependency to task
-    });
+    graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
+    task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
   });
 
   return graph;
 }
 
+function parseTodoListTasks(todoContent) {
+  // Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
+  const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
+  const tasks = [];
+  let match;
+
+  while ((match = taskPattern.exec(todoContent)) !== null) {
+    tasks.push({
+      status: match[1] === 'x' ? 'completed' : 'pending',
+      id: match[2],
+      title: match[3]
+    });
+  }
+
+  return tasks;
+}
+
 function groupByExecutionGroup(tasks) {
   const groups = {};
 
@@ -338,18 +404,19 @@ TodoWrite({
 - **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
 
 #### TODO_LIST.md Update Timing
-- **Before Agent Launch**: Update TODO_LIST.md to mark task as `in_progress` (⚠️)
-- **After Task Complete**: Update TODO_LIST.md to mark as `completed` (✅), advance to next
-- **On Error**: Keep as `in_progress` in TODO_LIST.md, add error note
-- **Workflow Complete**: When all tasks completed, call `/workflow:session:complete`
-- **Session End**: Sync all TODO_LIST.md statuses with JSON task files
+**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
+
+- **Before Agent Launch**: Mark task as `in_progress`
+- **After Task Complete**: Mark as `completed`, advance to next
+- **On Error**: Keep as `in_progress`, add error note
+- **Workflow Complete**: Call `/workflow:session:complete`
 
 ### 3. Agent Context Management
 **Comprehensive context preparation** for autonomous agent execution:
 
 #### Context Sources (Priority Order)
 1. **Complete Task JSON**: Full task definition including all fields and artifacts
-2. **Artifacts Context**: Brainstorming outputs and synthesis specifications from task.context.artifacts
+2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
 3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
 4. **Dependency Summaries**: Previous task completion summaries
 5. **Session Context**: Workflow paths and session metadata
@@ -370,10 +437,10 @@ TodoWrite({
 {
   "task": { /* Complete task JSON with artifacts array */ },
   "artifacts": {
-    "synthesis_specification": { "path": ".workflow/WFS-session/.brainstorming/synthesis-specification.md", "priority": "highest" },
-    "topic_framework": { "path": ".workflow/WFS-session/.brainstorming/topic-framework.md", "priority": "medium" },
-    "role_analyses": [ /* Individual role analysis files */ ],
-    "available_artifacts": [ /* All detected brainstorming artifacts */ ]
+    "synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
+    "guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
+    "role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
+    "conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
   },
   "flow_context": {
     "step_outputs": {
@@ -385,7 +452,7 @@ TodoWrite({
   },
   "session": {
     "workflow_dir": ".workflow/WFS-session/",
-    "brainstorming_dir": ".workflow/WFS-session/.brainstorming/",
+    "context_package_path": ".workflow/WFS-session/.process/context-package.json",
     "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
     "summaries_dir": ".workflow/WFS-session/.summaries/",
     "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
@@ -397,10 +464,10 @@ TodoWrite({
 
 #### Context Validation Rules
 - **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
-- **Artifacts Available**: Synthesis specifications and brainstorming outputs accessible
+- **Artifacts Available**: All artifacts loaded from context-package.json
 - **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
 - **Dependencies Loaded**: All depends_on summaries available
-- **Session Paths Valid**: All workflow paths exist and accessible, including .brainstorming directory
+- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
 - **Agent Assignment**: Valid agent type specified in meta.agent
 
 ### 4. Agent Execution Pattern
@@ -417,13 +484,13 @@ Task(subagent_type="{meta.agent}",
      ## Instructions
      1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control)
      2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially:
-        - Load artifacts (synthesis-specification.md, role analyses) using commands in each step
+        - Load artifacts (role analysis documents, role analyses) using commands in each step
         - Accumulate context from step outputs using variable substitution [variable_name]
         - Handle errors per step.on_error (skip_optional | fail | retry_once)
      3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context
      4. **Complete Task**:
         - Update task status: `jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}`
-        - Update TODO list: {session.todo_list_path}
+        - Update TODO_LIST.md: Mark task as [x] completed in {session.todo_list_path}
         - Generate summary: {session.summaries_dir}/{task.id}-summary.md
         - Check workflow completion and call `/workflow:session:complete` if all tasks done
 
@@ -466,7 +533,7 @@ Task(subagent_type="{meta.agent}",
   "status": "pending|active|completed|blocked",
   "meta": {
     "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
+    "agent": "@code-developer|@test-fix-agent|@universal-executor"
   },
   "context": {
     "requirements": ["req1", "req2"],
@@ -477,15 +544,16 @@ Task(subagent_type="{meta.agent}",
     "artifacts": [
       {
         "type": "synthesis_specification",
-        "source": "brainstorm_synthesis",
-        "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
+        "source": "context-package.json → brainstorm_artifacts.synthesis_output",
+        "path": "{{loaded dynamically from context-package.json}}",
         "priority": "highest",
         "contains": "complete_integrated_specification"
       },
       {
         "type": "individual_role_analysis",
-        "source": "brainstorm_roles",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md",
+        "source": "context-package.json → brainstorm_artifacts.role_analyses[]",
+        "path": "{{loaded dynamically from context-package.json}}",
+        "note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
         "priority": "low",
         "contains": "role_specific_analysis_fallback"
       }
@@ -495,10 +563,11 @@ Task(subagent_type="{meta.agent}",
     "pre_analysis": [
       {
         "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification from brainstorming",
+        "action": "Load synthesis specification from context-package.json",
         "commands": [
-          "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'synthesis specification not found')",
-          "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
+          "Read(.workflow/WFS-[session]/.process/context-package.json)",
+          "Extract(brainstorm_artifacts.synthesis_output.path)",
+          "Read(extracted path)"
         ],
         "output_to": "synthesis_specification",
         "on_error": "skip_optional"
@@ -513,16 +582,16 @@ Task(subagent_type="{meta.agent}",
     "implementation_approach": [
       {
         "step": 1,
-        "title": "Implement task following synthesis specification",
-        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "title": "Implement task following role analyses",
+        "description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
         "modification_points": [
-          "Apply consolidated requirements from synthesis-specification.md",
+          "Apply consolidated requirements from role analysis documents",
           "Follow technical guidelines from synthesis",
           "Consult artifacts for implementation details when needed",
           "Integrate with existing patterns"
         ],
         "logic_flow": [
-          "Load synthesis specification",
+          "Load role analyses",
           "Parse architecture and requirements",
           "Implement following specification",
           "Consult artifacts for technical details when needed",
@@ -552,7 +621,7 @@ meta.agent missing → Infer from meta.type:
   - "feature" → @code-developer
   - "test-gen" → @code-developer
   - "test-fix" → @test-fix-agent
-  - "review" → @general-purpose
+  - "review" → @universal-executor
   - "docs" → @doc-generator
 ```
 

.claude/commands/workflow/plan.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
+description: 5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
 argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -13,20 +13,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 **Execution Model - Auto-Continue Workflow with Quality Gate**:
 
-This workflow runs **mostly autonomously** once triggered, with one interactive quality gate (Phase 3.5). Phases 3 and 4 are delegated to specialized agents for complex analysis and task generation.
+This workflow runs **fully autonomously** once triggered. Phase 3 (conflict resolution) and Phase 4 (task generation) are delegated to specialized agents.
+
 
 1. **User triggers**: `/workflow:plan "task"`
 2. **Phase 1 executes** → Session discovery → Auto-continues
 3. **Phase 2 executes** → Context gathering → Auto-continues
-4. **Phase 3 executes** (cli-execution-agent) → Intelligent analysis → Auto-continues
-5. **Phase 3.5 executes** → **Pauses for user Q&A** → User answers clarification questions → Auto-continues
-6. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
+4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
+5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
 
 **Auto-Continue Mechanism**:
 - TodoList tracks current phase status
 - After each phase completion, automatically executes next pending phase
-- **Phase 3.5 requires user interaction** - answers clarification questions (up to 5)
-- If no ambiguities found, Phase 3.5 auto-skips and continues to Phase 4
+- All phases run autonomously without user interaction (clarification handled in brainstorm phase)
 - Progress updates shown at each phase for visibility
 
 **Execution Modes**:
@@ -96,23 +95,31 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 ---
 
-### Phase 3: Intelligent Analysis
+### Phase 3: Conflict Resolution (Optional - auto-triggered by conflict risk)
 
-**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")`
+**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
 
-**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2
+**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
+
+**Input**:
+- sessionId from Phase 1
+- contextPath from Phase 2
+- conflict_risk from context-package.json
 
 **Parse Output**:
-- Extract: Execution status (success/failed)
-- Verify: ANALYSIS_RESULTS.md file path
+- Extract: Execution status (success/skipped/failed)
+- Verify: CONFLICT_RESOLUTION.md file path (if executed)
 
 **Validation**:
-- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists
+- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
 
+**Skip Behavior**:
+- If conflict_risk is "none" or "low", skip directly to Phase 3.5
+- Display: "No significant conflicts detected, proceeding to clarification"
 
-**TodoWrite**: Mark phase 3 completed, phase 3.5 in_progress
+**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
 
-**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 3.5
+**After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
 
 **Memory State Check**:
 - Evaluate current context window usage and memory state
@@ -124,47 +131,33 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 ---
 
-### Phase 3.5: Concept Clarification (Quality Gate)
+### Phase 3.5: Pre-Task Generation Validation (Optional Quality Gate)
 
-**Command**: `SlashCommand(command="/workflow:concept-clarify --session [sessionId]")`
+**Purpose**: Optional quality gate before task generation - primarily handled by brainstorm synthesis phase
 
-**Purpose**: Quality gate to verify and clarify analysis results before task generation
 
-**Input**: `sessionId` from Phase 1
+**Current Behavior**: Auto-skip to Phase 4 (Task Generation)
 
-**Behavior**:
-- Auto-detects plan mode (ANALYSIS_RESULTS.md exists)
-- Interactively asks up to 5 targeted questions to resolve ambiguities
-- Updates ANALYSIS_RESULTS.md with clarifications
-- Pauses workflow for user input (breaks auto-continue temporarily)
+**Future Enhancement**: Could add additional validation steps like:
+- Cross-reference checks between conflict resolution and brainstorm analyses
+- Final sanity checks before task generation
+- User confirmation prompt for proceeding
 
-**Parse Output**:
-- Verify clarifications added to ANALYSIS_RESULTS.md
-- Check recommendation: "PROCEED" or "ADDRESS_OUTSTANDING"
+**TodoWrite**: Mark phase 3.5 completed (auto-skip), phase 4 in_progress
 
-**Validation**:
-- ANALYSIS_RESULTS.md updated with `## Clarifications` section
-- All critical ambiguities resolved or documented as outstanding
-
-**TodoWrite**: Mark phase 3.5 completed, phase 4 in_progress
-
-**After Phase 3.5**: Return to user showing clarification summary, then auto-continue to Phase 4
-
-**Skip Conditions**:
-- If `/workflow:concept-clarify` reports "No critical ambiguities detected", automatically proceed to Phase 4
-- User can skip by responding "skip" or "proceed" immediately
+**After Phase 3.5**: Auto-continue to Phase 4 immediately
 
 ---
 
 ### Phase 4: Task Generation
 
 **Relationship with Brainstorm Phase**:
-- If brainstorm synthesis exists (synthesis-specification.md), Phase 3 analysis incorporates it as input
-- **⚠️ User's original intent is ALWAYS primary**: New or refined user goals override synthesis recommendations
-- **synthesis-specification.md defines "WHAT"**: Requirements, design specs, high-level features
+- If brainstorm role analyses exist ([role]/analysis.md files), Phase 3 analysis incorporates them as input
+- **User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations
+- **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights
 - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
-- Task generation translates high-level specifications into concrete, actionable work items
-- **Intent priority**: Current user prompt > synthesis-specification.md > topic-framework.md
+- Task generation translates high-level role analyses into concrete, actionable work items
+- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
 
 **Command Selection**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
@@ -199,36 +192,48 @@ Planning complete for session: [sessionId]
 Tasks generated: [count]
 Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
-✅ Recommended Next Steps:
+Recommended Next Steps:
 1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
 2. /workflow:status  # Review task breakdown
 3. /workflow:execute  # Start implementation (after verification)
 
-⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
+Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
 // Initialize (before Phase 1)
+// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
 TodoWrite({todos: [
   {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
   {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
-  {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
+  // Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// After Phase 1
+// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
 TodoWrite({todos: [
   {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
-  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
-  {"content": "Execute concept clarification", "status": "pending", "activeForm": "Executing concept clarification"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// Continue pattern for Phase 2, 3, 3.5, 4...
+// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
+]})
+
+// After Phase 3 (if executed), continue to Phase 4
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
+]})
 ```
 
 ## Input Processing
@@ -277,20 +282,22 @@ Phase 1: session:start --auto "structured-description"
     ↓
 Phase 2: context-gather --session sessionId "structured-description"
     ↓ Input: sessionId + session memory + structured description
-    ↓ Output: contextPath (context-package.json)
+    ↓ Output: contextPath (context-package.json) + conflict_risk
     ↓
-Phase 3: cli-execution-agent (Intelligent Analysis)
-    ↓ Input: sessionId + contextPath + task description
-    ↓ Agent discovers context, enhances prompt, executes with Gemini
-    ↓ Output: ANALYSIS_RESULTS.md + execution log
-    ↓
-Phase 3.5: concept-clarify --session sessionId (Quality Gate)
-    ↓ Input: sessionId + ANALYSIS_RESULTS.md (auto-detected)
-    ↓ Interactive: User answers clarification questions
-    ↓ Output: Updated ANALYSIS_RESULTS.md with clarifications
+Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
+    ↓ Input: sessionId + contextPath + conflict_risk
+    ↓ CLI-powered conflict detection (JSON output)
+    ↓ AskUserQuestion: Present conflicts + resolution strategies
+    ↓ User selects strategies (or skip)
+    ↓ Apply modifications via Edit tool:
+    ↓   - Update guidance-specification.md
+    ↓   - Update role analyses (*.md)
+    ↓   - Mark context-package.json as "resolved"
+    ↓ Output: Modified brainstorm artifacts (NO report file)
+    ↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
     ↓
 Phase 4: task-generate[--agent] --session sessionId
-    ↓ Input: sessionId + clarified ANALYSIS_RESULTS.md + session memory
+    ↓ Input: sessionId + resolved brainstorm artifacts + session memory
     ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
     ↓
 Return summary to user
@@ -299,7 +306,7 @@ Return summary to user
 **Session Memory Flow**: Each phase receives session ID, which provides access to:
 - Previous task summaries
 - Existing context and analysis
-- Brainstorming artifacts
+- Brainstorming artifacts (potentially modified by Phase 3)
 - Session-specific configuration
 
 **Structured Description Benefits**:
@@ -316,27 +323,24 @@ Return summary to user
 
 ## Coordinator Checklist
 
-✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
-✅ Initialize TodoWrite before any command (include Phase 3.5)
-✅ Execute Phase 1 immediately with structured description
-✅ Parse session ID from Phase 1 output, store in memory
-✅ Pass session ID and structured description to Phase 2 command
-✅ Parse context path from Phase 2 output, store in memory
-✅ **Launch Phase 3 agent**: Build Task prompt with sessionId and contextPath
-✅ Wait for agent completion, parse execution log path
-✅ Verify ANALYSIS_RESULTS.md created by agent
-✅ **Execute Phase 3.5**: Pass session ID to `/workflow:concept-clarify`
-✅ Wait for user interaction (clarification Q&A)
-✅ Verify ANALYSIS_RESULTS.md updated with clarifications
-✅ Check recommendation: proceed if "PROCEED", otherwise alert user
-✅ **Build Phase 4 command** based on flags:
+- **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
+- Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
+- Execute Phase 1 immediately with structured description
+- Parse session ID from Phase 1 output, store in memory
+- Pass session ID and structured description to Phase 2 command
+- Parse context path from Phase 2 output, store in memory
+- **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
+- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
+- Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
+- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
+- **Build Phase 4 command** based on flags:
   - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
   - Add `--session [sessionId]`
   - Add `--cli-execute` if flag present
-✅ Pass session ID to Phase 4 command
-✅ Verify all Phase 4 outputs
-✅ Update TodoWrite after each phase
-✅ After each phase, automatically continue to next phase based on TodoList status
+- Pass session ID to Phase 4 command
+- Verify all Phase 4 outputs
+- Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
+- After each phase, automatically continue to next phase based on TodoList status
 
 ## Structure Template Reference
 
@@ -364,3 +368,22 @@ CONSTRAINTS: [Limitations or boundaries]
 # Phase 2
 /workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
 ```
+
+## Related Commands
+
+**Prerequisite Commands**:
+- `/workflow:brainstorm:artifacts` - Optional: Generate role-based analyses before planning (if complex requirements need multiple perspectives)
+- `/workflow:brainstorm:synthesis` - Optional: Refine brainstorm analyses with clarifications
+
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create or discover workflow session
+- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
+- `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
+- `/compact` - Phase 3: Memory optimization (if context approaching limits)
+- `/workflow:tools:task-generate` - Phase 4: Generate task JSON files with manual approach
+- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach (when `--agent` flag used)
+
+**Follow-up Commands**:
+- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution
+- `/workflow:status` - Review task breakdown and current progress
+- `/workflow:execute` - Begin implementation of generated tasks

.claude/commands/workflow/resume.md

@@ -1,6 +1,6 @@
 ---
 name: resume
-description: Intelligent workflow session resumption with automatic progress analysis
+description: Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection
 argument-hint: "session-id for workflow session to resume"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -89,5 +89,17 @@ The special `--resume-session` flag tells `/workflow:execute`:
 3. **Agent coordination**: TodoWrite and agent execution initiated successfully
 4. **Context preservation**: Session state and progress properly maintained
 
+## Related Commands
+
+**Prerequisite Commands**:
+- `/workflow:plan` or `/workflow:execute` - Workflow must be in progress or paused
+
+**Called by This Command** (2 phases):
+- `/workflow:status` - Phase 1: Analyze current session status and identify resume point
+- `/workflow:execute` - Phase 2: Resume execution with `--resume-session` flag
+
+**Follow-up Commands**:
+- None - Workflow continues automatically via `/workflow:execute`
+
 ---
 *Sequential command coordination for workflow session resumption*

.claude/commands/workflow/review.md

@@ -1,20 +1,20 @@
 ---
 name: review
-description: Optional specialized review (security, architecture, docs) for completed implementation
+description: Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini
 argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
 ---
 
-### 🚀 Command Overview: `/workflow:review`
+## Command Overview: /workflow:review
 
 **Optional specialized review** for completed implementations. In the standard workflow, **passing tests = approved code**. Use this command only when specialized review is required (security, architecture, compliance, docs).
 
 ## Philosophy: "Tests Are the Review"
 
-- ✅ **Default**: All tests pass → Code approved
-- 🔍 **Optional**: Specialized reviews for:
-  - 🔒 Security audits (vulnerabilities, auth/authz)
-  - 🏗️ Architecture compliance (patterns, technical debt)
-  - 📋 Action items verification (requirements met, acceptance criteria)
+- **Default**: All tests pass -> Code approved
+- **Optional**: Specialized reviews for:
+  - Security audits (vulnerabilities, auth/authz)
+  - Architecture compliance (patterns, technical debt)
+  - Action items verification (requirements met, acceptance criteria)
 
 ## Review Types
 
@@ -44,13 +44,13 @@ fi
 
 # Step 2: Validation
 if [ ! -d ".workflow/${sessionId}" ]; then
-    echo "❌ Session ${sessionId} not found"
+    echo "Session ${sessionId} not found"
     exit 1
 fi
 
 # Check for completed tasks
 if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
-    echo "❌ No completed implementation found. Complete implementation first"
+    echo "No completed implementation found. Complete implementation first"
     exit 1
 fi
 
@@ -59,7 +59,7 @@ review_type="${TYPE_ARG:-quality}"
 
 # Redirect docs review to specialized command
 if [ "$review_type" = "docs" ]; then
-    echo "💡 For documentation generation, please use:"
+    echo "For documentation generation, please use:"
     echo "   /workflow:tools:docs"
     echo ""
     echo "The docs command provides:"
@@ -73,7 +73,7 @@ fi
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 ```
 
-### 🧠 Model Analysis Phase
+### Model Analysis Phase
 
 After bash validation, the model takes control to:
 
@@ -92,17 +92,17 @@ After bash validation, the model takes control to:
 2. **Perform Specialized Review**: Based on `review_type`
 
    **Security Review** (`--type=security`):
-   - Use MCP code search for security patterns:
+   - Use ripgrep for security patterns:
      ```bash
-     mcp__code-index__search_code_advanced(pattern="password|token|secret|auth", file_pattern="*.{ts,js,py}")
-     mcp__code-index__search_code_advanced(pattern="eval|exec|innerHTML|dangerouslySetInnerHTML", file_pattern="*.{ts,js,tsx}")
+     rg "password|token|secret|auth" -g "*.{ts,js,py}"
+     rg "eval|exec|innerHTML|dangerouslySetInnerHTML" -g "*.{ts,js,tsx}"
      ```
    - Use Gemini for security analysis:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Security audit of completed implementation
      TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Security findings report with severity levels
      RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
      " --approval-mode yolo
@@ -111,10 +111,10 @@ After bash validation, the model takes control to:
    **Architecture Review** (`--type=architecture`):
    - Use Qwen for architecture analysis:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/qwen-wrapper -p "
+     cd .workflow/${sessionId} && qwen -p "
      PURPOSE: Architecture compliance review
      TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Architecture assessment with recommendations
      RULES: Check for patterns, separation of concerns, modularity, scalability
      " --approval-mode yolo
@@ -123,10 +123,10 @@ After bash validation, the model takes control to:
    **Quality Review** (`--type=quality`):
    - Use Gemini for code quality:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Code quality and best practices review
      TASK: Assess code readability, maintainability, adherence to best practices
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Quality assessment with improvement suggestions
      RULES: Check for code smells, duplication, complexity, naming conventions
      " --approval-mode yolo
@@ -143,10 +143,10 @@ After bash validation, the model takes control to:
      ' {} \;
 
      # Check implementation summaries against requirements
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Verify all requirements and acceptance criteria are met
      TASK: Cross-check implementation summaries against original requirements
-     CONTEXT: @{.task/IMPL-*.json,.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED:
      - Requirements coverage matrix
      - Acceptance criteria verification
@@ -205,7 +205,7 @@ After bash validation, the model takes control to:
    ```bash
    # If architecture or quality issues found, suggest memory update
    if [ "$review_type" = "architecture" ] || [ "$review_type" = "quality" ]; then
-       echo "💡 Consider updating project documentation:"
+       echo "Consider updating project documentation:"
        echo "   /update-memory-related"
    fi
    ```
@@ -226,7 +226,7 @@ After bash validation, the model takes control to:
 /workflow:review --type=docs
 ```
 
-## ✨ Features
+## Features
 
 - **Simple Validation**: Check session exists and has completed tasks
 - **No Complex Orchestration**: Direct analysis, no multi-phase pipeline
@@ -240,10 +240,10 @@ After bash validation, the model takes control to:
 
 ```
 Standard Workflow:
-  plan → execute → test-gen → execute ✅
+  plan -> execute -> test-gen -> execute (complete)
 
 Optional Review (when needed):
-  plan → execute → test-gen → execute → review (security/architecture/docs)
+  plan -> execute -> test-gen -> execute -> review (security/architecture/docs)
 ```
 
 **When to Use**:
@@ -256,11 +256,3 @@ Optional Review (when needed):
 - Regular development (tests are sufficient)
 - Simple bug fixes (test-fix-agent handles it)
 - Minor changes (update-memory-related is enough)
-
-## Related Commands
-
-- `/workflow:execute` - Must complete implementation first
-- `/workflow:test-gen` - Primary quality gate (tests)
-- `/workflow:tools:docs` - Generate hierarchical documentation (use instead of `--type=docs`)
-- `/update-memory-related` - Update CLAUDE.md docs after architecture findings
-- `/workflow:status` - Check session status

.claude/commands/workflow/session/complete.md

@@ -1,6 +1,6 @@
 ---
 name: complete
-description: Mark the active workflow session as complete and remove active flag
+description: Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag
 examples:
   - /workflow:session:complete
   - /workflow:session:complete --detailed
@@ -9,7 +9,7 @@ examples:
 # Complete Workflow Session (/workflow:session:complete)
 
 ## Overview
-Mark the currently active workflow session as complete, update its status, and remove the active flag marker.
+Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
 
 ## Usage
 ```bash
@@ -19,87 +19,129 @@ Mark the currently active workflow session as complete, update its status, and r
 
 ## Implementation Flow
 
-### Step 1: Find Active Session
+### Phase 1: Prepare for Archival (Minimal Manual Operations)
+
+**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
+
+#### Step 1.1: Find Active Session and Get Name
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-```
+# Find active marker
+bash(find .workflow/ -name ".active-*" -type f | head -1)
 
-### Step 2: Get Session Name
+# Extract session name from marker path
+bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+```
+**Output**: Session name `WFS-session-name`
+
+#### Step 1.2: Move Session to Archive
 ```bash
-basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
+# Create archive directory if needed
+bash(mkdir -p .workflow/.archives/)
+
+# Move session to archive location
+bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+```
+**Result**: Session now at `.workflow/.archives/WFS-session-name/`
+
+### Phase 2: Agent-Orchestrated Completion (All Data Processing)
+
+**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
+
+#### Agent Invocation
+
+Invoke `universal-executor` agent to complete the archival process.
+
+**Agent Task**:
+```
+Task(
+  subagent_type="universal-executor",
+  description="Complete session archival",
+  prompt=`
+Complete workflow session archival. Session already moved to archive location.
+
+## Context
+- Session: .workflow/.archives/WFS-session-name/
+- Active marker: .workflow/.active-WFS-session-name
+
+## Tasks
+
+1. **Extract session data** from workflow-session.json (session_id, description/topic, started_at/timestamp, completed_at, status)
+   - If status != "completed", update it with timestamp
+
+2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
+
+3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt (fallback: analyze files directly)
+   - Return: {successes, challenges, watch_patterns}
+
+4. **Build archive entry**:
+   - Calculate: duration_hours, success_rate, tags (3-5 keywords)
+   - Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons
+
+5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
+
+6. **Remove active marker**
+
+7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
+
+## Error Handling
+- On failure: return {"status": "error", "task": "...", "message": "..."}
+- Do NOT remove marker if failed
+  `
+)
 ```
 
-### Step 3: Update Session Status
+**Expected Output**:
+- Agent returns JSON result confirming successful archival
+- Display completion summary to user based on agent response
+
+## Workflow Execution Strategy
+
+### Two-Phase Approach (Optimized)
+
+**Phase 1: Minimal Manual Setup** (2 simple operations)
+- Find active session and extract name
+- Move session to archive location
+- **No data extraction** - agent handles all data processing
+- **No counting** - agent does this from archive location
+- **Total**: 2 bash commands (find + move)
+
+**Phase 2: Agent-Driven Completion** (1 agent invocation)
+- Extract all session data from archived location
+- Count tasks and summaries
+- Generate lessons learned analysis
+- Build complete archive metadata
+- Update manifest
+- Remove active marker
+- Return success/error result
+
+## Quick Commands
+
 ```bash
-jq '.status = "completed"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+# Phase 1: Find and move
+bash(find .workflow/ -name ".active-*" -type f | head -1)
+bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+bash(mkdir -p .workflow/.archives/)
+bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+
+# Phase 2: Agent completes archival
+Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
 ```
 
-### Step 4: Add Completion Timestamp
+## Archive Query Commands
+
+After archival, you can query the manifest:
+
 ```bash
-jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+# List all archived sessions
+jq '.archives[].session_id' .workflow/.archives/manifest.json
+
+# Find sessions by keyword
+jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
+
+# Get specific session details
+jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
+
+# List all watch patterns across sessions
+jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
 ```
 
-### Step 5: Count Final Statistics
-```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
-```
-
-### Step 6: Remove Active Marker
-```bash
-rm .workflow/.active-WFS-session-name
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Find active session**: `find .workflow/ -name ".active-*" -type f`
-- **Get session name**: `basename marker | sed 's/^\.active-//'`
-- **Update status**: `jq '.status = "completed"' session.json > temp.json`
-- **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
-- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
-- **Remove marker**: `rm .workflow/.active-session`
-
-### Completion Result
-```
-Session WFS-user-auth completed
-- Status: completed
-- Started: 2025-09-15T10:00:00Z
-- Completed: 2025-09-15T16:30:00Z
-- Duration: 6h 30m
-- Total tasks: 8
-- Completed tasks: 8
-- Success rate: 100%
-```
-
-### Detailed Summary (--detailed flag)
-```
-Session Completion Summary:
-├── Session: WFS-user-auth
-├── Project: User authentication system
-├── Total time: 6h 30m
-├── Tasks completed: 8/8 (100%)
-├── Files generated: 24 files
-├── Summaries created: 8 summaries
-├── Status: All tasks completed successfully
-└── Location: .workflow/WFS-user-auth/
-```
-
-### Error Handling
-```bash
-# No active session
-find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
-
-# Incomplete tasks
-task_count=$(find .task/ -name "*.json" -type f | wc -l)
-summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
-```
-
-## Related Commands
-- `/workflow:session:list` - View all sessions including completed
-- `/workflow:session:start` - Start new session
-- `/workflow:status` - Check completion status before completing

.claude/commands/workflow/session/list.md

@@ -1,6 +1,6 @@
 ---
 name: list
-description: List all workflow sessions with status
+description: List all workflow sessions with status filtering, shows session metadata and progress information
 examples:
   - /workflow:session:list
 ---
@@ -59,19 +59,19 @@ jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
 ```
 Workflow Sessions:
 
-✅ WFS-oauth-integration (ACTIVE)
+[ACTIVE] WFS-oauth-integration
    Project: OAuth2 authentication system
    Status: active
    Progress: 3/8 tasks completed
    Created: 2025-09-15T10:30:00Z
 
-⏸️ WFS-user-profile (PAUSED)
+[PAUSED] WFS-user-profile
    Project: User profile management
    Status: paused
    Progress: 1/5 tasks completed
    Created: 2025-09-14T14:15:00Z
 
-📁 WFS-database-migration (COMPLETED)
+[COMPLETED] WFS-database-migration
    Project: Database schema migration
    Status: completed
    Progress: 4/4 tasks completed
@@ -81,10 +81,10 @@ Total: 3 sessions (1 active, 1 paused, 1 completed)
 ```
 
 ### Status Indicators
-- **✅**: Active session
-- **⏸️**: Paused session
-- **📁**: Completed session
-- **❌**: Error/corrupted session
+- **[ACTIVE]**: Active session
+- **[PAUSED]**: Paused session
+- **[COMPLETED]**: Completed session
+- **[ERROR]**: Error/corrupted session
 
 ### Quick Commands
 ```bash
@@ -96,9 +96,4 @@ ls .workflow/.active-* | basename | sed 's/^\.active-//'
 
 # Show recent sessions
 ls -t .workflow/WFS-*/workflow-session.json | head -3
-```
-
-## Related Commands
-- `/workflow:session:start` - Create new session
-- `/workflow:session:switch` - Switch to different session
-- `/workflow:session:status` - Detailed session info
+```

.claude/commands/workflow/session/resume.md

@@ -1,6 +1,6 @@
 ---
 name: resume
-description: Resume the most recently paused workflow session
+description: Resume the most recently paused workflow session with automatic session discovery and status update
 ---
 
 # Resume Workflow Session (/workflow:session:resume)
@@ -64,9 +64,4 @@ Session WFS-user-auth resumed
 - Paused at: 2025-09-15T14:30:00Z
 - Resumed at: 2025-09-15T15:45:00Z
 - Ready for: /workflow:execute
-```
-
-## Related Commands
-- `/workflow:session:pause` - Pause current session
-- `/workflow:execute` - Continue workflow execution
-- `/workflow:session:list` - Show all sessions
+```

.claude/commands/workflow/session/start.md

@@ -1,6 +1,6 @@
 ---
 name: start
-description: Discover existing sessions or start a new workflow session with intelligent session management
+description: Discover existing sessions or start new workflow session with intelligent session management and conflict detection
 argument-hint: [--auto|--new] [optional: task description for new session]
 examples:
   - /workflow:session:start
@@ -212,9 +212,4 @@ bash(echo '{"session_id":"WFS-test","project":"test project","status":"planning"
 - Pattern: `WFS-[lowercase-slug]`
 - Characters: `a-z`, `0-9`, `-` only
 - Max length: 50 characters
-- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)
-
-## Related Commands
-- `/workflow:plan` - Uses `--auto` mode for session management
-- `/workflow:execute` - Uses discovery mode for session selection
-- `/workflow:session:status` - Shows detailed session information
+- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)

.claude/commands/workflow/status.md

@@ -1,6 +1,6 @@
 ---
 name: workflow:status
-description: Generate on-demand views from JSON task data
+description: Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view
 argument-hint: "[optional: task-id]"
 ---
 
@@ -51,11 +51,11 @@ find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 **Progress**: 3/8 tasks completed
 
 ## Active Tasks
-- [⚠️] impl-1: Current task in progress
+- [IN PROGRESS] impl-1: Current task in progress
 - [ ] impl-2: Next pending task
 
 ## Completed Tasks
-- [✅] impl-0: Setup completed
+- [COMPLETED] impl-0: Setup completed
 ```
 
 ## Simple Bash Commands
@@ -112,13 +112,8 @@ Summary: .summaries/impl-1-summary.md
 
 ### Validation Results
 ```
-✅ Session file valid
-✅ 8 task files found
-✅ 3 summaries found
-⚠️ 5 tasks pending completion
-```
-
-## Related Commands
-- `/workflow:execute` - Uses this for task discovery
-- `/workflow:resume` - Uses this for progress analysis
-- `/workflow:session:status` - Shows session metadata
+Session file valid
+8 task files found
+3 summaries found
+5 tasks pending completion
+```

.claude/commands/workflow/tdd-plan.md

@@ -1,6 +1,6 @@
 ---
 name: tdd-plan
-description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
+description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
 argument-hint: "[--agent] \"feature description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -20,12 +20,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data for next phase
-4. **Sequential Execution**: Each phase depends on previous output
-5. **Complete All Phases**: Do not return until Phase 7 completes (with concept verification)
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
 6. **TDD Context**: All descriptions include "TDD:" prefix
-7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
+7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
 
-## 7-Phase Execution (with Concept Verification)
+## 6-Phase Execution (with Conflict Resolution)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -41,10 +41,32 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Extract sessionId
 
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
+
+---
+
 ### Phase 2: Context Gathering
 **Command**: `/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"`
 
-**Parse**: Extract contextPath
+**Use Same Structured Description**: Pass the same structured format from Phase 1
+
+**Input**: `sessionId` from Phase 1
+
+**Parse Output**:
+- Extract: context-package.json path (store as `contextPath`)
+- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
+
+**Validation**:
+- Context package path extracted
+- File exists and is valid JSON
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+
+---
 
 ### Phase 3: Test Coverage Analysis
 **Command**: `/workflow:tools:test-context-gather --session [sessionId]`
@@ -63,34 +85,49 @@ TEST_FOCUS: [Test scenarios]
 - Prevents duplicate test creation
 - Enables integration with existing tests
 
-### Phase 4: TDD Analysis
-**Command**: `/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]`
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
-**Note**: Generates ANALYSIS_RESULTS.md with TDD-specific structure:
-- Feature list with testable requirements
-- Test cases for Red phase
-- Implementation requirements for Green phase
-- Refactoring opportunities
-- Task dependencies and execution order
+**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
 
-**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
+---
 
-### Phase 5: Concept Verification (NEW QUALITY GATE)
-**Command**: `/workflow:concept-verify --session [sessionId]`
+### Phase 4: Conflict Resolution (Optional - auto-triggered by conflict risk)
 
-**Purpose**: Verify conceptual clarity before TDD task generation
-- Clarify test requirements and acceptance criteria
-- Resolve ambiguities in expected behavior
-- Validate TDD approach is appropriate
+**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
 
-**Behavior**:
-- If no ambiguities found → Auto-proceed to Phase 6
-- If ambiguities exist → Interactive clarification (up to 5 questions)
-- After clarifications → Auto-proceed to Phase 6
+**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
 
-**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+**Input**:
+- sessionId from Phase 1
+- contextPath from Phase 2
+- conflict_risk from context-package.json
 
-### Phase 6: TDD Task Generation
+**Parse Output**:
+- Extract: Execution status (success/skipped/failed)
+- Verify: CONFLICT_RESOLUTION.md file path (if executed)
+
+**Validation**:
+- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
+
+**Skip Behavior**:
+- If conflict_risk is "none" or "low", skip directly to Phase 5
+- Display: "No significant conflicts detected, proceeding to TDD task generation"
+
+**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
+
+**After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
+
+**Memory State Check**:
+- Evaluate current context window usage and memory state
+- If memory usage is high (>110K tokens or approaching context limits):
+  - **Command**: `SlashCommand(command="/compact")`
+  - This optimizes memory before proceeding to Phase 5
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
+---
+
+### Phase 5: TDD Task Generation
 **Command**:
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
@@ -108,7 +145,7 @@ TEST_FOCUS: [Test scenarios]
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 - Task count ≤10 (compliance with task limit)
 
-### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
+### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
 **Internal Validation**:
@@ -134,14 +171,14 @@ Total tasks: [M] (1 task per simple feature + subtasks for complex features)
 Task breakdown:
 - Simple features: [K] tasks (IMPL-1 to IMPL-K)
 - Complex features: [L] features with [P] subtasks
-- Total task count: [M] (within 10-task limit ✅)
+- Total task count: [M] (within 10-task limit)
 
 Structure:
-- IMPL-1: {Feature 1 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
-- IMPL-2: {Feature 2 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
+- IMPL-2: {Feature 2 Name} (Internal: Red → Green → Refactor)
 - IMPL-3: {Complex Feature} (Container)
-  - IMPL-3.1: {Sub-feature A} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
-  - IMPL-3.2: {Sub-feature B} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+  - IMPL-3.1: {Sub-feature A} (Internal: Red → Green → Refactor)
+  - IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor)
 [...]
 
 Plans generated:
@@ -155,29 +192,55 @@ TDD Configuration:
 - Green phase includes test-fix cycle (max 3 iterations)
 - Auto-revert on max iterations reached
 
-✅ Recommended Next Steps:
+Recommended Next Steps:
 1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
 2. /workflow:execute --session [sessionId]  # Start TDD execution
 3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
 
-⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
+Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize (7 phases now with concept verification)
-[
-  {content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
-  {content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
-  {content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
-  {content: "Execute TDD analysis", status: "pending", activeForm": "Executing TDD analysis"},
-  {content: "Execute concept verification", status: "pending", activeForm": "Executing concept verification"},
-  {content: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
-  {content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
-]
+// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
+  // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
 
-// Update after each phase: mark current "completed", next "in_progress"
+// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
+
+// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
+
+// After Phase 4 (if executed), continue to Phase 5
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
 ```
 
 ## Input Processing
@@ -195,11 +258,6 @@ Convert user input to TDD-structured format:
 - **Command failure**: Keep phase in_progress, report error
 - **TDD validation failure**: Report incomplete chains or wrong dependencies
 
-## Related Commands
-- `/workflow:plan` - Standard (non-TDD) planning
-- `/workflow:execute` - Execute TDD tasks
-- `/workflow:tdd-verify` - Verify TDD compliance
-- `/workflow:status` - View progress
 ## TDD Workflow Enhancements
 
 ### Overview
@@ -231,7 +289,7 @@ IMPL (Green phase) tasks now include automatic test-fix cycle for resilient impl
 ```
 1. Write minimal implementation code
 2. Execute test suite
-3. IF tests pass → Complete task ✅
+3. IF tests pass → Complete task
 4. IF tests fail → Enter fix cycle:
    a. Gemini diagnoses with bug-fix template
    b. Apply fix (manual or Codex)
@@ -241,10 +299,10 @@ IMPL (Green phase) tasks now include automatic test-fix cycle for resilient impl
 ```
 
 **Benefits**:
-- ✅ Faster feedback within Green phase
-- ✅ Autonomous recovery from implementation errors
-- ✅ Systematic debugging with Gemini
-- ✅ Safe rollback prevents broken state
+- Faster feedback within Green phase
+- Autonomous recovery from implementation errors
+- Systematic debugging with Gemini
+- Safe rollback prevents broken state
 
 #### 3. Agent-Driven Planning
 **From plan --agent workflow**
@@ -272,7 +330,7 @@ Supports action-planning-agent for more autonomous TDD planning with:
 
 ### Migration Notes
 
-**Backward Compatibility**: ✅ Fully compatible
+**Backward Compatibility**: Fully compatible
 - Existing TDD workflows continue to work
 - New features are additive, not breaking
 - Phase 3 can be skipped if test-context-gather not available
@@ -304,3 +362,23 @@ Supports action-planning-agent for more autonomous TDD planning with:
 - `meta.max_iterations`: Fix attempts (default: 3)
 - `meta.use_codex`: Auto-fix mode (default: false)
 
+## Related Commands
+
+**Prerequisite Commands**:
+- None - TDD planning is self-contained (can optionally run brainstorm commands before)
+
+**Called by This Command** (6 phases):
+- `/workflow:session:start` - Phase 1: Create or discover TDD workflow session
+- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
+- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
+- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
+- `/compact` - Phase 4: Memory optimization (if context approaching limits)
+- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD task chains with Red-Green-Refactor cycles
+- `/workflow:tools:task-generate-tdd --agent` - Phase 5: Generate TDD tasks with agent-driven approach (when `--agent` flag used)
+
+**Follow-up Commands**:
+- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
+- `/workflow:status` - Review TDD task breakdown
+- `/workflow:execute` - Begin TDD implementation
+- `/workflow:tdd-verify` - Post-execution: Verify TDD compliance and generate quality report
+

.claude/commands/workflow/tdd-verify.md

@@ -1,9 +1,9 @@
 ---
 name: tdd-verify
-description: Verify TDD workflow compliance and generate quality report
+description: Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis
 
 argument-hint: "[optional: WFS-session-id]"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
 ---
 
 # TDD Verification Command (/workflow:tdd-verify)
@@ -94,7 +94,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 **Gemini analysis for comprehensive TDD compliance report**
 
 ```bash
-cd project-root && ~/.claude/scripts/gemini-wrapper -p "
+cd project-root && gemini -p "
 PURPOSE: Generate TDD compliance report
 TASK: Analyze TDD workflow execution and generate quality report
 CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
@@ -118,14 +118,14 @@ RULES: Focus on TDD best practices and workflow adherence. Be specific about vio
 TDD Verification Report - Session: {sessionId}
 
 ## Chain Validation
-✅ Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
-✅ Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
-⚠️  Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
+[COMPLETE] Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
+[COMPLETE] Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
+[INCOMPLETE] Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
 
 ## Test Execution
-✅ All TEST tasks produced failing tests
-✅ All IMPL tasks made tests pass
-✅ All REFACTOR tasks maintained green tests
+All TEST tasks produced failing tests
+All IMPL tasks made tests pass
+All REFACTOR tasks maintained green tests
 
 ## Coverage Metrics
 Line Coverage: {percentage}%
@@ -237,7 +237,7 @@ Final Score: Max(0, Base Score - Deductions)
 
 ### Command Chain
 - **Called After**: `/workflow:execute` (when TDD tasks completed)
-- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini wrapper
+- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini CLI
 - **Related**: `/workflow:tdd-plan`, `/workflow:status`
 
 ### Basic Usage
@@ -271,20 +271,20 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 ## Chain Analysis
 
 ### Feature 1: {Feature Name}
-**Status**: ✅ Complete
+**Status**: Complete
 **Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
 
-- ✅ **Red Phase**: Test created and failed with clear message
-- ✅ **Green Phase**: Minimal implementation made test pass
-- ✅ **Refactor Phase**: Code improved, tests remained green
+- **Red Phase**: Test created and failed with clear message
+- **Green Phase**: Minimal implementation made test pass
+- **Refactor Phase**: Code improved, tests remained green
 
 ### Feature 2: {Feature Name}
-**Status**: ⚠️ Incomplete
+**Status**: Incomplete
 **Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1)
 
-- ✅ **Red Phase**: Test created and failed
-- ⚠️ **Green Phase**: Implementation seems over-engineered
-- ❌ **Refactor Phase**: Missing
+- **Red Phase**: Test created and failed
+- **Green Phase**: Implementation seems over-engineered
+- **Refactor Phase**: Missing
 
 **Issues**:
 - REFACTOR-2.1 task not completed
@@ -306,16 +306,16 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 ## TDD Cycle Validation
 
 ### Red Phase (Write Failing Test)
-- ✅ {N}/{total} features had failing tests initially
-- ⚠️ Feature 3: No evidence of initial test failure
+- {N}/{total} features had failing tests initially
+- Feature 3: No evidence of initial test failure
 
 ### Green Phase (Make Test Pass)
-- ✅ {N}/{total} implementations made tests pass
-- ✅ All implementations minimal and focused
+- {N}/{total} implementations made tests pass
+- All implementations minimal and focused
 
 ### Refactor Phase (Improve Quality)
-- ⚠️ {N}/{total} features completed refactoring
-- ❌ Feature 2, 4: Refactoring step skipped
+- {N}/{total} features completed refactoring
+- Feature 2, 4: Refactoring step skipped
 
 ## Best Practices Assessment
 
@@ -351,8 +351,3 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 {Summary of compliance status and next steps}
 ```
 
-## Related Commands
-- `/workflow:tdd-plan` - Creates TDD workflow
-- `/workflow:execute` - Executes TDD tasks
-- `/workflow:tools:tdd-coverage-analysis` - Analyzes test coverage
-- `/workflow:status` - Views workflow progress

.claude/commands/workflow/test-cycle-execute.md

@@ -1,6 +1,6 @@
 ---
 name: test-cycle-execute
-description: Execute test-fix workflow with dynamic task generation and iterative fix cycles
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached
 argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ---
@@ -10,6 +10,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ## Overview
 Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
 
+**CRITICAL - Orchestrator Boundary**:
+- This command is the **ONLY place** where test failures are handled
+- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
+- Agents (@test-fix-agent) only execute single tasks and return results
+- **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
+
 **Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
 
 ## Core Philosophy
@@ -53,21 +59,23 @@ Orchestrates dynamic test-fix workflow execution through iterative cycles of tes
 
 ## Responsibility Matrix
 
-**Clear division of labor between orchestrator and agents:**
+**CRITICAL - Clear division of labor between orchestrator and agents:**
 
 | Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
 |----------------|----------------------------|---------------------------|
-| Manage iteration loop | ✅ Controls loop flow | ❌ Executes single task |
-| Run CLI analysis (Gemini/Qwen) | ✅ Runs between agent tasks | ❌ Not involved |
-| Generate IMPL-fix-N.json | ✅ Creates task files | ❌ Not involved |
-| Run tests | ❌ Delegates to agent | ✅ Executes test command |
-| Apply fixes | ❌ Delegates to agent | ✅ Modifies code |
-| Detect test failures | ✅ Analyzes agent output | ✅ Reports results |
-| Add tasks to queue | ✅ Manages queue | ❌ Not involved |
-| Update iteration state | ✅ Maintains state files | ✅ Updates task status |
+| Manage iteration loop | Yes - Controls loop flow | No - Executes single task |
+| Run CLI analysis (Gemini/Qwen) | Yes - Runs between agent tasks | No - Not involved |
+| Generate IMPL-fix-N.json | Yes - Creates task files | No - Not involved |
+| Run tests | No - Delegates to agent | Yes - Executes test command |
+| Apply fixes | No - Delegates to agent | Yes - Modifies code |
+| Detect test failures | Yes - Analyzes results and decides next action | Yes - Executes tests and reports outcomes |
+| Add tasks to queue | Yes - Manages queue | No - Not involved |
+| Update iteration state | Yes - Maintains overall iteration state | Yes - Updates individual task status only |
 
 **Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
 
+**ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
+
 ## Execution Lifecycle
 
 ### Phase 1: Discovery & Initialization
@@ -217,20 +225,22 @@ Iteration N (managed by test-cycle-execute orchestrator):
 **Orchestrator executes CLI analysis between agent tasks:**
 
 #### When Test Failures Occur
-1. **[Orchestrator]** Detects failures from agent output
+1. **[Orchestrator]** Detects failures from agent test execution output
 2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
-3. **[Orchestrator]** Runs Gemini/Qwen wrapper with failure context
-4. **[CLI Tool]** Analyzes failures and generates fix strategy
+3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
+4. **[Orchestrator]** Interprets CLI tool output to extract fix strategy
 5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
 6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
 
+**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
+
 #### CLI Analysis Command (executed by orchestrator)
 ```bash
-cd {project_root} && ~/.claude/scripts/gemini-wrapper -p "
+cd {project_root} && gemini -p "
 PURPOSE: Analyze test failures and generate fix strategy
 TASK: Review test failures and identify root causes
 MODE: analysis
-CONTEXT: @{test files, implementation files}
+CONTEXT: @test files @ implementation files
 
 [Test failure context and requirements...]
 
@@ -516,15 +526,16 @@ Task(subagent_type="{meta.agent}",
      ### For test-fix (IMPL-002):
      - Run test suite: {test_command}
      - Collect results to .process/test-results.json
-     - If failures: Save context, return to orchestrator
+     - Report results to orchestrator (do NOT analyze failures)
+     - Orchestrator will handle failure detection and iteration decisions
      - If success: Mark complete
 
      ### For test-fix-iteration (IMPL-fix-N):
      - Load fix strategy from context.fix_strategy (CONTENT, not path)
      - Apply surgical fixes to identified files
-     - Run tests to verify
-     - If still failures: Save context with new failure data
-     - Update iteration state
+     - Return results to orchestrator
+     - Do NOT run tests independently - orchestrator manages all test execution
+     - Do NOT handle failures - orchestrator analyzes and decides next iteration
 
      ## STEP 4: Implementation Context (From JSON)
      **Requirements**: {context.requirements}
@@ -642,10 +653,3 @@ mv temp.json iteration-state.json
 5. **Verify No Regressions**: Check all tests pass, not just previously failing ones
 6. **Preserve Context**: All iteration artifacts saved for debugging
 
-## Related Commands
-
-- `/workflow:test-fix-gen` - Planning phase (creates initial tasks)
-- `/workflow:execute` - Standard workflow execution (no dynamic iteration)
-- `/workflow:status` - Check progress and iteration state
-- `/workflow:session:complete` - Mark session complete (auto-called on success)
-- `/task:create` - Manually create additional tasks if needed

.claude/commands/workflow/test-fix-gen.md

@@ -1,6 +1,6 @@
 ---
 name: test-fix-gen
-description: Create independent test-fix workflow session from existing implementation (session or prompt-based)
+description: Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning
 argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -13,7 +13,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 This command creates an independent test-fix workflow session for existing code. It orchestrates a 5-phase process to analyze implementation, generate test requirements, and create executable test generation and fix tasks.
 
-**⚠️ Command Scope**: Prepares test workflow artifacts only. Task execution requires separate commands (`/workflow:test-cycle-execute` or `/workflow:execute`).
+**CRITICAL - Command Scope**:
+- **This command ONLY generates task JSON files** (IMPL-001.json, IMPL-002.json)
+- **Does NOT execute tests or apply fixes** - all execution happens in separate orchestrator
+- **Must call `/workflow:test-cycle-execute`** after this command to actually run tests and fixes
+- **Test failure handling happens in test-cycle-execute**, not here
 
 ### Dual-Mode Support
 
@@ -44,12 +48,15 @@ fi
 
 ### Coordinator Role
 
-This command is a **pure orchestrator**:
+This command is a **pure planning coordinator**:
 - Does NOT analyze code directly
 - Does NOT generate tests or documentation
-- ONLY coordinates slash commands in sequence
+- Does NOT execute tests or apply fixes
+- Does NOT handle test failures or iterations
+- ONLY coordinates slash commands to generate task JSON files
 - Parses outputs to pass data between phases
 - Creates independent test workflow session
+- **All execution delegated to `/workflow:test-cycle-execute`**
 
 ---
 
@@ -267,14 +274,20 @@ Review artifacts:
 - Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 
-Next Steps:
-- Review IMPL_PLAN.md
-- Execute: /workflow:test-cycle-execute [testSessionId]
+CRITICAL - Next Steps:
+1. Review IMPL_PLAN.md
+2. **MUST execute: /workflow:test-cycle-execute**
+   - This command only generated task JSON files
+   - Test execution and fix iterations happen in test-cycle-execute
+   - Do NOT attempt to run tests or fixes in main workflow
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
-**Note**: Command completes here. Task execution requires separate workflow commands.
+**BOUNDARY NOTE**:
+- Command completes here - only task JSON files generated
+- All test execution, failure detection, CLI analysis, fix generation happens in `/workflow:test-cycle-execute`
+- This command does NOT handle test failures or apply fixes
 
 ---
 
@@ -329,7 +342,9 @@ Generates minimum 2 tasks (expandable for complex projects):
 
 **Agent**: `@test-fix-agent`
 
-**Purpose**: Execute tests and apply iterative fixes (max 5 iterations)
+**Purpose**: Execute initial tests and trigger orchestrator-managed fix cycles
+
+**Note**: This task executes tests and reports results. The test-cycle-execute orchestrator manages all fix iterations, CLI analysis, and fix task generation.
 
 **Task Configuration**:
 - Task ID: `IMPL-002`
@@ -340,11 +355,12 @@ Generates minimum 2 tasks (expandable for complex projects):
 - `context.requirements`: Execute and fix tests
 
 **Test-Fix Cycle Specification**:
-- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
-- **Tools Configuration**:
+**Note**: This specification describes what test-cycle-execute orchestrator will do. The agent only executes single tasks.
+- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → manual_fix (or codex) → retest
+- **Tools Configuration** (orchestrator-controlled):
   - Gemini for analysis with bug-fix template → surgical fix suggestions
   - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
-- **Exit Conditions**:
+- **Exit Conditions** (orchestrator-enforced):
   - Success: All tests pass
   - Failure: Max iterations reached (5)
 
@@ -446,25 +462,23 @@ WFS-test-[session]/
    - Use `--use-codex` for autonomous fix application
    - Use `--cli-execute` for enhanced generation capabilities
 
-### Related Commands
+## Related Commands
 
-**Planning Phase**:
-- `/workflow:plan` - Create implementation workflow
-- `/workflow:session:start` - Initialize workflow session
+**Prerequisite Commands**:
+- `/workflow:plan` or `/workflow:execute` - Complete implementation session (for Session Mode)
+- None for Prompt Mode (ad-hoc test generation)
 
-**Context Gathering**:
-- `/workflow:tools:test-context-gather` - Session-based context (Phase 2 for session mode)
-- `/workflow:tools:context-gather` - Prompt-based context (Phase 2 for prompt mode)
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create independent test workflow session
+- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
+- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
+- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs with fix cycle specification
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
 
-**Analysis & Task Generation**:
-- `/workflow:tools:test-concept-enhanced` - Gemini test analysis (Phase 3)
-- `/workflow:tools:test-task-generate` - Generate test tasks (Phase 4)
+**Follow-up Commands**:
+- `/workflow:status` - Review generated test tasks
+- `/workflow:test-cycle-execute` - Execute test generation and iterative fix cycles
+- `/workflow:execute` - Standard execution of generated test tasks
 
-**Execution**:
-- `/workflow:test-cycle-execute` - Execute test-fix workflow (recommended for IMPL-002)
-- `/workflow:execute` - Execute standard workflow tasks
-- `/workflow:status` - Check task progress
-
-**Review & Management**:
-- `/workflow:review` - Review workflow results
-- `/workflow:session:complete` - Mark session complete

.claude/commands/workflow/test-gen.md

@@ -1,6 +1,6 @@
 ---
 name: test-gen
-description: Create independent test-fix workflow session by analyzing completed implementation
+description: Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks
 argument-hint: "[--use-codex] [--cli-execute] source-session-id"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -24,7 +24,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
 4. Generate test task from analysis → Return summary
 
-**⚠️ Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
+**Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
 
 ## Core Rules
 
@@ -36,7 +36,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 6. **Track Progress**: Update TodoWrite after every phase completion
 7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
 8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
-9. **⚠️ Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
+9. **Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
 
 ## 5-Phase Execution
 
@@ -177,13 +177,13 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ---
 
-### Phase 5: Return Summary (⚠️ Command Ends Here)
+### Phase 5: Return Summary (Command Ends Here)
 
-**⚠️ Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
+**Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
 
 **Return to User**:
 ```
-✅ Test workflow preparation complete!
+Test workflow preparation complete!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
@@ -198,17 +198,17 @@ Test Framework: [detected framework]
 Test Files to Generate: [count]
 Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
-📋 Review Generated Artifacts:
+Review Generated Artifacts:
 - Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 - Analysis: .workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
 
-⚠️ Ready for execution. Use appropriate workflow commands to proceed.
+Ready for execution. Use appropriate workflow commands to proceed.
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
-**⚠️ Command Boundary**: After this phase, the command terminates and returns to user prompt.
+**Command Boundary**: After this phase, the command terminates and returns to user prompt.
 
 ---
 
@@ -244,7 +244,7 @@ Update status to `in_progress` when starting each phase, mark `completed` when d
 │   ↓                                                     │
 │ Phase 5: Return summary                                │
 └─────────────────────────────────────────────────────────┘
-         ⚠️ COMMAND ENDS - Control returns to user
+         COMMAND ENDS - Control returns to user
 
 Artifacts Created:
 ├── .workflow/WFS-test-[session]/
@@ -330,8 +330,18 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
 
 ## Related Commands
 
-- `/workflow:tools:test-context-gather` - Phase 2 (coverage analysis)
-- `/workflow:tools:test-concept-enhanced` - Phase 3 (Gemini test analysis)
-- `/workflow:tools:test-task-generate` - Phase 4 (task generation)
-- `/workflow:execute` - Execute workflow
-- `/workflow:status` - Check progress
+**Prerequisite Commands**:
+- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
+
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create independent test workflow session
+- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
+- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test generation and execution task JSONs
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
+
+**Follow-up Commands**:
+- `/workflow:status` - Review generated test tasks
+- `/workflow:test-cycle-execute` - Execute test generation and fix cycles
+- `/workflow:execute` - Execute generated test tasks

.claude/commands/workflow/tools/concept-enhanced.md

@@ -1,229 +0,0 @@
----
-name: concept-enhanced
-description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation
-argument-hint: "--session WFS-session-id --context path/to/context-package.json"
-examples:
-  - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
-  - /workflow:tools:concept-enhanced --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
----
-
-# Enhanced Analysis Command (/workflow:tools:concept-enhanced)
-
-## Overview
-Advanced solution design and feasibility analysis engine with parallel CLI execution. Processes standardized context packages to produce ANALYSIS_RESULTS.md focused on solution improvements, key design decisions, and critical insights.
-
-**Scope**: Solution-focused technical analysis only. Does NOT generate task breakdowns or implementation plans.
-
-**Usage**: Standalone command or integrated into `/workflow:plan`. Accepts context packages and orchestrates Gemini/Codex for comprehensive analysis.
-
-## Core Philosophy & Responsibilities
-- **Agent Coordination**: Delegate analysis execution to specialized agent (cli-execution-agent)
-- **Solution-Focused Analysis**: Emphasize design decisions, architectural rationale, and critical insights (exclude task planning)
-- **Context-Driven**: Parse and validate context-package.json for precise analysis
-- **Agent-Driven Tool Selection**: Agent autonomously selects Gemini/Codex based on task complexity
-- **Solution Design**: Evaluate architecture, identify key design decisions with rationale
-- **Feasibility Assessment**: Analyze technical complexity, risks, implementation readiness
-- **Optimization Recommendations**: Performance, security, and code quality improvements
-- **Output Validation**: Verify ANALYSIS_RESULTS.md generation and quality
-- **Single Output**: Generate only ANALYSIS_RESULTS.md with technical analysis
-
-## Analysis Strategy Selection
-
-**Agent-Driven Strategy**: cli-execution-agent autonomously determines tool selection based on:
-- **Task Complexity**: Number of modules, integration scope, technical depth
-- **Tech Stack**: Frontend (Gemini-focused), Backend (Codex-preferred), Fullstack (hybrid)
-- **Analysis Focus**: Architecture design (Gemini), Feasibility validation (Codex), Performance optimization (both)
-
-**Complexity Tiers** (Agent decides internally):
-- **Simple (≤3 modules)**: Gemini-only analysis
-- **Medium (4-6 modules)**: Gemini comprehensive analysis
-- **Complex (>6 modules)**: Gemini + Codex parallel execution
-
-## Execution Lifecycle
-
-### Phase 1: Validation & Preparation
-1. **Session Validation**: Verify `.workflow/{session_id}/` exists, load `workflow-session.json`
-2. **Context Package Validation**: Verify path, validate JSON format and structure
-3. **Task Analysis**: Extract keywords, identify domain/complexity, determine scope
-4. **Agent Preparation**: Prepare agent task prompt with complete analysis requirements
-
-### Phase 2: Agent-Delegated Analysis
-
-**Agent Invocation**:
-```javascript
-Task(
-  subagent_type="cli-execution-agent",
-  description="Enhanced solution design and feasibility analysis",
-  prompt=`
-## Execution Context
-
-**Session ID**: {session_id}
-**Mode**: Enhanced Analysis with CLI Tool Orchestration
-
-## Input Context
-
-**Context Package**: {context_path}
-**Session State**: .workflow/{session_id}/workflow-session.json
-**Project Standards**: CLAUDE.md
-
-## Analysis Task
-
-### Analysis Templates (Use these to guide CLI tool execution)
-- **Document Structure**: ~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt
-- **Gemini Analysis**: ~/.claude/workflows/cli-templates/prompts/workflow/gemini-solution-design.txt
-- **Codex Validation**: ~/.claude/workflows/cli-templates/prompts/workflow/codex-feasibility-validation.txt
-
-### Execution Strategy
-1. **Load Context**: Read context-package.json to determine task complexity (module count, integration scope)
-2. **Gemini Analysis** (ALL tasks): Execute using gemini-solution-design.txt template
-   - Output: .workflow/{session_id}/.process/gemini-solution-design.md
-3. **Codex Validation** (COMPLEX tasks >6 modules only): Execute using codex-feasibility-validation.txt template
-   - Output: .workflow/{session_id}/.process/codex-feasibility-validation.md
-4. **Synthesize Results**: Combine outputs into ANALYSIS_RESULTS.md following analysis-results-structure.txt
-
-### Output Requirements
-
-**Intermediate Outputs**:
-- Gemini: \`.workflow/{session_id}/.process/gemini-solution-design.md\` (always required)
-- Codex: \`.workflow/{session_id}/.process/codex-feasibility-validation.md\` (complex tasks only)
-
-**Final Output**:
-- \`.workflow/{session_id}/.process/ANALYSIS_RESULTS.md\` (synthesized, required)
-
-**Required Sections** (7 sections per analysis-results-structure.txt):
-1. Executive Summary
-2. Current State Analysis
-3. Proposed Solution Design
-4. Implementation Strategy
-5. Solution Optimization
-6. Critical Success Factors
-7. Reference Information
-
-### Synthesis Rules
-- Follow 7-section structure from analysis-results-structure.txt
-- Integrate Gemini insights as primary content
-- Incorporate Codex validation findings (if executed)
-- Resolve conflicts between tools with clear rationale
-- Generate confidence scores (1-5 scale) for all assessment dimensions
-- Provide final recommendation: PROCEED | PROCEED_WITH_MODIFICATIONS | RECONSIDER | REJECT
-
-## Output
-Generate final ANALYSIS_RESULTS.md and report completion status:
-- Gemini analysis: [completed/failed]
-- Codex validation: [completed/skipped/failed]
-- Synthesis: [completed/failed]
-- Final output: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
-`
-)
-```
-
-**Agent Execution Flow** (Internal to cli-execution-agent):
-1. Parse session ID and context path, load context-package.json
-2. Analyze task complexity (module count, integration scope)
-3. Discover additional context via MCP code-index
-4. Execute Gemini analysis (all tasks) with template-guided prompt
-5. Execute Codex validation (complex tasks >6 modules) with template-guided prompt
-6. Synthesize Gemini + Codex outputs into ANALYSIS_RESULTS.md
-7. Verify output file exists at correct path
-8. Return execution log path
-
-**Command Execution**: Launch agent via Task tool, wait for completion
-
-### Phase 3: Output Validation
-1. **File Verification**: Confirm `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md` exists
-2. **Content Validation**: Verify required sections present (Executive Summary, Solution Design, etc.)
-3. **Quality Check**: Ensure design rationale, feasibility assessment, confidence scores included
-4. **Agent Log**: Retrieve agent execution log from `.workflow/{session_id}/.chat/`
-5. **Success Criteria**: File exists, contains all required sections, meets quality standards
-
-## Analysis Results Format
-
-**Template Reference**: `~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt`
-
-Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning).
-
-### Required Structure (7 Sections)
-
-1. **Executive Summary**: Analysis focus, tools used, overall assessment (X/5), recommendation status
-2. **Current State Analysis**: Architecture overview, compatibility/dependencies, critical findings
-3. **Proposed Solution Design**: Core principles, system design, key decisions with rationale, technical specs
-4. **Implementation Strategy**: Development approach, code modification targets, feasibility assessment, risk mitigation
-5. **Solution Optimization**: Performance, security, code quality recommendations
-6. **Critical Success Factors**: Technical requirements, quality metrics, success validation
-7. **Reference Information**: Tool analysis summary, context & resources
-
-### Key Requirements
-
-**Code Modification Targets**:
-- Existing files: `file:function:lines` (e.g., `src/auth/login.ts:validateUser:45-52`)
-- New files: `file` only (e.g., `src/auth/PasswordReset.ts`)
-- Unknown lines: `file:function:*`
-
-**Key Design Decisions** (minimum 2):
-- Decision statement
-- Rationale (why this approach)
-- Alternatives considered (tradeoffs)
-- Impact (implications on architecture)
-
-**Assessment Scores** (1-5 scale):
-- Conceptual Integrity, Architectural Soundness, Technical Feasibility, Implementation Readiness
-- Overall Confidence score
-- Final Recommendation: PROCEED | PROCEED_WITH_MODIFICATIONS | RECONSIDER | REJECT
-
-### Content Focus
-- ✅ Solution improvements and architectural decisions
-- ✅ Design rationale, alternatives, and tradeoffs
-- ✅ Risk assessment with mitigation strategies
-- ✅ Optimization opportunities (performance, security, quality)
-- ❌ Task lists or implementation steps
-- ❌ Code examples or snippets
-- ❌ Project management timelines
-
-## Execution Management
-
-### Error Handling & Recovery
-1. **Pre-execution**: Verify session/context package exists and is valid
-2. **Agent Monitoring**: Track agent execution status via Task tool
-3. **Validation**: Check ANALYSIS_RESULTS.md generation on completion
-4. **Error Recovery**:
-   - Agent execution failure → report error, check agent logs
-   - Missing output file → retry agent execution once
-   - Incomplete output → use agent logs to diagnose issue
-5. **Graceful Degradation**: If agent fails, report specific error and suggest manual analysis
-
-### Agent Delegation Benefits
-- **Autonomous Tool Selection**: Agent decides Gemini/Codex based on complexity
-- **Context Discovery**: Agent discovers additional relevant files via MCP
-- **Prompt Enhancement**: Agent optimizes prompts with discovered patterns
-- **Error Handling**: Agent manages CLI tool failures internally
-- **Log Tracking**: Agent execution logs saved to `.workflow/{session_id}/.chat/`
-
-## Integration & Success Criteria
-
-### Input/Output Interface
-**Input**:
-- `--session` (required): Session ID (e.g., WFS-auth)
-- `--context` (required): Context package path
-
-**Output**:
-- Single file: `ANALYSIS_RESULTS.md` at `.workflow/{session_id}/.process/`
-- No supplementary files (JSON, roadmap, templates)
-
-### Quality & Success Validation
-**Quality Checks**: Completeness, consistency, feasibility validation
-
-**Success Criteria**:
-- ✅ Solution-focused analysis (design decisions, critical insights, NO task planning)
-- ✅ Single output file only (ANALYSIS_RESULTS.md)
-- ✅ Design decision depth with rationale/alternatives/tradeoffs
-- ✅ Feasibility assessment (complexity, risks, readiness)
-- ✅ Optimization strategies (performance, security, quality)
-- ✅ Agent-driven tool selection (autonomous Gemini/Codex execution)
-- ✅ Robust error handling (validation, retry, graceful degradation)
-- ✅ Confidence scoring with clear recommendation status
-- ✅ Agent execution log saved to session chat directory
-
-## Related Commands
-- `/context:gather` - Generate context packages required by this command
-- `/workflow:plan` - Call this command for analysis
-- `/task:create` - Create specific tasks based on analysis results

.claude/commands/workflow/tools/conflict-resolution.md

@@ -0,0 +1,472 @@
+---
+name: conflict-resolution
+description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
+argument-hint: "--session WFS-session-id --context path/to/context-package.json"
+examples:
+  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
+---
+
+# Conflict Resolution Command
+
+## Purpose
+Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
+
+**Scope**: Detection and strategy generation only - NO code modification or task creation.
+
+**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`.
+
+## Core Responsibilities
+
+| Responsibility | Description |
+|---------------|-------------|
+| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
+| **Generate Strategies** | Provide 2-4 resolution options per conflict |
+| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
+| **User Decision** | Present options, never auto-apply |
+| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
+| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
+
+## Conflict Categories
+
+### 1. Architecture Conflicts
+- Incompatible design patterns
+- Module structure changes
+- Pattern migration requirements
+
+### 2. API Conflicts
+- Breaking contract changes
+- Signature modifications
+- Public interface impacts
+
+### 3. Data Model Conflicts
+- Schema modifications
+- Type breaking changes
+- Data migration needs
+
+### 4. Dependency Conflicts
+- Version incompatibilities
+- Setup conflicts
+- Breaking updates
+
+## Execution Flow
+
+### Phase 1: Validation
+```
+1. Verify session directory exists
+2. Load context-package.json
+3. Check conflict_risk (skip if none/low)
+4. Prepare agent task prompt
+```
+
+### Phase 2: CLI-Powered Analysis
+
+**Agent Delegation**:
+```javascript
+Task(subagent_type="cli-execution-agent", prompt=`
+  ## Context
+  - Session: {session_id}
+  - Risk: {conflict_risk}
+  - Files: {existing_files_list}
+
+  ## Analysis Steps
+
+  ### 1. Load Context
+  - Read existing files from conflict_detection.existing_files
+  - Load plan from .workflow/{session_id}/.process/context-package.json
+  - Extract role analyses and requirements
+
+  ### 2. Execute CLI Analysis
+
+  Primary (Gemini):
+  cd {project_root} && gemini -p "
+  PURPOSE: Detect conflicts between plan and codebase
+  TASK:
+  • Compare architectures
+  • Identify breaking API changes
+  • Detect data model incompatibilities
+  • Assess dependency conflicts
+  MODE: analysis
+  CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
+  EXPECTED: Conflict list with severity ratings
+  RULES: Focus on breaking changes and migration needs
+  "
+
+  Fallback: Qwen (same prompt) → Claude (manual analysis)
+
+  ### 3. Generate Strategies (2-4 per conflict)
+
+  Template per conflict:
+  - Severity: Critical/High/Medium
+  - Category: Architecture/API/Data/Dependency
+  - Affected files + impact
+  - Options with pros/cons, effort, risk
+  - Recommended strategy + rationale
+
+  ### 4. Return Structured Conflict Data
+
+  ⚠️ DO NOT generate CONFLICT_RESOLUTION.md file
+
+  Return JSON format for programmatic processing:
+
+  \`\`\`json
+  {
+    "conflicts": [
+      {
+        "id": "CON-001",
+        "brief": "一行中文冲突摘要",
+        "severity": "Critical|High|Medium",
+        "category": "Architecture|API|Data|Dependency",
+        "affected_files": [
+          ".workflow/{session}/.brainstorm/guidance-specification.md",
+          ".workflow/{session}/.brainstorm/system-architect/analysis.md"
+        ],
+        "description": "详细描述冲突 - 什么不兼容",
+        "impact": {
+          "scope": "影响的模块/组件",
+          "compatibility": "Yes|No|Partial",
+          "migration_required": true|false,
+          "estimated_effort": "人天估计"
+        },
+        "strategies": [
+          {
+            "name": "策略名称（中文）",
+            "approach": "实现方法简述",
+            "complexity": "Low|Medium|High",
+            "risk": "Low|Medium|High",
+            "effort": "时间估计",
+            "pros": ["优点1", "优点2"],
+            "cons": ["缺点1", "缺点2"],
+            "modifications": [
+              {
+                "file": ".workflow/{session}/.brainstorm/guidance-specification.md",
+                "section": "## 2. System Architect Decisions",
+                "change_type": "update",
+                "old_content": "原始内容片段（用于定位）",
+                "new_content": "修改后的内容",
+                "rationale": "为什么这样改"
+              },
+              {
+                "file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
+                "section": "## Design Decisions",
+                "change_type": "update",
+                "old_content": "原始内容片段",
+                "new_content": "修改后的内容",
+                "rationale": "修改理由"
+              }
+            ]
+          },
+          {
+            "name": "策略2名称",
+            "approach": "...",
+            "complexity": "Medium",
+            "risk": "Low",
+            "effort": "1-2天",
+            "pros": ["优点"],
+            "cons": ["缺点"],
+            "modifications": [...]
+          }
+        ],
+        "recommended": 0,
+        "modification_suggestions": [
+          "建议1：具体的修改方向或注意事项",
+          "建议2：可能需要考虑的边界情况",
+          "建议3：相关的最佳实践或模式"
+        ]
+      }
+    ],
+    "summary": {
+      "total": 2,
+      "critical": 1,
+      "high": 1,
+      "medium": 0
+    }
+  }
+  \`\`\`
+
+  ⚠️ CRITICAL Requirements for modifications field:
+  - old_content: Must be exact text from target file (20-100 chars for unique match)
+  - new_content: Complete replacement text (maintains formatting)
+  - change_type: "update" (replace), "add" (insert), "remove" (delete)
+  - file: Full path relative to project root
+  - section: Markdown heading for context (helps locate position)
+  - Minimum 2 strategies per conflict, max 4
+  - All text in Chinese for user-facing fields (brief, name, pros, cons)
+  - modification_suggestions: 2-5 actionable suggestions for custom handling (Chinese)
+
+  Quality Standards:
+  - Each strategy must have actionable modifications
+  - old_content must be precise enough for Edit tool matching
+  - new_content preserves markdown formatting and structure
+  - Recommended strategy (index) based on lowest complexity + risk
+  - modification_suggestions must be specific, actionable, and context-aware
+  - Each suggestion should address a specific aspect (compatibility, migration, testing, etc.)
+`)
+```
+
+**Agent Internal Flow**:
+```
+1. Load context package
+2. Check conflict_risk (exit if none/low)
+3. Read existing files + plan artifacts
+4. Run CLI analysis (Gemini→Qwen→Claude)
+5. Parse conflict findings
+6. Generate 2-4 strategies per conflict with modifications
+7. Return JSON to stdout (NOT file write)
+8. Return execution log path
+```
+
+### Phase 3: User Confirmation via Text Interaction
+
+**Command parses agent JSON output and presents conflicts to user via text**:
+
+```javascript
+// 1. Parse agent JSON output
+const conflictData = JSON.parse(agentOutput);
+const conflicts = conflictData.conflicts; // No 4-conflict limit
+
+// 2. Format conflicts as text output (max 10 per round)
+const batchSize = 10;
+const batches = chunkArray(conflicts, batchSize);
+
+for (const [batchIdx, batch] of batches.entries()) {
+  const totalBatches = batches.length;
+
+  // Output batch header
+  console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
+
+  // Output each conflict in batch
+  batch.forEach((conflict, idx) => {
+    const questionNum = batchIdx * batchSize + idx + 1;
+    console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
+
+    conflict.strategies.forEach((strategy, sIdx) => {
+      const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
+      console.log(`${optionLetter}) ${strategy.name}`);
+      console.log(`   说明：${strategy.approach}`);
+      console.log(`   复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
+    });
+
+    // Add custom option
+    const customLetter = String.fromCharCode(97 + conflict.strategies.length);
+    console.log(`${customLetter}) 自定义修改`);
+    console.log(`   说明：根据修改建议自行处理，不应用预设策略`);
+
+    // Show modification suggestions
+    if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
+      console.log(`   修改建议：`);
+      conflict.modification_suggestions.forEach(suggestion => {
+        console.log(`   - ${suggestion}`);
+      });
+    }
+    console.log();
+  });
+
+  console.log(`请回答 (格式: 1a 2b 3c...)：`);
+
+  // Wait for user input
+  const userInput = await readUserInput();
+
+  // Parse answers
+  const answers = parseUserAnswers(userInput, batch);
+}
+
+// 3. Build selected strategies (exclude custom selections)
+const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
+const customConflicts = answers.filter(a => a.isCustom).map(a => ({
+  id: a.conflict.id,
+  brief: a.conflict.brief,
+  suggestions: a.conflict.modification_suggestions
+}));
+```
+
+**Text Output Example**:
+```markdown
+===== 冲突解决 (第 1/1 轮) =====
+
+【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
+a) 渐进式迁移
+   说明：保留现有系统，逐步迁移到新方案
+   复杂度: Medium | 风险: Low | 工作量: 3-5天
+b) 完全重写
+   说明：废弃旧系统，从零实现新认证
+   复杂度: High | 风险: Medium | 工作量: 7-10天
+c) 自定义修改
+   说明：根据修改建议自行处理，不应用预设策略
+   修改建议：
+   - 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
+   - 检查JWT token格式和验证逻辑是否需要调整
+   - 确保用户会话管理与新架构保持一致
+
+【问题2 - Data】CON-002: 数据库 schema 冲突
+a) 添加迁移脚本
+   说明：创建数据库迁移脚本处理 schema 变更
+   复杂度: Low | 风险: Low | 工作量: 1-2天
+b) 自定义修改
+   说明：根据修改建议自行处理，不应用预设策略
+   修改建议：
+   - 检查现有表结构是否支持新增字段，避免破坏性变更
+   - 考虑使用数据库版本控制工具（如Flyway或Liquibase）
+   - 准备数据迁移和回滚策略
+
+请回答 (格式: 1a 2b)：
+```
+
+**User Input Examples**:
+- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
+- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
+- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
+
+### Phase 4: Apply Modifications
+
+```javascript
+// 1. Extract modifications from selected strategies
+const modifications = [];
+selectedStrategies.forEach(strategy => {
+  if (strategy !== "skip") {
+    modifications.push(...strategy.modifications);
+  }
+});
+
+// 2. Apply each modification using Edit tool
+modifications.forEach(mod => {
+  if (mod.change_type === "update") {
+    Edit({
+      file_path: mod.file,
+      old_string: mod.old_content,
+      new_string: mod.new_content
+    });
+  }
+  // Handle "add" and "remove" similarly
+});
+
+// 3. Update context-package.json
+const contextPackage = JSON.parse(Read(contextPath));
+contextPackage.conflict_detection.conflict_risk = "resolved";
+contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
+contextPackage.conflict_detection.resolved_at = new Date().toISOString();
+Write(contextPath, JSON.stringify(contextPackage, null, 2));
+
+// 4. Output custom conflict summary (if any)
+if (customConflicts.length > 0) {
+  console.log("\n===== 需要自定义处理的冲突 =====\n");
+  customConflicts.forEach(conflict => {
+    console.log(`【${conflict.id}】${conflict.brief}`);
+    console.log("修改建议：");
+    conflict.suggestions.forEach(suggestion => {
+      console.log(`  - ${suggestion}`);
+    });
+    console.log();
+  });
+}
+
+// 5. Return summary
+return {
+  resolved: modifications.length,
+  custom: customConflicts.length,
+  modified_files: [...new Set(modifications.map(m => m.file))],
+  custom_conflicts: customConflicts
+};
+```
+
+**Validation**:
+```
+✓ Agent returns valid JSON structure
+✓ Text output displays all conflicts (max 10 per round)
+✓ User selections captured correctly
+✓ Edit tool successfully applies modifications
+✓ guidance-specification.md updated
+✓ Role analyses (*.md) updated
+✓ context-package.json marked as resolved
+✓ Agent log saved to .workflow/{session_id}/.chat/
+```
+
+## Output Format: Agent JSON Response
+
+**Focus**: Structured conflict data with actionable modifications for programmatic processing.
+
+**Format**: JSON to stdout (NO file generation)
+
+**Structure**: Defined in Phase 2, Step 4 (agent prompt)
+
+### Key Requirements
+| Requirement | Details |
+|------------|---------|
+| **Conflict batching** | Max 10 conflicts per round (no total limit) |
+| **Strategy count** | 2-4 strategies per conflict |
+| **Modifications** | Each strategy includes file paths, old_content, new_content |
+| **User-facing text** | Chinese (brief, strategy names, pros/cons) |
+| **Technical fields** | English (severity, category, complexity, risk) |
+| **old_content precision** | 20-100 chars for unique Edit tool matching |
+| **File targets** | guidance-specification.md, role analyses (*.md) |
+
+## Error Handling
+
+### Recovery Strategy
+```
+1. Pre-check: Verify conflict_risk ≥ medium
+2. Monitor: Track agent via Task tool
+3. Validate: Parse agent JSON output
+4. Recover:
+   - Agent failure → check logs + report error
+   - Invalid JSON → retry once with Claude fallback
+   - CLI failure → fallback to Claude analysis
+   - Edit tool failure → report affected files + rollback option
+   - User cancels → mark as "unresolved", continue to task-generate
+5. Degrade: If all fail, generate minimal conflict report and skip modifications
+```
+
+### Rollback Handling
+```
+If Edit tool fails mid-application:
+1. Log all successfully applied modifications
+2. Output rollback option via text interaction
+3. If rollback selected: restore files from git or backups
+4. If continue: mark partial resolution in context-package.json
+```
+
+## Integration
+
+### Interface
+**Input**:
+- `--session` (required): WFS-{session-id}
+- `--context` (required): context-package.json path
+- Requires: `conflict_risk ≥ medium`
+
+**Output**:
+- Modified files:
+  - `.workflow/{session_id}/.brainstorm/guidance-specification.md`
+  - `.workflow/{session_id}/.brainstorm/{role}/analysis.md`
+  - `.workflow/{session_id}/.process/context-package.json` (conflict_risk → resolved)
+- NO report file generation
+
+**User Interaction**:
+- Text-based strategy selection (max 10 conflicts per round)
+- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
+
+### Success Criteria
+```
+✓ CLI analysis returns valid JSON structure
+✓ Conflicts presented in batches (max 10 per round)
+✓ Min 2 strategies per conflict with modifications
+✓ Each conflict includes 2-5 modification_suggestions
+✓ Text output displays all conflicts correctly with suggestions
+✓ User selections captured and processed
+✓ Edit tool applies modifications successfully
+✓ Custom conflicts displayed with suggestions for manual handling
+✓ guidance-specification.md updated with resolved conflicts
+✓ Role analyses (*.md) updated with resolved conflicts
+✓ context-package.json marked as "resolved"
+✓ No CONFLICT_RESOLUTION.md file generated
+✓ Modification summary includes custom conflict count
+✓ Agent log saved to .workflow/{session_id}/.chat/
+✓ Error handling robust (validate/retry/degrade)
+```
+
+## Related Commands
+| Command | Relationship |
+|---------|--------------|
+| `/workflow:tools:context-gather` | Generates input conflict_detection data |
+| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
+| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
+| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

.claude/commands/workflow/tools/context-gather.md

@@ -1,353 +1,282 @@
 ---
 name: gather
-description: Intelligently collect project context using general-purpose agent based on task description and package into standardized JSON
+description: Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
   - /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
   - /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
+allowed-tools: Task(*), Read(*), Glob(*)
 ---
 
 # Context Gather Command (/workflow:tools:context-gather)
 
 ## Overview
-Agent-driven intelligent context collector that gathers relevant information from project codebase, documentation, and dependencies based on task descriptions, generating standardized context packages.
+
+Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
+
+**Agent**: `context-search-agent` (`.claude/agents/context-search-agent.md`)
 
 ## Core Philosophy
-- **Agent-Driven**: Delegate execution to general-purpose agent for autonomous operation
-- **Two-Phase Flow**: Discovery (context loading) → Execution (context gathering and packaging)
-- **Memory-First**: Reuse loaded documents from conversation memory
-- **MCP-Enhanced**: Use MCP tools for advanced code analysis and file discovery
-- **Intelligent Collection**: Auto-identify relevant resources based on keyword analysis
-- **Comprehensive Coverage**: Collect code, documentation, configurations, and dependencies
-- **Standardized Output**: Generate unified format context-package.json
 
-## Execution Lifecycle
+- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
+- **Detection-First**: Check for existing context-package before executing
+- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
+- **Standardized Output**: Generate `.workflow/{session}/.process/context-package.json`
 
-### Phase 1: Discovery & Context Loading
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+## Execution Flow
+
+### Step 1: Context-Package Detection
+
+**Execute First** - Check if valid package already exists:
 
-**Agent Context Package**:
 ```javascript
-{
-  "session_id": "WFS-[session-id]",
-  "task_description": "[user provided task description]",
-  "session_metadata": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/workflow-session.json
-  },
-  "mcp_capabilities": {
-    // Agent will use these tools to discover project context
-    "code_index": true,
-    "exa_code": true,
-    "exa_web": true
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
+
+if (file_exists(contextPackagePath)) {
+  const existing = Read(contextPackagePath);
+
+  // Validate package belongs to current session
+  if (existing?.metadata?.session_id === session_id) {
+    console.log("✅ Valid context-package found for session:", session_id);
+    console.log("📊 Stats:", existing.statistics);
+    console.log("⚠️  Conflict Risk:", existing.conflict_detection.risk_level);
+    return existing; // Skip execution, return existing
+  } else {
+    console.warn("⚠️ Invalid session_id in existing package, re-generating...");
   }
 }
-
-// Agent will autonomously execute:
-// - Project structure analysis: bash(~/.claude/scripts/get_modules_by_depth.sh)
-// - Documentation loading: Read(CLAUDE.md), Read(README.md)
 ```
 
-**Discovery Actions**:
-1. **Load Session Context** (if not in memory)
-   ```javascript
-   if (!memory.has("workflow-session.json")) {
-     Read(.workflow/{session-id}/workflow-session.json)
-   }
-   ```
+### Step 2: Invoke Context-Search Agent
 
-### Phase 2: Agent Execution (Context Gathering & Packaging)
+**Only execute if Step 1 finds no valid package**
 
-**Agent Invocation**:
 ```javascript
 Task(
-  subagent_type="general-purpose",
-  description="Gather project context and generate context package",
+  subagent_type="context-search-agent",
+  description="Gather comprehensive context for plan",
   prompt=`
-## Execution Context
+You are executing as context-search-agent (.claude/agents/context-search-agent.md).
 
-**Session ID**: WFS-{session-id}
-**Task Description**: {task_description}
-**Mode**: Agent-Driven Context Gathering
+## Execution Mode
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
 
-## Phase 1: Discovery Results (Provided Context)
+## Session Information
+- **Session ID**: ${session_id}
+- **Task Description**: ${task_description}
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
 
-### Session Metadata
-{session_metadata_content}
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
 
-### MCP Capabilities
-- code-index: Available for file discovery and code search
-- exa-code: Available for external research
-- exa-web: Available for web search
+### Phase 1: Initialization & Pre-Analysis
+1. **Detection**: Check for existing context-package (early exit if valid)
+2. **Foundation**: Initialize code-index, get project structure, load docs
+3. **Analysis**: Extract keywords, determine scope, classify complexity
 
-## Phase 2: Context Gathering Task
+### Phase 2: Multi-Source Context Discovery
+Execute all 4 discovery tracks:
+- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
+- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
 
-### Core Responsibilities
-1. **Project Structure Analysis**: Execute get_modules_by_depth.sh for architecture overview
-2. **Documentation Loading**: Load CLAUDE.md, README.md and relevant documentation
-3. **Keyword Extraction**: Extract core keywords from task description
-4. **Smart File Discovery**: Use MCP code-index tools to locate relevant files
-5. **Code Structure Analysis**: Analyze project structure to identify relevant modules
-6. **Dependency Discovery**: Identify tech stack and dependency relationships
-7. **Context Packaging**: Generate standardized JSON context package
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. Synthesize 4-source data (archive > docs > code > web)
+3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+4. Perform conflict detection with risk assessment
+5. **Inject historical conflicts** from archive analysis into conflict_detection
+6. Generate and validate context-package.json
 
-### Execution Process
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
 
-#### Step 0: Foundation Setup (Execute First)
-1. **Project Structure Analysis**
-   Execute to get comprehensive architecture overview:
-   \`\`\`javascript
-   bash(~/.claude/scripts/get_modules_by_depth.sh)
-   \`\`\`
-
-2. **Load Project Documentation** (if not in memory)
-   Load core project documentation:
-   \`\`\`javascript
-   Read(CLAUDE.md)
-   Read(README.md)
-   // Load other relevant documentation based on session context
-   \`\`\`
-
-#### Step 1: Task Analysis
-1. **Keyword Extraction**
-   - Parse task description to extract core keywords
-   - Identify technical domain (auth, API, frontend, backend, etc.)
-   - Determine complexity level (simple, medium, complex)
-
-2. **Scope Determination**
-   - Define collection scope based on keywords
-   - Identify potentially involved modules and components
-   - Set file type filters
-
-#### Step 2: MCP-Enhanced File Discovery
-1. **Code File Location**
-   Use MCP code-index tools:
-   \`\`\`javascript
-   // Find files by pattern
-   mcp__code-index__find_files(pattern="*{keyword}*")
-
-   // Search code content
-   mcp__code-index__search_code_advanced(
-     pattern="{keyword_patterns}",
-     file_pattern="*.{ts,js,py,go,md}",
-     context_lines=3
-   )
-
-   // Get file summaries
-   mcp__code-index__get_file_summary(file_path="relevant/file.ts")
-   \`\`\`
-
-2. **Configuration Files Discovery**
-   Locate: package.json, requirements.txt, Cargo.toml, tsconfig.json, etc.
-
-3. **Test Files Location**
-   Find test files related to task keywords
-
-#### Step 3: Intelligent Filtering & Association
-1. **Relevance Scoring**
-   - Score based on keyword match degree
-   - Score based on file path relevance
-   - Score based on code content relevance
-
-2. **Dependency Analysis**
-   - Analyze import/require statements
-   - Identify inter-module dependencies
-   - Determine core and optional dependencies
-
-#### Step 4: Context Packaging
-Generate standardized context-package.json following the format below
-
-### Required Output
-
-**Output Location**: \`.workflow/{session-id}/.process/context-package.json\`
-
-**Output Format**:
-\`\`\`json
-{
-  "metadata": {
-    "task_description": "Implement user authentication system",
-    "timestamp": "2025-09-29T10:30:00Z",
-    "keywords": ["user", "authentication", "JWT", "login"],
-    "complexity": "medium",
-    "tech_stack": ["typescript", "node.js", "express"],
-    "session_id": "WFS-user-auth"
-  },
-  "assets": [
-    {
-      "type": "documentation",
-      "path": "CLAUDE.md",
-      "relevance": "Project development standards and conventions",
-      "priority": "high"
-    },
-    {
-      "type": "documentation",
-      "path": ".workflow/docs/architecture/security.md",
-      "relevance": "Security architecture design guidance",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/auth/AuthService.ts",
-      "relevance": "Existing authentication service implementation",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/models/User.ts",
-      "relevance": "User data model definition",
-      "priority": "medium"
-    },
-    {
-      "type": "config",
-      "path": "package.json",
-      "relevance": "Project dependencies and tech stack",
-      "priority": "medium"
-    },
-    {
-      "type": "test",
-      "path": "tests/auth/*.test.ts",
-      "relevance": "Authentication related test cases",
-      "priority": "medium"
-    }
-  ],
-  "tech_stack": {
-    "frameworks": ["express", "typescript"],
-    "libraries": ["jsonwebtoken", "bcrypt"],
-    "testing": ["jest", "supertest"]
-  },
-  "statistics": {
-    "total_files": 15,
-    "source_files": 8,
-    "docs_files": 4,
-    "config_files": 2,
-    "test_files": 1
-  }
-}
-\`\`\`
-
-### Quality Validation
-
-Before completion, verify:
-- [ ] context-package.json created in correct location
+## Quality Validation
+Before completion verify:
 - [ ] Valid JSON format with all required fields
-- [ ] Metadata includes task description, keywords, complexity
-- [ ] Assets array contains relevant files with priorities
-- [ ] Tech stack accurately identified
-- [ ] Statistics section provides file counts
 - [ ] File relevance accuracy >80%
-- [ ] No sensitive information exposed
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files ≤50 (prioritize high-relevance)
 
-### Performance Optimization
-
-**Large Project Optimization**:
-- File count limit: Maximum 50 files per type
-- Size filtering: Skip oversized files (>10MB)
-- Depth limit: Maximum search depth of 3 levels
-- Use MCP tools for efficient discovery
-
-**MCP Tools Integration**:
-Agent should use MCP code-index tools when available:
-\`\`\`javascript
-// Set project path
-mcp__code-index__set_project_path(path="{current_project_path}")
-
-// Refresh index
-mcp__code-index__refresh_index()
-
-// Find files by pattern
-mcp__code-index__find_files(pattern="*{keyword}*")
-
-// Search code content
-mcp__code-index__search_code_advanced(
-  pattern="{keyword_patterns}",
-  file_pattern="*.{ts,js,py,go,md}",
-  context_lines=3
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
 )
-\`\`\`
-
-**Fallback Strategy**:
-When MCP tools unavailable, agent should use traditional commands:
-- \`find\` for file discovery
-- \`rg\` or \`grep\` for content search
-- Bash commands from project structure analysis
-
-## Output
-
-Generate context-package.json and report completion:
-- Task description: {description}
-- Keywords extracted: {count}
-- Files collected: {total}
-  - Source files: {count}
-  - Documentation: {count}
-  - Configuration: {count}
-  - Tests: {count}
-- Tech stack identified: {frameworks/libraries}
-- Output location: .workflow/{session-id}/.process/context-package.json
-\`
-)
-\`\`\`
-
-## Command Integration
-
-### Usage
-```bash
-# Basic usage
-/workflow:tools:context-gather --session WFS-auth "Implement JWT authentication"
-
-# Called by /workflow:plan
-SlashCommand(command="/workflow:tools:context-gather --session WFS-[id] \\"[task description]\\"")
 ```
 
-### Agent Context Passing
+### Step 3: Output Verification
+
+After agent completes, verify output:
 
-**Memory-Aware Context Assembly**:
 ```javascript
-// Assemble minimal context package for agent
-// Agent will execute project structure analysis and documentation loading
-const agentContext = {
-  session_id: "WFS-[id]",
-  task_description: "[user provided task description]",
+// Verify file was created
+const outputPath = `.workflow/${session_id}/.process/context-package.json`;
+if (!file_exists(outputPath)) {
+  throw new Error("❌ Agent failed to generate context-package.json");
+}
+```
 
-  // Use memory if available, else load
-  session_metadata: memory.has("workflow-session.json")
-    ? memory.get("workflow-session.json")
-    : Read(.workflow/WFS-[id]/workflow-session.json),
+## Parameter Reference
 
-  // MCP capabilities - agent will use these tools
-  mcp_capabilities: {
-    code_index: true,
-    exa_code: true,
-    exa_web: true
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) |
+| `task_description` | string | ✅ | Detailed task description for context extraction |
+
+## Output Schema
+
+Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema.
+
+**Key Sections**:
+- **metadata**: Session info, keywords, complexity, tech stack
+- **project_context**: Architecture patterns, conventions, tech stack
+- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
+- **dependencies**: Internal and external dependency graphs
+- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
+- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
+
+## Historical Archive Analysis
+
+### Track 1: Query Archive Manifest
+
+The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
+
+**Step 1: Check for Archive Manifest**
+```bash
+# Check if archive manifest exists
+if [[ -f .workflow/.archives/manifest.json ]]; then
+  # Manifest available for querying
+fi
+```
+
+**Step 2: Extract Task Keywords**
+```javascript
+// From current task description, extract key entities and operations
+const keywords = extractKeywords(task_description);
+// Examples: ["User", "model", "authentication", "JWT", "reporting"]
+```
+
+**Step 3: Search Archive for Relevant Sessions**
+```javascript
+// Query manifest for sessions with matching tags or descriptions
+const relevantArchives = archives.filter(archive => {
+  return archive.tags.some(tag => keywords.includes(tag)) ||
+         keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
+});
+```
+
+**Step 4: Extract Watch Patterns**
+```javascript
+// For each relevant archive, check watch_patterns for applicability
+const historicalConflicts = [];
+
+relevantArchives.forEach(archive => {
+  archive.lessons.watch_patterns?.forEach(pattern => {
+    // Check if pattern trigger matches current task
+    if (isPatternRelevant(pattern.pattern, task_description)) {
+      historicalConflicts.push({
+        source_session: archive.session_id,
+        pattern: pattern.pattern,
+        action: pattern.action,
+        files_to_check: pattern.related_files,
+        archived_at: archive.archived_at
+      });
+    }
+  });
+});
+```
+
+**Step 5: Inject into Context Package**
+```json
+{
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": ["..."],
+    "affected_modules": ["..."],
+    "mitigation_strategy": "...",
+    "historical_conflicts": [
+      {
+        "source_session": "WFS-auth-feature",
+        "pattern": "When modifying User model",
+        "action": "Check reporting-service and auditing-service dependencies",
+        "files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
+        "archived_at": "2025-09-16T09:00:00Z"
+      }
+    ]
   }
 }
-
-// Note: Agent will execute these steps autonomously:
-// - bash(~/.claude/scripts/get_modules_by_depth.sh) for project structure
-// - Read(CLAUDE.md) and Read(README.md) for documentation
 ```
 
-## Session ID Integration
+### Risk Level Escalation
 
-### Session ID Usage
-- **Required Parameter**: `--session WFS-session-id`
-- **Session Context Loading**: Load existing session state and metadata
-- **Session Continuity**: Maintain context across workflow pipeline phases
+If `historical_conflicts` array is not empty, minimum risk level should be "medium":
 
-### Session Validation
 ```javascript
-// Validate session exists
-const sessionPath = `.workflow/${session_id}`;
-if (!fs.existsSync(sessionPath)) {
-  console.error(`❌ Session ${session_id} not found`);
-  process.exit(1);
+if (historicalConflicts.length > 0 && currentRisk === "low") {
+  conflict_detection.risk_level = "medium";
+  conflict_detection.risk_factors.push(
+    `${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
+  );
 }
 ```
 
-## Success Criteria
-- Valid context-package.json generated in correct location
-- Contains sufficient relevant information (>80% relevance)
-- Execution completes within reasonable time (<2 minutes)
-- All required fields present and properly formatted
-- Agent reports completion status with statistics
+### Archive Query Algorithm
 
+```markdown
+1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
+2. IF manifest exists:
+   a. Load manifest.json
+   b. Extract keywords from task_description (nouns, verbs, technical terms)
+   c. Filter archives where:
+      - ANY tag matches keywords (case-insensitive) OR
+      - description contains keywords (case-insensitive substring match)
+   d. For each relevant archive:
+      - Read lessons.watch_patterns array
+      - Check if pattern.pattern keywords overlap with task_description
+      - If relevant: Add to historical_conflicts array
+   e. IF historical_conflicts.length > 0:
+      - Set risk_level = max(current_risk, "medium")
+      - Add to risk_factors
+3. Continue to Track 2 (reference documentation)
+```
+
+## Usage Examples
+
+### Basic Usage
+```bash
+/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
+```
+## Success Criteria
+
+- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
+- ✅ Contains >80% relevant files based on task keywords
+- ✅ Execution completes within 2 minutes
+- ✅ All required schema fields present and valid
+- ✅ Conflict risk accurately assessed
+- ✅ Agent reports completion with statistics
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
+| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
+| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
+| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
+
+## Notes
+
+- **Detection-first**: Always check for existing package before invoking agent
+- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
+- **No redundancy**: This command is a thin orchestrator, all logic in agent
+- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call

.claude/commands/workflow/tools/task-generate-agent.md

@@ -1,6 +1,6 @@
 ---
 name: task-generate-agent
-description: Autonomous task generation using action-planning-agent with discovery and output phases
+description: Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning
 argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
@@ -19,6 +19,7 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 - **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
 - **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
 - **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
 
 ## Execution Lifecycle
 
@@ -37,17 +38,19 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/workflow-session.json
   },
-  "analysis_results": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
-  },
-  "artifacts_inventory": {
-    // If in memory: use cached list
-    // Else: Scan .workflow/{session-id}/.brainstorming/ directory
-    "synthesis_specification": "path or null",
-    "topic_framework": "path or null",
-    "role_analyses": ["paths"]
+  "brainstorm_artifacts": {
+    // Loaded from context-package.json → brainstorm_artifacts section
+    "role_analyses": [
+      {
+        "role": "system-architect",
+        "files": [{"path": "...", "type": "primary|supplementary"}]
+      }
+    ],
+    "guidance_specification": {"path": "...", "exists": true},
+    "synthesis_output": {"path": "...", "exists": true},
+    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
   },
+  "context_package_path": ".workflow/{session-id}/.process/context-package.json",
   "context_package": {
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/.process/context-package.json
@@ -68,31 +71,38 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
    }
    ```
 
-2. **Load Analysis Results** (if not in memory)
+2. **Load Context Package** (if not in memory)
    ```javascript
-   if (!memory.has("ANALYSIS_RESULTS.md")) {
-     Read(.workflow/{session-id}/.process/ANALYSIS_RESULTS.md)
+   if (!memory.has("context-package.json")) {
+     Read(.workflow/{session-id}/.process/context-package.json)
    }
    ```
 
-3. **Discover Artifacts** (if not in memory)
+3. **Extract & Load Role Analyses** (from context-package.json)
    ```javascript
-   if (!memory.has("artifacts_inventory")) {
-     bash(find .workflow/{session-id}/.brainstorming/ -name "*.md" -type f)
+   // Extract role analysis paths from context package
+   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
+     .flatMap(role => role.files.map(f => f.path));
+
+   // Load each role analysis file
+   roleAnalysisPaths.forEach(path => Read(path));
+   ```
+
+4. **Load Conflict Resolution** (from context-package.json, if exists)
+   ```javascript
+   if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
+     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
    }
    ```
 
-4. **MCP Code Analysis** (optional - enhance understanding)
-   ```javascript
-   // Find relevant files for task context
-   mcp__code-index__find_files(pattern="*auth*")
-   mcp__code-index__search_code_advanced(
-     pattern="authentication|oauth",
-     file_pattern="*.ts"
-   )
+5. **Code Analysis with Native Tools** (optional - enhance understanding)
+   ```bash
+   # Find relevant files for task context
+   find . -name "*auth*" -type f
+   rg "authentication|oauth" -g "*.ts"
    ```
 
-5. **MCP External Research** (optional - gather best practices)
+6. **MCP External Research** (optional - gather best practices)
    ```javascript
    // Get external examples for implementation
    mcp__exa__get_code_context_exa(
@@ -128,16 +138,24 @@ Task(
 ### Session Metadata
 {session_metadata_content}
 
-### Analysis Results
-{analysis_results_content}
+### Role Analyses (Enhanced by Synthesis)
+{role_analyses_content}
+- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
 
 ### Artifacts Inventory
-- **Synthesis Specification**: {synthesis_spec_path}
-- **Topic Framework**: {topic_framework_path}
+- **Guidance Specification**: {guidance_spec_path}
 - **Role Analyses**: {role_analyses_list}
 
 ### Context Package
 {context_package_summary}
+- Includes conflict_risk assessment
+
+### Conflict Resolution (Conditional)
+If conflict_risk was medium/high, modifications have been applied to:
+- **guidance-specification.md**: Design decisions updated to resolve conflicts
+- **Role analyses (*.md)**: Recommendations adjusted for compatibility
+- **context-package.json**: Marked as "resolved" with conflict IDs
+- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
 
 ### MCP Analysis Results (Optional)
 **Code Structure**: {mcp_code_index_results}
@@ -159,23 +177,49 @@ Task(
 - **Function-based**: Complete units (logic + UI + tests + config)
 - **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
 
+### Quantification Requirements (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
+
+**Core Rules**:
+1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
+2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
+3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
+4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
+5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
+
+**Standard Formats**:
+- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
+- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
+- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
+
+**Validation Checklist**:
+- [ ] Every requirement contains explicit count or enumerated list
+- [ ] Every acceptance criterion is measurable with verification command
+- [ ] Every modification_point specifies exact targets (files/functions/lines)
+- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
+- [ ] Each implementation step has its own acceptance criteria
+
 ### Required Outputs
 
 #### 1. Task JSON Files (.task/IMPL-*.json)
-**Location**: .workflow/{session-id}/.task/
-**Template**: Read from the template path provided above
 
-**Task JSON Template Loading**:
-\`\`\`
-Read({template_path})
-\`\`\`
+**Location**: `.workflow/{session-id}/.task/`
+**Template Path**: Provided by command (agent-mode or cli-mode template)
 
-**Important**:
-- Read the template from the path provided in context
-- Use the template structure exactly as written
-- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
-- Include MCP tool integration in pre_analysis steps
+**Key Responsibilities**:
+- Read template from provided path: `Read({template_path})`
+- Replace placeholder variables with session-specific paths
+- Include MCP tool integration in `pre_analysis` steps
 - Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
+- Apply quantification requirements to all task fields
+- Ensure all tasks follow template structure exactly
+
+**Template Selection** (Pre-selected by command):
+- **Agent Mode**: `~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt`
+- **CLI Mode**: `~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt`
+
+**Note**: Agent does NOT choose template - it's pre-selected based on `--cli-execute` flag and provided in context
 
 #### 2. IMPL_PLAN.md
 **Location**: .workflow/{session-id}/IMPL_PLAN.md
@@ -189,8 +233,9 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
 - Use the template above for IMPL_PLAN.md generation
 - Replace all {placeholder} variables with actual session-specific values
 - Populate CCW Workflow Context based on actual phase progression
-- Extract content from ANALYSIS_RESULTS.md and context-package.json
-- List all detected brainstorming artifacts with correct paths
+- Extract content from role analyses and context-package.json
+- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
+- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
 
 #### 3. TODO_LIST.md
 **Location**: .workflow/{session-id}/TODO_LIST.md
@@ -221,18 +266,31 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
 - Read template from the provided path: `Read({template_path})`
 - This template is already the correct one based on execution mode
 
-**Step 2: Extract and Decompose Tasks**
-- Parse ANALYSIS_RESULTS.md for task recommendations
+**Step 2: Extract and Decompose Tasks (WITH QUANTIFICATION)**
+- Parse role analysis.md files for requirements, design specs, and task recommendations
+- **CRITICAL: Apply Quantification Extraction Process**:
+  - Scan for counts: numbers + nouns (e.g., "5 files", "17 commands", "3 features")
+  - Build explicit lists for each deliverable (no "..." unless list >20 items)
+  - Flag vague language ("complete", "comprehensive", "reorganize") for replacement
+  - Extract verification methods for each deliverable
+- Review synthesis enhancements and clarifications in role analyses
+- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
 - Apply task merging rules (merge when possible, decompose only when necessary)
-- Map artifacts to tasks based on domain (UI/Backend/Data)
+- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
 - Ensure task count ≤10
 
-**Step 3: Generate Task JSON Files**
+**Step 3: Generate Task JSON Files (ENFORCE QUANTIFICATION)**
 - Use the template structure from Step 1
 - Create .task/IMPL-*.json files with proper structure
+- **MANDATORY: Apply Quantification Formats**:
+  - Every requirement: \`{count} {type}: [{explicit_list}]\`
+  - Every acceptance: Measurable with verification command
+  - Every modification_point: Exact targets (files/functions/lines)
+  - NO vague language in any field
 - Replace all {placeholder} variables with actual session paths
 - Embed artifacts array with brainstorming outputs
 - Include MCP tool integration in pre_analysis steps
+- **Validation**: Run checklist from Quantification Requirements section before writing files
 
 **Step 4: Create IMPL_PLAN.md**
 - Use IMPL_PLAN template
@@ -249,39 +307,10 @@ $(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
 - Update workflow-session.json with task count and artifact inventory
 - Mark session ready for execution
 
-### MCP Enhancement Examples
+### MCP Enhancement (Optional)
 
-**Code Index Usage**:
-\`\`\`javascript
-// Discover authentication-related files
-mcp__code-index__find_files(pattern="*auth*")
-
-// Search for OAuth patterns
-mcp__code-index__search_code_advanced(
-  pattern="oauth|jwt|authentication",
-  file_pattern="*.{ts,js}"
-)
-
-// Get file summary for key components
-mcp__code-index__get_file_summary(
-  file_path="src/auth/index.ts"
-)
-\`\`\`
-
-**Exa Research Usage**:
-\`\`\`javascript
-// Get best practices for task implementation
-mcp__exa__get_code_context_exa(
-  query="TypeScript OAuth2 implementation patterns",
-  tokensNum="dynamic"
-)
-
-// Research specific API usage
-mcp__exa__get_code_context_exa(
-  query="Express.js JWT middleware examples",
-  tokensNum=5000
-)
-\`\`\`
+**Code Analysis**: Use `find`, `rg` for file discovery and pattern search
+**External Research**: Use `mcp__exa__get_code_context_exa` for best practices and API examples
 
 ### Quality Validation
 
@@ -301,7 +330,7 @@ Before completion, verify:
 
 Generate all three documents and report completion status:
 - Task JSON files created: N files
-- Artifacts integrated: synthesis-spec, topic-framework, N role analyses
+- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
 - MCP enhancements: code-index, exa-research
 - Session ready for execution: /workflow:execute
 `
@@ -322,17 +351,24 @@ const agentContext = {
     ? memory.get("workflow-session.json")
     : Read(.workflow/WFS-[id]/workflow-session.json),
 
-  analysis_results: memory.has("ANALYSIS_RESULTS.md")
-    ? memory.get("ANALYSIS_RESULTS.md")
-    : Read(.workflow/WFS-[id]/.process/ANALYSIS_RESULTS.md),
-
-  artifacts_inventory: memory.has("artifacts_inventory")
-    ? memory.get("artifacts_inventory")
-    : discoverArtifacts(),
+  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
 
   context_package: memory.has("context-package.json")
     ? memory.get("context-package.json")
-    : Read(.workflow/WFS-[id]/.process/context-package.json),
+    : Read(".workflow/WFS-[id]/.process/context-package.json"),
+
+  // Extract brainstorm artifacts from context package
+  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
+
+  // Load role analyses using paths from context package
+  role_analyses: brainstorm_artifacts.role_analyses
+    .flatMap(role => role.files)
+    .map(file => Read(file.path)),
+
+  // Load conflict resolution if exists (from context package)
+  conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
+    ? Read(brainstorm_artifacts.conflict_resolution.path)
+    : null,
 
   // Optional MCP enhancements
   mcp_analysis: executeMcpDiscovery()

.claude/commands/workflow/tools/task-generate-tdd.md

@@ -1,8 +1,8 @@
 ---
 name: task-generate-tdd
-description: Generate TDD task chains with Red-Green-Refactor dependencies
+description: Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation
 argument-hint: "--session WFS-session-id [--agent]"
-allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
+allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
 ---
 
 # TDD Task Generation Command
@@ -49,11 +49,39 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
 - **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
 - **Phase-Explicit**: Internal phases clearly marked in flow_control.implementation_approach
 - **Task Merging**: Prefer single task per feature over decomposition
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
 - **Artifact-Aware**: Integrates brainstorming outputs
 - **Memory-First**: Reuse loaded documents from memory
 - **Context-Aware**: Analyzes existing codebase and test patterns
 - **Iterative Green Phase**: Auto-diagnose and fix test failures with Gemini + optional Codex
 - **Safety-First**: Auto-revert on max iterations to prevent broken state
+- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations (e.g., "15 test cases: [test1, test2, ...]" not "comprehensive tests")
+
+## Quantification Requirements for TDD (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit test case counts, coverage metrics, and implementation scope.
+
+**Core Rules**:
+1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list
+2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%")
+3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts
+4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts
+
+**TDD Phase Formats**:
+- **Red Phase**: `"Write N test cases: [test1, test2, ...]"`
+- **Green Phase**: `"Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"`
+- **Refactor Phase**: `"Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"`
+- **Acceptance**: `"All N tests pass with >=X% coverage: verify by [test command]"`
+
+**TDD Cycles Array**: Each cycle must include `test_count`, `test_cases` array, `implementation_scope`, and `expected_coverage`
+
+**Validation Checklist**:
+- [ ] Every Red phase specifies exact test case count with enumerated list
+- [ ] Every Green phase enumerates files, functions, and estimated line counts
+- [ ] Every Refactor phase lists specific improvements with counts
+- [ ] Every acceptance criterion includes measurable coverage percentage
+- [ ] tdd_cycles array contains test_count and test_cases for each cycle
+- [ ] No vague language ("comprehensive", "complete", "thorough")
 
 ## Core Responsibilities
 - Parse analysis results and identify testable features
@@ -72,25 +100,35 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
    - If session metadata in memory → Skip loading
    - Else: Load `.workflow/{session_id}/workflow-session.json`
 
-2. **Analysis Results Loading**
-   - If ANALYSIS_RESULTS.md in memory → Skip loading
-   - Else: Read `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
+2. **Conflict Resolution Check** (NEW - Priority Input)
+   - If CONFLICT_RESOLUTION.md exists → Load selected strategies
+   - Else: Skip to brainstorming artifacts
+   - Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md`
 
 3. **Artifact Discovery**
    - If artifact inventory in memory → Skip scanning
    - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
-   - Detect: synthesis-specification.md, topic-framework.md, role analyses
+   - Detect: role analysis documents, guidance-specification.md, role analyses
+
+4. **Context Package Loading**
+   - Load `.workflow/{session_id}/.process/context-package.json`
+   - Load `.workflow/{session_id}/.process/test-context-package.json` (if exists)
 
 ### Phase 2: TDD Task JSON Generation
 
-**Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase)
+**Input Sources** (priority order):
+1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies
+2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.)
+3. **Context Package**: `.process/context-package.json` - Project structure and requirements
+4. **Test Context**: `.process/test-context-package.json` - Existing test patterns
 
-**ANALYSIS_RESULTS.md includes**:
+**TDD Task Structure includes**:
 - Feature list with testable requirements
 - Test cases for Red phase
-- Implementation requirements for Green phase
+- Implementation requirements for Green phase (with test-fix cycle)
 - Refactoring opportunities
 - Task dependencies and execution order
+- Conflict resolution decisions (if applicable)
 
 ### Phase 3: Task JSON & IMPL_PLAN.md Generation
 
@@ -118,247 +156,87 @@ For each feature, generate task(s) with ID format:
 
 #### Task JSON Structure Reference
 
-**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
-```json
-{
-  "id": "IMPL-N",                                  // Task identifier
-  "title": "Feature description with TDD",         // Human-readable title
-  "status": "pending",                             // pending | in_progress | completed | container
-  "meta": {
-    "type": "feature",                             // Task type
-    "agent": "@code-developer",                    // Assigned agent
-    "tdd_workflow": true,                          // REQUIRED: Enables TDD flow
-    "max_iterations": 3,                           // Green phase test-fix cycle limit
-    "use_codex": false                             // false=manual fixes, true=Codex automated fixes
-  },
-  "context": {
-    "requirements": [                              // Feature requirements with TDD phases
-      "Feature description",
-      "Red: Test scenarios to write",
-      "Green: Implementation approach with test-fix cycle",
-      "Refactor: Code quality improvements"
-    ],
-    "tdd_cycles": [                                // OPTIONAL: Detailed test cycles
-      {
-        "cycle": 1,
-        "feature": "Specific functionality",
-        "test_focus": "What to test",
-        "expected_failure": "Why test should fail initially"
-      }
-    ],
-    "focus_paths": ["src/path/", "tests/path/"],  // Files to modify
-    "acceptance": [                                // Success criteria
-      "All tests pass (Red → Green)",
-      "Code refactored (Refactor complete)",
-      "Test coverage ≥80%"
-    ],
-    "depends_on": []                               // Task dependencies
-  },
-  "flow_control": {
-    "pre_analysis": [                              // OPTIONAL: Pre-execution checks
-      {
-        "step": "check_test_framework",
-        "action": "Verify test framework",
-        "command": "bash(npm list jest)",
-        "output_to": "test_framework_info",
-        "on_error": "warn"
-      }
-    ],
-    "implementation_approach": [                   // REQUIRED: 3 TDD phases
-      {
-        "step": 1,
-        "title": "RED Phase: Write failing tests",
-        "tdd_phase": "red",                        // REQUIRED: Phase identifier
-        "description": "Write comprehensive failing tests",
-        "modification_points": ["Files/changes to make"],
-        "logic_flow": ["Step-by-step process"],
-        "acceptance": ["Phase success criteria"],
-        "depends_on": [],
-        "output": "failing_tests"
-      },
-      {
-        "step": 2,
-        "title": "GREEN Phase: Implement to pass tests",
-        "tdd_phase": "green",                      // REQUIRED: Phase identifier
-        "description": "Minimal implementation with test-fix cycle",
-        "modification_points": ["Implementation files"],
-        "logic_flow": [
-          "Implement minimal code",
-          "Run tests",
-          "If fail → Enter iteration loop (max 3):",
-          "  1. Extract failure messages",
-          "  2. Gemini bug-fix diagnosis",
-          "  3. Apply fixes",
-          "  4. Rerun tests",
-          "If max_iterations → Auto-revert"
-        ],
-        "acceptance": ["All tests pass"],
-        "command": "bash(npm test -- tests/path/)",
-        "depends_on": [1],
-        "output": "passing_implementation"
-      },
-      {
-        "step": 3,
-        "title": "REFACTOR Phase: Improve code quality",
-        "tdd_phase": "refactor",                   // REQUIRED: Phase identifier
-        "description": "Refactor while keeping tests green",
-        "modification_points": ["Quality improvements"],
-        "logic_flow": ["Incremental refactoring with test verification"],
-        "acceptance": ["Tests still pass", "Code quality improved"],
-        "command": "bash(npm run lint && npm test)",
-        "depends_on": [2],
-        "output": "refactored_implementation"
-      }
-    ],
-    "post_completion": [                           // OPTIONAL: Final verification
-      {
-        "step": "verify_full_tdd_cycle",
-        "action": "Confirm complete TDD cycle",
-        "command": "bash(npm test && echo 'TDD complete')",
-        "output_to": "final_validation",
-        "on_error": "fail"
-      }
-    ],
-    "error_handling": {                            // OPTIONAL: Error recovery
-      "green_phase_max_iterations": {
-        "action": "revert_all_changes",
-        "commands": ["bash(git reset --hard HEAD)"],
-        "report": "Generate failure report"
-      }
-    }
-  }
-}
-```
+Each TDD task JSON contains complete Red-Green-Refactor cycle with these key fields:
 
-**Key JSON Fields Summary**:
-- `meta.tdd_workflow`: Must be `true`
-- `meta.max_iterations`: Green phase fix cycle limit (default: 3)
-- `meta.use_codex`: Automated fixes (false=manual, true=Codex)
-- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor"
-- `context.tdd_cycles`: Optional detailed test cycle specifications
-- `context.parent`: Required for subtasks (IMPL-N.M)
+**Top-Level Fields**:
+- `id`: Task identifier (`IMPL-N` or `IMPL-N.M` for subtasks)
+- `title`: Feature description with TDD
+- `status`: `pending | in_progress | completed | container`
+- `context_package_path`: Path to context package
+- `meta`: TDD-specific metadata
+- `context`: Requirements, cycles, paths, acceptance
+- `flow_control`: Pre-analysis, 3 TDD phases, post-completion, error handling
+
+**Meta Object (TDD-Specific)**:
+- `type`: "feature"
+- `agent`: "@code-developer"
+- `tdd_workflow`: `true` (REQUIRED - enables TDD flow)
+- `max_iterations`: Green phase test-fix cycle limit (default: 3)
+- `use_codex`: `false` (manual fixes) or `true` (Codex automated fixes)
+
+**Context Object**:
+- `requirements`: Quantified feature requirements with TDD phase details
+- `tdd_cycles`: Array of test cycles (each with `test_count`, `test_cases`, `implementation_scope`, `expected_coverage`)
+- `focus_paths`: Target directories (absolute or relative from project root)
+- `acceptance`: Measurable success criteria with verification commands
+- `depends_on`: Task dependencies
+- `parent`: Parent task ID (for subtasks only)
+
+**Flow Control Object**:
+- `pre_analysis`: Optional pre-execution checks
+- `implementation_approach`: Exactly 3 steps with `tdd_phase` field:
+  1. **Red Phase** (`tdd_phase: "red"`): Write failing tests
+  2. **Green Phase** (`tdd_phase: "green"`): Implement to pass tests (includes test-fix cycle)
+  3. **Refactor Phase** (`tdd_phase: "refactor"`): Improve code quality
+- `post_completion`: Optional final verification
+- `error_handling`: Error recovery strategies (e.g., auto-revert on max iterations)
+
+**Implementation Approach Step Structure**:
+Each step includes:
+- `step`: Step number
+- `title`: Phase description
+- `tdd_phase`: Phase identifier ("red" | "green" | "refactor")
+- `description`: Detailed phase description
+- `modification_points`: Quantified changes to make
+- `logic_flow`: Step-by-step execution logic
+- `acceptance`: Phase-specific acceptance criteria
+- `command`: Test/verification command (optional)
+- `depends_on`: Previous step dependencies
+- `output`: Step output identifier
 
 #### IMPL_PLAN.md Structure
 
-Generate IMPL_PLAN.md with 8-section structure:
+**Frontmatter** (TDD-specific fields):
+- `workflow_type`: "tdd"
+- `tdd_workflow`: true
+- `feature_count`, `task_count` (≤10 total)
+- `task_breakdown`: simple_features, complex_features, total_subtasks
+- `test_context`: Path to test-context-package.json (if exists)
+- `conflict_resolution`: Path to CONFLICT_RESOLUTION.md (if exists)
+- `verification_history`, `phase_progression`
 
-**Frontmatter** (required fields):
-```yaml
----
-identifier: WFS-{session-id}
-source: "User requirements" | "File: path"
-analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
-context_package: .workflow/{session-id}/.process/context-package.json
-workflow_type: "tdd"
-verification_history:
-  concept_verify: "passed | skipped | pending"
-  action_plan_verify: "pending"
-phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"
-feature_count: N
-task_count: N  # ≤10 total
-task_breakdown:
-  simple_features: K
-  complex_features: L
-  total_subtasks: M
-tdd_workflow: true
----
-```
-
-**8 Sections Structure**:
-
-```markdown
-# Implementation Plan: {Project Title}
-
-## 1. Summary
-- Core requirements and objectives (2-3 paragraphs)
-- TDD-specific technical approach
-
-## 2. Context Analysis
-- CCW Workflow Context (Phase progression, Quality gates)
-- Context Package Summary (Focus paths, Test context)
-- Project Profile (Type, Scale, Tech Stack, Timeline)
-- Module Structure (Directory tree)
-- Dependencies (Primary, Testing, Development)
-- Patterns & Conventions
-
-## 3. Brainstorming Artifacts Reference
-- Artifact Usage Strategy
-  - synthesis-specification.md (primary reference)
-  - test-context-package.json (test patterns)
-  - context-package.json (smart context)
-  - ANALYSIS_RESULTS.md (technical analysis)
-- Artifact Priority in Development
-
-## 4. Implementation Strategy
-- Execution Strategy (TDD Cycles: Red-Green-Refactor)
-- Architectural Approach
-- Key Dependencies (Task dependency graph)
-- Testing Strategy (Coverage targets, Quality gates)
-
-## 5. TDD Implementation Tasks
-- Feature-by-Feature TDD Tasks
-  - Each task: IMPL-N with internal Red → Green → Refactor
-  - Dependencies and complexity metrics
-- Complex Feature Examples (when subtasks needed)
-- TDD Task Breakdown Summary
-
-## 6. Implementation Plan (Detailed Phased Breakdown)
-- Execution Strategy (feature-by-feature sequential)
-- Phase breakdown (Phase 1, Phase 2, etc.)
-- Resource Requirements (Team, Dependencies, Infrastructure)
-
-## 7. Risk Assessment & Mitigation
-- Risk table (Risk, Impact, Probability, Mitigation, Owner)
-- Critical Risks (TDD-specific)
-- Monitoring Strategy
-
-## 8. Success Criteria
-- Functional Completeness
-- Technical Quality (Test coverage ≥80%)
-- Operational Readiness
-- TDD Compliance
-```
+**8 Sections**:
+1. **Summary**: Core requirements, TDD-specific approach
+2. **Context Analysis**: CCW workflow context, project profile, module structure, dependencies
+3. **Brainstorming Artifacts Reference**: Artifact usage strategy, priority order
+4. **Implementation Strategy**: TDD cycles (Red-Green-Refactor), architectural approach, testing strategy
+5. **TDD Implementation Tasks**: Feature-by-feature tasks with internal TDD cycles, dependencies
+6. **Implementation Plan**: Phased breakdown, resource requirements
+7. **Risk Assessment & Mitigation**: Risk table, TDD-specific risks, monitoring
+8. **Success Criteria**: Functional completeness, technical quality (≥80% coverage), TDD compliance
 
 ### Phase 4: TODO_LIST.md Generation
 
 Generate task list with internal TDD phase indicators:
 
-**For Simple Features (1 task per feature)**:
-```markdown
-## TDD Implementation Tasks
-
-### Feature 1: {Feature Name}
-- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
-  - Internal phases: Red → Green → Refactor
-  - Dependencies: None
-
-### Feature 2: {Feature Name}
-- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
-  - Internal phases: Red → Green → Refactor
-  - Dependencies: IMPL-1
-```
-
-**For Complex Features (with subtasks)**:
-```markdown
-### Feature 3: {Complex Feature Name}
-▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
-  - [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
-    - Internal phases: Red → Green → Refactor
-  - [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
-    - Internal phases: Red → Green → Refactor
-    - Dependencies: IMPL-3.1
-```
+**Structure**:
+- Simple features: `- [ ] **IMPL-N**: Feature with TDD` (Internal phases: Red → Green → Refactor)
+- Complex features: `▸ **IMPL-N**: Container` with subtasks `- [ ] **IMPL-N.M**: Sub-feature`
 
 **Status Legend**:
-```markdown
-## Status Legend
-- ▸ = Container task (has subtasks)
-- [ ] = Pending task
-- [x] = Completed task
-- Red = Write failing tests
-- Green = Implement to pass tests (with test-fix cycle)
-- Refactor = Improve code quality
-```
+- `▸` = Container task (has subtasks)
+- `[ ]` = Pending | `[x]` = Completed
+- Red → Green → Refactor = TDD phases
 
 ### Phase 5: Session State Update
 
@@ -397,9 +275,10 @@ Update workflow-session.json with TDD metadata:
 │   ├── IMPL-3.2.json                # Complex feature subtask (if needed)
 │   └── ...
 └── .process/
-    ├── ANALYSIS_RESULTS.md          # Enhanced with TDD breakdown from concept-enhanced
+    ├── CONFLICT_RESOLUTION.md       # Conflict resolution strategies (if conflict_risk ≥ medium)
     ├── test-context-package.json    # Test coverage analysis
     ├── context-package.json         # Input from context-gather
+    ├── context_package_path         # Path to smart context package
     └── green-fix-iteration-*.md     # Fix logs from Green phase test-fix cycles
 ```
 
@@ -438,7 +317,7 @@ Update workflow-session.json with TDD metadata:
 | Error | Cause | Resolution |
 |-------|-------|------------|
 | Session not found | Invalid session ID | Verify session exists |
-| Analysis missing | Incomplete planning | Run concept-enhanced first |
+| Context missing | Incomplete planning | Run context-gather first |
 
 ### TDD Generation Errors
 | Error | Cause | Resolution |
@@ -450,12 +329,12 @@ Update workflow-session.json with TDD metadata:
 
 ## Integration & Usage
 
-### Command Chain
-- **Called By**: `/workflow:tdd-plan` (Phase 4)
-- **Calls**: Gemini wrapper for TDD breakdown
-- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
+**Command Chain**:
+- Called by: `/workflow:tdd-plan` (Phase 4)
+- Calls: Gemini CLI for TDD breakdown
+- Followed by: `/workflow:execute`, `/workflow:tdd-verify`
 
-### Basic Usage
+**Basic Usage**:
 ```bash
 # Manual mode (default)
 /workflow:tools:task-generate-tdd --session WFS-auth
@@ -464,38 +343,11 @@ Update workflow-session.json with TDD metadata:
 /workflow:tools:task-generate-tdd --session WFS-auth --agent
 ```
 
-### Expected Output
-```
-TDD task generation complete for session: WFS-auth
-
-Features analyzed: 5
-Total tasks: 5 (1 task per feature with internal TDD cycles)
-
-Task breakdown:
-- Simple features: 4 tasks (IMPL-1 to IMPL-4)
-- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
-- Total task count: 6 (within 10-task limit)
-
-Structure:
-- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
-- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
-- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
-- IMPL-4: Role Management (Internal: Red → Green → Refactor)
-- IMPL-5: Payment System (Container)
-  - IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
-  - IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
-
-Plans generated:
-- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
-- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
-
-TDD Configuration:
-- Each task contains complete Red-Green-Refactor cycle
-- Green phase includes test-fix cycle (max 3 iterations)
-- Auto-revert on max iterations reached
-
-Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
-```
+**Output**:
+- Task JSON files in `.task/` directory (IMPL-N.json format)
+- IMPL_PLAN.md with TDD Implementation Tasks section
+- TODO_LIST.md with internal TDD phase indicators
+- Session state updated with task count and TDD metadata
 
 ## Test Coverage Analysis Integration
 

.claude/commands/workflow/tools/task-generate.md

@@ -1,6 +1,6 @@
 --- 
 name: task-generate
-description: Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration
+description: Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration
 argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate --session WFS-auth
@@ -10,7 +10,7 @@ examples:
 # Task Generation Command
 
 ## 1. Overview
-This command generates task JSON files and an `IMPL_PLAN.md` from `ANALYSIS_RESULTS.md`. It automatically detects and integrates brainstorming artifacts, creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate analysis into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
+This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
 
 ## 2. Execution Modes
 
@@ -37,33 +37,86 @@ When the `--cli-execute` flag is used, each step in `implementation_approach` **
 ## 3. Core Principles
 This command is built on a set of core principles to ensure efficient and reliable task generation.
 
-- **Analysis-Driven**: All generated tasks originate from `ANALYSIS_RESULTS.md`, ensuring a direct link between analysis and implementation
-- **Artifact-Aware**: Automatically detects and integrates brainstorming outputs (`synthesis-specification.md`, role analyses) to enrich task context
+- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
+- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
 - **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
 - **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
 - **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
 - **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
 - **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
+- **Quantification-Enforced**: **NEW** - All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations to prevent ambiguity (e.g., "17 commands: [list]" not "implement commands")
 - **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
 
+## 3.5. Quantification Requirements (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
+
+**Core Rules**:
+1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
+2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
+3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
+4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
+5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
+
+**Standard Formats**:
+
+- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
+- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
+- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
+
+**Validation Checklist**:
+- [ ] Every requirement contains explicit count or enumerated list
+- [ ] Every acceptance criterion is measurable with verification command
+- [ ] Every modification_point specifies exact targets (files/functions/lines)
+- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
+- [ ] Each implementation step has its own acceptance criteria
+
 ## 4. Execution Flow
 The command follows a streamlined, three-step process to convert analysis into executable tasks.
 
 ### Step 1: Input & Discovery
 The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
 1.  **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`.
-2.  **Analysis Loading**: Reads the primary input, `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`.
-3.  **Artifact Discovery**: Scans the `.workflow/{session_id}/.brainstorming/` directory to find `synthesis-specification.md`, `topic-framework.md`, and various role analyses.
+2.  **Context Package Loading** (primary source): Reads `.workflow/{session_id}/.process/context-package.json` for smart context and artifact catalog.
+3.  **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
+4.  **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
 
 ### Step 2: Task Decomposition & Grouping
 Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
-1.  **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies.
-2.  **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`.
+
+**Phase 2.1: Quantification Extraction (NEW - CRITICAL)**
+1. **Count Extraction**: Scan analysis documents for quantifiable information:
+   - Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features")
+   - Identify enumerated lists (bullet points, numbered lists, comma-separated items)
+   - Extract explicit counts from tables, diagrams, or structured data
+   - Store extracted counts with their context (what is being counted)
+
+2. **List Enumeration**: Build explicit lists for each deliverable:
+   - If analysis says "implement session commands", enumerate ALL commands: [start, resume, list, complete, archive]
+   - If analysis mentions "create categories", list ALL categories: [literature, experiment, data-analysis, visualization, context]
+   - If analysis describes "modify functions", list ALL functions with line numbers
+   - Maintain full enumerations (no "..." unless list exceeds 20 items)
+
+3. **Verification Method Assignment**: For each deliverable, determine verification approach:
+   - File count: `ls {path}/*.{ext} | wc -l = {count}`
+   - Directory existence: `ls {parent}/ | grep -E '(name1|name2|...)' | wc -l = {count}`
+   - Test coverage: `pytest --cov={module} --cov-report=term | grep TOTAL | awk '{print $4}' >= {percentage}`
+   - Function existence: `grep -E '(func1|func2|...)' {file} | wc -l = {count}`
+
+4. **Ambiguity Detection**: Flag vague language for replacement:
+   - Detect words: "complete", "comprehensive", "reorganize", "refactor", "implement", "create" without counts
+   - Require quantification: "implement" → "implement {N} {items}: [{list}]"
+   - Reject unquantified deliverables
+
+**Phase 2.2: Task Definition & Grouping**
+1.  **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies from quantified analysis
+2.  **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`
 3.  **Task Grouping**:
-    *   Tasks with the **same signature** are candidates for merging, as they operate on the same context.
-    *   Tasks with **different signatures** and no dependencies are grouped for parallel execution.
-    *   Tasks with `depends_on` relationships are marked for sequential execution.
-4.  **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field.
+    *   Tasks with the **same signature** are candidates for merging, as they operate on the same context
+    *   Tasks with **different signatures** and no dependencies are grouped for parallel execution
+    *   Tasks with `depends_on` relationships are marked for sequential execution
+4.  **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field
 
 ### Step 3: Output Generation
 Finally, the command generates all the necessary output files.
@@ -165,131 +218,134 @@ function assignExecutionGroups(tasks) {
 The command produces three key documents and a directory of task files.
 
 ### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
-This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
+Each task JSON embeds all necessary context, artifacts, and execution steps using this schema:
 
+**Top-Level Fields**:
+- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
+- `title`: Descriptive task name
+- `status`: Task state (`pending|active|completed|blocked|container`)
+- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
+- `meta`: Task metadata
+- `context`: Task-specific context and requirements
+- `flow_control`: Execution steps and workflow
+
+**Meta Object**:
+- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`)
+- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`)
+- `execution_group`: Parallelization group ID or null
+- `context_signature`: Hash for context-based grouping
+
+**Context Object**:
+- `requirements`: Quantified implementation requirements (with counts and explicit lists)
+- `focus_paths`: Target directories/files (absolute or relative paths)
+- `acceptance`: Measurable acceptance criteria (with verification commands)
+- `parent`: Parent task ID for subtasks
+- `depends_on`: Prerequisite task IDs
+- `inherited`: Shared patterns and dependencies from parent
+- `shared_context`: Tech stack and conventions
+- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage
+
+**Flow Control Object**:
+- `pre_analysis`: Context loading and preparation steps
+  - `load_context_package`: Load smart context and artifact catalog
+  - `load_role_analysis_artifacts`: Load role analyses dynamically from context package
+  - `load_planning_context`: Load finalized decisions with resolved conflicts
+  - `codebase_exploration`: Discover existing patterns
+  - `analyze_task_patterns`: Identify modification targets
+- `implementation_approach`: Execution steps
+  - **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously)
+  - **CLI Mode**: Steps include `command` field with CLI tool invocation
+- `target_files`: Specific files/functions/lines to modify
+
+**Key Characteristics**:
+- **Quantification**: All requirements/acceptance use explicit counts and enumerations
+- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`)
+- **Context Intelligence**: References context-package.json for smart context and artifact paths
+- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts
+
+**Example Task JSON**:
 ```json
 {
-  "id": "IMPL-N[.M]",
-  "title": "Descriptive task name",
-  "status": "pending|active|completed|blocked|container",
+  "id": "IMPL-1",
+  "title": "Implement feature X with Y components",
+  "status": "pending",
+  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
   "meta": {
-    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose",
-    "execution_group": "group-id|null",
-    "context_signature": "hash-of-focus_paths-and-artifacts"
+    "type": "feature",
+    "agent": "@code-developer",
+    "execution_group": "parallel-abc123",
+    "context_signature": "hash-value"
   },
   "context": {
-    "requirements": ["Clear requirement from analysis"],
-    "focus_paths": ["src/module/path", "tests/module/path"],
-    "acceptance": ["Measurable acceptance criterion"],
-    "parent": "IMPL-N",
-    "depends_on": ["IMPL-N.M"],
-    "inherited": {"shared_patterns": [], "common_dependencies": []},
-    "shared_context": {"tech_stack": [], "conventions": []},
+    "requirements": [
+      "Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]",
+      "Create 3 directories: [dir1/, dir2/, dir3/]",
+      "Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]"
+    ],
+    "focus_paths": ["D:\\project\\src\\module", "./tests/module"],
+    "acceptance": [
+      "5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5",
+      "3 directories exist: verify by ls -d dir*/ | wc -l = 3",
+      "All tests pass: pytest tests/ --cov=src/module (>=80% coverage)"
+    ],
+    "depends_on": [],
     "artifacts": [
       {
-        "type": "synthesis_specification",
-        "source": "brainstorm_synthesis",
-        "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
+        "path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
         "priority": "highest",
-        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
-      },
-      {
-        "type": "role_analysis",
-        "source": "brainstorm_roles",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis.md",
-        "priority": "high",
-        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
-        "note": "Dynamically discovered - multiple role analysis files may be included based on brainstorming results"
-      },
-      {
-        "type": "topic_framework",
-        "source": "brainstorm_framework",
-        "path": ".workflow/WFS-[session]/.brainstorming/topic-framework.md",
-        "priority": "low",
-        "usage": "Discussion context and framework structure"
+        "usage": "Architecture decisions and API specifications"
       }
     ]
   },
   "flow_control": {
     "pre_analysis": [
       {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
-        "commands": [
-          "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')",
-          "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
-        ],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
+        "step": "load_context_package",
+        "action": "Load context package for artifact paths and smart context",
+        "commands": ["Read({{context_package_path}})"],
+        "output_to": "context_package",
+        "on_error": "fail"
       },
       {
         "step": "load_role_analysis_artifacts",
-        "action": "Load role-specific analysis documents for technical details",
-        "note": "These artifacts contain implementation details not in synthesis. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics.",
+        "action": "Load role analyses from context-package.json",
         "commands": [
-          "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis.md' 2>/dev/null | head -8)",
-          "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)",
-          "Read(.workflow/WFS-[session]/.brainstorming/ui-designer/analysis.md)",
-          "Read(.workflow/WFS-[session]/.brainstorming/product-manager/analysis.md)"
+          "Read({{context_package_path}})",
+          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+          "Read(each extracted path)"
         ],
         "output_to": "role_analysis_artifacts",
         "on_error": "skip_optional"
-      },
-      {
-        "step": "load_planning_context",
-        "action": "Load plan-generated analysis",
-        "commands": [
-          "Read(.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md)",
-          "Read(.workflow/WFS-[session]/.process/context-package.json)"
-        ],
-        "output_to": "planning_context"
-      },
-      {
-        "step": "mcp_codebase_exploration",
-        "action": "Explore codebase using MCP tools",
-        "command": "mcp__code-index__find_files(pattern=\"[patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[patterns]\")",
-        "output_to": "codebase_structure"
-      },
-      {
-        "step": "analyze_task_patterns",
-        "action": "Analyze existing code patterns and identify modification targets",
-        "commands": [
-          "bash(cd \"[focus_paths]\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
-        ],
-        "output_to": "task_context_with_targets",
-        "on_error": "fail"
       }
     ],
     "implementation_approach": [
       {
         "step": 1,
-        "title": "Implement task following synthesis specification",
-        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "title": "Implement feature following role analyses",
+        "description": "Implement feature X using requirements from role analyses and context package",
         "modification_points": [
-          "Apply consolidated requirements from synthesis-specification.md",
-          "Follow technical guidelines from synthesis",
-          "Consult artifacts for implementation details when needed",
-          "Integrate with existing patterns"
+          "Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]",
+          "Modify funcA() in file1.ts lines 10-25: add validation logic",
+          "Modify funcB() in file2.ts lines 40-60: integrate with new API"
         ],
         "logic_flow": [
-          "Load synthesis specification",
-          "Extract requirements and design",
-          "Analyze existing patterns",
-          "Implement following specification",
-          "Consult artifacts for technical details when needed",
+          "Load role analyses and context package",
+          "Extract requirements and design decisions",
+          "Implement commands following existing patterns",
+          "Update functions with new logic",
           "Validate against acceptance criteria"
         ],
         "depends_on": [],
         "output": "implementation"
       }
     ],
-    "target_files": ["file:function:lines"]
+    "target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"]
   }
 }
 ```
 
+**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`).
+
 ### 6.2. IMPL_PLAN.md Structure
 This document provides a high-level overview of the entire implementation plan.
 
@@ -297,14 +353,16 @@ This document provides a high-level overview of the entire implementation plan.
 ---
 identifier: WFS-{session-id}
 source: "User requirements" | "File: path" | "Issue: ISS-001"
-analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+role_analyses: .workflow/{session-id}/.brainstorming/[role]/analysis*.md
 artifacts: .workflow/{session-id}/.brainstorming/
 context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+guidance_specification: .workflow/{session-id}/.brainstorming/guidance-specification.md  # Finalized decisions with resolved conflicts
 workflow_type: "standard | tdd | design"  # Indicates execution model
 verification_history:  # CCW quality gates
-  concept_verify: "passed | skipped | pending"
+  synthesis_clarify: "passed | skipped | pending"  # Brainstorm phase clarification
   action_plan_verify: "pending"
-phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
+  conflict_resolution: "resolved | none | low"  # Status from context-package.json
+phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning"  # CCW workflow phases
 ---
 
 # Implementation Plan: {Project Title}
@@ -323,14 +381,14 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 ### CCW Workflow Context
 **Phase Progression**:
-- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
-- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
-- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
-- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
-- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
+- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
+- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
+- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
+- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
+- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
 
 **Quality Gates**:
-- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
+- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
 - action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
 
 **Context Package Summary**:
@@ -364,40 +422,42 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 ## 3. Brainstorming Artifacts Reference
 
 ### Artifact Usage Strategy
-**Primary Reference (synthesis-specification.md)**:
-- **What**: Comprehensive implementation blueprint from multi-role synthesis
-- **When**: Every task references this first for requirements and design decisions
-- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
-- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
-- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
+**Primary Reference (Role Analyses)**:
+- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
+- **When**: Every task references relevant role analyses for requirements and design decisions
+- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
+- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
+- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
 
 **Context Intelligence (context-package.json)**:
 - **What**: Smart context gathered by CCW's context-gather phase
-- **Content**: Focus paths, dependency graph, existing patterns, module structure
-- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup
+- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
+- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
 - **CCW Value**: Automated intelligent context discovery replacing manual file exploration
 
-**Technical Analysis (ANALYSIS_RESULTS.md)**:
-- **What**: Gemini/Qwen/Codex parallel analysis results
-- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
-- **Usage**: Referenced in task planning for technical guidance and risk mitigation
-- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
+**Conflict Resolution Status**:
+- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
+- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
+- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
+- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
+- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
 
-### Integrated Specifications (Highest Priority)
-- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+### Role Analysis Documents (Highest Priority)
+Role analyses provide specialized perspectives on the implementation:
+- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
+- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
+- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
+- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
+- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
+- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
 
 ### Supporting Artifacts (Reference)
 - **topic-framework.md**: Role-specific discussion points and analysis framework
-- **system-architect/analysis.md**: Detailed architecture specifications
-- **ui-designer/analysis.md**: Layout and component specifications
-- **product-manager/analysis.md**: Product vision and user stories
 
 **Artifact Priority in Development**:
-1. synthesis-specification.md (primary reference for all tasks)
-2. context-package.json (smart context for execution environment)
-3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
-4. Role-specific analyses (fallback for detailed specifications)
+1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
+2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
+3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
 
 ## 4. Implementation Strategy
 
@@ -414,7 +474,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 ### Architectural Approach
 **Key Architecture Decisions**:
-- [ADR references from synthesis]
+- [ADR references from role analyses]
 - [Justification for architecture patterns]
 
 **Integration Strategy**:
@@ -506,7 +566,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 ## 8. Success Criteria
 
 **Functional Completeness**:
-- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All requirements from role analysis documents implemented
 - [ ] All acceptance criteria from task.json files met
 
 **Technical Quality**:
@@ -520,7 +580,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - [ ] Documentation complete
 
 **Business Metrics**:
-- [ ] [Key business metrics from synthesis]
+- [ ] [Key business metrics from role analyses]
 ```
 
 ### 6.3. TODO_LIST.md Structure
@@ -553,216 +613,39 @@ The command organizes outputs into a standard directory structure.
 │   ├── IMPL-1.json                  # Container task
 │   ├── IMPL-1.1.json                # Leaf task with flow_control
 │   └── IMPL-1.2.json                # Leaf task with flow_control
-├── .brainstorming/                  # Input artifacts
-│   ├── synthesis-specification.md
-│   ├── topic-framework.md
-│   └── {role}/analysis.md
+├── .brainstorming              # Input artifacts from brainstorm + synthesis
+│   ├── guidance-specification.md    # Finalized decisions (with resolved conflicts if any)
+│   └── {role}/analysis*.md          # Role analyses (enhanced by synthesis, with resolved conflicts if any)
 └── .process/
-    ├── ANALYSIS_RESULTS.md          # Input from concept-enhanced
-    └── context-package.json         # Input from context-gather
+    └── context-package.json         # Input from context-gather (smart context + conflict_risk status)
 ```
 
 ## 7. Artifact Integration
 The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
 
 #### Artifact Priority
-1.  **synthesis-specification.md** (highest): The complete, integrated specification that serves as the primary source of truth.
-2.  **topic-framework.md** (medium): The discussion framework that provides high-level structure.
-3.  **role/analysis.md** (low): Individual role-based analyses that offer detailed, perspective-specific insights.
+1.  **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
+2.  **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
+3.  **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
 
 #### Artifact-Task Mapping
 Artifacts are mapped to tasks based on their relevance to the task's domain.
-- **synthesis-specification.md**: Included in all tasks as the primary reference.
-- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks.
-- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks.
-- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards.
-- **data-architect/analysis.md**: Mapped to tasks involving data models or APIs.
+- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
+- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
+- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
+- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
+- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
+- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
 
-This ensures that each task has access to the most relevant and detailed specifications, from the high-level synthesis down to the role-specific details.
+This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
 
-## 8. CLI Execute Mode Details
-When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
-
-**Key Points**:
-- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
-- **Context Delivery**: Each codex command receives context via CONTEXT field: `@{.workflow/{session}/.process/context-package.json}` and `@{.workflow/{session}/.brainstorming/synthesis-specification.md}`
-- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
-- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
-
-### Example 1: Agent Mode - Simple Task (Default, No Command)
-```json
-{
-  "id": "IMPL-001",
-  "title": "Implement user authentication module",
-  "context": {
-    "depends_on": [],
-    "focus_paths": ["src/auth"],
-    "requirements": ["JWT-based authentication", "Login and registration endpoints"],
-    "acceptance": [
-      "JWT token generation working",
-      "Login and registration endpoints implemented",
-      "Tests passing with >70% coverage"
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis",
-        "action": "Load synthesis specification for requirements",
-        "commands": ["Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"],
-        "output_to": "synthesis_spec",
-        "on_error": "fail"
-      },
-      {
-        "step": "load_context",
-        "action": "Load context package for project structure",
-        "commands": ["Read(.workflow/WFS-session/.process/context-package.json)"],
-        "output_to": "context_pkg",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement JWT-based authentication",
-        "description": "Create authentication module using JWT following [synthesis_spec] requirements and [context_pkg] patterns",
-        "modification_points": [
-          "Create auth service with JWT generation",
-          "Implement login endpoint with credential validation",
-          "Implement registration endpoint with user creation",
-          "Add JWT middleware for route protection"
-        ],
-        "logic_flow": [
-          "User registers → validate input → hash password → create user",
-          "User logs in → validate credentials → generate JWT → return token",
-          "Protected routes → validate JWT → extract user → allow access"
-        ],
-        "depends_on": [],
-        "output": "auth_implementation"
-      }
-    ],
-    "target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"]
-  }
-}
-```
-
-### Example 2: CLI Execute Mode - Single Codex Step
-```json
-{
-  "id": "IMPL-002",
-  "title": "Implement user authentication module",
-  "context": {
-    "depends_on": [],
-    "focus_paths": ["src/auth"],
-    "requirements": ["JWT-based authentication", "Login and registration endpoints"],
-    "acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis",
-        "action": "Load synthesis specification",
-        "commands": ["Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"],
-        "output_to": "synthesis_spec",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement authentication with Codex",
-        "description": "Create JWT-based authentication module",
-        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Complete auth module with tests RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
-        "logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
-        "depends_on": [],
-        "output": "auth_implementation"
-      }
-    ],
-    "target_files": ["src/auth/service.ts", "src/auth/middleware.ts"]
-  }
-}
-```
-
-### Example 3: CLI Execute Mode - Multi-Step with Resume
-```json
-{
-  "id": "IMPL-003",
-  "title": "Implement role-based access control",
-  "context": {
-    "depends_on": ["IMPL-002"],
-    "focus_paths": ["src/auth", "src/middleware"],
-    "requirements": ["User roles and permissions", "Route protection middleware"],
-    "acceptance": ["RBAC models created", "Middleware working", "Management API complete"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_context",
-        "action": "Load context and synthesis",
-        "commands": [
-          "Read(.workflow/WFS-session/.process/context-package.json)",
-          "Read(.workflow/WFS-session/.brainstorming/synthesis-specification.md)"
-        ],
-        "output_to": "full_context",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Create RBAC models",
-        "description": "Define role and permission data models",
-        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{.workflow/WFS-session/.process/context-package.json} @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Models with migrations RULES: Follow synthesis spec\" --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Define role model", "Define permission model", "Create migrations"],
-        "logic_flow": ["Design schema", "Implement models", "Generate migrations"],
-        "depends_on": [],
-        "output": "rbac_models"
-      },
-      {
-        "step": 2,
-        "title": "Implement RBAC middleware",
-        "description": "Create route protection middleware using models from step 1",
-        "command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
-        "logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
-        "depends_on": [1],
-        "output": "rbac_middleware"
-      },
-      {
-        "step": 3,
-        "title": "Add role management API",
-        "description": "Create CRUD endpoints for roles and permissions",
-        "command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
-        "logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
-        "depends_on": [2],
-        "output": "role_management_api"
-      }
-    ],
-    "target_files": [
-      "src/models/Role.ts",
-      "src/models/Permission.ts",
-      "src/middleware/rbac.ts",
-      "src/routes/roles.ts"
-    ]
-  }
-}
-```
-
-**Pattern Summary**:
-- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
-- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
-- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
-- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
-
-## 9. Error Handling
+## 8. Error Handling
 
 ### Input Validation Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
 | Session not found | Invalid session ID | Verify session exists |
-| Analysis missing | Incomplete planning | Run concept-enhanced first |
+| Context missing | Incomplete planning | Run context-gather first |
 | Invalid format | Corrupted results | Regenerate analysis |
 
 ### Task Generation Errors
@@ -779,21 +662,19 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
 | Invalid format | Corrupted file | Skip artifact loading |
 | Path invalid | Moved/deleted | Update references |
 
-## 10. Integration & Usage
+## 10. Usage & Related Commands
 
-### Command Chain
-- **Called By**: `/workflow:plan` (Phase 4)
-- **Calls**: None (terminal command)
-- **Followed By**: `/workflow:execute`, `/workflow:status`
-
-### Basic Usage
+**Basic Usage**:
 ```bash
-/workflow:tools:task-generate --session WFS-auth
+/workflow:tools:task-generate --session WFS-auth [--cli-execute]
 ```
 
-## 11. Related Commands
-- `/workflow:plan` - Orchestrates entire planning
-- `/workflow:plan --cli-execute` - Planning with CLI execution mode
-- `/workflow:tools:context-gather` - Provides context package
-- `/workflow:tools:concept-enhanced` - Provides analysis results
+**Workflow Integration**:
+- Called by: `/workflow:plan` (task generation phase)
+- Followed by: `/workflow:execute`, `/workflow:status`
+
+**Related Commands**:
+- `/workflow:plan` - Orchestrates entire planning workflow
+- `/workflow:tools:context-gather` - Provides context package input
+- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed)
 - `/workflow:execute` - Executes generated tasks

.claude/commands/workflow/tools/tdd-coverage-analysis.md

@@ -1,6 +1,6 @@
 ---
 name: tdd-coverage-analysis
-description: Analyze test coverage and TDD cycle execution
+description: Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification
 argument-hint: "--session WFS-session-id"
 allowed-tools: Read(*), Write(*), Bash(*)
 ---

.claude/commands/workflow/tools/test-concept-enhanced.md

@@ -1,6 +1,6 @@
 ---
 name: test-concept-enhanced
-description: Analyze test requirements and generate test generation strategy using Gemini
+description: Analyze test requirements and generate test generation strategy using Gemini with test-context package
 argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
 examples:
   - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
@@ -48,7 +48,7 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
 
 **Tool Configuration**:
 ```bash
-cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -p "
+cd .workflow/{test_session_id}/.process && gemini -p "
 PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
 TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
 MODE: analysis

.claude/commands/workflow/tools/test-context-gather.md

@@ -1,285 +1,188 @@
 ---
 name: test-context-gather
-description: Collect test coverage context and identify files requiring test generation
+description: Collect test coverage context using test-context-search-agent and package into standardized test-context JSON
 argument-hint: "--session WFS-test-session-id"
 examples:
   - /workflow:tools:test-context-gather --session WFS-test-auth
   - /workflow:tools:test-context-gather --session WFS-test-payment
+allowed-tools: Task(*), Read(*), Glob(*)
 ---
 
-# Test Context Gather Command
+# Test Context Gather Command (/workflow:tools:test-context-gather)
 
 ## Overview
-Specialized context collector for test generation workflows that analyzes test coverage, identifies missing tests, and packages implementation context from source sessions.
+
+Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
+
+**Agent**: `test-context-search-agent` (`.claude/agents/test-context-search-agent.md`)
 
 ## Core Philosophy
-- **Coverage-First**: Analyze existing test coverage before planning
-- **Gap Identification**: Locate implementation files without corresponding tests
+
+- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution
+- **Detection-First**: Check for existing test-context-package before executing
+- **Coverage-First**: Analyze existing test coverage before planning new tests
 - **Source Context Loading**: Import implementation summaries from source session
-- **Framework Detection**: Auto-detect test framework and patterns
-- **MCP-Powered**: Leverage code-index tools for precise analysis
+- **Standardized Output**: Generate `.workflow/{test_session_id}/.process/test-context-package.json`
 
-## Core Responsibilities
-- Load source session implementation context
-- Analyze current test coverage using MCP tools
-- Identify files requiring test generation
-- Detect test framework and conventions
-- Package test context for analysis phase
+## Execution Flow
 
-## Execution Lifecycle
+### Step 1: Test-Context-Package Detection
 
-### Phase 1: Session Validation & Source Loading
+**Execute First** - Check if valid package already exists:
 
-1. **Test Session Validation**
-   - Load `.workflow/{test_session_id}/workflow-session.json`
-   - Extract `meta.source_session` reference
-   - Validate test session type is "test-gen"
+```javascript
+const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
 
-2. **Source Session Context Loading**
-   - Read `.workflow/{source_session_id}/workflow-session.json`
-   - Load implementation summaries from `.workflow/{source_session_id}/.summaries/`
-   - Extract changed files and implementation scope
-   - Identify implementation patterns and tech stack
+if (file_exists(testContextPath)) {
+  const existing = Read(testContextPath);
 
-### Phase 2: Test Coverage Analysis (MCP Tools)
-
-1. **Existing Test Discovery**
-   ```bash
-   # Find all test files
-   mcp__code-index__find_files(pattern="*.test.*")
-   mcp__code-index__find_files(pattern="*.spec.*")
-   mcp__code-index__find_files(pattern="*test_*.py")
-
-   # Search for test patterns
-   mcp__code-index__search_code_advanced(
-     pattern="describe|it|test|@Test",
-     file_pattern="*.test.*",
-     context_lines=0
-   )
-   ```
-
-2. **Coverage Gap Analysis**
-   ```bash
-   # For each implementation file from source session
-   # Check if corresponding test file exists
-
-   # Example: src/auth/AuthService.ts -> tests/auth/AuthService.test.ts
-   #          src/utils/validator.py -> tests/test_validator.py
-
-   # Output: List of files without tests
-   ```
-
-3. **Test Statistics**
-   - Count total test files
-   - Count implementation files from source session
-   - Calculate coverage percentage
-   - Identify coverage gaps by module
-
-### Phase 3: Test Framework Detection
-
-1. **Framework Identification**
-   ```bash
-   # Check package.json or requirements.txt
-   mcp__code-index__search_code_advanced(
-     pattern="jest|mocha|jasmine|pytest|unittest|rspec",
-     file_pattern="package.json|requirements.txt|Gemfile",
-     context_lines=2
-   )
-
-   # Analyze existing test patterns
-   mcp__code-index__search_code_advanced(
-     pattern="describe\\(|it\\(|test\\(|def test_",
-     file_pattern="*.test.*",
-     context_lines=3
-   )
-   ```
-
-2. **Convention Analysis**
-   - Test file naming patterns (*.test.ts vs *.spec.ts)
-   - Test directory structure (tests/ vs __tests__ vs src/**/*.test.*)
-   - Assertion library (expect, assert, should)
-   - Mocking framework (jest.fn, sinon, unittest.mock)
-
-### Phase 4: Context Packaging
-
-Generate `test-context-package.json`:
-
-```json
-{
-  "metadata": {
-    "test_session_id": "WFS-test-auth",
-    "source_session_id": "WFS-auth",
-    "timestamp": "2025-10-04T10:30:00Z",
-    "task_type": "test-generation",
-    "complexity": "medium"
-  },
-  "source_context": {
-    "implementation_summaries": [
-      {
-        "task_id": "IMPL-001",
-        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
-        "changed_files": [
-          "src/auth/AuthService.ts",
-          "src/auth/TokenValidator.ts",
-          "src/middleware/auth.ts"
-        ],
-        "implementation_type": "feature"
-      }
-    ],
-    "tech_stack": ["typescript", "express", "jsonwebtoken"],
-    "project_patterns": {
-      "architecture": "layered",
-      "error_handling": "try-catch with custom errors",
-      "async_pattern": "async/await"
-    }
-  },
-  "test_coverage": {
-    "existing_tests": [
-      "tests/auth/AuthService.test.ts",
-      "tests/middleware/auth.test.ts"
-    ],
-    "missing_tests": [
-      {
-        "implementation_file": "src/auth/TokenValidator.ts",
-        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
-        "priority": "high",
-        "reason": "New implementation without tests"
-      }
-    ],
-    "coverage_stats": {
-      "total_implementation_files": 3,
-      "files_with_tests": 2,
-      "files_without_tests": 1,
-      "coverage_percentage": 66.7
-    }
-  },
-  "test_framework": {
-    "framework": "jest",
-    "version": "^29.0.0",
-    "test_pattern": "**/*.test.ts",
-    "test_directory": "tests/",
-    "assertion_library": "expect",
-    "mocking_framework": "jest",
-    "conventions": {
-      "file_naming": "*.test.ts",
-      "test_structure": "describe/it blocks",
-      "setup_teardown": "beforeEach/afterEach"
-    }
-  },
-  "assets": [
-    {
-      "type": "implementation_summary",
-      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
-      "relevance": "Source implementation context",
-      "priority": "highest"
-    },
-    {
-      "type": "existing_test",
-      "path": "tests/auth/AuthService.test.ts",
-      "relevance": "Test pattern reference",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/auth/TokenValidator.ts",
-      "relevance": "Implementation requiring tests",
-      "priority": "high"
-    },
-    {
-      "type": "documentation",
-      "path": "CLAUDE.md",
-      "relevance": "Project conventions",
-      "priority": "medium"
-    }
-  ],
-  "focus_areas": [
-    "Generate comprehensive tests for TokenValidator",
-    "Follow existing Jest patterns from AuthService tests",
-    "Cover happy path, error cases, and edge cases",
-    "Include integration tests for middleware"
-  ]
+  // Validate package belongs to current test session
+  if (existing?.metadata?.test_session_id === test_session_id) {
+    console.log("✅ Valid test-context-package found for session:", test_session_id);
+    console.log("📊 Coverage Stats:", existing.test_coverage.coverage_stats);
+    console.log("🧪 Framework:", existing.test_framework.framework);
+    console.log("⚠️  Missing Tests:", existing.test_coverage.missing_tests.length);
+    return existing; // Skip execution, return existing
+  } else {
+    console.warn("⚠️ Invalid test_session_id in existing package, re-generating...");
+  }
 }
 ```
 
-## Output Location
+### Step 2: Invoke Test-Context-Search Agent
 
-```
-.workflow/{test_session_id}/.process/test-context-package.json
-```
+**Only execute if Step 1 finds no valid package**
 
-## MCP Tools Usage
+```javascript
+Task(
+  subagent_type="test-context-search-agent",
+  description="Gather test coverage context",
+  prompt=`
+You are executing as test-context-search-agent (.claude/agents/test-context-search-agent.md).
 
-### File Discovery
-```bash
-# Test files
-mcp__code-index__find_files(pattern="*.test.*")
-mcp__code-index__find_files(pattern="*.spec.*")
+## Execution Mode
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
 
-# Implementation files
-mcp__code-index__find_files(pattern="*.ts")
-mcp__code-index__find_files(pattern="*.js")
-```
+## Session Information
+- **Test Session ID**: ${test_session_id}
+- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json
 
-### Content Search
-```bash
-# Test framework detection
-mcp__code-index__search_code_advanced(
-  pattern="jest|mocha|pytest",
-  file_pattern="package.json|requirements.txt"
-)
+## Mission
+Execute complete test-context-search-agent workflow for test generation planning:
 
-# Test pattern analysis
-mcp__code-index__search_code_advanced(
-  pattern="describe|it|test",
-  file_pattern="*.test.*",
-  context_lines=2
+### Phase 1: Session Validation & Source Context Loading
+1. **Detection**: Check for existing test-context-package (early exit if valid)
+2. **Test Session Validation**: Load test session metadata, extract source_session reference
+3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack
+
+### Phase 2: Test Coverage Analysis
+Execute coverage discovery:
+- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files)
+- **Track 2**: Coverage gap analysis (match implementation files to test files)
+- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module)
+
+### Phase 3: Framework Detection & Packaging
+1. Framework identification from package.json/requirements.txt
+2. Convention analysis from existing test patterns
+3. Generate and validate test-context-package.json
+
+## Output Requirements
+Complete test-context-package.json with:
+- **metadata**: test_session_id, source_session_id, task_type, complexity
+- **source_context**: implementation_summaries, tech_stack, project_patterns
+- **test_coverage**: existing_tests[], missing_tests[], coverage_stats
+- **test_framework**: framework, version, test_pattern, conventions
+- **assets**: implementation_summary[], existing_test[], source_code[] with priorities
+- **focus_areas**: Test generation guidance based on coverage gaps
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] Source session context loaded successfully
+- [ ] Test coverage gaps identified
+- [ ] Test framework detected (or marked as 'unknown')
+- [ ] Coverage percentage calculated correctly
+- [ ] Missing tests catalogued with priority
+- [ ] Execution time < 30 seconds (< 60s for large codebases)
+
+Execute autonomously following agent documentation.
+Report completion with coverage statistics.
+`
 )
 ```
 
-### Coverage Analysis
-```bash
-# For each implementation file
-# Check if test exists
-implementation_file="src/auth/AuthService.ts"
-test_file_patterns=(
-  "tests/auth/AuthService.test.ts"
-  "src/auth/AuthService.test.ts"
-  "src/auth/__tests__/AuthService.test.ts"
-)
+### Step 3: Output Verification
 
-# Search for test file
-for pattern in "${test_file_patterns[@]}"; do
-  if mcp__code-index__find_files(pattern="$pattern") | grep -q .; then
-    echo "✅ Test exists: $pattern"
-    break
-  fi
-done
+After agent completes, verify output:
+
+```javascript
+// Verify file was created
+const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+if (!file_exists(outputPath)) {
+  throw new Error("❌ Agent failed to generate test-context-package.json");
+}
+
+// Load and display summary
+const testContext = Read(outputPath);
+console.log("✅ Test context package generated successfully");
+console.log("📊 Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%");
+console.log("⚠️  Tests to generate:", testContext.test_coverage.missing_tests.length);
 ```
 
+## Parameter Reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) |
+
+## Output Schema
+
+Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema.
+
+**Key Sections**:
+- **metadata**: Test session info, source session reference, complexity
+- **source_context**: Implementation summaries with changed files and tech stack
+- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics
+- **test_framework**: Framework name, version, patterns, conventions
+- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code)
+- **focus_areas**: Test generation guidance based on analysis
+
+## Usage Examples
+
+### Basic Usage
+```bash
+/workflow:tools:test-context-gather --session WFS-test-auth
+```
+
+### Expected Output
+```
+✅ Valid test-context-package found for session: WFS-test-auth
+📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 }
+🧪 Framework: jest
+⚠️  Missing Tests: 1
+```
+
+## Success Criteria
+
+- ✅ Valid test-context-package.json generated in `.workflow/{test_session_id}/.process/`
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified (>90% accuracy)
+- ✅ Test framework detected and documented
+- ✅ Execution completes within 30 seconds (60s for large codebases)
+- ✅ All required schema fields present and valid
+- ✅ Coverage statistics calculated correctly
+- ✅ Agent reports completion with statistics
+
 ## Error Handling
 
 | Error | Cause | Resolution |
 |-------|-------|------------|
+| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate |
 | Source session not found | Invalid source_session reference | Verify test session metadata |
 | No implementation summaries | Source session incomplete | Complete source session first |
-| MCP tools unavailable | MCP not configured | Fallback to bash find/grep |
-| No test framework detected | Missing test dependencies | Request user to specify framework |
-
-## Fallback Strategy (No MCP)
-
-```bash
-# File discovery
-find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
-
-# Framework detection
-grep -r "jest\|mocha\|pytest" package.json requirements.txt 2>/dev/null
-
-# Coverage analysis
-for impl_file in $(cat changed_files.txt); do
-  test_file=$(echo $impl_file | sed 's/src/tests/' | sed 's/\(.*\)\.\(ts\|js\|py\)$/\1.test.\2/')
-  [ ! -f "$test_file" ] && echo "$impl_file → MISSING TEST"
-done
-```
+| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access |
+| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
+| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed |
 
 ## Integration
 
@@ -287,20 +190,18 @@ done
 - `/workflow:test-gen` (Phase 3: Context Gathering)
 
 ### Calls
-- MCP code-index tools for analysis
-- Bash file operations for fallback
+- `test-context-search-agent` - Autonomous test coverage analysis
 
 ### Followed By
-- `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning
 
-## Success Criteria
+## Notes
 
-- ✅ Source session context loaded successfully
-- ✅ Test coverage gaps identified with MCP tools
-- ✅ Test framework detected and documented
-- ✅ Valid test-context-package.json generated
-- ✅ All missing tests catalogued with priority
-- ✅ Execution time < 20 seconds
+- **Detection-first**: Always check for existing test-context-package before invoking agent
+- **Agent autonomy**: Agent handles all coverage analysis logic per `.claude/agents/test-context-search-agent.md`
+- **No redundancy**: This command is a thin orchestrator, all logic in agent
+- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
+- **Coverage focus**: Primary goal is identifying implementation files without tests
 
 ## Related Commands
 

.claude/commands/workflow/tools/test-task-generate.md

@@ -1,6 +1,6 @@
 ---
 name: test-task-generate
-description: Generate test-fix task JSON with iterative test-fix-retest cycle specification
+description: Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex
 argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
 examples:
   - /workflow:tools:test-task-generate --session WFS-test-auth
@@ -146,9 +146,9 @@ Generate **TWO task JSON files**:
         "step": "load_existing_test_patterns",
         "action": "Study existing tests for pattern reference",
         "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "bash(find . -name \"*.test.*\" -type f)",
           "bash(# Read first 2 existing test files as examples)",
-          "bash(test_files=$(mcp__code-index__find_files(pattern=\"*.test.*\") | head -2))",
+          "bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
           "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
         ],
         "output_to": "existing_test_patterns",
@@ -198,7 +198,7 @@ Generate **TWO task JSON files**:
         "Codex generates comprehensive test suite",
         "Codex validates test syntax and executability"
       ],
-      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @{.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md,.workflow/WFS-test-[session]/.process/test-context-package.json} EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
+      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
       "depends_on": [],
       "output": "test_generation"
     }],
@@ -282,11 +282,11 @@ Generate **TWO task JSON files**:
         "step": "analyze_test_coverage",
         "action": "Analyze test coverage and identify missing tests",
         "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
-          "mcp__code-index__search_code_advanced(pattern=\"test|describe|it|def test_\", file_pattern=\"*.test.*\")",
+          "bash(find . -name \"*.test.*\" -type f)",
+          "bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
           "bash(# Count implementation files vs test files)",
           "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
-          "bash(test_count=$(mcp__code-index__find_files(pattern=\"*.test.*\") | wc -l))",
+          "bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))",
           "bash(echo \"Implementation files: $impl_count, Test files: $test_count\")"
         ],
         "output_to": "test_coverage_analysis",
@@ -323,7 +323,7 @@ Generate **TWO task JSON files**:
           "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
           "tools": {
             "test_execution": "bash(test_command)",
-            "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+            "diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
             "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
             "verification": "bash(test_command) + regression_check"
           },
@@ -354,16 +354,16 @@ Generate **TWO task JSON files**:
         "      * Source files from focus_paths",
         "      * Implementation summaries from source session",
         "    - Execute Gemini analysis with bug-fix template:",
-        "      bash(cd .workflow/WFS-test-[session]/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+        "      bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
         "      PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
         "      TASK: Systematic bug analysis and fix recommendations for test failure",
         "      MODE: analysis",
-        "      CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
+        "      CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
         "               Test output: [test_failures]",
         "               Source files: [focus_paths]",
         "               Implementation: [implementation_context]",
         "      EXPECTED: Root cause analysis, code path tracing, targeted fixes",
-        "      RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
+        "      RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Bug: [test_failure_description]",
         "             Minimal surgical fixes only - no refactoring",
         "      \" > fix-iteration-[N]-diagnosis.md)",
         "    - Parse diagnosis → extract fix_suggestion and target_files",
@@ -690,6 +690,6 @@ The `@test-fix-agent` will execute the task by following the `flow_control.imple
 6. **Phase 3**: Generate summary and certify code
 7. **Error Recovery**: Revert changes if max iterations reached
 
-**Bug Diagnosis Template**: Uses bug-fix.md template as referenced in bug-index.md for systematic root cause analysis, code path tracing, and targeted fix recommendations.
+**Bug Diagnosis Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
 
 **Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.

.claude/commands/workflow/ui-design/animation-extract.md

@@ -1,6 +1,6 @@
 ---
 name: animation-extract
-description: Extract animation and transition patterns from URLs, CSS, or interactive questioning
+description: Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation
 argument-hint: "[--base-path <path>] [--session <id>] [--urls "<list>"] [--mode <auto|interactive>] [--focus "<types>"]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
 ---
@@ -170,128 +170,318 @@ ELSE:
     extraction_insufficient = true
 ```
 
-### Step 2: Interactive Question Workflow (Agent)
+### Step 2: Generate Animation Questions (Main Flow)
 
 ```bash
 # If extraction failed or insufficient, use interactive questioning
 IF extraction_insufficient OR extraction_mode == "interactive":
-    REPORT: "🤔 Launching interactive animation specification mode"
+    REPORT: "🤔 Interactive animation specification mode"
+    REPORT: "   Context: {has_design_context ? 'Aligning with design tokens' : 'Standalone animation system'}"
+    REPORT: "   Focus: {focus_types}"
 
-    # Launch ui-design-agent for interactive questioning
-    Task(ui-design-agent): `
-      [ANIMATION_SPECIFICATION_TASK]
-      Guide user through animation design decisions via structured questions
+    # Determine question categories based on focus_types
+    question_categories = []
+    IF "all" IN focus_types OR "transitions" IN focus_types:
+        question_categories.append("timing_scale")
+        question_categories.append("easing_philosophy")
 
-      SESSION: {session_id} | MODE: interactive | BASE_PATH: {base_path}
+    IF "all" IN focus_types OR "interactions" IN focus_types OR "hover" IN focus_types:
+        question_categories.append("button_interactions")
+        question_categories.append("card_interactions")
+        question_categories.append("input_interactions")
 
-      ## Context
-      - Design tokens available: {has_design_context}
-      - Focus areas: {focus_types}
-      - Extracted data: {animations_extracted ? "Partial CSS data available" : "No CSS data"}
+    IF "all" IN focus_types OR "page" IN focus_types:
+        question_categories.append("page_transitions")
 
-      ## Interactive Workflow
+    IF "all" IN focus_types OR "loading" IN focus_types:
+        question_categories.append("loading_states")
 
-      For each animation category, ASK user and WAIT for response:
+    IF "all" IN focus_types OR "scroll" IN focus_types:
+        question_categories.append("scroll_animations")
+```
 
-      ### 1. Transition Duration Scale
-      QUESTION: "What timing scale feels right for your design?"
-      OPTIONS:
-        - "Fast & Snappy" (100-200ms transitions)
-        - "Balanced" (200-400ms transitions)
-        - "Smooth & Deliberate" (400-600ms transitions)
-        - "Custom" (specify values)
+### Step 3: Output Questions in Text Format (Main Flow)
 
-      ### 2. Easing Philosophy
-      QUESTION: "What easing style matches your brand?"
-      OPTIONS:
-        - "Linear" (constant speed, technical feel)
-        - "Ease-Out" (fast start, natural feel)
-        - "Ease-In-Out" (balanced, polished feel)
-        - "Spring/Bounce" (playful, modern feel)
-        - "Custom" (specify cubic-bezier)
+```markdown
+# Generate and output structured questions
+REPORT: ""
+REPORT: "===== 动画规格交互式配置 ====="
+REPORT: ""
 
-      ### 3. Common Interactions (Ask for each)
-      FOR interaction IN ["button-hover", "link-hover", "card-hover", "modal-open", "dropdown-toggle"]:
-        QUESTION: "How should {interaction} animate?"
-        OPTIONS:
-          - "Subtle" (color/opacity change only)
-          - "Lift" (scale + shadow increase)
-          - "Slide" (transform translateY)
-          - "Fade" (opacity transition)
-          - "None" (no animation)
-          - "Custom" (describe behavior)
+question_number = 1
+questions_output = []
 
-      ### 4. Page Transitions
-      QUESTION: "Should page/route changes have animations?"
-      IF YES:
-        ASK: "What style?"
-        OPTIONS:
-          - "Fade" (crossfade between views)
-          - "Slide" (swipe left/right)
-          - "Zoom" (scale in/out)
-          - "None"
+# Q1: Timing Scale (if included)
+IF "timing_scale" IN question_categories:
+    REPORT: "【问题{question_number} - 时间尺度】您的设计需要什么样的过渡速度？"
+    REPORT: "a) 快速敏捷"
+    REPORT: "   说明：100-200ms 过渡，适合工具型应用和即时反馈场景"
+    REPORT: "b) 平衡适中"
+    REPORT: "   说明：200-400ms 过渡，通用选择，符合多数用户预期"
+    REPORT: "c) 流畅舒缓"
+    REPORT: "   说明：400-600ms 过渡，适合品牌展示和沉浸式体验"
+    REPORT: "d) 自定义"
+    REPORT: "   说明：需要指定具体数值和使用场景"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "timing_scale", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ### 5. Loading States
-      QUESTION: "What loading animation style?"
-      OPTIONS:
-        - "Spinner" (rotating circle)
-        - "Pulse" (opacity pulse)
-        - "Skeleton" (shimmer effect)
-        - "Progress Bar" (linear fill)
-        - "Custom" (describe)
+# Q2: Easing Philosophy (if included)
+IF "easing_philosophy" IN question_categories:
+    REPORT: "【问题{question_number} - 缓动风格】哪种缓动曲线符合您的品牌调性？"
+    REPORT: "a) 线性匀速"
+    REPORT: "   说明：恒定速度，技术感和精确性，适合数据可视化"
+    REPORT: "b) 快入慢出"
+    REPORT: "   说明：快速启动自然减速，最接近物理世界，通用推荐"
+    REPORT: "c) 慢入慢出"
+    REPORT: "   说明：平滑对称，精致优雅，适合高端品牌"
+    REPORT: "d) 弹性效果"
+    REPORT: "   说明：Spring/Bounce 回弹，活泼现代，适合互动性强的应用"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "easing_philosophy", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ### 6. Micro-interactions
-      QUESTION: "Should form inputs have micro-interactions?"
-      IF YES:
-        ASK: "What interactions?"
-        OPTIONS:
-          - "Focus state animation" (border/shadow transition)
-          - "Error shake" (horizontal shake on error)
-          - "Success check" (checkmark animation)
-          - "All of the above"
+# Q3-5: Interaction Animations (button, card, input - if included)
+IF "button_interactions" IN question_categories:
+    REPORT: "【问题{question_number} - 按钮交互】按钮悬停/点击时如何反馈？"
+    REPORT: "a) 微妙变化"
+    REPORT: "   说明：仅颜色/透明度变化，适合简约设计"
+    REPORT: "b) 抬升效果"
+    REPORT: "   说明：轻微缩放+阴影加深，增强物理感知"
+    REPORT: "c) 滑动移位"
+    REPORT: "   说明：Transform translateY，视觉引导明显"
+    REPORT: "d) 无动画"
+    REPORT: "   说明：静态交互，性能优先或特定品牌要求"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "button_interactions", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ### 7. Scroll Animations
-      QUESTION: "Should elements animate on scroll?"
-      IF YES:
-        ASK: "What scroll animation style?"
-        OPTIONS:
-          - "Fade In" (opacity 0→1)
-          - "Slide Up" (translateY + fade)
-          - "Scale In" (scale 0.9→1 + fade)
-          - "Stagger" (sequential delays)
-          - "None"
+IF "card_interactions" IN question_categories:
+    REPORT: "【问题{question_number} - 卡片交互】卡片悬停时的动画效果？"
+    REPORT: "a) 阴影加深"
+    REPORT: "   说明：Box-shadow 变化，层次感增强"
+    REPORT: "b) 上浮效果"
+    REPORT: "   说明：Transform translateY(-4px)，明显的空间层次"
+    REPORT: "c) 缩放放大"
+    REPORT: "   说明：Scale(1.02)，突出焦点内容"
+    REPORT: "d) 无动画"
+    REPORT: "   说明：静态卡片，性能或设计考量"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "card_interactions", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      ## Output Generation
+IF "input_interactions" IN question_categories:
+    REPORT: "【问题{question_number} - 表单交互】输入框是否需要微交互反馈？"
+    REPORT: "a) 聚焦动画"
+    REPORT: "   说明：边框/阴影过渡，清晰的状态指示"
+    REPORT: "b) 错误抖动"
+    REPORT: "   说明：水平shake动画，错误提示更明显"
+    REPORT: "c) 成功勾选"
+    REPORT: "   说明：Checkmark 动画，完成反馈"
+    REPORT: "d) 全部包含"
+    REPORT: "   说明：聚焦+错误+成功的完整反馈体系"
+    REPORT: "e) 无微交互"
+    REPORT: "   说明：标准表单，无额外动画"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "input_interactions", options: ["a", "b", "c", "d", "e"]})
+    question_number += 1
 
-      Based on user responses, generate structured data:
+# Q6: Page Transitions (if included)
+IF "page_transitions" IN question_categories:
+    REPORT: "【问题{question_number} - 页面过渡】页面/路由切换是否需要过渡动画？"
+    REPORT: "a) 淡入淡出"
+    REPORT: "   说明：Crossfade 效果，平滑过渡不突兀"
+    REPORT: "b) 滑动切换"
+    REPORT: "   说明：Swipe left/right，方向性导航"
+    REPORT: "c) 缩放过渡"
+    REPORT: "   说明：Scale in/out，空间层次感"
+    REPORT: "d) 无过渡"
+    REPORT: "   说明：即时切换，性能优先"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "page_transitions", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      1. Create animation-specification.json with user choices:
-         - timing_scale (fast/balanced/slow/custom)
-         - easing_philosophy (linear/ease-out/ease-in-out/spring)
-         - interactions: {interaction_name: {type, properties, timing}}
-         - page_transitions: {enabled, style, duration}
-         - loading_animations: {style, duration}
-         - scroll_animations: {enabled, style, stagger_delay}
+# Q7: Loading States (if included)
+IF "loading_states" IN question_categories:
+    REPORT: "【问题{question_number} - 加载状态】加载时使用何种动画风格？"
+    REPORT: "a) 旋转加载器"
+    REPORT: "   说明：Spinner 圆形旋转，通用加载指示"
+    REPORT: "b) 脉冲闪烁"
+    REPORT: "   说明：Opacity pulse，轻量级反馈"
+    REPORT: "c) 骨架屏"
+    REPORT: "   说明：Shimmer effect，内容占位预览"
+    REPORT: "d) 进度条"
+    REPORT: "   说明：Linear fill，进度量化展示"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "loading_states", options: ["a", "b", "c", "d"]})
+    question_number += 1
 
-      2. Write to {base_path}/.intermediates/animation-analysis/animation-specification.json
+# Q8: Scroll Animations (if included)
+IF "scroll_animations" IN question_categories:
+    REPORT: "【问题{question_number} - 滚动动画】元素是否在滚动时触发动画？"
+    REPORT: "a) 淡入出现"
+    REPORT: "   说明：Opacity 0→1，渐进式内容呈现"
+    REPORT: "b) 上滑出现"
+    REPORT: "   说明：TranslateY + fade，方向性引导"
+    REPORT: "c) 缩放淡入"
+    REPORT: "   说明：Scale 0.9→1 + fade，聚焦效果"
+    REPORT: "d) 交错延迟"
+    REPORT: "   说明：Stagger 序列动画，列表渐次呈现"
+    REPORT: "e) 无滚动动画"
+    REPORT: "   说明：静态内容，性能或可访问性考量"
+    REPORT: ""
+    questions_output.append({id: question_number, category: "scroll_animations", options: ["a", "b", "c", "d", "e"]})
+    question_number += 1
 
-      ## Critical Requirements
-      - ✅ Use Write() tool immediately for specification file
-      - ✅ Wait for user response after EACH question before proceeding
-      - ✅ Validate responses and ask for clarification if needed
-      - ✅ Provide sensible defaults if user skips questions
-      - ❌ NO external research or MCP calls
-    `
+REPORT: "支持格式："
+REPORT: "- 空格分隔：1a 2b 3c"
+REPORT: "- 逗号分隔：1a,2b,3c"
+REPORT: "- 自由组合：1a 2b,3c"
+REPORT: ""
+REPORT: "请输入您的选择："
+```
+
+### Step 4: Wait for User Input (Main Flow)
+
+```javascript
+# Wait for user input
+user_raw_input = WAIT_FOR_USER_INPUT()
+
+# Store raw input for debugging
+REPORT: "收到输入: {user_raw_input}"
+```
+
+### Step 5: Parse User Answers (Main Flow)
+
+```javascript
+# Intelligent input parsing (support multiple formats)
+answers = {}
+
+# Parse input using intelligent matching
+# Support formats: "1a 2b 3c", "1a,2b,3c", "1a 2b,3c"
+parsed_responses = PARSE_USER_INPUT(user_raw_input, questions_output)
+
+# Validate parsing
+IF parsed_responses.is_valid:
+    # Map question numbers to categories
+    FOR response IN parsed_responses.answers:
+        question_id = response.question_id
+        selected_option = response.option
+
+        # Find category for this question
+        FOR question IN questions_output:
+            IF question.id == question_id:
+                category = question.category
+                answers[category] = selected_option
+                REPORT: "✅ 问题{question_id} ({category}): 选择 {selected_option}"
+                break
+ELSE:
+    REPORT: "❌ 输入格式无法识别，请参考格式示例重新输入："
+    REPORT: "   示例：1a 2b 3c 4d"
+    # Return to Step 3 for re-input
+    GOTO Step 3
+```
+
+### Step 6: Write Animation Specification (Main Flow)
+
+```javascript
+# Map user choices to specification structure
+specification = {
+    "metadata": {
+        "source": "interactive",
+        "timestamp": NOW(),
+        "focus_types": focus_types,
+        "has_design_context": has_design_context
+    },
+    "timing_scale": MAP_TIMING_SCALE(answers.timing_scale),
+    "easing_philosophy": MAP_EASING_PHILOSOPHY(answers.easing_philosophy),
+    "interactions": {
+        "button": MAP_BUTTON_INTERACTION(answers.button_interactions),
+        "card": MAP_CARD_INTERACTION(answers.card_interactions),
+        "input": MAP_INPUT_INTERACTION(answers.input_interactions)
+    },
+    "page_transitions": MAP_PAGE_TRANSITIONS(answers.page_transitions),
+    "loading_animations": MAP_LOADING_STATES(answers.loading_states),
+    "scroll_animations": MAP_SCROLL_ANIMATIONS(answers.scroll_animations)
+}
+
+# Mapping functions (inline logic)
+FUNCTION MAP_TIMING_SCALE(option):
+    SWITCH option:
+        CASE "a": RETURN {scale: "fast", base_duration: "150ms", range: "100-200ms"}
+        CASE "b": RETURN {scale: "balanced", base_duration: "300ms", range: "200-400ms"}
+        CASE "c": RETURN {scale: "smooth", base_duration: "500ms", range: "400-600ms"}
+        CASE "d": RETURN {scale: "custom", base_duration: "300ms", note: "User to provide values"}
+
+FUNCTION MAP_EASING_PHILOSOPHY(option):
+    SWITCH option:
+        CASE "a": RETURN {style: "linear", curve: "linear"}
+        CASE "b": RETURN {style: "ease-out", curve: "cubic-bezier(0, 0, 0.2, 1)"}
+        CASE "c": RETURN {style: "ease-in-out", curve: "cubic-bezier(0.4, 0, 0.2, 1)"}
+        CASE "d": RETURN {style: "spring", curve: "cubic-bezier(0.34, 1.56, 0.64, 1)"}
+
+FUNCTION MAP_BUTTON_INTERACTION(option):
+    SWITCH option:
+        CASE "a": RETURN {type: "subtle", properties: ["color", "background-color", "opacity"]}
+        CASE "b": RETURN {type: "lift", properties: ["transform", "box-shadow"], transform: "scale(1.02)"}
+        CASE "c": RETURN {type: "slide", properties: ["transform"], transform: "translateY(-2px)"}
+        CASE "d": RETURN {type: "none", properties: []}
+
+FUNCTION MAP_CARD_INTERACTION(option):
+    SWITCH option:
+        CASE "a": RETURN {type: "shadow", properties: ["box-shadow"]}
+        CASE "b": RETURN {type: "float", properties: ["transform", "box-shadow"], transform: "translateY(-4px)"}
+        CASE "c": RETURN {type: "scale", properties: ["transform"], transform: "scale(1.02)"}
+        CASE "d": RETURN {type: "none", properties: []}
+
+FUNCTION MAP_INPUT_INTERACTION(option):
+    SWITCH option:
+        CASE "a": RETURN {enabled: ["focus"], focus: {properties: ["border-color", "box-shadow"]}}
+        CASE "b": RETURN {enabled: ["error"], error: {animation: "shake", keyframes: "translateX"}}
+        CASE "c": RETURN {enabled: ["success"], success: {animation: "checkmark", keyframes: "draw"}}
+        CASE "d": RETURN {enabled: ["focus", "error", "success"]}
+        CASE "e": RETURN {enabled: []}
+
+FUNCTION MAP_PAGE_TRANSITIONS(option):
+    SWITCH option:
+        CASE "a": RETURN {enabled: true, style: "fade", animation: "fadeIn/fadeOut"}
+        CASE "b": RETURN {enabled: true, style: "slide", animation: "slideLeft/slideRight"}
+        CASE "c": RETURN {enabled: true, style: "zoom", animation: "zoomIn/zoomOut"}
+        CASE "d": RETURN {enabled: false}
+
+FUNCTION MAP_LOADING_STATES(option):
+    SWITCH option:
+        CASE "a": RETURN {style: "spinner", animation: "rotate", keyframes: "360deg"}
+        CASE "b": RETURN {style: "pulse", animation: "pulse", keyframes: "opacity"}
+        CASE "c": RETURN {style: "skeleton", animation: "shimmer", keyframes: "gradient-shift"}
+        CASE "d": RETURN {style: "progress", animation: "fill", keyframes: "width"}
+
+FUNCTION MAP_SCROLL_ANIMATIONS(option):
+    SWITCH option:
+        CASE "a": RETURN {enabled: true, style: "fade", animation: "fadeIn"}
+        CASE "b": RETURN {enabled: true, style: "slideUp", animation: "slideUp", transform: "translateY(20px)"}
+        CASE "c": RETURN {enabled: true, style: "scaleIn", animation: "scaleIn", transform: "scale(0.9)"}
+        CASE "d": RETURN {enabled: true, style: "stagger", animation: "fadeIn", stagger_delay: "100ms"}
+        CASE "e": RETURN {enabled: false}
+
+# Write specification file
+output_path = "{base_path}/.intermediates/animation-analysis/animation-specification.json"
+Write(output_path, JSON.stringify(specification, indent=2))
+
+REPORT: "✅ Animation specification saved to {output_path}"
+REPORT: "   Proceeding to token synthesis..."
 ```
 
 ---
 
 **Phase 2 Output**: `animation-specification.json` (user preferences)
 
-## Phase 3: Animation Token Synthesis (Agent)
+## Phase 3: Animation Token Synthesis (Agent - No User Interaction)
 
 **Executor**: `Task(ui-design-agent)` for token generation
 
+**⚠️ CRITICAL**: This phase has NO user interaction. Agent only reads existing data and generates tokens.
+
 ### Step 1: Load All Input Sources
 
 ```bash
@@ -305,61 +495,96 @@ IF animations_extracted:
 user_specification = null
 IF exists({base_path}/.intermediates/animation-analysis/animation-specification.json):
     user_specification = Read(file)
+    REPORT: "✅ Loaded user specification from Phase 2"
+ELSE:
+    REPORT: "⚠️ No user specification found - using extracted CSS only"
 
 design_tokens = null
 IF has_design_context:
     design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
 ```
 
-### Step 2: Launch Token Generation Task
+### Step 2: Launch Token Generation Task (Pure Synthesis)
 
 ```javascript
 Task(ui-design-agent): `
   [ANIMATION_TOKEN_GENERATION_TASK]
-  Synthesize all animation data into production-ready animation tokens
+  Synthesize animation data into production-ready tokens - NO user interaction
 
   SESSION: {session_id} | BASE_PATH: {base_path}
 
-  ## Input Sources
-  1. Extracted CSS Animations: {JSON.stringify(extracted_animations) OR "None"}
-  2. User Specification: {JSON.stringify(user_specification) OR "None"}
-  3. Design Tokens Context: {JSON.stringify(design_tokens) OR "None"}
+  ## ⚠️ CRITICAL: Pure Synthesis Task
+  - NO user questions or interaction
+  - READ existing specification files ONLY
+  - Generate tokens based on available data
+
+  ## Input Sources (Read-Only)
+  1. **Extracted CSS Animations** (if available):
+     ${extracted_animations.length > 0 ? JSON.stringify(extracted_animations) : "None - skip CSS data"}
+
+  2. **User Specification** (REQUIRED if Phase 2 ran):
+     File: {base_path}/.intermediates/animation-analysis/animation-specification.json
+     ${user_specification ? "Status: ✅ Found - READ this file for user choices" : "Status: ⚠️ Not found - use CSS extraction only"}
+
+  3. **Design Tokens Context** (for alignment):
+     ${design_tokens ? JSON.stringify(design_tokens) : "None - standalone animation system"}
 
   ## Synthesis Rules
 
   ### Priority System
-  1. User specification (highest priority)
-  2. Extracted CSS values (medium priority)
+  1. User specification from animation-specification.json (highest priority)
+  2. Extracted CSS values from animations-*.json (medium priority)
   3. Industry best practices (fallback)
 
   ### Duration Normalization
-  - Analyze all extracted durations
-  - Cluster into 3-5 semantic scales: instant, fast, normal, slow, very-slow
+  - IF user_specification.timing_scale EXISTS:
+      Use user's chosen scale (fast/balanced/smooth/custom)
+  - ELSE IF extracted CSS durations available:
+      Cluster extracted durations into 3-5 semantic scales
+  - ELSE:
+      Use standard scale (instant:0ms, fast:150ms, normal:300ms, slow:500ms, very-slow:800ms)
   - Align with design token spacing scale if available
 
   ### Easing Standardization
-  - Identify common easing functions from extracted data
-  - Map to semantic names: linear, ease-in, ease-out, ease-in-out, spring
-  - Convert all cubic-bezier values to standard format
+  - IF user_specification.easing_philosophy EXISTS:
+      Use user's chosen philosophy (linear/ease-out/ease-in-out/spring)
+  - ELSE IF extracted CSS easings available:
+      Identify common easing functions from CSS
+  - ELSE:
+      Use standard easings
+  - Map to semantic names and convert to cubic-bezier format
 
   ### Animation Categorization
   Organize into:
-  - transitions: Property-specific transitions (color, transform, opacity)
-  - keyframe_animations: Named @keyframe animations
-  - interactions: Interaction-specific presets (hover, focus, active)
-  - micro_interactions: Small feedback animations
-  - page_transitions: Route/view change animations
-  - scroll_animations: Scroll-triggered animations
+  - **duration**: Timing scale (instant, fast, normal, slow, very-slow)
+  - **easing**: Easing functions (linear, ease-in, ease-out, ease-in-out, spring)
+  - **transitions**: Property-specific transitions (color, transform, opacity, etc.)
+  - **keyframes**: Named @keyframe animations (fadeIn, slideInUp, pulse, etc.)
+  - **interactions**: Interaction-specific presets (button-hover, card-hover, input-focus, etc.)
+  - **page_transitions**: Route/view change animations (if user enabled)
+  - **scroll_animations**: Scroll-triggered animations (if user enabled)
+
+  ### User Specification Integration
+  IF user_specification EXISTS:
+    - Map user choices to token values:
+      * timing_scale → duration values
+      * easing_philosophy → easing curves
+      * interactions.button → interactions.button-hover token
+      * interactions.card → interactions.card-hover token
+      * interactions.input → micro-interaction tokens
+      * page_transitions → page_transitions tokens
+      * loading_animations → loading state tokens
+      * scroll_animations → scroll_animations tokens
 
   ## Generate Files
 
   ### 1. animation-tokens.json
-  Complete animation token structure:
+  Complete animation token structure using var() references:
 
   {
     "duration": {
       "instant": "0ms",
-      "fast": "150ms",
+      "fast": "150ms",      # Adjust based on user_specification.timing_scale
       "normal": "300ms",
       "slow": "500ms",
       "very-slow": "800ms"
@@ -367,7 +592,7 @@ Task(ui-design-agent): `
     "easing": {
       "linear": "linear",
       "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
-      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",      # Adjust based on user_specification.easing_philosophy
       "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
       "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
     },
@@ -389,66 +614,74 @@ Task(ui-design-agent): `
       }
     },
     "keyframes": {
-      "fadeIn": {
-        "0%": {"opacity": "0"},
-        "100%": {"opacity": "1"}
-      },
-      "slideInUp": {
-        "0%": {"transform": "translateY(20px)", "opacity": "0"},
-        "100%": {"transform": "translateY(0)", "opacity": "1"}
-      },
-      "pulse": {
-        "0%, 100%": {"opacity": "1"},
-        "50%": {"opacity": "0.7"}
-      }
+      "fadeIn": {"0%": {"opacity": "0"}, "100%": {"opacity": "1"}},
+      "slideInUp": {"0%": {"transform": "translateY(20px)", "opacity": "0"}, "100%": {"transform": "translateY(0)", "opacity": "1"}},
+      "pulse": {"0%, 100%": {"opacity": "1"}, "50%": {"opacity": "0.7"}},
+      # Add more keyframes based on user_specification choices
     },
     "interactions": {
       "button-hover": {
+        # Map from user_specification.interactions.button
         "properties": ["background-color", "transform"],
         "duration": "var(--duration-fast)",
         "easing": "var(--easing-ease-out)",
         "transform": "scale(1.02)"
       },
       "card-hover": {
+        # Map from user_specification.interactions.card
         "properties": ["box-shadow", "transform"],
         "duration": "var(--duration-normal)",
         "easing": "var(--easing-ease-out)",
         "transform": "translateY(-4px)"
       }
+      # Add input-focus, modal-open, dropdown-toggle based on user choices
     },
     "page_transitions": {
+      # IF user_specification.page_transitions.enabled == true
       "fade": {
         "duration": "var(--duration-normal)",
         "enter": "fadeIn",
         "exit": "fadeOut"
       }
+      # Add slide, zoom based on user_specification.page_transitions.style
     },
     "scroll_animations": {
+      # IF user_specification.scroll_animations.enabled == true
       "default": {
-        "animation": "fadeInUp",
+        "animation": "fadeIn",  # From user_specification.scroll_animations.style
         "duration": "var(--duration-slow)",
         "easing": "var(--easing-ease-out)",
         "threshold": "0.1",
-        "stagger_delay": "100ms"
+        "stagger_delay": "100ms"  # From user_specification if stagger chosen
       }
     }
   }
 
   ### 2. animation-guide.md
-  Comprehensive usage guide:
-  - Animation philosophy and rationale
-  - Duration scale explanation
-  - Easing function usage guidelines
-  - Interaction animation patterns
-  - Implementation examples (CSS and JS)
-  - Accessibility considerations (prefers-reduced-motion)
-  - Performance best practices
+  Comprehensive usage guide with sections:
+  - **Animation Philosophy**: Rationale from user choices and CSS analysis
+  - **Duration Scale**: Explanation of timing values and usage contexts
+  - **Easing Functions**: When to use each easing curve
+  - **Transition Presets**: Property-specific transition guidelines
+  - **Keyframe Animations**: Available animations and use cases
+  - **Interaction Patterns**: Button, card, input animation examples
+  - **Page Transitions**: Route change animation implementation (if enabled)
+  - **Scroll Animations**: Scroll-trigger setup and configuration (if enabled)
+  - **Implementation Examples**: CSS and JavaScript code samples
+  - **Accessibility**: prefers-reduced-motion media query setup
+  - **Performance Best Practices**: Hardware acceleration, will-change usage
+
+  ## Output File Paths
+  - animation-tokens.json: {base_path}/animation-extraction/animation-tokens.json
+  - animation-guide.md: {base_path}/animation-extraction/animation-guide.md
 
   ## Critical Requirements
+  - ✅ READ animation-specification.json if it exists (from Phase 2)
   - ✅ Use Write() tool immediately for both files
-  - ✅ Ensure all tokens use CSS Custom Property format: var(--duration-fast)
+  - ✅ All tokens use CSS Custom Property format: var(--duration-fast)
   - ✅ Include prefers-reduced-motion media query guidance
-  - ✅ Validate all cubic-bezier values are valid
+  - ✅ Validate all cubic-bezier values are valid (4 numbers between 0-1)
+  - ❌ NO user questions or interaction in this phase
   - ❌ NO external research or MCP calls
 `
 ```
@@ -487,8 +720,8 @@ bash(ls -lh {base_path}/animation-extraction/)
 TodoWrite({todos: [
   {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
   {content: "CSS animation extraction (auto mode)", status: "completed", activeForm: "Extracting from CSS"},
-  {content: "Interactive specification (fallback)", status: "completed", activeForm: "Collecting user input"},
-  {content: "Animation token synthesis (agent)", status: "completed", activeForm: "Generating tokens"},
+  {content: "Interactive specification (main flow)", status: "completed", activeForm: "Collecting user input in main flow"},
+  {content: "Animation token synthesis (agent - no interaction)", status: "completed", activeForm: "Generating tokens via agent"},
   {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
 ]});
 ```
@@ -506,7 +739,7 @@ Configuration:
   - ✅ CSS extracted from {len(url_list)} URL(s)
   }
   {IF user_specification:
-  - ✅ User specification via interactive mode
+  - ✅ User specification via interactive mode (main flow)
   }
   {IF has_design_context:
   - ✅ Aligned with existing design tokens
@@ -652,11 +885,12 @@ ERROR: Invalid cubic-bezier values
 
 - **Auto-Trigger CSS Extraction** - Automatically extracts animations when --urls provided
 - **Hybrid Strategy** - Combines CSS extraction with interactive specification
+- **Main Flow Interaction** - User questions in main flow, agent only for token synthesis
 - **Intelligent Fallback** - Gracefully handles extraction failures
 - **Context-Aware** - Aligns with existing design tokens
 - **Production-Ready** - CSS var() format, accessibility support
 - **Comprehensive Coverage** - Transitions, keyframes, interactions, scroll animations
-- **Agent-Driven** - Autonomous token generation with ui-design-agent
+- **Separated Concerns** - User decisions (Phase 2 main flow) → Token generation (Phase 3 agent)
 
 ## Integration
 

.claude/commands/workflow/ui-design/batch-generate.md

@@ -1,6 +1,6 @@
 ---
 name: batch-generate
-description: Prompt-driven batch UI generation using target-style-centric parallel execution
+description: Prompt-driven batch UI generation using target-style-centric parallel execution with design token application
 argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
 ---
@@ -129,7 +129,10 @@ Task(ui-design-agent): `
   ## Reference
   - Layout inspiration: Read("{base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt")
   - Design tokens: Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-    Parse ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+    Parse ALL token values including:
+    * colors, typography (with combinations), spacing, opacity
+    * border_radius, shadows, breakpoints
+    * component_styles (button, card, input variants)
   ${design_attributes ? "- Adapt DOM to: density, visual_weight, formality, organic_vs_geometric" : ""}
 
   ## Generation
@@ -152,14 +155,16 @@ Task(ui-design-agent): `
 
   2. CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
      - Self-contained: Direct token VALUES (no var())
-     - Use tokens: colors, fonts, spacing, borders, shadows
+     - Use tokens: colors, fonts, spacing, opacity, borders, shadows
+     - IF tokens.component_styles exists: Use component presets for buttons, cards, inputs
+     - IF tokens.typography.combinations exists: Use typography presets for headings and body text
      - Device-optimized: {device_type} styles
      ${device_type === 'responsive' ? '- Responsive: Mobile-first @media' : '- Fixed: ' + device_type}
      ${design_attributes ? `
      - Token selection: density → spacing, visual_weight → shadows` : ""}
 
   ## Notes
-  - ✅ Token VALUES directly from design-tokens.json
+  - ✅ Token VALUES directly from design-tokens.json (with typography.combinations, opacity, component_styles support)
   - ✅ Follow prompt requirements for {target}
   - ✅ Optimize for {device_type}
   - ❌ NO var() refs, NO external deps

.claude/commands/workflow/ui-design/capture.md

@@ -1,6 +1,6 @@
 ---
 name: capture
-description: Batch screenshot capture for UI design workflows using MCP or local fallback
+description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping
 argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
 ---

.claude/commands/workflow/ui-design/explore-auto.md

@@ -1,6 +1,6 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow with style-centric batch generation
+description: Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution
 argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
@@ -107,7 +107,43 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 ## 6-Phase Execution
 
-### Phase 0a: Intelligent Prompt Parsing
+### Phase 0a: Intelligent Path Detection & Source Selection
+```bash
+# Step 1: Detect if prompt/images contain existing file paths
+code_files_detected = false
+code_base_path = null
+has_visual_input = false
+
+IF --prompt:
+    # Extract potential file paths from prompt
+    potential_paths = extract_paths_from_text(--prompt)
+    FOR path IN potential_paths:
+        IF file_or_directory_exists(path):
+            code_files_detected = true
+            code_base_path = path
+            BREAK
+
+IF --images:
+    # Check if images parameter points to existing files
+    IF glob_matches_files(--images):
+        has_visual_input = true
+
+# Step 2: Determine design source strategy
+design_source = "unknown"
+IF code_files_detected AND has_visual_input:
+    design_source = "hybrid"  # Both code and visual
+ELSE IF code_files_detected:
+    design_source = "code_only"  # Only code files
+ELSE IF has_visual_input OR --prompt:
+    design_source = "visual_only"  # Only visual/prompt
+ELSE:
+    ERROR: "No design source provided (code files, images, or prompt required)"
+    EXIT 1
+
+STORE: design_source, code_base_path, has_visual_input
+```
+
+### Phase 0a-2: Intelligent Prompt Parsing
 ```bash
 # Parse variant counts from prompt or use explicit/default values
 IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
@@ -205,7 +241,7 @@ ELSE IF --prompt:
     target_source = "prompt_analysis"
 
 # Step 4: Session synthesis
-ELSE IF --session AND exists(synthesis-specification.md):
+ELSE IF --session AND exists(role analysis documents):
     target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
 
 # Step 5: Fallback
@@ -267,29 +303,101 @@ detect_target_type(target_list):
     RETURN "component" IF component_matches > page_matches ELSE "page"
 ```
 
-### Phase 1: Style Extraction
+### Phase 0d: Code Import & Completeness Assessment (Conditional)
 ```bash
-command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
-          (--images ? "--images \"{images}\" " : "") +
-          (--prompt ? "--prompt \"{prompt}\" " : "") +
-          "--mode explore --variants {style_variants}"
-SlashCommand(command)
+IF design_source IN ["code_only", "hybrid"]:
+    REPORT: "🔍 Phase 0d: Code Import ({design_source})"
+    command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" --base-path \"{code_base_path}\""
+    SlashCommand(command)
 
-# Output: {style_variants} style cards with design_attributes
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue)
+    # Check file existence and assess completeness
+    style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
+    animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
+    layout_exists = exists("{base_path}/layout-extraction/layout-templates.json")
+
+    style_complete = false
+    animation_complete = false
+    layout_complete = false
+    missing_categories = []
+
+    # Style completeness check
+    IF style_exists:
+        tokens = Read("{base_path}/style-extraction/style-1/design-tokens.json")
+        style_complete = (
+            tokens.colors?.brand && tokens.colors?.surface &&
+            tokens.typography?.font_family && tokens.spacing &&
+            Object.keys(tokens.colors.brand || {}).length >= 3 &&
+            Object.keys(tokens.spacing || {}).length >= 8
+        )
+        IF NOT style_complete AND tokens._metadata?.completeness?.missing_categories:
+            missing_categories.extend(tokens._metadata.completeness.missing_categories)
+    ELSE:
+        missing_categories.push("style tokens")
+
+    # Animation completeness check
+    IF animation_exists:
+        anim = Read("{base_path}/animation-extraction/animation-tokens.json")
+        animation_complete = (
+            anim.duration && anim.easing &&
+            Object.keys(anim.duration || {}).length >= 3 &&
+            Object.keys(anim.easing || {}).length >= 3
+        )
+        IF NOT animation_complete AND anim._metadata?.completeness?.missing_items:
+            missing_categories.extend(anim._metadata.completeness.missing_items)
+    ELSE:
+        missing_categories.push("animation tokens")
+
+    # Layout completeness check
+    IF layout_exists:
+        layouts = Read("{base_path}/layout-extraction/layout-templates.json")
+        layout_complete = (
+            layouts.layout_templates?.length >= 3 &&
+            layouts.extraction_metadata?.layout_system?.type &&
+            layouts.extraction_metadata?.responsive?.breakpoints
+        )
+        IF NOT layout_complete AND layouts.extraction_metadata?.completeness?.missing_items:
+            missing_categories.extend(layouts.extraction_metadata.completeness.missing_items)
+    ELSE:
+        missing_categories.push("layout templates")
+
+    needs_visual_supplement = false
+
+    IF design_source == "code_only" AND NOT (style_complete AND layout_complete):
+        REPORT: "⚠️  Missing: {', '.join(missing_categories)}"
+        REPORT: "Options: 'continue' | 'supplement: <images>' | 'cancel'"
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+            "continue" → needs_visual_supplement = false
+            "supplement: ..." → needs_visual_supplement = true; --images = extract_path(user_response)
+            "cancel" → EXIT 0
+            default → needs_visual_supplement = false
+    ELSE IF design_source == "hybrid":
+        needs_visual_supplement = true
+
+    STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete
 ```
 
-### Phase 2.3: Animation Extraction (Optional - Interactive Mode)
+### Phase 1: Style Extraction
 ```bash
-# Animation extraction for motion design patterns
-REPORT: "🚀 Phase 2.3: Animation Extraction (interactive mode)"
-REPORT: "   → Mode: Interactive specification"
-REPORT: "   → Purpose: Define motion design patterns"
+IF design_source == "visual_only" OR needs_visual_supplement:
+    REPORT: "🎨 Phase 1: Style Extraction (variants: {style_variants})"
+    command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
+              (--images ? "--images \"{images}\" " : "") +
+              (--prompt ? "--prompt \"{prompt}\" " : "") +
+              "--mode explore --variants {style_variants}"
+    SlashCommand(command)
+ELSE:
+    REPORT: "✅ Phase 1: Style (Using Code Import)"
+```
 
-command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
-
-SlashCommand(command)
+### Phase 2.3: Animation Extraction
+```bash
+IF design_source == "visual_only" OR NOT animation_complete:
+    REPORT: "🚀 Phase 2.3: Animation Extraction"
+    command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
+    SlashCommand(command)
+ELSE:
+    REPORT: "✅ Phase 2.3: Animation (Using Code Import)"
 
 # Output: animation-tokens.json + animation-guide.md
 # SlashCommand blocks until phase complete
@@ -299,23 +407,16 @@ SlashCommand(command)
 ### Phase 2.5: Layout Extraction
 ```bash
 targets_string = ",".join(inferred_target_list)
-command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
-          (--images ? "--images \"{images}\" " : "") +
-          (--prompt ? "--prompt \"{prompt}\" " : "") +
-          "--targets \"{targets_string}\" " +
-          "--mode explore --variants {layout_variants} " +
-          "--device-type \"{device_type}\""
 
-REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
-REPORT: "   → Targets: {targets_string}"
-REPORT: "   → Layout variants: {layout_variants}"
-REPORT: "   → Device: {device_type}"
-
-SlashCommand(command)
-
-# Output: layout-templates.json with {targets × layout_variants} layout structures
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
+IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_complete):
+    REPORT: "🚀 Phase 2.5: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})"
+    command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
+              (--images ? "--images \"{images}\" " : "") +
+              (--prompt ? "--prompt \"{prompt}\" " : "") +
+              "--targets \"{targets_string}\" --mode explore --variants {layout_variants} --device-type \"{device_type}\""
+    SlashCommand(command)
+ELSE:
+    REPORT: "✅ Phase 2.5: Layout (Using Code Import)"
 ```
 
 ### Phase 3: UI Assembly

.claude/commands/workflow/ui-design/explore-layers.md

@@ -1,6 +1,6 @@
 ---
 name: explore-layers
-description: Interactive deep UI capture with depth-controlled layer exploration
+description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer
 argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
 ---

.claude/commands/workflow/ui-design/generate.md

@@ -1,6 +1,6 @@
 ---
 name: generate
-description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
+description: Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation
 argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---
@@ -99,7 +99,11 @@ Task(ui-design-agent): `
 
   2. Design Tokens:
      Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+     Extract: ALL token values including:
+       * colors, typography (with combinations), spacing, opacity
+       * border_radius, shadows, breakpoints
+       * component_styles (button, card, input variants)
+     Note: typography.combinations, opacity, and component_styles fields contain preset configurations using var() references
 
   3. Animation Tokens (OPTIONAL):
      IF exists("{base_path}/animation-extraction/animation-tokens.json"):
@@ -133,11 +137,21 @@ Task(ui-design-agent): `
      - Replace ALL var(--*) with actual token values from design-tokens.json
        Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
        Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+       Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
      - Add visual styling using design tokens:
        * Colors: tokens.colors.*
-       * Typography: tokens.typography.*
+       * Typography: tokens.typography.* (including combinations)
+       * Opacity: tokens.opacity.*
        * Shadows: tokens.shadows.*
        * Border radius: tokens.border_radius.*
+     - IF tokens.component_styles exists: Add component style classes
+       * Generate classes for button variants (.btn-primary, .btn-secondary)
+       * Generate classes for card variants (.card-default, .card-interactive)
+       * Generate classes for input variants (.input-default, .input-focus, .input-error)
+       * Use var() references that resolve to actual token values
+     - IF tokens.typography.combinations exists: Add typography preset classes
+       * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
+       * Use var() references for family, size, weight, line-height, letter-spacing
      - IF has_animations == true: Inject animation tokens
        * Add CSS Custom Properties for animations at :root level:
          --duration-instant, --duration-fast, --duration-normal, etc.

.claude/commands/workflow/ui-design/imitate-auto.md

@@ -1,6 +1,6 @@
 ---
 name: imitate-auto
-description: High-speed multi-page UI replication with batch screenshot capture
+description: High-speed multi-page UI replication with batch screenshot capture and design token extraction
 argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt "<desc>"]
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ---
@@ -115,6 +115,23 @@ ELSE:
 # Create base directory
 Bash(mkdir -p "{base_path}")
 
+# Step 0.1: Intelligent Path Detection
+code_files_detected = false
+code_base_path = null
+design_source = "web"  # Default for imitate-auto
+
+IF --prompt:
+    # Extract potential file paths from prompt
+    potential_paths = extract_paths_from_text(--prompt)
+    FOR path IN potential_paths:
+        IF file_or_directory_exists(path):
+            code_files_detected = true
+            code_base_path = path
+            design_source = "hybrid"  # Web + Code
+            BREAK
+
+STORE: design_source, code_base_path
+
 # Parse url-map
 url_map_string = {--url-map}
 VALIDATE: url_map_string is not empty, "--url-map parameter is required"
@@ -196,11 +213,110 @@ TodoWrite({todos: [
 ]})
 ```
 
+### Phase 0.5: Code Import & Completeness Assessment (Conditional)
+
+```bash
+# Only execute if code files detected
+IF design_source == "hybrid":
+    REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    REPORT: "🔍 Phase 0.5: Code Import & Analysis"
+    REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+    REPORT: "   → Source: {code_base_path}"
+    REPORT: "   → Mode: Hybrid (Web + Code)"
+
+    command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" " +
+              "--base-path \"{code_base_path}\""
+
+    TRY:
+        SlashCommand(command)
+    CATCH error:
+        WARN: "Code import failed: {error}"
+        WARN: "Falling back to web-only mode"
+        design_source = "web"
+
+    IF design_source == "hybrid":
+        # Check file existence and assess completeness
+        style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
+        animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
+        layout_exists = exists("{base_path}/layout-extraction/layout-templates.json")
+
+        style_complete = false
+        animation_complete = false
+        layout_complete = false
+        missing_categories = []
+
+        # Style completeness check
+        IF style_exists:
+            tokens = Read("{base_path}/style-extraction/style-1/design-tokens.json")
+            style_complete = (
+                tokens.colors?.brand && tokens.colors?.surface &&
+                tokens.typography?.font_family && tokens.spacing &&
+                Object.keys(tokens.colors.brand || {}).length >= 3 &&
+                Object.keys(tokens.spacing || {}).length >= 8
+            )
+            IF NOT style_complete AND tokens._metadata?.completeness?.missing_categories:
+                missing_categories.extend(tokens._metadata.completeness.missing_categories)
+        ELSE:
+            missing_categories.push("style tokens")
+
+        # Animation completeness check
+        IF animation_exists:
+            anim = Read("{base_path}/animation-extraction/animation-tokens.json")
+            animation_complete = (
+                anim.duration && anim.easing &&
+                Object.keys(anim.duration || {}).length >= 3 &&
+                Object.keys(anim.easing || {}).length >= 3
+            )
+            IF NOT animation_complete AND anim._metadata?.completeness?.missing_items:
+                missing_categories.extend(anim._metadata.completeness.missing_items)
+        ELSE:
+            missing_categories.push("animation tokens")
+
+        # Layout completeness check
+        IF layout_exists:
+            layouts = Read("{base_path}/layout-extraction/layout-templates.json")
+            layout_complete = (
+                layouts.layout_templates?.length >= 3 &&
+                layouts.extraction_metadata?.layout_system?.type &&
+                layouts.extraction_metadata?.responsive?.breakpoints
+            )
+            IF NOT layout_complete AND layouts.extraction_metadata?.completeness?.missing_items:
+                missing_categories.extend(layouts.extraction_metadata.completeness.missing_items)
+        ELSE:
+            missing_categories.push("layout templates")
+
+        # Report code analysis results
+        IF len(missing_categories) > 0:
+            REPORT: ""
+            REPORT: "⚠️  Code Analysis Partial"
+            REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            REPORT: "Missing Design Elements:"
+            FOR category IN missing_categories:
+                REPORT: "  • {category}"
+            REPORT: ""
+            REPORT: "Web screenshots will supplement missing elements"
+            REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+        ELSE:
+            REPORT: ""
+            REPORT: "✅ Code Analysis Complete"
+            REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+            REPORT: "All design elements extracted from code"
+            REPORT: "Web screenshots will verify and enhance findings"
+            REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+        STORE: style_complete, animation_complete, layout_complete
+
+TodoWrite(mark_completed: "Initialize and parse url-map",
+          mark_in_progress: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})")
+```
+
 ### Phase 1: Screenshot Capture (Dual Mode)
 
 ```bash
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 REPORT: "🚀 Phase 1: Screenshot Capture"
+IF design_source == "hybrid":
+    REPORT: "   → Purpose: Verify and supplement code analysis"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 IF capture_mode == "batch":
@@ -264,161 +380,84 @@ TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} target
           mark_in_progress: "Extract style (visual tokens)")
 ```
 
-### Phase 2: Style Extraction (Visual Tokens)
+### Phase 2: Style Extraction
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2: Style Extraction"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+# Determine if style extraction needed
+skip_style = (design_source == "hybrid" AND style_complete)
 
-# Use all screenshots as input to extract single design system
-IF capture_mode == "batch":
-    images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
-ELSE:  # deep mode
-    images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"
-
-# Build extraction prompt
-IF --prompt:
-    user_guidance = {--prompt}
-    extraction_prompt = f"Extract visual style tokens from '{primary_target}'. User guidance: {user_guidance}"
+IF skip_style:
+    REPORT: "✅ Phase 2: Style (Using Code Import)"
 ELSE:
-    extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
+    REPORT: "🚀 Phase 2: Style Extraction"
+    IF capture_mode == "batch":
+        images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
+    ELSE:
+        images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"
 
-# Build url-map string for style-extract (enables computed styles extraction)
-url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()])
+    IF --prompt:
+        extraction_prompt = f"Extract visual style tokens from '{primary_target}'. {--prompt}"
+    ELSE:
+        IF design_source == "hybrid":
+            extraction_prompt = f"Extract visual style tokens from '{primary_target}' to supplement code-imported design tokens."
+        ELSE:
+            extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
 
-# Call style-extract command (imitate mode, automatically uses single variant)
-# Pass --urls to enable auto-trigger of computed styles extraction
-extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate"
-
-TRY:
+    url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()])
+    extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate"
     SlashCommand(extract_command)
-CATCH error:
-    ERROR: "Style extraction failed: {error}"
-    ERROR: "Cannot proceed without visual tokens"
-    EXIT 1
 
-# Verify extraction results
-design_tokens_path = "{base_path}/style-extraction/style-1/design-tokens.json"
-style_guide_path = "{base_path}/style-extraction/style-1/style-guide.md"
-
-IF NOT exists(design_tokens_path) OR NOT exists(style_guide_path):
-    ERROR: "style-extract did not generate required files"
-    EXIT 1
-
-TodoWrite(mark_completed: "Extract style (complete design systems)",
-          mark_in_progress: "Extract animation (CSS auto mode)")
+TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation")
 ```
 
-### Phase 2.3: Animation Extraction (CSS Auto Mode)
+### Phase 2.3: Animation Extraction
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2.3: Animation Extraction"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+skip_animation = (design_source == "hybrid" AND animation_complete)
 
-# Build URL list for animation-extract (auto mode for CSS extraction)
-url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()])
-
-# Call animation-extract command (auto mode for CSS animation extraction)
-# Pass --urls to auto-trigger CSS animation/transition extraction via Chrome DevTools
-animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto"
-
-TRY:
+IF skip_animation:
+    REPORT: "✅ Phase 2.3: Animation (Using Code Import)"
+ELSE:
+    REPORT: "🚀 Phase 2.3: Animation Extraction"
+    url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()])
+    animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto"
     SlashCommand(animation_extract_command)
-CATCH error:
-    ERROR: "Animation extraction failed: {error}"
-    ERROR: "Cannot proceed without animation tokens"
-    EXIT 1
 
-# Verify animation extraction results
-animation_tokens_path = "{base_path}/animation-extraction/animation-tokens.json"
-animation_guide_path = "{base_path}/animation-extraction/animation-guide.md"
-
-IF NOT exists(animation_tokens_path) OR NOT exists(animation_guide_path):
-    ERROR: "animation-extract did not generate required files"
-    EXIT 1
-
-TodoWrite(mark_completed: "Extract animation (CSS auto mode)",
-          mark_in_progress: "Extract layout (structure templates)")
 ```
 
-### Phase 2.5: Layout Extraction (Structure Templates)
+### Phase 2.5: Layout Extraction
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2.5: Layout Extraction"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+skip_layout = (design_source == "hybrid" AND layout_complete)
 
-# Build URL map for layout-extract
-url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
-
-# Call layout-extract command (imitate mode for structure replication)
-# Pass --urls to enable auto-trigger of DOM structure extraction
-layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate"
-
-TRY:
+IF skip_layout:
+    REPORT: "✅ Phase 2.5: Layout (Using Code Import)"
+ELSE:
+    REPORT: "🚀 Phase 2.5: Layout Extraction"
+    url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
+    layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate"
     SlashCommand(layout_extract_command)
-CATCH error:
-    ERROR: "Layout extraction failed: {error}"
-    ERROR: "Cannot proceed without layout templates"
-    EXIT 1
 
-# Verify layout extraction results
-layout_templates_path = "{base_path}/layout-extraction/layout-templates.json"
-
-IF NOT exists(layout_templates_path):
-    ERROR: "layout-extract did not generate layout-templates.json"
-    EXIT 1
-
-TodoWrite(mark_completed: "Extract layout (structure templates)",
-          mark_in_progress: f"Assemble UI for {len(target_names)} targets")
+TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI")
 ```
 
-### Phase 3: Batch UI Assembly
+### Phase 3: UI Assembly
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 REPORT: "🚀 Phase 3: UI Assembly"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-# Call generate command (pure assembler - combines layout templates + design tokens)
 generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"
+SlashCommand(generate_command)
 
-TRY:
-    SlashCommand(generate_command)
-CATCH error:
-    ERROR: "UI assembly failed: {error}"
-    ERROR: "Layout templates or design tokens may be invalid"
-    EXIT 1
-
-# Verify assembly results
-prototypes_dir = "{base_path}/prototypes"
-generated_html_files = Glob(f"{prototypes_dir}/*-style-1-layout-1.html")
-generated_count = len(generated_html_files)
-
-IF generated_count < len(target_names):
-    WARN: "⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
-
-TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
-          mark_in_progress: session_id ? "Integrate design system" : "Standalone completion")
+TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integrate design system" : "Completion")
 ```
 
 ### Phase 4: Design System Integration
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 4: Design System Integration"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
 IF session_id:
+    REPORT: "🚀 Phase 4: Design System Integration"
     update_command = f"/workflow:ui-design:update --session {session_id}"
-
-    TRY:
-        SlashCommand(update_command)
-    CATCH error:
-        WARN: "⚠️ Design system integration failed: {error}"
-        WARN: "Prototypes available at {base_path}/prototypes/"
+    SlashCommand(update_command)
 
 # Update metadata
 metadata = Read("{base_path}/.run-metadata.json")

.claude/commands/workflow/ui-design/import-from-code.md

@@ -0,0 +1,785 @@
+---
+name: workflow:ui-design:import-from-code
+description: Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis
+argument-hint: "[--base-path <path>] [--css \"<glob>\"] [--js \"<glob>\"] [--scss \"<glob>\"] [--html \"<glob>\"] [--style-files \"<glob>\"] [--session <id>]"
+allowed-tools: Read,Write,Bash,Glob,Grep,Task,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Import from Code
+
+## Overview
+
+Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using parallel agent analysis. Each agent can reference any file type for cross-source token extraction, and directly generates completeness reports with findings and gaps.
+
+**Key Characteristics**:
+- Executes parallel agent analysis (3 agents: Style, Animation, Layout)
+- Each agent can read ALL file types (CSS/SCSS/JS/TS/HTML) for cross-reference
+- Direct completeness reporting without synthesis phase
+- Graceful failure handling with detailed missing content analysis
+- Returns concrete analysis results with recommendations
+
+## Core Functionality
+
+- **File Discovery**: Auto-discover or target specific CSS/SCSS/JS/HTML files
+- **Parallel Analysis**: 3 agents extract tokens simultaneously with cross-file-type support
+- **Completeness Reporting**: Each agent reports found tokens, missing content, and recommendations
+- **Cross-Source Extraction**: Agents can reference any file type (e.g., Style agent can read JS theme configs)
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:import-from-code [FLAGS]
+
+# Flags
+--base-path <path>      Base directory for analysis (default: current directory)
+--css "<glob>"          CSS file glob pattern (e.g., "theme/*.css")
+--scss "<glob>"         SCSS file glob pattern (e.g., "styles/*.scss")
+--js "<glob>"           JavaScript file glob pattern (e.g., "theme/*.js")
+--html "<glob>"         HTML file glob pattern (e.g., "pages/*.html")
+--style-files "<glob>"  Universal style file glob (applies to CSS/SCSS/JS)
+--session <id>          Session identifier for workflow tracking
+```
+
+### Usage Examples
+
+```bash
+# Basic usage - auto-discover all files
+/workflow:ui-design:import-from-code --base-path ./
+
+# Target specific directories
+/workflow:ui-design:import-from-code --base-path ./src --css "theme/*.css" --js "theme/*.js"
+
+# Tailwind config only
+/workflow:ui-design:import-from-code --js "tailwind.config.js"
+
+# CSS framework import
+/workflow:ui-design:import-from-code --css "styles/**/*.scss" --html "components/**/*.html"
+
+# Universal style files
+/workflow:ui-design:import-from-code --style-files "**/theme.*"
+```
+
+---
+
+## Execution Process
+
+### Step 1: Setup & File Discovery
+
+**Purpose**: Initialize session, discover and categorize code files
+
+**Operations**:
+
+```bash
+# 1. Initialize directories
+base_path="${base_path:-.}"
+intermediates_dir="${base_path}/.intermediates/import-analysis"
+mkdir -p "$intermediates_dir"
+
+echo "[Phase 0] File Discovery Started"
+```
+
+<!-- TodoWrite: Initialize todo list -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 发现和分类代码文件", "status": "in_progress", "activeForm": "发现代码文件"},
+  {"content": "Phase 1: 并行Agent分析并生成completeness-report.json", "status": "pending", "activeForm": "生成design system"}
+]
+```
+
+**File Discovery Logic**:
+
+```bash
+# 2. Discover files by type
+cd "$base_path" || exit 1
+
+# CSS files
+if [ -n "$css" ]; then
+  find . -type f -name "*.css" | grep -E "$css" > "$intermediates_dir/css-files.txt"
+elif [ -n "$style_files" ]; then
+  find . -type f -name "*.css" | grep -E "$style_files" > "$intermediates_dir/css-files.txt"
+else
+  find . -type f -name "*.css" -not -path "*/node_modules/*" -not -path "*/dist/*" > "$intermediates_dir/css-files.txt"
+fi
+
+# SCSS files
+if [ -n "$scss" ]; then
+  find . -type f \( -name "*.scss" -o -name "*.sass" \) | grep -E "$scss" > "$intermediates_dir/scss-files.txt"
+elif [ -n "$style_files" ]; then
+  find . -type f \( -name "*.scss" -o -name "*.sass" \) | grep -E "$style_files" > "$intermediates_dir/scss-files.txt"
+else
+  find . -type f \( -name "*.scss" -o -name "*.sass" \) -not -path "*/node_modules/*" -not -path "*/dist/*" > "$intermediates_dir/scss-files.txt"
+fi
+
+# JavaScript files (theme/style related)
+if [ -n "$js" ]; then
+  find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) | grep -E "$js" > "$intermediates_dir/js-files.txt"
+elif [ -n "$style_files" ]; then
+  find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) | grep -E "$style_files" > "$intermediates_dir/js-files.txt"
+else
+  # Look for common theme/style file patterns
+  find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" \) -not -path "*/node_modules/*" -not -path "*/dist/*" | \
+    grep -iE "(theme|style|color|token|design)" > "$intermediates_dir/js-files.txt" || touch "$intermediates_dir/js-files.txt"
+fi
+
+# HTML files
+if [ -n "$html" ]; then
+  find . -type f \( -name "*.html" -o -name "*.htm" \) | grep -E "$html" > "$intermediates_dir/html-files.txt"
+else
+  find . -type f \( -name "*.html" -o -name "*.htm" \) -not -path "*/node_modules/*" -not -path "*/dist/*" > "$intermediates_dir/html-files.txt"
+fi
+
+# 3. Count discovered files
+css_count=$(wc -l < "$intermediates_dir/css-files.txt" 2>/dev/null || echo 0)
+scss_count=$(wc -l < "$intermediates_dir/scss-files.txt" 2>/dev/null || echo 0)
+js_count=$(wc -l < "$intermediates_dir/js-files.txt" 2>/dev/null || echo 0)
+html_count=$(wc -l < "$intermediates_dir/html-files.txt" 2>/dev/null || echo 0)
+
+echo "[Phase 0] Discovered: CSS=$css_count, SCSS=$scss_count, JS=$js_count, HTML=$html_count"
+```
+
+<!-- TodoWrite: Mark Phase 0 complete, start Phase 1 -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 发现和分类代码文件", "status": "completed", "activeForm": "发现代码文件"},
+  {"content": "Phase 1: 并行Agent分析并生成completeness-report.json", "status": "in_progress", "activeForm": "生成design system"}
+]
+```
+
+---
+
+### Step 2: Parallel Agent Analysis
+
+**Purpose**: Three agents analyze all file types in parallel, each producing completeness-report.json
+
+**Operations**:
+- **Style Agent**: Extracts visual tokens (colors, typography, spacing) from ALL files (CSS/SCSS/JS/HTML)
+- **Animation Agent**: Extracts animations/transitions from ALL files
+- **Layout Agent**: Extracts layout patterns/component structures from ALL files
+
+**Validation**:
+- Each agent can reference any file type (not restricted to single type)
+- Direct output: Each agent generates completeness-report.json with findings + missing content
+- No synthesis needed: Agents produce final output directly
+
+```bash
+echo "[Phase 1] Starting parallel agent analysis (3 agents)"
+```
+
+#### Style Agent Task (style-completeness-report.json)
+
+**Agent Task**:
+
+```javascript
+Task(ui-design-agent): `
+  [STYLE_TOKENS_EXTRACTION]
+  Extract visual design tokens (colors, typography, spacing, shadows, borders) from ALL file types
+
+  MODE: style-extraction | BASE_PATH: ${base_path}
+
+  ## Input Files (Can reference ANY file type)
+
+  **CSS/SCSS files (${css_count})**:
+  $(cat "${intermediates_dir}/css-files.txt" 2>/dev/null | head -20)
+
+  **JavaScript/TypeScript files (${js_count})**:
+  $(cat "${intermediates_dir}/js-files.txt" 2>/dev/null | head -20)
+
+  **HTML files (${html_count})**:
+  $(cat "${intermediates_dir}/html-files.txt" 2>/dev/null | head -20)
+
+  ## Extraction Strategy
+
+  **You can read ALL file types** - Cross-reference for better extraction:
+  1. **CSS/SCSS**: Primary source for colors, typography, spacing, shadows, borders
+  2. **JavaScript/TypeScript**: Theme objects (styled-components, Tailwind config, CSS-in-JS tokens)
+  3. **HTML**: Inline styles, class usage patterns, component examples
+
+  **Smart inference** - Fill gaps using cross-source data:
+  - Missing CSS colors? Check JS theme objects
+  - Missing spacing scale? Infer from existing values in any file type
+  - Missing typography? Check font-family usage in CSS + HTML + JS configs
+
+  ## Output Requirements
+
+  Generate 2 files in ${base_path}/style-extraction/style-1/:
+  1. design-tokens.json (production-ready design tokens)
+  2. style-guide.md (design philosophy and usage guide)
+
+  ### design-tokens.json Structure:
+  {
+    "colors": {
+      "brand": {
+        "primary": {"value": "#0066cc", "source": "file.css:23"},
+        "secondary": {"value": "#6c757d", "source": "file.css:24"}
+      },
+      "surface": {
+        "background": {"value": "#ffffff", "source": "file.css:10"},
+        "card": {"value": "#f8f9fa", "source": "file.css:11"}
+      },
+      "semantic": {
+        "success": {"value": "#28a745", "source": "file.css:30"},
+        "warning": {"value": "#ffc107", "source": "file.css:31"},
+        "error": {"value": "#dc3545", "source": "file.css:32"}
+      },
+      "text": {
+        "primary": {"value": "#212529", "source": "file.css:15"},
+        "secondary": {"value": "#6c757d", "source": "file.css:16"}
+      },
+      "border": {
+        "default": {"value": "#dee2e6", "source": "file.css:20"}
+      }
+    },
+    "typography": {
+      "font_family": {
+        "base": {"value": "system-ui, sans-serif", "source": "theme.js:12"},
+        "heading": {"value": "Georgia, serif", "source": "theme.js:13"}
+      },
+      "font_size": {
+        "xs": {"value": "0.75rem", "source": "styles.css:5"},
+        "sm": {"value": "0.875rem", "source": "styles.css:6"},
+        "base": {"value": "1rem", "source": "styles.css:7"},
+        "lg": {"value": "1.125rem", "source": "styles.css:8"},
+        "xl": {"value": "1.25rem", "source": "styles.css:9"}
+      },
+      "font_weight": {
+        "normal": {"value": "400", "source": "styles.css:12"},
+        "medium": {"value": "500", "source": "styles.css:13"},
+        "bold": {"value": "700", "source": "styles.css:14"}
+      },
+      "line_height": {
+        "tight": {"value": "1.25", "source": "styles.css:18"},
+        "normal": {"value": "1.5", "source": "styles.css:19"},
+        "relaxed": {"value": "1.75", "source": "styles.css:20"}
+      },
+      "letter_spacing": {
+        "tight": {"value": "-0.025em", "source": "styles.css:24"},
+        "normal": {"value": "0", "source": "styles.css:25"},
+        "wide": {"value": "0.025em", "source": "styles.css:26"}
+      }
+    },
+    "spacing": {
+      "0": {"value": "0", "source": "styles.css:30"},
+      "1": {"value": "0.25rem", "source": "styles.css:31"},
+      "2": {"value": "0.5rem", "source": "styles.css:32"},
+      "3": {"value": "0.75rem", "source": "styles.css:33"},
+      "4": {"value": "1rem", "source": "styles.css:34"},
+      "6": {"value": "1.5rem", "source": "styles.css:35"},
+      "8": {"value": "2rem", "source": "styles.css:36"},
+      "12": {"value": "3rem", "source": "styles.css:37"}
+    },
+    "opacity": {
+      "0": {"value": "0", "source": "styles.css:40"},
+      "50": {"value": "0.5", "source": "styles.css:41"},
+      "100": {"value": "1", "source": "styles.css:42"}
+    },
+    "border_radius": {
+      "none": {"value": "0", "source": "styles.css:45"},
+      "sm": {"value": "0.125rem", "source": "styles.css:46"},
+      "base": {"value": "0.25rem", "source": "styles.css:47"},
+      "lg": {"value": "0.5rem", "source": "styles.css:48"},
+      "full": {"value": "9999px", "source": "styles.css:49"}
+    },
+    "shadows": {
+      "sm": {"value": "0 1px 2px rgba(0,0,0,0.05)", "source": "theme.css:45"},
+      "base": {"value": "0 1px 3px rgba(0,0,0,0.1)", "source": "theme.css:46"},
+      "md": {"value": "0 4px 6px rgba(0,0,0,0.1)", "source": "theme.css:47"},
+      "lg": {"value": "0 10px 15px rgba(0,0,0,0.1)", "source": "theme.css:48"}
+    },
+    "breakpoints": {
+      "sm": {"value": "640px", "source": "media.scss:3"},
+      "md": {"value": "768px", "source": "media.scss:4"},
+      "lg": {"value": "1024px", "source": "media.scss:5"},
+      "xl": {"value": "1280px", "source": "media.scss:6"}
+    },
+    "_metadata": {
+      "extraction_source": "code_import",
+      "files_analyzed": {
+        "css": ["list of CSS/SCSS files read"],
+        "js": ["list of JS/TS files read"],
+        "html": ["list of HTML files read"]
+      },
+      "completeness": {
+        "colors": "complete | partial | minimal",
+        "typography": "complete | partial | minimal",
+        "spacing": "complete | partial | minimal",
+        "missing_categories": ["accent", "warning"],
+        "recommendations": [
+          "Define accent color for interactive elements",
+          "Add semantic colors (warning, error, success)"
+        ]
+      }
+    }
+  }
+
+  ### style-guide.md Structure:
+ 
+  # Design System Style Guide
+
+  ## Overview
+  Extracted from code files: [list of source files]
+
+  ## Colors
+  - **Brand**: Primary, Secondary
+  - **Surface**: Background, Card
+  - **Semantic**: Success, Warning, Error
+  - **Text**: Primary, Secondary
+  - **Border**: Default
+
+  ## Typography
+  - **Font Families**: Base (system-ui), Heading (Georgia)
+  - **Font Sizes**: xs to xl (0.75rem - 1.25rem)
+  - **Font Weights**: Normal (400), Medium (500), Bold (700)
+
+  ## Spacing
+  System: 8px-grid (0, 0.25rem, 0.5rem, ..., 3rem)
+
+  ## Missing Elements
+  - Accent colors for interactive elements
+  - Extended shadow scale
+
+  ## Usage
+  All tokens are production-ready and can be used with CSS variables.
+  
+
+  ## Completeness Criteria
+  - **colors**: ≥5 categories (brand, semantic, surface, text, border), ≥10 tokens
+  - **typography**: ≥3 font families, ≥8 sizes, ≥5 weights
+  - **spacing**: ≥8 values in consistent system
+  - **shadows**: ≥3 elevation levels
+  - **borders**: ≥3 radius values, ≥2 widths
+
+  ## Critical Requirements
+  - ✅ Can read ANY file type (CSS/SCSS/JS/TS/HTML) - not restricted to CSS only
+  - ✅ Use Read() tool for each file you want to analyze
+  - ✅ Cross-reference between file types for better extraction
+  - ✅ Extract all visual token types systematically
+  - ✅ Create style-extraction/style-1/ directory first: Bash(mkdir -p "${base_path}/style-extraction/style-1")
+  - ✅ Use Write() to save both files:
+    - ${base_path}/style-extraction/style-1/design-tokens.json
+    - ${base_path}/style-extraction/style-1/style-guide.md
+  - ✅ Include _metadata.completeness field to track missing content
+  - ❌ NO external research or MCP calls
+`
+```
+
+#### Animation Agent Task
+
+**Agent Task**:
+
+```javascript
+Task(ui-design-agent): `
+  [ANIMATION_TOKENS_EXTRACTION]
+  Extract animation/transition tokens from ALL file types
+
+  MODE: animation-extraction | BASE_PATH: ${base_path}
+
+  ## Input Files (Can reference ANY file type)
+
+  **CSS/SCSS files (${css_count})**:
+  $(cat "${intermediates_dir}/css-files.txt" 2>/dev/null | head -20)
+
+  **JavaScript/TypeScript files (${js_count})**:
+  $(cat "${intermediates_dir}/js-files.txt" 2>/dev/null | head -20)
+
+  **HTML files (${html_count})**:
+  $(cat "${intermediates_dir}/html-files.txt" 2>/dev/null | head -20)
+
+  ## Extraction Strategy
+
+  **You can read ALL file types** - Find animations anywhere:
+  1. **CSS/SCSS**: @keyframes, transition properties, animation properties
+  2. **JavaScript/TypeScript**: Animation configs (Framer Motion, GSAP, CSS-in-JS animations)
+  3. **HTML**: Inline animation styles, data-animation attributes
+
+  **Cross-reference**:
+  - CSS animations referenced in JS configs
+  - JS animation libraries with CSS class triggers
+  - HTML elements with animation classes/attributes
+
+  ## Output Requirements
+
+  Generate 2 files in ${base_path}/animation-extraction/:
+  1. animation-tokens.json (production-ready animation tokens)
+  2. animation-guide.md (animation usage guide)
+
+  ### animation-tokens.json Structure:
+  {
+    "duration": {
+      "instant": {"value": "0ms", "source": "animations.css:10"},
+      "fast": {"value": "150ms", "source": "animations.css:12"},
+      "base": {"value": "250ms", "source": "animations.css:13"},
+      "slow": {"value": "500ms", "source": "animations.css:14"}
+    },
+    "easing": {
+      "linear": {"value": "linear", "source": "animations.css:20"},
+      "ease-in": {"value": "cubic-bezier(0.4, 0, 1, 1)", "source": "theme.js:45"},
+      "ease-out": {"value": "cubic-bezier(0, 0, 0.2, 1)", "source": "theme.js:46"},
+      "ease-in-out": {"value": "cubic-bezier(0.4, 0, 0.2, 1)", "source": "theme.js:47"}
+    },
+    "transitions": {
+      "color": {
+        "property": "color",
+        "duration": "var(--duration-fast)",
+        "easing": "var(--ease-out)",
+        "source": "transitions.css:30"
+      },
+      "transform": {
+        "property": "transform",
+        "duration": "var(--duration-base)",
+        "easing": "var(--ease-in-out)",
+        "source": "transitions.css:35"
+      },
+      "opacity": {
+        "property": "opacity",
+        "duration": "var(--duration-fast)",
+        "easing": "var(--ease-out)",
+        "source": "transitions.css:40"
+      }
+    },
+    "keyframes": {
+      "fadeIn": {
+        "name": "fadeIn",
+        "keyframes": {
+          "0%": {"opacity": "0"},
+          "100%": {"opacity": "1"}
+        },
+        "source": "styles.css:67"
+      },
+      "slideInUp": {
+        "name": "slideInUp",
+        "keyframes": {
+          "0%": {"transform": "translateY(20px)", "opacity": "0"},
+          "100%": {"transform": "translateY(0)", "opacity": "1"}
+        },
+        "source": "styles.css:75"
+      }
+    },
+    "interactions": {
+      "button-hover": {
+        "trigger": "hover",
+        "properties": ["background-color", "transform"],
+        "duration": "var(--duration-fast)",
+        "easing": "var(--ease-out)",
+        "source": "button.css:45"
+      }
+    },
+    "_metadata": {
+      "extraction_source": "code_import",
+      "framework_detected": "css-animations | framer-motion | gsap | none",
+      "files_analyzed": {
+        "css": ["list of CSS/SCSS files read"],
+        "js": ["list of JS/TS files read"],
+        "html": ["list of HTML files read"]
+      },
+      "completeness": {
+        "durations": "complete | partial | minimal",
+        "easing": "complete | partial | minimal",
+        "keyframes": "complete | partial | minimal",
+        "missing_items": ["bounce easing", "slide animations"],
+        "recommendations": [
+          "Add slow duration for complex animations",
+          "Define spring/bounce easing for interactive feedback"
+        ]
+      }
+    }
+  }
+
+  ### animation-guide.md Structure:
+  
+  # Animation System Guide
+
+  ## Overview
+  Extracted from code files: [list of source files]
+  Framework detected: [css-animations | framer-motion | gsap | none]
+
+  ## Durations
+  - **Instant**: 0ms
+  - **Fast**: 150ms (UI feedback)
+  - **Base**: 250ms (standard transitions)
+  - **Slow**: 500ms (complex animations)
+
+  ## Easing Functions
+  - **Linear**: Constant speed
+  - **Ease-out**: Fast start, slow end (entering elements)
+  - **Ease-in-out**: Smooth acceleration and deceleration
+
+  ## Keyframe Animations
+  - **fadeIn**: Opacity 0 → 1
+  - **slideInUp**: Slide from bottom with fade
+
+  ## Missing Elements
+  - Bounce/spring easing for playful interactions
+  - Slide-out animations
+
+  ## Usage
+  All animation tokens use CSS variables and can be referenced in transitions.
+
+
+  ## Completeness Criteria
+  - **durations**: ≥3 (fast, medium, slow)
+  - **easing**: ≥3 functions (ease-in, ease-out, ease-in-out)
+  - **keyframes**: ≥3 animation types (fade, scale, slide)
+  - **transitions**: ≥5 properties defined
+
+  ## Critical Requirements
+  - ✅ Can read ANY file type (CSS/SCSS/JS/TS/HTML)
+  - ✅ Use Read() tool for each file you want to analyze
+  - ✅ Detect animation framework if used
+  - ✅ Extract all animation-related tokens
+  - ✅ Create animation-extraction/ directory first: Bash(mkdir -p "${base_path}/animation-extraction")
+  - ✅ Use Write() to save both files:
+    - ${base_path}/animation-extraction/animation-tokens.json
+    - ${base_path}/animation-extraction/animation-guide.md
+  - ✅ Include _metadata.completeness field to track missing content
+  - ❌ NO external research or MCP calls
+`
+```
+
+#### Layout Agent Task
+
+**Agent Task**:
+
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_PATTERNS_EXTRACTION]
+  Extract layout patterns and component structures from ALL file types
+
+  MODE: layout-extraction | BASE_PATH: ${base_path}
+
+  ## Input Files (Can reference ANY file type)
+
+  **CSS/SCSS files (${css_count})**:
+  $(cat "${intermediates_dir}/css-files.txt" 2>/dev/null | head -20)
+
+  **JavaScript/TypeScript files (${js_count})**:
+  $(cat "${intermediates_dir}/js-files.txt" 2>/dev/null | head -20)
+
+  **HTML files (${html_count})**:
+  $(cat "${intermediates_dir}/html-files.txt" 2>/dev/null | head -20)
+
+  ## Extraction Strategy
+
+  **You can read ALL file types** - Find layout patterns anywhere:
+  1. **CSS/SCSS**: Grid systems, flexbox utilities, layout classes, media queries
+  2. **JavaScript/TypeScript**: Layout components (React/Vue), grid configurations, responsive logic
+  3. **HTML**: Layout structures, semantic patterns, component hierarchies
+
+  **Cross-reference**:
+  - HTML structure + CSS classes → layout system
+  - JS components + CSS styles → component patterns
+  - Responsive classes across all file types
+
+  ## Output Requirements
+
+  Generate 1 file: ${base_path}/layout-extraction/layout-templates.json
+
+  ### layout-templates.json Structure:
+  {
+    "extraction_metadata": {
+      "extraction_source": "code_import",
+      "analysis_time": "ISO8601 timestamp",
+      "files_analyzed": {
+        "css": ["list of CSS/SCSS files read"],
+        "js": ["list of JS/TS files read"],
+        "html": ["list of HTML files read"]
+      },
+      "naming_convention": "BEM | SMACSS | utility-first | css-modules | custom",
+      "layout_system": {
+        "type": "12-column | flexbox | css-grid | custom",
+        "confidence": "high | medium | low",
+        "container_classes": ["container", "wrapper"],
+        "row_classes": ["row"],
+        "column_classes": ["col-1", "col-md-6"],
+        "source_files": ["grid.css", "Layout.jsx"]
+      },
+      "responsive": {
+        "breakpoint_prefixes": ["sm:", "md:", "lg:", "xl:"],
+        "mobile_first": true,
+        "breakpoints": {
+          "sm": "640px",
+          "md": "768px",
+          "lg": "1024px",
+          "xl": "1280px"
+        },
+        "source": "responsive.scss:5"
+      },
+      "completeness": {
+        "layout_system": "complete | partial | minimal",
+        "components": "complete | partial | minimal",
+        "responsive": "complete | partial | minimal",
+        "missing_items": ["gap utilities", "modal", "dropdown"],
+        "recommendations": [
+          "Add gap utilities for consistent spacing in grid layouts",
+          "Define modal/dropdown/tabs component patterns"
+        ]
+      }
+    },
+    "layout_templates": [
+      {
+        "target": "button",
+        "variant_id": "layout-1",
+        "device_type": "responsive",
+        "component_type": "component",
+        "dom_structure": {
+          "tag": "button",
+          "classes": ["btn", "btn-primary"],
+          "children": [
+            {"tag": "span", "classes": ["btn-text"], "content": "{{text}}"}
+          ],
+          "variants": {
+            "primary": {"classes": ["btn", "btn-primary"]},
+            "secondary": {"classes": ["btn", "btn-secondary"]}
+          },
+          "sizes": {
+            "sm": {"classes": ["btn-sm"]},
+            "base": {"classes": []},
+            "lg": {"classes": ["btn-lg"]}
+          },
+          "states": ["hover", "active", "disabled"]
+        },
+        "css_layout_rules": "display: inline-flex; align-items: center; justify-content: center; padding: var(--spacing-2) var(--spacing-4); border-radius: var(--radius-base);",
+        "source": "button.css:12"
+      },
+      {
+        "target": "card",
+        "variant_id": "layout-1",
+        "device_type": "responsive",
+        "component_type": "component",
+        "dom_structure": {
+          "tag": "div",
+          "classes": ["card"],
+          "children": [
+            {"tag": "div", "classes": ["card-header"], "content": "{{title}}"},
+            {"tag": "div", "classes": ["card-body"], "content": "{{content}}"},
+            {"tag": "div", "classes": ["card-footer"], "content": "{{footer}}"}
+          ]
+        },
+        "css_layout_rules": "display: flex; flex-direction: column; border: 1px solid var(--color-border); border-radius: var(--radius-lg); padding: var(--spacing-4); background: var(--color-surface-card);",
+        "source": "card.css:25"
+      }
+    ]
+  }
+
+  ## Completeness Criteria
+  - **layout_system**: Clear grid/flexbox system identified
+  - **components**: ≥5 component patterns (button, card, input, modal, dropdown)
+  - **responsive**: ≥3 breakpoints, clear mobile-first strategy
+  - **naming_convention**: Consistent pattern identified
+
+  ## Critical Requirements
+  - ✅ Can read ANY file type (CSS/SCSS/JS/TS/HTML)
+  - ✅ Use Read() tool for each file you want to analyze
+  - ✅ Identify naming conventions and layout systems
+  - ✅ Extract component patterns with variants and states
+  - ✅ Create layout-extraction/ directory first: Bash(mkdir -p "${base_path}/layout-extraction")
+  - ✅ Use Write() to save: ${base_path}/layout-extraction/layout-templates.json
+  - ✅ Include extraction_metadata.completeness field to track missing content
+  - ❌ NO external research or MCP calls
+`
+```
+
+**Wait for All Agents**:
+
+```bash
+# Note: Agents run in parallel and write separate completeness reports
+# Each agent generates its own completeness-report.json directly
+# No synthesis phase needed
+echo "[Phase 1] Parallel agent analysis complete"
+```
+
+<!-- TodoWrite: Mark all complete -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 发现和分类代码文件", "status": "completed", "activeForm": "发现代码文件"},
+  {"content": "Phase 1: 并行Agent分析并生成completeness-report.json", "status": "completed", "activeForm": "生成design system"}
+]
+```
+
+---
+
+## Output Files
+
+### Generated Files
+
+**Location**: `${base_path}/`
+
+**Directory Structure**:
+```
+${base_path}/
+├── style-extraction/
+│   └── style-1/
+│       ├── design-tokens.json       # Production-ready design tokens
+│       └── style-guide.md           # Design philosophy and usage
+├── animation-extraction/
+│   ├── animation-tokens.json        # Animation/transition tokens
+│   └── animation-guide.md           # Animation usage guide
+├── layout-extraction/
+│   └── layout-templates.json        # Layout patterns and component structures
+└── .intermediates/
+    └── import-analysis/
+        ├── css-files.txt            # Discovered CSS/SCSS files
+        ├── js-files.txt             # Discovered JS/TS files
+        └── html-files.txt           # Discovered HTML files
+```
+
+**Files**:
+1. **style-extraction/style-1/design-tokens.json**
+   - Production-ready design tokens
+   - Categories: colors, typography, spacing, opacity, border_radius, shadows, breakpoints
+   - Metadata: extraction_source, files_analyzed, completeness assessment
+
+2. **style-extraction/style-1/style-guide.md**
+   - Design system overview
+   - Token categories and usage
+   - Missing elements and recommendations
+
+3. **animation-extraction/animation-tokens.json**
+   - Animation tokens: duration, easing, transitions, keyframes, interactions
+   - Framework detection: css-animations, framer-motion, gsap, etc.
+   - Metadata: extraction_source, completeness assessment
+
+4. **animation-extraction/animation-guide.md**
+   - Animation system overview
+   - Usage guidelines and examples
+
+5. **layout-extraction/layout-templates.json**
+   - Layout templates for each discovered component
+   - Extraction metadata: naming_convention, layout_system, responsive strategy
+   - Component patterns with DOM structure and CSS rules
+
+**Intermediate Files**: `.intermediates/import-analysis/`
+- `css-files.txt` - Discovered CSS/SCSS files
+- `js-files.txt` - Discovered JS/TS files
+- `html-files.txt` - Discovered HTML files
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No files discovered | Glob patterns too restrictive or wrong base-path | Check glob patterns and base-path, verify file locations |
+| Agent reports "failed" status | No tokens found in any file | Review file content, check if files contain design tokens |
+| Empty completeness reports | Files exist but contain no extractable tokens | Manually verify token definitions in source files |
+| Missing file type | Specific file type not discovered | Use explicit glob flags (--css, --js, --html, --scss) |
+
+---
+
+## Best Practices
+
+1. **Use auto-discovery for full projects**: Omit glob flags to discover all files automatically
+2. **Target specific directories for speed**: Use `--base-path` + specific globs for focused analysis
+3. **Cross-reference agent reports**: Compare all three completeness reports to identify gaps
+4. **Review missing content**: Check `missing` field in reports for actionable improvements
+5. **Verify file discovery**: Check `.intermediates/import-analysis/*-files.txt` if agents report no data

.claude/commands/workflow/ui-design/layout-extract.md

@@ -1,6 +1,6 @@
 ---
 name: layout-extract
-description: Extract structural layout information from reference images, URLs, or text prompts
+description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis
 argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
 ---

.claude/commands/workflow/ui-design/style-extract.md

@@ -1,6 +1,6 @@
 ---
 name: style-extract
-description: Extract design style from reference images or text prompts using Claude's analysis
+description: Extract design style from reference images or text prompts using Claude analysis with variant generation
 argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
 ---
@@ -154,7 +154,7 @@ IF exists: SKIP to completion
 ### Step 2: Load Project Context (Explore Mode)
 ```bash
 # Load brainstorming context if available
-bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
+bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
 ```
 
 ### Step 3: Generate Design Direction Options (Agent Task 1)
@@ -418,17 +418,33 @@ Task(ui-design-agent): `
   Create complete design system in {base_path}/style-extraction/style-1/
 
   1. **design-tokens.json**:
-     - Complete token structure: colors (brand, surface, semantic, text, border), typography (families, sizes, weights, line heights, letter spacing), spacing (0-24 scale), border_radius (none to full), shadows (sm to xl), breakpoints (sm to 2xl)
+     - Complete token structure with ALL fields:
+       * colors (brand, surface, semantic, text, border) - OKLCH format
+       * typography (families, sizes, weights, line heights, letter spacing, combinations)
+       * typography.combinations: Predefined typography presets (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) using var() references
+       * spacing (0-24 scale)
+       * opacity (0, 10, 20, 40, 60, 80, 90, 100)
+       * border_radius (none to full)
+       * shadows (sm to xl)
+       * component_styles (button, card, input variants) - component presets using var() references
+       * breakpoints (sm to 2xl)
      - All colors in OKLCH format
      ${extraction_mode == "explore" ? "- Start from preview colors and expand to full palette" : ""}
      ${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
+     - Common Tailwind CSS usage patterns in project (if extracting from existing project)
 
   2. **style-guide.md**:
      - Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
      - Complete color system documentation with accessibility notes
      - Typography scale and usage guidelines
+     - Typography Combinations section: Document each preset (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) with usage context and code examples
      - Spacing system explanation
+     - Opacity & Transparency section: Opacity scale usage, common use cases (disabled states, overlays, hover effects), accessibility considerations
+     - Shadows & Elevation section: Shadow hierarchy and semantic usage
+     - Component Styles section: Document button, card, and input variants with code examples and visual descriptions
+     - Border Radius system and semantic usage
      - Component examples and usage patterns
+     - Common Tailwind CSS patterns (if applicable)
 
   ## Critical Requirements
   - ✅ Use Write() tool immediately for each file
@@ -541,7 +557,7 @@ bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colo
 ### File Operations
 ```bash
 # Load brainstorming context
-bash(test -f .brainstorming/synthesis-specification.md && cat it)
+bash(test -f .brainstorming/role analysis documents && cat it)
 
 # Create directories
 bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
@@ -577,15 +593,46 @@ bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json &&
     "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
     "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
   },
-  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "typography": {
+    "font_family": {...},
+    "font_size": {...},
+    "font_weight": {...},
+    "line_height": {...},
+    "letter_spacing": {...},
+    "combinations": {
+      "heading-primary": {"family": "var(--font-family-heading)", "size": "var(--font-size-3xl)", "weight": "var(--font-weight-bold)", "line_height": "var(--line-height-tight)", "letter_spacing": "var(--letter-spacing-tight)"},
+      "heading-secondary": {...},
+      "body-regular": {...},
+      "body-emphasis": {...},
+      "caption": {...},
+      "label": {...}
+    }
+  },
   "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "opacity": {"0": "0", "10": "0.1", "20": "0.2", "40": "0.4", "60": "0.6", "80": "0.8", "90": "0.9", "100": "1"},
   "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
   "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "component_styles": {
+    "button": {
+      "primary": {"background": "var(--color-brand-primary)", "color": "var(--color-text-inverse)", "padding": "var(--spacing-3) var(--spacing-6)", "border_radius": "var(--border-radius-md)", "font_weight": "var(--font-weight-semibold)"},
+      "secondary": {...},
+      "tertiary": {...}
+    },
+    "card": {
+      "default": {"background": "var(--color-surface-elevated)", "padding": "var(--spacing-6)", "border_radius": "var(--border-radius-lg)", "shadow": "var(--shadow-md)"},
+      "interactive": {...}
+    },
+    "input": {
+      "default": {"border": "1px solid var(--color-border-default)", "padding": "var(--spacing-3)", "border_radius": "var(--border-radius-md)", "background": "var(--color-surface-background)"},
+      "focus": {...},
+      "error": {...}
+    }
+  },
   "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
 }
 ```
 
-**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance
+**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance, typography combinations, component style presets, opacity scale
 
 ## Error Handling
 

.claude/commands/workflow/ui-design/update.md

@@ -1,6 +1,6 @@
 ---
 name: update
-description: Update brainstorming artifacts with finalized design system references
+description: Update brainstorming artifacts with finalized design system references from selected prototypes
 argument-hint: --session <session_id> [--selected-prototypes "<list>"]
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
@@ -15,7 +15,7 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 
 - **Reference-Only Updates**: Use @ references, no content duplication
 - **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
-- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
+- **Synthesis Alignment**: Update role analysis documents UI/UX Guidelines section
 - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
 - **Minimal Reading**: Verify file existence, don't read design content
 
@@ -50,8 +50,8 @@ REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
 ### Phase 1.1: Memory Check (Skip if Already Updated)
 
 ```bash
-# Check if synthesis-specification.md contains current design run reference
-synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/synthesis-specification.md"
+# Check if role analysis documents contains current design run reference
+synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents"
 current_design_run = basename(latest_design)  # e.g., "design-run-20250109-143022"
 
 IF exists(synthesis_spec_path):
@@ -68,7 +68,7 @@ IF exists(synthesis_spec_path):
 
 ```bash
 # Load target brainstorming artifacts (files to be updated)
-Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+Read(.workflow/WFS-{session}/.brainstorming/role analysis documents)
 IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
 
 # Optional: Read prototype notes for descriptions (minimal context)
@@ -80,7 +80,7 @@ FOR each selected_prototype IN selected_list:
 
 ### Phase 3: Update Synthesis Specification
 
-Update `.brainstorming/synthesis-specification.md` with design system references.
+Update `.brainstorming/role analysis documents` with design system references.
 
 **Target Section**: `## UI/UX Guidelines`
 
@@ -113,7 +113,7 @@ Update `.brainstorming/synthesis-specification.md` with design system references
 **Implementation**:
 ```bash
 # Option 1: Edit existing section
-Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
+Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents",
      old_string="## UI/UX Guidelines\n[existing content]",
      new_string="## UI/UX Guidelines\n\n[new design reference content]")
 
@@ -122,12 +122,77 @@ IF section not found:
     Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
 ```
 
-### Phase 4: Update UI Designer Style Guide
+### Phase 4A: Update Relevant Role Analysis Documents
 
-Create or update `.brainstorming/ui-designer/style-guide.md`:
+**Discovery**: Find role analysis.md files affected by design outputs
+
+```bash
+# Always update ui-designer
+ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
+
+# Conditionally update other roles
+has_animations = exists({latest_design}/animation-extraction/animation-tokens.json)
+has_layouts = exists({latest_design}/layout-extraction/layout-templates.json)
+
+IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
+IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md")
+IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md")
+```
+
+**Content Templates**:
+
+**ui-designer/analysis.md** (append if not exists):
+```markdown
+## Design System Implementation Reference
+
+**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**ux-expert/analysis.md** (if animations):
+```markdown
+## Animation & Interaction Reference
+
+**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**system-architect/analysis.md** (if layouts):
+```markdown
+## Layout Structure Reference
+
+**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**product-manager/analysis.md** (if prototypes):
+```markdown
+## Prototype Validation Reference
+
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**Implementation**:
+```bash
+FOR file IN [ui_designer_files, ux_expert_files, architect_files, pm_files]:
+  IF file exists AND section_not_exists(file):
+    Edit(file, old_string="[end of document]", new_string="\n\n{role-specific section}")
+```
+
+### Phase 4B: Create UI Designer Design System Reference
+
+Create or update `.brainstorming/ui-designer/design-system-reference.md`:
 
 ```markdown
-# UI Designer Style Guide
+# UI Designer Design System Reference
 
 ## Design System Integration
 This style guide references the finalized design system from the design refinement phase.
@@ -158,7 +223,7 @@ For complete token definitions and usage examples, see:
 
 **Implementation**:
 ```bash
-Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
+Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
       content="[generated content with @ references]")
 ```
 
@@ -168,8 +233,9 @@ Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.
 TodoWrite({todos: [
   {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
   {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
-  {content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
-  {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
+  {content: "Update role analysis documents with design references", status: "completed", activeForm: "Updating synthesis spec"},
+  {content: "Update relevant role analysis.md documents", status: "completed", activeForm: "Updating role analysis files"},
+  {content: "Create/update ui-designer/design-system-reference.md", status: "completed", activeForm: "Creating design system reference"}
 ]});
 ```
 
@@ -178,8 +244,9 @@ TodoWrite({todos: [
 ✅ Design system references updated for session: WFS-{session}
 
 Updated artifacts:
-✓ synthesis-specification.md - UI/UX Guidelines section with @ references
-✓ ui-designer/style-guide.md - Design system reference guide
+✓ role analysis documents - UI/UX Guidelines section with @ references
+✓ {role_count} role analysis.md files - Design system references
+✓ ui-designer/design-system-reference.md - Design system reference guide
 
 Design system assets ready for /workflow:plan:
 - design-tokens.json | style-guide.md | {prototype_count} reference prototypes
@@ -193,31 +260,43 @@ Next: /workflow:plan [--agent] "<task description>"
 **Updated Files**:
 ```
 .workflow/WFS-{session}/.brainstorming/
-├── synthesis-specification.md       # Updated with UI/UX Guidelines section
-└── ui-designer/
-    └── style-guide.md               # New or updated design reference guide
+├── role analysis documents              # Updated with UI/UX Guidelines section
+├── ui-designer/
+│   ├── analysis*.md                     # Updated with design system references
+│   └── design-system-reference.md       # New or updated design reference guide
+├── ux-expert/analysis*.md               # Updated if animations exist
+├── product-manager/analysis*.md         # Updated if prototypes exist
+└── system-architect/analysis*.md        # Updated if layouts exist
 ```
 
-**@ Reference Format** (synthesis-specification.md):
+**@ Reference Format** (role analysis documents):
 ```
 @../design-{run_id}/style-extraction/style-1/design-tokens.json
 @../design-{run_id}/style-extraction/style-1/style-guide.md
 @../design-{run_id}/prototypes/{prototype}.html
 ```
 
-**@ Reference Format** (ui-designer/style-guide.md):
+**@ Reference Format** (ui-designer/design-system-reference.md):
 ```
 @../../design-{run_id}/style-extraction/style-1/design-tokens.json
 @../../design-{run_id}/style-extraction/style-1/style-guide.md
 @../../design-{run_id}/prototypes/{prototype}.html
 ```
 
+**@ Reference Format** (role analysis.md files):
+```
+@../../design-{run_id}/style-extraction/style-1/design-tokens.json
+@../../design-{run_id}/animation-extraction/animation-tokens.json
+@../../design-{run_id}/layout-extraction/layout-templates.json
+@../../design-{run_id}/prototypes/{prototype}.html
+```
+
 ## Integration with /workflow:plan
 
 After this update, `/workflow:plan` will discover design assets through:
 
 **Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
-- Reads synthesis-specification.md → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
+- Reads role analysis documents → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
 
 **Phase 4: Task Generation** (`/workflow:tools:task-generate`)
 - Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
@@ -239,7 +318,7 @@ After this update, `/workflow:plan` will discover design assets through:
 ## Error Handling
 
 - **Missing design artifacts**: Error with message "Run /workflow:ui-design:style-extract and /workflow:ui-design:generate first"
-- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
+- **role analysis documents not found**: Warning, create minimal version with just UI/UX Guidelines
 - **ui-designer/ directory missing**: Create directory and file
 - **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
 - **Invalid prototype names**: Skip invalid entries, continue with valid ones
@@ -247,9 +326,11 @@ After this update, `/workflow:plan` will discover design assets through:
 ## Validation Checks
 
 After update, verify:
-- [ ] synthesis-specification.md contains UI/UX Guidelines section
+- [ ] role analysis documents contains UI/UX Guidelines section
 - [ ] UI/UX Guidelines include @ references (not content duplication)
-- [ ] ui-designer/style-guide.md created or updated
+- [ ] ui-designer/analysis*.md updated with design system references
+- [ ] ui-designer/design-system-reference.md created or updated
+- [ ] Relevant role analysis.md files updated (ux-expert, product-manager, system-architect)
 - [ ] All @ referenced files exist and are accessible
 - [ ] @ reference paths are relative and correct
 
@@ -264,7 +345,7 @@ After update, verify:
 ## Integration Points
 
 - **Input**: Design system artifacts from `/workflow:ui-design:style-extract` and `/workflow:ui-design:generate`
-- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
+- **Output**: Updated role analysis documents, role analysis.md files, ui-designer/design-system-reference.md with @ references
 - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
 - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
 

.claude/scripts/gemini-wrapper

@@ -1,288 +0,0 @@
-#!/bin/bash
-# gemini-wrapper - Token-aware wrapper for gemini command
-# Location: ~/.claude/scripts/gemini-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: gemini-wrapper [all gemini options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "gemini-wrapper - Token-aware wrapper for gemini command"
-    echo ""
-    echo "Usage: gemini-wrapper [options] [gemini options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set GEMINI_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  gemini-wrapper -p \"Analyze the codebase structure\""
-    echo "  gemini-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  gemini-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${GEMINI_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Respect custom Gemini base URL
-if [[ -n "$GOOGLE_GEMINI_BASE_URL" ]]; then
-    echo -e "${GREEN}🌐 Using custom Gemini base URL: $GOOGLE_GEMINI_BASE_URL${NC}" >&2
-    export GOOGLE_GEMINI_BASE_URL
-fi
-
-# Function to count tokens (approximate: chars/4) - optimized version
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-
-    # Use single find with bulk wc for better performance
-    # Common source file extensions
-    local extensions="py js ts tsx jsx java cpp c h rs go md txt json yaml yml xml html css scss sass php rb sh bash"
-
-    # Build find command with extension patterns
-    local find_cmd="find . -type f \("
-    local first=true
-    for ext in $extensions; do
-        if [[ "$first" == true ]]; then
-            find_cmd+=" -name \"*.$ext\""
-            first=false
-        else
-            find_cmd+=" -o -name \"*.$ext\""
-        fi
-    done
-    find_cmd+=" \)"
-
-    # Exclude common build/cache directories
-    find_cmd+=" -not -path \"*/node_modules/*\""
-    find_cmd+=" -not -path \"*/.git/*\""
-    find_cmd+=" -not -path \"*/dist/*\""
-    find_cmd+=" -not -path \"*/build/*\""
-    find_cmd+=" -not -path \"*/.next/*\""
-    find_cmd+=" -not -path \"*/.nuxt/*\""
-    find_cmd+=" -not -path \"*/target/*\""
-    find_cmd+=" -not -path \"*/vendor/*\""
-    find_cmd+=" -not -path \"*/__pycache__/*\""
-    find_cmd+=" -not -path \"*/.cache/*\""
-    find_cmd+=" 2>/dev/null"
-
-    # Use efficient bulk processing with wc
-    if command -v wc >/dev/null 2>&1; then
-        # Try bulk wc first - much faster for many files
-        local wc_output
-        wc_output=$(eval "$find_cmd" | xargs wc -c 2>/dev/null | tail -n 1)
-
-        # Parse the total line (last line of wc output when processing multiple files)
-        if [[ -n "$wc_output" && "$wc_output" =~ ^[[:space:]]*([0-9]+)[[:space:]]+total[[:space:]]*$ ]]; then
-            total_chars="${BASH_REMATCH[1]}"
-            file_count=$(eval "$find_cmd" | wc -l 2>/dev/null || echo 0)
-        else
-            # Fallback: single file processing
-            while IFS= read -r file; do
-                if [[ -f "$file" && -r "$file" ]]; then
-                    local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-                    total_chars=$((total_chars + chars))
-                    file_count=$((file_count + 1))
-                fi
-            done < <(eval "$find_cmd")
-        fi
-    else
-        # No wc available - fallback method
-        while IFS= read -r file; do
-            if [[ -f "$file" && -r "$file" ]]; then
-                local chars=$(stat -c%s "$file" 2>/dev/null || echo 0)
-                total_chars=$((total_chars + chars))
-                file_count=$((file_count + 1))
-            fi
-        done < <(eval "$find_cmd")
-    fi
-
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-args=()
-i=0
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: gemini ${args[*]}${NC}" >&2
-
-# Execute gemini with adjusted arguments (we're already in the right directory)
-gemini "${args[@]}"

.claude/scripts/qwen-wrapper

@@ -1,228 +0,0 @@
-#!/bin/bash
-# qwen-wrapper - Token-aware wrapper for qwen command
-# Location: ~/.claude/scripts/qwen-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: qwen-wrapper [all qwen options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "qwen-wrapper - Token-aware wrapper for qwen command"
-    echo ""
-    echo "Usage: qwen-wrapper [options] [qwen options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set QWEN_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  qwen-wrapper -p \"Analyze the codebase structure\""
-    echo "  qwen-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  qwen-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${QWEN_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Function to count tokens (approximate: chars/4)
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-    
-    # Count characters in common source files
-    while IFS= read -r -d '' file; do
-        if [[ -f "$file" && -r "$file" ]]; then
-            local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-            total_chars=$((total_chars + chars))
-            file_count=$((file_count + 1))
-        fi
-    done < <(find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.java" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.rs" -o -name "*.go" -o -name "*.md" -o -name "*.txt" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.xml" -o -name "*.html" -o -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.php" -o -name "*.rb" -o -name "*.sh" -o -name "*.bash" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" -not -path "*/.nuxt/*" -not -path "*/target/*" -not -path "*/vendor/*" -print0 2>/dev/null)
-    
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: qwen ${args[*]}${NC}" >&2
-
-# Execute qwen with adjusted arguments (we're already in the right directory)
-qwen "${args[@]}"

.claude/scripts/update_module_claude.sh

@@ -1,14 +1,32 @@
 #!/bin/bash
-# Update CLAUDE.md for a specific module with unified template
-# Usage: update_module_claude.sh <module_path> [update_type] [tool]
+# Update CLAUDE.md for modules with two strategies
+# Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]
+#   strategy: single-layer|multi-layer
 #   module_path: Path to the module directory
-#   update_type: full|related (default: full)
 #   tool: gemini|qwen|codex (default: gemini)
+#   model: Model name (optional, uses tool defaults)
+#
+# Default Models:
+#   gemini: gemini-2.5-flash
+#   qwen: coder-model
+#   codex: gpt5-codex
+#
+# Strategies:
+#   single-layer: Upward aggregation
+#     - Read: Current directory code + child CLAUDE.md files
+#     - Generate: Single ./CLAUDE.md in current directory
+#     - Use: Large projects, incremental bottom-up updates
+#
+#   multi-layer: Downward distribution
+#     - Read: All files in current and subdirectories
+#     - Generate: CLAUDE.md for each directory containing files
+#     - Use: Small projects, full documentation generation
 #
 # Features:
-# - Respects .gitignore patterns (current directory or git root)
-# - Unified template for all modules (folders and files)
-# - Template-based documentation generation
+#   - Minimal prompts based on unified template
+#   - Respects .gitignore patterns
+#   - Path-focused processing (script only cares about paths)
+#   - Template-driven generation
 
 # Build exclusion filters from .gitignore
 build_exclusion_filters() {
@@ -59,15 +77,84 @@ build_exclusion_filters() {
     echo "$filters"
 }
 
+# Scan directory structure and generate structured information
+scan_directory_structure() {
+    local target_path="$1"
+    local strategy="$2"
+
+    if [ ! -d "$target_path" ]; then
+        echo "Directory not found: $target_path"
+        return 1
+    fi
+
+    local exclusion_filters=$(build_exclusion_filters)
+    local structure_info=""
+
+    # Get basic directory info
+    local dir_name=$(basename "$target_path")
+    local total_files=$(eval "find \"$target_path\" -type f $exclusion_filters 2>/dev/null" | wc -l)
+    local total_dirs=$(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="Directory: $dir_name\n"
+    structure_info+="Total files: $total_files\n"
+    structure_info+="Total directories: $total_dirs\n\n"
+
+    if [ "$strategy" = "multi-layer" ]; then
+        # For multi-layer: show all subdirectories with file counts
+        structure_info+="Subdirectories with files:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ] && [ "$dir" != "$target_path" ]; then
+                local rel_path=${dir#$target_path/}
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                if [ $file_count -gt 0 ]; then
+                    structure_info+="  - $rel_path/ ($file_count files)\n"
+                fi
+            fi
+        done < <(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null")
+    else
+        # For single-layer: show direct children only
+        structure_info+="Direct subdirectories:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ]; then
+                local dir_name=$(basename "$dir")
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                local has_claude=$([ -f "$dir/CLAUDE.md" ] && echo " [has CLAUDE.md]" || echo "")
+                structure_info+="  - $dir_name/ ($file_count files)$has_claude\n"
+            fi
+        done < <(eval "find \"$target_path\" -maxdepth 1 -type d $exclusion_filters 2>/dev/null" | grep -v "^$target_path$")
+    fi
+
+    # Show main file types in current directory
+    structure_info+="\nCurrent directory files:\n"
+    local code_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local config_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.toml' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local doc_files=$(eval "find \"$target_path\" -maxdepth 1 -type f -name '*.md' $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="  - Code files: $code_files\n"
+    structure_info+="  - Config files: $config_files\n"
+    structure_info+="  - Documentation: $doc_files\n"
+
+    printf "%b" "$structure_info"
+}
+
 update_module_claude() {
-    local module_path="$1"
-    local update_type="${2:-full}"
+    local strategy="$1"
+    local module_path="$2"
     local tool="${3:-gemini}"
+    local model="$4"
 
     # Validate parameters
-    if [ -z "$module_path" ]; then
-        echo "❌ Error: Module path is required"
-        echo "Usage: update_module_claude.sh <module_path> [update_type]"
+    if [ -z "$strategy" ] || [ -z "$module_path" ]; then
+        echo "❌ Error: Strategy and module path are required"
+        echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
+        echo "Strategies: single-layer|multi-layer"
+        return 1
+    fi
+
+    # Validate strategy
+    if [ "$strategy" != "single-layer" ] && [ "$strategy" != "multi-layer" ]; then
+        echo "❌ Error: Invalid strategy '$strategy'"
+        echo "Valid strategies: single-layer, multi-layer"
         return 1
     fi
 
@@ -76,6 +163,24 @@ update_module_claude() {
         return 1
     fi
 
+    # Set default models if not specified
+    if [ -z "$model" ]; then
+        case "$tool" in
+            gemini)
+                model="gemini-2.5-flash"
+                ;;
+            qwen)
+                model="coder-model"
+                ;;
+            codex)
+                model="gpt5-codex"
+                ;;
+            *)
+                model=""
+                ;;
+        esac
+    fi
+
     # Build exclusion filters from .gitignore
     local exclusion_filters=$(build_exclusion_filters)
 
@@ -85,79 +190,105 @@ update_module_claude() {
         echo "⚠️  Skipping '$module_path' - no files found (after .gitignore filtering)"
         return 0
     fi
-    
+
     # Use unified template for all modules
-    local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt"
-    local analysis_strategy="--all-files"
-    
+    local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/02-document-module-structure.txt"
+
+    # Read template content directly
+    local template_content=""
+    if [ -f "$template_path" ]; then
+        template_content=$(cat "$template_path")
+        echo "   📋 Loaded template: $(wc -l < "$template_path") lines"
+    else
+        echo "   ⚠️  Template not found: $template_path"
+        echo "   Using fallback template..."
+        template_content="Create comprehensive CLAUDE.md documentation following standard structure with Purpose, Structure, Components, Dependencies, Integration, and Implementation sections."
+    fi
+
+    # Scan directory structure first
+    echo "   🔍 Scanning directory structure..."
+    local structure_info=$(scan_directory_structure "$module_path" "$strategy")
+
     # Prepare logging info
     local module_name=$(basename "$module_path")
 
     echo "⚡ Updating: $module_path"
-    echo "   Type: $update_type | Tool: $tool | Files: $file_count"
-    echo "   Template: $(basename "$template_path")"
-    
-    # Generate prompt with template injection
-    local template_content=""
-    if [ -f "$template_path" ]; then
-        template_content=$(cat "$template_path")
-    else
-        echo "   ⚠️  Template not found: $template_path, using fallback"
-        template_content="Update CLAUDE.md documentation for this module: document structure, key components, dependencies, and integration points."
-    fi
-    
-    local update_context=""
-    if [ "$update_type" = "full" ]; then
-        update_context="
-        Update Mode: Complete refresh
-        - Perform comprehensive analysis of all content
-        - Document module structure, dependencies, and key components
-        - Follow template guidelines strictly"
-    else
-        update_context="
-        Update Mode: Context-aware update
-        - Focus on recent changes and affected areas
-        - Maintain consistency with existing documentation
-        - Update only relevant sections
-        - Follow template guidelines for updated content"
-    fi
-    
-    local base_prompt="
-    ⚠️ CRITICAL RULES - MUST FOLLOW:
-    1. ONLY modify CLAUDE.md files
-    2. NEVER modify source code files
-    3. Focus exclusively on updating documentation
-    4. Follow the template guidelines exactly
+    echo "   Strategy: $strategy | Tool: $tool | Model: $model | Files: $file_count"
+    echo "   Template: $(basename "$template_path") ($(echo "$template_content" | wc -l) lines)"
+    echo "   Structure: Scanned $(echo "$structure_info" | wc -l) lines of structure info"
 
-    $template_content
+    # Build minimal strategy-specific prompt with explicit paths and structure info
+    local final_prompt=""
+
+    if [ "$strategy" = "multi-layer" ]; then
+        # multi-layer strategy: read all, generate for each directory
+        final_prompt="Directory Structure Analysis:
+$structure_info
+
+Read: @**/*
+
+Generate CLAUDE.md files:
+- Primary: ./CLAUDE.md (current directory)
+- Additional: CLAUDE.md in each subdirectory containing files
+
+Template Guidelines:
+$template_content
+
+Instructions:
+- Work bottom-up: deepest directories first
+- Parent directories reference children
+- Each CLAUDE.md file must be in its respective directory
+- Follow the template guidelines above for consistent structure
+- Use the structure analysis to understand directory hierarchy"
+    else
+        # single-layer strategy: read current + child CLAUDE.md, generate current only
+        final_prompt="Directory Structure Analysis:
+$structure_info
+
+Read: @*/CLAUDE.md @*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.md @*.json @*.yaml @*.yml
+
+Generate single file: ./CLAUDE.md
+
+Template Guidelines:
+$template_content
+
+Instructions:
+- Create exactly one CLAUDE.md file in the current directory
+- Reference child CLAUDE.md files, do not duplicate their content
+- Follow the template guidelines above for consistent structure
+- Use the structure analysis to understand the current directory context"
+    fi
 
-    $update_context"
-    
     # Execute update
     local start_time=$(date +%s)
     echo "   🔄 Starting update..."
 
     if cd "$module_path" 2>/dev/null; then
         local tool_result=0
-        local final_prompt="$base_prompt
 
-        Module Information:
-        - Name: $module_name
-        - Path: $module_path
-        - Tool: $tool"
-
-        # Execute with selected tool (always use --all-files)
+        # Execute with selected tool
+        # NOTE: Model parameter (-m) is placed AFTER the prompt
         case "$tool" in
             qwen)
-                qwen --all-files --yolo -p "$final_prompt" 2>&1
+                if [ "$model" = "coder-model" ]; then
+                    # coder-model is default, -m is optional
+                    qwen -p "$final_prompt" --yolo 2>&1
+                else
+                    qwen -p "$final_prompt" -m "$model" --yolo 2>&1
+                fi
                 tool_result=$?
                 ;;
             codex)
-                codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
+                codex --full-auto exec "$final_prompt" -m "$model" --skip-git-repo-check -s danger-full-access 2>&1
                 tool_result=$?
                 ;;
-            gemini|*)
-                gemini --all-files --yolo -p "$final_prompt" 2>&1
+            gemini)
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
+                tool_result=$?
+                ;;
+            *)
+                echo "   ⚠️  Unknown tool: $tool, defaulting to gemini"
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
                 tool_result=$?
                 ;;
         esac
@@ -181,5 +312,22 @@ update_module_claude() {
 
 # Execute function if script is run directly
 if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Show help if no arguments or help requested
+    if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+        echo "Usage: update_module_claude.sh <strategy> <module_path> [tool] [model]"
+        echo ""
+        echo "Strategies:"
+        echo "  single-layer    - Read current dir code + child CLAUDE.md, generate ./CLAUDE.md"
+        echo "  multi-layer     - Read all files, generate CLAUDE.md for each directory"
+        echo ""
+        echo "Tools: gemini (default), qwen, codex"
+        echo "Models: Use tool defaults if not specified"
+        echo ""
+        echo "Examples:"
+        echo "  ./update_module_claude.sh single-layer ./src/auth"
+        echo "  ./update_module_claude.sh multi-layer ./components gemini gemini-2.5-flash"
+        exit 0
+    fi
+
     update_module_claude "$@"
-fi
+fi

.claude/skills/command-guide/SKILL.md

@@ -0,0 +1,347 @@
+---
+name: command-guide
+description: Workflow command guide for Claude DMS3 (69 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
+allowed-tools: Read, Grep, Glob, AskUserQuestion
+---
+
+# Command Guide Skill
+
+Comprehensive command guide for Claude DMS3 workflow system covering 69 commands across 4 categories (workflow, cli, memory, task).
+
+## 🧠 Core Principle: Intelligent Integration
+
+**⚠️ IMPORTANT**: This SKILL provides **reference materials** for intelligent integration, NOT templates for direct copying.
+
+**Response Strategy**:
+1. **Analyze user's specific context** - Understand their exact need, workflow stage, and technical level
+2. **Extract relevant information** - Select only the pertinent parts from reference guides
+3. **Synthesize and customize** - Combine multiple sources, add context-specific examples
+4. **Deliver targeted response** - Provide concise, actionable guidance tailored to the user's situation
+
+**Never**:
+- ❌ Copy-paste entire template sections verbatim
+- ❌ Return raw reference documentation without processing
+- ❌ Provide generic responses that ignore user context
+
+**Always**:
+- ✅ Understand the user's specific situation first
+- ✅ Integrate information from multiple sources (indexes, guides, reference docs)
+- ✅ Customize examples and explanations to match user's use case
+- ✅ Provide progressive depth - brief answers with "more detail available" prompts
+
+---
+
+## 🎯 Operation Modes
+
+### Mode 1: Command Search 🔍
+
+**When**: User searches by keyword, category, or use-case
+
+**Triggers**: "搜索命令", "find command", "planning 相关", "search"
+
+**Process**:
+1. Identify search type (keyword/category/use-case)
+2. Query appropriate index (all-commands/by-category/by-use-case)
+3. **Intelligently filter and rank** results based on user's implied context
+4. **Synthesize concise response** with command names, brief descriptions, and use-case fit
+5. **Suggest next steps** - related commands or workflow patterns
+
+**Example**: "搜索 planning 命令" → Analyze user's likely goal → Present top 3-5 most relevant planning commands with context-specific usage hints, NOT raw JSON dump
+
+---
+
+### Mode 2: Smart Recommendations 🤖
+
+**When**: User asks for next steps after a command
+
+**Triggers**: "下一步", "what's next", "after /workflow:plan", "推荐"
+
+**Process**:
+1. **Analyze workflow context** - Understand where user is in their development cycle
+2. Query `index/command-relationships.json` for possible next commands
+3. **Evaluate and prioritize** recommendations based on:
+   - User's stated goals
+   - Common workflow patterns
+   - Project complexity indicators
+4. **Craft contextual guidance** - Explain WHY each recommendation fits, not just WHAT to run
+5. **Provide workflow examples** - Show complete flow, not isolated commands
+
+**Example**: "执行完 /workflow:plan 后做什么？" → Analyze plan output quality → Recommend `/workflow:action-plan-verify` (if complex) OR `/workflow:execute` (if straightforward) with reasoning for each choice
+
+---
+
+### Mode 3: Full Documentation 📖
+
+**When**: User requests command details
+
+**Triggers**: "参数说明", "怎么用", "how to use", "详情"
+
+**Process**:
+1. Locate command in `index/all-commands.json`
+2. Read original command file for full details
+3. **Extract user-relevant sections** - Focus on what they asked about (parameters OR examples OR workflow)
+4. **Enhance with context** - Add use-case specific examples if user's scenario is clear
+5. **Progressive disclosure** - Provide core info first, offer "need more details?" prompts
+
+**Example**: "/workflow:plan 的参数是什么？" → Identify user's experience level → Present parameters with context-appropriate explanations (beginner: verbose + examples; advanced: concise + edge cases), NOT raw documentation dump
+
+---
+
+### Mode 4: Beginner Onboarding 🎓
+
+**When**: New user needs guidance
+
+**Triggers**: "新手", "getting started", "如何开始", "常用命令", **"从0到1"**, **"全新项目"**
+
+**Process**:
+1. **Assess user background** - Ask clarifying questions if needed (coding experience? project type?)
+2. **⚠️ Identify project stage** - FROM-ZERO-TO-ONE vs FEATURE-ADDITION:
+   - **从0到1场景** (全新项目/产品/架构决策) → **MUST START with brainstorming workflow**
+   - **功能新增场景** (已有项目中添加功能) → Start with planning workflow
+3. **Design personalized learning path** based on their goals and stage
+4. **Curate essential commands** from `index/essential-commands.json` - Select 3-5 most relevant for their use case
+5. **Provide guided first example** - Walk through ONE complete workflow with explanation, **emphasizing brainstorming for 0-to-1 scenarios**
+6. **Set clear next steps** - What to try next, where to get help
+
+**Example 1 (从0到1)**: "我是新手，如何开始全新项目？" → Identify as FROM-ZERO-TO-ONE → Emphasize brainstorming workflow (`/workflow:brainstorm:artifacts`) as mandatory first step → Explain brainstorm → plan → execute flow
+
+**Example 2 (功能新增)**: "我是新手，如何在已有项目中添加功能？" → Identify as FEATURE-ADDITION → Guide to planning workflow (`/workflow:plan`) → Explain plan → execute → test flow
+
+**Example 3 (探索)**: "我是新手，如何开始？" → Ask clarifying question: "是全新项目启动（从0到1）还是在已有项目中添加功能？" → Based on answer, route to appropriate workflow
+
+---
+
+### Mode 5: Issue Reporting 📝
+
+**When**: User wants to report issue or request feature
+
+**Triggers**: **"CCW-issue"**, **"CCW-help"**, **"ccw-issue"**, **"ccw-help"**, **"ccw"**, "报告 bug", "功能建议", "问题咨询", "交互式诊断"
+
+**Process**:
+1. **Understand issue context** - Use AskUserQuestion to confirm type AND gather initial context
+2. **Intelligently guide information collection**:
+   - Adapt questions based on previous answers
+   - Skip irrelevant sections
+   - Probe for missing critical details
+3. **Select and customize template**:
+   - `issue-diagnosis.md`, `issue-bug.md`, `issue-feature.md`, or `issue-question.md`
+   - **Adapt template sections** to match user's specific scenario
+4. **Synthesize coherent issue report**:
+   - Integrate collected information with appropriate template sections
+   - **Highlight key details** - Don't bury critical info in boilerplate
+   - Add privacy-protected command history
+5. **Provide actionable next steps** - Immediate troubleshooting OR submission guidance
+
+**Example**: "CCW-issue" → Detect user frustration level → For urgent: fast-track to critical info collection; For exploratory: comprehensive diagnostic flow, NOT one-size-fits-all questionnaire
+
+**🆕 Enhanced Features**:
+- Complete command history with privacy protection
+- Interactive diagnostic checklists
+- Decision tree navigation (diagnosis template)
+- Execution environment capture
+
+---
+
+### Mode 6: Deep Command Analysis 🔬
+
+**When**: User asks detailed questions about specific commands or agents
+
+**Triggers**: "详细说明", "命令原理", "agent 如何工作", "实现细节", specific command/agent name mentioned
+
+**Data Sources**:
+- `reference/agents/*.md` - All agent documentation (11 agents)
+- `reference/commands/**/*.md` - All command documentation (69 commands)
+
+**Process**:
+
+**Simple Query** (direct documentation lookup):
+1. Identify target command/agent from user query
+2. Locate corresponding markdown file in `reference/`
+3. **Extract contextually relevant sections** - Not entire document
+4. **Synthesize focused explanation**:
+   - Address user's specific question
+   - Add context-appropriate examples
+   - Link related concepts
+5. **Offer progressive depth** - "Want to know more about X?"
+
+**Complex Query** (CLI-assisted analysis):
+1. **Detect complexity indicators** (多个命令对比、工作流程分析、最佳实践)
+2. **Design targeted analysis prompt** for gemini/qwen:
+   - Frame user's question precisely
+   - Specify required analysis depth
+   - Request structured comparison/synthesis
+   ```bash
+   gemini -p "
+   PURPOSE: Analyze command documentation to answer user query
+   TASK: [extracted user question with context]
+   MODE: analysis
+   CONTEXT: @**/*
+   EXPECTED: Comprehensive answer with examples and recommendations
+   RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on practical usage | analysis=READ-ONLY
+   " -m gemini-3-pro-preview-11-2025 --include-directories ~/.claude/skills/command-guide/reference
+   ```
+   Note: Use absolute path `~/.claude/skills/command-guide/reference` for reference documentation access
+3. **Process and integrate CLI analysis**:
+   - Extract key insights from CLI output
+   - Add context-specific examples
+   - Synthesize actionable recommendations
+4. **Deliver tailored response** - Not raw CLI output
+
+**Query Classification**:
+- **Simple**: Single command explanation, parameter list, basic usage
+- **Complex**: Cross-command workflows, performance comparison, architectural analysis, best practices across multiple commands
+
+**Examples**:
+
+*Simple Query*:
+```
+User: "action-planning-agent 如何工作？"
+→ Read reference/agents/action-planning-agent.md
+→ **Identify user's knowledge gap** (mechanism? inputs/outputs? when to use?)
+→ **Extract relevant sections** addressing their need
+→ **Synthesize focused explanation** with examples
+→ NOT: Dump entire agent documentation
+```
+
+*Complex Query*:
+```
+User: "对比 workflow:plan 和 workflow:tdd-plan 的使用场景和最佳实践"
+→ Detect: 多命令对比 + 最佳实践
+→ **Design comparison framework** (when to use, trade-offs, workflow integration)
+→ Use gemini to analyze both commands with structured comparison prompt
+→ **Synthesize insights** into decision matrix and usage guidelines
+→ NOT: Raw command documentation side-by-side
+```
+
+---
+
+## 📚 Index Files
+
+All command metadata is stored in JSON indexes for fast querying:
+
+- **all-commands.json** - Complete catalog (69 commands) with full metadata
+- **by-category.json** - Hierarchical organization (workflow/cli/memory/task)
+- **by-use-case.json** - Grouped by scenario (planning/implementation/testing/docs/session)
+- **essential-commands.json** - Top 14 most-used commands
+- **command-relationships.json** - Next-step recommendations and dependencies
+
+📖 Detailed structure: [Index Structure Reference](guides/index-structure.md)
+
+---
+
+## 🗂️ Supporting Guides
+
+- **[Getting Started](guides/getting-started.md)** - 5-minute quickstart for beginners
+- **[Workflow Patterns](guides/workflow-patterns.md)** - Common workflow examples (Plan→Execute, TDD, UI design)
+- **[CLI Tools Guide](guides/cli-tools-guide.md)** - Gemini/Qwen/Codex usage
+- **[Troubleshooting](guides/troubleshooting.md)** - Common issues and solutions
+- **[Implementation Details](guides/implementation-details.md)** - Detailed logic for each mode
+- **[Usage Examples](guides/examples.md)** - Example dialogues and edge cases
+
+## 📦 Reference Documentation
+
+Complete backup of all command and agent documentation for deep analysis:
+
+- **[reference/agents/](reference/agents/)** - 11 agent markdown files with implementation details
+- **[reference/commands/](reference/commands/)** - 69 command markdown files organized by category
+  - `cli/` - CLI tool commands (9 files)
+  - `memory/` - Memory management commands (8 files)
+  - `task/` - Task management commands (4 files)
+  - `workflow/` - Workflow commands (46 files)
+
+**Installation Path**: `~/.claude/skills/command-guide/` (skill designed for global installation)
+
+**Absolute Reference Path**: `~/.claude/skills/command-guide/reference/`
+
+**Usage**: Mode 6 queries these files directly for detailed command/agent analysis, or uses CLI tools (gemini/qwen) with absolute paths for complex cross-command analysis.
+
+---
+
+## 🛠️ Issue Templates
+
+Generate standardized GitHub issue templates with **execution flow emphasis**:
+
+- **[Interactive Diagnosis](templates/issue-diagnosis.md)** - 🆕 Comprehensive diagnostic workflow with decision tree, checklists, and full command history
+- **[Bug Report](templates/issue-bug.md)** - Report command errors with complete execution flow and environment details
+- **[Feature Request](templates/issue-feature.md)** - Suggest improvements with current workflow analysis and pain points
+- **[Question](templates/issue-question.md)** - Ask usage questions with detailed attempt history and context
+
+**All templates now include**:
+- ✅ Complete command history sections (with privacy protection)
+- ✅ Execution environment details
+- ✅ Interactive problem-locating checklists
+- ✅ Structured troubleshooting guidance
+
+Templates are auto-populated during Mode 5 (Issue Reporting) interaction.
+
+---
+
+## 📊 System Statistics
+
+- **Total Commands**: 69
+- **Total Agents**: 11
+- **Categories**: 4 (workflow: 46, cli: 9, memory: 8, task: 4, general: 2)
+- **Use Cases**: 5 (planning, implementation, testing, documentation, session-management)
+- **Difficulty Levels**: 3 (Beginner, Intermediate, Advanced)
+- **Essential Commands**: 14
+- **Reference Docs**: 80 markdown files (11 agents + 69 commands)
+
+---
+
+## 🔧 Maintenance
+
+### Updating Indexes
+
+When commands are added/modified/removed:
+
+```bash
+bash scripts/update-index.sh
+```
+
+This script:
+1. Scans all command files in `../../commands/`
+2. Extracts metadata from YAML frontmatter
+3. Analyzes command relationships
+4. Regenerates all 5 index files
+
+### Committing Updates
+
+```bash
+git add .claude/skills/command-guide/index/
+git commit -m "docs: update command indexes"
+git push
+```
+
+Team members get latest indexes via `git pull`.
+
+---
+
+## 📖 Related Documentation
+
+- [Workflow Architecture](../../workflows/workflow-architecture.md) - System design overview
+- [Intelligent Tools Strategy](../../workflows/intelligent-tools-strategy.md) - CLI tool selection
+- [Context Search Strategy](../../workflows/context-search-strategy.md) - Search patterns
+- [Task Core](../../workflows/task-core.md) - Task system fundamentals
+
+---
+
+**Version**: 1.3.1 (Path configuration for global installation)
+**Last Updated**: 2025-11-06
+**Maintainer**: Claude DMS3 Team
+
+**Changelog v1.3.1**:
+- ✅ Updated all paths to use absolute paths (`~/.claude/skills/command-guide/`)
+- ✅ CLI commands now use `--include-directories` with absolute reference path
+- ✅ Ensures skill works correctly when installed in `~/.claude/skills/`
+
+**Changelog v1.3.0**:
+- ✅ Added Mode 6: Deep Command Analysis with CLI-assisted queries
+- ✅ Created reference documentation backup (80 files: 11 agents + 69 commands)
+- ✅ Support simple queries (direct file lookup) and complex queries (CLI analysis)
+- ✅ Integrated gemini/qwen for cross-command analysis and best practices
+
+**Changelog v1.2.0**:
+- ✅ Added Interactive Diagnosis template with decision tree
+- ✅ Enhanced all templates with complete command history sections
+- ✅ Added privacy protection guidelines for sensitive information
+- ✅ Integrated execution flow emphasis across all issue templates

.claude/skills/command-guide/guides/cli-tools-guide.md

@@ -0,0 +1,410 @@
+# CLI 工具使用指南
+
+> **SKILL 参考文档**：用于回答用户关于 CLI 工具（Gemini、Qwen、Codex）的使用问题
+>
+> **用途**：当用户询问 CLI 工具的能力、使用方法、调用方式时，从本文档中提取相关信息，根据用户具体需求加工后返回
+
+## 🎯 快速理解：CLI 工具是什么？
+
+CLI 工具是集成在 Claude DMS3 中的**智能分析和执行助手**。
+
+**工作流程**：
+1. **用户** → 用自然语言向 Claude Code 描述需求（如"分析认证模块的安全性"）
+2. **Claude Code** → 识别用户意图，决定使用哪种方式：
+   - **CLI 工具语义调用**：生成并执行 `gemini`/`qwen`/`codex` 命令
+   - **Slash 命令调用**：执行预定义的工作流命令（如 `/workflow:plan`）
+3. **工具** → 自动完成任务并返回结果
+
+**核心理念**：用户用自然语言描述需求 → Claude Code 选择最佳方式 → 工具执行 → 返回结果
+
+---
+
+## 📋 三大工具能力对比
+
+| 工具 | 擅长领域 | 典型场景 | 何时使用 |
+|------|----------|----------|----------|
+| **Gemini** | 分析、理解、规划 | 代码分析、架构设计、问题诊断 | 需要深入理解代码或系统 |
+| **Qwen** | 分析、备选方案 | 代码审查、模式识别 | Gemini 不可用时的备选 |
+| **Codex** | 实现、测试、执行 | 功能开发、测试生成、自动化任务 | 需要生成代码或自动执行 |
+
+**简单记忆**：
+- 想**理解**什么 → Gemini / Qwen
+- 想**实现**什么 → Codex
+
+---
+
+## 🚀 Claude Code 的两种响应方式
+
+当用户用自然语言描述需求时，Claude Code 会根据任务特性选择最佳方式：
+
+### 方式 1：CLI 工具语义调用（灵活、强大）
+
+**用户明确指示使用 CLI 工具**，Claude Code 生成并执行相应命令。
+
+#### 示例 1：Gemini 语义分析
+
+**用户输入**（必须明确提到工具）：
+```
+使用 gemini 分析认证模块的安全性，识别潜在的安全漏洞，
+关注 JWT 令牌处理、密码存储、会话管理等方面，
+提供具体的修复建议
+```
+
+**Claude Code 生成并执行**（CLI 命令）：
+```bash
+cd src/auth && gemini -p "
+分析认证模块的安全性，识别潜在的安全漏洞，
+关注 JWT 令牌处理、密码存储、会话管理等方面，
+提供具体的修复建议
+" -m gemini-3-pro-preview-11-2025
+```
+
+**工具输出**：Gemini 自动理解任务，组合多个分析步骤，返回结构化报告
+
+---
+
+#### 示例 2：Qwen 语义分析（Gemini 的备选）
+
+**用户输入**：
+```
+用 qwen 追踪用户登录的完整执行流程，
+从 API 入口到数据库查询，
+列出所有调用的函数和依赖关系
+```
+
+**Claude Code 生成并执行**：
+```bash
+cd src/auth && qwen -p "
+追踪用户登录的完整执行流程，
+从 API 入口到数据库查询，
+列出所有调用的函数和依赖关系
+" -m coder-model
+```
+
+**工具输出**：Qwen 理解需求，自动追踪执行路径
+
+---
+
+#### 示例 3：Codex 语义实现
+
+**用户输入**：
+```
+让 codex 实现 JWT 令牌刷新机制：
+1. 添加 refreshToken 端点
+2. 验证旧令牌的有效性
+3. 生成新的访问令牌
+4. 确保安全性（防重放攻击）
+```
+
+**Claude Code 生成并执行**：
+```bash
+codex -C src/auth --full-auto exec "
+实现 JWT 令牌刷新机制：
+1. 添加 refreshToken 端点
+2. 验证旧令牌的有效性
+3. 生成新的访问令牌
+4. 确保安全性（防重放攻击）
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+**工具输出**：Codex 理解需求，自动生成代码并集成到现有系统
+
+---
+
+**核心特点**：
+- ✅ **用户明确指定工具**：必须说"使用 gemini"、"用 qwen"、"让 codex"等触发工具调用
+- ✅ **Claude 生成命令**：识别工具名称后，自动构造最优的 CLI 工具调用
+- ✅ **工具自动理解**：CLI 工具解析需求，组合分析/实现步骤
+- ✅ **灵活强大**：不受预定义工作流限制
+- ✅ **精确控制**：Claude 可指定工作目录、文件范围、模型参数
+
+**触发方式**：
+- "使用 gemini ..."
+- "用 qwen ..."
+- "让 codex ..."
+- "通过 gemini 工具..."
+
+**Claude Code 何时选择此方式**：
+- 用户明确指定使用某个 CLI 工具
+- 复杂分析任务（跨模块、多维度）
+- 自定义工作流需求
+- 需要精确控制上下文范围
+
+---
+
+### 方式 2：Slash 命令调用（标准工作流）
+
+**用户直接输入 Slash 命令**，或 **Claude Code 建议使用 Slash 命令**，系统执行预定义工作流（内部调用 CLI 工具）。
+
+#### Workflow 类命令（系统自动选择工具）
+
+**示例 1：规划任务**
+
+**用户输入**：
+```
+/workflow:plan --agent "实现用户认证功能"
+```
+
+**系统执行**：内部调用 gemini/qwen 分析 + action-planning-agent 生成任务
+
+---
+
+**示例 2：执行任务**
+
+**用户输入**：
+```
+/workflow:execute
+```
+
+**系统执行**：内部调用 codex 实现代码
+
+---
+
+**示例 3：生成测试**
+
+**用户输入**：
+```
+/workflow:test-gen WFS-xxx
+```
+
+**系统执行**：内部调用 gemini 分析 + codex 生成测试
+
+---
+
+#### CLI 类命令（指定工具）
+
+**示例 1：封装的分析命令**
+
+**用户输入**：
+```
+/cli:analyze --tool gemini "分析认证模块"
+```
+
+**系统执行**：使用 gemini 工具进行分析
+
+---
+
+**示例 2：封装的执行命令**
+
+**用户输入**：
+```
+/cli:execute --tool codex "实现 JWT 刷新"
+```
+
+**系统执行**：使用 codex 工具实现功能
+
+---
+
+**示例 3：快速执行（YOLO 模式）**
+
+**用户输入**：
+```
+/cli:codex-execute "添加用户头像上传"
+```
+
+**系统执行**：使用 codex 快速实现
+
+---
+
+**核心特点**：
+- ✅ **用户可直接输入**：Slash 命令格式固定，用户可以直接输入（如 `/workflow:plan`）
+- ✅ **Claude 可建议**：Claude Code 也可以识别需求后建议或执行 Slash 命令
+- ✅ **预定义流程**：标准化的工作流模板
+- ✅ **自动工具选择**：workflow 命令内部自动选择合适的 CLI 工具
+- ✅ **集成完整**：包含规划、执行、测试、文档等环节
+- ✅ **简单易用**：无需了解底层 CLI 工具细节
+
+**Claude Code 何时选择此方式**：
+- 标准开发任务（功能开发、测试、重构）
+- 团队协作（统一工作流）
+- 适合新手（降低学习曲线）
+- 快速开发（减少配置时间）
+
+---
+
+## 🔄 两种方式对比
+
+| 维度 | CLI 工具语义调用 | Slash 命令调用 |
+|------|------------------|----------------|
+| **用户输入** | 纯自然语言描述需求 | `/` 开头的固定命令格式 |
+| **Claude Code 行为** | 生成并执行 `gemini`/`qwen`/`codex` 命令 | 执行预定义工作流（内部调用 CLI 工具） |
+| **灵活性** | 完全自定义任务和执行方式 | 固定工作流模板 |
+| **学习曲线** | 用户无需学习（纯自然语言） | 需要知道 Slash 命令名称 |
+| **适用复杂度** | 复杂、探索性、定制化任务 | 标准、重复性、工作流化任务 |
+| **工具选择** | Claude 自动选择最佳 CLI 工具 | 系统自动选择（workflow 类）<br>或用户指定（cli 类） |
+| **典型场景** | 深度分析、自定义流程、探索研究 | 日常开发、团队协作、标准流程 |
+
+**使用建议**：
+- **日常开发** → 优先使用 Slash 命令（标准化、快速）
+- **复杂分析** → Claude 自动选择 CLI 工具语义调用（灵活、强大）
+- **用户角度** → 只需用自然语言描述需求，Claude Code 会选择最佳方式
+
+---
+
+## 💡 工具能力速查
+
+### Gemini - 分析与规划
+- 执行流程追踪、依赖分析、代码模式识别
+- 架构设计、技术方案评估、任务分解
+- 文档生成（API 文档、模块说明）
+
+**触发示例**：`使用 gemini 追踪用户登录的完整流程`
+
+---
+
+### Qwen - Gemini 的备选
+- 代码分析、模式识别、架构评审
+- 作为 Gemini 不可用时的备选方案
+
+**触发示例**：`用 qwen 分析数据处理模块`
+
+---
+
+### Codex - 实现与执行
+- 功能开发、组件实现、API 创建
+- 单元测试、集成测试、TDD 支持
+- 代码重构、性能改进、Bug 修复
+
+**触发示例**：`让 codex 实现用户注册功能，包含邮箱验证`
+
+---
+
+## 🔄 典型使用场景
+
+### 场景 1：理解陌生代码库
+
+**需求**：接手新项目，需要快速理解代码结构
+
+**方式 1：CLI 工具语义调用**（推荐，灵活）
+
+- **用户输入**：`使用 gemini 分析这个项目的架构设计，识别主要模块、依赖关系和架构模式`
+- **Claude Code 生成并执行**：`cd project-root && gemini -p "..." -m gemini-3-pro-preview-11-2025`
+
+**方式 2：Slash 命令**
+- **用户输入**：`/cli:analyze --tool gemini "分析项目架构"`
+
+---
+
+### 场景 2：实现新功能
+
+**需求**：实现用户认证功能
+
+**方式 1：CLI 工具语义调用**
+- **用户输入**：`让 codex 实现用户认证功能：注册（邮箱+密码+验证）、登录（JWT token）、刷新令牌，技术栈 Node.js + Express`
+- **Claude Code 生成并执行**：`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
+
+**方式 2：Slash 命令**（工作流化）
+- **用户输入**：`/workflow:plan --agent "实现用户认证功能"` → `/workflow:execute`
+
+---
+
+### 场景 3：诊断 Bug
+
+**需求**：登录功能偶尔超时
+
+**方式 1：CLI 工具语义调用**
+- **用户输入**：`使用 gemini 诊断登录超时问题，分析处理流程、性能瓶颈、数据库查询效率`
+- **Claude Code 生成并执行**：`cd src/auth && gemini -p "..." -m gemini-3-pro-preview-11-2025`
+- **用户输入**：`让 codex 根据上述分析修复登录超时，优化查询、添加缓存`
+- **Claude Code 生成并执行**：`codex -C src/auth --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access`
+
+**方式 2：Slash 命令**
+- **用户输入**：`/cli:mode:bug-diagnosis --tool gemini "诊断登录超时"` → `/cli:execute --tool codex "修复登录超时"`
+
+---
+
+### 场景 4：生成文档
+
+**需求**：为 API 模块生成完整文档
+
+**方式 1：CLI 工具语义调用**
+- **用户输入**：`使用 gemini 为 API 模块生成技术文档，包含端点说明、数据模型、使用示例`
+- **Claude Code 生成并执行**：`cd src/api && gemini -p "..." -m gemini-3-pro-preview-11-2025 --approval-mode yolo`
+
+**方式 2：Slash 命令**
+- **用户输入**：`/memory:docs src/api --tool gemini --mode full`
+
+---
+
+## 🎯 常用工作流程
+
+### 简单 Bug 修复
+```
+使用 gemini 诊断问题（可选其他 cli 工具）
+→ Claude 分析
+→ Claude 直接执行修复
+```
+
+### 复杂 Bug 修复
+```
+/cli:mode:plan 或 /cli:mode:bug-diagnosis
+→ Claude 分析
+→ Claude 执行修复
+```
+
+### 简单功能增加
+```
+/cli:mode:plan
+→ Claude 执行
+```
+
+### 复杂功能增加
+```
+/cli:mode:plan --agent
+→ Claude 执行 或 /cli:codex-execute
+
+或
+
+/cli:mode:plan
+→ 进入工作流模式（/workflow:execute）
+```
+
+### 项目内存管理
+
+**建立技术栈文档**（为项目提供技术参考）
+```
+/memory:tech-research [session-id | tech-stack-name]
+```
+
+**为项目重建多级结构的 CLAUDE.md 内存**
+```
+/memory:docs [path] [--tool gemini|qwen|codex] [--mode full|partial]
+```
+
+---
+
+## 📚 常用命令速查
+
+| 需求 | 推荐命令 |
+|------|----------|
+| **代码分析** | `使用 gemini 分析...` 或 `/cli:analyze --tool gemini` |
+| **Bug 诊断** | `/cli:mode:bug-diagnosis` |
+| **功能实现** | `/cli:codex-execute` 或 `让 codex 实现...` |
+| **架构规划** | `/cli:mode:plan` |
+| **生成测试** | `/workflow:test-gen WFS-xxx` |
+| **完整工作流** | `/workflow:plan` → `/workflow:execute` |
+| **技术文档** | `/memory:tech-research [tech-name]` |
+| **项目文档** | `/memory:docs [path]` |
+
+---
+
+## 🆘 快速提示
+
+**触发 CLI 工具语义调用**：
+- "使用 gemini ..."
+- "用 qwen ..."
+- "让 codex ..."
+
+**选择工具**：
+- **理解/分析/规划** → Gemini
+- **实现/测试/执行** → Codex
+- **不确定** → 使用 Slash 命令让系统选择
+
+**提升质量**：
+- 清晰描述需求和期望
+- 提供上下文信息
+- 使用 `--agent` 处理复杂任务
+
+---
+
+**最后更新**: 2025-11-06

.claude/skills/command-guide/guides/examples.md

@@ -0,0 +1,537 @@
+# Usage Examples
+
+Comprehensive examples of command-guide skill in action across all 5 operation modes.
+
+---
+
+## Mode 1: Command Search 🔍
+
+### Example 1: Keyword Search
+
+**User**: "搜索包含 'execute' 的命令"
+
+**Skill Response**:
+```
+找到 4 个相关命令：
+
+1. **cli:execute** (高级)
+   描述: Auto-execution of implementation tasks with YOLO permissions
+   参数: [--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id
+   场景: implementation
+
+2. **task:execute** (中级)
+   描述: Execute tasks with appropriate agents and context-aware orchestration
+   参数: task-id
+   场景: implementation
+
+3. **workflow:execute** (中级)
+   描述: Coordinate agents for existing workflow tasks with automatic discovery
+   参数: [--resume-session="session-id"]
+   场景: implementation
+
+4. **codex-execute** (高级)
+   描述: Automated task decomposition and execution with Codex
+   参数: task description or task-id
+   场景: implementation
+
+💡 相关命令: workflow:plan, task:create
+📖 详细文档: [Implementation Commands](workflow-patterns.md#implementation)
+```
+
+---
+
+### Example 2: Category Search
+
+**User**: "cli 类别下有哪些命令？"
+
+**Skill Response**:
+```
+CLI 类别包含 9 个命令：
+
+**核心命令** (6个):
+- cli:analyze - Quick codebase analysis
+- cli:chat - Direct codebase interaction
+- cli:execute - Auto-execution with YOLO
+- cli:cli-init - Initialize CLI tool configs
+- cli:codex-execute - Codex-powered execution
+- cli:discuss-plan - Multi-model planning discussion
+
+**模式命令** (3个):
+- cli:mode:plan - Project planning mode
+- cli:mode:code-analysis - Deep code analysis mode
+- cli:mode:bug-diagnosis - Bug diagnosis mode
+
+📚 使用指南: [CLI Tools Guide](cli-tools-guide.md)
+```
+
+---
+
+### Example 3: Use-Case Search
+
+**User**: "planning 相关的命令有哪些？"
+
+**Skill Response**:
+```
+Planning 场景包含 8 个命令：
+
+**核心规划**:
+1. workflow:plan (高级) - 5阶段规划工作流
+2. cli:mode:plan (高级) - 项目规划和架构分析
+3. workflow:tdd-plan (高级) - TDD 规划工作流
+
+**任务分解**:
+4. task:breakdown (中级) - 智能任务分解
+5. workflow:tools:task-generate (中级) - 生成任务 JSON
+
+**架构设计**:
+6. workflow:brainstorm:system-architect (中级) - 系统架构师头脑风暴
+7. workflow:brainstorm:api-designer (中级) - API 设计师头脑风暴
+
+**评估验证**:
+8. workflow:action-plan-verify (中级) - 规划质量验证
+
+💡 常见工作流: Plan → Verify → Execute
+📖 模式参考: [Workflow Patterns](workflow-patterns.md#planning-workflow)
+```
+
+---
+
+## Mode 2: Smart Recommendations 🤖
+
+### Example 1: After Planning
+
+**User**: "执行完 /workflow:plan 后下一步做什么？"
+
+**Skill Response**:
+```
+推荐的后续步骤：
+
+**🎯 主要选择**:
+1. **/workflow:execute** - 开始执行规划的任务
+   ✅ 这是最常见的下一步
+   作用: 实际执行 workflow:plan 生成的任务
+
+**📋 可选步骤**:
+2. **/workflow:action-plan-verify** - 验证规划质量
+   作用: 在执行前检查规划的一致性和完整性
+   建议: 重要项目建议先验证
+
+3. **/workflow:status** - 查看规划状态
+   作用: 查看生成的任务和当前进度
+
+**📚 完整工作流模式**:
+Plan → Verify (可选) → Execute → Review
+
+详见: [Planning Workflow Pattern](workflow-patterns.md#planning-execution)
+```
+
+---
+
+### Example 2: After Execution
+
+**User**: "workflow:execute 执行完成后，推荐做什么？"
+
+**Skill Response**:
+```
+推荐的后续步骤：
+
+**🎯 主要选择**:
+1. **/workflow:review** - 审查实现结果
+   ✅ 检查代码质量、安全性、架构
+   参数: [--type=quality|security|architecture]
+
+**📊 可选步骤**:
+2. **/workflow:status** - 查看执行状态
+   作用: 确认所有任务都已完成
+
+3. **/workflow:test-gen** - 生成测试
+   作用: 为实现的功能创建测试用例
+
+4. **/workflow:session:complete** - 完成会话
+   作用: 标记工作流已完成，归档经验
+
+**🔄 如果需要修改**:
+- /task:replan - 重新规划某个任务
+- /workflow:resume - 恢复工作流
+
+详见: [Execution Review Pattern](workflow-patterns.md#execution-review)
+```
+
+---
+
+## Mode 3: Full Documentation 📖
+
+### Example 1: Command Parameters
+
+**User**: "/workflow:plan 的参数是什么？"
+
+**Skill Response**:
+```
+# workflow:plan
+
+**描述**: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
+
+**参数**:
+```bash
+/workflow:plan [--agent] [--cli-execute] "text description"|file.md
+```
+
+**参数说明**:
+- `--agent` (可选): 使用 agent 模式执行规划
+- `--cli-execute` (可选): 允许在规划阶段执行 CLI 命令
+- `"text description"`: 任务描述文本
+- `file.md`: 或者提供任务描述文件路径
+
+**使用场景**: planning
+**难度级别**: 高级
+
+**使用示例**:
+```bash
+# 基本用法
+/workflow:plan "实现用户认证功能"
+
+# 使用 agent 模式
+/workflow:plan --agent "重构支付模块"
+
+# 从文件读取
+/workflow:plan --agent feature-spec.md
+
+# 允许 CLI 执行
+/workflow:plan --cli-execute "添加搜索功能"
+```
+
+**执行流程**:
+1. 上下文收集
+2. 概念规划
+3. 实现规划
+4. 任务生成
+5. 质量验证
+
+**相关命令**:
+- workflow:execute - 执行规划的任务
+- workflow:action-plan-verify - 验证规划质量
+- workflow:status - 查看规划状态
+
+**详细文档**: ../../commands/workflow/plan.md
+```
+
+---
+
+## Mode 4: Beginner Onboarding 🎓
+
+### Example 1: Complete Beginner
+
+**User**: "我是新手，如何开始使用工作流系统？"
+
+**Skill Response**:
+```
+欢迎使用 Claude DMS3 工作流系统！🎉
+
+## 🚀 快速开始（3 步）
+
+### Step 1: 了解核心命令（Top 5）
+
+1. **/workflow:plan** - 规划一个功能或任务
+   用法: /workflow:plan "你想做的事情"
+
+2. **/workflow:execute** - 执行规划的任务
+   用法: /workflow:execute
+
+3. **/cli:execute** - 快速自动执行
+   用法: /cli:execute "实现XXX功能"
+
+4. **/task:create** - 创建单个任务
+   用法: /task:create "任务标题"
+
+5. **/enhance-prompt** - 优化你的提示词
+   用法: /enhance-prompt "你的想法"
+
+### Step 2: 尝试第一个工作流
+
+```bash
+# 1. 规划一个简单功能
+/workflow:plan "添加用户登录功能"
+
+# 2. 执行规划
+/workflow:execute
+
+# 3. 审查结果
+/workflow:review
+```
+
+### Step 3: 学习资源
+
+📖 **必读指南**:
+- [5分钟快速开始](getting-started.md)
+- [常见工作流模式](workflow-patterns.md)
+
+🛠️ **工具指南**:
+- [CLI 工具使用](cli-tools-guide.md)
+- [问题排查](troubleshooting.md)
+
+💡 **下一步建议**:
+1. 阅读 getting-started.md（5分钟）
+2. 尝试上面的第一个工作流
+3. 探索更多命令: 询问 "常用命令有哪些"
+
+有问题随时问 "CCW-help"！
+```
+
+---
+
+### Example 2: Intermediate User
+
+**User**: "常用命令有哪些？"
+
+**Skill Response**:
+```
+## 核心命令列表（Top 14）
+
+### 🎯 工作流管理 (5个)
+1. workflow:plan - 5阶段规划
+2. workflow:execute - 执行任务
+3. workflow:review - 审查实现
+4. workflow:tdd-plan - TDD 规划
+5. workflow:test-gen - 生成测试
+
+### 🛠️ CLI 工具 (3个)
+6. cli:execute - 自动执行
+7. cli:mode:plan - 规划模式
+8. cli:analyze - 代码分析
+
+### 📋 任务管理 (3个)
+9. task:create - 创建任务
+10. task:execute - 执行任务
+11. task:breakdown - 分解任务
+
+### 🔧 实用工具 (2个)
+12. enhance-prompt - 提示词增强
+13. version - 版本信息
+
+### 💡 使用频率
+- **每天**: workflow:plan, workflow:execute, cli:execute
+- **经常**: task:create, enhance-prompt
+- **按需**: workflow:review, test-gen, tdd-plan
+
+📚 详细文档: [Index Structure](index-structure.md#essential-commands)
+```
+
+---
+
+## Mode 5: Issue Reporting 📝
+
+### Example 1: Bug Report
+
+**User**: "CCW-issue"
+
+**Skill (Interactive)**:
+```
+请选择问题类型：
+1. 🐛 Bug 报告
+2. ✨ 功能请求
+3. ❓ 问题咨询
+```
+
+**User**: "1"
+
+**Skill**:
+```
+好的，我将帮您创建 Bug 报告。请回答以下问题：
+
+1. 简要描述问题：
+```
+
+**User**: "/workflow:plan 执行后没有生成任务文件"
+
+**Skill**:
+```
+2. 您执行的完整命令是什么？
+```
+
+**User**: "/workflow:plan '添加登录功能'"
+
+**Skill**:
+```
+3. 期望的结果是什么？
+```
+
+**User**: "应该在 .workflow/ 目录生成 task.json"
+
+**Skill**:
+```
+4. 实际发生了什么？
+```
+
+**User**: "命令执行了但没有生成文件"
+
+**Skill**:
+```
+✅ Bug 报告已生成！
+
+文件路径: templates/.generated/bug-2025-01-06-123456.md
+
+--- 报告内容 ---
+# Bug 报告
+
+## 问题描述
+/workflow:plan 执行后没有生成任务文件
+
+## 执行的命令
+```bash
+/workflow:plan '添加登录功能'
+```
+
+## 期望行为
+应该在 .workflow/ 目录生成 task.json
+
+## 实际行为
+命令执行了但没有生成文件
+
+## 环境信息
+- 操作系统: Windows
+- 报告日期: 2025-01-06
+- 相关命令: /workflow:plan
+
+---
+
+**下一步操作**:
+1. 复制以上内容到 GitHub Issues
+2. 或使用: gh issue create -F templates/.generated/bug-2025-01-06-123456.md
+
+需要更多帮助？使用 "CCW-help"
+```
+
+---
+
+### Example 2: Feature Request
+
+**User**: "我想提个功能建议"
+
+**Skill (Interactive)**:
+```
+请选择问题类型：
+1. 🐛 Bug 报告
+2. ✨ 功能请求
+3. ❓ 问题咨询
+```
+
+**User**: "2"
+
+**Skill**:
+```
+好的，功能请求。请描述：
+
+1. 您希望添加什么功能？
+```
+
+**User**: "希望 /workflow:plan 能自动估算任务时间"
+
+**Skill**:
+```
+2. 这个功能解决什么问题？
+```
+
+**User**: "帮助更好地规划项目进度和资源分配"
+
+**Skill**:
+```
+3. 具体的使用场景是什么？（可选）
+```
+
+**User**: "规划大型项目时，能看到预计完成时间"
+
+**Skill**:
+```
+✅ 功能请求已生成！
+
+文件路径: templates/.generated/feature-2025-01-06-123457.md
+
+--- 内容预览 ---
+# 功能请求
+
+## 功能概述
+希望 /workflow:plan 能自动估算任务时间
+
+## 问题背景
+帮助更好地规划项目进度和资源分配
+
+## 使用场景
+规划大型项目时，能看到预计完成时间
+
+## 优先级
+- [ ] 高 - 严重影响工作效率
+- [x] 中 - 有明显改善但有变通方案
+- [ ] 低 - 锦上添花
+
+---
+
+可以复制到 GitHub 提交，或使用:
+gh issue create -F templates/.generated/feature-2025-01-06-123457.md
+```
+
+---
+
+## Edge Cases & Error Handling
+
+### Case 1: No Results Found
+
+**User**: "搜索 xyz 命令"
+
+**Skill**:
+```
+❌ 未找到包含 "xyz" 的命令
+
+💡 建议：
+1. 尝试更广泛的关键词（如 "plan", "execute", "test"）
+2. 按类别浏览：workflow, cli, memory, task
+3. 查看所有常用命令：询问 "常用命令"
+4. 需要帮助：使用 "CCW-help"
+
+📚 快速参考：[All Commands Index](index-structure.md#all-commands)
+```
+
+---
+
+### Case 2: Ambiguous Query
+
+**User**: "命令"
+
+**Skill**:
+```
+您想了解什么？请选择：
+
+1. 🔍 搜索特定命令
+2. 🤖 获取命令推荐
+3. 📖 查看命令文档
+4. 🎓 新手入门指导
+5. 📝 报告问题或建议
+
+或者直接说出具体需求，例如：
+- "搜索 planning 命令"
+- "执行完 /workflow:plan 下一步做什么"
+- "/task:create 怎么用"
+```
+
+---
+
+### Case 3: Multiple Matches
+
+**User**: "execute 命令"
+
+**Skill**:
+```
+找到多个相关命令，请选择您需要的：
+
+1. **cli:execute** - CLI 自动执行（推荐新手）
+2. **task:execute** - 执行单个任务
+3. **workflow:execute** - 执行整个工作流
+
+或者询问：
+- "cli:execute 的详细文档"
+- "三者有什么区别"
+- "我该用哪个"
+```
+
+---
+
+**Last Updated**: 2025-01-06

.claude/skills/command-guide/guides/getting-started.md

@@ -0,0 +1,242 @@
+# 5分钟快速上手指南
+
+> 欢迎使用 Claude DMS3！本指南将帮助您快速上手，5分钟内开始第一个工作流。
+
+## 🎯 Claude DMS3 是什么？
+
+Claude DMS3 是一个**智能开发管理系统**，集成了 69 个命令，帮助您：
+- 📋 规划和分解复杂任务
+- ⚡ 自动化代码实现
+- 🧪 生成和执行测试
+- 📚 生成项目文档
+- 🤖 使用 AI 工具（Gemini、Qwen、Codex）加速开发
+
+**核心理念**：用自然语言描述需求 → 系统自动规划和执行 → 获得结果
+
+---
+
+## 🚀 最常用的14个命令
+
+### 工作流类（必会）
+
+| 命令 | 用途 | 何时使用 |
+|------|------|----------|
+| `/workflow:plan` | 规划任务 | 开始新功能、新项目 |
+| `/workflow:execute` | 执行任务 | plan 之后，实现功能 |
+| `/workflow:test-gen` | 生成测试 | 实现完成后，生成测试 |
+| `/workflow:status` | 查看进度 | 查看工作流状态 |
+| `/workflow:resume` | 恢复任务 | 继续之前的工作流 |
+
+### CLI 工具类（常用）
+
+| 命令 | 用途 | 何时使用 |
+|------|------|----------|
+| `/cli:analyze` | 代码分析 | 理解代码、分析架构 |
+| `/cli:execute` | 执行实现 | 精确控制实现过程 |
+| `/cli:codex-execute` | 自动化实现 | 快速实现功能 |
+| `/cli:chat` | 问答交互 | 询问代码库问题 |
+
+### Memory 类（知识管理）
+
+| 命令 | 用途 | 何时使用 |
+|------|------|----------|
+| `/memory:docs` | 生成文档 | 生成模块文档 |
+| `/memory:load` | 加载上下文 | 获取任务相关上下文 |
+
+### Task 类（任务管理）
+
+| 命令 | 用途 | 何时使用 |
+|------|------|----------|
+| `/task:create` | 创建任务 | 手动创建单个任务 |
+| `/task:execute` | 执行任务 | 执行特定任务 |
+
+---
+
+## 📝 第一个工作流：实现一个新功能
+
+让我们通过一个实际例子来体验完整的工作流：**实现用户登录功能**
+
+### 步骤 1：规划任务
+
+```bash
+/workflow:plan --agent "实现用户登录功能，包括邮箱密码验证和JWT令牌"
+```
+
+**发生什么**：
+- 系统分析需求
+- 自动生成任务计划（IMPL_PLAN.md）
+- 创建多个子任务（task JSON 文件）
+- 返回 workflow session ID（如 WFS-20251106-xxx）
+
+**你会看到**：
+- ✅ 规划完成
+- 📋 任务列表（如：task-001-user-model, task-002-login-api 等）
+- 📁 Session 目录创建
+
+---
+
+### 步骤 2：执行实现
+
+```bash
+/workflow:execute
+```
+
+**发生什么**：
+- 系统自动发现最新的 workflow session
+- 按顺序执行所有任务
+- 使用 Codex 自动生成代码
+- 实时显示进度
+
+**你会看到**：
+- ⏳ Task 1 执行中...
+- ✅ Task 1 完成
+- ⏳ Task 2 执行中...
+- （依次执行所有任务）
+
+---
+
+### 步骤 3：生成测试
+
+```bash
+/workflow:test-gen WFS-20251106-xxx
+```
+
+**发生什么**：
+- 分析实现的代码
+- 生成测试策略
+- 创建测试任务
+
+---
+
+### 步骤 4：查看状态
+
+```bash
+/workflow:status
+```
+
+**发生什么**：
+- 显示当前工作流状态
+- 列出所有任务及其状态
+- 显示已完成/进行中/待执行任务
+
+---
+
+## 🎓 其他常用场景
+
+### 场景 1：快速代码分析
+
+**需求**：理解陌生代码
+
+```bash
+# 分析整体架构
+/cli:analyze --tool gemini "分析项目架构和模块关系"
+
+# 追踪执行流程
+/cli:mode:code-analysis --tool gemini "追踪用户注册的执行流程"
+```
+
+---
+
+### 场景 2：快速实现功能
+
+**需求**：实现一个简单功能
+
+```bash
+# 方式 1：完整工作流（推荐）
+/workflow:plan "添加用户头像上传功能"
+/workflow:execute
+
+# 方式 2：直接实现（快速）
+/cli:codex-execute "添加用户头像上传功能，支持图片裁剪和压缩"
+```
+
+---
+
+### 场景 3：恢复之前的工作
+
+**需求**：继续上次的任务
+
+```bash
+# 查看可恢复的 session
+/workflow:status
+
+# 恢复特定 session
+/workflow:resume WFS-20251106-xxx
+```
+
+---
+
+### 场景 4：生成文档
+
+**需求**：为模块生成文档
+
+```bash
+/memory:docs src/auth --tool gemini --mode full
+```
+
+---
+
+## 💡 快速记忆法
+
+记住这个流程，就能完成大部分任务：
+
+```
+规划 → 执行 → 测试 → 完成
+  ↓      ↓      ↓
+plan → execute → test-gen
+```
+
+**扩展场景**：
+- 需要分析理解 → 使用 `/cli:analyze`
+- 需要精确控制 → 使用 `/cli:execute`
+- 需要快速实现 → 使用 `/cli:codex-execute`
+
+---
+
+## 🆘 遇到问题？
+
+### 命令记不住？
+
+使用 Command Guide SKILL：
+```bash
+ccw  # 或 ccw-help
+```
+
+然后说：
+- "搜索 planning 命令"
+- "执行完 /workflow:plan 后做什么"
+- "我是新手，如何开始"
+
+---
+
+### 执行失败？
+
+1. **查看错误信息**：仔细阅读错误提示
+2. **使用诊断模板**：`ccw-issue` → 选择 "诊断模板"
+3. **查看排查指南**：[Troubleshooting Guide](troubleshooting.md)
+
+---
+
+### 想深入学习？
+
+- **工作流模式**：[Workflow Patterns](workflow-patterns.md) - 学习更多工作流组合
+- **CLI 工具使用**：[CLI Tools Guide](cli-tools-guide.md) - 了解 Gemini/Qwen/Codex 的高级用法
+- **完整命令列表**：查看 `index/essential-commands.json`
+
+---
+
+## 🎯 下一步
+
+现在你已经掌握了基础！尝试：
+
+1. **实践基础工作流**：选择一个小功能，走一遍 plan → execute → test-gen 流程
+2. **探索 CLI 工具**：尝试用 `/cli:analyze` 分析你的代码库
+3. **学习工作流模式**：阅读 [Workflow Patterns](workflow-patterns.md) 了解更多高级用法
+
+**记住**：Claude DMS3 的设计理念是让你用自然语言描述需求，系统自动完成繁琐的工作。不要担心命令记不住，随时可以使用 `ccw` 获取帮助！
+
+---
+
+**祝你使用愉快！** 🎉
+
+有任何问题，使用 `ccw-issue` 提交问题或查询帮助。

.claude/skills/command-guide/guides/index-structure.md

@@ -0,0 +1,326 @@
+# Index Structure Reference
+
+Complete documentation for command index files and their data structures.
+
+## Overview
+
+The command-guide skill uses 5 JSON index files to organize and query 69 commands across the Claude DMS3 workflow system.
+
+## Index Files
+
+### 1. `all-commands.json`
+
+**Purpose**: Complete catalog of all commands with full metadata
+
+**Use Cases**:
+- Full-text search across all commands
+- Detailed command queries
+- Batch operations
+- Reference lookup
+
+**Structure**:
+```json
+[
+  {
+    "name": "workflow:plan",
+    "description": "Orchestrate 5-phase planning workflow with quality gate",
+    "arguments": "[--agent] [--cli-execute] \"text description\"|file.md",
+    "category": "workflow",
+    "subcategory": "core",
+    "usage_scenario": "planning",
+    "difficulty": "Advanced",
+    "file_path": "workflow/plan.md"
+  },
+  ...
+]
+```
+
+**Fields**:
+- `name` (string): Command name (e.g., "workflow:plan")
+- `description` (string): Brief functional description
+- `arguments` (string): Parameter specification
+- `category` (string): Primary category (workflow/cli/memory/task)
+- `subcategory` (string|null): Secondary grouping if applicable
+- `usage_scenario` (string): Primary use case (planning/implementation/testing/etc.)
+- `difficulty` (string): Skill level (Beginner/Intermediate/Advanced)
+- `file_path` (string): Relative path to command file
+
+**Total Records**: 69 commands
+
+---
+
+### 2. `by-category.json`
+
+**Purpose**: Hierarchical organization by category and subcategory
+
+**Use Cases**:
+- Browse commands by category
+- Category-specific listings
+- Hierarchical navigation
+- Understanding command organization
+
+**Structure**:
+```json
+{
+  "workflow": {
+    "core": [
+      {
+        "name": "workflow:plan",
+        "description": "...",
+        ...
+      }
+    ],
+    "brainstorm": [...],
+    "session": [...],
+    "tools": [...],
+    "ui-design": [...]
+  },
+  "cli": {
+    "mode": [...],
+    "core": [...]
+  },
+  "memory": [...],
+  "task": [...]
+}
+```
+
+**Category Breakdown**:
+- **workflow** (46 commands):
+  - core: 11 commands
+  - brainstorm: 12 commands
+  - session: 4 commands
+  - tools: 9 commands
+  - ui-design: 10 commands
+- **cli** (9 commands):
+  - mode: 3 commands
+  - core: 6 commands
+- **memory** (8 commands)
+- **task** (4 commands)
+- **general** (2 commands)
+
+---
+
+### 3. `by-use-case.json`
+
+**Purpose**: Commands organized by practical usage scenarios
+
+**Use Cases**:
+- Task-oriented command discovery
+- "I want to do X" queries
+- Workflow planning
+- Learning paths
+
+**Structure**:
+```json
+{
+  "planning": [
+    {
+      "name": "workflow:plan",
+      "description": "...",
+      ...
+    },
+    ...
+  ],
+  "implementation": [...],
+  "testing": [...],
+  "documentation": [...],
+  "session-management": [...],
+  "general": [...]
+}
+```
+
+**Use Case Categories**:
+- **planning**: Architecture, task breakdown, design
+- **implementation**: Coding, development, execution
+- **testing**: Test generation, TDD, quality assurance
+- **documentation**: Docs generation, memory management
+- **session-management**: Workflow control, resumption
+- **general**: Utilities, versioning, prompt enhancement
+
+---
+
+### 4. `essential-commands.json`
+
+**Purpose**: Curated list of 10-15 most frequently used commands
+
+**Use Cases**:
+- Quick reference for beginners
+- Onboarding new users
+- Common workflow starters
+- Cheat sheet
+
+**Structure**:
+```json
+[
+  {
+    "name": "enhance-prompt",
+    "description": "Context-aware prompt enhancement",
+    "arguments": "\"user input to enhance\"",
+    "category": "general",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "enhance-prompt.md"
+  },
+  ...
+]
+```
+
+**Selection Criteria**:
+- Frequency of use in common workflows
+- Value for beginners
+- Core functionality coverage
+- Minimal overlap in capabilities
+
+**Current Count**: 14 commands
+
+**List**:
+1. `enhance-prompt` - Prompt enhancement
+2. `version` - Version info
+3. `cli:analyze` - Quick codebase analysis
+4. `cli:chat` - Direct CLI interaction
+5. `cli:execute` - Auto-execution
+6. `cli:mode:plan` - Planning mode
+7. `task:breakdown` - Task decomposition
+8. `task:create` - Create tasks
+9. `task:execute` - Execute tasks
+10. `workflow:execute` - Run workflows
+11. `workflow:plan` - Plan workflows
+12. `workflow:review` - Review implementation
+13. `workflow:tdd-plan` - TDD planning
+14. `workflow:test-gen` - Test generation
+
+---
+
+### 5. `command-relationships.json`
+
+**Purpose**: Mapping of command dependencies and common sequences
+
+**Use Cases**:
+- Next-step recommendations
+- Workflow pattern suggestions
+- Related command discovery
+- Smart navigation
+
+**Structure**:
+```json
+{
+  "workflow:plan": {
+    "related_commands": [
+      "workflow:execute",
+      "workflow:action-plan-verify"
+    ],
+    "next_steps": ["workflow:execute"],
+    "prerequisites": []
+  },
+  "workflow:execute": {
+    "related_commands": [
+      "workflow:status",
+      "workflow:resume",
+      "workflow:review"
+    ],
+    "next_steps": ["workflow:review", "workflow:status"],
+    "prerequisites": ["workflow:plan"]
+  },
+  ...
+}
+```
+
+**Fields**:
+- `related_commands` (array): Commonly used together
+- `next_steps` (array): Typical next commands
+- `prerequisites` (array): Usually run before this command
+
+**Relationship Types**:
+1. **Sequential**: A → B (plan → execute)
+2. **Alternatives**: A | B (execute OR codex-execute)
+3. **Built-in**: A includes B (plan auto-includes context-gather)
+
+---
+
+## Query Patterns
+
+### Pattern 1: Keyword Search
+```javascript
+// Search by keyword in name or description
+const results = allCommands.filter(cmd =>
+  cmd.name.includes(keyword) ||
+  cmd.description.toLowerCase().includes(keyword.toLowerCase())
+);
+```
+
+### Pattern 2: Category Browse
+```javascript
+// Get all commands in a category
+const workflowCommands = byCategory.workflow;
+const coreWorkflow = byCategory.workflow.core;
+```
+
+### Pattern 3: Use-Case Lookup
+```javascript
+// Find commands for specific use case
+const planningCommands = byUseCase.planning;
+```
+
+### Pattern 4: Related Commands
+```javascript
+// Get next steps after a command
+const nextSteps = commandRelationships["workflow:plan"].next_steps;
+```
+
+### Pattern 5: Essential Commands
+```javascript
+// Get beginner-friendly quick reference
+const quickStart = essentialCommands;
+```
+
+---
+
+## Maintenance
+
+### Regenerating Indexes
+
+When commands are added/modified/removed:
+
+```bash
+bash scripts/update-index.sh
+```
+
+The script will:
+1. Scan all .md files in commands/
+2. Extract metadata from YAML frontmatter
+3. Analyze command relationships
+4. Identify essential commands
+5. Generate all 5 index files
+
+### Validation Checklist
+
+After regeneration, verify:
+- [ ] All 5 JSON files are valid (no syntax errors)
+- [ ] Total command count matches (currently 69)
+- [ ] No missing fields in records
+- [ ] Category breakdown correct
+- [ ] Essential commands reasonable (10-15)
+- [ ] Relationships make logical sense
+
+---
+
+## Performance Considerations
+
+**Index Sizes**:
+- `all-commands.json`: ~28KB
+- `by-category.json`: ~31KB
+- `by-use-case.json`: ~29KB
+- `command-relationships.json`: ~7KB
+- `essential-commands.json`: ~5KB
+
+**Total**: ~100KB (fast to load)
+
+**Query Speed**:
+- In-memory search: < 1ms
+- File read + parse: < 50ms
+- Recommended: Load indexes once, cache in memory
+
+---
+
+**Last Updated**: 2025-01-06

.claude/skills/command-guide/guides/troubleshooting.md

@@ -0,0 +1,92 @@
+# 常见问题与解决方案
+
+在使用 Gemini CLI 的过程中，您可能会遇到一些问题。本指南旨在帮助您诊断和解决这些常见问题，确保您能顺利使用 CLI。
+
+## 1. 命令执行失败或未找到
+
+**问题描述**:
+- 您输入的命令没有响应，或者系统提示“命令未找到”。
+- 命令执行后出现错误信息，但您不理解其含义。
+
+**可能原因**:
+- 命令拼写错误。
+- CLI 未正确安装或环境变量配置不正确。
+- 命令所需的依赖项缺失。
+- 命令参数不正确或缺失。
+
+**解决方案**:
+1.  **检查拼写**: 仔细核对您输入的命令是否正确，包括命令名称和任何参数。
+2.  **查看帮助**: 使用 `gemini help` 或 `gemini [command-name] --help` 来查看命令的正确用法、可用参数和示例。
+3.  **验证安装**: 确保 Gemini CLI 已正确安装，并且其可执行文件路径已添加到系统的环境变量中。您可以尝试重新安装 CLI。
+4.  **检查日志**: CLI 通常会生成日志文件。查看这些日志可以提供更详细的错误信息，帮助您定位问题。
+5.  **更新 CLI**: 确保您使用的是最新版本的 Gemini CLI。旧版本可能存在已知错误，通过 `gemini version` 检查并更新。
+
+## 2. 权限问题
+
+**问题描述**:
+- CLI 尝试读取、写入或创建文件/目录时，提示“权限被拒绝”或类似错误。
+- 某些操作（如安装依赖、修改系统配置）失败。
+
+**可能原因**:
+- 当前用户没有足够的权限执行该操作。
+- 文件或目录被其他程序占用。
+
+**解决方案**:
+1.  **以管理员身份运行**: 尝试以管理员权限（Windows）或使用 `sudo`（Linux/macOS）运行您的终端或命令提示符。
+    ```bash
+    # Windows (在命令提示符或 PowerShell 中右键选择“以管理员身份运行”)
+    # Linux/macOS
+    sudo gemini [command]
+    ```
+2.  **检查文件/目录权限**: 确保您对目标文件或目录拥有读/写/执行权限。您可能需要使用 `chmod` (Linux/macOS) 或修改文件属性 (Windows) 来更改权限。
+3.  **关闭占用程序**: 确保没有其他程序正在使用您尝试访问的文件或目录。
+
+## 3. 配置问题
+
+**问题描述**:
+- CLI 行为异常，例如无法连接到 LLM 服务，或者某些功能无法正常工作。
+- 提示缺少 API 密钥或配置项。
+
+**可能原因**:
+- 配置文件（如 `.gemini.json` 或相关环境变量）设置不正确。
+- API 密钥过期或无效。
+- 网络连接问题导致无法访问外部服务。
+
+**解决方案**:
+1.  **检查配置文件**: 仔细检查 Gemini CLI 的配置文件（通常位于用户主目录或项目根目录）中的设置。确保所有路径、API 密钥和选项都正确无误。
+2.  **验证环境变量**: 确认所有必要的环境变量（如 `GEMINI_API_KEY`）都已正确设置。
+3.  **网络连接**: 检查您的网络连接是否正常，并确保没有防火墙或代理设置阻止 CLI 访问外部服务。
+4.  **重新初始化配置**: 对于某些配置问题，您可能需要使用 `gemini cli-init` 命令重新初始化 CLI 配置。
+    ```bash
+    gemini cli-init
+    ```
+
+## 4. 智能代理 (LLM) 相关问题
+
+**问题描述**:
+- 智能代理的响应质量不佳，不相关或不准确。
+- 代理响应速度慢，或提示达到速率限制。
+
+**可能原因**:
+- 提示不够清晰或缺乏上下文。
+- 选择了不适合当前任务的 LLM 模型。
+- LLM 服务提供商的速率限制或服务中断。
+
+**解决方案**:
+1.  **优化提示**: 尝试使用 `enhance-prompt` 命令来优化您的输入，提供更清晰、更具体的上下文信息。
+2.  **选择合适的工具**: 根据任务类型，使用 `--tool` 标志选择最合适的 LLM 模型（如 `codex` 适用于代码生成，`gemini` 适用于复杂推理）。
+    ```bash
+    gemini analyze --tool gemini "分析这个复杂算法"
+    ```
+3.  **检查 API 密钥和配额**: 确保您的 LLM 服务 API 密钥有效，并且没有超出使用配额。
+4.  **重试或等待**: 如果是速率限制或服务中断，请稍后重试或联系服务提供商。
+
+## 5. 寻求帮助
+
+如果以上解决方案都无法解决您的问题，您可以：
+
+-   **查阅官方文档**: 访问 Gemini CLI 的官方文档获取更全面的信息。
+-   **社区支持**: 在相关的开发者社区或论坛中提问。
+-   **提交问题**: 如果您认为是 CLI 的 bug，请在项目的问题跟踪器中提交详细的问题报告。
+
+希望本指南能帮助您解决遇到的问题，让您更好地利用 Gemini CLI！

.claude/skills/command-guide/guides/ui-design-workflow-guide.md

@@ -0,0 +1,326 @@
+# UI Design Workflow Guide
+
+## Overview
+
+The UI Design Workflow System is a comprehensive suite of 11 autonomous commands designed to transform intent (prompts), references (images/URLs), or existing code into functional, production-ready UI prototypes. It employs a **Separation of Concerns** architecture, treating Style (visual tokens), Structure (layout templates), and Motion (animation tokens) as independent, mix-and-match components.
+
+## Command Taxonomy
+
+### 1. Orchestrators (High-Level Workflows)
+
+These commands automate end-to-end processes by chaining specialized sub-commands.
+
+- **`/workflow:ui-design:explore-auto`**: For creating *new* designs. Generates multiple style and layout variants from a prompt to explore design directions.
+- **`/workflow:ui-design:imitate-auto`**: For *replicating* existing designs. High-fidelity cloning of target URLs into a reusable design system.
+- **`/workflow:ui-design:batch-generate`**: For rapid, high-volume prototype generation based on established design tokens.
+
+### 2. Core Extractors (Specialized Analysis)
+
+Agents dedicated to analyzing specific aspects of design.
+
+- **`/workflow:ui-design:style-extract`**: Extracts visual tokens (colors, typography, spacing, shadows) into `design-tokens.json`.
+- **`/workflow:ui-design:layout-extract`**: Extracts DOM structure and CSS layout rules into `layout-templates.json`.
+- **`/workflow:ui-design:animation-extract`**: Extracts motion patterns into `animation-tokens.json`.
+
+### 3. Input & Capture Utilities
+
+Tools for gathering raw data for analysis.
+
+- **`/workflow:ui-design:capture`**: High-speed batch screenshot capture for multiple URLs.
+- **`/workflow:ui-design:explore-layers`**: Interactive, depth-controlled capture (e.g., capturing modals, dropdowns, shadow DOM).
+- **`/workflow:ui-design:import-from-code`**: Bootstraps a design system by analyzing existing CSS/JS/HTML files.
+
+### 4. Assemblers & Integrators
+
+Tools for combining components and integrating results.
+
+- **`/workflow:ui-design:generate`**: Pure assembler that combines Layout Templates + Design Tokens into HTML/CSS prototypes.
+- **`/workflow:ui-design:update`**: Synchronizes generated design artifacts with the main project session for implementation planning.
+
+---
+
+## Common Workflow Patterns
+
+### Workflow A: Exploratory Design (New Concepts)
+
+**Goal:** Create multiple design options for a new project from a text description.
+
+**Primary Command:** `explore-auto`
+
+**Steps:**
+
+1. **Initiate**: User runs `/workflow:ui-design:explore-auto --prompt "Modern fintech dashboard" --style-variants 3`
+2. **Style Extraction**: System generates 3 distinct visual design systems based on the prompt.
+3. **Layout Extraction**: System researches and generates responsive layout templates for a dashboard.
+4. **Assembly**: System generates a matrix of prototypes (3 styles × 1 layout = 3 prototypes).
+5. **Review**: User views `compare.html` to select the best direction.
+
+**Example:**
+
+```bash
+/workflow:ui-design:explore-auto \
+  --prompt "Modern SaaS landing page with hero, features, pricing sections" \
+  --style-variants 3 \
+  --layout-variants 2 \
+  --session WFS-001
+```
+
+**Output:**
+- `design-tokens-v1.json`, `design-tokens-v2.json`, `design-tokens-v3.json` (3 style variants)
+- `layout-templates-v1.json`, `layout-templates-v2.json` (2 layout variants)
+- 6 HTML prototypes (3 × 2 combinations)
+- `compare.html` for side-by-side comparison
+
+---
+
+### Workflow B: Design Replication (Imitation)
+
+**Goal:** Create a design system and prototypes based on existing reference sites.
+
+**Primary Command:** `imitate-auto`
+
+**Steps:**
+
+1. **Initiate**: User runs `/workflow:ui-design:imitate-auto --url-map "home:https://example.com, pricing:https://example.com/pricing"`
+2. **Capture**: System screenshots all provided URLs.
+3. **Extraction**: System extracts a unified design system (style, layout, animation) from the primary URL.
+4. **Assembly**: System recreates all target pages using the extracted system.
+
+**Example:**
+
+```bash
+/workflow:ui-design:imitate-auto \
+  --url-map "landing:https://stripe.com, pricing:https://stripe.com/pricing, docs:https://stripe.com/docs" \
+  --capture-mode batch \
+  --session WFS-002
+```
+
+**Output:**
+- Screenshots of all URLs
+- `design-tokens.json` (unified style system)
+- `layout-templates.json` (page structures)
+- 3 HTML prototypes matching the captured pages
+
+---
+
+### Workflow C: Code-First Bootstrap
+
+**Goal:** Create a design system from an existing codebase.
+
+**Primary Command:** `import-from-code`
+
+**Steps:**
+
+1. **Initiate**: User runs `/workflow:ui-design:import-from-code --base-path ./src`
+2. **Analysis**: Parallel agents analyze CSS, JS, and HTML to find tokens, layouts, and animations.
+3. **Reporting**: Generates completeness reports and initial token files.
+4. **Supplement (Optional)**: Run `style-extract` or `layout-extract` to fill gaps identified in the reports.
+
+**Example:**
+
+```bash
+/workflow:ui-design:import-from-code \
+  --base-path ./src/components \
+  --session WFS-003
+```
+
+**Output:**
+- `design-tokens.json` (extracted from CSS variables, theme files)
+- `layout-templates.json` (extracted from component structures)
+- `completeness-report.md` (gaps and recommendations)
+- `import-summary.json` (statistics and findings)
+
+---
+
+### Workflow D: Batch Generation (High Volume)
+
+**Goal:** Generate multiple UI prototypes based on established design tokens.
+
+**Primary Command:** `batch-generate`
+
+**Steps:**
+
+1. **Prerequisites**: Have `design-tokens.json` ready (from previous extraction or manual creation)
+2. **Initiate**: User runs `/workflow:ui-design:batch-generate --targets "dashboard,settings,profile" --style-variants 2`
+3. **Parallel Generation**: System generates all targets in parallel, applying style variants
+4. **Review**: User reviews generated prototypes
+
+**Example:**
+
+```bash
+/workflow:ui-design:batch-generate \
+  --targets "login-page,dashboard,settings,profile,notifications" \
+  --target-type page \
+  --style-variants 2 \
+  --device-type responsive \
+  --session WFS-004
+```
+
+**Output:**
+- 10 HTML prototypes (5 targets × 2 styles)
+- All using the same design system for consistency
+
+---
+
+## Architecture & Best Practices
+
+### Separation of Concerns
+
+**Always keep design tokens separate from layout templates:**
+
+- `design-tokens.json` (Style) - Colors, typography, spacing, shadows
+- `layout-templates.json` (Structure) - DOM hierarchy, CSS layout rules
+- `animation-tokens.json` (Motion) - Transitions, keyframes, timing functions
+
+**Benefits:**
+- Instant re-theming by swapping design tokens
+- Layout reuse across different visual styles
+- Independent evolution of style and structure
+
+### Token-First CSS
+
+Generated CSS should primarily use CSS custom properties:
+
+```css
+/* Good - Token-based */
+.button {
+  background: var(--color-primary);
+  padding: var(--spacing-md);
+  border-radius: var(--radius-md);
+}
+
+/* Avoid - Hardcoded */
+.button {
+  background: #3b82f6;
+  padding: 16px;
+  border-radius: 8px;
+}
+```
+
+### Style-Centric Batching
+
+For high-volume generation:
+- Group tasks by style to minimize context switching
+- Use `batch-generate` with multiple targets
+- Reuse existing layout inspirations
+
+### Input Quality Guidelines
+
+**For Prompts:**
+- Specify the desired *vibe* (e.g., "minimalist, high-contrast")
+- Specify the *targets* (e.g., "dashboard, settings page")
+- Include functional requirements (e.g., "responsive, mobile-first")
+
+**For URL Mapping:**
+- First URL is treated as primary source of truth
+- Use descriptive keys in `--url-map`
+- Ensure URLs are accessible (no authentication walls)
+
+---
+
+## Advanced Usage
+
+### Multi-Session Workflows
+
+You can run UI design workflows within an existing workflow session:
+
+```bash
+# 1. Start a workflow session
+/workflow:session:start --new
+
+# 2. Run exploratory design
+/workflow:ui-design:explore-auto --prompt "E-commerce checkout flow" --session <session-id>
+
+# 3. Update main session with design artifacts
+/workflow:ui-design:update --session <session-id> --selected-prototypes "v1,v2"
+```
+
+### Combining Workflows
+
+**Example: Imitation + Custom Variants**
+
+```bash
+# 1. Replicate existing design
+/workflow:ui-design:imitate-auto --url-map "ref:https://example.com"
+
+# 2. Generate additional variants with batch-generate
+/workflow:ui-design:batch-generate --targets "new-page-1,new-page-2" --style-variants 1
+```
+
+### Deep Interactive Capture
+
+For complex UIs with overlays, modals, or dynamic content:
+
+```bash
+/workflow:ui-design:explore-layers \
+  --url https://complex-app.com \
+  --depth 3 \
+  --session WFS-005
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Likely Cause | Resolution |
+|-------|--------------|------------|
+| **Missing Design Tokens** | `style-extract` failed or wasn't run | Run `/workflow:ui-design:style-extract` manually or check logs |
+| **Inaccurate Layouts** | Complex DOM structure not captured | Use `--urls` in `layout-extract` for Chrome DevTools analysis |
+| **Empty Screenshots** | Anti-bot measures or timeout | Use `explore-layers` interactive mode or increase timeout |
+| **Generation Stalls** | Too many concurrent tasks | System defaults to max 6 parallel tasks; check resources |
+| **Integration Failures** | Session ID mismatch or missing markers | Ensure `--session <id>` matches active workflow session |
+| **Low Quality Tokens** | Insufficient reference material | Provide multiple reference images/URLs for better token extraction |
+| **Inconsistent Styles** | Multiple token files without merge | Use single unified `design-tokens.json` or explicit variants |
+
+---
+
+## Command Reference Quick Links
+
+### Orchestrators
+- `/workflow:ui-design:explore-auto` - Create new designs from prompts
+- `/workflow:ui-design:imitate-auto` - Replicate existing designs
+- `/workflow:ui-design:batch-generate` - High-volume prototype generation
+
+### Extractors
+- `/workflow:ui-design:style-extract` - Extract visual design tokens
+- `/workflow:ui-design:layout-extract` - Extract layout structures
+- `/workflow:ui-design:animation-extract` - Extract motion patterns
+
+### Utilities
+- `/workflow:ui-design:capture` - Batch screenshot capture
+- `/workflow:ui-design:explore-layers` - Interactive deep capture
+- `/workflow:ui-design:import-from-code` - Bootstrap from existing code
+- `/workflow:ui-design:generate` - Assemble prototypes from tokens
+- `/workflow:ui-design:update` - Integrate with workflow sessions
+
+---
+
+## Performance Optimization
+
+### Parallel Execution
+
+The system is designed to run extraction phases in parallel:
+- Animation and layout extraction can run concurrently
+- Multiple target generation runs in parallel (default: max 6)
+- Style variant generation is parallelized
+
+### Reuse Intermediates
+
+- `batch-generate` reuses existing layout inspirations
+- Cached screenshots avoid redundant captures
+- Token files can be versioned and reused
+
+### Resource Management
+
+- Each agent task consumes memory and CPU
+- Monitor system resources with large batch operations
+- Consider splitting large batches into smaller chunks
+
+---
+
+## Related Guides
+
+- **Getting Started** - Basic workflow concepts
+- **Workflow Patterns** - General workflow guidance
+- **CLI Tools Guide** - CLI integration strategies
+- **Troubleshooting** - Common issues and solutions

.claude/skills/command-guide/guides/workflow-patterns.md

@@ -0,0 +1,662 @@
+# 常见工作流模式
+
+> 学习如何组合命令完成复杂任务，提升开发效率
+
+## 🎯 什么是工作流？
+
+工作流是**一系列命令的组合**，用于完成特定的开发目标。Claude DMS3 提供了多种工作流模式，覆盖从规划到测试的完整开发周期。
+
+**核心概念**：
+- **工作流（Workflow）**：一组相关任务的集合
+- **任务（Task）**：独立的工作单元，有明确的输入和输出
+- **Session**：工作流的执行实例，记录所有任务状态
+- **上下文（Context）**：任务执行所需的代码、文档、配置等信息
+
+---
+
+## 💡 Pattern 0: 头脑风暴（从0到1的第一步）
+
+**⚠️ 重要**：这是**从0到1开发的起点**！在开始编码之前，通过多角色头脑风暴明确需求、技术选型和架构决策。
+
+**适用场景**：
+- 全新项目启动，需求和技术方案不明确
+- 重大功能开发，涉及多个技术领域和权衡
+- 架构决策，需要多角色视角分析
+
+**流程**：话题分析 → 角色选择 → 角色问答 → 冲突解决 → 生成指导文档
+
+### 模式 A：交互式头脑风暴（推荐）
+
+**特点**：通过问答交互，逐步明确需求和决策
+
+```bash
+# 步骤 1：启动头脑风暴
+/workflow:brainstorm:artifacts "
+GOAL: 实现实时协作编辑平台
+SCOPE: 支持100+用户同时在线，低延迟(<100ms)，冲突自动解决
+CONTEXT: MVP阶段，3个月上线，团队5人（2前端+2后端+1全栈）
+" --count 3
+
+# 系统输出 Phase 0：自动收集项目上下文
+# ✅ 分析现有代码库结构
+# ✅ 加载相关文档
+# ✅ 识别技术栈和依赖
+
+# 系统输出 Phase 1：意图分析（2-4个问题）
+# 【问题1 - 核心挑战】实时协作的主要技术挑战？
+# a) 实时数据同步
+# b) 可扩展性架构
+# c) 冲突解决机制
+# 【问题2 - 优先级】MVP阶段最关注？
+# a) 功能完整性
+# b) 用户体验
+# c) 系统稳定性
+# 请回答 (格式: 1a 2c)：
+
+# 用户输入：1c 2b
+
+# 系统输出 Phase 2：角色选择（推荐 count+2 个角色）
+# 【角色选择】请选择 3 个角色参与头脑风暴
+# a) system-architect (系统架构师) - 实时同步架构设计
+# b) ui-designer (UI设计师) - 协作界面用户体验
+# c) product-manager (产品经理) - 功能优先级决策
+# d) data-architect (数据架构师) - 数据同步模型设计
+# e) ux-expert (UX专家) - 多用户协作交互流程
+# 请输入选择 (格式: 2acd 或 2a 2c 2d)：
+
+# 用户输入：2acd
+
+# 系统输出 Phase 3：角色问题（每个角色 3-4 个问题）
+# ===== system-architect 问题 =====
+# 【问题1】100+ 用户实时状态同步方案？
+# a) Event Sourcing - 完整事件历史，易于回溯
+# b) 集中式状态管理 - 简单直接，适合MVP
+# c) CRDT - 自动冲突解决，分布式友好
+# 【问题2】低延迟通信协议选择？
+# ...
+# 请回答：
+
+# 用户输入：1c 2a 3b 4c
+
+# 系统输出 Phase 4：冲突检测和解决
+# 【冲突1】CRDT 与 UI 回滚期望冲突
+# Background: system-architect 选择 CRDT，但 ui-designer 期望回滚UI
+# a) 采用 CRDT，显示合并状态
+# b) 切换到 OT 算法支持回滚
+# c) 混合方案：CRDT + 本地撤销栈
+# ...
+
+# 系统输出 Phase 5：生成指导文档
+# ✅ 生成 guidance-specification.md
+# ✅ 记录所有决策和理由
+# ✅ 标注冲突解决方案
+# 📁 文件位置：.workflow/WFS-realtime-collab/.brainstorming/guidance-specification.md
+
+# 步骤 2：查看生成的指导文档
+cat .workflow/WFS-*//.brainstorming/guidance-specification.md
+```
+
+### 模式 B：自动并行头脑风暴（快速）
+
+**特点**：自动选择角色，并行执行，快速生成多角色分析
+
+```bash
+# 步骤 1：一键启动并行头脑风暴
+/workflow:brainstorm:auto-parallel "
+GOAL: 实现支付处理模块
+SCOPE: 支持微信/支付宝/银行卡，日交易10万笔，99.99%可用性
+CONTEXT: 金融合规要求，PCI DSS认证，风控系统集成
+" --count 4
+
+# 系统输出：
+# ✅ Phase 0: 收集项目上下文
+# ✅ Phase 1-2: artifacts 交互式框架生成
+# ⏳ Phase 3: 4个角色并行分析
+#   - system-architect → 分析中...
+#   - data-architect → 分析中...
+#   - product-manager → 分析中...
+#   - subject-matter-expert → 分析中...
+# ✅ Phase 4: synthesis 综合分析
+# 📁 输出文件：
+#   - .brainstorming/guidance-specification.md (框架)
+#   - system-architect/analysis.md
+#   - data-architect/analysis.md
+#   - product-manager/analysis.md
+#   - subject-matter-expert/analysis.md
+#   - synthesis/final-recommendations.md
+
+# 步骤 2：查看综合建议
+cat .workflow/WFS-*//.brainstorming/synthesis/final-recommendations.md
+```
+
+### 模式 C：单角色深度分析（特定领域）
+
+**特点**：针对特定领域问题，调用单个角色深度分析
+
+```bash
+# 系统架构分析
+/workflow:brainstorm:system-architect "API 网关架构设计，支持10万QPS，微服务集成"
+
+# UI 设计分析
+/workflow:brainstorm:ui-designer "管理后台界面设计，复杂数据展示，操作效率优先"
+
+# 数据架构分析
+/workflow:brainstorm:data-architect "分布式数据存储方案，MySQL+Redis+ES 组合"
+```
+
+### 关键点
+
+1. **Phase 0 自动上下文收集**：
+   - 自动分析现有代码库、文档、技术栈
+   - 识别潜在冲突和集成点
+   - 为后续问题生成提供上下文
+
+2. **动态问题生成**：
+   - 基于话题关键词和项目上下文生成问题
+   - 不使用预定义模板
+   - 问题直接针对你的具体场景
+
+3. **智能角色推荐**：
+   - 基于话题分析推荐最相关的角色
+   - 推荐 count+2 个角色供选择
+   - 每个角色都有基于话题的推荐理由
+
+4. **输出物**：
+   - `guidance-specification.md` - 确认的指导规范（决策、理由、集成点）
+   - `{role}/analysis.md` - 各角色详细分析（仅 auto-parallel 模式）
+   - `synthesis/final-recommendations.md` - 综合建议（仅 auto-parallel 模式）
+
+5. **下一步**：
+   - 头脑风暴完成后，使用 `/workflow:plan` 基于指导文档生成实施计划
+   - 指导文档作为规划和实现的权威参考
+
+### 使用场景对比
+
+| 场景 | 推荐模式 | 原因 |
+|------|---------|------|
+| 全新项目启动 | 交互式 (artifacts) | 需要充分澄清需求和约束 |
+| 重大架构决策 | 交互式 (artifacts) | 需要深入讨论权衡 |
+| 快速原型验证 | 自动并行 (auto-parallel) | 快速获得多角色建议 |
+| 特定技术问题 | 单角色 (specific role) | 专注某个领域深度分析 |
+
+---
+
+## 📋 Pattern 1: 规划→执行（最常用）
+
+**适用场景**：实现新功能、新模块
+
+**流程**：规划 → 执行 → 查看状态
+
+### 完整示例
+
+```bash
+# 步骤 1：规划任务
+/workflow:plan --agent "实现用户认证模块"
+
+# 系统输出：
+# ✅ 规划完成
+# 📁 Session: WFS-20251106-123456
+# 📋 生成 5 个任务
+
+# 步骤 2：执行任务
+/workflow:execute
+
+# 系统输出：
+# ⏳ 执行 task-001-user-model...
+# ✅ task-001 完成
+# ⏳ 执行 task-002-login-api...
+# ...
+
+# 步骤 3：查看状态
+/workflow:status
+
+# 系统输出：
+# Session: WFS-20251106-123456
+# Total: 5 | Completed: 5 | Pending: 0
+```
+
+**关键点**：
+- `--agent` 参数使用 AI 生成更详细的计划
+- 系统自动发现最新 session，无需手动指定
+- 所有任务按依赖顺序自动执行
+
+---
+
+## 🧪 Pattern 2: TDD测试驱动开发
+
+**适用场景**：需要高质量代码和测试覆盖
+
+**流程**：TDD规划 → 执行（红→绿→重构）→ 验证
+
+### 完整示例
+
+```bash
+# 步骤 1：TDD 规划
+/workflow:tdd-plan --agent "实现购物车功能"
+
+# 系统输出：
+# ✅ TDD 任务链生成
+# 📋 Red-Green-Refactor 周期：
+#   - task-001-cart-tests (RED)
+#   - task-002-cart-implement (GREEN)
+#   - task-003-cart-refactor (REFACTOR)
+
+# 步骤 2：执行 TDD 周期
+/workflow:execute
+
+# 系统会自动：
+# 1. 生成失败的测试（RED）
+# 2. 实现代码让测试通过（GREEN）
+# 3. 重构代码（REFACTOR）
+
+# 步骤 3：验证 TDD 合规性
+/workflow:tdd-verify
+
+# 系统输出：
+# ✅ TDD 周期完整
+# ✅ 测试覆盖率: 95%
+# ✅ Red-Green-Refactor 合规
+```
+
+**关键点**：
+- TDD 模式自动生成测试优先的任务链
+- 每个任务有依赖关系，确保正确的顺序
+- 验证命令检查 TDD 合规性
+
+---
+
+## 🔄 Pattern 3: 测试生成
+
+**适用场景**：已有代码，需要生成测试
+
+**流程**：分析代码 → 生成测试策略 → 执行测试生成
+
+### 完整示例
+
+```bash
+# 步骤 1：实现功能（已完成）
+# 假设已经完成实现，session 为 WFS-20251106-123456
+
+# 步骤 2：生成测试
+/workflow:test-gen WFS-20251106-123456
+
+# 系统输出：
+# ✅ 分析实现代码
+# ✅ 生成测试策略
+# 📋 创建测试任务：WFS-test-20251106-789
+
+# 步骤 3：执行测试生成
+/workflow:test-cycle-execute --resume-session WFS-test-20251106-789
+
+# 系统输出：
+# ⏳ 生成测试用例...
+# ⏳ 执行测试...
+# ❌ 3 tests failed
+# ⏳ 修复失败测试...
+# ✅ All tests passed
+```
+
+**关键点**：
+- `test-gen` 分析现有代码生成测试
+- `test-cycle-execute` 自动生成→测试→修复循环
+- 最多迭代 N 次直到所有测试通过
+
+---
+
+## 🎨 Pattern 4: UI 设计工作流
+
+**适用场景**：基于设计稿或现有网站实现 UI
+
+**流程**：提取样式 → 提取布局 → 生成原型 → 更新
+
+### 完整示例
+
+```bash
+# 步骤 1：提取设计样式
+/workflow:ui-design:style-extract \
+  --images "design/*.png" \
+  --mode imitate \
+  --variants 3
+
+# 系统输出：
+# ✅ 提取颜色系统
+# ✅ 提取字体系统
+# ✅ 生成 3 个样式变体
+
+# 步骤 2：提取页面布局
+/workflow:ui-design:layout-extract \
+  --urls "https://example.com/dashboard" \
+  --device-type responsive
+
+# 系统输出：
+# ✅ 提取布局结构
+# ✅ 识别组件层次
+# ✅ 生成响应式布局
+
+# 步骤 3：生成 UI 原型
+/workflow:ui-design:generate \
+  --style-variants 2 \
+  --layout-variants 2
+
+# 系统输出：
+# ✅ 生成 4 个原型组合
+# 📁 输出：.workflow/ui-design/prototypes/
+
+# 步骤 4：更新最终版本
+/workflow:ui-design:update \
+  --session ui-session-id \
+  --selected-prototypes "proto-1,proto-3"
+
+# 系统输出：
+# ✅ 应用最终设计系统
+# ✅ 更新所有原型
+```
+
+**关键点**：
+- 支持从图片或 URL 提取设计
+- 可生成多个变体供选择
+- 最终更新使用确定的设计系统
+
+---
+
+## 🔍 Pattern 5: 代码分析→重构
+
+**适用场景**：优化现有代码，提高可维护性
+
+**流程**：分析现状 → 制定计划 → 执行重构 → 生成测试
+
+### 完整示例
+
+```bash
+# 步骤 1：分析代码质量
+/cli:analyze --tool gemini --cd src/auth \
+  "评估认证模块的代码质量、可维护性和潜在问题"
+
+# 系统输出：
+# ✅ 识别 3 个设计问题
+# ✅ 发现 5 个性能瓶颈
+# ✅ 建议 7 项改进
+
+# 步骤 2：制定重构计划
+/cli:mode:plan --tool gemini --cd src/auth \
+  "基于上述分析，制定认证模块重构方案"
+
+# 系统输出：
+# ✅ 重构计划生成
+# 📋 包含 8 个重构任务
+
+# 步骤 3：执行重构
+/cli:execute --tool codex \
+  "按照重构计划执行认证模块重构"
+
+# 步骤 4：生成测试确保正确性
+/workflow:test-gen WFS-refactor-session-id
+```
+
+**关键点**：
+- Gemini 用于分析和规划（理解）
+- Codex 用于执行实现（重构）
+- 重构后必须生成测试验证
+
+---
+
+## 📚 Pattern 6: 文档生成
+
+**适用场景**：为项目或模块生成文档
+
+**流程**：分析代码 → 生成文档 → 更新索引
+
+### 完整示例
+
+```bash
+# 方式 1：为单个模块生成文档
+/memory:docs src/auth --tool gemini --mode full
+
+# 系统输出：
+# ✅ 分析模块结构
+# ✅ 生成 CLAUDE.md
+# ✅ 生成 API 文档
+# ✅ 生成使用指南
+
+# 方式 2：更新所有模块文档
+/memory:update-full --tool gemini
+
+# 系统输出：
+# ⏳ 按层级更新文档...
+# ✅ Layer 3: 12 modules updated
+# ✅ Layer 2: 5 modules updated
+# ✅ Layer 1: 2 modules updated
+
+# 方式 3：只更新修改过的模块
+/memory:update-related --tool gemini
+
+# 系统输出：
+# ✅ 检测 git 变更
+# ✅ 更新 3 个相关模块
+```
+
+**关键点**：
+- `--mode full` 生成完整文档
+- `update-full` 适用于初始化或大规模更新
+- `update-related` 适用于日常增量更新
+
+---
+
+## 🔄 Pattern 7: 恢复和继续
+
+**适用场景**：中断后继续工作，或修复失败的任务
+
+**流程**：查看状态 → 恢复 session → 继续执行
+
+### 完整示例
+
+```bash
+# 步骤 1：查看所有 session
+/workflow:status
+
+# 系统输出：
+# Session: WFS-20251106-123456 (5/10 completed)
+# Session: WFS-20251105-234567 (10/10 completed)
+
+# 步骤 2：恢复特定 session
+/workflow:resume WFS-20251106-123456
+
+# 系统输出：
+# ✅ Session 恢复
+# 📋 5/10 tasks completed
+# ⏳ 待执行: task-006, task-007, ...
+
+# 步骤 3：继续执行
+/workflow:execute --resume-session WFS-20251106-123456
+
+# 系统输出：
+# ⏳ 继续执行 task-006...
+# ✅ task-006 完成
+# ...
+```
+
+**关键点**：
+- 所有 session 状态都被保存
+- 可以随时恢复中断的工作流
+- 恢复时自动分析进度和待办任务
+
+---
+
+## 🎯 Pattern 8: 快速实现（Codex YOLO）
+
+**适用场景**：快速实现简单功能，跳过规划
+
+**流程**：直接执行 → 完成
+
+### 完整示例
+
+```bash
+# 一键实现功能
+/cli:codex-execute --verify-git \
+  "实现用户头像上传功能：
+  - 支持 jpg/png 格式
+  - 自动裁剪为 200x200
+  - 压缩到 100KB 以下
+  - 上传到 OSS
+  "
+
+# 系统输出：
+# ⏳ 分析需求...
+# ⏳ 生成代码...
+# ⏳ 集成现有代码...
+# ✅ 功能实现完成
+# 📁 修改文件:
+#   - src/api/upload.ts
+#   - src/utils/image.ts
+```
+
+**关键点**：
+- 适合简单、独立的功能
+- `--verify-git` 确保 git 状态干净
+- 自动分析需求并完整实现
+
+---
+
+## 🤝 Pattern 9: 多工具协作
+
+**适用场景**：复杂任务需要多个 AI 工具配合
+
+**流程**：Gemini 分析 → Gemini/Qwen 规划 → Codex 实现
+
+### 完整示例
+
+```bash
+# 步骤 1：Gemini 深度分析
+/cli:analyze --tool gemini \
+  "分析支付模块的安全性和性能问题"
+
+# 步骤 2：多工具讨论方案
+/cli:discuss-plan --topic "支付模块重构方案" --rounds 3
+
+# 系统输出：
+# Round 1:
+#   Gemini: 建议方案 A（关注安全）
+#   Codex: 建议方案 B（关注性能）
+# Round 2:
+#   Gemini: 综合分析...
+#   Codex: 技术实现评估...
+# Round 3:
+#   最终方案: 方案 C（安全+性能）
+
+# 步骤 3：Codex 执行实现
+/cli:execute --tool codex "按照方案 C 重构支付模块"
+```
+
+**关键点**：
+- `discuss-plan` 让多个 AI 讨论方案
+- 每个工具贡献自己的专长
+- 最终选择综合最优方案
+
+---
+
+## 📊 工作流选择指南
+
+**核心区分**：从0到1 vs 功能新增
+- **从0到1**：全新项目、新产品、重大架构决策 → **必须头脑风暴**
+- **功能新增**：已有项目中添加功能 → **可直接规划**
+
+```mermaid
+graph TD
+    A[我要做什么?] --> B{项目阶段?}
+
+    B -->|从0到1<br/>全新项目/产品| Z[💡头脑风暴<br/>必经阶段]
+    B -->|功能新增<br/>已有项目| C{任务类型?}
+
+    Z --> Z1[/workflow:brainstorm:artifacts<br/>或<br/>/workflow:brainstorm:auto-parallel]
+    Z1 --> Z2[⬇️ 生成指导文档]
+    Z2 --> C
+
+    C -->|新功能| D[规划→执行]
+    C -->|需要测试| E{代码是否存在?}
+    C -->|UI开发| F[UI设计工作流]
+    C -->|代码优化| G[分析→重构]
+    C -->|生成文档| H[文档生成]
+    C -->|快速实现| I[Codex YOLO]
+
+    E -->|不存在| J[TDD工作流]
+    E -->|已存在| K[测试生成]
+
+    D --> L[/workflow:plan<br/>↓<br/>/workflow:execute]
+    J --> M[/workflow:tdd-plan<br/>↓<br/>/workflow:execute]
+    K --> N[/workflow:test-gen<br/>↓<br/>/workflow:test-cycle-execute]
+    F --> O[/workflow:ui-design:*]
+    G --> P[/cli:analyze<br/>↓<br/>/cli:mode:plan<br/>↓<br/>/cli:execute]
+    H --> Q[/memory:docs]
+    I --> R[/cli:codex-execute]
+```
+
+**说明**：
+- **从0到1场景**：创业项目、新产品线、系统重构 → 头脑风暴明确方向后再规划
+- **功能新增场景**：现有系统添加模块、优化现有功能 → 直接进入规划或分析
+
+---
+
+## 💡 最佳实践
+
+### ✅ 推荐做法
+
+1. **复杂任务使用完整工作流**
+   ```bash
+   /workflow:plan → /workflow:execute → /workflow:test-gen
+   ```
+
+2. **简单任务使用 Codex YOLO**
+   ```bash
+   /cli:codex-execute "快速实现xxx"
+   ```
+
+3. **重要代码使用 TDD**
+   ```bash
+   /workflow:tdd-plan → /workflow:execute → /workflow:tdd-verify
+   ```
+
+4. **定期更新文档**
+   ```bash
+   /memory:update-related  # 每次提交前
+   ```
+
+5. **善用恢复功能**
+   ```bash
+   /workflow:status → /workflow:resume
+   ```
+
+---
+
+### ❌ 避免做法
+
+1. **⚠️ 不要在从0到1场景跳过头脑风暴**
+   - ❌ 全新项目直接 `/workflow:plan`
+   - ✅ 先 `/workflow:brainstorm:artifacts` 明确方向再规划
+
+2. **不要跳过规划直接执行复杂任务**
+   - ❌ 直接 `/cli:execute` 实现复杂功能
+   - ✅ 先 `/workflow:plan` 再 `/workflow:execute`
+
+3. **不要忽略测试**
+   - ❌ 实现完成后不生成测试
+   - ✅ 使用 `/workflow:test-gen` 生成测试
+
+4. **不要遗忘文档**
+   - ❌ 代码实现后忘记更新文档
+   - ✅ 使用 `/memory:update-related` 自动更新
+
+---
+
+## 🔗 相关资源
+
+- **快速入门**：[Getting Started](getting-started.md) - 5分钟上手
+- **CLI 工具**：[CLI Tools Guide](cli-tools-guide.md) - Gemini/Qwen/Codex 详解
+- **UI设计工作流**：[UI Design Workflow Guide](ui-design-workflow-guide.md) - UI设计完整指南
+- **问题排查**：[Troubleshooting](troubleshooting.md) - 常见问题解决
+- **完整命令列表**：查看 `index/all-commands.json`
+
+---
+
+**最后更新**: 2025-11-06
+
+记住：选择合适的工作流模式，事半功倍！不确定用哪个？使用 `ccw` 询问 Command Guide！

.claude/skills/command-guide/index/all-commands.json

@@ -0,0 +1,772 @@
+[
+  {
+    "name": "analyze",
+    "command": "/cli:analyze",
+    "description": "Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection",
+    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target",
+    "category": "cli",
+    "subcategory": null,
+    "usage_scenario": "analysis",
+    "difficulty": "Beginner",
+    "file_path": "cli/analyze.md"
+  },
+  {
+    "name": "chat",
+    "command": "/cli:chat",
+    "description": "Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference",
+    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry",
+    "category": "cli",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Beginner",
+    "file_path": "cli/chat.md"
+  },
+  {
+    "name": "cli-init",
+    "command": "/cli:cli-init",
+    "description": "Generate .gemini/ and .qwen/ config directories with settings.json and ignore files based on workspace technology detection",
+    "arguments": "[--tool gemini|qwen|all] [--output path] [--preview]",
+    "category": "cli",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "cli/cli-init.md"
+  },
+  {
+    "name": "codex-execute",
+    "command": "/cli:codex-execute",
+    "description": "Multi-stage Codex execution with automatic task decomposition into grouped subtasks using resume mechanism for context continuity",
+    "arguments": "[--verify-git] task description or task-id",
+    "category": "cli",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "cli/codex-execute.md"
+  },
+  {
+    "name": "discuss-plan",
+    "command": "/cli:discuss-plan",
+    "description": "Multi-round collaborative planning using Gemini, Codex, and Claude synthesis with iterative discussion cycles (read-only, no code changes)",
+    "arguments": "[--topic '...'] [--task-id '...'] [--rounds N]",
+    "category": "cli",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "cli/discuss-plan.md"
+  },
+  {
+    "name": "execute",
+    "command": "/cli:execute",
+    "description": "Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection",
+    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id",
+    "category": "cli",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "cli/execute.md"
+  },
+  {
+    "name": "bug-diagnosis",
+    "command": "/cli:mode:bug-diagnosis",
+    "description": "Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions",
+    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
+    "category": "cli",
+    "subcategory": "mode",
+    "usage_scenario": "analysis",
+    "difficulty": "Intermediate",
+    "file_path": "cli/mode/bug-diagnosis.md"
+  },
+  {
+    "name": "code-analysis",
+    "command": "/cli:mode:code-analysis",
+    "description": "Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization",
+    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
+    "category": "cli",
+    "subcategory": "mode",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "cli/mode/code-analysis.md"
+  },
+  {
+    "name": "plan",
+    "command": "/cli:mode:plan",
+    "description": "Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis",
+    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
+    "category": "cli",
+    "subcategory": "mode",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "cli/mode/plan.md"
+  },
+  {
+    "name": "enhance-prompt",
+    "command": "/enhance-prompt",
+    "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection",
+    "arguments": "user input to enhance",
+    "category": "general",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "enhance-prompt.md"
+  },
+  {
+    "name": "docs",
+    "command": "/memory:docs",
+    "description": "Plan documentation workflow with dynamic grouping (≤10 docs/task), generates IMPL tasks for parallel module trees, README, ARCHITECTURE, and HTTP API docs",
+    "arguments": "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/docs.md"
+  },
+  {
+    "name": "load-skill-memory",
+    "command": "/memory:load-skill-memory",
+    "description": "Activate SKILL package (auto-detect from paths/keywords or manual) and intelligently load documentation based on task intent keywords",
+    "arguments": "[skill_name] \\\"task intent description\\",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/load-skill-memory.md"
+  },
+  {
+    "name": "load",
+    "command": "/memory:load",
+    "description": "Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context",
+    "arguments": "[--tool gemini|qwen] \\\"task context description\\",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "memory/load.md"
+  },
+  {
+    "name": "skill-memory",
+    "command": "/memory:skill-memory",
+    "description": "4-phase autonomous orchestrator: check docs → /memory:docs planning → /workflow:execute → generate SKILL.md with progressive loading index (skips phases 2-3 if docs exist)",
+    "arguments": "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/skill-memory.md"
+  },
+  {
+    "name": "tech-research",
+    "command": "/memory:tech-research",
+    "description": "3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists)",
+    "arguments": "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "memory/tech-research.md"
+  },
+  {
+    "name": "update-full",
+    "command": "/memory:update-full",
+    "description": "Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel",
+    "arguments": "[--tool gemini|qwen|codex] [--path <directory>]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "memory/update-full.md"
+  },
+  {
+    "name": "update-related",
+    "command": "/memory:update-related",
+    "description": "Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution",
+    "arguments": "[--tool gemini|qwen|codex]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "memory/update-related.md"
+  },
+  {
+    "name": "workflow-skill-memory",
+    "command": "/memory:workflow-skill-memory",
+    "description": "Process WFS-* archived sessions using universal-executor agents with Gemini analysis to generate workflow-progress SKILL package (sessions-timeline, lessons, conflicts)",
+    "arguments": "session <session-id> | all",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/workflow-skill-memory.md"
+  },
+  {
+    "name": "breakdown",
+    "command": "/task:breakdown",
+    "description": "Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order",
+    "arguments": "task-id",
+    "category": "task",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "task/breakdown.md"
+  },
+  {
+    "name": "create",
+    "command": "/task:create",
+    "description": "Generate task JSON from natural language description with automatic file pattern detection, scope inference, and dependency analysis",
+    "arguments": "\\\"task title\\",
+    "category": "task",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "task/create.md"
+  },
+  {
+    "name": "execute",
+    "command": "/task:execute",
+    "description": "Execute task JSON using appropriate agent (@doc-generator/@implementation-agent/@test-agent) with pre-analysis context loading and status tracking",
+    "arguments": "task-id",
+    "category": "task",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "task/execute.md"
+  },
+  {
+    "name": "replan",
+    "command": "/task:replan",
+    "description": "Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json",
+    "arguments": "task-id [\\\"text\\\"|file.md] | --batch [verification-report.md]",
+    "category": "task",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "task/replan.md"
+  },
+  {
+    "name": "version",
+    "command": "/version",
+    "description": "Display Claude Code version information and check for updates",
+    "arguments": "",
+    "category": "general",
+    "subcategory": null,
+    "usage_scenario": "general",
+    "difficulty": "Beginner",
+    "file_path": "version.md"
+  },
+  {
+    "name": "action-plan-verify",
+    "command": "/workflow:action-plan-verify",
+    "description": "Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation",
+    "arguments": "[optional: --session session-id]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/action-plan-verify.md"
+  },
+  {
+    "name": "api-designer",
+    "command": "/workflow:brainstorm:api-designer",
+    "description": "Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/api-designer.md"
+  },
+  {
+    "name": "artifacts",
+    "command": "/workflow:brainstorm:artifacts",
+    "description": "Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis",
+    "arguments": "topic or challenge description [--count N]",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/artifacts.md"
+  },
+  {
+    "name": "auto-parallel",
+    "command": "/workflow:brainstorm:auto-parallel",
+    "description": "Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives",
+    "arguments": "topic or challenge description\" [--count N]",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Advanced",
+    "file_path": "workflow/brainstorm/auto-parallel.md"
+  },
+  {
+    "name": "data-architect",
+    "command": "/workflow:brainstorm:data-architect",
+    "description": "Generate or update data-architect/analysis.md addressing guidance-specification discussion points for data architecture perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/data-architect.md"
+  },
+  {
+    "name": "product-manager",
+    "command": "/workflow:brainstorm:product-manager",
+    "description": "Generate or update product-manager/analysis.md addressing guidance-specification discussion points for product management perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/product-manager.md"
+  },
+  {
+    "name": "product-owner",
+    "command": "/workflow:brainstorm:product-owner",
+    "description": "Generate or update product-owner/analysis.md addressing guidance-specification discussion points for product ownership perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/product-owner.md"
+  },
+  {
+    "name": "scrum-master",
+    "command": "/workflow:brainstorm:scrum-master",
+    "description": "Generate or update scrum-master/analysis.md addressing guidance-specification discussion points for Agile process perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/scrum-master.md"
+  },
+  {
+    "name": "subject-matter-expert",
+    "command": "/workflow:brainstorm:subject-matter-expert",
+    "description": "Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points for domain expertise perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/subject-matter-expert.md"
+  },
+  {
+    "name": "synthesis",
+    "command": "/workflow:brainstorm:synthesis",
+    "description": "Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent",
+    "arguments": "[optional: --session session-id]",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Advanced",
+    "file_path": "workflow/brainstorm/synthesis.md"
+  },
+  {
+    "name": "system-architect",
+    "command": "/workflow:brainstorm:system-architect",
+    "description": "Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/system-architect.md"
+  },
+  {
+    "name": "ui-designer",
+    "command": "/workflow:brainstorm:ui-designer",
+    "description": "Generate or update ui-designer/analysis.md addressing guidance-specification discussion points for UI design perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/ui-designer.md"
+  },
+  {
+    "name": "ux-expert",
+    "command": "/workflow:brainstorm:ux-expert",
+    "description": "Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective",
+    "arguments": "optional topic - uses existing framework if available",
+    "category": "workflow",
+    "subcategory": "brainstorm",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/brainstorm/ux-expert.md"
+  },
+  {
+    "name": "execute",
+    "command": "/workflow:execute",
+    "description": "Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking",
+    "arguments": "[--resume-session=\\\"session-id\\\"]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/execute.md"
+  },
+  {
+    "name": "plan",
+    "command": "/workflow:plan",
+    "description": "5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
+    "arguments": "[--agent] [--cli-execute] \\\"text description\\\"|file.md",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/plan.md"
+  },
+  {
+    "name": "resume",
+    "command": "/workflow:resume",
+    "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection",
+    "arguments": "session-id for workflow session to resume",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "session-management",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/resume.md"
+  },
+  {
+    "name": "review",
+    "command": "/workflow:review",
+    "description": "Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini",
+    "arguments": "[--type=security|architecture|action-items|quality] [optional: session-id]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "analysis",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/review.md"
+  },
+  {
+    "name": "complete",
+    "command": "/workflow:session:complete",
+    "description": "Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag",
+    "arguments": "",
+    "category": "workflow",
+    "subcategory": "session",
+    "usage_scenario": "session-management",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/session/complete.md"
+  },
+  {
+    "name": "list",
+    "command": "/workflow:session:list",
+    "description": "List all workflow sessions with status filtering, shows session metadata and progress information",
+    "arguments": "",
+    "category": "workflow",
+    "subcategory": "session",
+    "usage_scenario": "general",
+    "difficulty": "Beginner",
+    "file_path": "workflow/session/list.md"
+  },
+  {
+    "name": "resume",
+    "command": "/workflow:session:resume",
+    "description": "Resume the most recently paused workflow session with automatic session discovery and status update",
+    "arguments": "",
+    "category": "workflow",
+    "subcategory": "session",
+    "usage_scenario": "session-management",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/session/resume.md"
+  },
+  {
+    "name": "start",
+    "command": "/workflow:session:start",
+    "description": "Discover existing sessions or start new workflow session with intelligent session management and conflict detection",
+    "arguments": "[--auto|--new] [optional: task description for new session]",
+    "category": "workflow",
+    "subcategory": "session",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/session/start.md"
+  },
+  {
+    "name": "workflow:status",
+    "command": "/workflow:status",
+    "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view",
+    "arguments": "[optional: task-id]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "session-management",
+    "difficulty": "Beginner",
+    "file_path": "workflow/status.md"
+  },
+  {
+    "name": "tdd-plan",
+    "command": "/workflow:tdd-plan",
+    "description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
+    "arguments": "[--agent] \\\"feature description\\\"|file.md",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Advanced",
+    "file_path": "workflow/tdd-plan.md"
+  },
+  {
+    "name": "tdd-verify",
+    "command": "/workflow:tdd-verify",
+    "description": "Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis",
+    "arguments": "[optional: WFS-session-id]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "testing",
+    "difficulty": "Advanced",
+    "file_path": "workflow/tdd-verify.md"
+  },
+  {
+    "name": "test-cycle-execute",
+    "command": "/workflow:test-cycle-execute",
+    "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached",
+    "arguments": "[--resume-session=\\\"session-id\\\"] [--max-iterations=N]",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/test-cycle-execute.md"
+  },
+  {
+    "name": "test-fix-gen",
+    "command": "/workflow:test-fix-gen",
+    "description": "Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning",
+    "arguments": "[--use-codex] [--cli-execute] (source-session-id | \\\"feature description\\\" | /path/to/file.md)",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "testing",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/test-fix-gen.md"
+  },
+  {
+    "name": "test-gen",
+    "command": "/workflow:test-gen",
+    "description": "Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks",
+    "arguments": "[--use-codex] [--cli-execute] source-session-id",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "testing",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/test-gen.md"
+  },
+  {
+    "name": "conflict-resolution",
+    "command": "/workflow:tools:conflict-resolution",
+    "description": "Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen",
+    "arguments": "--session WFS-session-id --context path/to/context-package.json",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "general",
+    "difficulty": "Advanced",
+    "file_path": "workflow/tools/conflict-resolution.md"
+  },
+  {
+    "name": "gather",
+    "command": "/workflow:tools:gather",
+    "description": "Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON",
+    "arguments": "--session WFS-session-id \\\"task description\\",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/tools/context-gather.md"
+  },
+  {
+    "name": "task-generate-agent",
+    "command": "/workflow:tools:task-generate-agent",
+    "description": "Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning",
+    "arguments": "--session WFS-session-id [--cli-execute]",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "implementation",
+    "difficulty": "Advanced",
+    "file_path": "workflow/tools/task-generate-agent.md"
+  },
+  {
+    "name": "task-generate-tdd",
+    "command": "/workflow:tools:task-generate-tdd",
+    "description": "Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation",
+    "arguments": "--session WFS-session-id [--agent]",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "implementation",
+    "difficulty": "Advanced",
+    "file_path": "workflow/tools/task-generate-tdd.md"
+  },
+  {
+    "name": "task-generate",
+    "command": "/workflow:tools:task-generate",
+    "description": "Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration",
+    "arguments": "--session WFS-session-id [--cli-execute]",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/tools/task-generate.md"
+  },
+  {
+    "name": "tdd-coverage-analysis",
+    "command": "/workflow:tools:tdd-coverage-analysis",
+    "description": "Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification",
+    "arguments": "--session WFS-session-id",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "testing",
+    "difficulty": "Advanced",
+    "file_path": "workflow/tools/tdd-coverage-analysis.md"
+  },
+  {
+    "name": "test-concept-enhanced",
+    "command": "/workflow:tools:test-concept-enhanced",
+    "description": "Analyze test requirements and generate test generation strategy using Gemini with test-context package",
+    "arguments": "--session WFS-test-session-id --context path/to/test-context-package.json",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "testing",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/tools/test-concept-enhanced.md"
+  },
+  {
+    "name": "test-context-gather",
+    "command": "/workflow:tools:test-context-gather",
+    "description": "Collect test coverage context using test-context-search-agent and package into standardized test-context JSON",
+    "arguments": "--session WFS-test-session-id",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "testing",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/tools/test-context-gather.md"
+  },
+  {
+    "name": "test-task-generate",
+    "command": "/workflow:tools:test-task-generate",
+    "description": "Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex",
+    "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
+    "category": "workflow",
+    "subcategory": "tools",
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/tools/test-task-generate.md"
+  },
+  {
+    "name": "animation-extract",
+    "command": "/workflow:ui-design:animation-extract",
+    "description": "Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation",
+    "arguments": "[--base-path <path>] [--session <id>] [--urls \"<list>\"] [--mode <auto|interactive>] [--focus \"<types>\"]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/animation-extract.md"
+  },
+  {
+    "name": "batch-generate",
+    "command": "/workflow:ui-design:batch-generate",
+    "description": "Prompt-driven batch UI generation using target-style-centric parallel execution with design token application",
+    "arguments": "[--targets \"<list>\"] [--target-type \"page|component\"] [--device-type \"desktop|mobile|tablet|responsive\"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/batch-generate.md"
+  },
+  {
+    "name": "capture",
+    "command": "/workflow:ui-design:capture",
+    "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
+    "arguments": "--url-map \"target:url,...\" [--base-path path] [--session id]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/capture.md"
+  },
+  {
+    "name": "explore-auto",
+    "command": "/workflow:ui-design:explore-auto",
+    "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution",
+    "arguments": "[--prompt \"<desc>\"] [--images \"<glob>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/explore-auto.md"
+  },
+  {
+    "name": "explore-layers",
+    "command": "/workflow:ui-design:explore-layers",
+    "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
+    "arguments": "--url <url> --depth <1-5> [--session id] [--base-path path]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/explore-layers.md"
+  },
+  {
+    "name": "generate",
+    "command": "/workflow:ui-design:generate",
+    "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation",
+    "arguments": "[--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "implementation",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/generate.md"
+  },
+  {
+    "name": "imitate-auto",
+    "command": "/workflow:ui-design:imitate-auto",
+    "description": "High-speed multi-page UI replication with batch screenshot capture and design token extraction",
+    "arguments": "--url-map \"<map>\" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt \"<desc>\"]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/imitate-auto.md"
+  },
+  {
+    "name": "workflow:ui-design:import-from-code",
+    "command": "/workflow:ui-design:import-from-code",
+    "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis",
+    "arguments": "[--base-path <path>] [--css \\\"<glob>\\\"] [--js \\\"<glob>\\\"] [--scss \\\"<glob>\\\"] [--html \\\"<glob>\\\"] [--style-files \\\"<glob>\\\"] [--session <id>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/import-from-code.md"
+  },
+  {
+    "name": "layout-extract",
+    "command": "/workflow:ui-design:layout-extract",
+    "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis",
+    "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/layout-extract.md"
+  },
+  {
+    "name": "style-extract",
+    "command": "/workflow:ui-design:style-extract",
+    "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation",
+    "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--mode <imitate|explore>] [--variants <count>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/style-extract.md"
+  },
+  {
+    "name": "update",
+    "command": "/workflow:ui-design:update",
+    "description": "Update brainstorming artifacts with finalized design system references from selected prototypes",
+    "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/update.md"
+  }
+]

.claude/skills/command-guide/index/by-category.json

@@ -0,0 +1,802 @@
+{
+  "cli": {
+    "_root": [
+      {
+        "name": "analyze",
+        "command": "/cli:analyze",
+        "description": "Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection",
+        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target",
+        "category": "cli",
+        "subcategory": null,
+        "usage_scenario": "analysis",
+        "difficulty": "Beginner",
+        "file_path": "cli/analyze.md"
+      },
+      {
+        "name": "chat",
+        "command": "/cli:chat",
+        "description": "Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference",
+        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry",
+        "category": "cli",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Beginner",
+        "file_path": "cli/chat.md"
+      },
+      {
+        "name": "cli-init",
+        "command": "/cli:cli-init",
+        "description": "Generate .gemini/ and .qwen/ config directories with settings.json and ignore files based on workspace technology detection",
+        "arguments": "[--tool gemini|qwen|all] [--output path] [--preview]",
+        "category": "cli",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "cli/cli-init.md"
+      },
+      {
+        "name": "codex-execute",
+        "command": "/cli:codex-execute",
+        "description": "Multi-stage Codex execution with automatic task decomposition into grouped subtasks using resume mechanism for context continuity",
+        "arguments": "[--verify-git] task description or task-id",
+        "category": "cli",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "cli/codex-execute.md"
+      },
+      {
+        "name": "discuss-plan",
+        "command": "/cli:discuss-plan",
+        "description": "Multi-round collaborative planning using Gemini, Codex, and Claude synthesis with iterative discussion cycles (read-only, no code changes)",
+        "arguments": "[--topic '...'] [--task-id '...'] [--rounds N]",
+        "category": "cli",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "cli/discuss-plan.md"
+      },
+      {
+        "name": "execute",
+        "command": "/cli:execute",
+        "description": "Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection",
+        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id",
+        "category": "cli",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "cli/execute.md"
+      }
+    ],
+    "mode": [
+      {
+        "name": "bug-diagnosis",
+        "command": "/cli:mode:bug-diagnosis",
+        "description": "Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions",
+        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
+        "category": "cli",
+        "subcategory": "mode",
+        "usage_scenario": "analysis",
+        "difficulty": "Intermediate",
+        "file_path": "cli/mode/bug-diagnosis.md"
+      },
+      {
+        "name": "code-analysis",
+        "command": "/cli:mode:code-analysis",
+        "description": "Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization",
+        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
+        "category": "cli",
+        "subcategory": "mode",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "cli/mode/code-analysis.md"
+      },
+      {
+        "name": "plan",
+        "command": "/cli:mode:plan",
+        "description": "Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis",
+        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
+        "category": "cli",
+        "subcategory": "mode",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "cli/mode/plan.md"
+      }
+    ]
+  },
+  "general": {
+    "_root": [
+      {
+        "name": "enhance-prompt",
+        "command": "/enhance-prompt",
+        "description": "Enhanced prompt transformation using session memory and codebase analysis with --enhance flag detection",
+        "arguments": "user input to enhance",
+        "category": "general",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "enhance-prompt.md"
+      },
+      {
+        "name": "version",
+        "command": "/version",
+        "description": "Display Claude Code version information and check for updates",
+        "arguments": "",
+        "category": "general",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Beginner",
+        "file_path": "version.md"
+      }
+    ]
+  },
+  "memory": {
+    "_root": [
+      {
+        "name": "docs",
+        "command": "/memory:docs",
+        "description": "Plan documentation workflow with dynamic grouping (≤10 docs/task), generates IMPL tasks for parallel module trees, README, ARCHITECTURE, and HTTP API docs",
+        "arguments": "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/docs.md"
+      },
+      {
+        "name": "load-skill-memory",
+        "command": "/memory:load-skill-memory",
+        "description": "Activate SKILL package (auto-detect from paths/keywords or manual) and intelligently load documentation based on task intent keywords",
+        "arguments": "[skill_name] \\\"task intent description\\",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/load-skill-memory.md"
+      },
+      {
+        "name": "load",
+        "command": "/memory:load",
+        "description": "Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context",
+        "arguments": "[--tool gemini|qwen] \\\"task context description\\",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "memory/load.md"
+      },
+      {
+        "name": "skill-memory",
+        "command": "/memory:skill-memory",
+        "description": "4-phase autonomous orchestrator: check docs → /memory:docs planning → /workflow:execute → generate SKILL.md with progressive loading index (skips phases 2-3 if docs exist)",
+        "arguments": "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/skill-memory.md"
+      },
+      {
+        "name": "tech-research",
+        "command": "/memory:tech-research",
+        "description": "3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists)",
+        "arguments": "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "memory/tech-research.md"
+      },
+      {
+        "name": "update-full",
+        "command": "/memory:update-full",
+        "description": "Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel",
+        "arguments": "[--tool gemini|qwen|codex] [--path <directory>]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "memory/update-full.md"
+      },
+      {
+        "name": "update-related",
+        "command": "/memory:update-related",
+        "description": "Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution",
+        "arguments": "[--tool gemini|qwen|codex]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "memory/update-related.md"
+      },
+      {
+        "name": "workflow-skill-memory",
+        "command": "/memory:workflow-skill-memory",
+        "description": "Process WFS-* archived sessions using universal-executor agents with Gemini analysis to generate workflow-progress SKILL package (sessions-timeline, lessons, conflicts)",
+        "arguments": "session <session-id> | all",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/workflow-skill-memory.md"
+      }
+    ]
+  },
+  "task": {
+    "_root": [
+      {
+        "name": "breakdown",
+        "command": "/task:breakdown",
+        "description": "Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order",
+        "arguments": "task-id",
+        "category": "task",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "task/breakdown.md"
+      },
+      {
+        "name": "create",
+        "command": "/task:create",
+        "description": "Generate task JSON from natural language description with automatic file pattern detection, scope inference, and dependency analysis",
+        "arguments": "\\\"task title\\",
+        "category": "task",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "task/create.md"
+      },
+      {
+        "name": "execute",
+        "command": "/task:execute",
+        "description": "Execute task JSON using appropriate agent (@doc-generator/@implementation-agent/@test-agent) with pre-analysis context loading and status tracking",
+        "arguments": "task-id",
+        "category": "task",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "task/execute.md"
+      },
+      {
+        "name": "replan",
+        "command": "/task:replan",
+        "description": "Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json",
+        "arguments": "task-id [\\\"text\\\"|file.md] | --batch [verification-report.md]",
+        "category": "task",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "task/replan.md"
+      }
+    ]
+  },
+  "workflow": {
+    "_root": [
+      {
+        "name": "action-plan-verify",
+        "command": "/workflow:action-plan-verify",
+        "description": "Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation",
+        "arguments": "[optional: --session session-id]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/action-plan-verify.md"
+      },
+      {
+        "name": "execute",
+        "command": "/workflow:execute",
+        "description": "Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking",
+        "arguments": "[--resume-session=\\\"session-id\\\"]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/execute.md"
+      },
+      {
+        "name": "plan",
+        "command": "/workflow:plan",
+        "description": "5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
+        "arguments": "[--agent] [--cli-execute] \\\"text description\\\"|file.md",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/plan.md"
+      },
+      {
+        "name": "resume",
+        "command": "/workflow:resume",
+        "description": "Resume paused workflow session with automatic progress analysis, pending task identification, and conflict detection",
+        "arguments": "session-id for workflow session to resume",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "session-management",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/resume.md"
+      },
+      {
+        "name": "review",
+        "command": "/workflow:review",
+        "description": "Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini",
+        "arguments": "[--type=security|architecture|action-items|quality] [optional: session-id]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "analysis",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/review.md"
+      },
+      {
+        "name": "workflow:status",
+        "command": "/workflow:status",
+        "description": "Generate on-demand task status views from JSON task data with optional task-id filtering for detailed view",
+        "arguments": "[optional: task-id]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "session-management",
+        "difficulty": "Beginner",
+        "file_path": "workflow/status.md"
+      },
+      {
+        "name": "tdd-plan",
+        "command": "/workflow:tdd-plan",
+        "description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
+        "arguments": "[--agent] \\\"feature description\\\"|file.md",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Advanced",
+        "file_path": "workflow/tdd-plan.md"
+      },
+      {
+        "name": "tdd-verify",
+        "command": "/workflow:tdd-verify",
+        "description": "Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis",
+        "arguments": "[optional: WFS-session-id]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "testing",
+        "difficulty": "Advanced",
+        "file_path": "workflow/tdd-verify.md"
+      },
+      {
+        "name": "test-cycle-execute",
+        "command": "/workflow:test-cycle-execute",
+        "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached",
+        "arguments": "[--resume-session=\\\"session-id\\\"] [--max-iterations=N]",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/test-cycle-execute.md"
+      },
+      {
+        "name": "test-fix-gen",
+        "command": "/workflow:test-fix-gen",
+        "description": "Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning",
+        "arguments": "[--use-codex] [--cli-execute] (source-session-id | \\\"feature description\\\" | /path/to/file.md)",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "testing",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/test-fix-gen.md"
+      },
+      {
+        "name": "test-gen",
+        "command": "/workflow:test-gen",
+        "description": "Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks",
+        "arguments": "[--use-codex] [--cli-execute] source-session-id",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "testing",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/test-gen.md"
+      }
+    ],
+    "brainstorm": [
+      {
+        "name": "api-designer",
+        "command": "/workflow:brainstorm:api-designer",
+        "description": "Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/api-designer.md"
+      },
+      {
+        "name": "artifacts",
+        "command": "/workflow:brainstorm:artifacts",
+        "description": "Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis",
+        "arguments": "topic or challenge description [--count N]",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/artifacts.md"
+      },
+      {
+        "name": "auto-parallel",
+        "command": "/workflow:brainstorm:auto-parallel",
+        "description": "Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives",
+        "arguments": "topic or challenge description\" [--count N]",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Advanced",
+        "file_path": "workflow/brainstorm/auto-parallel.md"
+      },
+      {
+        "name": "data-architect",
+        "command": "/workflow:brainstorm:data-architect",
+        "description": "Generate or update data-architect/analysis.md addressing guidance-specification discussion points for data architecture perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/data-architect.md"
+      },
+      {
+        "name": "product-manager",
+        "command": "/workflow:brainstorm:product-manager",
+        "description": "Generate or update product-manager/analysis.md addressing guidance-specification discussion points for product management perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/product-manager.md"
+      },
+      {
+        "name": "product-owner",
+        "command": "/workflow:brainstorm:product-owner",
+        "description": "Generate or update product-owner/analysis.md addressing guidance-specification discussion points for product ownership perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/product-owner.md"
+      },
+      {
+        "name": "scrum-master",
+        "command": "/workflow:brainstorm:scrum-master",
+        "description": "Generate or update scrum-master/analysis.md addressing guidance-specification discussion points for Agile process perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/scrum-master.md"
+      },
+      {
+        "name": "subject-matter-expert",
+        "command": "/workflow:brainstorm:subject-matter-expert",
+        "description": "Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points for domain expertise perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/subject-matter-expert.md"
+      },
+      {
+        "name": "synthesis",
+        "command": "/workflow:brainstorm:synthesis",
+        "description": "Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent",
+        "arguments": "[optional: --session session-id]",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Advanced",
+        "file_path": "workflow/brainstorm/synthesis.md"
+      },
+      {
+        "name": "system-architect",
+        "command": "/workflow:brainstorm:system-architect",
+        "description": "Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/system-architect.md"
+      },
+      {
+        "name": "ui-designer",
+        "command": "/workflow:brainstorm:ui-designer",
+        "description": "Generate or update ui-designer/analysis.md addressing guidance-specification discussion points for UI design perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/ui-designer.md"
+      },
+      {
+        "name": "ux-expert",
+        "command": "/workflow:brainstorm:ux-expert",
+        "description": "Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective",
+        "arguments": "optional topic - uses existing framework if available",
+        "category": "workflow",
+        "subcategory": "brainstorm",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/brainstorm/ux-expert.md"
+      }
+    ],
+    "session": [
+      {
+        "name": "complete",
+        "command": "/workflow:session:complete",
+        "description": "Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag",
+        "arguments": "",
+        "category": "workflow",
+        "subcategory": "session",
+        "usage_scenario": "session-management",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/session/complete.md"
+      },
+      {
+        "name": "list",
+        "command": "/workflow:session:list",
+        "description": "List all workflow sessions with status filtering, shows session metadata and progress information",
+        "arguments": "",
+        "category": "workflow",
+        "subcategory": "session",
+        "usage_scenario": "general",
+        "difficulty": "Beginner",
+        "file_path": "workflow/session/list.md"
+      },
+      {
+        "name": "resume",
+        "command": "/workflow:session:resume",
+        "description": "Resume the most recently paused workflow session with automatic session discovery and status update",
+        "arguments": "",
+        "category": "workflow",
+        "subcategory": "session",
+        "usage_scenario": "session-management",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/session/resume.md"
+      },
+      {
+        "name": "start",
+        "command": "/workflow:session:start",
+        "description": "Discover existing sessions or start new workflow session with intelligent session management and conflict detection",
+        "arguments": "[--auto|--new] [optional: task description for new session]",
+        "category": "workflow",
+        "subcategory": "session",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/session/start.md"
+      }
+    ],
+    "tools": [
+      {
+        "name": "conflict-resolution",
+        "command": "/workflow:tools:conflict-resolution",
+        "description": "Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen",
+        "arguments": "--session WFS-session-id --context path/to/context-package.json",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "general",
+        "difficulty": "Advanced",
+        "file_path": "workflow/tools/conflict-resolution.md"
+      },
+      {
+        "name": "gather",
+        "command": "/workflow:tools:gather",
+        "description": "Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON",
+        "arguments": "--session WFS-session-id \\\"task description\\",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/tools/context-gather.md"
+      },
+      {
+        "name": "task-generate-agent",
+        "command": "/workflow:tools:task-generate-agent",
+        "description": "Autonomous task generation using action-planning-agent with discovery and output phases for workflow planning",
+        "arguments": "--session WFS-session-id [--cli-execute]",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "implementation",
+        "difficulty": "Advanced",
+        "file_path": "workflow/tools/task-generate-agent.md"
+      },
+      {
+        "name": "task-generate-tdd",
+        "command": "/workflow:tools:task-generate-tdd",
+        "description": "Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation",
+        "arguments": "--session WFS-session-id [--agent]",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "implementation",
+        "difficulty": "Advanced",
+        "file_path": "workflow/tools/task-generate-tdd.md"
+      },
+      {
+        "name": "task-generate",
+        "command": "/workflow:tools:task-generate",
+        "description": "Generate task JSON files and IMPL_PLAN.md from analysis results using action-planning-agent with artifact integration",
+        "arguments": "--session WFS-session-id [--cli-execute]",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/tools/task-generate.md"
+      },
+      {
+        "name": "tdd-coverage-analysis",
+        "command": "/workflow:tools:tdd-coverage-analysis",
+        "description": "Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification",
+        "arguments": "--session WFS-session-id",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "testing",
+        "difficulty": "Advanced",
+        "file_path": "workflow/tools/tdd-coverage-analysis.md"
+      },
+      {
+        "name": "test-concept-enhanced",
+        "command": "/workflow:tools:test-concept-enhanced",
+        "description": "Analyze test requirements and generate test generation strategy using Gemini with test-context package",
+        "arguments": "--session WFS-test-session-id --context path/to/test-context-package.json",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "testing",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/tools/test-concept-enhanced.md"
+      },
+      {
+        "name": "test-context-gather",
+        "command": "/workflow:tools:test-context-gather",
+        "description": "Collect test coverage context using test-context-search-agent and package into standardized test-context JSON",
+        "arguments": "--session WFS-test-session-id",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "testing",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/tools/test-context-gather.md"
+      },
+      {
+        "name": "test-task-generate",
+        "command": "/workflow:tools:test-task-generate",
+        "description": "Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex",
+        "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
+        "category": "workflow",
+        "subcategory": "tools",
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/tools/test-task-generate.md"
+      }
+    ],
+    "ui-design": [
+      {
+        "name": "animation-extract",
+        "command": "/workflow:ui-design:animation-extract",
+        "description": "Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation",
+        "arguments": "[--base-path <path>] [--session <id>] [--urls \"<list>\"] [--mode <auto|interactive>] [--focus \"<types>\"]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/animation-extract.md"
+      },
+      {
+        "name": "batch-generate",
+        "command": "/workflow:ui-design:batch-generate",
+        "description": "Prompt-driven batch UI generation using target-style-centric parallel execution with design token application",
+        "arguments": "[--targets \"<list>\"] [--target-type \"page|component\"] [--device-type \"desktop|mobile|tablet|responsive\"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/batch-generate.md"
+      },
+      {
+        "name": "capture",
+        "command": "/workflow:ui-design:capture",
+        "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
+        "arguments": "--url-map \"target:url,...\" [--base-path path] [--session id]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/capture.md"
+      },
+      {
+        "name": "explore-auto",
+        "command": "/workflow:ui-design:explore-auto",
+        "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution",
+        "arguments": "[--prompt \"<desc>\"] [--images \"<glob>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/explore-auto.md"
+      },
+      {
+        "name": "explore-layers",
+        "command": "/workflow:ui-design:explore-layers",
+        "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
+        "arguments": "--url <url> --depth <1-5> [--session id] [--base-path path]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/explore-layers.md"
+      },
+      {
+        "name": "generate",
+        "command": "/workflow:ui-design:generate",
+        "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation",
+        "arguments": "[--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "implementation",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/generate.md"
+      },
+      {
+        "name": "imitate-auto",
+        "command": "/workflow:ui-design:imitate-auto",
+        "description": "High-speed multi-page UI replication with batch screenshot capture and design token extraction",
+        "arguments": "--url-map \"<map>\" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt \"<desc>\"]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/imitate-auto.md"
+      },
+      {
+        "name": "workflow:ui-design:import-from-code",
+        "command": "/workflow:ui-design:import-from-code",
+        "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis",
+        "arguments": "[--base-path <path>] [--css \\\"<glob>\\\"] [--js \\\"<glob>\\\"] [--scss \\\"<glob>\\\"] [--html \\\"<glob>\\\"] [--style-files \\\"<glob>\\\"] [--session <id>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/import-from-code.md"
+      },
+      {
+        "name": "layout-extract",
+        "command": "/workflow:ui-design:layout-extract",
+        "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis",
+        "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/layout-extract.md"
+      },
+      {
+        "name": "style-extract",
+        "command": "/workflow:ui-design:style-extract",
+        "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation",
+        "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--mode <imitate|explore>] [--variants <count>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/style-extract.md"
+      },
+      {
+        "name": "update",
+        "command": "/workflow:ui-design:update",
+        "description": "Update brainstorming artifacts with finalized design system references from selected prototypes",
+        "arguments": "--session <session_id> [--selected-prototypes \"<list>\"]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/update.md"
+      }
+    ]
+  }
+}