refactor: 更新模块文档更新流程，简化任务描述并增强执行脚本的失败处理

- Renamed update-memory-full.md -> update-full.md for consistency
- Renamed update-memory-related.md -> update-related.md for consistency
- Added parallel execution support (max 4 concurrent) for both direct and agent modes
- Fixed execution strategy: <20 modules direct parallel, ≥20 modules agent batch
- Removed misleading "orchestrator agent" section that caused hierarchy confusion
- Clarified coordinator always executes, agents only for batching ≥20 modules
- Added explicit file naming rules to prevent ToolSidebar.CLAUDE.md errors
- Updated template and script with CRITICAL file naming constraints
- Removed all emoji symbols from documentation for clean text format
- Added smart filtering strategy to docs.md for auto-skip patterns

Key improvements:
- Phase 3A: Direct parallel execution (max 4 concurrent per depth)
- Phase 3B: Agent batch execution (4 modules/agent)
- Both modes use same batching strategy, differ only in agent layer
- Explicit CLAUDE.md file naming in 3 locations (script, template, checklist)

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

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

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

@@ -0,0 +1,478 @@
+---
+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
+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.
+
+## Core Execution Philosophy
+
+- **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
+
+## 5-Phase Execution Workflow
+
+```
+Phase 1: Task Understanding
+    ↓ Intent, complexity, keywords
+Phase 2: Context Discovery (MCP + Search)
+    ↓ Relevant files, patterns, dependencies
+Phase 3: Prompt Enhancement
+    ↓ Structured enhanced prompt
+Phase 4: Tool Selection & Execution
+    ↓ CLI output and results
+Phase 5: Output Routing
+    ↓ Session logs and summaries
+```
+
+---
+
+## 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**
+- `design|plan|architecture|strategy` → **plan**
+- `discuss|evaluate|compare|trade-off` → **discuss**
+
+**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
+
+Score ≥ 5 → Complex
+Score ≥ 2 → Medium
+Score < 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
+
+---
+
+## Phase 2: Context Discovery
+
+### Multi-Tool Parallel Strategy
+
+**1. Project Structure Analysis**:
+```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)**:
+```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 "^(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
+```
+
+**4. External Research (MCP Exa - Optional)**:
+```javascript
+// Best practices for complex tasks
+mcp__exa__get_code_context_exa(
+  query="{tech_stack} {task_type} implementation 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
+```
+
+**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**:
+```bash
+CONTEXT: @CLAUDE.md @{discovered_file1} @{discovered_file2} ...
+
+## Discovered Context
+- **Project Structure**: {module_summary}
+- **Relevant Files**: {top_files_with_scores}
+- **Code Patterns**: {identified_patterns}
+- **Dependencies**: {tech_stack}
+- **Session Memory**: {conversation_context}
+
+## External Research
+{optional_best_practices_from_exa}
+```
+
+**3. Template Selection**:
+```
+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
+```
+
+**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}
+```
+
+---
+
+## Phase 4: Tool Selection & Execution
+
+### Tool Selection Logic
+
+```
+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
+```
+
+### Command Construction
+
+**Gemini/Qwen (Analysis Mode)**:
+```bash
+cd {directory} && ~/.claude/scripts/{tool}-wrapper -p "
+{enhanced_prompt}
+"
+```
+
+**Gemini/Qwen (Write Mode)**:
+```bash
+cd {directory} && ~/.claude/scripts/{tool}-wrapper --approval-mode yolo -p "
+{enhanced_prompt}
+"
+```
+
+**Codex (Auto Mode)**:
+```bash
+codex -C {directory} --full-auto exec "
+{enhanced_prompt}
+" --skip-git-repo-check -s danger-full-access
+```
+
+**Codex (Resume for Related Tasks)**:
+```bash
+codex --full-auto exec "
+{continuation_prompt}
+" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+### Timeout Configuration
+
+```javascript
+baseTimeout = {
+  simple: 20 * 60 * 1000,   // 20min
+  medium: 40 * 60 * 1000,   // 40min
+  complex: 60 * 60 * 1000   // 60min
+}
+
+if (tool === 'codex') {
+  timeout = baseTimeout * 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}/`
+  }
+}
+```
+
+### 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
+
+```markdown
+# CLI Execution Agent Log
+
+**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 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}
+```
+
+---
+
+## MCP Integration Guidelines
+
+### Code Index Usage
+
+**Project Setup**:
+```javascript
+mcp__code-index__set_project_path(path="{project_root}")
+mcp__code-index__refresh_index()
+```
+
+**File Discovery**:
+```javascript
+// Find by pattern
+mcp__code-index__find_files(pattern="*auth*")
+
+// Search content
+mcp__code-index__search_code_advanced(
+  pattern="function.*authenticate",
+  file_pattern="*.ts",
+  context_lines=3
+)
+
+// 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
+
+---
+
+## Error Handling & Recovery
+
+### 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)
+- [ ] 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
+
+---
+
+## Key Reminders
+
+**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
+
+**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
+
+

.claude/agents/doc-generator.md

@@ -53,8 +53,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"
 }

.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/commands/cli/analyze.md

@@ -1,8 +1,8 @@
 ---
 name: analyze
 description: Quick codebase analysis using CLI tools (codex/gemini/qwen)
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
-allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target"
+allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 ---
 
 # CLI Analyze Command (/cli:analyze)
@@ -23,12 +23,15 @@ Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code*
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--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` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
 ## Execution Flow
 
+### Standard Mode (Default)
+
 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
@@ -36,26 +39,52 @@ Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code*
 5. Execute analysis (read-only, no code changes)
 6. Return analysis report with insights and recommendations
 
+### Agent Mode (`--agent` flag)
+
+Delegate task to `cli-execution-agent` for intelligent execution with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Analyze codebase with automated context discovery",
+  prompt=`
+    Task: ${analysis_target}
+    Mode: analyze
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${enhance_flag ? 'Enhance: true' : ''}
+
+    Agent will autonomously:
+    - Discover relevant files and patterns
+    - Build enhanced analysis prompt
+    - Select optimal tool and execute
+    - Route output to session/scratchpad
+  `
+)
+```
+
+The agent handles all phases internally (understanding, discovery, enhancement, execution, routing).
+
 ## 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 trigger specific file patterns (each @ references one pattern):
+- "auth" → `@**/*auth* @**/*user*`
+- "component" → `@src/components/**/* @**/*.component.*`
+- "API" → `@**/api/**/* @**/routes/**/*`
+- "test" → `@**/*.test.* @**/*.spec.*`
+- "config" → `@*.config.* @**/config/**/*`
+- Generic → `@src/**/*`
 
 For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
 ## Command Template
 
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
+cd . && gemini -p "
 PURPOSE: [analysis goal from target]
 TASK: [auto-detected analysis type]
 MODE: analysis
-CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+CONTEXT: @CLAUDE.md [auto-detected file patterns]
 EXPECTED: Insights, patterns, recommendations (NO code modification)
 RULES: [auto-selected template] | Focus on [analysis aspect]
 "
@@ -63,16 +92,27 @@ RULES: [auto-selected template] | Focus on [analysis aspect]
 
 ## Examples
 
-**Basic Analysis**:
+**Basic Analysis (Standard Mode)**:
 ```bash
 /cli:analyze "authentication patterns"
 # Executes: Gemini analysis with auth file patterns
 # Returns: Pattern analysis, architecture insights, recommendations
 ```
 
+**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
+```
+
 **Architecture Analysis**:
 ```bash
-/cli:analyze --tool qwen "component architecture"
+/cli:analyze --tool qwen -p "component architecture"
 # Executes: Qwen with component file patterns
 # Returns: Architecture review, design patterns, improvement suggestions
 ```

.claude/commands/cli/chat.md

@@ -1,8 +1,8 @@
 ---
 name: chat
 description: Simple CLI interaction command for direct codebase analysis
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Chat Command (/cli:chat)
@@ -24,53 +24,93 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - d
 ## Parameters
 
 - `<inquiry>` (Required) - Question or analysis request
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--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
 
 ## Execution Flow
 
+### Standard Mode (Default)
+
 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`
+3. Assemble context: `@CLAUDE.md` + user-specified files or `@**/*` for entire codebase
 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
 
+### Agent Mode (`--agent` flag)
+
+Delegate inquiry to `cli-execution-agent` for intelligent Q&A with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Answer question with automated context discovery",
+  prompt=`
+    Task: ${inquiry}
+    Mode: analyze (Q&A)
+    Tool Preference: ${tool_flag || 'auto-select'}
+
+    Agent will autonomously:
+    - Discover files relevant to the question
+    - Build Q&A prompt with precise context
+    - Execute and generate comprehensive answer
+    - Save conversation log
+  `
+)
+```
+
+The agent handles all phases internally.
+
 ## Context Assembly
 
-**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
+**Always included**: `@CLAUDE.md @**/*CLAUDE.md` (project guidelines, space-separated)
 
 **Optional**:
 - User-explicit files from inquiry keywords
-- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
+- Use `@**/*` in CONTEXT for entire codebase
 
 For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
 
 ## Command Template
 
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-INQUIRY: [user question]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+cd . && gemini -p "
+PURPOSE: Answer user inquiry about codebase
+TASK: [user question]
 MODE: analysis
-RESPONSE: Direct answer, explanation, insights (NO code modification)
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md [inferred files or @**/* for all files]
+EXPECTED: Direct answer, explanation, insights (NO code modification)
+RULES: Focus on clarity and accuracy
 "
 ```
 
 ## Examples
 
-**Basic Question**:
+**Basic Question (Standard Mode)**:
 ```bash
 /cli:chat "analyze the authentication flow"
 # Executes: Gemini analysis
 # Returns: Explanation of auth flow, components involved, data flow
 ```
 
+**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
+```
+
 **Architecture Question**:
 ```bash
-/cli:chat --tool qwen "how does React component optimization work here"
+/cli:chat --tool qwen -p "how does React component optimization work here"
 # Executes: Qwen architecture analysis
 # Returns: Component structure explanation, optimization patterns used
 ```
@@ -90,13 +130,6 @@ RESPONSE: Direct answer, explanation, insights (NO code modification)
 # 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**:

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

@@ -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
@@ -284,10 +284,22 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 1. Mark subtask as blocked in TodoWrite
 2. Report error details to user
 3. Pause execution for manual intervention
-4. User can choose to:
-   - Retry current subtask
-   - Continue to next subtask
-   - Abort entire task
+4. Use AskUserQuestion for recovery decision:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Codex execution failed for the subtask. How should the workflow proceed?",
+    header: "Recovery",
+    options: [
+      { label: "Retry Subtask", description: "Attempt to execute the same subtask again." },
+      { label: "Skip Subtask", description: "Continue to the next subtask in the plan." },
+      { label: "Abort Workflow", description: "Stop the entire execution." }
+    ],
+    multiSelect: false
+  }]
+})
+```
 
 **Git Verification Failure** (if --verify-git):
 1. Show unexpected changes

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

@@ -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
@@ -86,18 +86,18 @@ Codex reviews Gemini's output using conversational reasoning. Uses `resume --las
 
 ```bash
 # First round (new session)
-codex chat "
+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
-"
+" --skip-git-repo-check
 
 # Subsequent rounds (resume discussion)
-codex chat "
+codex --full-auto exec "
 PURPOSE: Re-evaluate plan based on latest synthesis
 TASK: Review updated plan and discussion points, provide further critique or refined ideas
 MODE: analysis
@@ -105,7 +105,7 @@ CONTEXT: Previous discussion context (maintained via resume)
 INPUT_PLAN: [Output from Gemini's analysis for current round]
 EXPECTED: Updated critique building on previous discussion
 RULES: Build on previous insights, avoid repeating points
-" resume --last
+" resume --last --skip-git-repo-check
 ```
 
 **Step 3: Claude's Synthesis (Priority 3)**
@@ -121,9 +121,22 @@ Claude (orchestrating AI) synthesizes both outputs:
 ### Phase 3: User Review and Iteration
 
 1.  **Present Synthesis**: Show synthesized plan and key discussion points
-2.  **Continue or Conclude**: Prompt user:
-    - **(1)** Start another round of discussion
-    - **(2)** Conclude and finalize the plan
+2.  **Continue or Conclude**: Use AskUserQuestion to prompt user:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Round of discussion complete. What is the next step?",
+    header: "Next Round",
+    options: [
+      { label: "Start another round", description: "Continue the discussion to refine the plan further." },
+      { label: "Conclude and finalize", description: "End the discussion and save the final plan." }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
 3.  **Loop or Finalize**:
     -   Continue → New round with Gemini analyzing latest synthesis
     -   Conclude → Save final synthesized document

.claude/commands/cli/execute.md

@@ -1,8 +1,8 @@
 ---
 name: execute
 description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Execute Command (/cli:execute)
@@ -39,13 +39,17 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar
 - Input: Workflow task identifier (e.g., `IMPL-001`)
 - Process: Task JSON parsing → Scope analysis → Execute
 
+**3. Agent Mode** (`--agent` flag):
+- Input: Description or task-id
+- Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
+
 ### 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.
 
@@ -64,7 +68,8 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--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 unless specified)
 - `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
 - `<description|task-id>` - Natural language description or task identifier
 - `--debug` - Verbose logging
@@ -101,15 +106,16 @@ Use `resume --last` when current task extends/relates to previous execution. See
 - No session, ad-hoc implementation:
   - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
 
-## Command Template
+## Execution Modes
 
+### 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
 "
@@ -124,15 +130,52 @@ EXPECTED: Complete implementation with tests
 " --skip-git-repo-check -s danger-full-access
 ```
 
+### Agent Mode (`--agent` flag)
+
+Delegate implementation to `cli-execution-agent` for intelligent execution with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Implement with automated context discovery and optimal tool selection",
+  prompt=`
+    Task: ${description_or_task_id}
+    Mode: execute
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${enhance_flag ? 'Enhance: true' : ''}
+
+    Agent will autonomously:
+    - Discover implementation files and dependencies
+    - Assess complexity and select optimal tool
+    - Execute with YOLO permissions (auto-approve)
+    - Generate task summary if task-id provided
+  `
+)
+```
+
+The agent handles all phases internally, including complexity-based tool selection.
+
 ## Examples
 
-**Basic Implementation** (⚠️ 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):
+```bash
+/cli:execute --agent "implement OAuth2 authentication with token refresh"
+# Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
+# Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
+# Phase 3: Enhances prompt with discovered patterns and best practices
+# Phase 4: Selects Codex (complex task), executes with comprehensive context
+# Phase 5: Saves execution log + generates implementation summary
+# Result: Complete OAuth2 implementation + detailed execution log
+```
+
 **Enhanced Implementation** (⚠️ modifies code):
 ```bash
 /cli:execute --enhance "implement JWT authentication"

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

@@ -1,8 +1,8 @@
 ---
 name: bug-index
 description: Bug analysis and fix suggestions using CLI tools
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
-allowed-tools: SlashCommand(*), Bash(*)
+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)
@@ -16,13 +16,16 @@ Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bu
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--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)
@@ -31,6 +34,33 @@ Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bu
 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
@@ -49,11 +79,11 @@ Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bu
 ## Command Template
 
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [directory] && gemini -p "
 PURPOSE: [bug analysis goal]
 TASK: Systematic bug analysis and fix recommendations
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+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]
 "
@@ -61,13 +91,31 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
 
 ## Examples
 
-**Basic Bug Analysis**:
+**Basic Bug Analysis (Standard Mode)**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+/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 . && gemini -p "
 PURPOSE: Debug authentication null pointer error
 TASK: Identify root cause and provide fix recommendations
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+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
 "
@@ -75,11 +123,11 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login
 
 **Directory-Specific**:
 ```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd src/auth && gemini -p "
 PURPOSE: Fix token validation failure
 TASK: Analyze token validation bug in auth module
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+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
 "
@@ -113,4 +161,4 @@ mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*
 - 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
+- Uses `@**/*` for in CONTEXT field for comprehensive codebase context

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

@@ -1,8 +1,8 @@
 ---
 name: code-analysis
 description: Deep code analysis and debugging using CLI tools with specialized template
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Code Analysis (/cli:mode:code-analysis)
@@ -16,13 +16,16 @@ Systematic code analysis with execution path tracing template (`~/.claude/prompt
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--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 analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
 
 ## 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)
@@ -31,6 +34,33 @@ Systematic code analysis with execution path tracing template (`~/.claude/prompt
 6. Execute deep analysis (read-only, no code modification)
 7. 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.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Analyze code execution paths with automated context discovery",
+  prompt=`
+    Task: ${analysis_target}
+    Mode: code-analysis (execution tracing)
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Template: code-analysis
+
+    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
+  `
+)
+```
+
+The agent handles all phases internally.
+
 ## Core Rules
 
 1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
@@ -52,11 +82,11 @@ Systematic code analysis with execution path tracing template (`~/.claude/prompt
 ## Command Template
 
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [directory] && gemini -p "
 PURPOSE: [analysis goal]
 TASK: Systematic code analysis and execution path tracing
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+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]
 "
@@ -64,13 +94,31 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
 
 ## Examples
 
-**Basic Code Analysis**:
+**Basic Code Analysis (Standard Mode)**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+/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 . && gemini -p "
 PURPOSE: Trace authentication execution flow
 TASK: Analyze complete auth flow from request to response
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+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
 "
@@ -78,11 +126,11 @@ RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flo
 
 **Directory-Specific Analysis**:
 ```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd src/auth && gemini -p "
 PURPOSE: Understand JWT token validation logic
 TASK: Trace JWT validation from middleware to service layer
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Validation flow diagram, token lifecycle analysis
 RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
 "
@@ -119,4 +167,4 @@ mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern
 - 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
+- Uses `@**/*` for in CONTEXT field for comprehensive code context

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

@@ -1,8 +1,8 @@
 ---
 name: plan
 description: Project planning and architecture analysis using CLI tools
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Plan (/cli:mode:plan)
@@ -16,13 +16,16 @@ Comprehensive planning and architecture analysis with strategic planning templat
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--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
 - `--cd "path"` - Target directory for focused planning
 - `<topic>` (Required) - Planning topic or architectural question
 
 ## Execution Flow
 
+### Standard Mode (Default)
+
 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)
@@ -31,6 +34,33 @@ Comprehensive planning and architecture analysis with strategic planning templat
 6. Execute analysis (read-only, no code modification)
 7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
 
+### Agent Mode (`--agent` flag)
+
+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",
+  prompt=`
+    Task: ${planning_topic}
+    Mode: plan (strategic planning)
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Template: plan
+
+    Agent will autonomously:
+    - Discover project structure and existing architecture
+    - Build planning prompt with plan template
+    - Execute strategic planning analysis
+    - Generate implementation roadmap and save
+  `
+)
+```
+
+The agent handles all phases internally.
+
 ## Core Rules
 
 1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
@@ -50,11 +80,11 @@ Comprehensive planning and architecture analysis with strategic planning templat
 ## Command Template
 
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd [directory] && gemini -p "
 PURPOSE: [planning goal from topic]
 TASK: Comprehensive planning and architecture analysis
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+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]
 "
@@ -62,13 +92,31 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
 
 ## Examples
 
-**Basic Planning Analysis**:
+**Basic Planning Analysis (Standard Mode)**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+/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 . && gemini -p "
 PURPOSE: Design user dashboard architecture
 TASK: Plan dashboard component structure and data flow
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Architecture recommendations, component design, data flow diagram
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
 "
@@ -76,11 +124,11 @@ RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
 
 **Directory-Specific Planning**:
 ```bash
-cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
+cd src/api && gemini -p "
 PURPOSE: Plan API refactoring strategy
 TASK: Analyze current API structure and recommend improvements
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+CONTEXT: @CLAUDE.md @**/*CLAUDE.md
 EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
 "
@@ -117,4 +165,4 @@ rg "architecture|design" --files-with-matches
 - 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
+- Uses `@**/*` for in CONTEXT field for comprehensive project context

.claude/commands/enhance-prompt.md

@@ -31,7 +31,7 @@ FUNCTION should_use_gemini(user_prompt):
 END
 ```
 
-**Gemini Integration:** @~/.claude/workflows/intelligent-tools-strategy.md
+**Gemini Integration:** ~/.claude/workflows/intelligent-tools-strategy.md
 
 ## Enhancement Rules
 

.claude/commands/memory/docs.md

@@ -0,0 +1,824 @@
+---
+name: docs
+description: Documentation planning and orchestration - creates structured documentation tasks for execution
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-generate]"
+---
+
+# Documentation Workflow (/memory:docs)
+
+## Overview
+Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent.
+
+**Documentation Output**: All generated documentation is placed in `.workflow/docs/` directory with **mirrored project structure**. For example:
+- Source: `src/modules/auth/index.ts` → Docs: `.workflow/docs/src/modules/auth/API.md`
+- Source: `lib/core/utils.js` → Docs: `.workflow/docs/lib/core/README.md`
+
+**Two Execution Modes**:
+- **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach`
+- **--cli-generate**: CLI generates docs in `implementation_approach` (MODE=write)
+
+## Path Mirroring Strategy
+
+**Principle**: Documentation structure **mirrors** source code structure.
+
+| Source Path | Documentation Path |
+|------------|-------------------|
+| `src/modules/auth/index.ts` | `.workflow/docs/src/modules/auth/API.md` |
+| `src/modules/auth/middleware/` | `.workflow/docs/src/modules/auth/middleware/README.md` |
+| `lib/core/utils.js` | `.workflow/docs/lib/core/API.md` |
+| `lib/core/helpers/` | `.workflow/docs/lib/core/helpers/README.md` |
+
+**Benefits**:
+- Easy to locate documentation for any source file
+- Maintains logical organization
+- Clear 1:1 mapping between code and docs
+- Supports any project structure (src/, lib/, packages/, etc.)
+
+## Parameters
+
+```bash
+/memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-generate]
+```
+
+- **path**: Target directory (default: current directory)
+  - Specifies the directory to generate documentation for
+
+- **--mode**: Documentation generation mode (default: full)
+  - `full`: Complete documentation (modules + project README + ARCHITECTURE + EXAMPLES)
+    - Level 1: Module tree documentation
+    - Level 2: Project README.md
+    - Level 3: ARCHITECTURE.md + EXAMPLES.md + HTTP API (optional)
+  - `partial`: Module documentation only
+    - Level 1: Module tree documentation (API.md + README.md)
+    - Skips project-level documentation
+
+- **--tool**: CLI tool selection (default: gemini)
+  - `gemini`: Comprehensive documentation, pattern recognition
+  - `qwen`: Architecture analysis, system design focus
+  - `codex`: Implementation validation, code quality
+
+- **--cli-generate**: Enable CLI-based documentation generation (optional)
+  - When enabled: CLI generates docs with MODE=write in implementation_approach
+  - When disabled (default): CLI analyzes with MODE=analysis in pre_analysis
+
+## Planning Workflow
+
+### Phase 1: Initialize Session
+
+#### Step 1: Create Session and Generate Config
+```bash
+# Create session structure and initialize config in one step
+bash(
+  # Parse arguments
+  path="${1:-.}"
+  tool="gemini"
+  mode="full"
+  cli_generate=false
+  shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --tool) tool="$2"; shift 2 ;;
+      --mode) mode="$2"; shift 2 ;;
+      --cli-generate) cli_generate=true; shift ;;
+      *) shift ;;
+    esac
+  done
+
+  # Detect paths
+  project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  if [[ "$path" == /* ]] || [[ "$path" == [A-Z]:* ]]; then
+    target_path="$path"
+  else
+    target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path")
+  fi
+
+  # Create session
+  timestamp=$(date +%Y%m%d-%H%M%S)
+  session="WFS-docs-${timestamp}"
+  mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
+  touch ".workflow/.active-${session}"
+
+  # Generate single config file with all info
+  cat > ".workflow/${session}/.process/config.json" <<EOF
+{
+  "session_id": "${session}",
+  "timestamp": "$(date -Iseconds)",
+  "path": "${path}",
+  "target_path": "${target_path}",
+  "project_root": "${project_root}",
+  "mode": "${mode}",
+  "tool": "${tool}",
+  "cli_generate": ${cli_generate}
+}
+EOF
+
+  echo "✓ Session initialized: ${session}"
+  echo "✓ Target: ${target_path}"
+  echo "✓ Mode: ${mode}"
+  echo "✓ Tool: ${tool}, CLI generate: ${cli_generate}"
+)
+```
+
+**Output**:
+```
+✓ Session initialized: WFS-docs-20240120-143022
+✓ Target: /d/Claude_dms3
+✓ Mode: full
+✓ Tool: gemini, CLI generate: false
+```
+
+### Phase 2: Analyze Structure
+
+**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack (Node.js/Python/Go/Rust/etc).
+
+#### Step 1: Discover and Classify Folders
+```bash
+# Run analysis pipeline (module discovery + folder classification + smart filtering)
+bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+```
+
+**Output Sample** (folder-analysis.txt):
+```
+./src/modules/auth|code|code:5|dirs:2
+./src/modules/api|code|code:3|dirs:0
+./src/utils|navigation|code:0|dirs:4
+```
+
+**Auto-skipped**:
+- Tests: `**/test/**`, `**/*.test.*`, `**/__tests__/**`
+- Build: `**/node_modules/**`, `**/dist/**`, `**/build/**`
+- Config: Root-level config files (package.json, tsconfig.json, etc)
+- Vendor: Language-specific dependency directories
+
+#### Step 2: Extract Top-Level Directories
+```bash
+# Group folders by top-level directory
+bash(awk -F'|' '{
+  path = $1
+  gsub(/^\.\//, "", path)
+  split(path, parts, "/")
+  if (length(parts) >= 2) print parts[1] "/" parts[2]
+  else if (length(parts) == 1 && parts[1] != ".") print parts[1]
+}' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | sort -u > .workflow/WFS-docs-20240120/.process/top-level-dirs.txt)
+```
+
+**Output** (top-level-dirs.txt):
+```
+src/modules
+src/utils
+lib/core
+```
+
+#### Step 3: Generate Analysis Summary
+```bash
+# Calculate statistics
+bash(
+  total=$(wc -l < .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+  code_count=$(grep '|code|' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | wc -l)
+  nav_count=$(grep '|navigation|' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | wc -l)
+  top_dirs=$(wc -l < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt)
+
+  echo "📊 Folder Analysis Complete:"
+  echo "  - Total folders: $total"
+  echo "  - Code folders: $code_count"
+  echo "  - Navigation folders: $nav_count"
+  echo "  - Top-level dirs: $top_dirs"
+)
+
+# Update config with statistics
+bash(jq '. + {analysis: {total: "15", code: "8", navigation: "7", top_level: "3"}}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json)
+```
+
+### Phase 3: Detect Update Mode
+
+#### Step 1: Count Existing Documentation in .workflow/docs/
+```bash
+# Check .workflow/docs/ directory and count existing files
+bash(if [[ -d ".workflow/docs" ]]; then
+  find .workflow/docs -name "*.md" 2>/dev/null | wc -l
+else
+  echo "0"
+fi)
+```
+
+**Output**: `5` (existing docs in .workflow/docs/)
+
+#### Step 2: List Existing Documentation
+```bash
+# List existing files in .workflow/docs/ (for task context)
+bash(if [[ -d ".workflow/docs" ]]; then
+  find .workflow/docs -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120/.process/existing-docs.txt
+else
+  touch .workflow/WFS-docs-20240120/.process/existing-docs.txt
+fi)
+```
+
+**Output** (existing-docs.txt):
+```
+.workflow/docs/src/modules/auth/API.md
+.workflow/docs/src/modules/auth/README.md
+.workflow/docs/lib/core/README.md
+.workflow/docs/README.md
+```
+
+#### Step 3: Update Config with Update Status
+```bash
+# Determine update status (create or update) and update config
+bash(
+  existing_count=$(find .workflow/docs -name "*.md" 2>/dev/null | wc -l)
+  if [[ $existing_count -gt 0 ]]; then
+    jq ". + {update_mode: \"update\", existing_docs: $existing_count}" .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
+  else
+    jq '. + {update_mode: "create", existing_docs: 0}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
+  fi
+)
+
+# Display strategy summary
+bash(
+  mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+  update_mode=$(jq -r '.update_mode' .workflow/WFS-docs-20240120/.process/config.json)
+  existing=$(jq -r '.existing_docs' .workflow/WFS-docs-20240120/.process/config.json)
+  tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+  cli_gen=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
+
+  echo "📋 Documentation Strategy:"
+  echo "  - Path: $(jq -r '.target_path' .workflow/WFS-docs-20240120/.process/config.json)"
+  echo "  - Mode: $mode ($([ "$mode" = "full" ] && echo "complete docs" || echo "modules only"))"
+  echo "  - Update: $update_mode ($existing existing files)"
+  echo "  - Tool: $tool, CLI generate: $cli_gen"
+)
+```
+
+### Phase 4: Decompose Tasks
+
+#### Task Hierarchy
+```
+Level 1: Module Trees (always, parallel execution)
+  ├─ IMPL-001: Document 'src/modules/'
+  ├─ IMPL-002: Document 'src/utils/'
+  └─ IMPL-003: Document 'lib/'
+
+Level 2: Project README (mode=full only, depends on Level 1)
+  └─ IMPL-004: Generate Project README
+
+Level 3: Architecture & Examples (mode=full only, depends on Level 2)
+  ├─ IMPL-005: Generate ARCHITECTURE.md + EXAMPLES.md
+  └─ IMPL-006: Generate HTTP API (optional)
+```
+
+#### Step 1: Generate Level 1 Tasks (Module Trees)
+```bash
+# Read top-level directories and create tasks
+bash(
+  task_count=0
+  while read -r top_dir; do
+    task_count=$((task_count + 1))
+    task_id=$(printf "IMPL-%03d" $task_count)
+    echo "Creating $task_id for '$top_dir'"
+    # Generate task JSON (see Task Templates section)
+  done < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt
+)
+```
+
+**Output**:
+```
+Creating IMPL-001 for 'src/modules'
+Creating IMPL-002 for 'src/utils'
+Creating IMPL-003 for 'lib'
+```
+
+#### Step 2: Generate Level 2-3 Tasks (Full Mode Only)
+```bash
+# Check documentation mode
+bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+
+# If full mode, create project-level tasks
+bash(
+  mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+  if [[ "$mode" == "full" ]]; then
+    echo "Creating IMPL-004: Project README"
+    echo "Creating IMPL-005: ARCHITECTURE.md + EXAMPLES.md"
+    # Optional: Check for HTTP API endpoints
+    if grep -r "router\.|@Get\|@Post" src/ >/dev/null 2>&1; then
+      echo "Creating IMPL-006: HTTP API docs"
+    fi
+  else
+    echo "Partial mode: Skipping project-level tasks"
+  fi
+)
+```
+
+### Phase 5: Generate Task JSONs
+
+#### Step 1: Extract Configuration
+```bash
+# Read config values from JSON
+bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
+```
+
+**Output**: `tool=gemini`, `cli_generate=false`
+
+#### Step 2: Determine CLI Command Strategy
+```bash
+# Determine MODE and placement based on cli_generate flag
+bash(
+  cli_generate=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
+
+  if [[ "$cli_generate" == "true" ]]; then
+    echo "mode=write"
+    echo "placement=implementation_approach"
+    echo "approval_flag=--approval-mode yolo"
+  else
+    echo "mode=analysis"
+    echo "placement=pre_analysis"
+    echo "approval_flag="
+  fi
+)
+```
+
+**Output**:
+```
+mode=analysis
+placement=pre_analysis
+approval_flag=
+```
+
+#### Step 3: Build Tool-Specific Commands
+```bash
+# Generate command templates based on tool selection
+bash(
+  tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+
+  if [[ "$tool" == "codex" ]]; then
+    echo "codex -C \${dir} --full-auto exec \"...\" --skip-git-repo-check -s danger-full-access"
+  else
+    echo "bash(cd \${dir} && ~/.claude/scripts/${tool}-wrapper ${approval_flag} -p \"...\")"
+  fi
+)
+```
+
+## Task Templates
+
+### Level 1: Module Tree Task
+
+**Path Mapping**: Source `src/modules/` → Output `.workflow/docs/src/modules/`
+
+**Default Mode (cli_generate=false)**:
+```json
+{
+  "id": "IMPL-001",
+  "title": "Document Module Tree: 'src/modules/'",
+  "status": "pending",
+  "meta": {
+    "type": "docs-tree",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false,
+    "source_path": "src/modules",
+    "output_path": ".workflow/docs/src/modules"
+  },
+  "context": {
+    "requirements": [
+      "Analyze source code in src/modules/",
+      "Generate docs to .workflow/docs/src/modules/ (mirrored structure)",
+      "For code folders: generate API.md + README.md",
+      "For navigation folders: generate README.md only"
+    ],
+    "focus_paths": ["src/modules"],
+    "folder_analysis_file": "${session_dir}/.process/folder-analysis.txt"
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_docs",
+        "command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
+        "output_to": "existing_module_docs"
+      },
+      {
+        "step": "load_folder_analysis",
+        "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
+        "output_to": "target_folders"
+      },
+      {
+        "step": "analyze_module_tree",
+        "command": "bash(cd src/modules && gemini \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @**/* [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
+        "output_to": "tree_outline",
+        "note": "CLI for analysis only"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate module tree documentation",
+        "description": "Analyze source folders and generate docs to .workflow/docs/ with mirrored structure",
+        "modification_points": [
+          "Parse folder types from [target_folders]",
+          "Parse structure from [tree_outline]",
+          "For src/modules/auth/ → write to .workflow/docs/src/modules/auth/",
+          "Generate API.md for code folders",
+          "Generate README.md for all folders"
+        ],
+        "logic_flow": [
+          "Parse [target_folders] to get folder types",
+          "Parse [tree_outline] for structure",
+          "For each folder in source:",
+          "  - Map source_path to .workflow/docs/{source_path}",
+          "  - If type == 'code': Generate API.md + README.md",
+          "  - Elif type == 'navigation': Generate README.md only"
+        ],
+        "depends_on": [],
+        "output": "module_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/${top_dir}/*/API.md",
+      ".workflow/docs/${top_dir}/*/README.md"
+    ]
+  }
+}
+```
+
+**CLI Generate Mode (cli_generate=true)**:
+```json
+{
+  "id": "IMPL-001",
+  "title": "Document Module Tree: 'src/modules/'",
+  "status": "pending",
+  "meta": {
+    "type": "docs-tree",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": true,
+    "source_path": "src/modules",
+    "output_path": ".workflow/docs/src/modules"
+  },
+  "context": {
+    "requirements": [
+      "Analyze source code in src/modules/",
+      "Generate docs to .workflow/docs/src/modules/ (mirrored structure)",
+      "CLI generates documentation files directly"
+    ],
+    "focus_paths": ["src/modules"]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_docs",
+        "command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
+        "output_to": "existing_module_docs"
+      },
+      {
+        "step": "load_folder_analysis",
+        "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
+        "output_to": "target_folders"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Parse folder analysis",
+        "description": "Parse [target_folders] to get folder types and structure",
+        "modification_points": ["Extract folder types", "Identify code vs navigation folders"],
+        "logic_flow": ["Parse [target_folders] to get folder types", "Prepare folder list for CLI generation"],
+        "depends_on": [],
+        "output": "folder_types"
+      },
+      {
+        "step": 2,
+        "title": "Generate documentation via CLI",
+        "description": "Call CLI to generate docs to .workflow/docs/ with mirrored structure using MODE=write",
+        "modification_points": [
+          "Execute CLI generation command",
+          "Generate files to .workflow/docs/src/modules/ (mirrored path)",
+          "Generate API.md and README.md files"
+        ],
+        "logic_flow": [
+          "CLI analyzes source code in src/modules/",
+          "CLI writes documentation to .workflow/docs/src/modules/",
+          "Maintains directory structure mirroring"
+        ],
+        "command": "bash(cd src/modules && gemini --approval-mode yolo \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @**/* [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
+        "depends_on": [1],
+        "output": "generated_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/${top_dir}/*/API.md",
+      ".workflow/docs/${top_dir}/*/README.md"
+    ]
+  }
+}
+```
+
+### Level 2: Project README Task
+
+**Default Mode**:
+```json
+{
+  "id": "IMPL-004",
+  "title": "Generate Project README",
+  "status": "pending",
+  "depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_readme",
+        "command": "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'No existing README')",
+        "output_to": "existing_readme"
+      },
+      {
+        "step": "load_module_docs",
+        "command": "bash(find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)",
+        "output_to": "all_module_docs",
+        "note": "Load all module docs from mirrored structure"
+      },
+      {
+        "step": "analyze_project",
+        "command": "bash(gemini \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
+        "output_to": "project_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate project README",
+        "description": "Generate project README with navigation links while preserving existing user modifications",
+        "modification_points": ["Parse [project_outline] and [all_module_docs]", "Generate project README structure", "Add navigation links to modules", "Preserve [existing_readme] user modifications"],
+        "logic_flow": ["Parse [project_outline] and [all_module_docs]", "Generate project README with navigation links", "Preserve [existing_readme] user modifications"],
+        "depends_on": [],
+        "output": "project_readme"
+      }
+    ],
+    "target_files": [".workflow/docs/README.md"]
+  }
+}
+```
+
+### Level 3: Architecture & Examples Documentation Task
+
+**Default Mode**:
+```json
+{
+  "id": "IMPL-005",
+  "title": "Generate Architecture & Examples Documentation",
+  "status": "pending",
+  "depends_on": ["IMPL-004"],
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_docs",
+        "command": "bash(cat .workflow/docs/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE'; echo '---SEPARATOR---'; cat .workflow/docs/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')",
+        "output_to": "existing_arch_examples"
+      },
+      {
+        "step": "load_all_docs",
+        "command": "bash(cat .workflow/docs/README.md && find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)",
+        "output_to": "all_docs",
+        "note": "Load README + all module docs from mirrored structure"
+      },
+      {
+        "step": "analyze_architecture_and_examples",
+        "command": "bash(gemini \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")",
+        "output_to": "arch_examples_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate architecture and examples documentation",
+        "description": "Generate ARCHITECTURE.md and EXAMPLES.md while preserving existing user modifications",
+        "modification_points": [
+          "Parse [arch_examples_outline] and [all_docs]",
+          "Generate ARCHITECTURE.md structure with system design and patterns",
+          "Generate EXAMPLES.md structure with code snippets and usage examples",
+          "Preserve [existing_arch_examples] user modifications"
+        ],
+        "logic_flow": [
+          "Parse [arch_examples_outline] and [all_docs]",
+          "Generate ARCHITECTURE.md with system design",
+          "Generate EXAMPLES.md with code snippets",
+          "Preserve [existing_arch_examples] modifications"
+        ],
+        "depends_on": [],
+        "output": "arch_examples_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/ARCHITECTURE.md",
+      ".workflow/docs/EXAMPLES.md"
+    ]
+  }
+}
+```
+
+### Level 3: HTTP API Documentation Task (Optional)
+
+**Default Mode**:
+```json
+{
+  "id": "IMPL-006",
+  "title": "Generate HTTP API Documentation",
+  "status": "pending",
+  "depends_on": ["IMPL-004"],
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "discover_api_endpoints",
+        "command": "mcp__code-index__search_code_advanced(pattern='router\\.|@(Get|Post)', file_pattern='*.{ts,js}')",
+        "output_to": "endpoint_discovery"
+      },
+      {
+        "step": "load_existing_api_docs",
+        "command": "bash(cat .workflow/docs/api/README.md 2>/dev/null || echo 'No existing API docs')",
+        "output_to": "existing_api_docs"
+      },
+      {
+        "step": "analyze_api",
+        "command": "bash(gemini \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\")",
+        "output_to": "api_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate HTTP API documentation",
+        "description": "Generate HTTP API documentation while preserving existing user modifications",
+        "modification_points": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Document endpoints and request/response formats", "Preserve [existing_api_docs] modifications"],
+        "logic_flow": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Preserve [existing_api_docs] modifications"],
+        "depends_on": [],
+        "output": "api_docs"
+      }
+    ],
+    "target_files": [".workflow/docs/api/README.md"]
+  }
+}
+```
+
+## Session Structure
+
+```
+.workflow/
+├── .active-WFS-docs-20240120-143022        # Active session marker
+└── WFS-docs-20240120-143022/
+    ├── IMPL_PLAN.md                         # Implementation plan
+    ├── TODO_LIST.md                         # Progress tracker
+    ├── .process/
+    │   ├── config.json                      # Single config (all settings + stats)
+    │   ├── folder-analysis.txt              # Folder classification results
+    │   ├── top-level-dirs.txt               # Top-level directory list
+    │   └── existing-docs.txt                # Existing documentation paths
+    └── .task/
+        ├── IMPL-001.json                    # Module tree task
+        ├── IMPL-002.json                    # Module tree task
+        ├── IMPL-003.json                    # Module tree task
+        ├── IMPL-004.json                    # Project README (full mode)
+        ├── IMPL-005.json                    # ARCHITECTURE.md + EXAMPLES.md (full mode)
+        └── IMPL-006.json                    # HTTP API docs (optional)
+```
+
+**Config File Structure** (config.json):
+```json
+{
+  "session_id": "WFS-docs-20240120-143022",
+  "timestamp": "2024-01-20T14:30:22+08:00",
+  "path": ".",
+  "target_path": "/d/Claude_dms3",
+  "project_root": "/d/Claude_dms3",
+  "mode": "full",
+  "tool": "gemini",
+  "cli_generate": false,
+  "update_mode": "update",
+  "existing_docs": 5,
+  "analysis": {
+    "total": "15",
+    "code": "8",
+    "navigation": "7",
+    "top_level": "3"
+  }
+}
+```
+
+## Generated Documentation
+
+**Structure mirrors project source directories**:
+
+```
+.workflow/docs/
+├── src/                               # Mirrors src/ directory
+│   ├── modules/                       # Level 1 output
+│   │   ├── README.md                  # Navigation for src/modules/
+│   │   ├── auth/
+│   │   │   ├── API.md                 # Auth module API signatures
+│   │   │   ├── README.md              # Auth module documentation
+│   │   │   └── middleware/
+│   │   │       ├── API.md             # Middleware API
+│   │   │       └── README.md          # Middleware docs
+│   │   └── api/
+│   │       ├── API.md                 # API module signatures
+│   │       └── README.md              # API module docs
+│   └── utils/                         # Level 1 output
+│       └── README.md                  # Utils navigation
+├── lib/                               # Mirrors lib/ directory
+│   └── core/
+│       ├── API.md
+│       └── README.md
+├── README.md                          # Level 2 output (root only)
+├── ARCHITECTURE.md                    # Level 3 output (root only)
+├── EXAMPLES.md                        # Level 3 output (root only)
+└── api/                               # Level 3 output (optional)
+    └── README.md                      # HTTP API reference
+```
+
+## Execution Commands
+
+```bash
+# Execute entire workflow (auto-discovers active session)
+/workflow:execute
+
+# Or specify session
+/workflow:execute --resume-session="WFS-docs-yyyymmdd-hhmmss"
+
+# Individual task execution (if needed)
+/task:execute IMPL-001
+```
+
+## Simple Bash Commands
+
+### Session Management
+```bash
+# Create session and initialize config (all in one)
+bash(
+  session="WFS-docs-$(date +%Y%m%d-%H%M%S)"
+  mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
+  touch ".workflow/.active-${session}"
+  cat > ".workflow/${session}/.process/config.json" <<EOF
+{"session_id":"${session}","timestamp":"$(date -Iseconds)","path":".","mode":"full","tool":"gemini","cli_generate":false}
+EOF
+  echo "Session: ${session}"
+)
+
+# Read session config
+bash(cat .workflow/WFS-docs-20240120/.process/config.json)
+
+# Extract config values
+bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+
+# List session tasks
+bash(ls .workflow/WFS-docs-20240120/.task/*.json)
+```
+
+### Analysis Commands
+```bash
+# Discover and classify folders (scans project source)
+bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
+
+# Count existing docs (in .workflow/docs/ directory)
+bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null | wc -l; else echo "0"; fi)
+
+# List existing documentation (in .workflow/docs/ directory)
+bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null; fi)
+```
+
+## Template Reference
+
+**Available Templates**:
+- `api.txt`: Unified template for Code API (Part A) and HTTP API (Part B)
+- `module-readme.txt`: Module purpose, usage, dependencies
+- `folder-navigation.txt`: Navigation README for folders with subdirectories
+- `project-readme.txt`: Project overview, getting started, module navigation
+- `project-architecture.txt`: System structure, module map, design patterns
+- `project-examples.txt`: End-to-end usage examples
+
+**Template Location**: `~/.claude/workflows/cli-templates/prompts/documentation/`
+
+## CLI Generate Mode Summary
+
+| Mode | CLI Placement | CLI MODE | Agent Role |
+|------|---------------|----------|------------|
+| **Default** | pre_analysis | analysis | Generates documentation files |
+| **--cli-generate** | implementation_approach | write | Validates and coordinates CLI output |
+
+## Related Commands
+- `/workflow:execute` - Execute documentation tasks
+- `/workflow:status` - View task progress
+- `/workflow:session:complete` - Mark session complete

.claude/commands/memory/load.md

@@ -0,0 +1,240 @@
+---
+name: load
+description: Load project memory by delegating to agent, returns structured core content package for subsequent operations
+argument-hint: "[--tool gemini|qwen] \"task context description\""
+allowed-tools: Task(*), Bash(*)
+examples:
+  - /memory:load "在当前前端基础上开发用户认证功能"
+  - /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.
+
+**Core Philosophy**:
+- **Agent-Driven**: Fully delegates execution to general-purpose 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
+- **Token Efficiency**: CLI analysis executed within agent to save tokens
+
+## 2. Parameters
+
+- `"task context description"` (Required): Task description to guide context extraction
+  - Example: "在当前前端基础上开发用户认证功能"
+  - Example: "重构支付模块API"
+  - Example: "修复数据库查询性能问题"
+
+- `--tool <gemini|qwen>` (Optional): Specify CLI tool for agent to use (default: gemini)
+  - gemini: Large context window, suitable for complex project analysis
+  - qwen: Alternative to Gemini with similar capabilities
+
+## 3. Agent-Driven Execution Flow
+
+The command fully delegates to **general-purpose 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
+3. **Extracts Keywords**: Derives core keywords from task description
+4. **Discovers Files**: Uses MCP code-index or rg/find to locate relevant files
+5. **CLI Deep Analysis**: Executes Gemini/Qwen CLI for deep context analysis
+6. **Generates Content Package**: Returns structured JSON core content package
+
+## 4. Core Content Package Structure
+
+**Output Format** - Loaded into main thread memory for subsequent use:
+
+```json
+{
+  "task_context": "在当前前端基础上开发用户认证功能",
+  "keywords": ["前端", "用户", "认证", "auth", "login"],
+  "project_summary": {
+    "architecture": "TypeScript + React frontend with Vite build system",
+    "tech_stack": ["React", "TypeScript", "Vite", "TailwindCSS"],
+    "key_patterns": [
+      "State management via Context API",
+      "Functional components with Hooks pattern",
+      "API calls encapsulated in custom hooks"
+    ]
+  },
+  "relevant_files": [
+    {
+      "path": "src/components/Auth/LoginForm.tsx",
+      "relevance": "Existing login form component",
+      "priority": "high"
+    },
+    {
+      "path": "src/contexts/AuthContext.tsx",
+      "relevance": "Authentication state management context",
+      "priority": "high"
+    },
+    {
+      "path": "CLAUDE.md",
+      "relevance": "Project development standards",
+      "priority": "high"
+    }
+  ],
+  "integration_points": [
+    "Must integrate with existing AuthContext",
+    "Follow component organization pattern: src/components/[Feature]/",
+    "API calls should use src/hooks/useApi.ts wrapper"
+  ],
+  "constraints": [
+    "Maintain backward compatibility",
+    "Follow TypeScript strict mode",
+    "Use existing UI component library"
+  ]
+}
+```
+
+## 5. Agent Invocation
+
+```javascript
+Task(
+  subagent_type="general-purpose",
+  description="Load project memory: ${task_description}",
+  prompt=`
+## Mission: Load Project Memory Context
+
+**Task Context**: "${task_description}"
+**Mode**: Read-only analysis
+**Tool**: ${tool || 'gemini'}
+
+## Execution Steps
+
+### Step 1: Foundation Analysis
+
+1. **Project Structure**
+   \`\`\`bash
+   bash(~/.claude/scripts/get_modules_by_depth.sh)
+   \`\`\`
+
+2. **Core Documentation**
+   \`\`\`javascript
+   Read(CLAUDE.md)
+   Read(README.md)
+   \`\`\`
+
+### 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)
+
+   // Fallback: use rg
+   bash(rg -l "{keyword}" --type ts --type md)
+   \`\`\`
+
+### Step 3: Deep Analysis via CLI
+
+Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens):
+
+\`\`\`bash
+cd . && ~/.claude/scripts/${tool}-wrapper -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}
+EXPECTED: Structured project summary and integration point analysis
+RULES:
+- Focus on task-relevant core information
+- Identify key architecture patterns and technical constraints
+- Extract integration points and development standards
+- Output concise, structured format
+"
+\`\`\`
+
+### Step 4: Generate Core Content Package
+
+Generate structured JSON content package (format shown above)
+
+**Required Fields**:
+- task_context: Original task description
+- keywords: Extracted keyword array
+- project_summary: Architecture, tech stack, key patterns
+- relevant_files: File list with path, relevance, priority
+- integration_points: Integration guidance
+- constraints: Development constraints
+
+### Step 5: Return Content Package
+
+Return JSON content package as final output for main thread to load into memory.
+
+## Quality Checklist
+
+Before returning:
+- [ ] Valid JSON format
+- [ ] All required fields complete
+- [ ] relevant_files contains 3-10 files minimum
+- [ ] project_summary accurately reflects architecture
+- [ ] integration_points clearly specify integration paths
+- [ ] keywords accurately extracted (3-8 keywords)
+- [ ] Content concise, avoiding redundancy (< 5KB total)
+
+  `
+)
+```
+
+## 6. Usage Examples
+
+### Example 1: Load Context for New Feature
+
+```bash
+/memory:load "在当前前端基础上开发用户认证功能"
+```
+
+**Agent Execution**:
+1. Analyzes project structure (`get_modules_by_depth.sh`)
+2. Reads CLAUDE.md, README.md
+3. Extracts keywords: ["前端", "用户", "认证", "auth"]
+4. Uses MCP to search relevant files
+5. Executes Gemini CLI for deep analysis
+6. Returns core content package
+
+**Returned Package** (loaded into memory):
+```json
+{
+  "task_context": "在当前前端基础上开发用户认证功能",
+  "keywords": ["前端", "认证", "auth", "login"],
+  "project_summary": { ... },
+  "relevant_files": [ ... ],
+  "integration_points": [ ... ],
+  "constraints": [ ... ]
+}
+```
+
+### Example 2: Using Qwen Tool
+
+```bash
+/memory:load --tool qwen -p "重构支付模块API"
+```
+
+Agent uses Qwen CLI for analysis, returns same structured package.
+
+### Example 3: Bug Fix Context
+
+```bash
+/memory:load "修复登录验证错误"
+```
+
+Returns core context related to login validation, including test files and validation logic.
+
+### Memory Persistence
+
+- **Session-Scoped**: Content package valid for current session
+- **Subsequent Reference**: All subsequent agents/commands can access
+- **Reload Required**: New sessions need to re-execute /memory:load
+
+## 8. Notes
+
+- **Read-Only**: Does not modify any code, pure analysis
+- **Token Optimization**: CLI analysis executed within agent, saves main thread tokens
+- **Memory Loading**: Returned JSON loaded directly into main thread memory
+- **Subsequent Use**: Other commands/agents can reference this package for development
+- **Session-Level**: Content package valid for current session

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

@@ -0,0 +1,329 @@
+---
+name: update-full
+description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback
+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
+
+  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 CLI wrapper (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-related.md

@@ -0,0 +1,352 @@
+---
+name: update-related
+description: Context-aware CLAUDE.md documentation updates based on recent changes with agent-based execution and tool fallback
+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
+# Refresh code index
+bash(mcp__code-index__refresh_index)
+
+# Detect changed modules
+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/task/breakdown.md

@@ -68,7 +68,21 @@ Define subtasks manually (remaining capacity: 4 tasks):
    - "User authentication" and "OAuth integration" both handle auth
    - Consider combining into single task
 
-Proceed with breakdown? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "File conflicts and/or similar functionality detected. How do you want to proceed?",
+    header: "Confirm",
+    options: [
+      { label: "Proceed with breakdown", description: "Accept the risks and create the subtasks as defined." },
+      { label: "Restart breakdown", description: "Discard current subtasks and start over." },
+      { label: "Cancel breakdown", description: "Abort the operation and leave the parent task as is." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Proceed with breakdown"
 
 ✅ Task IMPL-1 broken down:
 ▸ IMPL-1: Build authentication module (container)

.claude/commands/task/replan.md

@@ -1,57 +1,95 @@
 ---
 name: replan
 description: Replan individual tasks with detailed user input and change tracking
-argument-hint: "task-id [\"text\"|file.md]"
+argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Task Replan Command (/task:replan)
 
 ## Overview
-Replans individual tasks with multiple input options, change tracking, and version management.
+Replans individual tasks or batch processes multiple tasks with change tracking and backup management.
+
+**Modes**:
+- **Single Task Mode**: Replan one task with specific changes
+- **Batch Mode**: Process multiple tasks from action-plan verification report
 
 ## Core Principles
 **Task System:** @~/.claude/workflows/task-core.md
 
 ## Key Features
-- **Single-Task Focus**: Operates on individual tasks only
-- **Multiple Input Sources**: Text, files, or issue references
-- **Version Tracking**: Backup previous versions
+- **Single/Batch Operations**: Single task or multiple tasks from verification report
+- **Multiple Input Sources**: Text, files, or verification report
+- **Backup Management**: Automatic backup of previous versions
 - **Change Documentation**: Track all modifications
+- **Progress Tracking**: TodoWrite integration for batch operations
 
 ⚠️ **CRITICAL**: Validates active session before replanning
 
-## Input Sources
+## Operation Modes
 
-### Direct Text (Default)
+### Single Task Mode
+
+#### Direct Text (Default)
 ```bash
 /task:replan IMPL-1 "Add OAuth2 authentication support"
 ```
 
-### File-based Input
+#### File-based Input
 ```bash
 /task:replan IMPL-1 updated-specs.md
 ```
 Supports: .md, .txt, .json, .yaml
 
-### Interactive Mode
+#### Interactive Mode
 ```bash
 /task:replan IMPL-1 --interactive
 ```
 Guided step-by-step modification process with validation
 
+### Batch Mode
+
+#### From Verification Report
+```bash
+/task:replan --batch ACTION_PLAN_VERIFICATION.md
+```
+
+**Workflow**:
+1. Parse verification report to extract replan recommendations
+2. Create TodoWrite task list for all modifications
+3. Process each task sequentially with confirmation
+4. Track progress and generate summary report
+
+**Auto-detection**: If input file contains "Action Plan Verification Report" header, automatically enters batch mode
+
 ## Replanning Process
 
+### Single Task Process
+
 1. **Load & Validate**: Read task JSON and validate session
 2. **Parse Input**: Process changes from input source
-3. **Backup Version**: Create previous version backup
+3. **Create Backup**: Save previous version to backup folder
 4. **Update Task**: Modify JSON structure and relationships
 5. **Save Changes**: Write updated task and increment version
 6. **Update Session**: Reflect changes in workflow stats
 
-## Version Management
+### Batch Process
 
-### Version Tracking
-Tasks maintain version history:
+1. **Parse Verification Report**: Extract all replan recommendations
+2. **Initialize TodoWrite**: Create task list for tracking
+3. **For Each Task**:
+   - Mark todo as in_progress
+   - Load and validate task JSON
+   - Create backup
+   - Apply recommended changes
+   - Save updated task
+   - Mark todo as completed
+4. **Generate Summary**: Report all changes and backup locations
+
+## Backup Management
+
+### Backup Tracking
+Tasks maintain backup history:
 ```json
 {
   "id": "IMPL-1",
@@ -61,7 +99,8 @@ Tasks maintain version history:
       "version": "1.2",
       "reason": "Add OAuth2 support",
       "input_source": "direct_text",
-      "backup_location": ".task/versions/IMPL-1-v1.1.json"
+      "backup_location": ".task/backup/IMPL-1-v1.1.json",
+      "timestamp": "2025-10-17T10:30:00Z"
     }
   ]
 }
@@ -73,11 +112,15 @@ Tasks maintain version history:
 ```
 .task/
 ├── IMPL-1.json                    # Current version
-├── versions/
-│   └── IMPL-1-v1.1.json          # Previous backup
+├── backup/
+│   ├── IMPL-1-v1.0.json          # Original version
+│   ├── IMPL-1-v1.1.json          # Previous backup
+│   └── IMPL-1-v1.2.json          # Latest backup
 └── [new subtasks as needed]
 ```
 
+**Backup Naming**: `{task-id}-v{version}.json`
+
 ## Implementation Updates
 
 ### Change Detection
@@ -127,18 +170,68 @@ Updates workflow-session.json with:
 /task:replan IMPL-1 --rollback v1.1
 
 Rollback to version 1.1:
-- Restore task from backup
+- Restore task from backup/.../IMPL-1-v1.1.json
 - Remove new subtasks if any
 - Update session stats
 
-Confirm rollback? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "Are you sure you want to roll back this task to a previous version?",
+    header: "Confirm",
+    options: [
+      { label: "Yes, rollback", description: "Restore the task from the selected backup." },
+      { label: "No, cancel", description: "Keep the current version of the task." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Yes, rollback"
 
 ✅ Task rolled back to version 1.1
 ```
 
+## Batch Processing with TodoWrite
+
+### Progress Tracking
+When processing multiple tasks, automatically creates TodoWrite task list:
+
+```markdown
+**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-008: Add NFR performance validation steps
+```
+
+### Batch Report
+After completion, generates summary:
+```markdown
+## Batch Replan Summary
+
+**Total Tasks**: 4
+**Successful**: 3
+**Failed**: 1
+**Skipped**: 0
+
+### Changes Made
+- IMPL-002 v1.0 → v1.1: Added FR-12 acceptance criteria
+- IMPL-003 v1.0 → v1.1: Added FR-14 acceptance criteria
+- IMPL-004 v1.0 → v1.1: Added FR-09 explicit coverage
+
+### Backups Created
+- .task/backup/IMPL-002-v1.0.json
+- .task/backup/IMPL-003-v1.0.json
+- .task/backup/IMPL-004-v1.0.json
+
+### Errors
+- IMPL-008: File not found (task may have been renamed)
+```
+
 ## Examples
 
-### Text Input
+### Single Task - Text Input
 ```bash
 /task:replan IMPL-1 "Add OAuth2 authentication support"
 
@@ -147,14 +240,27 @@ Proposed updates:
 + Add OAuth2 integration
 + Update authentication flow
 
-Apply changes? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "Do you want to apply these changes to the task?",
+    header: "Apply",
+    options: [
+      { label: "Yes, apply", description: "Create new version with these changes." },
+      { label: "No, cancel", description: "Discard changes and keep current version." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Yes, apply"
 
 ✓ Version 1.2 created
 ✓ Context updated
-✓ Backup saved
+✓ Backup saved to .task/backup/IMPL-1-v1.1.json
 ```
 
-### File Input
+### Single Task - File Input
 ```bash
 /task:replan IMPL-2 requirements.md
 
@@ -163,14 +269,59 @@ Applying specification changes...
 
 ✓ Task updated with new requirements
 ✓ Version 1.1 created
+✓ Backup saved to .task/backup/IMPL-2-v1.0.json
+```
+
+### Batch Mode - From Verification Report
+```bash
+/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+
+Parsing verification report...
+Found 4 tasks requiring replanning:
+- IMPL-002: Add FR-12 draft saving acceptance criteria
+- IMPL-003: Add FR-14 history tracking acceptance criteria
+- IMPL-004: Add FR-09 response surface explicit coverage
+- IMPL-008: Add NFR performance validation steps
+
+Creating task tracking list...
+
+Processing IMPL-002...
+✓ 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
+
+Processing IMPL-004...
+✓ 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
+
+✅ Batch replan completed: 4/4 successful
+📋 Summary report saved
+```
+
+### Batch Mode - Auto-detection
+```bash
+# If file contains "Action Plan Verification Report", auto-enters batch mode
+/task:replan ACTION_PLAN_VERIFICATION.md
+
+Detected verification report format
+Entering batch mode...
+[same as above]
 ```
 
 ## Error Handling
 
+### Single Task Errors
 ```bash
 # Task not found
 ❌ Task IMPL-5 not found
-→ Check task ID with /context
+→ Check task ID with /workflow:status
 
 # Task completed
 ⚠️ Task IMPL-1 is completed (cannot replan)
@@ -182,12 +333,112 @@ Applying specification changes...
 
 # No input provided
 ❌ Please specify changes needed
-→ Provide text, file, or issue reference
+→ 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
+
+# Partial failures
+⚠️ 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
+```
+
+## Batch Mode Integration
+
+### Input Format Expectations
+Batch mode parses verification reports looking for:
+
+1. **Required Actions Section**: Commands like `/task:replan IMPL-X "changes"`
+2. **Findings Table**: Task IDs with recommendations
+3. **Next Actions Section**: Specific replan commands
+
+**Example Patterns**:
+```markdown
+#### 1. HIGH Priority - Address FR Coverage Gaps
+/task:replan IMPL-004 "
+Add explicit acceptance criteria:
+- FR-09: Response surface 3D visualization
+"
+
+#### 2. MEDIUM Priority - Enhance NFR Coverage
+/task:replan IMPL-008 "
+Add performance testing:
+- NFR-01: Load test API endpoints
+"
+```
+
+### Extraction Logic
+1. Scan for `/task:replan` commands in report
+2. Extract task ID and change description
+3. Group by priority (HIGH, MEDIUM, LOW)
+4. Process in priority order with TodoWrite tracking
+
+### Confirmation Behavior
+- **Default**: Confirm each task before applying
+- **With `--auto-confirm`**: Apply all changes without prompting
+  ```bash
+  /task:replan --batch report.md --auto-confirm
+  ```
+
+## Implementation Details
+
+### Backup Management
+```typescript
+// Backup file naming convention
+const backupPath = `.task/backup/${taskId}-v${previousVersion}.json`;
+
+// Backup metadata in task JSON
+{
+  "replan_history": [
+    {
+      "version": "1.2",
+      "timestamp": "2025-10-17T10:30:00Z",
+      "reason": "Add FR-09 explicit coverage",
+      "input_source": "batch_verification_report",
+      "backup_location": ".task/backup/IMPL-004-v1.1.json"
+    }
+  ]
+}
+```
+
+### TodoWrite Integration
+```typescript
+// Initialize tracking for batch mode
+TodoWrite({
+  todos: taskList.map(task => ({
+    content: `${task.id}: ${task.changeDescription}`,
+    status: "pending",
+    activeForm: `Replanning ${task.id}`
+  }))
+});
+
+// Update progress during processing
+TodoWrite({
+  todos: updateTaskStatus(taskId, "in_progress")
+});
+
+// Mark completed
+TodoWrite({
+  todos: updateTaskStatus(taskId, "completed")
+});
 ```
 
 ## Related Commands
 
-- `/context` - View updated task structure
+- `/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
-- `/workflow:action-plan` - For workflow-wide changes
+- `/task:breakdown` - Break down complex tasks
+
+## Context
+
+$ARGUMENTS

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

@@ -1,174 +0,0 @@
----
-name: update-memory-full
-description: Complete project-wide CLAUDE.md documentation update
-argument-hint: "[--tool gemini|qwen|codex]"
----
-
-### 🚀 Command Overview: `/update-memory-full`
-
-Complete project-wide documentation update using depth-parallel execution.
-
-**Tool Selection**:
-- **Gemini (default)**: Documentation generation, pattern recognition, architecture review
-- **Qwen**: Architecture analysis, system design documentation
-- **Codex**: Implementation validation, code quality analysis
-
-### 📝 Execution Template
-
-```bash
-#!/bin/bash
-# Complete project-wide CLAUDE.md documentation update
-
-# Step 1: Parse tool selection (default: gemini)
-tool="gemini"
-[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
-[[ "$*" == *"--tool codex"* ]] && tool="codex"
-
-# Step 2: Code Index architecture analysis
-mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
-mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}")
-
-# Step 3: Cache git changes
-Bash(git add -A 2>/dev/null || true)
-
-# Step 4: Get and display project structure
-modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
-count=$(echo "$modules" | wc -l)
-
-# Step 5: Analysis handover → Model takes control
-# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
-
-# Pseudocode flow:
-# IF (module_count > 20 OR complex_project_detected):
-#     → Task "Complex project full update" subagent_type: "memory-bridge"
-# ELSE:
-#     → Present plan and WAIT FOR USER APPROVAL before execution
-#
-# Pass tool parameter to update_module_claude.sh: "$tool"
-```
-
-### 🧠 Model Analysis Phase
-
-After the bash script completes the initial analysis, the model takes control to:
-
-1. **Analyze Complexity**: Review module count and project context
-2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files
-3. **Choose Strategy**:
-   - Simple projects: Present execution plan with CLAUDE.md paths to user
-   - Complex projects: Delegate to memory-bridge agent
-4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated
-5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
-
-### 📋 Execution Strategies
-
-**For Simple Projects (≤20 modules):**
-
-Model will present detailed plan:
-```
-📋 Update Plan:
-  Tool: [gemini|qwen|codex] (from --tool parameter)
-
-  NEW CLAUDE.md files (X):
-    - ./src/components/CLAUDE.md
-    - ./src/services/CLAUDE.md
-
-  UPDATE existing CLAUDE.md files (Y):
-    - ./CLAUDE.md
-    - ./src/CLAUDE.md
-    - ./tests/CLAUDE.md
-
-  Total: N CLAUDE.md files will be processed
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-```pseudo
-# ⚠️ MANDATORY: User confirmation → MUST await explicit approval  
-IF user_explicitly_confirms():
-    continue_execution()
-ELSE:
-    abort_execution()
-
-# Step 4: Organize modules by depth → Prepare execution
-depth_modules = organize_by_depth(modules)
-
-# Step 5: Execute depth-parallel updates → Process by depth
-FOR depth FROM max_depth DOWN TO 0:
-    FOR each module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" "$tool" &)
-    wait_all_jobs()
-
-# Step 6: Safety check and restore staging state
-non_claude=$(Bash(git diff --cached --name-only | grep -v "CLAUDE.md" || true))
-if [ -n "$non_claude" ]; then
-    Bash(git restore --staged .)
-    echo "⚠️ Warning: Non-CLAUDE.md files were modified, staging reverted"
-    echo "Modified files: $non_claude"
-else
-    echo "✅ Only CLAUDE.md files modified, staging preserved"
-fi
-
-# Step 7: Display changes → Final status
-Bash(git status --short)
-```
-
-**For Complex Projects (>20 modules):**
-
-The model will delegate to the memory-bridge agent with structured context:
-
-```javascript
-Task "Complex project full update"
-subagent_type: "memory-bridge"
-prompt: `
-CONTEXT:
-- Total modules: ${module_count}
-- Tool: ${tool}  // from --tool parameter, default: gemini
-- Mode: full
-- Existing CLAUDE.md: ${existing_count}
-- New CLAUDE.md needed: ${new_count}
-
-MODULE LIST:
-${modules_output}  // Full output from get_modules_by_depth.sh list
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level before execution
-2. Process depths 5→0 sequentially, max 4 parallel jobs per depth
-3. Command format: update_module_claude.sh "<path>" "full" "${tool}" &
-4. Extract exact path from "depth:N|path:<PATH>|..." format
-5. Verify all ${module_count} modules are processed
-6. Run safety check after completion
-7. Display git status
-
-Execute depth-parallel updates for all modules.
-`
-```
-
-**Agent receives complete context:**
-- Module count and tool selection
-- Full structured module list
-- Clear execution requirements
-- Path extraction format
-- Success criteria
-
-
-### 📚 Usage Examples
-
-```bash
-# Complete project documentation refresh
-/update-memory-full
-
-# After major architectural changes
-/update-memory-full
-```
-
-### ✨ Features
-
-- **Separated Commands**: Each bash operation is a discrete, trackable step
-- **Intelligent Complexity Detection**: Model analyzes project context for optimal strategy
-- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially
-- **Git Integration**: Auto-cache changes before, safety check and show status after
-- **Safety Protection**: Automatic detection and revert of unintended source code modifications
-- **Module Detection**: Uses get_modules_by_depth.sh for structure discovery
-- **User Confirmation**: Clear plan presentation with approval step
-- **CLAUDE.md Only**: Only updates documentation, never source code

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

@@ -1,182 +0,0 @@
----
-name: update-memory-related
-description: Context-aware CLAUDE.md documentation updates based on recent changes
-argument-hint: "[--tool gemini|qwen|codex]"
----
-
-### 🚀 Command Overview: `/update-memory-related`
-
-Context-aware documentation update for modules affected by recent changes.
-
-**Tool Selection**:
-- **Gemini (default)**: Documentation generation, pattern recognition, architecture review
-- **Qwen**: Architecture analysis, system design documentation
-- **Codex**: Implementation validation, code quality analysis
-
-
-### 📝 Execution Template
-
-```bash
-#!/bin/bash
-# Context-aware CLAUDE.md documentation update
-
-# Step 1: Parse tool selection (default: gemini)
-tool="gemini"
-[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
-[[ "$*" == *"--tool codex"* ]] && tool="codex"
-
-# Step 2: Code Index refresh and architecture analysis
-mcp__code-index__refresh_index()
-mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
-
-# Step 3: Detect changed modules (before staging)
-changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list))
-
-# Step 4: Cache git changes (protect current state)
-Bash(git add -A 2>/dev/null || true)
-
-# Step 5: Use detected changes or fallback
-if [ -z "$changed" ]; then
-    changed=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list | head -10))
-fi
-count=$(echo "$changed" | wc -l)
-
-# Step 6: Analysis handover → Model takes control
-# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
-
-# Pseudocode flow:
-# IF (change_count > 15 OR complex_changes_detected):
-#     → Task "Complex project related update" subagent_type: "memory-bridge"
-# ELSE:
-#     → Present plan and WAIT FOR USER APPROVAL before execution
-#
-# Pass tool parameter to update_module_claude.sh: "$tool"
-```
-
-### 🧠 Model Analysis Phase
-
-After the bash script completes change detection, the model takes control to:
-
-1. **Analyze Changes**: Review change count and complexity  
-2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files
-3. **Choose Strategy**: 
-   - Simple changes: Present execution plan with CLAUDE.md paths to user
-   - Complex changes: Delegate to memory-bridge agent
-4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules
-5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
-
-### 📋 Execution Strategies
-
-**For Simple Changes (≤15 modules):**
-
-Model will present detailed plan for affected modules:
-```
-📋 Related Update Plan:
-  Tool: [gemini|qwen|codex] (from --tool parameter)
-
-  CHANGED modules affecting CLAUDE.md:
-
-  NEW CLAUDE.md files (X):
-    - ./src/api/auth/CLAUDE.md  [new module]
-    - ./src/utils/helpers/CLAUDE.md  [new module]
-
-  UPDATE existing CLAUDE.md files (Y):
-    - ./src/api/CLAUDE.md  [parent of changed auth/]
-    - ./src/CLAUDE.md  [root level]
-
-  Total: N CLAUDE.md files will be processed for recent changes
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-```pseudo
-# ⚠️ MANDATORY: User confirmation → MUST await explicit approval
-IF user_explicitly_confirms():
-    continue_execution()
-ELSE:
-    abort_execution()
-
-# Step 4: Organize modules by depth → Prepare execution
-depth_modules = organize_by_depth(changed_modules)
-
-# Step 5: Execute depth-parallel updates → Process by depth
-FOR depth FROM max_depth DOWN TO 0:
-    FOR each module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" "$tool" &)
-    wait_all_jobs()
-
-# Step 6: Safety check and restore staging state
-non_claude=$(Bash(git diff --cached --name-only | grep -v "CLAUDE.md" || true))
-if [ -n "$non_claude" ]; then
-    Bash(git restore --staged .)
-    echo "⚠️ Warning: Non-CLAUDE.md files were modified, staging reverted"
-    echo "Modified files: $non_claude"
-else
-    echo "✅ Only CLAUDE.md files modified, staging preserved"
-fi
-
-# Step 7: Display changes → Final status
-Bash(git diff --stat)
-```
-
-**For Complex Changes (>15 modules):**
-
-The model will delegate to the memory-bridge agent with structured context:
-
-```javascript
-Task "Complex project related update"
-subagent_type: "memory-bridge"
-prompt: `
-CONTEXT:
-- Total modules: ${change_count}
-- Tool: ${tool}  // from --tool parameter, default: gemini
-- Mode: related
-- Changed modules detected via: detect_changed_modules.sh
-- Existing CLAUDE.md: ${existing_count}
-- New CLAUDE.md needed: ${new_count}
-
-MODULE LIST:
-${changed_modules_output}  // Full output from detect_changed_modules.sh list
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level before execution
-2. Process depths sequentially (deepest→shallowest), max 4 parallel jobs per depth
-3. Command format: update_module_claude.sh "<path>" "related" "${tool}" &
-4. Extract exact path from "depth:N|path:<PATH>|..." format
-5. Verify all ${change_count} modules are processed
-6. Run safety check after completion
-7. Display git diff --stat
-
-Execute depth-parallel updates for changed modules only.
-`
-```
-
-**Agent receives complete context:**
-- Changed module count and tool selection
-- Full structured module list (changed only)
-- Clear execution requirements with "related" mode
-- Path extraction format
-- Success criteria
-
-
-### 📚 Usage Examples
-
-```bash
-# Daily development update
-/update-memory-related
-
-# After feature work
-/update-memory-related
-```
-
-### ✨ Features
-
-- **Separated Commands**: Each bash operation is a discrete, trackable step
-- **Intelligent Change Analysis**: Model analyzes change complexity for optimal strategy
-- **Change Detection**: Automatically finds affected modules using git diff
-- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially  
-- **Git Integration**: Auto-cache changes, show diff statistics after
-- **Fallback Mode**: Updates recent files when no git changes found
-- **User Confirmation**: Clear plan presentation with approval step
-- **CLAUDE.md Only**: Only updates documentation, never source code

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

@@ -67,6 +67,11 @@ IF TASK_FILES.count == 0:
 
 Load only minimal necessary context from each artifact:
 
+**From workflow-session.json** (NEW - PRIMARY REFERENCE):
+- Original user prompt/intent (project or description field)
+- User's stated goals and objectives
+- User's scope definition
+
 **From synthesis-specification.md**:
 - Functional Requirements (IDs, descriptions, acceptance criteria)
 - Non-Functional Requirements (IDs, targets)
@@ -117,7 +122,14 @@ Create internal representations (do not include raw artifacts in output):
 
 Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
 
-#### A. Requirements Coverage Analysis
+#### A. User Intent Alignment (NEW - CRITICAL)
+
+- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
+- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
+- **Success Criteria Match**: Plan's success criteria reflect user's expectations
+- **Intent Conflicts**: Tasks contradicting user's original objectives
+
+#### B. Requirements Coverage Analysis
 
 - **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
 - **Unmapped Tasks**: Tasks with no clear requirement linkage
@@ -167,6 +179,7 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 Use this heuristic to prioritize findings:
 
 - **CRITICAL**:
+  - Violates user's original intent (goal misalignment, scope drift)
   - Violates synthesis authority (requirement conflict)
   - Core requirement with zero coverage
   - Circular dependencies
@@ -307,111 +320,63 @@ Output a Markdown report (no file writes) with the following structure:
 
 ### Next Actions
 
-#### If CRITICAL Issues Exist (Current Status: 2 CRITICAL)
-**Recommendation**: ❌ **BLOCK EXECUTION** - Resolve CRITICAL issues before proceeding
+#### Action Recommendations
 
-**Required Actions**:
-1. **CRITICAL**: Add authentication implementation tasks to cover FR-03
-2. **CRITICAL**: Add performance optimization tasks to cover NFR-01
+**If CRITICAL Issues Exist**:
+- ❌ **BLOCK EXECUTION** - Resolve critical issues before proceeding
+- Use `/task:create` for missing requirements coverage
+- Fix broken dependencies and circular references
 
-#### If Only HIGH/MEDIUM/LOW Issues
-**Recommendation**: ⚠️ **PROCEED WITH CAUTION** - Issues are non-blocking but should be addressed
+**If Only HIGH/MEDIUM/LOW Issues**:
+- ⚠️ **PROCEED WITH CAUTION** - Fix high-priority issues first
+- Use batch replan mode to apply all task improvements systematically
 
-**Suggested Improvements**:
-1. Add context.artifacts references to all tasks (use /task:replan)
-2. Fix broken dependency IMPL-2.3 → IMPL-2.4
-3. Add flow_control.target_files to underspecified tasks
+#### Batch Remediation
 
-#### Command Suggestions
+**Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
+
+**Apply All Task Improvements** (Recommended):
 ```bash
-# Fix critical coverage gaps
+# Batch process all task replan recommendations
+/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+
+# 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)"
 
-# Refine existing tasks
+# Then apply task refinements individually
 /task:replan IMPL-1.2 "Add context.artifacts and target_files"
-
-# Update IMPL_PLAN if architecture drift detected
-# (Manual edit required)
-```
 ```
 
-### 7. Provide Remediation Options
+**Notes**:
+- Batch mode extracts all `/task:replan` commands from report
+- Processes by priority: CRITICAL → HIGH → MEDIUM → LOW
+- Creates TodoWrite tracking for all modifications
+- Architecture drift in IMPL_PLAN requires manual editing
+```
 
-At end of report, ask the user:
+### 7. Save Report and Provide Remediation Options
+
+**Save Analysis Report**:
+```bash
+report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
+Write(report_path, full_report_content)
+```
+
+At end of report, provide batch remediation guidance:
 
 ```markdown
 ### 🔧 Remediation Options
 
-Would you like me to:
-1. **Generate task suggestions** for unmapped requirements (no auto-creation)
-2. **Provide specific edit commands** for top N issues (you execute manually)
-3. **Create remediation checklist** for systematic fixing
+**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
 
-(Do NOT apply fixes automatically - this is read-only analysis)
-```
-
-### 8. Update Session Metadata
-
-```json
-{
-  "phases": {
-    "PLAN": {
-      "status": "completed",
-      "action_plan_verification": {
-        "completed": true,
-        "completed_at": "timestamp",
-        "overall_risk_level": "HIGH",
-        "recommendation": "PROCEED_WITH_FIXES",
-        "issues": {
-          "critical": 2,
-          "high": 5,
-          "medium": 8,
-          "low": 3
-        },
-        "coverage": {
-          "functional_requirements": 0.85,
-          "non_functional_requirements": 0.40,
-          "business_requirements": 1.00
-        },
-        "report_path": ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
-      }
-    }
-  }
-}
-```
-
-## Operating Principles
-
-### Context Efficiency
-- **Minimal high-signal tokens**: Focus on actionable findings
-- **Progressive disclosure**: Load artifacts incrementally
-- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
-- **Deterministic results**: Rerunning without changes produces consistent IDs and counts
-
-### Analysis Guidelines
-- **NEVER modify files** (this is read-only analysis)
-- **NEVER hallucinate missing sections** (if absent, report them accurately)
-- **Prioritize synthesis violations** (these are always CRITICAL)
-- **Use examples over exhaustive rules** (cite specific instances)
-- **Report zero issues gracefully** (emit success report with coverage statistics)
-
-### Verification Taxonomy
-- **Coverage**: Requirements → Tasks mapping
-- **Consistency**: Cross-artifact alignment
-- **Dependencies**: Task ordering and relationships
-- **Synthesis Alignment**: Adherence to authoritative requirements
-- **Task Quality**: Specification completeness
-- **Feasibility**: Implementation risks
-
-## Behavior Rules
-
-- **If no issues found**: Report "✅ Action plan verification passed. No issues detected." and suggest proceeding to `/workflow:execute`.
-- **If CRITICAL issues exist**: Recommend blocking execution until resolved.
-- **If only HIGH/MEDIUM issues**: User may proceed with caution, but provide improvement suggestions.
-- **If IMPL_PLAN.md or task files missing**: Instruct user to run `/workflow:plan` first.
-- **Always provide actionable remediation suggestions**: Don't just identify problems—suggest solutions.
-
-## Context
-
-{ARGS}
+**Note**: All fixes require explicit user confirmation.

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

@@ -0,0 +1,585 @@
+---
+name: api-designer
+description: Generate or update api-designer/analysis.md addressing topic-framework discussion points
+argument-hint: "optional topic - uses existing framework if available"
+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.
+
+### Core Function
+- **Framework-based Analysis**: Address each discussion point in topic-framework.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
+
+### Analysis Scope
+- **API Architecture**: RESTful/GraphQL design patterns and best practices
+- **Endpoint Design**: Resource modeling, URL structure, and HTTP method selection
+- **Data Contracts**: Request/response schemas, validation rules, and data transformation
+- **API Documentation**: OpenAPI/Swagger specifications and developer experience
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (API Contract Within Architectural Framework)**
+- **API Contract Definition**: Specific endpoint paths, HTTP methods, and status codes
+- **Resource Modeling**: Mapping domain entities to RESTful resources or GraphQL types
+- **Request/Response Schemas**: Detailed data contracts, validation rules, and error formats
+- **API Versioning Strategy**: Version management, deprecation policies, and migration paths
+- **Developer Experience**: API documentation (OpenAPI/Swagger), code examples, and SDKs
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **System Architecture Decisions**: Microservices vs monolithic, overall communication patterns → Defers to **System Architect**
+- **Canonical Data Model**: Underlying data schemas and entity relationships → Defers to **Data Architect**
+- **UI/Frontend Integration**: How clients consume the API → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **FROM System Architect**: Receives architectural constraints (REST vs GraphQL, sync vs async) that define the design space
+- **FROM Data Architect**: Receives canonical data model and translates it into public API data contracts (as projection/view)
+- **TO Frontend Teams**: Provides complete API specifications, documentation, and integration guides
+
+## ⚙️ **Execution Protocol**
+
+### Phase 1: Session & Framework Detection
+```bash
+# Check active session and framework
+CHECK: .workflow/.active-* marker files
+IF active_session EXISTS:
+    session_id = get_active_session()
+    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+
+    CHECK: brainstorm_dir/topic-framework.md
+    IF EXISTS:
+        framework_mode = true
+        load_framework = true
+    ELSE:
+        IF topic_provided:
+            framework_mode = false  # Create analysis without framework
+        ELSE:
+            ERROR: "No framework found and no topic provided"
+```
+
+### Phase 2: Analysis Mode Detection
+```bash
+# Check existing analysis
+CHECK: brainstorm_dir/api-designer/analysis.md
+IF EXISTS:
+    SHOW existing analysis summary
+    ASK: "Analysis exists. Do you want to:"
+    OPTIONS:
+      1. "Update with new insights" → Update existing
+      2. "Replace completely" → Generate new
+      3. "Cancel" → Exit without changes
+ELSE:
+    CREATE new analysis
+```
+
+### Phase 3: Agent Task Generation
+**Framework-Based Analysis** (when topic-framework.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
+     **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
+
+     ## Analysis Requirements
+     1. **Load Topic Framework**: Read topic-framework.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
+     4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
+     5. **Structured Response**: Use framework structure for analysis organization
+
+     ## Framework Sections to Address
+     - Core Requirements (from API design perspective)
+     - Technical Considerations (detailed API architecture analysis)
+     - User Experience Factors (developer experience and API usability)
+     - Implementation Challenges (API design risks and solutions)
+     - Success Metrics (API performance metrics and adoption tracking)
+
+     ## Output Structure Required
+     ```markdown
+     # API Designer Analysis: [Topic]
+
+     **Framework Reference**: @../topic-framework.md
+     **Role Focus**: Backend API Design and Contract Definition
+
+     ## Core Requirements Analysis
+     [Address framework requirements from API design perspective]
+
+     ## Technical Considerations
+     [Detailed API architecture and endpoint design analysis]
+
+     ## Developer Experience Factors
+     [API usability, documentation, and integration ease]
+
+     ## Implementation Challenges
+     [API design risks and mitigation strategies]
+
+     ## Success Metrics
+     [API performance metrics, adoption rates, and developer satisfaction]
+
+     ## API Design-Specific Recommendations
+     [Detailed API design recommendations and best practices]
+     ```",
+     description="Generate API designer framework-based analysis")
+```
+
+### Phase 4: Update Mechanism
+**Analysis Update Process**:
+```bash
+# For existing analysis updates
+IF update_mode = "incremental":
+    Task(subagent_type="conceptual-planning-agent",
+         prompt="Update existing API designer analysis
+
+         ## Current Analysis Context
+         **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
+         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.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
+
+         ## Update Instructions
+         - Read existing analysis completely
+         - Identify areas for enhancement or new insights
+         - Add API design depth while preserving original structure
+         - Update recommendations with new API design patterns and approaches
+         - Maintain framework discussion point addressing",
+         description="Update API designer analysis incrementally")
+```
+
+## Document Structure
+
+### Output Files
+```
+.workflow/WFS-[topic]/.brainstorming/
+├── topic-framework.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)
+- **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
+
+## ⚡ **Two-Step Execution Flow**
+
+### ⚠️ Session Management - FIRST STEP
+Session detection and selection:
+```bash
+# Check for active sessions
+active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
+if [ multiple_sessions ]; then
+  prompt_user_to_select_session()
+else
+  use_existing_or_create_new()
+fi
+```
+
+### Step 1: Context Gathering Phase
+**API Designer Perspective Questioning**
+
+Before agent assignment, gather comprehensive API design context:
+
+#### 📋 Role-Specific Questions
+1. **API Type & Architecture**
+   - RESTful, GraphQL, or hybrid API approach?
+   - Synchronous vs asynchronous communication patterns?
+   - Real-time requirements (WebSocket, Server-Sent Events)?
+
+2. **Resource Modeling & Endpoints**
+   - What are the core domain resources/entities?
+   - Expected CRUD operations for each resource?
+   - Complex query requirements (filtering, sorting, pagination)?
+
+3. **Data Contracts & Validation**
+   - Request/response data format requirements (JSON, XML, Protocol Buffers)?
+   - Input validation and sanitization requirements?
+   - Data transformation and mapping needs?
+
+4. **API Management & Governance**
+   - API versioning strategy requirements?
+   - Authentication and authorization mechanisms?
+   - Rate limiting and throttling requirements?
+   - API documentation and developer portal needs?
+
+5. **Integration & Compatibility**
+   - Client platforms consuming the API (web, mobile, third-party)?
+   - Backward compatibility requirements?
+   - External API integrations needed?
+
+#### Context Validation
+- **Minimum Response**: Each answer must be ≥50 characters
+- **Re-prompting**: Insufficient detail triggers follow-up questions
+- **Context Storage**: Save responses to `.brainstorming/api-designer-context.md`
+
+### Step 2: Agent Assignment with Flow Control
+**Dedicated Agent Execution**
+
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute dedicated api-designer conceptual analysis for: {topic}
+
+ASSIGNED_ROLE: api-designer
+OUTPUT_LOCATION: .brainstorming/api-designer/
+USER_CONTEXT: {validated_responses_from_context_gathering}
+
+Flow Control Steps:
+[
+  {
+    \"step\": \"load_role_template\",
+    \"action\": \"Load api-designer planning template\",
+    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/api-designer.md))\",
+    \"output_to\": \"role_template\"
+  }
+]
+
+Conceptual Analysis Requirements:
+- Apply api-designer perspective to topic analysis
+- Focus on endpoint design, data contracts, and API governance
+- Use loaded role template framework for analysis structure
+- Generate role-specific deliverables in designated output location
+- Address all user context from questioning phase
+
+Deliverables:
+- analysis.md: Main API design analysis
+- api-specification.md: Detailed endpoint specifications
+- data-contracts.md: Request/response schemas and validation rules
+- api-documentation.md: API documentation strategy and templates
+
+Embody api-designer role expertise for comprehensive conceptual planning."
+```
+
+### Progress Tracking
+TodoWrite tracking for two-step process:
+```json
+[
+  {"content": "Gather API designer context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
+  {"content": "Validate context responses and save to api-designer-context.md", "status": "pending", "activeForm": "Validating context"},
+  {"content": "Load api-designer planning template via flow control", "status": "pending", "activeForm": "Loading template"},
+  {"content": "Execute dedicated conceptual-planning-agent for api-designer role", "status": "pending", "activeForm": "Executing agent"}
+]
+```
+
+## 📊 **Output Specification**
+
+### Output Location
+```
+.workflow/WFS-{topic-slug}/.brainstorming/api-designer/
+├── analysis.md                 # Primary API design analysis
+├── api-specification.md        # Detailed endpoint specifications (OpenAPI/Swagger)
+├── data-contracts.md           # Request/response schemas and validation rules
+├── versioning-strategy.md      # API versioning and backward compatibility plan
+└── developer-guide.md          # API usage documentation and integration examples
+```
+
+### Document Templates
+
+#### analysis.md Structure
+```markdown
+# API Design Analysis: {Topic}
+*Generated: {timestamp}*
+
+## Executive Summary
+[Key API design findings and recommendations overview]
+
+## API Architecture Overview
+### API Type Selection (REST/GraphQL/Hybrid)
+### Communication Patterns
+### Authentication & Authorization Strategy
+
+## Resource Modeling
+### Core Domain Resources
+### Resource Relationships
+### URL Structure and Naming Conventions
+
+## Endpoint Design
+### Resource Endpoints
+- GET /api/v1/resources
+- POST /api/v1/resources
+- GET /api/v1/resources/{id}
+- PUT /api/v1/resources/{id}
+- DELETE /api/v1/resources/{id}
+
+### Query Parameters
+- Filtering: ?filter[field]=value
+- Sorting: ?sort=field,-field2
+- Pagination: ?page=1&limit=20
+
+### HTTP Methods and Status Codes
+- Success responses (2xx)
+- Client errors (4xx)
+- Server errors (5xx)
+
+## Data Contracts
+### Request Schemas
+[JSON Schema or OpenAPI definitions]
+
+### Response Schemas
+[JSON Schema or OpenAPI definitions]
+
+### Validation Rules
+- Required fields
+- Data types and formats
+- Business logic constraints
+
+## API Versioning Strategy
+### Versioning Approach (URL/Header/Accept)
+### Version Lifecycle Management
+### Deprecation Policy
+### Migration Paths
+
+## Security & Governance
+### Authentication Mechanisms
+- OAuth 2.0 / JWT / API Keys
+### Authorization Patterns
+- RBAC / ABAC / Resource-based
+### Rate Limiting & Throttling
+### CORS and Security Headers
+
+## Error Handling
+### Standard Error Response Format
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message",
+    "details": [],
+    "trace_id": "uuid"
+  }
+}
+```
+
+### Error Code Taxonomy
+### Validation Error Responses
+
+## API Documentation
+### OpenAPI/Swagger Specification
+### Developer Portal Requirements
+### Code Examples and SDKs
+### Changelog and Migration Guides
+
+## Performance Optimization
+### Response Caching Strategies
+### Compression (gzip, brotli)
+### Field Selection (sparse fieldsets)
+### Bulk Operations and Batch Endpoints
+
+## Monitoring & Observability
+### API Metrics
+- Request count, latency, error rates
+- Endpoint usage analytics
+### Logging Strategy
+### Distributed Tracing
+
+## Developer Experience
+### API Usability Assessment
+### Integration Complexity
+### SDK and Client Library Needs
+### Sandbox and Testing Environments
+```
+
+#### api-specification.md Structure
+```markdown
+# API Specification: {Topic}
+*OpenAPI 3.0 Specification*
+
+## API Information
+- **Title**: {API Name}
+- **Version**: 1.0.0
+- **Base URL**: https://api.example.com/v1
+- **Contact**: api-team@example.com
+
+## Endpoints
+
+### Users API
+
+#### GET /users
+**Description**: Retrieve a list of users
+
+**Parameters**:
+- `page` (query, integer): Page number (default: 1)
+- `limit` (query, integer): Items per page (default: 20, max: 100)
+- `sort` (query, string): Sort field (e.g., "created_at", "-updated_at")
+- `filter[status]` (query, string): Filter by user status
+
+**Response 200**:
+```json
+{
+  "data": [
+    {
+      "id": "uuid",
+      "username": "string",
+      "email": "string",
+      "created_at": "2025-10-15T00:00:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100
+  },
+  "links": {
+    "self": "/users?page=1",
+    "next": "/users?page=2",
+    "prev": null
+  }
+}
+```
+
+#### POST /users
+**Description**: Create a new user
+
+**Request Body**:
+```json
+{
+  "username": "string (required, 3-50 chars)",
+  "email": "string (required, valid email)",
+  "password": "string (required, min 8 chars)",
+  "profile": {
+    "first_name": "string (optional)",
+    "last_name": "string (optional)"
+  }
+}
+```
+
+**Response 201**:
+```json
+{
+  "data": {
+    "id": "uuid",
+    "username": "string",
+    "email": "string",
+    "created_at": "2025-10-15T00:00:00Z"
+  }
+}
+```
+
+**Response 400** (Validation Error):
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  }
+}
+```
+
+[Continue for all endpoints...]
+
+## Authentication
+
+### OAuth 2.0 Flow
+1. Client requests authorization
+2. User grants permission
+3. Client receives access token
+4. Client uses token in requests
+
+**Header Format**:
+```
+Authorization: Bearer {access_token}
+```
+
+## Rate Limiting
+
+**Headers**:
+- `X-RateLimit-Limit`: 1000
+- `X-RateLimit-Remaining`: 999
+- `X-RateLimit-Reset`: 1634270400
+
+**Response 429** (Too Many Requests):
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "API rate limit exceeded",
+    "retry_after": 3600
+  }
+}
+```
+```
+
+## 🔄 **Session Integration**
+
+### Status Synchronization
+Upon completion, update `workflow-session.json`:
+```json
+{
+  "phases": {
+    "BRAINSTORM": {
+      "api_designer": {
+        "status": "completed",
+        "completed_at": "timestamp",
+        "output_directory": ".workflow/WFS-{topic}/.brainstorming/api-designer/",
+        "key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
+      }
+    }
+  }
+}
+```
+
+### Cross-Role Collaboration
+API designer perspective provides:
+- **API Contract Specifications** → Frontend Developer
+- **Data Schema Requirements** → Data Architect
+- **Security Requirements** → Security Expert
+- **Integration Endpoints** → System Architect
+- **Performance Constraints** → DevOps Engineer
+
+## ✅ **Quality Assurance**
+
+### Required Analysis Elements
+- [ ] Complete endpoint inventory with HTTP methods and paths
+- [ ] Detailed request/response schemas with validation rules
+- [ ] Clear versioning strategy and backward compatibility plan
+- [ ] Comprehensive error handling and status code usage
+- [ ] API documentation strategy (OpenAPI/Swagger)
+
+### API Design Principles
+- [ ] **Consistency**: Uniform naming conventions and patterns across all endpoints
+- [ ] **Simplicity**: Intuitive resource modeling and URL structures
+- [ ] **Flexibility**: Support for filtering, sorting, pagination, and field selection
+- [ ] **Security**: Proper authentication, authorization, and input validation
+- [ ] **Performance**: Caching strategies, compression, and efficient data structures
+
+### Developer Experience Validation
+- [ ] API is self-documenting with clear endpoint descriptions
+- [ ] Error messages are actionable and helpful for debugging
+- [ ] Response formats are consistent and predictable
+- [ ] Code examples and integration guides are provided
+- [ ] Sandbox environment available for testing
+
+### Technical Completeness
+- [ ] **Resource Modeling**: All domain entities mapped to API resources
+- [ ] **CRUD Coverage**: Complete create, read, update, delete operations
+- [ ] **Query Capabilities**: Advanced filtering, sorting, and search functionality
+- [ ] **Versioning**: Clear version management and migration paths
+- [ ] **Monitoring**: API metrics, logging, and tracing strategies defined
+
+### Integration Readiness
+- [ ] **Client Compatibility**: API works with all target client platforms
+- [ ] **External Integration**: Third-party API dependencies identified
+- [ ] **Backward Compatibility**: Changes don't break existing clients
+- [ ] **Migration Path**: Clear upgrade paths for API consumers
+- [ ] **SDK Support**: Client libraries and code generation considered

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

@@ -12,9 +12,16 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
 ```
 
+**Recommended Structured Format**:
+```bash
+/workflow:brainstorm:artifacts "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--roles "..."]
+```
+
 ## 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.
 
+**⚠️ User Intent Preservation**: Topic description is stored in session metadata and serves as authoritative reference throughout workflow lifecycle.
+
 ## Role-Based Framework Generation
 
 **Dynamic Generation**: Framework content adapts based on selected roles

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

@@ -1,7 +1,7 @@
 ---
 name: auto-parallel
 description: Parallel brainstorming automation with dynamic role selection and concurrent execution
-argument-hint: "topic or challenge description"
+argument-hint: "topic or challenge description" [--count N]
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
@@ -9,21 +9,34 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 ## Usage
 ```bash
-/workflow:brainstorm:auto-parallel "<topic>"
+/workflow:brainstorm:auto-parallel "<topic>" [--count N]
 ```
 
+**Recommended Structured Format**:
+```bash
+/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
+```
+
+**Parameters**:
+- `topic` (required): Topic or challenge description (structured format recommended)
+- `--count N` (optional): Number of roles to auto-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.
+
 ## 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 2-3 complementary roles
+- **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)
 
 **Template Loading**: `bash($(cat "~/.claude/workflows/cli-templates/planning-roles/<role-name>.md"))`
 **Template Source**: `.claude/workflows/cli-templates/planning-roles/`
-**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+**Available Roles**: api-designer, data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
 **Example**:
 ```bash
@@ -37,9 +50,10 @@ bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
 The command follows a structured three-phase approach with dedicated document types:
 
 **Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
-- **Role selection**: Auto-select 2-3 roles based on topic keywords (see Role Selection Logic)
-- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"` using SlashCommand tool
+- **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
 
 **Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
 - **Parallel execution**: Multiple roles execute simultaneously for faster completion
@@ -50,6 +64,8 @@ The command follows a structured three-phase approach with dedicated document ty
 
 **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
 
 ## Implementation Standards
 
@@ -57,10 +73,10 @@ The command follows a structured three-phase approach with dedicated document ty
 Auto command coordinates independent specialized commands:
 
 **Command Sequence**:
-1. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
-2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"`
+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`
+4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis` (loads user intent from session as primary reference)
 
 **SlashCommand Integration**:
 1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
@@ -70,10 +86,33 @@ Auto command coordinates independent specialized commands:
 
 **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**: 2-3 most relevant roles based on topic analysis
+- **Auto-select**: N most relevant roles based on topic analysis (N from --count parameter, default: 3)
+
+### Parameter Parsing
+
+**Count Parameter Handling**:
+```bash
+# Parse --count parameter 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
+ELSE:
+    count_value = 3  # Default to 3 roles
+END IF
+```
+
+**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)
 
 ### Simplified Processing Standards
 
@@ -85,7 +124,7 @@ Auto command coordinates independent specialized commands:
 5. **TodoWrite control** - Progress tracking throughout all phases
 
 **Implementation Rules**:
-- **Maximum 3 roles**: Auto-selected based on simple keyword mapping
+- **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
@@ -143,16 +182,17 @@ Task(subagent_type="conceptual-planning-agent",
         - Output: role_template
 
      3. **load_session_metadata**
-        - Action: Load session metadata and topic description
+        - Action: Load session metadata and original user intent
         - Command: bash(cat .workflow/WFS-{topic}/workflow-session.json 2>/dev/null || echo '{}')
-        - Output: session_metadata
+        - 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
-     **Analysis Type**: Address framework discussion points from role perspective
+     **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
+     **Structured Approach**: Create analysis.md addressing all topic framework points relevant to user's goals
 
      ### Session Context
      **Workflow Directory**: .workflow/WFS-{topic}/.brainstorming/
@@ -165,31 +205,37 @@ Task(subagent_type="conceptual-planning-agent",
      **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)
-     2. **Address Topic Framework**: Respond to all discussion points in topic-framework.md from role perspective
-     3. Apply role template guidelines within topic framework structure
-     4. Generate structured role analysis addressing framework points
-     5. Create single comprehensive deliverable in OUTPUT_LOCATION:
-        - analysis.md (structured analysis addressing all topic framework points with role-specific insights)
-     6. Include framework reference: @../topic-framework.md in analysis.md
-     7. Update workflow-session.json with completion status",
+     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 multiple roles in parallel using single message with multiple Task calls
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: system-architect perspective for {topic}...",
-     description="Execute system-architect brainstorming analysis")
+# 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: ui-designer perspective for {topic}...",
-     description="Execute ui-designer brainstorming analysis")
+     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: security-expert perspective for {topic}...",
-     description="Execute security-expert brainstorming analysis")
+     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)
@@ -211,9 +257,9 @@ TodoWrite({
       activeForm: "Initializing brainstorming session"
     },
     {
-      content: "Select roles based on topic keyword analysis",
+      content: "Parse --count parameter and select N roles based on topic keyword analysis",
       status: "pending",
-      activeForm: "Selecting roles for brainstorming analysis"
+      activeForm: "Parsing parameters and selecting roles for brainstorming"
     },
     {
       content: "Execute artifacts command with selected roles for role-specific framework",
@@ -230,6 +276,12 @@ TodoWrite({
       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",
@@ -255,24 +307,25 @@ TodoWrite({
   ]
 });
 
-// Phase 3: Parallel agent execution tracking
+// Phase 3: Parallel agent execution tracking (N roles, N from --count parameter)
 TodoWrite({
   todos: [
     // ... previous completed tasks
     {
-      content: "Execute system-architect analysis [conceptual-planning-agent] [FLOW_CONTROL]",
+      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
       status: "in_progress",  // Executing in parallel
-      activeForm: "Executing system-architect brainstorming analysis"
+      activeForm: "Executing [role-1] brainstorming analysis"
     },
     {
-      content: "Execute ui-designer analysis [conceptual-planning-agent] [FLOW_CONTROL]",
+      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
       status: "in_progress",  // Executing in parallel
-      activeForm: "Executing ui-designer brainstorming analysis"
+      activeForm: "Executing [role-2] brainstorming analysis"
     },
+    // ... repeat for remaining N-2 roles
     {
-      content: "Execute security-expert analysis [conceptual-planning-agent] [FLOW_CONTROL]",
+      content: "Execute [role-N] analysis [conceptual-planning-agent] [FLOW_CONTROL]",
       status: "in_progress",  // Executing in parallel
-      activeForm: "Executing security-expert brainstorming analysis"
+      activeForm: "Executing [role-N] brainstorming analysis"
     }
   ]
 });

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

@@ -1,253 +0,0 @@
----
-name: auto-squeeze
-description: Orchestrate 3-phase brainstorming workflow by executing commands sequentially
-argument-hint: "topic or challenge description for coordinated brainstorming"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
----
-
-# Workflow Brainstorm Auto-Squeeze Command
-
-## Coordinator Role
-
-**This command is a pure orchestrator**: Execute brainstorming commands in sequence (artifacts → roles → synthesis), auto-select relevant roles, and ensure complete brainstorming workflow execution.
-
-**Execution Flow**:
-1. Initialize TodoWrite → Execute Phase 1 (artifacts) → Validate framework → Update TodoWrite
-2. Select 2-3 relevant roles → Display selection → Execute Phase 2 (role analyses) → Update TodoWrite
-3. Execute Phase 3 (synthesis) → Validate outputs → Return summary
-
-## Core Rules
-
-1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
-2. **Auto-Select Roles**: Analyze topic keywords to select 2-3 most relevant roles (max 3)
-3. **Display Selection**: Show selected roles to user before execution
-4. **Sequential Execution**: Execute role commands one by one, not in parallel
-5. **Complete All Phases**: Do not return to user until synthesis completes
-6. **Track Progress**: Update TodoWrite after every command completion
-
-## 3-Phase Execution
-
-### Phase 1: Framework Generation
-
-**Step 1.1: Role Selection**
-Auto-select 2-3 roles based on topic keywords (see Role Selection Logic below)
-
-**Step 1.2: Generate Role-Specific Framework**
-**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"[topic]\" --roles \"[role1,role2,role3]\"")`
-
-**Input**: Selected roles from step 1.1
-
-**Parse Output**:
-- Verify topic-framework.md created with role-specific sections
-
-**Validation**:
-- File `.workflow/[session]/.brainstorming/topic-framework.md` exists
-- Contains sections for each selected role
-- Includes cross-role integration points
-
-**TodoWrite**: Mark phase 1 completed, mark "Display selected roles" as in_progress
-
----
-
-### Phase 2: Role Analysis Execution
-
-**Step 2.1: Role Selection**
-Use keyword analysis to auto-select 2-3 roles:
-
-**Role Selection Logic**:
-- **Technical/Architecture keywords**: `architecture|system|performance|database|api|backend|scalability`
-  → system-architect, data-architect, subject-matter-expert
-- **UI/UX keywords**: `user|ui|ux|interface|design|frontend|experience`
-  → ui-designer, ux-expert
-- **Product/Business keywords**: `product|feature|business|workflow|process|customer`
-  → product-manager, product-owner
-- **Agile/Delivery keywords**: `agile|sprint|scrum|team|collaboration|delivery`
-  → scrum-master, product-owner
-- **Domain Expertise keywords**: `domain|standard|compliance|expertise|regulation`
-  → subject-matter-expert
-- **Default**: product-manager (if no clear match)
-
-**Selection Rules**:
-- Maximum 3 roles
-- Select most relevant role first based on strongest keyword match
-- Include complementary perspectives (e.g., if system-architect selected, also consider security-expert)
-
-**Step 2.2: Display Selected Roles**
-Show selection to user before execution:
-```
-Selected roles for analysis:
-- ui-designer (UI/UX perspective)
-- system-architect (Technical architecture)
-- security-expert (Security considerations)
-```
-
-**Step 2.3: Execute Role Commands Sequentially**
-Execute each selected role command one by one:
-
-**Commands**:
-- `SlashCommand(command="/workflow:brainstorm:ui-designer")`
-- `SlashCommand(command="/workflow:brainstorm:ux-expert")`
-- `SlashCommand(command="/workflow:brainstorm:system-architect")`
-- `SlashCommand(command="/workflow:brainstorm:data-architect")`
-- `SlashCommand(command="/workflow:brainstorm:product-manager")`
-- `SlashCommand(command="/workflow:brainstorm:product-owner")`
-- `SlashCommand(command="/workflow:brainstorm:scrum-master")`
-- `SlashCommand(command="/workflow:brainstorm:subject-matter-expert")`
-- `SlashCommand(command="/workflow:brainstorm:test-strategist")`
-
-**Validation** (after each role):
-- File `.workflow/[session]/.brainstorming/[role]/analysis.md` exists
-- Contains role-specific analysis
-
-**TodoWrite**: Mark each role task completed after execution, start next role as in_progress
-
----
-
-### Phase 3: Synthesis Generation
-**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis")`
-
-**Validation**:
-- File `.workflow/[session]/.brainstorming/synthesis-report.md` exists
-- Contains cross-references to role analyses using @ notation
-
-**TodoWrite**: Mark phase 3 completed
-
-**Return to User**:
-```
-Brainstorming complete for topic: [topic]
-Framework: .workflow/[session]/.brainstorming/topic-framework.md
-Roles analyzed: [role1], [role2], [role3]
-Synthesis: .workflow/[session]/.brainstorming/synthesis-report.md
-```
-
-## TodoWrite Pattern
-
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Generate topic framework", "status": "in_progress", "activeForm": "Generating topic framework"},
-  {"content": "Display selected roles", "status": "pending", "activeForm": "Displaying selected roles"},
-  {"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
-  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
-]})
-
-// After Phase 1
-TodoWrite({todos: [
-  {"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
-  {"content": "Display selected roles", "status": "in_progress", "activeForm": "Displaying selected roles"},
-  {"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
-  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
-]})
-
-// After displaying roles
-TodoWrite({todos: [
-  {"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
-  {"content": "Display selected roles", "status": "completed", "activeForm": "Displaying selected roles"},
-  {"content": "Execute ui-designer analysis", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
-  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
-]})
-
-// Continue pattern for each role and synthesis...
-```
-
-## Data Flow
-
-```
-User Input (topic)
-    ↓
-Role Selection (analyze topic keywords)
-    ↓ Output: 2-3 selected roles (e.g., ui-designer, system-architect, security-expert)
-    ↓
-Phase 1: artifacts "topic" --roles "role1,role2,role3"
-    ↓ Input: topic + selected roles
-    ↓ Output: role-specific topic-framework.md
-    ↓
-Display: Show selected roles to user
-    ↓
-Phase 2: Execute each role command sequentially
-    ↓ Role 1 → reads role-specific section → analysis.md
-    ↓ Role 2 → reads role-specific section → analysis.md
-    ↓ Role 3 → reads role-specific section → analysis.md
-    ↓
-Phase 3: synthesis
-    ↓ Input: role-specific framework + all role analyses
-    ↓ Output: synthesis-report.md with role-targeted insights
-    ↓
-Return summary to user
-```
-
-**Session Context**: All commands use active brainstorming session, sharing:
-- Role-specific topic framework
-- Role-targeted analyses
-- Cross-role integration points
-- Synthesis with role-specific insights
-
-**Key Improvement**: Framework is generated with roles parameter, ensuring all discussion points are relevant to selected roles
-
-## Role Selection Examples
-
-### Example 1: UI-Focused Topic
-**Topic**: "Redesign user authentication interface"
-**Keywords detected**: user, interface, design
-**Selected roles**:
-- ui-designer (primary: UI/UX match)
-- ux-expert (secondary: user experience)
-- subject-matter-expert (complementary: auth standards)
-
-### Example 2: Architecture Topic
-**Topic**: "Design scalable microservices architecture"
-**Keywords detected**: architecture, scalable, system
-**Selected roles**:
-- system-architect (primary: architecture match)
-- data-architect (secondary: scalability/data)
-- subject-matter-expert (complementary: domain expertise)
-
-### Example 3: Agile Delivery Topic
-**Topic**: "Optimize team sprint planning and delivery process"
-**Keywords detected**: sprint, team, delivery, process
-**Selected roles**:
-- scrum-master (primary: agile process match)
-- product-owner (secondary: backlog/delivery focus)
-- product-manager (complementary: product strategy)
-
-## Error Handling
-
-- **Framework Generation Failure**: Stop workflow, report error, do not proceed to role selection
-- **Role Analysis Failure**: Log failure, continue with remaining roles, note in final summary
-- **Synthesis Failure**: Retry once, if still fails report partial completion with available analyses
-- **Session Error**: Report session issue, prompt user to check session status
-
-## Output Structure
-
-```
-.workflow/[session]/.brainstorming/
-├── topic-framework.md          # Phase 1 output
-├── [role1]/
-│   └── analysis.md            # Phase 2 output (role 1)
-├── [role2]/
-│   └── analysis.md            # Phase 2 output (role 2)
-├── [role3]/
-│   └── analysis.md            # Phase 2 output (role 3)
-└── synthesis-report.md        # Phase 3 output
-```
-
-## Coordinator Checklist
-
-✅ Initialize TodoWrite with framework + display + N roles + synthesis tasks
-✅ Execute Phase 1 (artifacts) immediately
-✅ Validate topic-framework.md exists
-✅ Analyze topic keywords for role selection
-✅ Auto-select 2-3 most relevant roles (max 3)
-✅ Display selected roles to user with rationale
-✅ Execute each role command sequentially
-✅ Validate each role's analysis.md after execution
-✅ Update TodoWrite after each role completion
-✅ Execute Phase 3 (synthesis) after all roles complete
-✅ Validate synthesis-report.md exists
-✅ Return summary with all generated files

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

@@ -22,6 +22,26 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Data Quality Management**: Data accuracy, completeness, and consistency
 - **Analytics and Insights**: Data analysis and business intelligence solutions
 
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Canonical Data Model - Source of Truth)**
+- **Canonical Data Model**: The authoritative, system-wide data schema representing domain entities and relationships
+- **Entity-Relationship Design**: Defining entities, attributes, relationships, and constraints
+- **Data Normalization & Optimization**: Ensuring data integrity, reducing redundancy, and optimizing storage
+- **Database Schema Design**: Physical database structures, indexes, partitioning strategies
+- **Data Pipeline Architecture**: ETL/ELT processes, data warehousing, and analytics pipelines
+- **Data Governance**: Data quality standards, retention policies, and compliance requirements
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **API Data Contracts**: Public-facing request/response schemas exposed by APIs → Defers to **API Designer**
+- **System Integration Patterns**: How services communicate at the macro level → Defers to **System Architect**
+- **UI Data Presentation**: How data is displayed to users → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **TO API Designer**: Provides canonical data model that API Designer translates into public API data contracts (as projection/view)
+- **TO System Architect**: Provides data flow requirements and storage constraints to inform system design
+- **FROM System Architect**: Receives system-level integration requirements and scalability constraints
+
 ## ⚙️ **Execution Protocol**
 
 ### Phase 1: Session & Framework Detection

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

@@ -1,8 +1,8 @@
 ---
 name: synthesis
-description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
-argument-hint: "no arguments required - synthesizes existing framework and role analyses"
-allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
+description: Generate synthesis-specification.md from topic-framework and role analyses with @ references using conceptual-planning-agent
+argument-hint: "[optional: --session session-id]"
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🧩 **Synthesis Document Generator**
@@ -29,32 +29,57 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
 
 ## ⚙️ **Execution Protocol**
 
-### ⚠️ Direct Execution by Main Claude
-**Execution Model**: Main Claude directly executes this command without delegating to sub-agents.
+### ⚠️ Agent Execution with Flow Control
+**Execution Model**: Uses conceptual-planning-agent for synthesis generation with structured file loading.
 
 **Rationale**:
-- **Full Context Access**: Avoids context transmission loss that occurs with Task tool delegation
-- **Complex Cognitive Analysis**: Leverages main Claude's complete reasoning capabilities for cross-role synthesis
-- **Tool Usage**: Combines Read/Write/Glob tools with main Claude's analytical intelligence
+- **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
 
-**DO NOT use Task tool** - Main Claude performs intelligent analysis directly while reading/writing files, ensuring no information loss from context passing.
+**Agent Responsibility**: All file reading and synthesis generation performed by conceptual-planning-agent with FLOW_CONTROL instructions.
+
+### 📋 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"}
+]
+```
 
 ### Phase 1: Document Discovery & Validation
 ```bash
 # Detect active brainstorming session
-CHECK: .workflow/.active-* marker files
-IF active_session EXISTS:
-    session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+IF --session parameter provided:
+    session_id = provided session
 ELSE:
-    ERROR: "No active brainstorming session found"
-    EXIT
+    CHECK: .workflow/.active-* marker files
+    IF active_session EXISTS:
+        session_id = get_active_session()
+    ELSE:
+        ERROR: "No active brainstorming session found"
+        EXIT
+
+brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
 # Validate required documents
 CHECK: brainstorm_dir/topic-framework.md
 IF NOT EXISTS:
     ERROR: "topic-framework.md not found. Run /workflow:brainstorm:artifacts first"
     EXIT
+
+# 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 Analysis Discovery
@@ -78,6 +103,7 @@ FIND_ANALYSES: [
 # - test-strategist
 
 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],
@@ -86,6 +112,7 @@ LOAD_DOCUMENTS: {
 
 # 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
 ```
 
 ### Phase 3: Update Mechanism Check
@@ -102,79 +129,123 @@ ELSE:
     CREATE new synthesis
 ```
 
-### Phase 4: Synthesis Generation Process
-Initialize synthesis task tracking:
-```json
-[
-  {"content": "Validate topic-framework.md and role analyses availability", "status": "in_progress", "activeForm": "Validating source documents"},
-  {"content": "Load topic framework discussion points structure", "status": "pending", "activeForm": "Loading framework structure"},
-  {"content": "Cross-analyze role responses to each framework point", "status": "pending", "activeForm": "Cross-analyzing framework responses"},
-  {"content": "Generate synthesis-specification.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"},
-  {"content": "Update session metadata with synthesis completion", "status": "pending", "activeForm": "Updating session metadata"}
-]
-```
+### Phase 4: Agent Execution with Flow Control
+**Synthesis Generation using conceptual-planning-agent**
 
-### Phase 5: Cross-Role Analysis Execution
+Delegate synthesis generation to conceptual-planning-agent with structured file loading:
 
-**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2.
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
 
-#### 5.1 Data Collection and Preprocessing
-```pseudo
-# Iterate over dynamically discovered role analyses
-FOR each discovered_role IN participating_roles:
-    role_directory = brainstorm_dir + "/" + discovered_role
+Execute comprehensive synthesis generation from topic framework and role analyses
 
-    # Load role analysis (required)
-    role_analysis = Read(role_directory + "/analysis.md")
+## 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
 
-    # Load optional artifacts if present
-    IF EXISTS(role_directory + "/recommendations.md"):
-        role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md")
-    END IF
+## ⚠️ 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.
 
-    # Extract insights from analysis
-    role_insights[discovered_role] = extract_key_insights(role_analysis)
-    role_recommendations[discovered_role] = extract_recommendations(role_analysis)
-    role_concerns[discovered_role] = extract_concerns_risks(role_analysis)
-    role_diagrams[discovered_role] = identify_diagrams_and_visuals(role_analysis)
-END FOR
+## 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
 
-# Log participating roles for metadata
-participating_role_count = COUNT(participating_roles)
-participating_role_names = participating_roles
-```
+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
 
-#### 5.2 Cross-Role Insight Analysis
-```pseudo
-# Consensus identification (across all participating roles)
-consensus_areas = identify_common_themes(role_insights)
-agreement_matrix = create_agreement_matrix(role_recommendations)
+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
 
-# Disagreement analysis (track which specific roles disagree)
-disagreement_areas = identify_conflicting_views(role_insights)
-tension_points = analyze_role_conflicts(role_recommendations)
-FOR each conflict IN disagreement_areas:
-    conflict.dissenting_roles = identify_dissenting_roles(conflict)
-END FOR
+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
 
-# Innovation opportunity extraction
-innovation_opportunities = extract_breakthrough_ideas(role_insights)
-synergy_opportunities = identify_cross_role_synergies(role_insights)
-```
+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]
 
-#### 5.3 Priority and Decision Matrix Generation
-```pseudo
-# Create comprehensive evaluation matrix
-FOR each recommendation:
-    impact_score = calculate_business_impact(recommendation, role_insights)
-    feasibility_score = calculate_technical_feasibility(recommendation, role_insights)
-    effort_score = calculate_implementation_effort(recommendation, role_insights)
-    risk_score = calculate_associated_risks(recommendation, role_insights)
-    
-    priority_score = weighted_score(impact_score, feasibility_score, effort_score, risk_score)
-END FOR
+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
 
-SORT recommendations BY priority_score DESC
+## 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**
@@ -189,153 +260,22 @@ The synthesis process creates **one consolidated document** that integrates all
 └── synthesis-specification.md  # ★ OUTPUT: Complete integrated specification
 ```
 
-#### synthesis-specification.md Structure (Complete Specification)
+#### synthesis-specification.md Structure
 
 **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).
 
-```markdown
-# [Topic] - Integrated Implementation Specification
+**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
 
-**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
-**Source Integration**: All brainstorming role perspectives consolidated
-**Document Type**: Requirements & Design Specification (WHAT to build)
-
-## Executive Summary
-Strategic overview with key insights, breakthrough opportunities, and implementation priorities.
-
-## Key Designs & Decisions
-### Core Architecture Diagram
-```mermaid
-graph TD
-    A[Component A] --> B[Component B]
-    B --> C[Component C]
-```
-*Reference: @system-architect/analysis.md#architecture-diagram*
-
-### User Journey Map
-![User Journey](./assets/user-journey.png)
-*Reference: @ux-expert/analysis.md#user-journey*
-
-### Data Model Overview
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    ORDER ||--|{ LINE-ITEM : contains
-```
-*Reference: @data-architect/analysis.md#data-model*
-
-### Architecture Decision Records (ADRs)
-**ADR-01: [Decision Title]**
-- **Context**: Background and problem statement
-- **Decision**: Chosen approach
-- **Rationale**: Why this approach was selected
-- **Reference**: @system-architect/analysis.md#adr-01
-
-## Controversial Points & Alternatives
-| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
-|-------|------------------|-------------------------|--------------------| -----------------|
-| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
-| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
-
-*This section preserves decision context and rejected alternatives for future reference.*
-
-## Requirements & Acceptance Criteria
-### Functional Requirements
-| ID | Description | Rationale Summary | Source | Priority | Acceptance | Dependencies |
-|----|-------------|-------------------|--------|----------|------------|--------------|
-| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password | None |
-| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON | FR-01 |
-
-### Non-Functional Requirements
-| ID | Description | Rationale Summary | Target | Validation | Source |
-|----|-------------|-------------------|--------|------------|--------|
-| NFR-01 | Response time | UX research shows <200ms critical | <200ms | Load testing | @ux-expert/analysis.md |
-| NFR-02 | Data encryption | Compliance requirement | AES-256 | Security audit | @security-expert/analysis.md |
-
-### Business Requirements
-| ID | Description | Rationale Summary | Value | Success Metric | Source |
-|----|-------------|-------------------|-------|----------------|--------|
-| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
-| BR-02 | Revenue growth | Business case justification | High | 25% MRR increase | @product-owner/analysis.md |
-
-## Design Specifications
-### UI/UX Guidelines
-**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md
-- Component specifications and interaction patterns
-- Visual design system and accessibility requirements
-- User flow and interface specifications
-
-### Architecture Design
-**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md
-- System architecture and component interactions
-- Data flow and storage strategy
-- Technology stack decisions
-
-### Domain Expertise & Standards
-**Consolidated from**: @subject-matter-expert/analysis.md
-- Industry standards and best practices
-- Compliance requirements and regulations
-- Technical quality and domain-specific patterns
-
-## Process & Collaboration Concerns
-**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
-
-### Team Capability Assessment
-| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
-|----------------|---------------|--------------|---------------------|-----------|
-| Kubernetes | Intermediate | Need advanced knowledge | Training + external consultant | @scrum-master/analysis.md |
-| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
-
-### Process Risks
-| Risk | Impact | Probability | Mitigation | Owner |
-|------|--------|-------------|------------|-------|
-| Cross-team API dependency | High | Medium | Early API contract definition | @scrum-master/analysis.md |
-| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | @ux-expert/analysis.md |
-
-### Collaboration Patterns
-- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
-- **Architecture Reviews**: Weekly arch review for system-level decisions
-- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
-- **Reference**: @scrum-master/analysis.md#collaboration
-
-### Timeline Constraints
-- **Blocking Dependencies**: Project-X API must complete before Phase 2
-- **Resource Constraints**: Only 2 backend developers available in Q1
-- **External Dependencies**: Third-party OAuth provider integration timeline
-- **Reference**: @scrum-master/analysis.md#constraints
-
-## Implementation Roadmap (High-Level)
-### Development Phases
-**Phase 1** (0-3 months): Foundation and core features
-**Phase 2** (3-6 months): Advanced features and integrations
-**Phase 3** (6+ months): Optimization and innovation
-
-### Technical Guidelines
-- Development standards and code organization
-- Testing strategy and quality assurance
-- Deployment and monitoring approach
-
-### Feature Grouping (Epic-Level)
-- High-level feature grouping and prioritization
-- Epic-level dependencies and sequencing
-- Strategic milestones and release planning
-
-**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
-
-## Risk Assessment & Mitigation
-### Critical Risks Identified
-1. **Risk**: Description | **Mitigation**: Strategy
-2. **Risk**: Description | **Mitigation**: Strategy
-
-### Success Factors
-- Key factors for implementation success
-- Continuous monitoring requirements
-- Quality gates and validation checkpoints
-
----
-*Complete implementation specification consolidating all role perspectives into actionable guidance*
-```
+**Agent Usage**: The conceptual-planning-agent loads this template to understand expected structure and quality standards.
 
 ## 🔄 **Session Integration**
 
@@ -400,98 +340,39 @@ Upon completion, update `workflow-session.json`:
 
 ## ✅ **Quality Assurance**
 
-### Required Synthesis Elements
-- [ ] Integration of all available role analyses with comprehensive coverage
-- [ ] **Key Designs & Decisions**: Architecture diagrams, user journey maps, ADRs documented
-- [ ] **Controversial Points**: Disagreement points, alternatives, and decision rationale captured
-- [ ] **Process Concerns**: Team capability gaps, process risks, collaboration patterns identified
-- [ ] Quantified priority recommendation matrix with evaluation criteria
-- [ ] Actionable implementation plan with phased approach
-- [ ] Comprehensive risk assessment with mitigation strategies
+Verify synthesis output meets these standards (detailed criteria in `synthesis-role.md` template):
 
-### Synthesis Analysis Quality Standards
-- [ ] **Completeness**: Integrates all available role analyses without gaps
-- [ ] **Visual Clarity**: Key diagrams (architecture, data model, user journey) included via Mermaid or images
-- [ ] **Decision Transparency**: Documents not just decisions, but alternatives and why they were rejected
-- [ ] **Insight Generation**: Identifies cross-role patterns and deep insights
-- [ ] **Actionability**: Provides specific, executable recommendations with rationale
-- [ ] **Balance**: Considers all role perspectives, including process-oriented roles (Scrum Master)
-- [ ] **Forward-Looking**: Includes long-term strategic and innovation considerations
+### 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
 
-### Output Validation Criteria
-- [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation
-- [ ] **Context-Rich**: Each requirement includes rationale summary for immediate understanding
-- [ ] **Resource-Aware**: Team skill gaps and constraints explicitly documented
-- [ ] **Risk-Managed**: Both technical and process risks captured with mitigation strategies
-- [ ] **Measurable Success**: Clear success metrics and monitoring frameworks
-- [ ] **Clear Actions**: Specific next steps with assigned responsibilities and timelines
-
-### Integration Excellence Standards
-- [ ] **Cross-Role Synthesis**: Successfully identifies and documents role perspective conflicts
-- [ ] **No Role Marginalization**: Process, UX, and compliance concerns equally visible as functional requirements
-- [ ] **Strategic Coherence**: Recommendations form coherent strategic direction
-- [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
-- [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
-- [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+### 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
 
 ## 🚀 **Recommended Next Steps**
 
-After synthesis completion, follow this recommended workflow:
+After synthesis completion, proceed to action planning:
 
-### Option 1: Standard Planning Workflow (Recommended)
+### Standard Workflow (Recommended)
 ```bash
-# Step 1: Verify conceptual clarity (Quality Gate)
-/workflow:concept-verify --session WFS-{session-id}
-# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
-
-# Step 2: Proceed to action planning (after concept verification)
-/workflow:plan --session WFS-{session-id}
-# → Generates IMPL_PLAN.md and task.json files
-
-# Step 3: Verify action plan quality (Quality Gate)
-/workflow:action-plan-verify --session WFS-{session-id}
-# → Read-only analysis to catch issues before execution
-
-# Step 4: Start implementation
-/workflow:execute --session WFS-{session-id}
+/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
 ```
 
-### Option 2: TDD Workflow
+### TDD Workflow
 ```bash
-# Step 1: Verify conceptual clarity
-/workflow:concept-verify --session WFS-{session-id}
-
-# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
+/workflow:concept-clarify --session WFS-{session-id}  # Optional: Clarify ambiguities
 /workflow:tdd-plan --session WFS-{session-id} "Feature description"
-
-# Step 3: Verify TDD plan quality
-/workflow:action-plan-verify --session WFS-{session-id}
-
-# Step 4: Execute TDD workflow
+/workflow:action-plan-verify --session WFS-{session-id}  # Optional: Verify plan quality
 /workflow:execute --session WFS-{session-id}
 ```
-
-### Quality Gates Explained
-
-**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
-- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
-- **Time**: 10-20 minutes (interactive)
-- **Value**: Reduces downstream rework by 40-60%
-- **Output**: Updated synthesis-specification.md with clarifications
-
-**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
-- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
-- **Time**: 5-10 minutes (read-only analysis)
-- **Value**: Prevents execution of flawed plans, saves 2-5 days
-- **Output**: Verification report with actionable recommendations
-
-### Skip Verification? (Not Recommended)
-
-If you want to skip verification and proceed directly:
-```bash
-/workflow:plan --session WFS-{session-id}
-/workflow:execute --session WFS-{session-id}
-```
-
-⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

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

@@ -22,6 +22,25 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Performance & Scalability**: Capacity planning and optimization strategies
 - **Integration Patterns**: System communication and data flow design
 
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Macro-Architecture)**
+- **System-Level Architecture**: Service boundaries, deployment topology, and system composition
+- **Cross-Service Communication Patterns**: Choosing between microservices/monolithic, event-driven/request-response, sync/async patterns
+- **Technology Stack Decisions**: Language, framework, database, and infrastructure choices
+- **Non-Functional Requirements**: Scalability, performance, availability, disaster recovery, and monitoring strategies
+- **Integration Planning**: How systems and services connect at the macro level (not specific API contracts)
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **API Contract Details**: Specific endpoint definitions, URL structures, HTTP methods → Defers to **API Designer**
+- **Data Schemas**: Detailed data model design and entity relationships → Defers to **Data Architect**
+- **UI/UX Design**: Interface design and user experience → Defers to **UX Expert** and **UI Designer**
+
+#### **Handoff Points**
+- **TO API Designer**: Provides architectural constraints (REST vs GraphQL, sync vs async) that define the API design space
+- **TO Data Architect**: Provides system-level data flow requirements and integration patterns
+- **FROM Data Architect**: Receives canonical data model to inform system integration design
+
 ## ⚙️ **Execution Protocol**
 
 ### Phase 1: Session & Framework Detection

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

@@ -17,10 +17,31 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
 
 ### Analysis Scope
-- **User Experience Design**: Intuitive and efficient user experiences
-- **Interface Design**: Beautiful and functional user interfaces
-- **Interaction Design**: Smooth user interaction flows and micro-interactions
-- **Accessibility Design**: Inclusive design meeting WCAG compliance
+- **Visual Design**: Color palettes, typography, spacing, and visual hierarchy implementation
+- **High-Fidelity Mockups**: Polished, pixel-perfect interface designs
+- **Design System Implementation**: Component libraries, design tokens, and style guides
+- **Micro-Interactions & Animations**: Transition effects, loading states, and interactive feedback
+- **Responsive Design**: Layout adaptations for different screen sizes and devices
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Concrete Visual Interface Implementation)**
+- **Visual Design Language**: Colors, typography, iconography, spacing, and overall aesthetic
+- **High-Fidelity Mockups**: Polished designs showing exactly how the interface will look
+- **Design System Components**: Building and documenting reusable UI components (buttons, inputs, cards, etc.)
+- **Design Tokens**: Defining variables for colors, spacing, typography that can be used in code
+- **Micro-Interactions**: Hover states, transitions, animations, and interactive feedback details
+- **Responsive Layouts**: Adapting designs for mobile, tablet, and desktop breakpoints
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **User Research & Personas**: User behavior analysis and needs assessment → Defers to **UX Expert**
+- **Information Architecture**: Content structure and navigation strategy → Defers to **UX Expert**
+- **Low-Fidelity Wireframes**: Structural layouts without visual design → Defers to **UX Expert**
+
+#### **Handoff Points**
+- **FROM UX Expert**: Receives wireframes, user flows, and information architecture as the foundation for visual design
+- **TO Frontend Developers**: Provides design specifications, component libraries, and design tokens for implementation
+- **WITH API Designer**: Coordinates on data presentation and form validation feedback (visual aspects only)
 
 ## ⚙️ **Execution Protocol**
 

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

@@ -17,10 +17,31 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
 
 ### Analysis Scope
-- **User Interface Design**: Visual hierarchy, layout patterns, and component design
-- **Interaction Patterns**: User flows, navigation, and microinteractions
-- **Usability Optimization**: Accessibility, cognitive load, and user testing strategies
-- **Design Systems**: Component libraries, design tokens, and consistency frameworks
+- **User Research**: User personas, behavioral analysis, and needs assessment
+- **Information Architecture**: Content structure, navigation hierarchy, and mental models
+- **User Journey Mapping**: User flows, task analysis, and interaction models
+- **Usability Strategy**: Accessibility planning, cognitive load reduction, and user testing frameworks
+- **Wireframing**: Low-fidelity layouts and structural prototypes (not visual design)
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Abstract User Experience & Research)**
+- **User Research & Personas**: Understanding target users, their goals, pain points, and behaviors
+- **Information Architecture**: Organizing content and defining navigation structures at a conceptual level
+- **User Journey Mapping**: Defining user flows, task sequences, and interaction models
+- **Wireframes & Low-Fidelity Prototypes**: Structural layouts showing information hierarchy (boxes and arrows, not colors/fonts)
+- **Usability Testing Strategy**: Planning user testing, A/B tests, and validation methods
+- **Accessibility Planning**: WCAG compliance strategy and inclusive design principles
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **Visual Design**: Colors, typography, spacing, visual style → Defers to **UI Designer**
+- **High-Fidelity Mockups**: Polished, pixel-perfect designs → Defers to **UI Designer**
+- **Component Implementation**: Design system components, CSS, animations → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **TO UI Designer**: Provides wireframes, user flows, and information architecture that UI Designer will transform into high-fidelity visual designs
+- **FROM User Research**: May receive external research data to inform UX decisions
+- **TO Product Owner**: Provides user insights and validation results to inform feature prioritization
 
 ## ⚙️ **Execution Protocol**
 

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

@@ -15,9 +15,13 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Outline
 
-**Goal**: Detect and reduce ambiguity or missing decision points in brainstorming artifacts (synthesis-specification.md, topic-framework.md, role analyses) before moving to action planning phase.
+**Goal**: Detect and reduce ambiguity or missing decision points in planning artifacts before moving to task generation. Supports both brainstorm and plan workflows.
 
-**Timing**: This command runs AFTER `/workflow:brainstorm:synthesis` and BEFORE `/workflow:plan`. It serves as a quality gate to ensure conceptual clarity before detailed task planning.
+**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**:
 
@@ -34,34 +38,60 @@ You **MUST** consider the user input before proceeding (if not empty).
            ERROR: "No active workflow session found. Use --session <session-id> or start a session."
            EXIT
 
-   # Validate brainstorming completion
+   # Mode detection: plan vs brainstorm
    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+   process_dir = .workflow/WFS-{session}/.process/
 
-   CHECK: brainstorm_dir/synthesis-specification.md
-   IF NOT EXISTS:
-       ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
+   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
 
-   CHECK: brainstorm_dir/topic-framework.md
-   IF NOT EXISTS:
-       WARN: "topic-framework.md not found. Verification will be limited."
+   # 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 Brainstorming Artifacts**
+2. **Load Artifacts (Mode-Aware)**
    ```bash
-   # Load primary artifacts
-   synthesis_spec = Read(brainstorm_dir + "/synthesis-specification.md")
-   topic_framework = Read(brainstorm_dir + "/topic-framework.md") # if exists
+   # Load primary artifact (determined in step 1)
+   primary_content = Read(primary_artifact)
 
-   # Discover role analyses
-   role_analyses = Glob(brainstorm_dir + "/*/analysis.md")
-   participating_roles = extract_role_names(role_analyses)
+   # 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
@@ -182,8 +212,8 @@ You **MUST** consider the user input before proceeding (if not empty).
 
    ```bash
    # Ensure Clarifications section exists
-   IF synthesis_spec NOT contains "## Clarifications":
-       Insert "## Clarifications" section after "# [Topic]" heading
+   IF primary_content NOT contains "## Clarifications":
+       Insert "## Clarifications" section after first heading
 
    # Create session subsection
    IF NOT contains "### Session YYYY-MM-DD":
@@ -194,20 +224,20 @@ You **MUST** consider the user input before proceeding (if not empty).
 
    # Apply clarification to appropriate section
    CASE category:
-       Functional Requirements → Update "## Requirements & Acceptance Criteria"
-       Architecture → Update "## Key Designs & Decisions" or "## Design Specifications"
-       User Experience → Update "## Design Specifications > UI/UX Guidelines"
-       Risk → Update "## Risk Assessment & Mitigation"
-       Process → Update "## Process & Collaboration Concerns"
-       Data Model → Update "## Key Designs & Decisions > Data Model Overview"
-       Non-Functional → Update "## Requirements & Acceptance Criteria > Non-Functional Requirements"
+       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
-   Write(synthesis_specification.md)
+   # Save immediately to primary_artifact
+   Write(primary_artifact)
    ```
 
 7. **Validation After Each Write**
@@ -227,8 +257,9 @@ You **MUST** consider the user input before proceeding (if not empty).
    ## ✅ Concept Verification Complete
 
    **Session**: WFS-{session-id}
+   **Mode**: {clarify_mode}
    **Questions Asked**: {count}/5
-   **Artifacts Updated**: synthesis-specification.md
+   **Artifacts Updated**: {primary_artifact filename}
    **Sections Touched**: {list section names}
 
    ### Coverage Summary
@@ -254,6 +285,13 @@ You **MUST** consider the user input before proceeding (if not empty).
    - 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
    ```
@@ -261,18 +299,26 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 9. **Update Session Metadata**
 
-   ```json
+   ```bash
+   # Update metadata based on mode
+   IF clarify_mode == "brainstorm":
+       phase_key = "BRAINSTORM"
+   ELSE: # plan mode
+       phase_key = "PLAN"
+
+   # Update session metadata
    {
      "phases": {
-       "BRAINSTORM": {
-         "status": "completed",
+       "{phase_key}": {
+         "status": "concept_verified",
          "concept_verification": {
            "completed": true,
            "completed_at": "timestamp",
-           "questions_asked": 3,
-           "categories_clarified": ["Requirements", "Risk", "Architecture"],
+           "mode": "{clarify_mode}",
+           "questions_asked": {count},
+           "categories_clarified": [{list}],
            "outstanding_items": [],
-           "recommendation": "PROCEED_TO_PLANNING"
+           "recommendation": "PROCEED" # or "ADDRESS_OUTSTANDING"
          }
        }
      }

.claude/commands/workflow/execute.md

@@ -35,28 +35,21 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 - **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
 
 ## Flow Control Execution
-**[FLOW_CONTROL]** marker indicates sequential step execution required for context gathering and preparation. **These steps are executed BY THE AGENT, not by the workflow:execute command.**
+**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
 
-### Flow Control Rules
-1. **Auto-trigger**: When `task.flow_control.pre_analysis` array exists in task JSON, agents execute these steps
-2. **Sequential Processing**: Agents execute steps in order, accumulating context including artifacts
-3. **Variable Passing**: Agents use `[variable_name]` syntax to reference step outputs including artifact content
-4. **Error Handling**: Agents follow step-specific error strategies (`fail`, `skip_optional`, `retry_once`)
-5. **Artifacts Priority**: When artifacts exist in task.context.artifacts, load synthesis specifications first
+### Orchestrator Responsibility
+- Pass complete task JSON to agent (including `flow_control` block)
+- Provide session paths for artifact access
+- Monitor agent completion
 
-### Execution Pattern
-```
-Step 1: load_dependencies → dependency_context
-Step 2: analyze_patterns [dependency_context] → pattern_analysis
-Step 3: implement_solution [pattern_analysis] [dependency_context] → implementation
-```
+### Agent Responsibility
+- Parse `flow_control.pre_analysis` array from JSON
+- Execute steps sequentially with variable substitution
+- Accumulate context from artifacts and dependencies
+- Follow error handling per `step.on_error`
+- Complete implementation using accumulated context
 
-### Context Accumulation Process (Executed by Agents)
-- **Load Artifacts**: Agents retrieve synthesis specifications and brainstorming outputs from `context.artifacts`
-- **Load Dependencies**: Agents retrieve summaries from `context.depends_on` tasks
-- **Execute Analysis**: Agents run CLI tools with accumulated context including artifacts
-- **Prepare Implementation**: Agents build comprehensive context for implementation
-- **Continue Implementation**: Agents use all accumulated context including artifacts for task execution
+**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
 
 ## Execution Lifecycle
 
@@ -143,6 +136,102 @@ completed → skip
 blocked → skip until dependencies clear
 ```
 
+## Batch Execution with Dependency Graph
+
+### Parallel Execution Algorithm
+**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
+
+#### Algorithm Steps
+```javascript
+function executeBatchWorkflow(sessionId) {
+  // 1. Build dependency graph from task JSONs
+  const graph = buildDependencyGraph(`.workflow/${sessionId}/.task/*.json`);
+
+  // 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);
+
+    // 5. Execute batch concurrently
+    await Promise.all(
+      parallelGroups.map(group => executeBatch(group))
+    );
+
+    // 6. Update graph: remove completed tasks and their edges
+    graph.removeNodes(batch);
+
+    // 7. Update TodoWrite to reflect completed batch
+    updateTodoWriteAfterBatch(batch);
+  }
+
+  // 8. All tasks complete - auto-complete session
+  SlashCommand("/workflow:session:complete");
+}
+
+function buildDependencyGraph(taskFiles) {
+  const tasks = loadAllTaskJSONs(taskFiles);
+  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
+    });
+  });
+
+  return graph;
+}
+
+function groupByExecutionGroup(tasks) {
+  const groups = {};
+
+  tasks.forEach(task => {
+    const groupId = task.meta.execution_group || task.id;
+    if (!groups[groupId]) groups[groupId] = [];
+    groups[groupId].push(task);
+  });
+
+  return Object.values(groups);
+}
+
+async function executeBatch(tasks) {
+  // Execute all tasks in batch concurrently
+  return Promise.all(
+    tasks.map(task => executeTask(task))
+  );
+}
+```
+
+#### Execution Group Rules
+1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
+2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
+3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
+4. **Same `context_signature`** → Should have been merged (warning if not)
+
+#### Parallel Execution Example
+```
+Batch 1 (no dependencies):
+  - IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
+  - IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
+  - IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
+
+Wait for Batch 1 completion...
+
+Batch 2 (depends on Batch 1):
+  - IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
+
+Wait for Batch 2 completion...
+
+Batch 3 (independent of Batch 2):
+  - IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
+  - IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
+```
+
 ## TodoWrite Coordination
 **Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
 
@@ -150,8 +239,11 @@ blocked → skip until dependencies clear
 1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
    - **Normal Mode**: Create from discovery results
    - **Resume Mode**: Create from existing session state and current progress
-2. **Single In-Progress**: Mark ONLY ONE task as `in_progress` at a time
-3. **Immediate Updates**: Update status after each task completion without user interruption
+2. **Parallel Task Support**:
+   - **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
+   - **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
+   - **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
+3. **Immediate Updates**: Update status after each task/batch completion without user interruption
 4. **Status Synchronization**: Sync with JSON task files after updates
 5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
 
@@ -167,36 +259,71 @@ blocked → skip until dependencies clear
 **Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
 
 ```javascript
-// Create initial todo list from discovered pending tasks
+// Example 1: Sequential execution (traditional)
 TodoWrite({
   todos: [
     {
       content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
-      status: "pending",
+      status: "in_progress",  // Single task in progress
       activeForm: "Executing IMPL-1.1: Design auth schema"
     },
     {
       content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]",
       status: "pending",
       activeForm: "Executing IMPL-1.2: Implement auth logic"
-    },
-    {
-      content: "Execute TEST-FIX-1: Validate implementation tests [test-fix-agent]",
-      status: "pending",
-      activeForm: "Executing TEST-FIX-1: Validate implementation tests"
     }
   ]
 });
 
-// Update status as tasks progress - ONLY ONE task should be in_progress at a time
+// Example 2: Batch execution (parallel tasks with execution_group)
 TodoWrite({
   todos: [
     {
-      content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
-      status: "in_progress",  // Mark current task as in_progress
-      activeForm: "Executing IMPL-1.1: Design auth schema"
+      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
+      status: "in_progress",  // Batch task 1
+      activeForm: "Executing IMPL-1.1: Build Auth API"
     },
-    // ... other tasks remain pending
+    {
+      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
+      status: "in_progress",  // Batch task 2 (running concurrently)
+      activeForm: "Executing IMPL-1.2: Build User UI"
+    },
+    {
+      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
+      status: "in_progress",  // Batch task 3 (running concurrently)
+      activeForm: "Executing IMPL-1.3: Setup Database"
+    },
+    {
+      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]",
+      status: "pending",  // Next batch (waits for current batch completion)
+      activeForm: "Executing IMPL-2.1: Integration Tests"
+    }
+  ]
+});
+
+// Example 3: After batch completion
+TodoWrite({
+  todos: [
+    {
+      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.1: Build Auth API"
+    },
+    {
+      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.2: Build User UI"
+    },
+    {
+      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.3: Setup Database"
+    },
+    {
+      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
+      status: "in_progress",  // Next batch started
+      activeForm: "Executing IMPL-2.1: Integration Tests"
+    }
   ]
 });
 ```
@@ -282,82 +409,40 @@ TodoWrite({
 #### Agent Prompt Template
 ```bash
 Task(subagent_type="{meta.agent}",
-     prompt="**TASK EXECUTION WITH FULL JSON LOADING**
+     prompt="**EXECUTE TASK FROM JSON**
 
-     ## STEP 1: Load Complete Task JSON
-     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+     ## Task JSON Location
+     {session.task_json_path}
 
-     cat {session.task_json_path}
+     ## 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
+        - 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}
+        - Generate summary: {session.summaries_dir}/{task.id}-summary.md
+        - Check workflow completion and call `/workflow:session:complete` if all tasks done
 
-     **CRITICAL**: Validate all 5 required fields are present:
-     - id, title, status, meta, context, flow_control
+     ## Context Sources (All from JSON)
+     - Requirements: `context.requirements`
+     - Focus Paths: `context.focus_paths`
+     - Acceptance: `context.acceptance`
+     - Artifacts: `context.artifacts` (synthesis specs, brainstorming outputs)
+     - Dependencies: `context.depends_on`
+     - Target Files: `flow_control.target_files`
 
-     ## STEP 2: Task Definition (From Loaded JSON)
-     **ID**: Use id field from JSON
-     **Title**: Use title field from JSON
-     **Type**: Use meta.type field from JSON
-     **Agent**: Use meta.agent field from JSON
-     **Status**: Verify status is pending or active
+     ## Session Paths
+     - Workflow Dir: {session.workflow_dir}
+     - TODO List: {session.todo_list_path}
+     - Summaries: {session.summaries_dir}
+     - Flow Context: {flow_context.step_outputs}
 
-     ## STEP 3: Flow Control Execution (if flow_control.pre_analysis exists)
-     **AGENT RESPONSIBILITY**: Execute pre_analysis steps sequentially from loaded JSON:
-
-     **PRIORITY: Artifact Loading Steps First**
-     1. **Load Synthesis Specification** (if present): Priority artifact loading for consolidated design
-     2. **Load Individual Artifacts** (fallback): Load role-specific brainstorming outputs if synthesis unavailable
-     3. **Execute Remaining Steps**: Continue with other pre_analysis steps
-
-     For each step in flow_control.pre_analysis array:
-     1. Execute step.command/commands with variable substitution (support both single command and commands array)
-     2. Store output to step.output_to variable
-     3. Handle errors per step.on_error strategy (skip_optional, fail, retry_once)
-     4. Pass accumulated variables to next step including artifact context
-
-     **Special Artifact Loading Commands**:
-     - Use `bash(ls path 2>/dev/null || echo 'file not found')` for artifact existence checks
-     - Use `Read(path)` for loading artifact content
-     - Use `find` commands for discovering multiple artifact files
-     - Reference artifacts in subsequent steps using output variables: [synthesis_specification], [individual_artifacts]
-
-     ## STEP 4: Implementation Context (From JSON context field)
-     **Requirements**: Use context.requirements array from JSON
-     **Focus Paths**: Use context.focus_paths array from JSON
-     **Acceptance Criteria**: Use context.acceptance array from JSON
-     **Dependencies**: Use context.depends_on array from JSON
-     **Parent Context**: Use context.inherited object from JSON
-     **Artifacts**: Use context.artifacts array from JSON (synthesis specifications, brainstorming outputs)
-     **Target Files**: Use flow_control.target_files array from JSON
-     **Implementation Approach**: Use flow_control.implementation_approach object from JSON (with artifact integration)
-
-     ## STEP 5: Session Context (Provided by workflow:execute)
-     **Workflow Directory**: {session.workflow_dir}
-     **TODO List Path**: {session.todo_list_path}
-     **Summaries Directory**: {session.summaries_dir}
-     **Task JSON Path**: {session.task_json_path}
-     **Flow Context**: {flow_context.step_outputs}
-
-     ## STEP 6: Agent Completion Requirements
-     1. **Load Task JSON**: Read and validate complete task structure
-     2. **Execute Flow Control**: Run all pre_analysis steps if present
-     3. **Implement Solution**: Follow implementation_approach from JSON
-     4. **Update Progress**: Mark task status in JSON as completed
-     5. **Update TODO List**: Update TODO_LIST.md at provided path
-     6. **Generate Summary**: Create completion summary in summaries directory
-     7. **Check Workflow Complete**: After task completion, check if all workflow tasks done
-     8. **Auto-Complete Session**: If all tasks completed, call SlashCommand(\"/workflow:session:complete\")
-
-     **JSON UPDATE COMMAND**:
-     Update task status to completed using jq:
-     jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}
-
-     **WORKFLOW COMPLETION CHECK**:
-     After updating task status, check if workflow is complete:
-     total_tasks=\$(find .workflow/*/\.task/ -name "*.json" -type f 2>/dev/null | wc -l)
-     completed_tasks=\$(find .workflow/*/\.summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-     if [ \$total_tasks -eq \$completed_tasks ]; then
-       SlashCommand(command=\"/workflow:session:complete\")
-     fi"),
-     description="Execute task with full JSON loading and validation")
+     **Complete JSON structure is authoritative - load and follow it exactly.**"),
+     description="Execute task: {task.id}")
 ```
 
 #### Agent JSON Loading Specification

.claude/commands/workflow/plan.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
+description: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
 argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -9,22 +9,24 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 4 slash commands in sequence, parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
+**This command is a pure orchestrator**: Execute 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
 
-**Execution Model - Auto-Continue Workflow**:
+**Execution Model - Auto-Continue Workflow with Quality Gate**:
 
-This workflow runs **fully autonomously** once triggered. Each phase completes, reports its output to you, then **immediately and automatically** proceeds to the next phase without requiring any user intervention.
+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.
 
 1. **User triggers**: `/workflow:plan "task"`
-2. **Phase 1 executes** → Reports output to user → Auto-continues
-3. **Phase 2 executes** → Reports output to user → Auto-continues
-4. **Phase 3 executes** → Reports output to user → Auto-continues
-5. **Phase 4 executes** → Reports final summary
+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
 
 **Auto-Continue Mechanism**:
 - TodoList tracks current phase status
 - After each phase completion, automatically executes next pending phase
-- **No user action required** - workflow runs end-to-end autonomously
+- **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
 - Progress updates shown at each phase for visibility
 
 **Execution Modes**:
@@ -36,11 +38,12 @@ This workflow runs **fully autonomously** once triggered. Each phase completes,
 
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
 2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1
-3. **Parse Every Output**: Extract required data from each command's output for next phase
+3. **Parse Every Output**: Extract required data from each command/agent output for next phase
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
 5. **Track Progress**: Update TodoWrite after every phase completion
+6. **Agent Delegation**: Phase 3 uses cli-execution-agent for autonomous intelligent analysis
 
-## 4-Phase Execution
+## 5-Phase Execution
 
 ### Phase 1: Session Discovery
 **Command**: `SlashCommand(command="/workflow:session:start --auto \"[structured-task-description]\"")`
@@ -81,7 +84,7 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **Parse Output**:
 - Extract: context-package.json path (store as `contextPath`)
-- Typical pattern: `.workflow/[sessionId]/.context/context-package.json`
+- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
 
 **Validation**:
 - Context package path extracted
@@ -94,20 +97,62 @@ CONTEXT: Existing user database schema, REST API endpoints
 ---
 
 ### Phase 3: Intelligent Analysis
+
 **Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")`
 
 **Input**: `sessionId` from Phase 1, `contextPath` from Phase 2
 
 **Parse Output**:
-- Verify ANALYSIS_RESULTS.md created
+- Extract: Execution status (success/failed)
+- Verify: ANALYSIS_RESULTS.md file path
 
 **Validation**:
-- File `.workflow/[sessionId]/ANALYSIS_RESULTS.md` exists
-- Contains task recommendations section
+- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
-**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 4
+**TodoWrite**: Mark phase 3 completed, phase 3.5 in_progress
+
+**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 3.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 3.5
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
+---
+
+### Phase 3.5: Concept Clarification (Quality Gate)
+
+**Command**: `SlashCommand(command="/workflow:concept-clarify --session [sessionId]")`
+
+**Purpose**: Quality gate to verify and clarify analysis results before task generation
+
+**Input**: `sessionId` from Phase 1
+
+**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)
+
+**Parse Output**:
+- Verify clarifications added to ANALYSIS_RESULTS.md
+- Check recommendation: "PROCEED" or "ADDRESS_OUTSTANDING"
+
+**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
 
 ---
 
@@ -115,9 +160,11 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **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
 - **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
 
 **Command Selection**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
@@ -168,6 +215,7 @@ 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"},
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
@@ -176,10 +224,11 @@ 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 task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// Continue pattern for Phase 2, 3, 4...
+// Continue pattern for Phase 2, 3, 3.5, 4...
 ```
 
 ## Input Processing
@@ -230,12 +279,18 @@ Phase 2: context-gather --session sessionId "structured-description"
     ↓ Input: sessionId + session memory + structured description
     ↓ Output: contextPath (context-package.json)
     ↓
-Phase 3: concept-enhanced --session sessionId --context contextPath
-    ↓ Input: sessionId + contextPath + session memory
-    ↓ Output: ANALYSIS_RESULTS.md
+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 4: task-generate[--agent] --session sessionId
-    ↓ Input: sessionId + ANALYSIS_RESULTS.md + session memory
+    ↓ Input: sessionId + clarified ANALYSIS_RESULTS.md + session memory
     ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
     ↓
 Return summary to user
@@ -262,13 +317,18 @@ Return summary to user
 ## Coordinator Checklist
 
 ✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
-✅ Initialize TodoWrite before any command
+✅ 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
-✅ Pass session ID and context path to Phase 3 command
-✅ Verify ANALYSIS_RESULTS.md after Phase 3
+✅ **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:
   - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
   - Add `--session [sessionId]`

.claude/commands/workflow/review.md

@@ -99,10 +99,10 @@ After bash validation, the model takes control to:
      ```
    - 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

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

@@ -95,47 +95,72 @@ TEST_FOCUS: [Test scenarios]
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
 
-**Parse**: Extract feature count, chain count, task count
+**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
 
 **Validate**:
-- IMPL_PLAN.md exists (unified plan with TDD Task Chains section)
-- TEST-*.json, IMPL-*.json, REFACTOR-*.json exist
-- TODO_LIST.md exists
-- IMPL tasks include test-fix-cycle configuration
+- IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
+- IMPL-*.json files exist (one per feature, or container + subtasks for complex features)
+- TODO_LIST.md exists with internal TDD phase indicators
+- Each IMPL task includes:
+  - `meta.tdd_workflow: true`
+  - `flow_control.implementation_approach` with 3 steps (red/green/refactor)
+  - Green phase includes test-fix-cycle configuration
 - 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)
 **Internal validation first, then recommend external verification**
 
 **Internal Validation**:
-1. Each feature has TEST → IMPL → REFACTOR chain
-2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
-3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
-4. Agents: TEST uses @code-review-test-agent, IMPL/REFACTOR use @code-developer
-5. IMPL tasks contain test-fix-cycle in flow_control for iterative Green phase
+1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
+2. Task structure validation:
+   - `meta.tdd_workflow: true` in all IMPL tasks
+   - `flow_control.implementation_approach` has exactly 3 steps
+   - Each step has correct `tdd_phase`: "red", "green", "refactor"
+3. Dependency validation:
+   - Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
+   - Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
+4. Agent assignment: All IMPL tasks use @code-developer
+5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
+6. Task count: Total tasks ≤10 (simple + subtasks)
 
 **Return Summary**:
 ```
 TDD Planning complete for session: [sessionId]
 
 Features analyzed: [N]
-TDD chains generated: [N]
-Total tasks: [3N]
+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 ✅)
 
 Structure:
-- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
+- 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)
 [...]
 
-Plan:
+Plans generated:
 - Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
-  (includes TDD Task Chains section with workflow_type: "tdd")
+  (includes TDD Implementation Tasks section with workflow_type: "tdd")
+- Task List: .workflow/[sessionId]/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
 
 ✅ Recommended Next Steps:
-1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+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 dependencies
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
 ```
 
 ## TodoWrite Pattern
@@ -232,14 +257,18 @@ Supports action-planning-agent for more autonomous TDD planning with:
 
 ### Workflow Comparison
 
-| Aspect | Previous | Current |
-|--------|----------|---------|
-| **Phases** | 5 | 6 (test coverage analysis) |
+| Aspect | Previous | Current (Optimized) |
+|--------|----------|---------------------|
+| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
 | **Context** | Greenfield assumption | Existing codebase aware |
+| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
 | **Green Phase** | Single implementation | Iterative with fix cycle |
 | **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
 | **Test Analysis** | None | Deep coverage analysis |
 | **Feedback Loop** | Post-execution | During Green phase |
+| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
+| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
 
 ### Migration Notes
 
@@ -251,19 +280,26 @@ Supports action-planning-agent for more autonomous TDD planning with:
 **Session Structure**:
 ```
 .workflow/WFS-xxx/
-├── IMPL_PLAN.md (unified plan with TDD Task Chains section)
-├── TODO_LIST.md
+├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
+├── TODO_LIST.md (with internal TDD phase indicators)
 ├── .process/
 │   ├── context-package.json
 │   ├── test-context-package.json
 │   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
-│   └── green-fix-iteration-*.md (fix logs)
+│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
 └── .task/
-    ├── TEST-*.json (Red phase)
-    ├── IMPL-*.json (Green phase with test-fix-cycle)
-    └── REFACTOR-*.json (Refactor phase)
+    ├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
+    ├── IMPL-2.json (Complete TDD task)
+    ├── IMPL-3.json (Complex feature container, if needed)
+    ├── IMPL-3.1.json (Complex feature subtask, if needed)
+    └── IMPL-3.2.json (Complex feature subtask, if needed)
 ```
 
+**File Count Comparison**:
+- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
+- **New structure**: 5 features = 5 task files (IMPL-N × 5)
+- **Complex features**: Add container + subtasks only when necessary
+
 **Configuration Options** (in IMPL tasks):
 - `meta.max_iterations`: Fix attempts (default: 3)
 - `meta.use_codex`: Auto-fix mode (default: false)

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

@@ -3,7 +3,7 @@ name: tdd-verify
 description: Verify TDD workflow compliance and generate quality report
 
 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}

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

@@ -0,0 +1,651 @@
+---
+name: test-cycle-execute
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles
+argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
+---
+
+# Workflow Test-Cycle-Execute Command
+
+## 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.
+
+**Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
+
+## Core Philosophy
+
+### Dynamic vs Static Execution
+**Standard Execute**: Pre-defined task queue → Sequential execution → Complete
+**Test Execute**: Initial tasks → Test → Analyze → Generate fix tasks → Execute → Re-test → Repeat
+
+### Iteration Loop Pattern
+```
+1. Execute current task (test/implement)
+2. Run tests and collect results
+3. If failures: CLI analysis → Generate fix tasks → Execute → Back to 2
+4. If success: Mark complete → Next task
+5. Repeat until all tests pass or max iterations reached
+```
+
+### Agent Coordination
+- **@code-developer**: Understands requirements, generates implementations
+- **@test-fix-agent**: Executes tests, applies fixes, validates results
+- **CLI Tools (Gemini/Qwen)**: Analyzes failures, suggests fix strategies
+
+## Core Rules
+1. **Dynamic Task Generation**: Create intermediate fix tasks based on test failures
+2. **Iterative Execution**: Repeat test-fix cycles until success or max iterations
+3. **CLI-Driven Analysis**: Use Gemini/Qwen to analyze failures and plan fixes
+4. **Agent Delegation**: All execution delegated to specialized agents
+5. **Context Accumulation**: Each iteration builds on previous attempt context
+6. **Autonomous Completion**: Continue until all tests pass without user interruption
+
+## Core Responsibilities
+- **Session Discovery**: Identify test-fix workflow sessions
+- **Task Queue Management**: Maintain dynamic task queue with runtime additions
+- **Test Execution**: Run tests through @test-fix-agent
+- **Failure Analysis**: Use CLI tools to diagnose test failures
+- **Fix Task Generation**: Create intermediate fix tasks dynamically
+- **Iteration Control**: Manage fix cycles with max iteration limits
+- **Context Propagation**: Pass failure context and fix history between iterations
+- **Progress Tracking**: TodoWrite updates for entire iteration cycle
+- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
+
+## Responsibility Matrix
+
+**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 |
+
+**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
+
+## Execution Lifecycle
+
+### Phase 1: Discovery & Initialization
+1. **Detect Session Type**: Identify test-fix session from `workflow_type: "test_session"`
+2. **Load Session State**: Read `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`
+3. **Scan Initial Tasks**: Analyze `.task/*.json` files
+4. **Initialize TodoWrite**: Create task list including initial tasks
+5. **Prepare Iteration Context**: Setup iteration counter and max limits
+
+**Resume Mode**: Load existing iteration context from `.process/iteration-state.json`
+
+### Phase 2: Task Execution Loop
+**Main execution loop with dynamic task generation (executed by test-cycle-execute orchestrator):**
+
+**Execution Order**: The workflow begins by executing IMPL-001 (test generation) first. Upon successful completion, IMPL-002 (test-fix cycle) is initiated, starting the iterative test-fix loop.
+
+```
+For each task in queue:
+  1. [Orchestrator] Load task JSON and context
+  2. [Orchestrator] Determine task type (test-gen, test-fix, fix-iteration)
+  3. [Orchestrator] Execute task through appropriate agent
+  4. [Orchestrator] Collect agent results and check exit conditions
+  5. If test failures detected:
+     a. [Orchestrator] Run CLI analysis (Gemini/Qwen)
+     b. [Orchestrator] Generate fix task JSON (IMPL-fix-N.json)
+     c. [Orchestrator] Insert fix task at front of queue
+     d. [Orchestrator] Continue loop
+  6. If test success:
+     a. [Orchestrator] Mark task complete
+     b. [Orchestrator] Update TodoWrite
+     c. [Orchestrator] Continue to next task
+  7. [Orchestrator] Check max iterations limit
+```
+
+**Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
+
+### Phase 3: Iteration Cycle (Test-Fix Loop)
+
+**Orchestrator-controlled iteration with agent delegation:**
+
+#### Iteration Structure
+```
+Iteration N (managed by test-cycle-execute orchestrator):
+├── 1. Test Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with test task
+│   ├── [Agent] Run test suite
+│   ├── [Agent] Collect failures and report back
+│   └── [Orchestrator] Receive failure report
+├── 2. Failure Analysis
+│   ├── [Orchestrator] Run CLI tool (Gemini/Qwen)
+│   ├── [CLI Tool] Analyze error messages and failure context
+│   ├── [CLI Tool] Identify root causes
+│   └── [CLI Tool] Generate fix strategy → saved to iteration-N-analysis.md
+├── 3. Fix Task Generation
+│   ├── [Orchestrator] Parse CLI analysis results
+│   ├── [Orchestrator] Create IMPL-fix-N.json with:
+│   │   ├── meta.agent: "@test-fix-agent"
+│   │   ├── Failure context (content, not just path)
+│   │   └── Fix strategy from CLI analysis
+│   └── [Orchestrator] Insert into task queue (front position)
+├── 4. Fix Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with fix task
+│   ├── [Agent] Load fix strategy from task context
+│   ├── [Agent] Apply fixes to code/tests
+│   └── [Agent] Report completion
+└── 5. Re-test
+    └── [Orchestrator] Return to step 1 with updated code
+```
+
+**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
+
+#### Iteration Task JSON Template
+```json
+{
+  "id": "IMPL-fix-{iteration}",
+  "title": "Fix test failures - Iteration {N}",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix-iteration",
+    "agent": "@test-fix-agent",
+    "iteration": N,
+    "parent_task": "IMPL-002",
+    "max_iterations": 5
+  },
+  "context": {
+    "requirements": [
+      "Fix identified test failures",
+      "Address root causes from analysis"
+    ],
+    "failure_context": {
+      "failed_tests": ["test1", "test2"],
+      "error_messages": ["error1", "error2"],
+      "failure_analysis": "Raw test output and error messages",
+      "previous_attempts": ["iteration-1 context"]
+    },
+    "fix_strategy": {
+      "approach": "Generated by CLI tool (Gemini/Qwen) analysis",
+      "modification_points": ["file1:func1", "file2:func2"],
+      "expected_outcome": "All tests pass"
+    },
+    "depends_on": ["IMPL-fix-{N-1}"],
+    "inherited": {
+      "iteration_history": [...]
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_failure_context",
+        "command": "Read(.workflow/{session}/.process/iteration-{N-1}-failures.json)",
+        "output_to": "previous_failures",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "load_fix_strategy",
+        "command": "Read(.workflow/{session}/.process/iteration-{N}-strategy.md)",
+        "output_to": "fix_strategy",
+        "on_error": "fail"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Apply fixes from strategy",
+        "description": "Implement fixes identified by CLI analysis",
+        "modification_points": "From fix_strategy",
+        "logic_flow": [
+          "Load failure context and strategy",
+          "Apply surgical fixes",
+          "Run tests",
+          "Validate fixes"
+        ]
+      }
+    ],
+    "target_files": ["from fix_strategy"],
+    "exit_conditions": {
+      "success": "all_tests_pass",
+      "failure": "max_iterations_reached",
+      "max_iterations": 5
+    }
+  }
+}
+```
+
+### Phase 4: CLI Analysis Integration
+
+**Orchestrator executes CLI analysis between agent tasks:**
+
+#### When Test Failures Occur
+1. **[Orchestrator]** Detects failures from agent 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
+5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
+6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
+
+#### CLI Analysis Command (executed by orchestrator)
+```bash
+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
+
+[Test failure context and requirements...]
+
+EXPECTED: Detailed fix strategy in markdown format
+RULES: Focus on minimal changes, avoid over-engineering
+"
+```
+
+#### Analysis Output Structure
+```markdown
+# Test Failure Analysis - Iteration {N}
+
+## Root Cause Analysis
+1. **Test: test_auth_flow**
+   - Error: `Expected 200, got 401`
+   - Root Cause: Missing authentication token in request headers
+   - Affected Code: `src/auth/client.ts:45`
+
+2. **Test: test_data_validation**
+   - Error: `TypeError: Cannot read property 'name' of undefined`
+   - Root Cause: Null check missing before property access
+   - Affected Code: `src/validators/user.ts:23`
+
+## Fix Strategy
+
+### Priority 1: Authentication Issue
+- **File**: src/auth/client.ts
+- **Function**: sendRequest (line 45)
+- **Change**: Add token header: `headers['Authorization'] = 'Bearer ' + token`
+- **Verification**: Run test_auth_flow
+
+### Priority 2: Null Check
+- **File**: src/validators/user.ts
+- **Function**: validateUser (line 23)
+- **Change**: Add check: `if (!user?.name) return false`
+- **Verification**: Run test_data_validation
+
+## Verification Plan
+1. Apply fixes in order
+2. Run test suite after each fix
+3. Check for regressions
+4. Validate all tests pass
+
+## Risk Assessment
+- Low risk: Changes are surgical and isolated
+- No breaking changes expected
+- Existing tests should remain green
+```
+
+### Phase 5: Task Queue Management
+
+**Orchestrator maintains dynamic task queue with runtime insertions:**
+
+#### Dynamic Queue Operations
+```
+Initial Queue: [IMPL-001, IMPL-002]
+
+After IMPL-002 execution (test failures detected by orchestrator):
+  [Orchestrator] Generates IMPL-fix-1.json
+  [Orchestrator] Inserts at front: [IMPL-fix-1, IMPL-002-retest, ...]
+
+After IMPL-fix-1 execution (still failures):
+  [Orchestrator] Generates IMPL-fix-2.json
+  [Orchestrator] Inserts at front: [IMPL-fix-2, IMPL-002-retest, ...]
+
+After IMPL-fix-2 execution (success):
+  [Orchestrator] Continues to: [IMPL-002-complete, ...]
+```
+
+#### Queue Priority Rules (orchestrator-managed)
+1. **Fix tasks**: Inserted at queue front for immediate execution
+2. **Retest tasks**: Automatically scheduled after fix tasks
+3. **Regular tasks**: Standard dependency order preserved
+4. **Iteration limit**: Max 5 fix iterations per test task (orchestrator enforces)
+
+### Phase 6: Completion & Session Management
+
+#### Success Conditions
+- All initial tasks completed
+- All generated fix tasks completed
+- All tests passing
+- No pending tasks in queue
+
+#### Completion Steps
+1. **Final Validation**: Run full test suite one more time
+2. **Update Session State**: Mark all tasks completed
+3. **Generate Summary**: Create session completion summary
+4. **Update TodoWrite**: Mark all items completed
+5. **Auto-Complete**: Call `/workflow:session:complete`
+
+#### Failure Conditions
+- Max iterations reached without success
+- Unrecoverable test failures
+- Agent execution errors
+
+#### Failure Handling
+1. **Document State**: Save current iteration context
+2. **Generate Report**: Create failure analysis report
+3. **Preserve Context**: Keep all iteration logs
+4. **Mark Blocked**: Update task status to blocked
+5. **Return Control**: Return to user with detailed report
+
+## TodoWrite Coordination
+
+### TodoWrite Structure for Test-Execute
+```javascript
+TodoWrite({
+  todos: [
+    {
+      content: "Execute IMPL-001: Generate tests [code-developer]",
+      status: "completed",
+      activeForm: "Executing test generation"
+    },
+    {
+      content: "Execute IMPL-002: Test & Fix Cycle [test-fix-agent] [ITERATION]",
+      status: "in_progress",
+      activeForm: "Running test-fix iteration cycle"
+    },
+    {
+      content: "  → Iteration 1: Initial test run",
+      status: "completed",
+      activeForm: "Running initial tests"
+    },
+    {
+      content: "  → Iteration 2: Fix auth issues",
+      status: "in_progress",
+      activeForm: "Fixing authentication issues"
+    },
+    {
+      content: "  → Iteration 3: Re-test and validate",
+      status: "pending",
+      activeForm: "Re-testing after fixes"
+    }
+  ]
+});
+```
+
+### TodoWrite Update Rules
+1. **Initial Tasks**: Standard task list
+2. **Iteration Start**: Add nested iteration item
+3. **Fix Task Added**: Add fix task as nested item
+4. **Iteration Complete**: Mark iteration item completed
+5. **All Complete**: Mark parent task completed
+
+## Agent Context Package
+
+**Generated by test-cycle-execute orchestrator before launching agents.**
+
+The orchestrator assembles this context package from:
+- Task JSON file (IMPL-*.json)
+- Iteration state files
+- Test results and failure context
+- Session metadata
+
+This package is passed to agents via the Task tool's prompt context.
+
+### Enhanced Context for Test-Fix Agent
+```json
+{
+  "task": { /* IMPL-fix-N.json */ },
+  "iteration_context": {
+    "current_iteration": N,
+    "max_iterations": 5,
+    "previous_attempts": [
+      {
+        "iteration": N-1,
+        "failures": ["test1", "test2"],
+        "fixes_attempted": ["fix1", "fix2"],
+        "result": "partial_success"
+      }
+    ],
+    "failure_analysis": {
+      "source": "gemini_cli",
+      "analysis_file": ".process/iteration-N-analysis.md",
+      "fix_strategy": { /* from CLI */ }
+    }
+  },
+  "test_context": {
+    "test_framework": "jest|pytest|...",
+    "test_files": ["path/to/test1.test.ts"],
+    "test_command": "npm test",
+    "coverage_target": 80
+  },
+  "session": {
+    "workflow_dir": ".workflow/WFS-test-{session}/",
+    "iteration_state_file": ".process/iteration-state.json",
+    "test_results_file": ".process/test-results.json",
+    "fix_history_file": ".process/fix-history.json"
+  }
+}
+```
+
+## File Structure
+
+### Test-Fix Session Files
+```
+.workflow/WFS-test-{session}/
+├── workflow-session.json          # Session metadata with workflow_type
+├── IMPL_PLAN.md                   # Test plan
+├── TODO_LIST.md                   # Progress tracking
+├── .task/
+│   ├── IMPL-001.json              # Test generation task
+│   ├── IMPL-002.json              # Initial test-fix task
+│   ├── IMPL-fix-1.json            # Generated: Iteration 1 fix
+│   ├── IMPL-fix-2.json            # Generated: Iteration 2 fix
+│   └── ...
+├── .summaries/
+│   ├── IMPL-001-summary.md
+│   ├── IMPL-002-summary.md
+│   └── iteration-summaries/
+│       ├── iteration-1.md
+│       ├── iteration-2.md
+│       └── ...
+└── .process/
+    ├── TEST_ANALYSIS_RESULTS.md   # From planning phase
+    ├── iteration-state.json       # Current iteration state
+    ├── test-results.json          # Latest test results
+    ├── test-output.log            # Full test output
+    ├── fix-history.json           # All fix attempts
+    ├── iteration-1-analysis.md    # CLI analysis for iteration 1
+    ├── iteration-1-failures.json  # Failures from iteration 1
+    ├── iteration-1-strategy.md    # Fix strategy for iteration 1
+    ├── iteration-2-analysis.md
+    └── ...
+```
+
+### Iteration State JSON
+```json
+{
+  "session_id": "WFS-test-user-auth",
+  "current_task": "IMPL-002",
+  "current_iteration": 2,
+  "max_iterations": 5,
+  "started_at": "2025-10-17T10:00:00Z",
+  "iterations": [
+    {
+      "iteration": 1,
+      "started_at": "2025-10-17T10:05:00Z",
+      "completed_at": "2025-10-17T10:15:00Z",
+      "test_results": {
+        "total": 10,
+        "passed": 7,
+        "failed": 3,
+        "failures": ["test1", "test2", "test3"]
+      },
+      "analysis_file": ".process/iteration-1-analysis.md",
+      "fix_task": "IMPL-fix-1",
+      "result": "partial_success"
+    }
+  ],
+  "status": "active",
+  "next_action": "execute_fix_task"
+}
+```
+
+## Agent Prompt Template
+
+**Unified template for all agent tasks (orchestrator invokes with Task tool):**
+
+```bash
+Task(subagent_type="{meta.agent}",
+     prompt="**TASK EXECUTION: {task.title}**
+
+     ## STEP 1: Load Complete Task JSON
+     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+
+     cat {session.task_json_path}
+
+     **CRITICAL**: Validate all required fields present
+
+     ## STEP 2: Task Context (From Loaded JSON)
+     **ID**: {task.id}
+     **Type**: {task.meta.type}
+     **Agent**: {task.meta.agent}
+
+     ## STEP 3: Execute Task Based on Type
+
+     ### For test-gen (IMPL-001):
+     - Generate tests based on TEST_ANALYSIS_RESULTS.md
+     - Follow test framework conventions
+     - Create test files in target_files
+
+     ### For test-fix (IMPL-002):
+     - Run test suite: {test_command}
+     - Collect results to .process/test-results.json
+     - If failures: Save context, return to orchestrator
+     - 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
+
+     ## STEP 4: Implementation Context (From JSON)
+     **Requirements**: {context.requirements}
+     **Fix Strategy**: {context.fix_strategy} (full content provided in task JSON)
+     **Failure Context**: {context.failure_context}
+     **Iteration History**: {context.inherited.iteration_history}
+
+     ## STEP 5: Flow Control Execution
+     If flow_control.pre_analysis exists, execute steps sequentially
+
+     ## STEP 6: Agent Completion
+     1. Execute task following implementation_approach
+     2. Update task status in JSON
+     3. Update TODO_LIST.md
+     4. Generate summary in .summaries/
+     5. **CRITICAL**: Save results for orchestrator to analyze
+
+     **Output Requirements**:
+     - test-results.json: Structured test results
+     - test-output.log: Full test output
+     - iteration-state.json: Current iteration state (if applicable)
+     - task-summary.md: Completion summary
+
+     **Return to Orchestrator**: Agent completes and returns. Orchestrator decides next action.
+     "),
+     description="Execute {task.type} task with JSON validation")
+```
+
+**Key Points**:
+- Agent executes single task and returns
+- Orchestrator analyzes results and decides next step
+- Fix strategy content (not path) embedded in task JSON by orchestrator
+- Agent does not manage iteration loop
+
+## Error Handling & Recovery
+
+### Iteration Failure Scenarios
+| Scenario | Handling | Recovery |
+|----------|----------|----------|
+| Test execution error | Log error, save context | Retry with error context |
+| CLI analysis failure | Fallback to Qwen, or manual analysis | Retry analysis with different tool |
+| Agent execution error | Save iteration state | Retry agent with simplified context |
+| Max iterations reached | Generate failure report | Mark blocked, return to user |
+| Unexpected test regression | Rollback last fix | Analyze regression, add to fix strategy |
+
+### Recovery Procedures
+
+#### Resume from Interruption
+```bash
+# Load iteration state
+iteration_state=$(cat .workflow/{session}/.process/iteration-state.json)
+current_iteration=$(jq -r '.current_iteration' <<< "$iteration_state")
+
+# Determine resume point
+if [[ "$(jq -r '.next_action' <<< "$iteration_state")" == "execute_fix_task" ]]; then
+  # Resume fix task execution
+  task_id="IMPL-fix-${current_iteration}"
+else
+  # Resume test execution
+  task_id="IMPL-002"
+fi
+```
+
+#### Rollback Failed Fix
+```bash
+# Revert last commit (if fixes were committed)
+git revert HEAD
+
+# Remove failed fix task
+rm .workflow/{session}/.task/IMPL-fix-{N}.json
+
+# Restore iteration state
+jq '.current_iteration -= 1' iteration-state.json > temp.json
+mv temp.json iteration-state.json
+
+# Re-run analysis with additional context
+# Include failure reason in next analysis
+```
+
+## Usage Examples
+
+### Basic Usage
+```bash
+# Execute test-fix workflow
+/workflow:test-cycle-execute
+
+# Resume interrupted session
+/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
+
+# Set custom iteration limit
+/workflow:test-cycle-execute --max-iterations=10
+```
+
+### Integration with Planning
+```bash
+# 1. Plan test workflow
+/workflow:test-fix-gen WFS-user-auth
+
+# 2. Execute with dynamic iteration
+/workflow:test-cycle-execute
+
+# 3. Monitor progress
+/workflow:status
+
+# 4. Resume if interrupted
+/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
+```
+
+## Best Practices
+
+1. **Set Realistic Iteration Limits**: Default 5, increase for complex fixes
+2. **Commit Between Iterations**: Easier rollback if needed
+3. **Monitor Iteration Logs**: Review CLI analysis for insights
+4. **Incremental Fixes**: Prefer multiple small iterations over large changes
+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

@@ -0,0 +1,470 @@
+---
+name: test-fix-gen
+description: Create independent test-fix workflow session from existing implementation (session or prompt-based)
+argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
+---
+
+# Workflow Test-Fix Generation Command (/workflow:test-fix-gen)
+
+## Overview
+
+### What It Does
+
+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`).
+
+### Dual-Mode Support
+
+**Automatic mode detection** based on input pattern:
+
+| Mode | Input Pattern | Context Source | Use Case |
+|------|--------------|----------------|----------|
+| **Session Mode** | `WFS-xxx` | Source session summaries | Test validation for completed workflow |
+| **Prompt Mode** | Text or file path | Direct codebase analysis | Test generation from description |
+
+**Detection Logic**:
+```bash
+if [[ "$input" == WFS-* ]]; then
+  MODE="session"  # Use test-context-gather
+else
+  MODE="prompt"   # Use context-gather
+fi
+```
+
+### Core Principles
+
+- **Dual Input Support**: Accepts session ID (WFS-xxx) or feature description/file path
+- **Session Isolation**: Creates independent `WFS-test-[slug]` session
+- **Context-First**: Gathers implementation context via appropriate method
+- **Format Reuse**: Creates standard `IMPL-*.json` tasks with `meta.type: "test-fix"`
+- **Manual First**: Default to manual fixes, use `--use-codex` for automation
+- **Automatic Detection**: Input pattern determines execution mode
+
+### Coordinator Role
+
+This command is a **pure orchestrator**:
+- Does NOT analyze code directly
+- Does NOT generate tests or documentation
+- ONLY coordinates slash commands in sequence
+- Parses outputs to pass data between phases
+- Creates independent test workflow session
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+# Basic syntax
+/workflow:test-fix-gen [FLAGS] <INPUT>
+
+# Flags (optional)
+--use-codex        # Enable Codex automated fixes in IMPL-002
+--cli-execute      # Enable CLI execution in IMPL-001
+
+# Input
+<INPUT>            # Session ID, description, or file path
+```
+
+### Usage Examples
+
+#### Session Mode
+```bash
+# Test validation for completed implementation
+/workflow:test-fix-gen WFS-user-auth-v2
+
+# With automated fixes
+/workflow:test-fix-gen --use-codex WFS-api-endpoints
+
+# With CLI execution
+/workflow:test-fix-gen --cli-execute --use-codex WFS-payment-flow
+```
+
+#### Prompt Mode - Text Description
+```bash
+# Generate tests from feature description
+/workflow:test-fix-gen "Test the user authentication API endpoints in src/auth/api.ts"
+
+# With automated fixes
+/workflow:test-fix-gen --use-codex "Test user registration and login flows"
+```
+
+#### Prompt Mode - File Reference
+```bash
+# Generate tests from requirements file
+/workflow:test-fix-gen ./docs/api-requirements.md
+
+# With flags
+/workflow:test-fix-gen --use-codex --cli-execute ./specs/feature.md
+```
+
+### Mode Comparison
+
+| Aspect | Session Mode | Prompt Mode |
+|--------|-------------|-------------|
+| **Phase 1** | Create `WFS-test-[source]` with `source_session_id` | Create `WFS-test-[slug]` without `source_session_id` |
+| **Phase 2** | `/workflow:tools:test-context-gather` | `/workflow:tools:context-gather` |
+| **Phase 3-5** | Identical | Identical |
+| **Context** | Source session summaries + artifacts | Direct codebase analysis |
+
+---
+
+## Execution Flow
+
+### Core Execution Rules
+
+1. **Start Immediately**: First action is TodoWrite, second is Phase 1 session creation
+2. **No Preliminary Analysis**: Do not read files before Phase 1
+3. **Parse Every Output**: Extract required data from each phase for next phase
+4. **Sequential Execution**: Each phase depends on previous phase's output
+5. **Complete All Phases**: Do not return until Phase 5 completes
+6. **Track Progress**: Update TodoWrite after every phase
+7. **Automatic Detection**: Mode auto-detected from input pattern
+8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+
+### 5-Phase Execution
+
+#### Phase 1: Create Test Session
+
+**Command**:
+- **Session Mode**: `SlashCommand("/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
+- **Prompt Mode**: `SlashCommand("/workflow:session:start --new \"Test generation for: [description]\"")`
+
+**Input**: User argument (session ID, description, or file path)
+
+**Expected Behavior**:
+- Creates new session: `WFS-test-[slug]`
+- Writes `workflow-session.json` metadata:
+  - **Session Mode**: Includes `workflow_type: "test_session"`, `source_session_id: "[sourceId]"`
+  - **Prompt Mode**: Includes `workflow_type: "test_session"` only
+- Returns new session ID
+
+**Parse Output**:
+- Extract: `testSessionId` (pattern: `WFS-test-[slug]`)
+
+**Validation**:
+- **Session Mode**: Source session exists with completed IMPL tasks
+- **Both Modes**: New test session directory created with metadata
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+#### Phase 2: Gather Test Context
+
+**Command**:
+- **Session Mode**: `SlashCommand("/workflow:tools:test-context-gather --session [testSessionId]")`
+- **Prompt Mode**: `SlashCommand("/workflow:tools:context-gather --session [testSessionId] \"[task_description]\"")`
+
+**Input**: `testSessionId` from Phase 1
+
+**Expected Behavior**:
+- **Session Mode**:
+  - Load source session implementation context and summaries
+  - Analyze test coverage using MCP tools
+  - Identify files requiring tests
+- **Prompt Mode**:
+  - Analyze codebase based on description
+  - Identify relevant files and dependencies
+- Detect test framework and conventions
+- Generate context package JSON
+
+**Parse Output**:
+- Extract: `contextPath` (pattern: `.workflow/[testSessionId]/.process/[test-]context-package.json`)
+
+**Validation**:
+- Context package created with coverage analysis
+- Test framework detected
+- Test conventions documented
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+#### Phase 3: Test Generation Analysis
+
+**Command**: `SlashCommand("/workflow:tools:test-concept-enhanced --session [testSessionId] --context [contextPath]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `contextPath` from Phase 2
+
+**Expected Behavior**:
+- Use Gemini to analyze coverage gaps and implementation
+- Study existing test patterns and conventions
+- Generate test requirements for missing test files
+- Design test generation strategy
+- Generate `TEST_ANALYSIS_RESULTS.md`
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
+
+**Validation**:
+- TEST_ANALYSIS_RESULTS.md exists with complete sections:
+  - Coverage Assessment
+  - Test Framework & Conventions
+  - Test Requirements by File
+  - Test Generation Strategy
+  - Implementation Targets
+  - Success Criteria
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+---
+
+#### Phase 4: Generate Test Tasks
+
+**Command**: `SlashCommand("/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `--use-codex` flag (if present) - Controls IMPL-002 fix mode
+- `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
+
+**Expected Behavior**:
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
+- Generate **minimum 2 task JSON files** (expandable based on complexity):
+  - **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
+  - **IMPL-002.json**: Test Execution & Fix Cycle (`@test-fix-agent`)
+  - **IMPL-003+**: Additional tasks if needed for complex projects
+- Generate `IMPL_PLAN.md` with test strategy
+- Generate `TODO_LIST.md` with task checklist
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
+- Verify additional `.task/IMPL-*.json` if applicable
+- Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
+
+**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
+
+---
+
+#### Phase 5: Return Summary
+
+**Return to User**:
+```
+Independent test-fix workflow created successfully!
+
+Input: [original input]
+Mode: [Session|Prompt]
+Test Session: [testSessionId]
+
+Tasks Created:
+- IMPL-001: Test Understanding & Generation (@code-developer)
+- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+[- IMPL-003+: Additional tasks if applicable]
+
+Test Framework: [detected framework]
+Test Files to Generate: [count]
+Max Fix Iterations: 5
+Fix Mode: [Manual|Codex Automated]
+
+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]
+```
+
+**TodoWrite**: Mark phase 5 completed
+
+**Note**: Command completes here. Task execution requires separate workflow commands.
+
+---
+
+### TodoWrite Progress Tracking
+
+Track all 5 phases:
+
+```javascript
+TodoWrite({todos: [
+  {"content": "Create independent test session", "status": "in_progress|completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "pending|in_progress|completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending|in_progress|completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending|in_progress|completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending|in_progress|completed", "activeForm": "Returning workflow summary"}
+]})
+```
+
+Update status to `in_progress` when starting each phase, `completed` when done.
+
+---
+
+## Task Specifications
+
+Generates minimum 2 tasks (expandable for complex projects):
+
+### IMPL-001: Test Understanding & Generation
+
+**Agent**: `@code-developer`
+
+**Purpose**: Understand source implementation and generate test files
+
+**Task Configuration**:
+- Task ID: `IMPL-001`
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Understand source implementation and generate tests
+- `flow_control.target_files`: Test files to create from TEST_ANALYSIS_RESULTS.md section 5
+
+**Execution Flow**:
+1. **Understand Phase**:
+   - Load TEST_ANALYSIS_RESULTS.md and test context
+   - Understand source code implementation patterns
+   - Analyze test requirements and conventions
+   - Identify test scenarios and edge cases
+2. **Generation Phase**:
+   - Generate test files following existing patterns
+   - Ensure test coverage aligns with requirements
+3. **Verification Phase**:
+   - Verify test completeness and correctness
+
+### IMPL-002: Test Execution & Fix Cycle
+
+**Agent**: `@test-fix-agent`
+
+**Purpose**: Execute tests and apply iterative fixes (max 5 iterations)
+
+**Task Configuration**:
+- Task ID: `IMPL-002`
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex: true|false` (based on `--use-codex` flag)
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Execute and fix tests
+
+**Test-Fix Cycle Specification**:
+- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
+- **Tools Configuration**:
+  - Gemini for analysis with bug-fix template → surgical fix suggestions
+  - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
+- **Exit Conditions**:
+  - Success: All tests pass
+  - Failure: Max iterations reached (5)
+
+**Execution Flow**:
+1. **Phase 1**: Initial test execution
+2. **Phase 2**: Iterative Gemini diagnosis + manual/Codex fixes
+3. **Phase 3**: Final validation and certification
+
+### IMPL-003+: Additional Tasks (Optional)
+
+**Scenarios for Multiple Tasks**:
+- Large projects requiring per-module test generation
+- Separate integration vs unit test tasks
+- Specialized test types (performance, security, etc.)
+
+**Agent**: `@code-developer` or specialized agents based on requirements
+
+---
+
+## Artifacts & Output
+
+### Output Files Structure
+
+Created in `.workflow/WFS-test-[session]/`:
+
+```
+WFS-test-[session]/
+├── workflow-session.json          # Session metadata
+├── IMPL_PLAN.md                   # Test generation and execution strategy
+├── TODO_LIST.md                   # Task checklist
+├── .task/
+│   ├── IMPL-001.json              # Test understanding & generation
+│   ├── IMPL-002.json              # Test execution & fix cycle
+│   └── IMPL-*.json                # Additional tasks (if applicable)
+└── .process/
+    ├── [test-]context-package.json # Context and coverage analysis
+    └── TEST_ANALYSIS_RESULTS.md    # Test requirements and strategy
+```
+
+### Session Metadata
+
+**File**: `workflow-session.json`
+
+**Session Mode** includes:
+- `workflow_type: "test_session"`
+- `source_session_id: "[sourceSessionId]"` (enables automatic cross-session context)
+
+**Prompt Mode** includes:
+- `workflow_type: "test_session"`
+- No `source_session_id` field
+
+### Complete Data Flow
+
+**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
+
+**Phase Execution Chain**:
+1. Phase 1: `session-start` → `WFS-test-user-auth`
+2. Phase 2: `test-context-gather` → `test-context-package.json`
+3. Phase 3: `test-concept-enhanced` → `TEST_ANALYSIS_RESULTS.md`
+4. Phase 4: `test-task-generate` → `IMPL-001.json` + `IMPL-002.json` (+ additional if needed)
+5. Phase 5: Return summary
+
+**Command completes after Phase 5**
+
+---
+
+## Reference
+
+### Error Handling
+
+| Phase | Error Condition | Action |
+|-------|----------------|--------|
+| 1 | Source session not found (session mode) | Return error with source session ID |
+| 1 | No completed IMPL tasks (session mode) | Return error, source incomplete |
+| 2 | Context gathering failed | Return error, check source artifacts |
+| 3 | Gemini analysis failed | Return error, check context package |
+| 4 | Task generation failed | Retry once, then return error with details |
+
+### Best Practices
+
+1. **Before Running**:
+   - Ensure implementation is complete (session mode: check summaries exist)
+   - Commit all implementation changes
+   - Review source code quality
+
+2. **After Running**:
+   - Review generated `IMPL_PLAN.md` before execution
+   - Check `TEST_ANALYSIS_RESULTS.md` for completeness
+   - Verify task dependencies in `TODO_LIST.md`
+
+3. **During Execution**:
+   - Monitor iteration logs in `.process/fix-iteration-*`
+   - Track progress with `/workflow:status`
+   - Review Gemini diagnostic outputs
+
+4. **Mode Selection**:
+   - Use **Session Mode** for completed workflow validation
+   - Use **Prompt Mode** for ad-hoc test generation
+   - Use `--use-codex` for autonomous fix application
+   - Use `--cli-execute` for enhanced generation capabilities
+
+### Related Commands
+
+**Planning Phase**:
+- `/workflow:plan` - Create implementation workflow
+- `/workflow:session:start` - Initialize workflow session
+
+**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)
+
+**Analysis & Task Generation**:
+- `/workflow:tools:test-concept-enhanced` - Gemini test analysis (Phase 3)
+- `/workflow:tools:test-task-generate` - Generate test tasks (Phase 4)
+
+**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

@@ -24,16 +24,19 @@ 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.
+
 ## Core Rules
 
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 test session creation
 2. **No Preliminary Analysis**: Do not read files or analyze before Phase 1
 3. **Parse Every Output**: Extract required data from each phase for next phase
 4. **Sequential Execution**: Each phase depends on previous phase's output
-5. **Complete All Phases**: Do not return to user until Phase 4 completes (execution triggered separately)
+5. **Complete All Phases**: Do not return to user until Phase 5 completes (summary returned)
 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.
 
 ## 5-Phase Execution
 
@@ -174,32 +177,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ---
 
-### Phase 5: Return Summary to User
+### 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.
 
 **Return to User**:
 ```
-Independent test-fix workflow created successfully!
+✅ Test workflow preparation complete!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
 
-Tasks Created:
-- IMPL-001: Test Generation (@code-developer)
-- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+Artifacts Created:
+- Test context analysis
+- Test generation strategy
+- Task definitions (IMPL-001, IMPL-002)
+- Implementation plan
 
 Test Framework: [detected framework]
 Test Files to Generate: [count]
-Max Fix Iterations: 5
 Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
-Next Steps:
-1. Review test plan: .workflow/[testSessionId]/IMPL_PLAN.md
-2. Execute workflow: /workflow:execute
-3. Monitor progress: /workflow:status
+📋 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.
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
+**⚠️ Command Boundary**: After this phase, the command terminates and returns to user prompt.
+
 ---
 
 ## TodoWrite Pattern
@@ -221,19 +231,32 @@ Update status to `in_progress` when starting each phase, mark `completed` when d
 ## Data Flow
 
 ```
-/workflow:test-gen WFS-user-auth
-  ↓
-Phase 1: session-start → WFS-test-user-auth
-  ↓
-Phase 2: test-context-gather → test-context-package.json
-  ↓
-Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md
-  ↓
-Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json
-  ↓
-Phase 5: Return summary
-  ↓
-/workflow:execute → IMPL-001 (@code-developer) → IMPL-002 (@test-fix-agent)
+┌─────────────────────────────────────────────────────────┐
+│ /workflow:test-gen WFS-user-auth                        │
+├─────────────────────────────────────────────────────────┤
+│ Phase 1: session-start → WFS-test-user-auth            │
+│   ↓                                                     │
+│ Phase 2: test-context-gather → test-context-package.json│
+│   ↓                                                     │
+│ Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md│
+│   ↓                                                     │
+│ Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json│
+│   ↓                                                     │
+│ Phase 5: Return summary                                │
+└─────────────────────────────────────────────────────────┘
+         ⚠️ COMMAND ENDS - Control returns to user
+
+Artifacts Created:
+├── .workflow/WFS-test-[session]/
+│   ├── workflow-session.json
+│   ├── IMPL_PLAN.md
+│   ├── TODO_LIST.md
+│   ├── .task/
+│   │   ├── IMPL-001.json (test generation task)
+│   │   └── IMPL-002.json (test execution task)
+│   └── .process/
+│       ├── test-context-package.json
+│       └── TEST_ANALYSIS_RESULTS.md
 ```
 
 ## Session Metadata
@@ -242,9 +265,16 @@ Test session includes `workflow_type: "test_session"` and `source_session_id` fo
 
 ## Task Output
 
-Generates two tasks:
-- **IMPL-001** (@code-developer): Test generation from TEST_ANALYSIS_RESULTS.md
-- **IMPL-002** (@test-fix-agent): Test execution with iterative fix cycle (max 5 iterations)
+Generates two task definition files:
+- **IMPL-001.json**: Test generation task specification
+  - Agent: @code-developer
+  - Input: TEST_ANALYSIS_RESULTS.md
+  - Output: Test files based on analysis
+- **IMPL-002.json**: Test execution and fix cycle specification
+  - Agent: @test-fix-agent
+  - Dependency: IMPL-001 must complete first
+  - Max iterations: 5
+  - Fix mode: Manual or Codex (based on --use-codex flag)
 
 See `/workflow:tools:test-task-generate` for complete task JSON schemas.
 
@@ -269,28 +299,34 @@ Created in `.workflow/WFS-test-[session]/`:
 - `IMPL_PLAN.md` - Test plan
 - `TODO_LIST.md` - Task checklist
 
-## Agent Execution
+## Task Specifications
 
-**IMPL-001** (@code-developer):
-- Generates test files based on TEST_ANALYSIS_RESULTS.md
-- Follows existing test patterns and conventions
+**IMPL-001.json Structure**:
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
+- `flow_control.target_files`: Test files to create
+- `flow_control.implementation_approach`: Test generation strategy
 
-**IMPL-002** (@test-fix-agent):
-1. Run test suite
-2. Iterative fix cycle (max 5):
-   - Gemini diagnosis with bug-fix template → surgical fix suggestions
-   - Manual fix application (default) OR Codex applies fixes if --use-codex flag (resume mechanism)
-   - Retest and check regressions
-3. Final validation and certification
+**IMPL-002.json Structure**:
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex`: true/false (based on --use-codex flag)
+- `context.depends_on: ["IMPL-001"]`
+- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
+  - Gemini diagnosis template
+  - Fix application mode (manual/codex)
+  - Max iterations: 5
+- `flow_control.implementation_approach.modification_points`: 3-phase flow
 
-See `/workflow:tools:test-task-generate` for detailed specifications.
+See `/workflow:tools:test-task-generate` for complete JSON schemas.
 
 ## Best Practices
 
-1. Run after implementation complete (ensure source session has summaries)
-2. Commit implementation changes before test-gen
-3. Monitor execution with `/workflow:status`
-4. Review iteration logs in `.process/fix-iteration-*`
+1. **Prerequisites**: Ensure source session has completed IMPL tasks with summaries
+2. **Clean State**: Commit implementation changes before running test-gen
+3. **Review Artifacts**: Check generated IMPL_PLAN.md and TODO_LIST.md before proceeding
+4. **Understand Scope**: This command only prepares artifacts; it does not execute tests
 
 ## Related Commands
 

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

@@ -10,521 +10,218 @@ examples:
 # Enhanced Analysis Command (/workflow:tools:concept-enhanced)
 
 ## Overview
-Advanced solution design and feasibility analysis engine with parallel CLI execution that processes standardized context packages and produces comprehensive technical analysis focused on solution improvements, key design decisions, and critical insights.
+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.
 
-**Analysis Focus**: Produces ANALYSIS_RESULTS.md with solution design, architectural rationale, feasibility assessment, and optimization strategies. Does NOT generate task breakdowns or implementation plans.
+**Scope**: Solution-focused technical analysis only. Does NOT generate task breakdowns or implementation plans.
 
-**Independent Usage**: This command can be called directly by users or as part of the `/workflow:plan` command. It accepts context packages and provides solution-focused technical analysis.
+**Usage**: Standalone command or integrated into `/workflow:plan`. Accepts context packages and orchestrates Gemini/Codex for comprehensive analysis.
 
-## Core Philosophy
-- **Solution-Focused**: Emphasize design decisions, architectural rationale, and critical insights
-- **Context-Driven**: Precise analysis based on comprehensive context packages
-- **Intelligent Tool Selection**: Choose optimal tools based on task complexity (Gemini for design, Codex for validation)
-- **Parallel Execution**: Execute multiple CLI tools simultaneously for efficiency
-- **No Task Planning**: Exclude implementation steps, task breakdowns, and project planning
+## 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
 
-## Core Responsibilities
-- **Context Package Parsing**: Read and validate context-package.json
-- **Parallel CLI Orchestration**: Execute Gemini (solution design) and optionally Codex (feasibility validation)
-- **Solution Design Analysis**: Evaluate architecture, identify key design decisions with rationale
-- **Feasibility Assessment**: Analyze technical complexity, risks, and implementation readiness
-- **Optimization Recommendations**: Propose performance, security, and code quality improvements
-- **Perspective Synthesis**: Integrate Gemini and Codex insights into unified solution assessment
-- **Technical Analysis Report**: Generate ANALYSIS_RESULTS.md focused on design decisions and critical insights (NO task planning)
-
 ## Analysis Strategy Selection
 
-### Tool Selection by Task Complexity
+**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)
 
-**Simple Tasks (≤3 modules)**:
-- **Primary Tool**: Gemini (rapid understanding and pattern recognition)
-- **Support Tool**: Code-index (structural analysis)
-- **Execution Mode**: Single-round analysis, focus on existing patterns
-
-**Medium Tasks (4-6 modules)**:
-- **Primary Tool**: Gemini (comprehensive single-round analysis and architecture design)
-- **Support Tools**: Code-index + Exa (external best practices)
-- **Execution Mode**: Single comprehensive analysis covering understanding + architecture design
-
-**Complex Tasks (>6 modules)**:
-- **Primary Tools**: Gemini (single comprehensive analysis) + Codex (implementation validation)
-- **Analysis Strategy**: Gemini handles understanding + architecture in one round, Codex validates implementation
-- **Execution Mode**: Parallel execution - Gemini comprehensive analysis + Codex validation
-
-### Tool Preferences by Tech Stack
-
-```json
-{
-  "frontend": {
-    "primary": "gemini",
-    "secondary": "codex",
-    "focus": ["component_design", "state_management", "ui_patterns"]
-  },
-  "backend": {
-    "primary": "codex",
-    "secondary": "gemini",
-    "focus": ["api_design", "data_flow", "security", "performance"]
-  },
-  "fullstack": {
-    "primary": "gemini",
-    "secondary": "codex",
-    "focus": ["system_architecture", "integration", "data_consistency"]
-  }
-}
-```
+**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 session directory exists: `.workflow/{session_id}/`
-   - Load session metadata from `workflow-session.json`
-   - Validate session state and task context
+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
 
-2. **Context Package Validation**
-   - Verify context package exists at specified path
-   - Validate JSON format and structure
-   - Assess context package size and complexity
+### Phase 2: Agent-Delegated Analysis
 
-3. **Task Analysis & Classification**
-   - Parse task description and extract keywords
-   - Identify technical domain and complexity level
-   - Determine required analysis depth and scope
-   - Load existing session context and task summaries
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Enhanced solution design and feasibility analysis",
+  prompt=`
+## Execution Context
 
-4. **Tool Selection Strategy**
-   - **Simple/Medium Tasks**: Single Gemini comprehensive analysis
-   - **Complex Tasks**: Gemini comprehensive + Codex validation
-   - Load appropriate prompt templates and configurations
+**Session ID**: {session_id}
+**Mode**: Enhanced Analysis with CLI Tool Orchestration
 
-### Phase 2: Analysis Preparation
-1. **Workspace Setup**
-   - Create analysis output directory: `.workflow/{session_id}/.process/`
-   - Initialize log files and monitoring structures
-   - Set process limits and resource management
+## Input Context
 
-2. **Context Optimization**
-   - Filter high-priority assets from context package
-   - Organize project structure and dependencies
-   - Prepare template references and rule configurations
+**Context Package**: {context_path}
+**Session State**: .workflow/{session_id}/workflow-session.json
+**Project Standards**: CLAUDE.md
 
-3. **Execution Environment**
-   - Configure CLI tools with write permissions
-   - Set timeout parameters and monitoring intervals
-   - Prepare error handling and recovery mechanisms
+## Analysis Task
 
-### Phase 3: Parallel Analysis Execution
-1. **Gemini Solution Design & Architecture Analysis**
-   - **Tool Configuration**:
-     ```bash
-     ~/.claude/scripts/gemini-wrapper -p "
-     PURPOSE: Analyze and design optimal solution for {task_description}
-     TASK: Evaluate current architecture, propose solution design, and identify key design decisions
-     CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
+### 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
 
-     **MANDATORY FIRST STEP**: Read and analyze .workflow/{session_id}/.process/context-package.json to understand:
-     - Task requirements from metadata.task_description
-     - Relevant source files from assets[] array
-     - Tech stack from tech_stack section
-     - Project structure from statistics section
+### 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
 
-     **ANALYSIS PRIORITY - Use ALL source documents from context-package assets[]**:
-     1. PRIMARY SOURCES (Highest Priority): Individual role analysis.md files (system-architect, ui-designer, product-manager, etc.)
-        - These contain complete technical details, design rationale, ADRs, and decision context
-        - Extract: Technical specs, API schemas, design tokens, caching configs, performance metrics
-     2. SYNTHESIS REFERENCE (Medium Priority): synthesis-specification.md
-        - Use for integrated requirements and cross-role alignment
-        - Validate decisions and identify integration points
-     3. TOPIC FRAMEWORK (Low Priority): topic-framework.md for discussion context
+### Output Requirements
 
-     EXPECTED:
-     1. CURRENT STATE ANALYSIS: Existing patterns, code structure, integration points, technical debt
-     2. SOLUTION DESIGN: Core architecture principles, system design, key design decisions with rationale
-     3. CRITICAL INSIGHTS: What works well, identified gaps, technical risks, architectural tradeoffs
-     4. OPTIMIZATION STRATEGIES: Performance improvements, security enhancements, code quality recommendations
-     5. FEASIBILITY ASSESSMENT: Complexity analysis, compatibility evaluation, implementation readiness
-     6. **OUTPUT FILE**: Write complete analysis to .workflow/{session_id}/.process/gemini-solution-design.md
+**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)
 
-     RULES:
-     - Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, NOT task planning
-     - Provide architectural rationale, evaluate alternatives, assess tradeoffs
-     - **CRITICAL**: Identify code targets - existing files as "file:function:lines", new files as "file"
-     - For modifications: specify exact files/functions/line ranges
-     - For new files: specify file path only (no function or lines)
-     - Do NOT create task lists, implementation steps, or code examples
-     - Do NOT generate any code snippets or implementation details
-     - **MUST write output to .workflow/{session_id}/.process/gemini-solution-design.md**
-     - Output ONLY architectural analysis and design recommendations
-     " --approval-mode yolo
-     ```
-   - **Output Location**: `.workflow/{session_id}/.process/gemini-solution-design.md`
+**Final Output**:
+- \`.workflow/{session_id}/.process/ANALYSIS_RESULTS.md\` (synthesized, required)
 
-2. **Codex Technical Feasibility Validation** (Complex Tasks Only)
-   - **Tool Configuration**:
-     ```bash
-     codex --full-auto exec "
-     PURPOSE: Validate technical feasibility and identify implementation risks for {task_description}
-     TASK: Assess implementation complexity, validate technology choices, evaluate performance and security implications
-     CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/.process/gemini-solution-design.md,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
+**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
 
-     **MANDATORY FIRST STEP**: Read and analyze:
-     - .workflow/{session_id}/.process/context-package.json for task context
-     - .workflow/{session_id}/.process/gemini-solution-design.md for proposed solution design
-     - Relevant source files listed in context-package.json assets[]
+### 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
 
-     EXPECTED:
-     1. FEASIBILITY ASSESSMENT: Technical complexity rating, resource requirements, technology compatibility
-     2. RISK ANALYSIS: Implementation risks, integration challenges, performance concerns, security vulnerabilities
-     3. TECHNICAL VALIDATION: Development approach validation, quality standards assessment, maintenance implications
-     4. CRITICAL RECOMMENDATIONS: Must-have requirements, optimization opportunities, security controls
-     5. **OUTPUT FILE**: Write validation results to .workflow/{session_id}/.process/codex-feasibility-validation.md
+## 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
+`
+)
+```
 
-     RULES:
-     - Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, NOT implementation planning
-     - Validate architectural decisions, identify potential issues, recommend optimizations
-     - **CRITICAL**: Verify code targets - existing files "file:function:lines", new files "file"
-     - Confirm exact locations for modifications, identify additional new files if needed
-     - Do NOT create task breakdowns, step-by-step guides, or code examples
-     - Do NOT generate any code snippets or implementation details
-     - **MUST write output to .workflow/{session_id}/.process/codex-feasibility-validation.md**
-     - Output ONLY feasibility analysis and risk assessment
-     " --skip-git-repo-check -s danger-full-access
-     ```
-   - **Output Location**: `.workflow/{session_id}/.process/codex-feasibility-validation.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
 
-3. **Parallel Execution Management**
-   - Launch both tools simultaneously for complex tasks
-   - Monitor execution progress with timeout controls
-   - Handle process completion and error scenarios
-   - Maintain execution logs for debugging and recovery
+**Command Execution**: Launch agent via Task tool, wait for completion
 
-### Phase 4: Results Collection & Synthesis
-1. **Output Validation & Collection**
-   - **Gemini Results**: Validate `gemini-solution-design.md` contains complete solution analysis
-   - **Codex Results**: For complex tasks, validate `codex-feasibility-validation.md` with technical assessment
-   - **Fallback Processing**: Use execution logs if primary outputs are incomplete
-   - **Status Classification**: Mark each tool as completed, partial, failed, or skipped
-
-2. **Quality Assessment**
-   - **Design Quality**: Verify architectural decisions have clear rationale and alternatives analysis
-   - **Insight Depth**: Assess quality of critical insights and risk identification
-   - **Feasibility Rigor**: Validate completeness of technical feasibility assessment
-   - **Optimization Value**: Check actionability of optimization recommendations
-
-3. **Analysis Synthesis Strategy**
-   - **Simple/Medium Tasks**: Direct integration of Gemini solution design
-   - **Complex Tasks**: Synthesis of Gemini design with Codex feasibility validation
-   - **Conflict Resolution**: Identify architectural disagreements and provide balanced resolution
-   - **Confidence Scoring**: Assess overall solution confidence based on multi-tool consensus
-
-### Phase 5: ANALYSIS_RESULTS.md Generation
-1. **Structured Report Assembly**
-   - **Executive Summary**: Analysis focus, overall assessment, recommendation status
-   - **Current State Analysis**: Architecture overview, compatibility, critical findings
-   - **Proposed Solution Design**: Core principles, system design, key design decisions with rationale
-   - **Implementation Strategy**: Development approach, feasibility assessment, risk mitigation
-   - **Solution Optimization**: Performance, security, code quality recommendations
-   - **Critical Success Factors**: Technical requirements, quality metrics, success validation
-   - **Confidence & Recommendations**: Assessment scores, final recommendation with rationale
-
-2. **Report Generation Guidelines**
-   - **Focus**: Solution improvements, key design decisions, critical insights
-   - **Exclude**: Task breakdowns, implementation steps, project planning
-   - **Emphasize**: Architectural rationale, tradeoff analysis, risk assessment
-   - **Structure**: Clear sections with decision justification and feasibility scoring
-
-3. **Final Output**
-   - **Primary Output**: `ANALYSIS_RESULTS.md` - comprehensive solution design and technical analysis
-   - **Single File Policy**: Only generate ANALYSIS_RESULTS.md, no supplementary files
-   - **Report Location**: `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
-   - **Content Focus**: Technical insights, design decisions, optimization strategies
+### 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
 
-Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning):
+**Template Reference**: `~/.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt`
 
-```markdown
-# Technical Analysis & Solution Design
+Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning).
 
-## Executive Summary
-- **Analysis Focus**: {core_problem_or_improvement_area}
-- **Analysis Timestamp**: {timestamp}
-- **Tools Used**: {analysis_tools}
-- **Overall Assessment**: {feasibility_score}/5 - {recommendation_status}
+### 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
 
-## 1. Current State Analysis
+### Key Requirements
 
-### Architecture Overview
-- **Existing Patterns**: {key_architectural_patterns}
-- **Code Structure**: {current_codebase_organization}
-- **Integration Points**: {system_integration_touchpoints}
-- **Technical Debt Areas**: {identified_debt_with_impact}
+**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:*`
 
-### Compatibility & Dependencies
-- **Framework Alignment**: {framework_compatibility_assessment}
-- **Dependency Analysis**: {critical_dependencies_and_risks}
-- **Migration Considerations**: {backward_compatibility_concerns}
+**Key Design Decisions** (minimum 2):
+- Decision statement
+- Rationale (why this approach)
+- Alternatives considered (tradeoffs)
+- Impact (implications on architecture)
 
-### Critical Findings
-- **Strengths**: {what_works_well}
-- **Gaps**: {missing_capabilities_or_issues}
-- **Risks**: {identified_technical_and_business_risks}
+**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
 
-## 2. Proposed Solution Design
+## Execution Management
 
-### Core Architecture Principles
-- **Design Philosophy**: {key_design_principles}
-- **Architectural Approach**: {chosen_architectural_pattern_with_rationale}
-- **Scalability Strategy**: {how_solution_scales}
+### 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
 
-### System Design
-- **Component Architecture**: {high_level_component_design}
-- **Data Flow**: {data_flow_patterns_and_state_management}
-- **API Design**: {interface_contracts_and_specifications}
-- **Integration Strategy**: {how_components_integrate}
+### 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/`
 
-### Key Design Decisions
-1. **Decision**: {critical_design_choice}
-   - **Rationale**: {why_this_approach}
-   - **Alternatives Considered**: {other_options_and_tradeoffs}
-   - **Impact**: {implications_on_architecture}
+## Integration & Success Criteria
 
-2. **Decision**: {another_critical_choice}
-   - **Rationale**: {reasoning}
-   - **Alternatives Considered**: {tradeoffs}
-   - **Impact**: {consequences}
+### Input/Output Interface
+**Input**:
+- `--session` (required): Session ID (e.g., WFS-auth)
+- `--context` (required): Context package path
 
-### Technical Specifications
-- **Technology Stack**: {chosen_technologies_with_justification}
-- **Code Organization**: {module_structure_and_patterns}
-- **Testing Strategy**: {testing_approach_and_coverage}
-- **Performance Targets**: {performance_requirements_and_benchmarks}
+**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
 
-## 3. Implementation Strategy
-
-### Development Approach
-- **Core Implementation Pattern**: {primary_implementation_strategy}
-- **Module Dependencies**: {dependency_graph_and_order}
-- **Quality Assurance**: {qa_approach_and_validation}
-
-### Code Modification Targets
-**Purpose**: Specific code locations for modification AND new files to create
-
-**Format**:
-- Existing files: `file:function:lines` (with line numbers)
-- New files: `file` (no function or lines)
-
-**Identified Targets**:
-1. **Target**: `src/auth/AuthService.ts:login:45-52`
-   - **Type**: Modify existing
-   - **Modification**: Enhance error handling
-   - **Rationale**: Current logic lacks validation for edge cases
-
-2. **Target**: `src/auth/PasswordReset.ts`
-   - **Type**: Create new file
-   - **Purpose**: Password reset functionality
-   - **Rationale**: New feature requirement
-
-3. **Target**: `src/middleware/auth.ts:validateToken:30-45`
-   - **Type**: Modify existing
-   - **Modification**: Add token expiry check
-   - **Rationale**: Security requirement for JWT validation
-
-4. **Target**: `tests/auth/PasswordReset.test.ts`
-   - **Type**: Create new file
-   - **Purpose**: Test coverage for password reset
-   - **Rationale**: Test requirement for new feature
-
-**Note**:
-- For new files, only specify the file path (no function or lines)
-- For existing files without line numbers, use `file:function:*` format
-- Task generation will refine these during the `analyze_task_patterns` step
-
-### Feasibility Assessment
-- **Technical Complexity**: {complexity_rating_and_analysis}
-- **Performance Impact**: {expected_performance_characteristics}
-- **Resource Requirements**: {development_resources_needed}
-- **Maintenance Burden**: {ongoing_maintenance_considerations}
-
-### Risk Mitigation
-- **Technical Risks**: {implementation_risks_and_mitigation}
-- **Integration Risks**: {compatibility_challenges_and_solutions}
-- **Performance Risks**: {performance_concerns_and_strategies}
-- **Security Risks**: {security_vulnerabilities_and_controls}
-
----
-
-## 4. Solution Optimization
-
-### Performance Optimization
-- **Optimization Strategies**: {key_performance_improvements}
-- **Caching Strategy**: {caching_approach_and_invalidation}
-- **Resource Management**: {resource_utilization_optimization}
-- **Bottleneck Mitigation**: {identified_bottlenecks_and_solutions}
-
-### Security Enhancements
-- **Security Model**: {authentication_authorization_approach}
-- **Data Protection**: {data_security_and_encryption}
-- **Vulnerability Mitigation**: {known_vulnerabilities_and_controls}
-- **Compliance**: {regulatory_and_compliance_considerations}
-
-### Code Quality
-- **Code Standards**: {coding_conventions_and_patterns}
-- **Testing Coverage**: {test_strategy_and_coverage_goals}
-- **Documentation**: {documentation_requirements}
-- **Maintainability**: {maintainability_practices}
-
----
-
-## 5. Critical Success Factors
-
-### Technical Requirements
-- **Must Have**: {essential_technical_capabilities}
-- **Should Have**: {important_but_not_critical_features}
-- **Nice to Have**: {optional_enhancements}
-
-### Quality Metrics
-- **Performance Benchmarks**: {measurable_performance_targets}
-- **Code Quality Standards**: {quality_metrics_and_thresholds}
-- **Test Coverage Goals**: {testing_coverage_requirements}
-- **Security Standards**: {security_compliance_requirements}
-
-### Success Validation
-- **Acceptance Criteria**: {how_to_validate_success}
-- **Testing Strategy**: {validation_testing_approach}
-- **Monitoring Plan**: {production_monitoring_strategy}
-- **Rollback Plan**: {failure_recovery_strategy}
-
----
-
-## 6. Analysis Confidence & Recommendations
-
-### Assessment Scores
-- **Conceptual Integrity**: {score}/5 - {brief_assessment}
-- **Architectural Soundness**: {score}/5 - {brief_assessment}
-- **Technical Feasibility**: {score}/5 - {brief_assessment}
-- **Implementation Readiness**: {score}/5 - {brief_assessment}
-- **Overall Confidence**: {overall_score}/5
-
-### Final Recommendation
-**Status**: {PROCEED|PROCEED_WITH_MODIFICATIONS|RECONSIDER|REJECT}
-
-**Rationale**: {clear_explanation_of_recommendation}
-
-**Critical Prerequisites**: {what_must_be_resolved_before_proceeding}
-
----
-
-## 7. Reference Information
-
-### Tool Analysis Summary
-- **Gemini Insights**: {key_architectural_and_pattern_insights}
-- **Codex Validation**: {technical_feasibility_and_implementation_notes}
-- **Consensus Points**: {agreements_between_tools}
-- **Conflicting Views**: {disagreements_and_resolution}
-
-### Context & Resources
-- **Analysis Context**: {context_package_reference}
-- **Documentation References**: {relevant_documentation}
-- **Related Patterns**: {similar_implementations_in_codebase}
-- **External Resources**: {external_references_and_best_practices}
-```
-
-## Error Handling & Fallbacks
-
-### Error Handling & Recovery Strategies
-
-1. **Pre-execution Validation**
-   - **Session Verification**: Ensure session directory and metadata exist
-   - **Context Package Validation**: Verify JSON format and content structure
-   - **Tool Availability**: Confirm CLI tools are accessible and configured
-   - **Prerequisite Checks**: Validate all required dependencies and permissions
-
-2. **Execution Monitoring & Timeout Management**
-   - **Progress Monitoring**: Track analysis execution with regular status checks
-   - **Timeout Controls**: 30-minute execution limit with graceful termination
-   - **Process Management**: Handle parallel tool execution and resource limits
-   - **Status Tracking**: Maintain real-time execution state and completion status
-
-3. **Partial Results Recovery**
-   - **Fallback Strategy**: Generate analysis results even with incomplete outputs
-   - **Log Integration**: Use execution logs when primary outputs are unavailable
-   - **Recovery Mode**: Create partial analysis reports with available data
-   - **Guidance Generation**: Provide next steps and retry recommendations
-
-4. **Resource Management**
-   - **Disk Space Monitoring**: Check available storage and cleanup temporary files
-   - **Process Limits**: Set CPU and memory constraints for analysis execution
-   - **Performance Optimization**: Manage resource utilization and system load
-   - **Cleanup Procedures**: Remove outdated logs and temporary files
-
-5. **Comprehensive Error Recovery**
-   - **Error Detection**: Automatic error identification and classification
-   - **Recovery Workflows**: Structured approach to handling different failure modes
-   - **Status Reporting**: Clear communication of issues and resolution attempts
-   - **Graceful Degradation**: Provide useful outputs even with partial failures
-
-## Performance Optimization
-
-### Analysis Optimization Strategies
-- **Parallel Analysis**: Execute multiple tools in parallel to reduce total time
-- **Context Sharding**: Analyze large projects by module shards
-- **Caching Mechanism**: Reuse analysis results for similar contexts
-- **Incremental Analysis**: Perform incremental analysis based on changes
-
-### Resource Management
-```bash
-# Set analysis timeout
-timeout 600s analysis_command || {
-  echo "⚠️ Analysis timeout, generating partial results"
-  # Generate partial results
-}
-
-# Memory usage monitoring
-memory_usage=$(ps -o pid,vsz,rss,comm -p $$)
-if [ "$memory_usage" -gt "$memory_limit" ]; then
-  echo "⚠️ High memory usage detected, optimizing..."
-fi
-```
-
-## Integration Points
-
-### Input Interface
-- **Required**: `--session` parameter specifying session ID (e.g., WFS-auth)
-- **Required**: `--context` parameter specifying context package path
-- **Optional**: `--depth` specify analysis depth (quick|full|deep)
-- **Optional**: `--focus` specify analysis focus areas
-
-### Output Interface
-- **Primary**: ANALYSIS_RESULTS.md - solution design and technical analysis
-- **Location**: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
-- **Single Output Policy**: Only ANALYSIS_RESULTS.md is generated
-- **No Supplementary Files**: No additional JSON, roadmap, or template files
-
-## Quality Assurance
-
-### Analysis Quality Checks
-- **Completeness Check**: Ensure all required analysis sections are completed
-- **Consistency Check**: Verify consistency of multi-tool analysis results
-- **Feasibility Validation**: Ensure recommended implementation plans are feasible
-
-### Success Criteria
-- ✅ **Solution-Focused Analysis**: ANALYSIS_RESULTS.md emphasizes solution improvements, design decisions, and critical insights
-- ✅ **Single Output File**: Only ANALYSIS_RESULTS.md generated, no supplementary files
-- ✅ **Design Decision Depth**: Clear rationale for architectural choices with alternatives and tradeoffs
-- ✅ **Feasibility Assessment**: Technical complexity, risk analysis, and implementation readiness evaluation
-- ✅ **Optimization Strategies**: Performance, security, and code quality recommendations
-- ✅ **Parallel Execution**: Efficient concurrent tool execution (Gemini + Codex for complex tasks)
-- ✅ **Robust Error Handling**: Comprehensive validation, timeout management, and partial result recovery
-- ✅ **Confidence Scoring**: Multi-dimensional assessment with clear recommendation status
-- ✅ **No Task Planning**: Exclude task breakdowns, implementation steps, and project planning details
+**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

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

@@ -1,6 +1,6 @@
 ---
 name: gather
-description: Intelligently collect project context based on task description and package into standardized JSON
+description: Intelligently collect project context using general-purpose agent based on task description and package into standardized JSON
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
@@ -11,25 +11,105 @@ examples:
 # Context Gather Command (/workflow:tools:context-gather)
 
 ## Overview
-Intelligent context collector that gathers relevant information from project codebase, documentation, and dependencies based on task descriptions, generating standardized context packages.
+Agent-driven intelligent context collector that gathers relevant information from project codebase, documentation, and dependencies based on task descriptions, generating standardized context packages.
 
 ## 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
-- **Efficient Execution**: Optimize collection strategies to avoid irrelevant information
 
-## Core Responsibilities
-- **Keyword Extraction**: Extract core keywords from task descriptions
-- **Smart Documentation Loading**: Load relevant project documentation based on keywords
-- **Code Structure Analysis**: Analyze project structure to locate relevant code files
-- **Dependency Discovery**: Identify tech stack and dependency relationships
-- **MCP Tools Integration**: Leverage code-index tools for enhanced collection
-- **Context Packaging**: Generate standardized JSON context packages
+## Execution Lifecycle
 
-## Execution Process
+### Phase 1: Discovery & Context Loading
+**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
 
-### Phase 1: Task Analysis
+**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
+  }
+}
+
+// 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)
+   }
+   ```
+
+### Phase 2: Agent Execution (Context Gathering & Packaging)
+
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="general-purpose",
+  description="Gather project context and generate context package",
+  prompt=`
+## Execution Context
+
+**Session ID**: WFS-{session-id}
+**Task Description**: {task_description}
+**Mode**: Agent-Driven Context Gathering
+
+## Phase 1: Discovery Results (Provided Context)
+
+### Session Metadata
+{session_metadata_content}
+
+### MCP Capabilities
+- code-index: Available for file discovery and code search
+- exa-code: Available for external research
+- exa-web: Available for web search
+
+## Phase 2: Context Gathering Task
+
+### 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
+
+### Execution Process
+
+#### 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.)
@@ -40,23 +120,31 @@ Intelligent context collector that gathers relevant information from project cod
    - Identify potentially involved modules and components
    - Set file type filters
 
-### Phase 2: Project Structure Exploration
-1. **Architecture Analysis**
-   - Use `~/.claude/scripts/get_modules_by_depth.sh` for comprehensive project structure
-   - Analyze project layout and module organization
-   - Identify key directories and components
+#### 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}*")
 
-2. **Code File Location**
-   - Use MCP tools for precise search: `mcp__code-index__find_files()` and `mcp__code-index__search_code_advanced()`
-   - Search for relevant source code files based on keywords
-   - Locate implementation files, interfaces, and modules
+   // Search code content
+   mcp__code-index__search_code_advanced(
+     pattern="{keyword_patterns}",
+     file_pattern="*.{ts,js,py,go,md}",
+     context_lines=3
+   )
 
-3. **Documentation Collection**
-   - Load CLAUDE.md and README.md
-   - Load relevant documentation from .workflow/docs/ based on keywords
-   - Collect configuration files (package.json, requirements.txt, etc.)
+   // Get file summaries
+   mcp__code-index__get_file_summary(file_path="relevant/file.ts")
+   \`\`\`
 
-### Phase 3: Intelligent Filtering & Association
+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
@@ -67,17 +155,15 @@ Intelligent context collector that gathers relevant information from project cod
    - Identify inter-module dependencies
    - Determine core and optional dependencies
 
-### Phase 4: Context Packaging
-1. **Standardized Output**
-   - Generate context-package.json
-   - Organize resources by type and importance
-   - Add relevance descriptions and usage recommendations
+#### Step 4: Context Packaging
+Generate standardized context-package.json following the format below
 
-## Context Package Format
+### Required Output
 
-Generated context package format:
+**Output Location**: \`.workflow/{session-id}/.process/context-package.json\`
 
-```json
+**Output Format**:
+\`\`\`json
 {
   "metadata": {
     "task_description": "Implement user authentication system",
@@ -138,163 +224,130 @@ Generated context package format:
     "test_files": 1
   }
 }
-```
+\`\`\`
 
-## MCP Tools Integration
+### Quality Validation
 
-### Code Index Integration
-```bash
-# Set project path
+Before completion, verify:
+- [ ] context-package.json created in correct location
+- [ ] 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
+
+### 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 to ensure latest
+// Refresh index
 mcp__code-index__refresh_index()
 
-# Search relevant files
+// Find files by pattern
 mcp__code-index__find_files(pattern="*{keyword}*")
 
-# Search code content
+// Search code content
 mcp__code-index__search_code_advanced(
   pattern="{keyword_patterns}",
   file_pattern="*.{ts,js,py,go,md}",
   context_lines=3
 )
+\`\`\`
+
+**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
+
+**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]",
+
+  // 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),
+
+  // MCP capabilities - agent will use these tools
+  mcp_capabilities: {
+    code_index: true,
+    exa_code: true,
+    exa_web: true
+  }
+}
+
+// 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
 
 ### Session ID Usage
 - **Required Parameter**: `--session WFS-session-id`
-- **Session Context Loading**: Load existing session state and task summaries
-- **Session Continuity**: Maintain context across pipeline phases
+- **Session Context Loading**: Load existing session state and metadata
+- **Session Continuity**: Maintain context across workflow pipeline phases
 
-### Session State Management
-```bash
-# Validate session exists
-if [ ! -d ".workflow/${session_id}" ]; then
-  echo "❌ Session ${session_id} not found"
-  exit 1
-fi
-
-# Load session metadata
-session_metadata=".workflow/${session_id}/workflow-session.json"
-```
-
-## Output Location
-
-Context package output location:
-```
-.workflow/{session_id}/.process/context-package.json
-```
-
-## Error Handling
-
-### Common Error Handling
-1. **No Active Session**: Create temporary session directory
-2. **MCP Tools Unavailable**: Fallback to traditional bash commands
-3. **Permission Errors**: Prompt user to check file permissions
-4. **Large Project Optimization**: Limit file count, prioritize high-relevance files
-
-### Graceful Degradation Strategy
-```bash
-# Fallback when MCP unavailable
-if ! command -v mcp__code-index__find_files; then
-  # Use find command for file discovery
-  find . -name "*{keyword}*" -type f -not -path "*/node_modules/*" -not -path "*/.git/*"
-
-  # Alternative pattern matching
-  find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" \) -exec grep -l "{keyword}" {} \;
-fi
-
-# Use ripgrep instead of MCP search
-rg "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 30
-
-# Content-based search with context
-rg -A 3 -B 3 "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source
-
-# Quick relevance check
-grep -r --include="*.{ts,js,py,go}" -l "{keywords}" . | head -15
-
-# Test files discovery
-find . -name "*test*" -o -name "*spec*" | grep -E "\.(ts|js|py|go)$" | head -10
-
-# Import/dependency analysis
-rg "^(import|from|require|#include)" --type-add 'source:*.{ts,js,py,go}' -t source | head -20
-```
-
-## Performance Optimization
-
-### Large Project Optimization Strategy
-- **File Count Limit**: Maximum 50 files per type
-- **Size Filtering**: Skip oversized files (>10MB)
-- **Depth Limit**: Maximum search depth of 3 levels
-- **Caching Strategy**: Cache project structure analysis results
-
-### Parallel Processing
-- Documentation collection and code search in parallel
-- MCP tool calls and traditional commands in parallel
-- Reduce I/O wait time
-
-## Essential Bash Commands (Max 10)
-
-### 1. Project Structure Analysis
-```bash
-~/.claude/scripts/get_modules_by_depth.sh
-```
-
-### 2. File Discovery by Keywords
-```bash
-find . -name "*{keyword}*" -type f -not -path "*/node_modules/*" -not -path "*/.git/*"
-```
-
-### 3. Content Search in Code Files
-```bash
-rg "{keyword}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 20
-```
-
-### 4. Configuration Files Discovery
-```bash
-find . -maxdepth 3 \( -name "*.json" -o -name "package.json" -o -name "requirements.txt" -o -name "Cargo.toml" \) -not -path "*/node_modules/*"
-```
-
-### 5. Documentation Files Collection
-```bash
-find . -name "*.md" -o -name "README*" -o -name "CLAUDE.md" | grep -v node_modules | head -10
-```
-
-### 6. Test Files Location
-```bash
-find . \( -name "*test*" -o -name "*spec*" \) -type f | grep -E "\.(js|ts|py|go)$" | head -10
-```
-
-### 7. Function/Class Definitions Search
-```bash
-rg "^(function|def|func|class|interface)" --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
-```
-
-### 8. Import/Dependency Analysis
-```bash
-rg "^(import|from|require|#include)" --type-add 'source:*.{ts,js,py,go}' -t source | head -15
-```
-
-### 9. Workflow Session Information
-```bash
-find .workflow/ -name "*.json" -path "*/${session_id}/*" -o -name "workflow-session.json" | head -5
-```
-
-### 10. Context-Aware Content Search
-```bash
-rg -A 2 -B 2 "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 10
+### 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);
+}
 ```
 
 ## Success Criteria
-- Generate valid context-package.json file
-- Contains sufficient relevant information for subsequent analysis
-- Execution time controlled within 30 seconds
-- File relevance accuracy rate >80%
+- 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
 
-## Related Commands
-- `/workflow:tools:concept-enhanced` - Consumes output of this command for analysis
-- `/workflow:plan` - Calls this command to gather context
-- `/workflow:status` - Can display context collection status

.claude/commands/workflow/tools/docs.md

@@ -1,665 +0,0 @@
----
-name: docs
-description: Documentation planning and orchestration - creates structured documentation tasks for execution
-argument-hint: "[path] [--tool <gemini|qwen|codex>] [--cli-generate]"
-examples:
-  - /workflow:docs                              # Current directory (root: full docs, subdir: module only)
-  - /workflow:docs src/modules                  # Module documentation only
-  - /workflow:docs . --tool qwen                # Root directory with Qwen
-  - /workflow:docs --cli-generate               # Use CLI for doc generation (not just analysis)
----
-
-# Documentation Workflow (/workflow:docs)
-
-## Overview
-Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent.
-
-**Two Execution Modes**:
-- **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach`
-- **--cli-generate**: CLI generates docs in `implementation_approach` (MODE=write)
-
-## Parameters
-
-```bash
-/workflow:docs [path] [--tool <gemini|qwen|codex>] [--cli-generate]
-```
-
-- **path**: Target directory (default: current directory)
-  - Project root → Full documentation (modules + project-level docs)
-  - Subdirectory → Module documentation only (API.md + README.md)
-
-- **--tool**: CLI tool selection (default: gemini)
-  - `gemini`: Comprehensive documentation, pattern recognition
-  - `qwen`: Architecture analysis, system design focus
-  - `codex`: Implementation validation, code quality
-
-- **--cli-generate**: Enable CLI-based documentation generation (optional)
-  - When enabled: CLI generates docs with MODE=write in implementation_approach
-  - When disabled (default): CLI analyzes with MODE=analysis in pre_analysis
-
-## Planning Workflow
-
-### Phase 1: Initialize Session
-```bash
-# Parse arguments
-path="${1:-.}"
-tool="gemini"
-cli_generate=false
-
-# Parse options
-while [[ $# -gt 0 ]]; do
-  case "$1" in
-    --tool) tool="$2"; shift 2 ;;
-    --cli-generate) cli_generate=true; shift ;;
-    *) shift ;;
-  esac
-done
-
-# Detect project root
-bash(git rev-parse --show-toplevel)
-project_root=$(pwd)
-target_path=$(cd "$path" && pwd)
-is_root=false
-[[ "$target_path" == "$project_root" ]] && is_root=true
-
-# Create session structure
-timestamp=$(date +%Y%m%d-%H%M%S)
-session_dir=".workflow/WFS-docs-${timestamp}"
-
-bash(mkdir -p "${session_dir}"/{.task,.process,.summaries})
-bash(touch ".workflow/.active-WFS-docs-${timestamp}")
-
-# Record configuration
-bash(cat > "${session_dir}/.process/config.txt" <<EOF
-path=$path
-target_path=$target_path
-is_root=$is_root
-tool=$tool
-cli_generate=$cli_generate
-EOF
-)
-```
-
-### Phase 2: Analyze Structure
-```bash
-# Step 1: Discover module hierarchy
-bash(~/.claude/scripts/get_modules_by_depth.sh)
-# Output: depth:N|path:<PATH>|files:N|size:N|has_claude:yes/no
-
-# Step 2: Classify folders by type
-bash(cat > "${session_dir}/.process/classify-folders.sh" <<'SCRIPT'
-while IFS='|' read -r depth_info path_info files_info size_info claude_info; do
-  folder_path=$(echo "$path_info" | cut -d':' -f2-)
-
-  # Count code files (maxdepth 1)
-  code_files=$(find "$folder_path" -maxdepth 1 -type f \
-    \( -name "*.ts" -o -name "*.js" -o -name "*.py" \
-       -o -name "*.go" -o -name "*.java" -o -name "*.rs" \) \
-    2>/dev/null | wc -l)
-
-  # Count subfolders
-  subfolders=$(find "$folder_path" -maxdepth 1 -type d \
-    -not -path "$folder_path" 2>/dev/null | wc -l)
-
-  # Determine type
-  if [[ $code_files -gt 0 ]]; then
-    folder_type="code"  # API.md + README.md
-  elif [[ $subfolders -gt 0 ]]; then
-    folder_type="navigation"  # README.md only
-  else
-    folder_type="skip"  # Empty
-  fi
-
-  echo "${folder_path}|${folder_type}|code:${code_files}|dirs:${subfolders}"
-done
-SCRIPT
-)
-
-bash(~/.claude/scripts/get_modules_by_depth.sh | bash "${session_dir}/.process/classify-folders.sh" > "${session_dir}/.process/folder-analysis.txt")
-
-# Step 3: Group by top-level directories
-bash(awk -F'|' '{split($1, parts, "/"); if (length(parts) >= 2) print parts[1] "/" parts[2]}' \
-  "${session_dir}/.process/folder-analysis.txt" | sort -u > "${session_dir}/.process/top-level-dirs.txt")
-```
-
-### Phase 3: Detect Update Mode
-```bash
-# Check existing documentation
-bash(find "$target_path" -name "API.md" -o -name "README.md" -o -name "ARCHITECTURE.md" -o -name "EXAMPLES.md" 2>/dev/null | grep -v ".workflow" | wc -l)
-
-existing_docs=$(...)
-
-if [[ $existing_docs -gt 0 ]]; then
-  bash(find "$target_path" -name "*.md" 2>/dev/null | grep -v ".workflow" > "${session_dir}/.process/existing-docs.txt")
-  echo "mode=update" >> "${session_dir}/.process/config.txt"
-else
-  echo "mode=create" >> "${session_dir}/.process/config.txt"
-fi
-
-# Record strategy
-bash(cat > "${session_dir}/.process/strategy.md" <<EOF
-**Path**: ${target_path}
-**Is Root**: ${is_root}
-**Tool**: ${tool}
-**CLI Generate**: ${cli_generate}
-**Mode**: $(grep 'mode=' "${session_dir}/.process/config.txt" | cut -d'=' -f2)
-**Existing Docs**: ${existing_docs} files
-EOF
-)
-```
-
-### Phase 4: Decompose Tasks
-
-**Task Hierarchy**:
-```
-Level 1: Module Tree Tasks (Always generated, can execute in parallel)
-  ├─ IMPL-001: Document tree 'src/modules/'
-  ├─ IMPL-002: Document tree 'src/utils/'
-  └─ IMPL-003: Document tree 'lib/'
-
-Level 2: Project README (Only if is_root=true, depends on Level 1)
-  └─ IMPL-004: Generate Project README
-
-Level 3: Architecture & Examples (Only if is_root=true, depends on Level 2)
-  ├─ IMPL-005: Generate ARCHITECTURE.md
-  ├─ IMPL-006: Generate EXAMPLES.md
-  └─ IMPL-007: Generate HTTP API docs (optional)
-```
-
-**Implementation**:
-```bash
-# Generate Level 1 tasks (always)
-task_count=0
-while read -r top_dir; do
-  task_count=$((task_count + 1))
-  # Create IMPL-00${task_count}.json for module tree
-done < "${session_dir}/.process/top-level-dirs.txt"
-
-# Generate Level 2-3 tasks (only if root)
-if [[ "$is_root" == "true" ]]; then
-  # IMPL-00$((task_count+1)).json: Project README
-  # IMPL-00$((task_count+2)).json: ARCHITECTURE.md
-  # IMPL-00$((task_count+3)).json: EXAMPLES.md
-  # IMPL-00$((task_count+4)).json: HTTP API (optional)
-fi
-```
-
-### Phase 5: Generate Task JSONs
-
-```bash
-# Read configuration
-cli_generate=$(grep 'cli_generate=' "${session_dir}/.process/config.txt" | cut -d'=' -f2)
-tool=$(grep 'tool=' "${session_dir}/.process/config.txt" | cut -d'=' -f2)
-
-# Determine CLI command placement
-if [[ "$cli_generate" == "true" ]]; then
-  # CLI generates docs: MODE=write, place in implementation_approach
-  mode="write"
-  placement="implementation_approach"
-  approval_flag="--approval-mode yolo"
-else
-  # CLI for analysis only: MODE=analysis, place in pre_analysis
-  mode="analysis"
-  placement="pre_analysis"
-  approval_flag=""
-fi
-
-# Build tool-specific command
-if [[ "$tool" == "codex" ]]; then
-  cmd="codex -C ${dir} --full-auto exec \"...\" --skip-git-repo-check -s danger-full-access"
-else
-  cmd="bash(cd ${dir} && ~/.claude/scripts/${tool}-wrapper ${approval_flag} -p \"...MODE: ${mode}...\")"
-fi
-```
-
-## Task Templates
-
-### Level 1: Module Tree Task
-
-**Default Mode (cli_generate=false)**:
-```json
-{
-  "id": "IMPL-001",
-  "title": "Document Module Tree: 'src/modules/'",
-  "status": "pending",
-  "meta": {
-    "type": "docs-tree",
-    "agent": "@doc-generator",
-    "tool": "gemini",
-    "cli_generate": false
-  },
-  "context": {
-    "requirements": [
-      "Recursively process all folders in src/modules/",
-      "For code folders: generate API.md + README.md",
-      "For navigation folders: generate README.md only"
-    ],
-    "focus_paths": ["src/modules"],
-    "folder_analysis_file": "${session_dir}/.process/folder-analysis.txt"
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_existing_docs",
-        "command": "bash(find src/modules -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
-        "output_to": "existing_module_docs"
-      },
-      {
-        "step": "load_folder_analysis",
-        "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
-        "output_to": "target_folders"
-      },
-      {
-        "step": "analyze_module_tree",
-        "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
-        "output_to": "tree_outline",
-        "note": "CLI for analysis only"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate module tree documentation",
-        "description": "Process target folders and generate appropriate documentation files based on folder types",
-        "modification_points": ["Parse folder types from [target_folders]", "Parse structure from [tree_outline]", "Generate API.md for code folders", "Generate README.md for all folders"],
-        "logic_flow": ["Parse [target_folders] to get folder types", "Parse [tree_outline] for structure", "For each folder: if type == 'code': Generate API.md + README.md; elif type == 'navigation': Generate README.md only"],
-        "depends_on": [],
-        "output": "module_docs"
-      }
-    ],
-    "target_files": [
-      ".workflow/docs/modules/*/API.md",
-      ".workflow/docs/modules/*/README.md"
-    ]
-  }
-}
-```
-
-**CLI Generate Mode (cli_generate=true)**:
-```json
-{
-  "id": "IMPL-001",
-  "title": "Document Module Tree: 'src/modules/'",
-  "status": "pending",
-  "meta": {
-    "type": "docs-tree",
-    "agent": "@doc-generator",
-    "tool": "gemini",
-    "cli_generate": true
-  },
-  "context": {
-    "requirements": [
-      "Recursively process all folders in src/modules/",
-      "CLI generates documentation files directly"
-    ],
-    "focus_paths": ["src/modules"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_existing_docs",
-        "command": "bash(find src/modules -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
-        "output_to": "existing_module_docs"
-      },
-      {
-        "step": "load_folder_analysis",
-        "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
-        "output_to": "target_folders"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Parse folder analysis",
-        "description": "Parse [target_folders] to get folder types and structure",
-        "modification_points": ["Extract folder types", "Identify code vs navigation folders"],
-        "logic_flow": ["Parse [target_folders] to get folder types", "Prepare folder list for CLI generation"],
-        "depends_on": [],
-        "output": "folder_types"
-      },
-      {
-        "step": 2,
-        "title": "Generate documentation via CLI",
-        "description": "Call CLI to generate documentation files for each folder using MODE=write",
-        "modification_points": ["Execute CLI generation command", "Generate API.md and README.md files"],
-        "logic_flow": ["Call CLI to generate documentation files for each folder"],
-        "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation files\\nMODE: write\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md files\\nRULES: Generate complete docs\")",
-        "depends_on": [1],
-        "output": "generated_docs"
-      }
-    ],
-    "target_files": [
-      ".workflow/docs/modules/*/API.md",
-      ".workflow/docs/modules/*/README.md"
-    ]
-  }
-}
-```
-
-### Level 2: Project README Task
-
-**Default Mode**:
-```json
-{
-  "id": "IMPL-004",
-  "title": "Generate Project README",
-  "status": "pending",
-  "depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
-  "meta": {
-    "type": "docs",
-    "agent": "@doc-generator",
-    "tool": "gemini",
-    "cli_generate": false
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_existing_readme",
-        "command": "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'No existing README')",
-        "output_to": "existing_readme"
-      },
-      {
-        "step": "load_module_docs",
-        "command": "bash(find .workflow/docs/modules -name '*.md' | xargs cat)",
-        "output_to": "all_module_docs"
-      },
-      {
-        "step": "analyze_project",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
-        "output_to": "project_outline"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate project README",
-        "description": "Generate project README with navigation links while preserving existing user modifications",
-        "modification_points": ["Parse [project_outline] and [all_module_docs]", "Generate project README structure", "Add navigation links to modules", "Preserve [existing_readme] user modifications"],
-        "logic_flow": ["Parse [project_outline] and [all_module_docs]", "Generate project README with navigation links", "Preserve [existing_readme] user modifications"],
-        "depends_on": [],
-        "output": "project_readme"
-      }
-    ],
-    "target_files": [".workflow/docs/README.md"]
-  }
-}
-```
-
-### Level 3: Architecture Documentation Task
-
-**Default Mode**:
-```json
-{
-  "id": "IMPL-005",
-  "title": "Generate Architecture Documentation",
-  "status": "pending",
-  "depends_on": ["IMPL-004"],
-  "meta": {
-    "type": "docs",
-    "agent": "@doc-generator",
-    "tool": "gemini",
-    "cli_generate": false
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_existing_arch",
-        "command": "bash(cat .workflow/docs/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE')",
-        "output_to": "existing_architecture"
-      },
-      {
-        "step": "load_all_docs",
-        "command": "bash(cat .workflow/docs/README.md && find .workflow/docs/modules -name '*.md' | xargs cat)",
-        "output_to": "all_docs"
-      },
-      {
-        "step": "analyze_architecture",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline\")",
-        "output_to": "arch_outline"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate architecture documentation",
-        "description": "Generate ARCHITECTURE.md while preserving existing user modifications",
-        "modification_points": ["Parse [arch_outline] and [all_docs]", "Generate ARCHITECTURE.md structure", "Document system design and patterns", "Preserve [existing_architecture] modifications"],
-        "logic_flow": ["Parse [arch_outline] and [all_docs]", "Generate ARCHITECTURE.md", "Preserve [existing_architecture] modifications"],
-        "depends_on": [],
-        "output": "architecture_doc"
-      }
-    ],
-    "target_files": [".workflow/docs/ARCHITECTURE.md"]
-  }
-}
-```
-
-### Level 3: Examples Documentation Task
-
-**Default Mode**:
-```json
-{
-  "id": "IMPL-006",
-  "title": "Generate Examples Documentation",
-  "status": "pending",
-  "depends_on": ["IMPL-004"],
-  "meta": {
-    "type": "docs",
-    "agent": "@doc-generator",
-    "tool": "gemini",
-    "cli_generate": false
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_existing_examples",
-        "command": "bash(cat .workflow/docs/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')",
-        "output_to": "existing_examples"
-      },
-      {
-        "step": "load_project_readme",
-        "command": "bash(cat .workflow/docs/README.md)",
-        "output_to": "project_readme"
-      },
-      {
-        "step": "generate_examples_outline",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Generate usage examples\\nTASK: Extract example patterns\\nMODE: analysis\\nCONTEXT: [project_readme]\\nEXPECTED: Examples outline\")",
-        "output_to": "examples_outline"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate examples documentation",
-        "description": "Generate EXAMPLES.md with code snippets while preserving existing user modifications",
-        "modification_points": ["Parse [examples_outline] and [project_readme]", "Generate EXAMPLES.md structure", "Add code snippets and usage examples", "Preserve [existing_examples] modifications"],
-        "logic_flow": ["Parse [examples_outline] and [project_readme]", "Generate EXAMPLES.md with code snippets", "Preserve [existing_examples] modifications"],
-        "depends_on": [],
-        "output": "examples_doc"
-      }
-    ],
-    "target_files": [".workflow/docs/EXAMPLES.md"]
-  }
-}
-```
-
-### Level 3: HTTP API Documentation Task (Optional)
-
-**Default Mode**:
-```json
-{
-  "id": "IMPL-007",
-  "title": "Generate HTTP API Documentation",
-  "status": "pending",
-  "depends_on": ["IMPL-004"],
-  "meta": {
-    "type": "docs",
-    "agent": "@doc-generator",
-    "tool": "gemini",
-    "cli_generate": false
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "discover_api_endpoints",
-        "command": "mcp__code-index__search_code_advanced(pattern='router\\.|@(Get|Post)', file_pattern='*.{ts,js}')",
-        "output_to": "endpoint_discovery"
-      },
-      {
-        "step": "load_existing_api_docs",
-        "command": "bash(cat .workflow/docs/api/README.md 2>/dev/null || echo 'No existing API docs')",
-        "output_to": "existing_api_docs"
-      },
-      {
-        "step": "analyze_api",
-        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @{src/api/**/*} [endpoint_discovery]\\nEXPECTED: API outline\")",
-        "output_to": "api_outline"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate HTTP API documentation",
-        "description": "Generate HTTP API documentation while preserving existing user modifications",
-        "modification_points": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Document endpoints and request/response formats", "Preserve [existing_api_docs] modifications"],
-        "logic_flow": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Preserve [existing_api_docs] modifications"],
-        "depends_on": [],
-        "output": "api_docs"
-      }
-    ],
-    "target_files": [".workflow/docs/api/README.md"]
-  }
-}
-```
-
-## Session Structure
-
-```
-.workflow/
-├── .active-WFS-docs-20240120-143022
-└── WFS-docs-20240120-143022/
-    ├── IMPL_PLAN.md              # Implementation plan
-    ├── TODO_LIST.md              # Progress tracker
-    ├── .process/
-    │   ├── config.txt            # path, is_root, tool, cli_generate, mode
-    │   ├── strategy.md           # Documentation strategy summary
-    │   ├── folder-analysis.txt   # Folder type classification
-    │   ├── top-level-dirs.txt    # Top-level directory list
-    │   └── existing-docs.txt     # Existing documentation files
-    └── .task/
-        ├── IMPL-001.json         # Module tree task
-        ├── IMPL-002.json         # Module tree task
-        ├── IMPL-003.json         # Module tree task
-        ├── IMPL-004.json         # Project README (if root)
-        ├── IMPL-005.json         # Architecture (if root)
-        ├── IMPL-006.json         # Examples (if root)
-        └── IMPL-007.json         # HTTP API (if root, optional)
-```
-
-## Generated Documentation
-
-```
-.workflow/docs/
-├── modules/                           # Level 1 output
-│   ├── README.md                      # Navigation for modules/
-│   ├── auth/
-│   │   ├── API.md                     # Auth module API signatures
-│   │   ├── README.md                  # Auth module documentation
-│   │   └── middleware/
-│   │       ├── API.md                 # Middleware API
-│   │       └── README.md              # Middleware docs
-│   └── api/
-│       ├── API.md                     # API module signatures
-│       └── README.md                  # API module docs
-├── README.md                          # Level 2 output (root only)
-├── ARCHITECTURE.md                    # Level 3 output (root only)
-├── EXAMPLES.md                        # Level 3 output (root only)
-└── api/                               # Level 3 output (optional)
-    └── README.md                      # HTTP API reference
-```
-
-## Execution Commands
-
-### Root Directory (Full Documentation)
-```bash
-# Level 1 - Module documentation (parallel)
-/workflow:execute IMPL-001
-/workflow:execute IMPL-002
-/workflow:execute IMPL-003
-
-# Level 2 - Project README (after Level 1)
-/workflow:execute IMPL-004
-
-# Level 3 - Architecture & Examples (after Level 2, parallel)
-/workflow:execute IMPL-005
-/workflow:execute IMPL-006
-/workflow:execute IMPL-007  # if HTTP API present
-```
-
-### Subdirectory (Module Only)
-```bash
-# Only Level 1 task generated
-/workflow:execute IMPL-001
-```
-
-## Simple Bash Commands
-
-### Check Documentation Status
-```bash
-# List existing documentation
-bash(find . -name "API.md" -o -name "README.md" -o -name "ARCHITECTURE.md" 2>/dev/null | grep -v ".workflow")
-
-# Count documentation files
-bash(find . -name "*.md" 2>/dev/null | grep -v ".workflow" | wc -l)
-```
-
-### Analyze Module Structure
-```bash
-# Discover modules
-bash(~/.claude/scripts/get_modules_by_depth.sh)
-
-# Count code files in directory
-bash(find src/modules -maxdepth 1 -type f \( -name "*.ts" -o -name "*.js" \) | wc -l)
-
-# Count subdirectories
-bash(find src/modules -maxdepth 1 -type d -not -path "src/modules" | wc -l)
-```
-
-### Session Management
-```bash
-# Create session directories
-bash(mkdir -p .workflow/WFS-docs-20240120/.{task,process,summaries})
-
-# Mark session as active
-bash(touch .workflow/.active-WFS-docs-20240120)
-
-# Read session configuration
-bash(cat .workflow/WFS-docs-20240120/.process/config.txt)
-
-# List session tasks
-bash(ls .workflow/WFS-docs-20240120/.task/*.json)
-```
-
-## Template Reference
-
-**Available Templates**:
-- `api.txt`: Unified template for Code API (Part A) and HTTP API (Part B)
-- `module-readme.txt`: Module purpose, usage, dependencies
-- `folder-navigation.txt`: Navigation README for folders with subdirectories
-- `project-readme.txt`: Project overview, getting started, module navigation
-- `project-architecture.txt`: System structure, module map, design patterns
-- `project-examples.txt`: End-to-end usage examples
-
-**Template Location**: `~/.claude/workflows/cli-templates/prompts/documentation/`
-
-## CLI Generate Mode Summary
-
-| Mode | CLI Placement | CLI MODE | Agent Role |
-|------|---------------|----------|------------|
-| **Default** | pre_analysis | analysis | Generates documentation files |
-| **--cli-generate** | implementation_approach | write | Validates and coordinates CLI output |
-
-## Related Commands
-- `/workflow:execute` - Execute documentation tasks
-- `/workflow:status` - View task progress
-- `/workflow:session:complete` - Mark session complete

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

@@ -1,21 +1,24 @@
 ---
 name: task-generate-agent
 description: Autonomous task generation using action-planning-agent with discovery and output phases
-argument-hint: "--session WFS-session-id"
+argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
+  - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
 ---
 
 # Autonomous Task Generation Command
 
 ## Overview
-Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation.
+Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
 
 ## Core Philosophy
 - **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
 - **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
 - **Memory-First**: Reuse loaded documents from conversation memory
 - **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
 
 ## Execution Lifecycle
 
@@ -26,6 +29,10 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 ```javascript
 {
   "session_id": "WFS-[session-id]",
+  "execution_mode": "agent-mode" | "cli-execute-mode",  // Determined by flag
+  "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
+                           | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
+  // Path selected by command based on --cli-execute flag, agent reads it
   "session_metadata": {
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/workflow-session.json
@@ -96,6 +103,14 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 
 ### Phase 2: Agent Execution (Document Generation)
 
+**Pre-Agent Template Selection** (Command decides path before invoking agent):
+```javascript
+// Command checks flag and selects template PATH (not content)
+const templatePath = hasCliExecuteFlag
+  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
+  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
+```
+
 **Agent Invocation**:
 ```javascript
 Task(
@@ -105,7 +120,8 @@ Task(
 ## Execution Context
 
 **Session ID**: WFS-{session-id}
-**Mode**: Two-Phase Autonomous Task Generation
+**Execution Mode**: {agent-mode | cli-execute-mode}
+**Task JSON Template Path**: {template_path}
 
 ## Phase 1: Discovery Results (Provided Context)
 
@@ -147,334 +163,34 @@ Task(
 
 #### 1. Task JSON Files (.task/IMPL-*.json)
 **Location**: .workflow/{session-id}/.task/
-**Schema**: 5-field enhanced schema with artifacts
+**Template**: Read from the template path provided above
 
-**Required Fields**:
-\`\`\`json
-{
-  "id": "IMPL-N[.M]",
-  "title": "Descriptive task name",
-  "status": "pending",
-  "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
-  },
-  "context": {
-    "requirements": ["extracted from analysis"],
-    "focus_paths": ["src/paths"],
-    "acceptance": ["measurable criteria"],
-    "depends_on": ["IMPL-N"],
-    "artifacts": [
-      {
-        "type": "synthesis_specification",
-        "path": "{synthesis_spec_path}",
-        "priority": "highest",
-        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
-      },
-      {
-        "type": "role_analysis",
-        "path": "{role_analysis_path}",
-        "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 included based on brainstorming results"
-      },
-      {
-        "type": "topic_framework",
-        "path": "{topic_framework_path}",
-        "priority": "low",
-        "usage": "Discussion context and framework structure"
-      }
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
-        "commands": [
-          "bash(ls {synthesis_spec_path} 2>/dev/null || echo 'not found')",
-          "Read({synthesis_spec_path})"
-        ],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "mcp_codebase_exploration",
-        "action": "Explore codebase using MCP",
-        "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",
-        "commands": [
-          "bash(cd \\"[focus_paths]\\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \\"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\\")"
-        ],
-        "output_to": "task_context",
-        "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.",
-        "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"
-        ],
-        "logic_flow": [
-          "Load synthesis specification and relevant role artifacts",
-          "Execute MCP code-index discovery for relevant files",
-          "Analyze existing patterns and identify modification targets",
-          "Implement following specification",
-          "Consult artifacts for technical details when needed",
-          "Validate against acceptance criteria"
-        ],
-        "depends_on": [],
-        "output": "implementation"
-      }
-    ],
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
-  }
-}
+**Task JSON Template Loading**:
 \`\`\`
+Read({template_path})
+\`\`\`
+
+**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
+- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
 
 #### 2. IMPL_PLAN.md
 **Location**: .workflow/{session-id}/IMPL_PLAN.md
-**Structure**:
-\`\`\`markdown
----
-identifier: WFS-{session-id}
-source: "User requirements" | "File: path" | "Issue: ISS-001"
-analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
-artifacts: .workflow/{session-id}/.brainstorming/
-context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
-workflow_type: "standard | tdd | design"  # Indicates execution model
-verification_history:  # CCW quality gates
-  concept_verify: "passed | skipped | pending"
-  action_plan_verify: "pending"
-phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
----
 
-# Implementation Plan: {Project Title}
-
-## 1. Summary
-Core requirements, objectives, technical approach summary (2-3 paragraphs max).
-
-**Core Objectives**:
-- [Key objective 1]
-- [Key objective 2]
-
-**Technical Approach**:
-- [High-level approach]
-
-## 2. Context Analysis
-
-### 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)
-
-**Quality Gates**:
-- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
-- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
-
-**Context Package Summary**:
-- **Focus Paths**: {list key directories from context-package.json}
-- **Key Files**: {list primary files for modification}
-- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
-- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
-
-### Project Profile
-- **Type**: Greenfield/Enhancement/Refactor
-- **Scale**: User count, data volume, complexity
-- **Tech Stack**: Primary technologies
-- **Timeline**: Duration and milestones
-
-### Module Structure
+**IMPL_PLAN Template**:
 \`\`\`
-[Directory tree showing key modules]
+$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
 \`\`\`
 
-### Dependencies
-**Primary**: [Core libraries and frameworks]
-**APIs**: [External services]
-**Development**: [Testing, linting, CI/CD tools]
-
-### Patterns & Conventions
-- **Architecture**: [Key patterns like DI, Event-Driven]
-- **Component Design**: [Design patterns]
-- **State Management**: [State strategy]
-- **Code Style**: [Naming, TypeScript coverage]
-
-## 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
-
-**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
-- **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
-
-### Integrated Specifications (Highest Priority)
-- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
-
-### 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)
-
-## 4. Implementation Strategy
-
-### Execution Strategy
-**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
-
-**Rationale**: [Why this execution model fits the project]
-
-**Parallelization Opportunities**:
-- [List independent workstreams]
-
-**Serialization Requirements**:
-- [List critical dependencies]
-
-### Architectural Approach
-**Key Architecture Decisions**:
-- [ADR references from synthesis]
-- [Justification for architecture patterns]
-
-**Integration Strategy**:
-- [How modules communicate]
-- [State management approach]
-
-### Key Dependencies
-**Task Dependency Graph**:
-\`\`\`
-[High-level dependency visualization]
-\`\`\`
-
-**Critical Path**: [Identify bottleneck tasks]
-
-### Testing Strategy
-**Testing Approach**:
-- Unit testing: [Tools, scope]
-- Integration testing: [Key integration points]
-- E2E testing: [Critical user flows]
-
-**Coverage Targets**:
-- Lines: ≥70%
-- Functions: ≥70%
-- Branches: ≥65%
-
-**Quality Gates**:
-- [CI/CD gates]
-- [Performance budgets]
-
-## 5. Task Breakdown Summary
-
-### Task Count
-**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
-
-### Task Structure
-- **IMPL-1**: [Main task title]
-- **IMPL-2**: [Main task title]
-...
-
-### Complexity Assessment
-- **High**: [List with rationale]
-- **Medium**: [List]
-- **Low**: [List]
-
-### Dependencies
-[Reference Section 4.3 for dependency graph]
-
-**Parallelization Opportunities**:
-- [Specific task groups that can run in parallel]
-
-## 6. Implementation Plan (Detailed Phased Breakdown)
-
-### Execution Strategy
-
-**Phase 1 (Weeks 1-2): [Phase Name]**
-- **Tasks**: IMPL-1, IMPL-2
-- **Deliverables**:
-  - [Specific deliverable 1]
-  - [Specific deliverable 2]
-- **Success Criteria**:
-  - [Measurable criterion]
-
-**Phase 2 (Weeks 3-N): [Phase Name]**
-...
-
-### Resource Requirements
-
-**Development Team**:
-- [Team composition and skills]
-
-**External Dependencies**:
-- [Third-party services, APIs]
-
-**Infrastructure**:
-- [Development, staging, production environments]
-
-## 7. Risk Assessment & Mitigation
-
-| Risk | Impact | Probability | Mitigation Strategy | Owner |
-|------|--------|-------------|---------------------|-------|
-| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
-
-**Critical Risks** (High impact + High probability):
-- [Risk 1]: [Detailed mitigation plan]
-
-**Monitoring Strategy**:
-- [How risks will be monitored]
-
-## 8. Success Criteria
-
-**Functional Completeness**:
-- [ ] All requirements from synthesis-specification.md implemented
-- [ ] All acceptance criteria from task.json files met
-
-**Technical Quality**:
-- [ ] Test coverage ≥70%
-- [ ] Bundle size within budget
-- [ ] Performance targets met
-
-**Operational Readiness**:
-- [ ] CI/CD pipeline operational
-- [ ] Monitoring and logging configured
-- [ ] Documentation complete
-
-**Business Metrics**:
-- [ ] [Key business metrics from synthesis]
-\`\`\`
+**Important**:
+- 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
 
 #### 3. TODO_LIST.md
 **Location**: .workflow/{session-id}/TODO_LIST.md
@@ -495,34 +211,43 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - \`- [x]\` = Completed leaf task
 \`\`\`
 
-### Execution Instructions
+### Execution Instructions for Agent
 
-**Step 1: Extract Task Definitions**
-- Parse analysis results for task recommendations
-- Extract task ID, title, requirements, complexity
-- Map artifacts to relevant tasks based on type
+**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
 
-**Step 2: Generate Task JSON Files**
-- Create individual .task/IMPL-*.json files
-- Embed artifacts array with detected brainstorming outputs
-- Generate flow_control with artifact loading steps
-- Add MCP tool integration for codebase exploration
+**Note**: The correct task JSON template path has been pre-selected by the command based on the `--cli-execute` flag and is provided in the context as `{template_path}`.
 
-**Step 3: Create IMPL_PLAN.md**
-- Summarize requirements and technical approach
-- List detected artifacts with priorities
-- Document task breakdown and dependencies
-- Define execution strategy and success criteria
+**Step 1: Load Task JSON Template**
+- Read template from the provided path: `Read({template_path})`
+- This template is already the correct one based on execution mode
 
-**Step 4: Generate TODO_LIST.md**
-- List all tasks with container/leaf structure
-- Link to task JSON files
+**Step 2: Extract and Decompose Tasks**
+- Parse ANALYSIS_RESULTS.md for task recommendations
+- Apply task merging rules (merge when possible, decompose only when necessary)
+- Map artifacts to tasks based on domain (UI/Backend/Data)
+- Ensure task count ≤10
+
+**Step 3: Generate Task JSON Files**
+- Use the template structure from Step 1
+- Create .task/IMPL-*.json files with proper structure
+- Replace all {placeholder} variables with actual session paths
+- Embed artifacts array with brainstorming outputs
+- Include MCP tool integration in pre_analysis steps
+
+**Step 4: Create IMPL_PLAN.md**
+- Use IMPL_PLAN template
+- Populate all sections with session-specific content
+- List artifacts with priorities and usage guidelines
+- Document execution strategy and dependencies
+
+**Step 5: Generate TODO_LIST.md**
+- Create task progress checklist matching generated JSONs
 - Use proper status indicators (▸, [ ], [x])
+- Link to task JSON files
 
-**Step 5: Update Session State**
-- Update .workflow/{session-id}/workflow-session.json
-- Mark session as ready for execution
-- Record task count and artifact inventory
+**Step 6: Update Session State**
+- Update workflow-session.json with task count and artifact inventory
+- Mark session ready for execution
 
 ### MCP Enhancement Examples
 
@@ -583,16 +308,6 @@ Generate all three documents and report completion status:
 )
 ```
 
-## Command Integration
-
-### Usage
-```bash
-# Basic usage
-/workflow:tools:task-generate-agent --session WFS-auth
-
-# Called by /workflow:plan
-SlashCommand(command="/workflow:tools:task-generate-agent --session WFS-[id]")
-```
 
 ### Agent Context Passing
 
@@ -623,20 +338,3 @@ const agentContext = {
   mcp_analysis: executeMcpDiscovery()
 }
 ```
-
-## Related Commands
-- `/workflow:plan` - Orchestrates planning and calls this command
-- `/workflow:tools:task-generate` - Manual version without agent
-- `/workflow:tools:context-gather` - Provides context package
-- `/workflow:tools:concept-enhanced` - Provides analysis results
-- `/workflow:execute` - Executes generated tasks
-
-## Key Differences from task-generate
-
-| Feature | task-generate | task-generate-agent |
-|---------|--------------|-------------------|
-| Execution | Manual/scripted | Agent-driven |
-| Phases | 6 phases | 2 phases (discovery + output) |
-| MCP Integration | Optional | Enhanced with examples |
-| Decision Logic | Command-driven | Agent-autonomous |
-| Complexity | Higher control | Simpler delegation |

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

@@ -2,18 +2,53 @@
 name: task-generate-tdd
 description: Generate TDD task chains with Red-Green-Refactor dependencies
 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
 
 ## Overview
-Generate TDD-specific task chains from analysis results with enforced Red-Green-Refactor structure and dependencies.
+Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
 
-## Core Philosophy
-- **TDD-First**: Every feature starts with a failing test
-- **Chain-Enforced**: Dependencies ensure proper TDD cycle
-- **Phase-Explicit**: Each task marked with Red/Green/Refactor phase
+## Task Strategy & Philosophy
+
+### Optimized Task Structure (Current)
+- **1 feature = 1 task** containing complete TDD cycle internally
+- Each task executes Red-Green-Refactor phases sequentially
+- Task count = Feature count (typically 5 features = 5 tasks)
+- **Benefits**:
+  - 70% reduction in task management overhead
+  - Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
+  - Simpler dependency management
+  - Maintains TDD rigor through internal phase structure
+
+**Previous Approach** (Deprecated):
+- 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
+- 5 features = 15 tasks with complex dependency chains
+- High context switching cost between phases
+
+### When to Use Subtasks
+- Feature complexity >2500 lines or >6 files per TDD cycle
+- Multiple independent sub-features needing parallel execution
+- Strong technical dependency blocking (e.g., API before UI)
+- Different tech stacks or domains within feature
+
+### Task Limits
+- **Maximum 10 tasks** (hard limit for TDD workflows)
+- **Feature-based**: Complete functional units with internal TDD cycles
+- **Hierarchy**: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features)
+- **Re-scope**: If >10 tasks needed, break project into multiple TDD workflow sessions
+
+### TDD Cycle Mapping
+- **Old approach**: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
+- **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
+- **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary
+
+### Core Principles
+- **TDD-First**: Every feature starts with a failing test (Red phase)
+- **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
 - **Artifact-Aware**: Integrates brainstorming outputs
 - **Memory-First**: Reuse loaded documents from memory
 - **Context-Aware**: Analyzes existing codebase and test patterns
@@ -22,16 +57,16 @@ Generate TDD-specific task chains from analysis results with enforced Red-Green-
 
 ## Core Responsibilities
 - Parse analysis results and identify testable features
-- Generate Red-Green-Refactor task chains for each feature
-- Enforce proper dependencies (TEST → IMPL → REFACTOR)
-- Create TDD_PLAN.md and enhanced IMPL_PLAN.md
-- Generate TODO_LIST.md with TDD phase indicators
-- Update session state for TDD execution
+- Generate feature-complete tasks with internal TDD cycles (1 task per simple feature)
+- Apply task merging strategy by default, create subtasks only when complexity requires
+- Generate IMPL_PLAN.md with TDD Implementation Tasks section
+- Generate TODO_LIST.md with internal TDD phase indicators
+- Update session state for TDD execution with task count compliance
 
 ## Execution Lifecycle
 
 ### Phase 1: Input Validation & Discovery
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+**Memory-First Rule**: Skip file loading if documents already in conversation memory
 
 1. **Session Validation**
    - If session metadata in memory → Skip loading
@@ -50,584 +85,352 @@ Generate TDD-specific task chains from analysis results with enforced Red-Green-
 
 **Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase)
 
-**Note**: The ANALYSIS_RESULTS.md now includes TDD-specific breakdown:
+**ANALYSIS_RESULTS.md includes**:
 - Feature list with testable requirements
 - Test cases for Red phase
 - Implementation requirements for Green phase
 - Refactoring opportunities
 - Task dependencies and execution order
 
-### Phase 3: Enhanced IMPL_PLAN.md Generation
+### Phase 3: Task JSON & IMPL_PLAN.md Generation
 
-#### Task Chain Structure
-For each feature, generate 3 tasks with ID format:
-- **TEST-N.M** (Red phase)
-- **IMPL-N.M** (Green phase)
-- **REFACTOR-N.M** (Refactor phase)
+#### Task Structure (Feature-Complete with Internal TDD)
+For each feature, generate task(s) with ID format:
+- **IMPL-N** - Single task containing complete TDD cycle (Red-Green-Refactor)
+- **IMPL-N.M** - Sub-tasks only when feature is complex (>2500 lines or technical blocking)
 
-#### Chain Dependency Rules
-- **IMPL depends_on TEST**: Cannot implement before test exists
-- **REFACTOR depends_on IMPL**: Cannot refactor before implementation
-- **Cross-feature dependencies**: If Feature 2 needs Feature 1, then `IMPL-2.1 depends_on ["REFACTOR-1.1"]`
+**Task Dependency Rules**:
+- **Sequential features**: IMPL-2 depends_on ["IMPL-1"] if Feature 2 needs Feature 1
+- **Independent features**: No dependencies, can execute in parallel
+- **Complex features**: IMPL-N.2 depends_on ["IMPL-N.1"] for subtask ordering
 
-#### Agent Assignment
-- **TEST tasks** → `@code-review-test-agent`
-- **IMPL tasks** → `@code-developer`
-- **REFACTOR tasks** → `@code-developer`
+**Agent Assignment**:
+- **All IMPL tasks** → `@code-developer` (handles full TDD cycle)
+- Agent executes Red, Green, Refactor phases sequentially within task
 
-#### Meta Fields
-- `meta.type`: "test" | "feature" | "refactor"
-- `meta.agent`: Agent for task execution
-- `meta.tdd_phase`: "red" | "green" | "refactor"
+**Meta Fields**:
+- `meta.type`: "feature" (TDD-driven feature implementation)
+- `meta.agent`: "@code-developer"
+- `meta.tdd_workflow`: true (enables TDD-specific flow)
+- `meta.tdd_phase`: Not used (phases are in flow_control.implementation_approach)
+- `meta.max_iterations`: 3 (for Green phase test-fix cycle)
+- `meta.use_codex`: false (manual fixes by default)
 
-#### Task JSON Examples
+#### Task JSON Structure Reference
 
-**RED Phase - Test Task (TEST-1.1.json)**
+**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
 ```json
 {
-  "id": "TEST-1.1",
-  "title": "Write failing test for user authentication",
-  "status": "pending",
+  "id": "IMPL-N",                                  // Task identifier
+  "title": "Feature description with TDD",         // Human-readable title
+  "status": "pending",                             // pending | in_progress | completed | container
   "meta": {
-    "type": "test",
-    "agent": "@code-review-test-agent",
-    "tdd_phase": "red"
+    "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": [
-      "Write test case for login with valid credentials",
-      "Test should fail with 'AuthService not implemented' error",
-      "Include tests for invalid credentials and edge cases"
+    "requirements": [                              // Feature requirements with TDD phases
+      "Feature description",
+      "Red: Test scenarios to write",
+      "Green: Implementation approach with test-fix cycle",
+      "Refactor: Code quality improvements"
     ],
-    "focus_paths": ["tests/auth/login.test.ts"],
-    "acceptance": [
-      "Test file created with at least 3 test cases",
-      "Test runs and fails with clear error message",
-      "Test assertions define expected behavior"
+    "tdd_cycles": [                                // OPTIONAL: Detailed test cycles
+      {
+        "cycle": 1,
+        "feature": "Specific functionality",
+        "test_focus": "What to test",
+        "expected_failure": "Why test should fail initially"
+      }
     ],
-    "depends_on": []
+    "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": [
+    "pre_analysis": [                              // OPTIONAL: Pre-execution checks
       {
         "step": "check_test_framework",
-        "action": "Verify test framework is configured",
-        "command": "bash(npm list jest || npm list vitest)",
+        "action": "Verify test framework",
+        "command": "bash(npm list jest)",
         "output_to": "test_framework_info",
         "on_error": "warn"
       }
-    ]
-  }
-}
-```
-
-**GREEN Phase - Implementation Task (IMPL-1.1.json)**
-```json
-{
-  "id": "IMPL-1.1",
-  "title": "Implement user authentication to pass tests",
-  "status": "pending",
-  "meta": {
-    "type": "feature",
-    "agent": "@code-developer",
-    "tdd_phase": "green",
-    "max_iterations": 3,
-    "use_codex": false
-  },
-  "context": {
-    "requirements": [
-      "Implement minimal AuthService to pass TEST-1.1",
-      "Handle valid and invalid credentials",
-      "Return appropriate success/error responses",
-      "If tests fail after implementation, diagnose and fix iteratively"
     ],
-    "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
-    "acceptance": [
-      "All tests in TEST-1.1 pass",
-      "Implementation is minimal and focused",
-      "No over-engineering or premature optimization",
-      "Test failures resolved within iteration limit"
-    ],
-    "depends_on": ["TEST-1.1"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_test_requirements",
-        "action": "Read test specifications from TEST phase",
-        "command": "bash(cat .workflow/WFS-xxx/.summaries/TEST-1.1-summary.md)",
-        "output_to": "test_requirements",
-        "on_error": "fail"
-      },
-      {
-        "step": "verify_tests_failing",
-        "action": "Confirm tests are currently failing (Red phase validation)",
-        "command": "bash(npm test -- tests/auth/login.test.ts || echo 'Tests failing as expected')",
-        "output_to": "initial_test_status",
-        "on_error": "warn"
-      },
-      {
-        "step": "load_test_context",
-        "action": "Load test patterns and framework info",
-        "command": "bash(cat .workflow/WFS-xxx/.process/test-context-package.json 2>/dev/null || echo '{}')",
-        "output_to": "test_context",
-        "on_error": "skip_optional"
-      }
-    ],
-    "implementation_approach": [
+    "implementation_approach": [                   // REQUIRED: 3 TDD phases
       {
         "step": 1,
-        "title": "Implement minimal code to pass tests",
-        "description": "Write minimal code based on test requirements following TDD principles - no over-engineering",
-        "modification_points": [
-          "Load test requirements from TEST phase",
-          "Create/modify implementation files",
-          "Implement only what tests require",
-          "Focus on passing tests, not perfection"
-        ],
-        "logic_flow": [
-          "Load test requirements from [test_requirements]",
-          "Parse test expectations and edge cases",
-          "Write minimal implementation code",
-          "Avoid premature optimization or abstraction"
-        ],
+        "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": "initial_implementation"
+        "output": "failing_tests"
       },
       {
         "step": 2,
-        "title": "Test and iteratively fix until passing",
-        "description": "Run tests and enter iterative fix cycle if needed (max 3 iterations with auto-revert on failure)",
-        "modification_points": [
-          "Execute test suite",
-          "If tests fail: diagnose with Gemini",
-          "Apply fixes (manual or Codex if meta.use_codex=true)",
-          "Retest and iterate"
-        ],
+        "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": [
-          "Run test suite",
-          "If all tests pass → Complete",
-          "If tests fail → Enter iteration loop (max 3):",
-          "  Extract failure messages and stack traces",
-          "  Use Gemini bug-fix template for diagnosis",
-          "  Generate targeted fix recommendations",
-          "  Apply fixes (manual or Codex)",
-          "  Rerun tests",
-          "  If pass → Complete, if fail → Continue iteration",
-          "If max_iterations reached → Trigger auto-revert"
+          "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"
         ],
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "acceptance": ["All tests pass"],
+        "command": "bash(npm test -- tests/path/)",
         "depends_on": [1],
-        "output": "test_results"
+        "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": [
+    "post_completion": [                           // OPTIONAL: Final verification
       {
-        "step": "verify_tests_passing",
-        "action": "Confirm all tests now pass (Green phase achieved)",
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
-        "output_to": "final_test_status",
+        "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": {
-      "max_iterations_reached": {
+    "error_handling": {                            // OPTIONAL: Error recovery
+      "green_phase_max_iterations": {
         "action": "revert_all_changes",
-        "commands": [
-          "bash(git reset --hard HEAD)",
-          "bash(echo 'TDD Green phase failed: Unable to pass tests within 3 iterations' > .workflow/WFS-xxx/.process/green-phase-failure.md)"
-        ],
-        "report": "Generate failure report in .summaries/IMPL-1.1-failure-report.md"
+        "commands": ["bash(git reset --hard HEAD)"],
+        "report": "Generate failure report"
       }
     }
   }
 }
 ```
 
-**REFACTOR Phase - Refactoring Task (REFACTOR-1.1.json)**
-```json
-{
-  "id": "REFACTOR-1.1",
-  "title": "Refactor authentication implementation",
-  "status": "pending",
-  "meta": {
-    "type": "refactor",
-    "agent": "@code-developer",
-    "tdd_phase": "refactor"
-  },
-  "context": {
-    "requirements": [
-      "Improve code quality while keeping tests green",
-      "Remove duplication in credential validation",
-      "Improve error handling and logging",
-      "Enhance code readability and maintainability"
-    ],
-    "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
-    "acceptance": [
-      "Code quality improved (complexity, readability)",
-      "All tests still pass after refactoring",
-      "No new functionality added",
-      "Duplication eliminated"
-    ],
-    "depends_on": ["IMPL-1.1"]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "verify_tests_passing",
-        "action": "Run tests to confirm green state before refactoring",
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
-        "output_to": "test_status",
-        "on_error": "fail"
-      },
-      {
-        "step": "analyze_code_quality",
-        "action": "Run linter and complexity analysis",
-        "command": "bash(npm run lint src/auth/AuthService.ts)",
-        "output_to": "quality_metrics",
-        "on_error": "warn"
-      }
-    ],
-    "post_completion": [
-      {
-        "step": "verify_tests_still_passing",
-        "action": "Confirm tests remain green after refactoring",
-        "command": "bash(npm test -- tests/auth/login.test.ts)",
-        "output_to": "final_test_status",
-        "on_error": "fail"
-      }
-    ]
-  }
-}
-```
+**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)
 
-### Phase 4: Unified IMPL_PLAN.md Generation
+#### IMPL_PLAN.md Structure
 
-Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
+Generate IMPL_PLAN.md with 8-section structure:
 
-**Frontmatter**:
+**Frontmatter** (required fields):
 ```yaml
 ---
 identifier: WFS-{session-id}
-source: "User requirements" | "File: path" | "Issue: ISS-001"
+source: "User requirements" | "File: path"
 analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
-artifacts: .workflow/{session-id}/.brainstorming/
-context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
-workflow_type: "tdd"  # TDD-specific workflow
-verification_history:  # CCW quality gates
+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"  # TDD workflow phases
+phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"
 feature_count: N
-task_count: 3N
-tdd_chains: N
+task_count: N  # ≤10 total
+task_breakdown:
+  simple_features: K
+  complex_features: L
+  total_subtasks: M
+tdd_workflow: true
 ---
 ```
 
-**Complete Structure** (8 Sections):
+**8 Sections Structure**:
 
 ```markdown
 # Implementation Plan: {Project Title}
 
 ## 1. Summary
-Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
-
-**Core Objectives**:
-- [Key objective 1]
-- [Key objective 2]
-
-**Technical Approach**:
-- TDD-driven development with Red-Green-Refactor cycles
-- [Other high-level approaches]
+- Core requirements and objectives (2-3 paragraphs)
+- TDD-specific technical approach
 
 ## 2. Context Analysis
-
-### CCW Workflow Context
-**Phase Progression** (TDD-specific):
-- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
-- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
-- ✅ Phase 3: Test Coverage Analysis (test-context-package.json: existing test patterns identified)
-- ✅ Phase 4: TDD Analysis (ANALYSIS_RESULTS.md: test-first requirements with Gemini/Qwen insights)
-- ✅ Phase 5: Concept Verification ({X} clarifications answered, test requirements clarified | skipped)
-- ⏳ Phase 6: TDD Task Generation (current phase - generating IMPL_PLAN.md with TDD chains)
-
-**Quality Gates**:
-- concept-verify: ✅ Passed (test requirements clarified, 0 ambiguities) | ⏭️ Skipped (user decision) | ⏳ Pending
-- action-plan-verify: ⏳ Pending (recommended before /workflow:execute for TDD dependency validation)
-
-**Context Package Summary**:
-- **Focus Paths**: {list key directories from context-package.json}
-- **Key Files**: {list primary files for modification}
-- **Test Context**: {existing test patterns, coverage baseline, test framework detected}
-- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
-- **Smart Context**: {total file count} files, {module count} modules, {test file count} tests identified
-
-### Project Profile
-- **Type**: Greenfield/Enhancement/Refactor
-- **Scale**: User count, data volume, complexity
-- **Tech Stack**: Primary technologies
-- **Timeline**: Duration and milestones
-- **TDD Framework**: Testing framework and tools
-
-### Module Structure
-```
-[Directory tree showing key modules and test directories]
-```
-
-### Dependencies
-**Primary**: [Core libraries and frameworks]
-**Testing**: [Test framework, mocking libraries]
-**Development**: [Linting, CI/CD tools]
-
-### Patterns & Conventions
-- **Architecture**: [Key patterns]
-- **Testing Patterns**: [Unit, integration, E2E patterns]
-- **Code Style**: [Naming, TypeScript coverage]
+- 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
-**Primary Reference (synthesis-specification.md)**:
-- **What**: Comprehensive implementation blueprint from multi-role synthesis
-- **When**: Every TDD task (TEST/IMPL/REFACTOR) references this for requirements and acceptance criteria
-- **How**: Extract testable requirements, architecture decisions, expected behaviors
-- **Priority**: Authoritative - defines what to test and how to implement
-- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth for TDD
-
-**Context Intelligence (context-package.json & test-context-package.json)**:
-- **What**: Smart context from CCW's context-gather and test-context-gather phases
-- **Content**: Focus paths, dependency graph, existing test patterns, test framework configuration
-- **Usage**: RED phase loads test patterns, GREEN phase loads implementation context
-- **CCW Value**: Automated discovery of existing tests and patterns for TDD consistency
-
-**Technical Analysis (ANALYSIS_RESULTS.md)**:
-- **What**: Gemini/Qwen parallel analysis with TDD-specific breakdown
-- **Content**: Testable requirements, test scenarios, implementation strategies, risk assessment
-- **Usage**: RED phase references test cases, GREEN phase references implementation approach
-- **CCW Value**: Multi-model analysis providing comprehensive TDD guidance
-
-### Integrated Specifications (Highest Priority)
-- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, functional/non-functional requirements
-
-### Supporting Artifacts (Reference)
-- **topic-framework.md**: Discussion framework
-- **system-architect/analysis.md**: Architecture specifications
-- **Role-specific analyses**: [Other relevant analyses]
-
-**Artifact Priority in Development**:
-1. synthesis-specification.md (primary reference for test cases and implementation)
-2. test-context-package.json (existing test patterns for TDD consistency)
-3. context-package.json (smart context for execution environment)
-4. ANALYSIS_RESULTS.md (technical analysis with TDD breakdown)
-5. Role-specific analyses (supplementary)
+- 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)
 
-### Execution Strategy
-**Execution Model**: TDD Cycles (Red-Green-Refactor)
-
-**Rationale**: Test-first approach ensures correctness and reduces bugs
-
-**TDD Cycle Pattern**:
-- RED: Write failing test
-- GREEN: Implement minimal code to pass (with test-fix cycle if needed)
-- REFACTOR: Improve code quality while keeping tests green
-
-**Parallelization Opportunities**:
-- [Independent features that can be developed in parallel]
-
-### Architectural Approach
-**Key Architecture Decisions**:
-- [ADR references from synthesis]
-- [TDD-compatible architecture patterns]
-
-**Integration Strategy**:
-- [How modules communicate]
-- [Test isolation strategy]
-
-### Key Dependencies
-**Task Dependency Graph**:
-```
-Feature 1:
-  TEST-1.1 (RED)
-      ↓
-  IMPL-1.1 (GREEN) [with test-fix cycle]
-      ↓
-  REFACTOR-1.1 (REFACTOR)
-
-Feature 2:
-  TEST-2.1 (RED) [depends on REFACTOR-1.1 if related]
-      ↓
-  IMPL-2.1 (GREEN)
-      ↓
-  REFACTOR-2.1 (REFACTOR)
-```
-
-**Critical Path**: [Identify bottleneck features]
-
-### Testing Strategy
-**TDD Testing Approach**:
-- Unit testing: Each feature has comprehensive unit tests
-- Integration testing: Cross-feature integration
-- E2E testing: Critical user flows after all TDD cycles
-
-**Coverage Targets**:
-- Lines: ≥80% (TDD ensures high coverage)
-- Functions: ≥80%
-- Branches: ≥75%
-
-**Quality Gates**:
-- All tests must pass before moving to next phase
-- Refactor phase must maintain test success
-
-## 5. TDD Task Chains (TDD-Specific Section)
-
-### Feature-by-Feature TDD Chains
-
-**Feature 1: {Feature Name}**
-```
-🔴 TEST-1.1: Write failing test for {feature}
-    ↓
-🟢 IMPL-1.1: Implement to pass tests (includes test-fix cycle: max 3 iterations)
-    ↓
-🔵 REFACTOR-1.1: Refactor implementation while keeping tests green
-```
-
-**Feature 2: {Feature Name}**
-```
-🔴 TEST-2.1: Write failing test for {feature}
-    ↓
-🟢 IMPL-2.1: Implement to pass tests (includes test-fix cycle)
-    ↓
-🔵 REFACTOR-2.1: Refactor implementation
-```
-
-[Continue for all N features]
-
-### TDD Task Breakdown Summary
-- **Total Features**: {N}
-- **Total Tasks**: {3N} (N TEST + N IMPL + N REFACTOR)
-- **TDD Chains**: {N}
+## 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
-
-**TDD Cycle Execution**: Feature-by-feature sequential TDD cycles
-
-**Phase 1 (Weeks 1-2): Foundation Features**
-- **Features**: Feature 1, Feature 2
-- **Tasks**: TEST-1.1, IMPL-1.1, REFACTOR-1.1, TEST-2.1, IMPL-2.1, REFACTOR-2.1
-- **Deliverables**:
-  - Complete TDD cycles for foundation features
-  - All tests passing
-- **Success Criteria**:
-  - ≥80% test coverage
-  - All RED-GREEN-REFACTOR cycles completed
-
-**Phase 2 (Weeks 3-N): Advanced Features**
-[Continue with remaining features]
-
-### Resource Requirements
-
-**Development Team**:
-- [Team composition with TDD experience]
-
-**External Dependencies**:
-- [Testing frameworks, mocking services]
-
-**Infrastructure**:
-- [CI/CD with test automation]
+- Execution Strategy (feature-by-feature sequential)
+- Phase breakdown (Phase 1, Phase 2, etc.)
+- Resource Requirements (Team, Dependencies, Infrastructure)
 
 ## 7. Risk Assessment & Mitigation
-
-| Risk | Impact | Probability | Mitigation Strategy | Owner |
-|------|--------|-------------|---------------------|-------|
-| Tests fail repeatedly in GREEN phase | High | Medium | Test-fix cycle (max 3 iterations) with auto-revert | Dev Team |
-| Complex features hard to test | High | Medium | Break down into smaller testable units | Architect |
-| [Other risks] | Med/Low | Med/Low | [Strategies] | [Owner] |
-
-**Critical Risks** (TDD-Specific):
-- **GREEN phase failures**: Mitigated by test-fix cycle with Gemini diagnosis
-- **Test coverage gaps**: Mitigated by TDD-first approach ensuring tests before code
-
-**Monitoring Strategy**:
-- Track TDD cycle completion rate
-- Monitor test success rate per iteration
+- Risk table (Risk, Impact, Probability, Mitigation, Owner)
+- Critical Risks (TDD-specific)
+- Monitoring Strategy
 
 ## 8. Success Criteria
-
-**Functional Completeness**:
-- [ ] All features implemented through TDD cycles
-- [ ] All RED-GREEN-REFACTOR cycles completed successfully
-
-**Technical Quality**:
-- [ ] Test coverage ≥80% (ensured by TDD)
-- [ ] All tests passing (GREEN state achieved)
-- [ ] Code refactored for quality (REFACTOR phase completed)
-
-**Operational Readiness**:
-- [ ] CI/CD pipeline with automated test execution
-- [ ] Test failure alerting configured
-
-**TDD Compliance**:
-- [ ] Every feature has TEST → IMPL → REFACTOR chain
-- [ ] No implementation without tests (RED-first principle)
-- [ ] Refactoring did not break tests
+- Functional Completeness
+- Technical Quality (Test coverage ≥80%)
+- Operational Readiness
+- TDD Compliance
 ```
 
-### Phase 5: TODO_LIST.md Generation
+### Phase 4: TODO_LIST.md Generation
 
-Generate task list with TDD phase indicators:
+Generate task list with internal TDD phase indicators:
+
+**For Simple Features (1 task per feature)**:
 ```markdown
-## Feature 1: {Feature Name}
-- [ ] **TEST-1.1**: Write failing test (🔴 RED) → [📋](./.task/TEST-1.1.json)
-- [ ] **IMPL-1.1**: Implement to pass tests (🟢 GREEN) [depends: TEST-1.1] → [📋](./.task/IMPL-1.1.json)
-- [ ] **REFACTOR-1.1**: Refactor implementation (🔵 REFACTOR) [depends: IMPL-1.1] → [📋](./.task/REFACTOR-1.1.json)
+## 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
 ```
 
-### Phase 6: Session State Update
+**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
+```
+
+**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
+```
+
+### Phase 5: Session State Update
 
 Update workflow-session.json with TDD metadata:
 ```json
 {
   "workflow_type": "tdd",
-  "feature_count": 10,
-  "task_count": 30,
-  "tdd_chains": 10
+  "feature_count": 5,
+  "task_count": 5,
+  "task_breakdown": {
+    "simple_features": 4,
+    "complex_features": 1,
+    "total_subtasks": 2
+  },
+  "tdd_workflow": true,
+  "task_limit_compliance": true
 }
 ```
 
+**Task Count Calculation**:
+- **Simple features**: 1 task each (IMPL-N with internal TDD cycle)
+- **Complex features**: 1 container + M subtasks (IMPL-N + IMPL-N.M)
+- **Total**: Simple feature count + Complex feature subtask count
+- **Example**: 4 simple + 1 complex (with 2 subtasks) = 6 total tasks (not 15)
+
 ## Output Files Structure
 ```
 .workflow/{session-id}/
-├── IMPL_PLAN.md                     # Unified plan with TDD Task Chains section
-├── TODO_LIST.md                     # Progress tracking with TDD phases
+├── IMPL_PLAN.md                     # Unified plan with TDD Implementation Tasks section
+├── TODO_LIST.md                     # Progress tracking with internal TDD phase indicators
 ├── .task/
-│   ├── TEST-1.1.json                # Red phase task
-│   ├── IMPL-1.1.json                # Green phase task (with test-fix-cycle)
-│   ├── REFACTOR-1.1.json            # Refactor phase task
+│   ├── IMPL-1.json                  # Complete TDD task (Red-Green-Refactor internally)
+│   ├── IMPL-2.json                  # Complete TDD task
+│   ├── IMPL-3.json                  # Complex feature container (if needed)
+│   ├── IMPL-3.1.json                # Complex feature subtask (if needed)
+│   ├── IMPL-3.2.json                # Complex feature subtask (if needed)
 │   └── ...
 └── .process/
     ├── ANALYSIS_RESULTS.md          # Enhanced with TDD breakdown from concept-enhanced
     ├── test-context-package.json    # Test coverage analysis
     ├── context-package.json         # Input from context-gather
-    └── green-fix-iteration-*.md     # Fix logs from Green phase
+    └── green-fix-iteration-*.md     # Fix logs from Green phase test-fix cycles
 ```
 
+**File Count**:
+- **Old approach**: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5)
+- **New approach**: 5 features = 5 task JSON files (IMPL-N × 5)
+- **Complex feature**: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M)
+
 ## Validation Rules
 
-### Chain Completeness
-- Every TEST-N.M must have corresponding IMPL-N.M and REFACTOR-N.M
+### Task Completeness
+- Every IMPL-N must contain complete TDD workflow in `flow_control.implementation_approach`
+- Each task must have 3 steps with `tdd_phase`: "red", "green", "refactor"
+- Every task must have `meta.tdd_workflow: true`
 
 ### Dependency Enforcement
-- IMPL-N.M must have `depends_on: ["TEST-N.M"]`
-- REFACTOR-N.M must have `depends_on: ["IMPL-N.M"]`
+- Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
+- Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies
+- No circular dependencies allowed
 
 ### Task Limits
-- Maximum 10 features (30 tasks total)
-- Flat hierarchy only
+- Maximum 10 total tasks (simple + subtasks)
+- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
+- Re-scope requirements if >10 tasks needed
+
+### TDD Workflow Validation
+- `meta.tdd_workflow` must be true
+- `flow_control.implementation_approach` must have exactly 3 steps
+- Each step must have `tdd_phase` field ("red", "green", or "refactor")
+- Green phase step must include test-fix cycle logic
+- `meta.max_iterations` must be present (default: 3)
 
 ## Error Handling
 
@@ -640,9 +443,10 @@ Update workflow-session.json with TDD metadata:
 ### TDD Generation Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
-| Feature count exceeds 10 | Too many features | Re-scope requirements |
+| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features |
 | Missing test framework | No test config | Configure testing first |
-| Invalid chain structure | Parsing error | Fix TDD breakdown |
+| Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
+| Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
 
 ## Integration & Usage
 
@@ -665,17 +469,32 @@ Update workflow-session.json with TDD metadata:
 TDD task generation complete for session: WFS-auth
 
 Features analyzed: 5
-TDD chains generated: 5
-Total tasks: 15 (5 TEST + 5 IMPL + 5 REFACTOR)
+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:
-- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
-- Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1
+- 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 Task Chains section)
+- 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)
 
-Next: /workflow:execute or /workflow:tdd-verify
+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
 ```
 
 ## Test Coverage Analysis Integration
@@ -704,10 +523,10 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
 5. **Safety Net**: Auto-revert all changes if max iterations reached
 
 **Key Benefits**:
-- ✅ Faster feedback loop within Green phase
-- ✅ Autonomous recovery from initial implementation errors
-- ✅ Systematic debugging with Gemini's bug-fix template
-- ✅ Safe rollback prevents broken TDD state
+- Faster feedback loop within Green phase
+- Autonomous recovery from initial implementation errors
+- Systematic debugging with Gemini's bug-fix template
+- Safe rollback prevents broken TDD state
 
 ## Configuration Options
 - **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)

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

@@ -1,4 +1,4 @@
----
+--- 
 name: task-generate
 description: Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration
 argument-hint: "--session WFS-session-id [--cli-execute]"
@@ -9,76 +9,164 @@ examples:
 
 # Task Generation Command
 
-## Overview
-Generate task JSON files and IMPL_PLAN.md from analysis results with automatic artifact detection and integration.
+## 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.
 
-## Execution Modes
+## 2. Execution Modes
+
+This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
 
 ### Agent Mode (Default)
-Tasks execute within agent context using agent's capabilities:
-- Agent reads synthesis specifications
-- Agent implements following requirements
-- Agent validates implementation
-- **Benefit**: Seamless context within single agent execution
+In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
+- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
+- **Execution**: Agent reads these fields and performs the implementation autonomously
+- **Context Loading**: Agent loads context via `pre_analysis` steps
+- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
+- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
+- **Use Case**: Standard implementation tasks where agent capability is sufficient
 
 ### CLI Execute Mode (`--cli-execute`)
-Tasks execute using Codex CLI with resume mechanism:
-- Each task uses `codex exec` command in `implementation_approach`
-- First task establishes Codex session
-- Subsequent tasks use `codex exec "..." resume --last` for context continuity
-- **Benefit**: Codex's autonomous development capabilities with persistent context
-- **Use Case**: Complex implementation requiring Codex's reasoning and iteration
+When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
+- **Step Structure**: Includes all default fields PLUS a `command` field
+- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
+- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
+- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
+- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
+- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
 
-## Core Philosophy
-- **Analysis-Driven**: Generate from ANALYSIS_RESULTS.md
-- **Artifact-Aware**: Auto-detect brainstorming outputs
-- **Context-Rich**: Embed comprehensive context in task JSON
-- **Flow-Control Ready**: Pre-define implementation steps
-- **Memory-First**: Reuse loaded documents from memory
-- **CLI-Aware**: Support Codex resume mechanism for persistent context
+## 3. Core Principles
+This command is built on a set of core principles to ensure efficient and reliable task generation.
 
-## Core Responsibilities
-- Parse analysis results and extract tasks
-- Detect and integrate brainstorming artifacts
-- Generate enhanced task JSON files (5-field schema)
-- Create IMPL_PLAN.md and TODO_LIST.md
-- Update session state for execution
+- **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
+- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
+- **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
+- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
 
-## Execution Lifecycle
+## 4. Execution Flow
+The command follows a streamlined, three-step process to convert analysis into executable tasks.
 
-### Phase 1: Input Validation & Discovery
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+### 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.
 
-1. **Session Validation**
-   - If session metadata in memory → Skip loading
-   - Else: Load `.workflow/{session_id}/workflow-session.json`
+### 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`.
+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.
 
-2. **Analysis Results Loading**
-   - If ANALYSIS_RESULTS.md in memory → Skip loading
-   - Else: Read `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
+### Step 3: Output Generation
+Finally, the command generates all the necessary output files.
+1.  **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
+2.  **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
+3.  **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
+4.  **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
 
-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
+## 5. Task Decomposition Strategy
+The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
 
-### Phase 2: Task JSON Generation
+### Core Principles
+- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
+- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
 
-#### Task Decomposition Standards
-**Core Principle: Task Merging Over Decomposition**
-- **Merge Rule**: Execute together when possible
-- **Decompose Only When**:
-  - Excessive workload (>2500 lines or >6 files)
-  - Different tech stacks or domains
-  - Sequential dependency blocking
-  - Parallel execution needed
+### Context Analysis for Task Grouping
+The decision to merge or decompose is based on analyzing context indicators:
 
+1.  **Shared Context Indicators (→ Merge)**:
+    *   Identical `focus_paths` (working on the same modules/files).
+    *   Same tech stack and dependencies.
+    *   Identical `context.artifacts` references.
+    *   A sequential logic flow within the same feature.
+    *   Shared test fixtures or setup.
+
+2.  **Independent Context Indicators (→ Decompose)**:
+    *   Different `focus_paths` (separate modules).
+    *   Different tech stacks (e.g., frontend vs. backend).
+    *   Different `context.artifacts` (using different brainstorming outputs).
+    *   No shared dependencies.
+    *   Can be tested independently.
+
+**Decomposition is only performed when**:
+- Tasks have different contexts and no shared dependencies (enabling parallel execution).
+- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
+- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
+
+### Context Signature Algorithm
+To automate grouping, a `context_signature` is computed for each task.
+
+```javascript
+// Compute context signature for task grouping
+function computeContextSignature(task) {
+  const focusPathsStr = task.context.focus_paths.sort().join('|');
+  const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
+  const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
+
+  return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
+}
+```
+
+### Execution Group Assignment
+Tasks are assigned to execution groups based on their signatures and dependencies.
+
+```javascript
+// Group tasks by context signature
+function groupTasksByContext(tasks) {
+  const groups = {};
+
+  tasks.forEach(task => {
+    const signature = computeContextSignature(task);
+    if (!groups[signature]) {
+      groups[signature] = [];
+    }
+    groups[signature].push(task);
+  });
+
+  return groups;
+}
+
+// Assign execution groups for parallel tasks
+function assignExecutionGroups(tasks) {
+  const contextGroups = groupTasksByContext(tasks);
+
+  Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
+    if (groupTasks.length === 1) {
+      const task = groupTasks[0];
+      // Single task with unique context
+      if (!task.context.depends_on || task.context.depends_on.length === 0) {
+        task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
+      } else {
+        task.meta.execution_group = null; // Sequential task
+      }
+    } else {
+      // Multiple tasks with same context → Should be merged
+      console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
+      // Merge tasks into single task
+      return mergeTasks(groupTasks);
+    }
+  });
+}
+```
 **Task Limits**:
-- **Maximum 10 tasks** (hard limit)
-- **Function-based**: Complete units (logic + UI + tests + config)
-- **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
+- **Maximum 10 tasks** (hard limit).
+- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
+- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
+
+## 6. Generated Outputs
+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.
 
-#### Enhanced Task JSON Schema (5-Field + Artifacts)
 ```json
 {
   "id": "IMPL-N[.M]",
@@ -86,7 +174,9 @@ Tasks execute using Codex CLI with resume mechanism:
   "status": "pending|active|completed|blocked|container",
   "meta": {
     "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
+    "agent": "@code-developer|@test-fix-agent|@general-purpose",
+    "execution_group": "group-id|null",
+    "context_signature": "hash-of-focus_paths-and-artifacts"
   },
   "context": {
     "requirements": ["Clear requirement from analysis"],
@@ -166,7 +256,7 @@ Tasks execute using Codex CLI with resume mechanism:
         "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\")"
+          "bash(gemini \"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"
@@ -195,123 +285,14 @@ Tasks execute using Codex CLI with resume mechanism:
         "output": "implementation"
       }
     ],
-
-    // CLI Execute Mode: Use Codex command (when --cli-execute flag present)
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Execute implementation with Codex",
-        "description": "Use Codex CLI to implement '[title]' following synthesis specification with autonomous development capabilities",
-        "modification_points": [
-          "Codex loads synthesis specification and artifacts",
-          "Codex implements following requirements",
-          "Codex validates and tests implementation"
-        ],
-        "logic_flow": [
-          "Establish or resume Codex session",
-          "Pass synthesis specification to Codex",
-          "Codex performs autonomous implementation",
-          "Codex validates against acceptance criteria"
-        ],
-        "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: [title] TASK: [requirements] MODE: auto CONTEXT: @{[synthesis_path],[artifacts_paths]} EXPECTED: [acceptance] RULES: Follow synthesis-specification.md\" [resume_flag] --skip-git-repo-check -s danger-full-access)",
-        "depends_on": [],
-        "output": "implementation"
-      }
-    ],
     "target_files": ["file:function:lines"]
   }
 }
 ```
 
-#### Task Generation Process
-1. Parse analysis results and extract task definitions
-2. Detect brainstorming artifacts with priority scoring
-3. Generate task context (requirements, focus_paths, acceptance)
-4. **Determine modification targets**: Extract specific code locations from analysis
-5. Build flow_control with artifact loading steps and target_files
-6. **CLI Execute Mode**: If `--cli-execute` flag present, generate Codex commands
-7. Create individual task JSON files in `.task/`
+### 6.2. IMPL_PLAN.md Structure
+This document provides a high-level overview of the entire implementation plan.
 
-#### Codex Resume Mechanism (CLI Execute Mode)
-
-**Session Continuity Strategy**:
-- **First Task** (no depends_on or depends_on=[]): Establish new Codex session
-  - Command: `codex -C [path] --full-auto exec "[prompt]" --skip-git-repo-check -s danger-full-access`
-  - Creates new session context
-
-- **Subsequent Tasks** (has depends_on): Resume previous Codex session
-  - Command: `codex --full-auto exec "[prompt]" resume --last --skip-git-repo-check -s danger-full-access`
-  - Maintains context from previous implementation
-  - **Critical**: `resume --last` flag enables context continuity
-
-**Resume Flag Logic**:
-```javascript
-// Determine resume flag based on task dependencies
-const resumeFlag = task.context.depends_on && task.context.depends_on.length > 0
-  ? "resume --last"
-  : "";
-
-// First task (IMPL-001): no resume flag
-// Later tasks (IMPL-002, IMPL-003): use "resume --last"
-```
-
-**Benefits**:
-- ✅ Shared context across related tasks
-- ✅ Codex learns from previous implementations
-- ✅ Consistent patterns and conventions
-- ✅ Reduced redundant analysis
-
-#### Target Files Generation (Critical)
-**Purpose**: Identify specific code locations for modification AND new files to create
-
-**Source Data Priority**:
-1. **ANALYSIS_RESULTS.md** - Should contain identified code locations
-2. **Gemini/MCP Analysis** - From `analyze_task_patterns` step
-3. **Context Package** - File references from `focus_paths`
-
-**Format**: `["file:function:lines"]` or `["file"]` (for new files)
-- `file`: Relative path from project root (e.g., `src/auth/AuthService.ts`)
-- `function`: Function/method name to modify (e.g., `login`, `validateToken`) - **omit for new files**
-- `lines`: Approximate line range (e.g., `45-52`, `120-135`) - **omit for new files**
-
-**Examples**:
-```json
-"target_files": [
-  "src/auth/AuthService.ts:login:45-52",
-  "src/middleware/auth.ts:validateToken:30-45",
-  "src/auth/PasswordReset.ts",
-  "tests/auth/PasswordReset.test.ts",
-  "tests/auth.test.ts:testLogin:15-20"
-]
-```
-
-**Generation Strategy**:
-- **New files to create** → Use `["path/to/NewFile.ts"]` (no function or lines)
-- **Existing files with specific locations** → Use `["file:function:lines"]`
-- **Existing files with function only** → Search lines using MCP/grep `["file:function:*"]`
-- **Existing files (explore entire)** → Mark as `["file.ts:*:*"]`
-- **No specific targets** → Leave empty `[]` (agent explores focus_paths)
-
-### Phase 3: Artifact Detection & Integration
-
-#### Artifact Priority
-1. **synthesis-specification.md** (highest) - Complete integrated spec
-2. **topic-framework.md** (medium) - Discussion framework
-3. **role/analysis.md** (low) - Individual perspectives
-
-#### Artifact-Task Mapping
-- **synthesis-specification.md** → All tasks
-- **ui-designer/analysis.md** → UI/Frontend tasks
-- **ux-expert/analysis.md** → UX/Interaction tasks
-- **system-architect/analysis.md** → Architecture/Backend tasks
-- **subject-matter-expert/analysis.md** → Domain/Standards tasks
-- **data-architect/analysis.md** → Data/API tasks
-- **scrum-master/analysis.md** → Sprint/Process tasks
-- **product-owner/analysis.md** → Backlog/Story tasks
-
-### Phase 4: IMPL_PLAN.md Generation
-
-#### Document Structure
 ```markdown
 ---
 identifier: WFS-{session-id}
@@ -365,9 +346,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - **Timeline**: Duration and milestones
 
 ### Module Structure
-```
+'''
 [Directory tree showing key modules]
-```
+'''
 
 ### Dependencies
 **Primary**: [Core libraries and frameworks]
@@ -442,9 +423,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 ### Key Dependencies
 **Task Dependency Graph**:
-```
+'''
 [High-level dependency visualization]
-```
+'''
 
 **Critical Path**: [Identify bottleneck tasks]
 
@@ -542,9 +523,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - [ ] [Key business metrics from synthesis]
 ```
 
-### Phase 5: TODO_LIST.md Generation
+### 6.3. TODO_LIST.md Structure
+A simple Markdown file for tracking the status of each task.
 
-#### Document Structure
 ```markdown
 # Tasks: [Session Topic]
 
@@ -562,12 +543,8 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - Maximum 2 levels: Main tasks and subtasks only
 ```
 
-### Phase 6: Session State Update
-1. Update workflow-session.json with task count and artifacts
-2. Validate all output files (task JSONs, IMPL_PLAN.md, TODO_LIST.md)
-3. Generate completion report
-
-## Output Files Structure
+### 6.4. Output Files Diagram
+The command organizes outputs into a standard directory structure.
 ```
 .workflow/{session-id}/
 ├── IMPL_PLAN.md                     # Implementation plan
@@ -585,7 +562,201 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
     └── context-package.json         # Input from context-gather
 ```
 
-## Error Handling
+## 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.
+
+#### 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.
+
+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.
+
+## 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
 
 ### Input Validation Errors
 | Error | Cause | Resolution |
@@ -608,7 +779,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 | Invalid format | Corrupted file | Skip artifact loading |
 | Path invalid | Moved/deleted | Update references |
 
-## Integration & Usage
+## 10. Integration & Usage
 
 ### Command Chain
 - **Called By**: `/workflow:plan` (Phase 4)
@@ -620,82 +791,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 /workflow:tools:task-generate --session WFS-auth
 ```
 
-## CLI Execute Mode Examples
-
-### Example 1: First Task (Establish Session)
-```json
-{
-  "id": "IMPL-001",
-  "title": "Implement user authentication module",
-  "context": {
-    "depends_on": [],
-    "focus_paths": ["src/auth"],
-    "requirements": ["JWT-based authentication", "Login and registration endpoints"]
-  },
-  "flow_control": {
-    "implementation_approach": [{
-      "step": 1,
-      "title": "Execute implementation with Codex",
-      "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication module TASK: JWT-based authentication with login and registration MODE: auto CONTEXT: @{.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)",
-      "depends_on": [],
-      "output": "implementation"
-    }]
-  }
-}
-```
-
-### Example 2: Subsequent Task (Resume Session)
-```json
-{
-  "id": "IMPL-002",
-  "title": "Add password reset functionality",
-  "context": {
-    "depends_on": ["IMPL-001"],
-    "focus_paths": ["src/auth"],
-    "requirements": ["Password reset via email", "Token validation"]
-  },
-  "flow_control": {
-    "implementation_approach": [{
-      "step": 1,
-      "title": "Execute implementation with Codex",
-      "command": "bash(codex --full-auto exec \"PURPOSE: Add password reset functionality TASK: Password reset via email with token validation MODE: auto CONTEXT: Previous auth implementation from session EXPECTED: Password reset endpoints with email integration RULES: Maintain consistency with existing auth patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
-      "depends_on": [],
-      "output": "implementation"
-    }]
-  }
-}
-```
-
-### Example 3: Third Task (Continue Session)
-```json
-{
-  "id": "IMPL-003",
-  "title": "Implement role-based access control",
-  "context": {
-    "depends_on": ["IMPL-001", "IMPL-002"],
-    "focus_paths": ["src/auth"],
-    "requirements": ["User roles and permissions", "Middleware for route protection"]
-  },
-  "flow_control": {
-    "implementation_approach": [{
-      "step": 1,
-      "title": "Execute implementation with Codex",
-      "command": "bash(codex --full-auto exec \"PURPOSE: Implement role-based access control TASK: User roles, permissions, and route protection middleware MODE: auto CONTEXT: Existing auth system from session EXPECTED: RBAC system integrated with current auth RULES: Use established patterns from session context\" resume --last --skip-git-repo-check -s danger-full-access)",
-      "depends_on": [],
-      "output": "implementation"
-    }]
-  }
-}
-```
-
-**Pattern Summary**:
-- IMPL-001: Fresh start with `-C src/auth` and full prompt
-- IMPL-002: Resume with `resume --last`, references "previous auth implementation"
-- IMPL-003: Resume with `resume --last`, references "existing auth system"
-
-## Related Commands
+## 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:execute` - Executes generated tasks
+- `/workflow:execute` - Executes generated tasks

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

@@ -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-task-generate.md

@@ -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"
     }],
@@ -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,11 +354,11 @@ 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]",

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

@@ -0,0 +1,677 @@
+---
+name: animation-extract
+description: Extract animation and transition patterns from URLs, CSS, or interactive questioning
+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(*)
+---
+
+# Animation Extraction Command
+
+## Overview
+
+Extract animation and transition patterns from web pages using CSS extraction, visual analysis, or interactive questioning. This command generates production-ready animation tokens and guidelines that integrate with design systems.
+
+**Strategy**: Hybrid Extraction with Interactive Fallback
+
+- **Auto Mode (Priority 1)**: Extract from CSS via Chrome DevTools when URLs provided
+- **Visual Mode (Priority 2)**: Analyze screenshots for motion cues (blur, position changes)
+- **Interactive Mode (Priority 3)**: Guided questioning when extraction insufficient
+- **Output**: `animation-tokens.json` + `animation-guide.md`
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input Mode & Base Path
+
+```bash
+# Detect input source
+# Priority: --urls → url mode | --mode interactive → question mode
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+    primary_url = url_list[0].url
+ELSE:
+    has_urls = false
+
+# Determine extraction mode
+extraction_mode = --mode OR (has_urls ? "auto" : "interactive")
+
+# Parse animation focus (if provided)
+IF --focus:
+    focus_types = split(--focus, ",")  # e.g., "transitions,hover,scroll"
+ELSE:
+    focus_types = ["all"]  # Extract all animation types
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Design Tokens Context
+
+```bash
+# Load existing design tokens for duration/easing alignment
+IF exists({base_path}/style-extraction/style-1/design-tokens.json):
+    design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
+    has_design_context = true
+ELSE:
+    has_design_context = false
+    WARN: "⚠️ No design tokens found - animation tokens will use standalone values"
+
+# Create output directory
+bash(mkdir -p {base_path}/animation-extraction)
+bash(mkdir -p {base_path}/.intermediates/animation-analysis)
+```
+
+---
+
+**Phase 0 Output**: `extraction_mode`, `base_path`, `has_urls`, `url_list[]`, `focus_types[]`, `has_design_context`
+
+## Phase 1: CSS Animation Extraction (Auto Mode - URL Required)
+
+### Step 1: Check Extraction Mode
+
+```bash
+# extraction_mode == "interactive" → skip to Phase 2
+# extraction_mode == "auto" AND has_urls → execute this phase
+```
+
+**If interactive mode**: Skip to Phase 2
+
+### Step 2: Extract Computed Animations (Auto-Trigger)
+
+```bash
+# AUTO-TRIGGER: If URLs are available, automatically extract CSS animations/transitions
+
+IF has_urls AND mcp_chrome_devtools_available:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting CSS animations and transitions"
+
+    # Read extraction script
+    script_content = Read(~/.claude/scripts/extract-animations.js)
+
+    # For each URL:
+    FOR url_info IN url_list:
+        target = url_info.target
+        url = url_info.url
+
+        REPORT: "   Processing: {target} ({url})"
+
+        # Open page in Chrome DevTools
+        mcp__chrome-devtools__navigate_page(url=url)
+
+        # Wait for page to fully load and animations to initialize
+        bash(sleep 2)
+
+        # Execute extraction script
+        result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+        # Save raw animation data
+        Write({base_path}/.intermediates/animation-analysis/animations-{target}.json, result)
+
+        REPORT: "   ✅ Extracted: {result.summary.total_animations} animations, {result.summary.total_transitions} transitions"
+
+    animations_extracted = true
+    REPORT: "   ✅ CSS animation extraction complete"
+ELSE IF has_urls AND NOT mcp_chrome_devtools_available:
+    animations_extracted = false
+    REPORT: "⚠️ Chrome DevTools MCP not available"
+    REPORT: "   Falling back to interactive mode for animation guidance"
+ELSE:
+    animations_extracted = false
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-animations.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `transitions`: Array of transition definitions (property, duration, easing, delay)
+- `animations`: Array of keyframe animations (name, duration, easing, keyframes)
+- `transforms`: Common transform patterns
+- `summary`: Statistics (total_animations, total_transitions, unique_easings)
+
+**Benefits**:
+- ✅ Real animation values from production sites
+- ✅ Captures all CSS transitions and @keyframes rules
+- ✅ Identifies common easing functions and durations
+- ✅ Maps animations to element selectors
+
+---
+
+**Phase 1 Output**: `animations-{target}.json` (intermediate files)
+
+## Phase 2: Interactive Animation Specification (Interactive/Fallback Mode)
+
+### Step 1: Check if Extraction Sufficient
+
+```bash
+# If animations extracted from CSS, check coverage
+IF animations_extracted:
+    total_animations = sum([data.summary.total_animations for data in all_extracted])
+    total_transitions = sum([data.summary.total_transitions for data in all_extracted])
+
+    # If sufficient data found, skip interactive mode
+    IF total_animations >= 3 OR total_transitions >= 5:
+        REPORT: "✅ Sufficient animation data extracted from CSS"
+        SKIP to Phase 3
+    ELSE:
+        REPORT: "⚠️ Limited animation data found - launching interactive mode"
+        extraction_insufficient = true
+ELSE:
+    extraction_insufficient = true
+```
+
+### Step 2: Interactive Question Workflow (Agent)
+
+```bash
+# If extraction failed or insufficient, use interactive questioning
+IF extraction_insufficient OR extraction_mode == "interactive":
+    REPORT: "🤔 Launching interactive animation specification mode"
+
+    # Launch ui-design-agent for interactive questioning
+    Task(ui-design-agent): `
+      [ANIMATION_SPECIFICATION_TASK]
+      Guide user through animation design decisions via structured questions
+
+      SESSION: {session_id} | MODE: interactive | BASE_PATH: {base_path}
+
+      ## Context
+      - Design tokens available: {has_design_context}
+      - Focus areas: {focus_types}
+      - Extracted data: {animations_extracted ? "Partial CSS data available" : "No CSS data"}
+
+      ## Interactive Workflow
+
+      For each animation category, ASK user and WAIT for response:
+
+      ### 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)
+
+      ### 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)
+
+      ### 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)
+
+      ### 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"
+
+      ### 5. Loading States
+      QUESTION: "What loading animation style?"
+      OPTIONS:
+        - "Spinner" (rotating circle)
+        - "Pulse" (opacity pulse)
+        - "Skeleton" (shimmer effect)
+        - "Progress Bar" (linear fill)
+        - "Custom" (describe)
+
+      ### 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"
+
+      ### 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"
+
+      ## Output Generation
+
+      Based on user responses, generate structured data:
+
+      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}
+
+      2. Write to {base_path}/.intermediates/animation-analysis/animation-specification.json
+
+      ## 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
+    `
+```
+
+---
+
+**Phase 2 Output**: `animation-specification.json` (user preferences)
+
+## Phase 3: Animation Token Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)` for token generation
+
+### Step 1: Load All Input Sources
+
+```bash
+# Gather all available animation data
+extracted_animations = []
+IF animations_extracted:
+    FOR target IN target_list:
+        IF exists({base_path}/.intermediates/animation-analysis/animations-{target}.json):
+            extracted_animations.append(Read(file))
+
+user_specification = null
+IF exists({base_path}/.intermediates/animation-analysis/animation-specification.json):
+    user_specification = Read(file)
+
+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
+
+```javascript
+Task(ui-design-agent): `
+  [ANIMATION_TOKEN_GENERATION_TASK]
+  Synthesize all animation data into production-ready animation tokens
+
+  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"}
+
+  ## Synthesis Rules
+
+  ### Priority System
+  1. User specification (highest priority)
+  2. Extracted CSS values (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
+  - 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
+
+  ### 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
+
+  ## Generate Files
+
+  ### 1. animation-tokens.json
+  Complete animation token structure:
+
+  {
+    "duration": {
+      "instant": "0ms",
+      "fast": "150ms",
+      "normal": "300ms",
+      "slow": "500ms",
+      "very-slow": "800ms"
+    },
+    "easing": {
+      "linear": "linear",
+      "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+      "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+      "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+    },
+    "transitions": {
+      "color": {
+        "property": "color, background-color, border-color",
+        "duration": "var(--duration-fast)",
+        "easing": "var(--easing-ease-out)"
+      },
+      "transform": {
+        "property": "transform",
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-out)"
+      },
+      "opacity": {
+        "property": "opacity",
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-in-out)"
+      }
+    },
+    "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"}
+      }
+    },
+    "interactions": {
+      "button-hover": {
+        "properties": ["background-color", "transform"],
+        "duration": "var(--duration-fast)",
+        "easing": "var(--easing-ease-out)",
+        "transform": "scale(1.02)"
+      },
+      "card-hover": {
+        "properties": ["box-shadow", "transform"],
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-out)",
+        "transform": "translateY(-4px)"
+      }
+    },
+    "page_transitions": {
+      "fade": {
+        "duration": "var(--duration-normal)",
+        "enter": "fadeIn",
+        "exit": "fadeOut"
+      }
+    },
+    "scroll_animations": {
+      "default": {
+        "animation": "fadeInUp",
+        "duration": "var(--duration-slow)",
+        "easing": "var(--easing-ease-out)",
+        "threshold": "0.1",
+        "stagger_delay": "100ms"
+      }
+    }
+  }
+
+  ### 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
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for both files
+  - ✅ Ensure all tokens use CSS Custom Property format: var(--duration-fast)
+  - ✅ Include prefers-reduced-motion media query guidance
+  - ✅ Validate all cubic-bezier values are valid
+  - ❌ NO external research or MCP calls
+`
+```
+
+---
+
+**Phase 3 Output**: `animation-tokens.json` + `animation-guide.md`
+
+## Phase 4: Verify Output
+
+### Step 1: Check Files Created
+
+```bash
+# Verify animation tokens created
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+bash(test -f {base_path}/animation-extraction/animation-guide.md && echo "exists")
+
+# Validate structure
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "easing" && echo "valid")
+```
+
+### Step 2: Verify File Sizes
+
+```bash
+bash(ls -lh {base_path}/animation-extraction/)
+```
+
+**Output**: 2 files verified (animation-tokens.json, animation-guide.md)
+
+## Completion
+
+### Todo Update
+
+```javascript
+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: "Verify output files", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+### Output Message
+
+```
+✅ Animation extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (auto/interactive)
+- Input Sources:
+  {IF animations_extracted:
+  - ✅ CSS extracted from {len(url_list)} URL(s)
+  }
+  {IF user_specification:
+  - ✅ User specification via interactive mode
+  }
+  {IF has_design_context:
+  - ✅ Aligned with existing design tokens
+  }
+
+Generated Files:
+{base_path}/animation-extraction/
+├── animation-tokens.json      # Production-ready animation tokens
+└── animation-guide.md          # Usage guidelines and examples
+
+{IF animations_extracted:
+Intermediate Analysis:
+{base_path}/.intermediates/animation-analysis/
+├── animations-*.json           # Extracted CSS data ({len(url_list)} files)
+}
+{IF user_specification:
+└── animation-specification.json # User preferences
+}
+
+Extracted Data Summary:
+- Duration scales: {duration_count} values
+- Easing functions: {easing_count} types
+- Interaction presets: {interaction_count} patterns
+- Keyframe animations: {keyframe_count} animations
+
+Next: Animation tokens ready for integration
+  • style-extract/layout-extract can reference animation tokens
+  • generate command will include animation CSS
+  • Tokens use var() format for easy customization
+```
+
+## Simple Bash Commands
+
+### Path Operations
+
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create output directories
+bash(mkdir -p {base_path}/animation-extraction)
+bash(mkdir -p {base_path}/.intermediates/animation-analysis)
+```
+
+### Validation Commands
+
+```bash
+# Check if already extracted
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+
+# Validate JSON structure
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
+
+# Count animation types
+bash(cat animation-tokens.json | grep -c "\"keyframes\":")
+```
+
+### File Operations
+
+```bash
+# Load design tokens context
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && cat it)
+
+# Verify output
+bash(ls {base_path}/animation-extraction/)
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                  # Intermediate analysis files
+│   └── animation-analysis/
+│       ├── animations-{target}.json      # Extracted CSS (auto mode)
+│       └── animation-specification.json  # User input (interactive mode)
+└── animation-extraction/            # Final animation tokens
+    ├── animation-tokens.json        # Production-ready animation tokens
+    └── animation-guide.md            # Usage guide and examples
+```
+
+## animation-tokens.json Format
+
+```json
+{
+  "duration": {
+    "instant": "0ms",
+    "fast": "150ms",
+    "normal": "300ms",
+    "slow": "500ms",
+    "very-slow": "800ms"
+  },
+  "easing": {
+    "linear": "linear",
+    "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+    "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+    "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+    "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+  },
+  "transitions": {
+    "color": {"property": "...", "duration": "var(--duration-fast)", "easing": "..."},
+    "transform": {"property": "...", "duration": "...", "easing": "..."}
+  },
+  "keyframes": {
+    "fadeIn": {"0%": {...}, "100%": {...}},
+    "slideInUp": {...}
+  },
+  "interactions": {
+    "button-hover": {"properties": [...], "duration": "...", "transform": "..."},
+    "card-hover": {...}
+  },
+  "page_transitions": {...},
+  "scroll_animations": {...}
+}
+```
+
+**Requirements**: CSS var() format, valid cubic-bezier values, prefers-reduced-motion support
+
+## Error Handling
+
+### Common Errors
+
+```
+ERROR: No URL or interactive mode specified
+→ Provide --urls for auto mode or use --mode interactive
+
+ERROR: Chrome DevTools unavailable
+→ Automatically falls back to interactive mode
+
+ERROR: Insufficient animation data extracted
+→ Launches interactive mode for supplemental input
+
+ERROR: Invalid cubic-bezier values
+→ Validates and corrects to nearest standard easing
+```
+
+### Recovery Strategies
+
+- **CSS extraction failure**: Falls back to interactive mode
+- **Partial extraction**: Supplements with interactive questioning
+- **Invalid data**: Validates and uses fallback values
+
+## Key Features
+
+- **Auto-Trigger CSS Extraction** - Automatically extracts animations when --urls provided
+- **Hybrid Strategy** - Combines CSS extraction with interactive specification
+- **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
+
+## Integration
+
+**Workflow Position**: Between style extraction and layout extraction (or parallel)
+
+**New Workflow**:
+1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
+2. **`/workflow:ui-design:animation-extract`** → `animation-tokens.json` + `animation-guide.md` (NEW)
+3. `/workflow:ui-design:layout-extract` → `layout-templates.json`
+4. `/workflow:ui-design:generate`:
+   - Reads: design-tokens.json + animation-tokens.json + layout-templates.json
+   - Generates: Prototypes with animation CSS included
+
+**Input**: URLs (auto mode) or interactive questioning
+**Output**: `animation-tokens.json` + `animation-guide.md`
+**Next**: `/workflow:ui-design:layout-extract` OR `/workflow:ui-design:generate`
+
+**Note**: This command extracts motion design patterns (animations, transitions) to complement visual style tokens. Can run in parallel with layout-extract.

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

@@ -47,48 +47,49 @@ ELSE:
     bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
 
 # Get variant counts
-style_variants = --style-variants OR bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+style_variants = --style-variants OR bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 layout_variants = --layout-variants OR 3
 ```
 
 **Output**: `base_path`, `target_list[]`, `target_type`, `device_type`, `style_variants`, `layout_variants`
 
-### Step 2: Detect Token Sources
+### Step 2: Validate Design Tokens
 ```bash
-# Check consolidated (priority 1) or proposed (priority 2)
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "consolidated")
-# OR
-bash(test -f {base_path}/style-extraction/style-cards.json && echo "proposed")
+# Check design tokens exist
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
 
-# If proposed: Create temp consolidation dirs + write tokens
-FOR style_id IN 1..style_variants:
-    bash(mkdir -p {base_path}/style-consolidation/style-{style_id})
-    Write({base_path}/style-consolidation/style-{style_id}/design-tokens.json, proposed_tokens)
-
-# Load design space analysis (optional)
-IF exists({base_path}/style-extraction/design-space-analysis.json):
-    design_space_analysis = Read({base_path}/style-extraction/design-space-analysis.json)
+# Load design space analysis (optional, from intermediates)
+IF exists({base_path}/.intermediates/style-analysis/design-space-analysis.json):
+    design_space_analysis = Read({base_path}/.intermediates/style-analysis/design-space-analysis.json)
 ```
 
-**Output**: `token_sources{}`, `consolidated_count`, `proposed_count`, `design_space_analysis`
+**Output**: `design_tokens_valid`, `design_space_analysis`
 
-### Step 3: Gather Layout Inspiration
+### Step 3: Gather Layout Inspiration (Reuse or Create)
 ```bash
-bash(mkdir -p {base_path}/prototypes/_inspirations)
+# Check if layout inspirations already exist from layout-extract phase
+inspiration_source = "{base_path}/.intermediates/layout-analysis/inspirations"
 
-# For each target: Research via MCP
 FOR target IN target_list:
-    search_query = "{target} {target_type} layout patterns variations"
-    mcp__exa__web_search_exa(query=search_query, numResults=5)
+    # Priority 1: Reuse existing inspiration from layout-extract
+    IF exists({inspiration_source}/{target}-layout-ideas.txt):
+        # Reuse existing inspiration (no action needed)
+        REPORT: "Using existing layout inspiration for {target}"
+    ELSE:
+        # Priority 2: Generate new inspiration via MCP
+        bash(mkdir -p {inspiration_source})
+        search_query = "{target} {target_type} layout patterns variations"
+        mcp__exa__web_search_exa(query=search_query, numResults=5)
 
-    # Extract context from prompt for this target
-    target_requirements = extract_relevant_context_from_prompt(prompt_text, target)
+        # Extract context from prompt for this target
+        target_requirements = extract_relevant_context_from_prompt(prompt_text, target)
 
-    # Write simple inspiration file
-    Write({base_path}/prototypes/_inspirations/{target}-layout-ideas.txt, inspiration_content)
+        # Write inspiration file to centralized location
+        Write({inspiration_source}/{target}-layout-ideas.txt, inspiration_content)
+        REPORT: "Created new layout inspiration for {target}"
 ```
 
-**Output**: `T` inspiration text files
+**Output**: `T` inspiration text files (reused or created in `.intermediates/layout-analysis/inspirations/`)
 
 ## Phase 2: Target-Style-Centric Batch Generation (Agent)
 
@@ -126,8 +127,8 @@ Task(ui-design-agent): `
   ${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""}
 
   ## Reference
-  - Layout inspiration: Read("{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt")
-  - Design tokens: Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
+  - 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)
   ${design_attributes ? "- Adapt DOM to: density, visual_weight, formality, organic_vs_geometric" : ""}
 
@@ -242,18 +243,19 @@ Quality:
 - Style-aware: {design_space_analysis ? 'HTML adapts to design_attributes' : 'Standard structure'}
 - CSS: Self-contained (direct token values, no var())
 - Device-optimized: {device_type} layouts
-- Tokens: {consolidated_count} consolidated, {proposed_count} proposed
-{IF proposed_count > 0: '  💡 For production: /workflow:ui-design:consolidate'}
+- Tokens: Production-ready (WCAG AA compliant)
 
 Generated Files:
 {base_path}/prototypes/
-├── _inspirations/ ({T} text files)
 ├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
 ├── {target}-style-{s}-layout-{l}.css
 ├── compare.html (interactive matrix)
 ├── index.html (navigation)
 └── PREVIEW.md (instructions)
 
+Layout Inspirations:
+{base_path}/.intermediates/layout-analysis/inspirations/ ({T} text files, reused or created)
+
 Preview:
 1. Open compare.html (recommended)
 2. Open index.html
@@ -270,11 +272,10 @@ Next: /workflow:ui-design:update
 bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
 
 # Count style variants
-bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 
-# Check token sources
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "consolidated")
-bash(test -f {base_path}/style-extraction/style-cards.json && echo "proposed")
+# Check design tokens exist
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
 ```
 
 ### Validation Commands
@@ -288,8 +289,11 @@ bash(test -f {base_path}/prototypes/compare.html && echo "exists")
 
 ### File Operations
 ```bash
-# Create directories
-bash(mkdir -p {base_path}/prototypes/_inspirations)
+# Create prototypes directory
+bash(mkdir -p {base_path}/prototypes)
+
+# Create inspirations directory (if needed)
+bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
 
 # Run preview script
 bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
@@ -299,15 +303,17 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 
 ```
 {base_path}/
+├── .intermediates/
+│   └── layout-analysis/
+│       └── inspirations/
+│           └── {target}-layout-ideas.txt  # Layout inspiration (reused or created)
 ├── prototypes/
-│   ├── _inspirations/
-│   │   └── {target}-layout-ideas.txt  # Layout inspiration
 │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
 │   ├── {target}-style-{s}-layout-{l}.css
 │   ├── compare.html
 │   ├── index.html
 │   └── PREVIEW.md
-└── style-consolidation/
+└── style-extraction/
     └── style-{s}/
         ├── design-tokens.json
         └── style-guide.md
@@ -317,8 +323,8 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 
 ### Common Errors
 ```
-ERROR: No token sources found
-→ Run /workflow:ui-design:extract or /workflow:ui-design:consolidate
+ERROR: No design tokens found
+→ Run /workflow:ui-design:style-extract first
 
 ERROR: No targets extracted from prompt
 → Use --targets explicitly or rephrase prompt
@@ -364,9 +370,14 @@ ERROR: Script permission denied
 
 ## Integration
 
-**Input**: Prompt, design-tokens.json, design-space-analysis.json (optional)
+**Input**:
+- Required: Prompt, design-tokens.json
+- Optional: design-space-analysis.json (from `.intermediates/style-analysis/`)
+- Reuses: Layout inspirations from `.intermediates/layout-analysis/inspirations/` (if available from layout-extract)
+
 **Output**: S×L×T prototypes for `/workflow:ui-design:update`
-**Compatible**: extract, consolidate, explore-auto, imitate-auto outputs
+**Compatible**: style-extract, explore-auto, imitate-auto outputs
+**Optimization**: Reuses layout inspirations from layout-extract phase, avoiding duplicate MCP searches
 
 ## Usage Examples
 

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

@@ -1,267 +0,0 @@
----
-name: consolidate
-description: Consolidate style variants into independent design systems and plan layout strategies
-argument-hint: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
-allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
----
-
-# Design System Consolidation Command
-
-## Overview
-Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `style-extract` into finalized design tokens and style guides.
-
-**Strategy**: Philosophy-Driven Refinement
-- **Agent-Driven**: Uses ui-design-agent for N variant generation
-- **Token Refinement**: Transforms proposed_tokens into complete systems
-- **Production-Ready**: design-tokens.json + style-guide.md per variant
-- **Matrix-Ready**: Provides style variants for generate phase
-
-## Phase 1: Setup & Validation
-
-### Step 1: Resolve Base Path & Load Style Cards
-```bash
-# Determine base path
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
-# OR use --base-path / --session parameters
-
-# Load style cards
-bash(cat {base_path}/style-extraction/style-cards.json)
-```
-
-### Step 2: Memory Check (Skip if Already Done)
-```bash
-# Check if already consolidated
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "exists")
-```
-
-**If exists**: Skip to completion message
-
-### Step 3: Select Variants
-```bash
-# Determine variant count (default: all from style-cards.json)
-bash(cat style-cards.json | grep -c "\"id\": \"variant-")
-
-# Validate variant count
-# Priority: --variants parameter → total_variants from style-cards.json
-```
-
-**Output**: `variants_count`, `selected_variants[]`
-
-### Step 4: Load Design Context (Optional)
-```bash
-# Load brainstorming context
-bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
-
-# Load design space analysis
-bash(test -f {base_path}/style-extraction/design-space-analysis.json && cat it)
-```
-
-**Output**: `design_context`, `design_space_analysis`
-
-## Phase 2: Design System Synthesis (Agent)
-
-**Executor**: `Task(ui-design-agent)` for all variants
-
-### Step 1: Create Output Directories
-```bash
-bash(mkdir -p {base_path}/style-consolidation/style-{{1..{variants_count}}})
-```
-
-### Step 2: Launch Agent Task
-For all variants (1 to {variants_count}):
-```javascript
-Task(ui-design-agent): `
-  [DESIGN_TOKEN_GENERATION_TASK]
-  Generate {variants_count} independent design systems using philosophy-driven refinement
-
-  SESSION: {session_id} | MODE: Philosophy-driven refinement | BASE_PATH: {base_path}
-
-  CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
-
-  VARIANT DATA:
-  {FOR each variant with index N:
-    VARIANT INDEX: {N} | ID: {variant.id} | NAME: {variant.name}
-    Design Philosophy: {variant.design_philosophy}
-    Proposed Tokens: {variant.proposed_tokens}
-    {IF design_space_analysis: Design Attributes: {attributes}, Anti-keywords: {anti_keywords}}
-  }
-
-  ## 参考
-  - Style cards: Each variant's proposed_tokens and design_philosophy
-  - Design space analysis: design_attributes (saturation, weight, formality, organic/geometric, innovation, density)
-  - Anti-keywords: Explicit constraints to avoid
-  - WCAG AA: 4.5:1 text, 3:1 UI (use built-in AI knowledge)
-
-  ## 生成
-  For EACH variant (use loop index N for paths):
-  1. {base_path}/style-consolidation/style-{N}/design-tokens.json
-     - Complete token structure: colors, typography, spacing, border_radius, shadows, breakpoints
-     - All colors in OKLCH format
-     - Apply design_attributes to token values (saturation→chroma, density→spacing, etc.)
-
-  2. {base_path}/style-consolidation/style-{N}/style-guide.md
-     - Expanded design philosophy
-     - Complete color system with accessibility notes
-     - Typography documentation
-     - Usage guidelines
-
-  ## 注意
-  - ✅ Use Write() tool immediately for each file
-  - ✅ Use loop index N for directory names: style-1/, style-2/, etc.
-  - ❌ DO NOT use variant.id in paths (metadata only)
-  - ❌ NO external research or MCP calls (pure AI refinement)
-  - Apply philosophy-driven refinement: design_attributes guide token values
-  - Maintain divergence: Use anti_keywords to prevent variant convergence
-  - Complete each variant's files before moving to next variant
-`
-```
-
-**Output**: Agent generates `variants_count × 2` files
-
-## Phase 3: Verify Output
-
-### Step 1: Check Files Created
-```bash
-# Verify all design systems created
-bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
-
-# Validate structure
-bash(cat {base_path}/style-consolidation/style-1/design-tokens.json | grep -q "colors" && echo "valid")
-```
-
-### Step 2: Verify File Sizes
-```bash
-bash(ls -lh {base_path}/style-consolidation/style-1/)
-```
-
-**Output**: `variants_count × 2` files verified
-
-## Completion
-
-### Todo Update
-```javascript
-TodoWrite({todos: [
-  {content: "Setup and load style cards", status: "completed", activeForm: "Loading style cards"},
-  {content: "Select variants and load context", status: "completed", activeForm: "Loading context"},
-  {content: "Generate design systems (agent)", status: "completed", activeForm: "Generating systems"},
-  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
-]});
-```
-
-### Output Message
-```
-✅ Design system consolidation complete!
-
-Configuration:
-- Session: {session_id}
-- Variants: {variants_count}
-- Philosophy-driven refinement (zero MCP calls)
-
-Generated Files:
-{base_path}/style-consolidation/
-├── style-1/ (design-tokens.json, style-guide.md)
-├── style-2/ (same structure)
-└── style-{variants_count}/ (same structure)
-
-Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --targets "dashboard,auth"
-```
-
-## Simple Bash Commands
-
-### Path Operations
-```bash
-# Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
-
-# Load style cards
-bash(cat {base_path}/style-extraction/style-cards.json)
-
-# Count variants
-bash(cat style-cards.json | grep -c "\"id\": \"variant-")
-```
-
-### Validation Commands
-```bash
-# Check if already consolidated
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "exists")
-
-# Verify output
-bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
-
-# Validate structure
-bash(cat design-tokens.json | grep -q "colors" && echo "valid")
-```
-
-### File Operations
-```bash
-# Create directories
-bash(mkdir -p {base_path}/style-consolidation/style-{{1..3}})
-
-# Check file sizes
-bash(ls -lh {base_path}/style-consolidation/style-1/)
-```
-
-## Output Structure
-
-```
-{base_path}/
-└── style-consolidation/
-    ├── style-1/
-    │   ├── design-tokens.json
-    │   └── style-guide.md
-    ├── style-2/
-    │   ├── design-tokens.json
-    │   └── style-guide.md
-    └── style-N/ (same structure)
-```
-
-## design-tokens.json Format
-
-```json
-{
-  "colors": {
-    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
-    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
-    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
-    "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": {...}},
-  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
-  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
-  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
-  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
-}
-```
-
-**Requirements**: OKLCH colors, complete coverage, semantic naming
-
-## Error Handling
-
-### Common Errors
-```
-ERROR: No style cards found
-→ Run /workflow:ui-design:style-extract first
-
-ERROR: Invalid variant count
-→ List available count, auto-select all
-
-ERROR: Agent file creation failed
-→ Check agent output, verify Write() operations
-```
-
-## Key Features
-
-- **Philosophy-Driven Refinement** - Pure AI token refinement using design_attributes
-- **Agent-Driven** - Uses ui-design-agent for multi-file generation
-- **Separate Design Systems** - N independent systems (one per variant)
-- **Production-Ready** - WCAG AA compliant, OKLCH colors, semantic naming
-- **Zero MCP Calls** - Faster execution, better divergence preservation
-
-## Integration
-
-**Input**: `style-cards.json` from `/workflow:ui-design:style-extract`
-**Output**: `style-consolidation/style-{N}/` for each variant
-**Next**: `/workflow:ui-design:generate --style-variants N`
-
-**Note**: After consolidate, use `/workflow:ui-design:layout-extract` to generate layout templates before running generate.

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

@@ -20,7 +20,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 1. User triggers: `/workflow:ui-design:explore-auto [params]`
 2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
 3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
-4. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
+4. Phase 2.3 (animation-extract, optional) → **WAIT for completion** → Auto-continues
 5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
 6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
 7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
@@ -91,8 +91,8 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 **Matrix Mode** (style-centric):
 - Generates `style_variants × layout_variants × targets` prototypes
-- **Phase 1**: `style_variants` style options with design_attributes (extract)
-- **Phase 2**: `style_variants` independent design systems (consolidate)
+- **Phase 1**: `style_variants` complete design systems (extract)
+- **Phase 2**: Layout templates extraction (layout-extract)
 - **Phase 3**: Style-centric batch generation (generate)
   - Sub-phase 1: `targets × layout_variants` target-specific layout plans
   - **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
@@ -277,16 +277,21 @@ SlashCommand(command)
 
 # Output: {style_variants} style cards with design_attributes
 # SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2 (auto-continue)
+# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue)
 ```
 
-### Phase 2: Style Consolidation
+### Phase 2.3: Animation Extraction (Optional - Interactive Mode)
 ```bash
-command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
-          "--variants {style_variants}"
+# Animation extraction for motion design patterns
+REPORT: "🚀 Phase 2.3: Animation Extraction (interactive mode)"
+REPORT: "   → Mode: Interactive specification"
+REPORT: "   → Purpose: Define motion design patterns"
+
+command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
+
 SlashCommand(command)
 
-# Output: {style_variants} independent design systems with tokens.css
+# Output: animation-tokens.json + animation-guide.md
 # SlashCommand blocks until phase complete
 # Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
 ```
@@ -360,7 +365,6 @@ IF --batch-plan:
 // Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
 TodoWrite({todos: [
   {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
-  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
   {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
   {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
   {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
@@ -442,9 +446,8 @@ Architecture: Style-Centric Batch Generation
 Run ID: {run_id} | Session: {session_id or "standalone"}
 Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
 
-Phase 1: {s} style variants with design_attributes (style-extract)
-Phase 2: {s} design systems with tokens.css (consolidate)
-Phase 2.5: {n×l} layout templates (layout-extract explore mode)
+Phase 1: {s} complete design systems (style-extract)
+Phase 2: {n×l} layout templates (layout-extract explore mode)
   - Device: {device_type} layouts
   - {n} targets × {l} layout variants = {n×l} structural templates
 Phase 3: UI Assembly (generate)
@@ -466,11 +469,13 @@ Design Quality:
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 📂 {base_path}/
-  ├── style-extraction/       ({s} style cards + design-space-analysis.json)
-  ├── style-consolidation/    ({s} design systems with tokens.css)
-  ├── layout-extraction/      ({n×l} layout templates + layout-space-analysis.json)
-  ├── prototypes/             ({total} assembled prototypes)
-  └── .run-metadata.json      (includes device type)
+  ├── .intermediates/          (Intermediate analysis files)
+  │   ├── style-analysis/      (computed-styles.json, design-space-analysis.json)
+  │   └── layout-analysis/     (dom-structure-*.json, inspirations/*.txt)
+  ├── style-extraction/        ({s} complete design systems)
+  ├── layout-extraction/       ({n×l} layout templates + layout-space-analysis.json)
+  ├── prototypes/              ({total} assembled prototypes)
+  └── .run-metadata.json       (includes device type)
 
 🌐 Preview: {base_path}/prototypes/compare.html
   - Interactive {s}×{l} matrix view

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

@@ -18,8 +18,7 @@ Pure assembler that combines pre-extracted layout templates with design tokens t
 - **Automatic Image Reference**: If source images exist in layout templates, they're automatically used for visual context
 
 **Prerequisite Commands**:
-- `/workflow:ui-design:style-extract` → Style tokens
-- `/workflow:ui-design:consolidate` → Final design tokens
+- `/workflow:ui-design:style-extract` → Complete design systems (design-tokens.json + style-guide.md)
 - `/workflow:ui-design:layout-extract` → Layout structure
 
 ## Phase 1: Setup & Validation
@@ -30,7 +29,7 @@ Pure assembler that combines pre-extracted layout templates with design tokens t
 bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
 
 # Get style count
-bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 
 # Image reference auto-detected from layout template source_image_path
 ```
@@ -50,14 +49,29 @@ Read({base_path}/layout-extraction/layout-templates.json)
 ### Step 3: Validate Design Tokens
 ```bash
 # Check design tokens exist for all styles
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
 
 # For each style variant: Load design tokens
-Read({base_path}/style-consolidation/style-{id}/design-tokens.json)
+Read({base_path}/style-extraction/style-{id}/design-tokens.json)
 ```
 
 **Output**: `design_tokens[]` for all style variants
 
+### Step 4: Load Animation Tokens (Optional)
+```bash
+# Check if animation tokens exist
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+
+# Load animation tokens if available
+IF exists({base_path}/animation-extraction/animation-tokens.json):
+    animation_tokens = Read({base_path}/animation-extraction/animation-tokens.json)
+    has_animations = true
+ELSE:
+    has_animations = false
+```
+
+**Output**: `animation_tokens` (optional), `has_animations` flag
+
 ## Phase 2: Assembly (Agent)
 
 **Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
@@ -84,10 +98,18 @@ Task(ui-design-agent): `
      Extract: dom_structure, css_layout_rules, device_type, source_image_path
 
   2. Design Tokens:
-     Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
+     Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
      Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
 
-  3. Reference Image (AUTO-DETECTED):
+  3. Animation Tokens (OPTIONAL):
+     IF exists("{base_path}/animation-extraction/animation-tokens.json"):
+       Read("{base_path}/animation-extraction/animation-tokens.json")
+       Extract: duration, easing, transitions, keyframes, interactions
+       has_animations = true
+     ELSE:
+       has_animations = false
+
+  4. Reference Image (AUTO-DETECTED):
      IF template.source_image_path exists:
        Read(template.source_image_path)
        Purpose: Additional visual context for better placeholder content generation
@@ -116,6 +138,14 @@ Task(ui-design-agent): `
        * Typography: tokens.typography.*
        * Shadows: tokens.shadows.*
        * Border radius: tokens.border_radius.*
+     - IF has_animations == true: Inject animation tokens
+       * Add CSS Custom Properties for animations at :root level:
+         --duration-instant, --duration-fast, --duration-normal, etc.
+         --easing-linear, --easing-ease-out, etc.
+       * Add @keyframes rules from animation_tokens.keyframes
+       * Add interaction classes (.button-hover, .card-hover) from animation_tokens.interactions
+       * Add utility classes (.transition-color, .transition-transform) from animation_tokens.transitions
+       * Include prefers-reduced-motion media query for accessibility
      - Device-optimized for template.device_type
 
   ## Assembly Rules
@@ -192,7 +222,7 @@ Assembly Process:
 
 Quality:
 - Structure: From layout-extract (DOM, CSS layout rules)
-- Style: From consolidate (design tokens)
+- Style: From style-extract (design tokens)
 - CSS: Token values directly applied (var() replaced)
 - Device-optimized: Layouts match device_type from templates
 
@@ -222,7 +252,7 @@ Next: /workflow:ui-design:update
 bash(find .workflow -type d -name "design-*" | head -1)
 
 # Count style variants
-bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 ```
 
 ### Validation Commands
@@ -231,7 +261,7 @@ bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
 bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
 
 # Check design tokens exist
-bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
 
 # Count generated files
 bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
@@ -255,9 +285,9 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 {base_path}/
 ├── layout-extraction/
 │   └── layout-templates.json      # Input (from layout-extract)
-├── style-consolidation/
+├── style-extraction/
 │   └── style-{s}/
-│       ├── design-tokens.json     # Input (from consolidate)
+│       ├── design-tokens.json     # Input (from style-extract)
 │       └── style-guide.md
 └── prototypes/
     ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
@@ -275,7 +305,7 @@ ERROR: Layout templates not found
 → Run /workflow:ui-design:layout-extract first
 
 ERROR: Design tokens not found
-→ Run /workflow:ui-design:consolidate first
+→ Run /workflow:ui-design:style-extract first
 
 ERROR: Agent assembly failed
 → Check inputs exist, validate JSON structure
@@ -311,8 +341,7 @@ ERROR: Script permission denied
 ## Integration
 
 **Prerequisites**:
-- `/workflow:ui-design:style-extract` → `style-cards.json`
-- `/workflow:ui-design:consolidate` → `design-tokens.json`
+- `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
 - `/workflow:ui-design:layout-extract` → `layout-templates.json`
 
 **Input**: `layout-templates.json` + `design-tokens.json`

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

@@ -1,7 +1,7 @@
 ---
 name: imitate-auto
-description: High-speed multi-page UI replication with batch screenshot and optional token refinement
-argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
+description: High-speed multi-page UI replication with batch screenshot capture
+argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt "<desc>"]
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ---
 
@@ -19,11 +19,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 1. User triggers: `/workflow:ui-design:imitate-auto --url-map "..."`
 2. Phase 0: Initialize and parse parameters
 3. Phase 1: Screenshot capture (batch or deep mode) → **WAIT for completion** → Auto-continues
-4. Phase 2: Style extraction (visual tokens) → **WAIT for completion** → Auto-continues
-5. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
-6. Phase 3: Token processing (conditional consolidate) → **WAIT for completion** → Auto-continues
-7. Phase 4: Batch UI assembly → **WAIT for completion** → Auto-continues
-8. Phase 5: Design system integration → Reports completion
+4. Phase 2: Style extraction (complete design systems) → **WAIT for completion** → Auto-continues
+5. Phase 2.3: Animation extraction (CSS auto mode) → **WAIT for completion** → Auto-continues
+6. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
+7. Phase 3: Batch UI assembly → **WAIT for completion** → Auto-continues
+8. Phase 4: Design system integration → Reports completion
 
 **Phase Transition Mechanism**:
 - `SlashCommand` is BLOCKING - execution pauses until completion
@@ -67,13 +67,10 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
   - Enable automatic design system integration (Phase 5)
   - If not provided: standalone mode (`.workflow/.design/`)
 
-- `--refine-tokens` (Optional, default: false): Enable full token refinement
-  - `false` (default): Fast path, skip consolidate (~30-60s faster)
-  - `true`: Production quality, execute full consolidate (philosophy-driven refinement)
-
 - `--prompt "<desc>"` (Optional): Style extraction guidance
   - Influences extract command analysis focus
   - Example: `"Focus on dark mode"`, `"Emphasize minimalist design"`
+  - **Note**: Design systems are now production-ready by default (no separate consolidate step)
 
 ## Execution Modes
 
@@ -86,14 +83,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
   - Captures page layers at different depths (1-5)
   - Only processes first URL from url-map
 
-**Token Processing Modes**:
-- **Fast-Track** (default): Skip consolidate, use proposed tokens directly (~2s)
-  - Best for rapid prototyping and testing
-  - Tokens may lack philosophy-driven refinement
-- **Production** (--refine-tokens): Full consolidate with WCAG validation (~60s)
-  - Philosophy-driven token refinement
-  - Complete accessibility validation
-  - Production-ready design system
+**Token Processing**:
+- **Direct Generation**: Complete design systems generated in style-extract phase
+  - Production-ready design-tokens.json with WCAG compliance
+  - Complete style-guide.md documentation
+  - No separate consolidation step required (~30-60s faster)
 
 **Session Integration**:
 - `--session` flag determines session integration or standalone execution
@@ -105,19 +99,6 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ### Phase 0: Initialization and Target Parsing
 
 ```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 UI Design Imitate-Auto"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-# Constants
-DEPTH_NAMES = {
-    1: "Page level",
-    2: "Element level",
-    3: "Interaction level",
-    4: "Embedded level",
-    5: "Shadow DOM"
-}
-
 # Generate run ID
 run_id = "run-$(date +%Y%m%d-%H%M%S)"
 
@@ -126,12 +107,10 @@ IF --session:
     session_id = {provided_session}
     base_path = ".workflow/WFS-{session_id}/design-{run_id}"
     session_mode = "integrated"
-    REPORT: "Mode: Integrated (Session: {session_id})"
 ELSE:
     session_id = null
     base_path = ".workflow/.design/{run_id}"
     session_mode = "standalone"
-    REPORT: "Mode: Standalone"
 
 # Create base directory
 Bash(mkdir -p "{base_path}")
@@ -163,7 +142,6 @@ FOR pair IN split(url_map_string, ","):
 VALIDATE: len(target_names) > 0, "url-map must contain at least one target:url pair"
 
 primary_target = target_names[0]  # First target as primary style source
-refine_tokens_mode = --refine-tokens OR false
 
 # Parse capture mode
 capture_mode = --capture-mode OR "batch"
@@ -198,7 +176,6 @@ metadata = {
         "url_map": url_map,
         "capture_mode": capture_mode,
         "depth": depth IF capture_mode == "deep" ELSE null,
-        "refine_tokens": refine_tokens_mode,
         "prompt": --prompt OR null
     },
     "targets": target_names,
@@ -207,28 +184,13 @@ metadata = {
 
 Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
 
-REPORT: ""
-REPORT: "Configuration:"
-REPORT: "  Capture mode: {capture_mode}"
-IF capture_mode == "deep":
-    REPORT: "    Depth level: {depth} ({DEPTH_NAMES[depth]})"
-    REPORT: "    Target: '{primary_target}' ({url_map[primary_target]})"
-ELSE:
-    REPORT: "    Targets: {len(target_names)} pages"
-    REPORT: "    Primary source: '{primary_target}' ({url_map[primary_target]})"
-    REPORT: "    All targets: {', '.join(target_names)}"
-REPORT: "  Token refinement: {refine_tokens_mode ? 'Enabled (production quality)' : 'Disabled (fast-track)'}"
-IF --prompt:
-    REPORT: "  Prompt guidance: \"{--prompt}\""
-REPORT: ""
-
 # Initialize TodoWrite
 TodoWrite({todos: [
   {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
   {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "pending", activeForm: "Capturing screenshots"},
-  {content: "Extract style (visual tokens)", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract style (complete design systems)", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract animation (CSS auto mode)", status: "pending", activeForm: "Extracting animation"},
   {content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
-  {content: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation (skip consolidate)", status: "pending", activeForm: "Processing tokens"},
   {content: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
   {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
 ]})
@@ -238,22 +200,14 @@ TodoWrite({todos: [
 
 ```bash
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: f"🚀 Phase 1: Screenshot Capture ({capture_mode} mode)"
+REPORT: "🚀 Phase 1: Screenshot Capture"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 IF capture_mode == "batch":
     # Mode A: Batch Multi-URL Capture
-    REPORT: "Using batch capture for multiple URLs..."
-
-    # Build url-map string for capture command
     url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
-
-    # Call capture command
     capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
 
-    REPORT: f"  Command: {capture_command}"
-    REPORT: f"  Targets: {len(target_names)}"
-
     TRY:
         SlashCommand(capture_command)
     CATCH error:
@@ -274,34 +228,19 @@ IF capture_mode == "batch":
     total_requested = screenshot_metadata.total_requested
     missing_count = total_requested - captured_count
 
-    REPORT: ""
-    REPORT: "✅ Batch capture complete:"
-    REPORT: "   Captured: {captured_count}/{total_requested} screenshots ({(captured_count/total_requested*100):.1f}%)"
-
     IF missing_count > 0:
         missing_targets = [s.target for s in screenshot_metadata.screenshots if not s.captured]
-        WARN: "   ⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
-        WARN: "   Proceeding with available screenshots for extract phase"
+        WARN: "⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
 
-    # If all screenshots failed, terminate
     IF captured_count == 0:
         ERROR: "No screenshots captured - cannot proceed"
-        ERROR: "Please check URLs and tool availability"
         EXIT 1
 
 ELSE:  # capture_mode == "deep"
     # Mode B: Deep Interactive Layer Exploration
-    REPORT: "Using deep exploration for single URL..."
-
     primary_url = url_map[primary_target]
-
-    # Call explore-layers command
     explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
 
-    REPORT: f"  Command: {explore_command}"
-    REPORT: f"  URL: {primary_url}"
-    REPORT: f"  Depth: {depth} ({DEPTH_NAMES[depth]})"
-
     TRY:
         SlashCommand(explore_command)
     CATCH error:
@@ -318,16 +257,7 @@ ELSE:  # capture_mode == "deep"
         EXIT 1
 
     layer_map = Read(layer_map_path)
-    total_layers = len(layer_map.layers)
     captured_count = layer_map.summary.total_captures
-
-    REPORT: ""
-    REPORT: "✅ Deep exploration complete:"
-    REPORT: "   Layers: {total_layers} (depth 1-{depth})"
-    REPORT: "   Captures: {captured_count} screenshots"
-    REPORT: "   Total size: {layer_map.summary.total_size_kb:.1f} KB"
-
-    # Count actual images for extract phase
     total_requested = captured_count  # For consistency with batch mode
 
 TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} targets)" IF capture_mode == "batch" ELSE f"Deep exploration (depth {depth})",
@@ -337,31 +267,29 @@ TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} target
 ### Phase 2: Style Extraction (Visual Tokens)
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2: Extract Style (Visual Tokens)"
+REPORT: "🚀 Phase 2: Style Extraction"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 # 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}}"  # Include all depth directories
+    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 (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency. User guidance: {user_guidance}"
+    extraction_prompt = f"Extract visual style tokens from '{primary_target}'. User guidance: {user_guidance}"
 ELSE:
-    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency across all pages."
+    extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
+
+# 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()])
 
 # Call style-extract command (imitate mode, automatically uses single variant)
-extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --prompt \"{extraction_prompt}\" --mode imitate"
-
-REPORT: "Calling style-extract command..."
-REPORT: f"  Mode: imitate (high-fidelity single style, auto variants=1)"
-REPORT: f"  Primary source: '{primary_target}'"
-REPORT: f"  Images: {images_glob}"
+# 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:
     SlashCommand(extract_command)
@@ -370,53 +298,64 @@ CATCH error:
     ERROR: "Cannot proceed without visual tokens"
     EXIT 1
 
-# style-extract outputs to: {base_path}/style-extraction/style-cards.json
-
 # Verify extraction results
-style_cards_path = "{base_path}/style-extraction/style-cards.json"
+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(style_cards_path):
-    ERROR: "style-extract command did not generate style-cards.json"
-    ERROR: "Expected: {style_cards_path}"
+IF NOT exists(design_tokens_path) OR NOT exists(style_guide_path):
+    ERROR: "style-extract did not generate required files"
     EXIT 1
 
-style_cards = Read(style_cards_path)
+TodoWrite(mark_completed: "Extract style (complete design systems)",
+          mark_in_progress: "Extract animation (CSS auto mode)")
+```
 
-IF len(style_cards.style_cards) != 1:
-    ERROR: "Expected single variant in imitate mode, got {len(style_cards.style_cards)}"
+### Phase 2.3: Animation Extraction (CSS Auto Mode)
+
+```bash
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 2.3: Animation Extraction"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# 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:
+    SlashCommand(animation_extract_command)
+CATCH error:
+    ERROR: "Animation extraction failed: {error}"
+    ERROR: "Cannot proceed without animation tokens"
     EXIT 1
 
-extracted_style = style_cards.style_cards[0]
+# Verify animation extraction results
+animation_tokens_path = "{base_path}/animation-extraction/animation-tokens.json"
+animation_guide_path = "{base_path}/animation-extraction/animation-guide.md"
 
-REPORT: ""
-REPORT: "✅ Phase 2 complete:"
-REPORT: "   Style: '{extracted_style.name}'"
-REPORT: "   Philosophy: {extracted_style.design_philosophy}"
-REPORT: "   Tokens: {count_tokens(extracted_style.proposed_tokens)} visual tokens"
+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 style (visual tokens)",
+TodoWrite(mark_completed: "Extract animation (CSS auto mode)",
           mark_in_progress: "Extract layout (structure templates)")
 ```
 
 ### Phase 2.5: Layout Extraction (Structure Templates)
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 2.5: Extract Layout (Structure Templates)"
+REPORT: "🚀 Phase 2.5: Layout Extraction"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
-# Reuse same screenshots for layout extraction
-# Build URL map for layout-extract (uses first URL from each target)
+# 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)
-layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --targets \"{','.join(target_names)}\" --mode imitate"
-
-REPORT: "Calling layout-extract command..."
-REPORT: f"  Mode: imitate (high-fidelity structure replication)"
-REPORT: f"  Targets: {', '.join(target_names)}"
-REPORT: f"  Images: {images_glob}"
+# 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:
     SlashCommand(layout_extract_command)
@@ -425,155 +364,27 @@ CATCH error:
     ERROR: "Cannot proceed without layout templates"
     EXIT 1
 
-# layout-extract outputs to: {base_path}/layout-extraction/layout-templates.json
-
 # Verify layout extraction results
 layout_templates_path = "{base_path}/layout-extraction/layout-templates.json"
 
 IF NOT exists(layout_templates_path):
-    ERROR: "layout-extract command did not generate layout-templates.json"
-    ERROR: "Expected: {layout_templates_path}"
+    ERROR: "layout-extract did not generate layout-templates.json"
     EXIT 1
 
-layout_templates = Read(layout_templates_path)
-template_count = len(layout_templates.layout_templates)
-
-REPORT: ""
-REPORT: "✅ Phase 2.5 complete:"
-REPORT: "   Templates: {template_count} layout structures"
-REPORT: "   Targets: {', '.join(target_names)}"
-
 TodoWrite(mark_completed: "Extract layout (structure templates)",
-          mark_in_progress: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation")
-```
-
-### Phase 3: Token Processing (Conditional Consolidate)
-
-```bash
-REPORT: ""
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 3: Token Processing"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-IF refine_tokens_mode:
-    # Path A: Full consolidate (production quality)
-    REPORT: "🔧 Using full consolidate for production-ready tokens"
-    REPORT: "   Benefits:"
-    REPORT: "   • Philosophy-driven token refinement"
-    REPORT: "   • WCAG AA accessibility validation"
-    REPORT: "   • Complete design system documentation"
-    REPORT: "   • Token gap filling and consistency checks"
-    REPORT: ""
-
-    consolidate_command = f"/workflow:ui-design:consolidate --base-path \"{base_path}\" --variants 1"
-
-    REPORT: f"Calling consolidate command..."
-
-    TRY:
-        SlashCommand(consolidate_command)
-    CATCH error:
-        ERROR: "Token consolidation failed: {error}"
-        ERROR: "Cannot proceed without refined tokens"
-        EXIT 1
-
-    # consolidate outputs to: {base_path}/style-consolidation/style-1/design-tokens.json
-    tokens_path = "{base_path}/style-consolidation/style-1/design-tokens.json"
-
-    IF NOT exists(tokens_path):
-        ERROR: "consolidate command did not generate design-tokens.json"
-        ERROR: "Expected: {tokens_path}"
-        EXIT 1
-
-    REPORT: ""
-    REPORT: "✅ Full consolidate complete"
-    REPORT: "   Output: style-consolidation/style-1/"
-    REPORT: "   Quality: Production-ready"
-    token_quality = "production-ready (consolidated)"
-    time_spent_estimate = "~60s"
-
-ELSE:
-    # Path B: Fast Token Adaptation
-    REPORT: "⚡ Fast token adaptation (skipping consolidate for speed)"
-    REPORT: "   Note: Using proposed tokens from extraction phase"
-    REPORT: "   For production quality, re-run with --refine-tokens flag"
-    REPORT: ""
-
-    # Directly copy proposed_tokens to consolidation directory
-    style_cards = Read("{base_path}/style-extraction/style-cards.json")
-    proposed_tokens = style_cards.style_cards[0].proposed_tokens
-
-    # Create directory and write tokens
-    consolidation_dir = "{base_path}/style-consolidation/style-1"
-    Bash(mkdir -p "{consolidation_dir}")
-
-    tokens_path = f"{consolidation_dir}/design-tokens.json"
-    Write(tokens_path, JSON.stringify(proposed_tokens, null, 2))
-
-    # Create simplified style guide
-    variant = style_cards.style_cards[0]
-    simple_guide = f"""# Design System: {variant.name}
-
-## Design Philosophy
-{variant.design_philosophy}
-
-## Description
-{variant.description}
-
-## Design Tokens
-All tokens in `design-tokens.json` follow OKLCH color space.
-
-**Note**: Generated in fast-track imitate mode using proposed tokens from extraction.
-For production-ready quality with philosophy-driven refinement, re-run with `--refine-tokens` flag.
-
-## Color Preview
-- Primary: {variant.preview.primary if variant.preview else "N/A"}
-- Background: {variant.preview.background if variant.preview else "N/A"}
-
-## Typography Preview
-- Heading Font: {variant.preview.font_heading if variant.preview else "N/A"}
-
-## Token Categories
-{list_token_categories(proposed_tokens)}
-"""
-
-    Write(f"{consolidation_dir}/style-guide.md", simple_guide)
-
-    REPORT: "✅ Fast adaptation complete (~2s vs ~60s with consolidate)"
-    REPORT: "   Output: style-consolidation/style-1/"
-    REPORT: "   Quality: Proposed (not refined)"
-    REPORT: "   Time saved: ~30-60s"
-    token_quality = "proposed (fast-track)"
-    time_spent_estimate = "~2s"
-
-REPORT: ""
-REPORT: "Token processing summary:"
-REPORT: "   Path: {refine_tokens_mode ? 'Full consolidate' : 'Fast adaptation'}"
-REPORT: "   Quality: {token_quality}"
-REPORT: "   Time: {time_spent_estimate}"
-
-TodoWrite(mark_completed: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation",
           mark_in_progress: f"Assemble UI for {len(target_names)} targets")
 ```
 
-### Phase 4: Batch UI Assembly
+### Phase 3: Batch UI Assembly
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 4: Batch UI Assembly"
+REPORT: "🚀 Phase 3: UI Assembly"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
-# Build targets string
-targets_string = ",".join(target_names)
-
-# Call generate command (now pure assembler - combines layout templates + design tokens)
+# 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"
 
-REPORT: "Calling generate command (pure assembler)..."
-REPORT: f"  Targets: {targets_string} (from layout templates)"
-REPORT: f"  Configuration: 1 style × 1 layout × {len(target_names)} pages"
-REPORT: f"  Inputs: layout-templates.json + design-tokens.json"
-
 TRY:
     SlashCommand(generate_command)
 CATCH error:
@@ -581,54 +392,33 @@ CATCH error:
     ERROR: "Layout templates or design tokens may be invalid"
     EXIT 1
 
-# generate outputs to: {base_path}/prototypes/{target}-style-1-layout-1.html
-
 # 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)
 
-REPORT: ""
-REPORT: "✅ Phase 4 complete:"
-REPORT: "   Assembled: {generated_count} HTML prototypes"
-REPORT: "   Targets: {', '.join(target_names)}"
-REPORT: "   Output: {prototypes_dir}/"
-
 IF generated_count < len(target_names):
-    WARN: "   ⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
-    WARN: "   Some targets may have failed - check generate output"
+    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")
 ```
 
-### Phase 5: Design System Integration
+### Phase 4: Design System Integration
 
 ```bash
-REPORT: ""
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 5: Design System Integration"
+REPORT: "🚀 Phase 4: Design System Integration"
 REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 IF session_id:
-    REPORT: "Integrating design system into session {session_id}..."
-
     update_command = f"/workflow:ui-design:update --session {session_id}"
 
     TRY:
         SlashCommand(update_command)
     CATCH error:
-        WARN: "Design system integration failed: {error}"
-        WARN: "Prototypes are still available at {base_path}/prototypes/"
-        # Don't terminate, prototypes already generated
-
-    REPORT: "✅ Design system integrated into session {session_id}"
-ELSE:
-    REPORT: "ℹ️ Standalone mode: Skipping integration"
-    REPORT: "   Prototypes available at: {base_path}/prototypes/"
-    REPORT: "   To integrate later:"
-    REPORT: "   1. Create a workflow session"
-    REPORT: "   2. Copy design-tokens.json to session artifacts"
+        WARN: "⚠️ Design system integration failed: {error}"
+        WARN: "Prototypes available at {base_path}/prototypes/"
 
 # Update metadata
 metadata = Read("{base_path}/.run-metadata.json")
@@ -636,9 +426,8 @@ metadata.status = "completed"
 metadata.completion_time = current_timestamp()
 metadata.outputs = {
     "screenshots": f"{base_path}/screenshots/",
-    "style_system": f"{base_path}/style-consolidation/style-1/",
+    "style_system": f"{base_path}/style-extraction/style-1/",
     "prototypes": f"{base_path}/prototypes/",
-    "token_quality": token_quality,
     "captured_count": captured_count,
     "generated_count": generated_count
 }
@@ -650,9 +439,10 @@ TodoWrite(mark_completed: session_id ? "Integrate design system" : "Standalone c
 TodoWrite({todos: [
   {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
   {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "completed", activeForm: "Capturing"},
-  {content: "Extract unified design system", status: "completed", activeForm: "Extracting"},
-  {content: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation", status: "completed", activeForm: "Processing"},
-  {content: f"Generate UI for {len(target_names)} targets", status: "completed", activeForm: "Generating"},
+  {content: "Extract style (complete design systems)", status: "completed", activeForm: "Extracting"},
+  {content: "Extract animation (CSS auto mode)", status: "completed", activeForm: "Extracting animation"},
+  {content: "Extract layout (structure templates)", status: "completed", activeForm: "Extracting layout"},
+  {content: f"Assemble UI for {len(target_names)} targets", status: "completed", activeForm: "Assembling"},
   {content: session_id ? "Integrate design system" : "Standalone completion", status: "completed", activeForm: "Completing"}
 ]})
 ```
@@ -674,24 +464,22 @@ Run ID: {run_id}
 Phase 1 - Screenshot Capture: ✅ {IF capture_mode == "batch": f"{captured_count}/{total_requested} screenshots" ELSE: f"{captured_count} screenshots ({total_layers} layers)"}
   {IF capture_mode == "batch" AND captured_count < total_requested: f"⚠️ {total_requested - captured_count} missing" ELSE: "All targets captured"}
 
-Phase 2 - Style Extraction: ✅ Single unified design system
-  Style: {extracted_style.name}
-  Philosophy: {extracted_style.design_philosophy[:80]}...
+Phase 2 - Style Extraction: ✅ Production-ready design systems
+  Output: style-extraction/style-1/ (design-tokens.json + style-guide.md)
+  Quality: WCAG AA compliant, OKLCH colors
 
-Phase 3 - Token Processing: ✅ {token_quality}
-  {IF refine_tokens_mode:
-    "Full consolidate (~60s)"
-    "Quality: Production-ready with philosophy-driven refinement"
-  ELSE:
-    "Fast adaptation (~2s, saved ~30-60s)"
-    "Quality: Proposed tokens (for production, use --refine-tokens)"
-  }
+Phase 2.3 - Animation Extraction: ✅ CSS animations and transitions
+  Output: animation-extraction/ (animation-tokens.json + animation-guide.md)
+  Method: Auto-extracted from live URLs via Chrome DevTools
 
-Phase 4 - UI Generation: ✅ {generated_count} pages generated
+Phase 2.5 - Layout Extraction: ✅ Structure templates
+  Templates: {template_count} layout structures
+
+Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
   Targets: {', '.join(target_names)}
   Configuration: 1 style × 1 layout × {generated_count} pages
 
-Phase 5 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
+Phase 4 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
 
 ━━━ 📂 Output Structure ━━━
 
@@ -710,12 +498,15 @@ ELSE:
 │   │   └── {layers}.png
 │   └── layer-map.json
 }
-├── style-extraction/               # Design analysis
-│   └── style-cards.json
-├── style-consolidation/            # {token_quality}
+├── style-extraction/               # Production-ready design systems
 │   └── style-1/
 │       ├── design-tokens.json
 │       └── style-guide.md
+├── animation-extraction/           # CSS animations and transitions
+│   ├── animation-tokens.json
+│   └── animation-guide.md
+├── layout-extraction/              # Structure templates
+│   └── layout-templates.json
 └── prototypes/                     # {generated_count} HTML/CSS files
     ├── {target1}-style-1-layout-1.html + .css
     ├── {target2}-style-1-layout-1.html + .css
@@ -750,13 +541,6 @@ ELSE:
 3. Explore prototypes in {base_path}/prototypes/ directory
 }
 
-{IF NOT refine_tokens_mode:
-💡 Production Quality Tip:
-   Fast-track mode used proposed tokens for speed.
-   For production-ready quality with full token refinement:
-   /workflow:ui-design:imitate-auto --url-map "{url_map_command_string}" --refine-tokens {f"--session {session_id}" if session_id else ""}
-}
-
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -767,9 +551,9 @@ ELSE:
 TodoWrite({todos: [
   {content: "Initialize and parse url-map", status: "in_progress", activeForm: "Initializing"},
   {content: "Batch screenshot capture", status: "pending", activeForm: "Capturing screenshots"},
-  {content: "Extract unified design system", status: "pending", activeForm: "Extracting style"},
-  {content: refine_tokens ? "Refine tokens via consolidate" : "Fast token adaptation", status: "pending", activeForm: "Processing tokens"},
-  {content: "Generate UI for all targets", status: "pending", activeForm: "Generating UI"},
+  {content: "Extract style (complete design systems)", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
+  {content: "Assemble UI for all targets", status: "pending", activeForm: "Assembling UI"},
   {content: "Integrate design system", status: "pending", activeForm: "Integrating"}
 ]})
 
@@ -818,7 +602,7 @@ TodoWrite({todos: [
 ## Key Features
 
 - **🚀 Dual Capture**: Batch mode for speed, deep mode for detail
-- **⚡ Fast-Track Option**: Skip consolidate for 30-60s time savings
+- **⚡ Production-Ready**: Complete design systems generated directly (~30-60s faster)
 - **🎨 High-Fidelity**: Single unified design system from primary target
 - **📦 Autonomous**: No user intervention required between phases
 - **🔄 Reproducible**: Deterministic flow with isolated run directories
@@ -832,10 +616,10 @@ TodoWrite({todos: [
 # Result: 2 prototypes with fast-track tokens
 ```
 
-### 2. Production-Ready with Session
+### 2. Session Integration
 ```bash
-/workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing" --refine-tokens
-# Result: 1 prototype with production tokens, integrated into session
+/workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing"
+# Result: 1 prototype with production-ready design system, integrated into session
 ```
 
 ### 3. Deep Exploration Mode
@@ -852,16 +636,17 @@ TodoWrite({todos: [
 
 ## Integration Points
 
-- **Input**: `--url-map` (multiple target:url pairs) + optional `--capture-mode`, `--depth`, `--session`, `--refine-tokens`, `--prompt`
-- **Output**: Complete design system in `{base_path}/` (screenshots, style-extraction, style-consolidation, prototypes)
+- **Input**: `--url-map` (multiple target:url pairs) + optional `--capture-mode`, `--depth`, `--session`, `--prompt`
+- **Output**: Complete design system in `{base_path}/` (screenshots, style-extraction, layout-extraction, prototypes)
 - **Sub-commands Called**:
   1. Phase 1 (conditional):
      - `--capture-mode batch`: `/workflow:ui-design:capture` (multi-URL batch)
      - `--capture-mode deep`: `/workflow:ui-design:explore-layers` (single-URL depth exploration)
-  2. `/workflow:ui-design:extract` (Phase 2)
-  3. `/workflow:ui-design:consolidate` (Phase 3, conditional)
-  4. `/workflow:ui-design:generate` (Phase 4)
-  5. `/workflow:ui-design:update` (Phase 5, if --session)
+  2. `/workflow:ui-design:style-extract` (Phase 2 - complete design systems)
+  3. `/workflow:ui-design:animation-extract` (Phase 2.3 - CSS animations and transitions)
+  4. `/workflow:ui-design:layout-extract` (Phase 2.5 - structure templates)
+  5. `/workflow:ui-design:generate` (Phase 3 - pure assembly)
+  6. `/workflow:ui-design:update` (Phase 4, if --session)
 
 ## Completion Output
 
@@ -872,20 +657,20 @@ Mode: {capture_mode} | Session: {session_id or "standalone"}
 Run ID: {run_id}
 
 Phase 1 - Screenshot Capture: ✅ {captured_count} screenshots
-Phase 2 - Style Extraction: ✅ Single unified design system
-Phase 3 - Token Processing: ✅ {token_quality}
-Phase 4 - UI Generation: ✅ {generated_count} pages generated
-Phase 5 - Integration: {IF session_id: "✅ Integrated" ELSE: "⏭️ Standalone"}
+Phase 2 - Style Extraction: ✅ Production-ready design systems
+Phase 2.5 - Layout Extraction: ✅ Structure templates
+Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
+Phase 4 - Integration: {IF session_id: "✅ Integrated" ELSE: "⏭️ Standalone"}
 
 Design Quality:
 ✅ High-Fidelity Replication: Accurate style from primary target
 ✅ Token-Driven Styling: 100% var() usage
-✅ {IF refine_tokens: "Production-Ready: WCAG validated" ELSE: "Fast-Track: Proposed tokens"}
+✅ Production-Ready: WCAG AA compliant, OKLCH colors
 
 📂 {base_path}/
   ├── screenshots/                  # {captured_count} screenshots
-  ├── style-extraction/             # Design analysis
-  ├── style-consolidation/          # {token_quality}
+  ├── style-extraction/style-1/     # Production-ready design system
+  ├── layout-extraction/            # Structure templates
   └── prototypes/                   # {generated_count} HTML/CSS files
 
 🌐 Preview: {base_path}/prototypes/compare.html

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

@@ -8,9 +8,11 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design
 # Layout Extraction Command
 
 ## Overview
+
 Extract structural layout information from reference images, URLs, or text prompts using AI analysis. This command separates the "scaffolding" (HTML structure and CSS layout) from the "paint" (visual tokens handled by `style-extract`).
 
 **Strategy**: AI-Driven Structural Analysis
+
 - **Agent-Powered**: Uses `ui-design-agent` for deep structural analysis
 - **Dual-Mode**:
   - `imitate`: High-fidelity replication of single layout structure
@@ -22,10 +24,27 @@ Extract structural layout information from reference images, URLs, or text promp
 ## Phase 0: Setup & Input Validation
 
 ### Step 1: Detect Input, Mode & Targets
+
 ```bash
 # Detect input source
 # Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
 
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            # Single URL without target
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+ELSE:
+    has_urls = false
+    url_list = []
+
 # Determine extraction mode
 extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
 
@@ -37,8 +56,15 @@ ELSE IF extraction_mode == "explore":
     VALIDATE: 1 <= variants_count <= 5
 
 # Resolve targets
-# Priority: --targets → prompt analysis → default ["page"]
-targets = --targets OR extract_from_prompt(--prompt) OR ["page"]
+# Priority: --targets → url_list targets → prompt analysis → default ["page"]
+IF --targets:
+    targets = split(--targets, ",")
+ELSE IF has_urls:
+    targets = [url_info.target for url_info in url_list]
+ELSE IF --prompt:
+    targets = extract_from_prompt(--prompt)
+ELSE:
+    targets = ["page"]
 
 # Resolve device type
 device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
@@ -65,17 +91,112 @@ Read({image_path})  # Load each image
 bash(mkdir -p {base_path}/layout-extraction)
 ```
 
-### Step 3: Memory Check (Skip if Already Done)
+### Step 2.5: Extract DOM Structure (URL Mode - Auto-Trigger)
 ```bash
-# Check if layouts already extracted
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# AUTO-TRIGGER: If URLs are available (from --urls parameter), automatically extract real DOM structure
+# This provides accurate layout data to supplement visual analysis
+
+# Check if URLs provided via --urls parameter
+IF --urls AND url_list:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting DOM structure"
+
+    bash(mkdir -p {base_path}/.intermediates/layout-analysis)
+
+    # For each URL in url_list:
+    FOR url_info IN url_list:
+        target = url_info.target
+        url = url_info.url
+
+        IF mcp_chrome_devtools_available:
+            REPORT: "   Processing: {target} ({url})"
+
+            # Read extraction script
+            script_content = Read(~/.claude/scripts/extract-layout-structure.js)
+
+            # Open page in Chrome DevTools
+            mcp__chrome-devtools__navigate_page(url=url)
+
+            # Execute layout extraction script
+            result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+            # Save DOM structure for this target (intermediate file)
+            Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
+
+            REPORT: "   ✅ DOM structure extracted for '{target}'"
+        ELSE:
+            REPORT: "   ⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
+            BREAK
+
+    dom_structure_available = mcp_chrome_devtools_available
+ELSE:
+    dom_structure_available = false
 ```
 
-**If exists**: Skip to completion message
+**Extraction Script Reference**: `~/.claude/scripts/extract-layout-structure.js`
 
-**Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
 
-## Phase 1: Layout Research (Explore Mode Only)
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method, version
+- `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
+- `structure`: Hierarchical DOM tree with layout properties
+- `exploration`: (Optional) Progressive exploration results when standard selectors fail
+
+**Benefits**:
+- ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
+- ✅ Accurate element bounds (x, y, width, height)
+- ✅ Structural hierarchy with depth control
+- ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
+- ✅ Progressive exploration: Auto-discovers missing selectors
+
+**Progressive Exploration Strategy** (v2.2.0+):
+
+When script finds <3 main containers, it automatically:
+1. **Scans** all large visible containers (≥500×300px)
+2. **Extracts** class patterns matching: `main|content|wrapper|container|page|layout|app`
+3. **Suggests** new selectors to add to script
+4. **Returns** exploration data in `result.exploration`:
+   ```json
+   {
+     "triggered": true,
+     "discoveredCandidates": [{classes, bounds, display}],
+     "suggestedSelectors": [".wrapper", ".page-index"],
+     "recommendation": ".wrapper, .page-index, .app-container"
+   }
+   ```
+
+**Using Exploration Results**:
+```javascript
+// After extraction, check for suggestions
+IF result.exploration?.triggered:
+    REPORT: result.exploration.warning
+    REPORT: "Suggested selectors: " + result.exploration.recommendation
+
+    // Update script by adding to commonClassSelectors array
+    // Then re-run extraction for better coverage
+```
+
+**Selector Update Workflow**:
+1. Run extraction on unfamiliar site
+2. Check `result.exploration.suggestedSelectors`
+3. Add relevant selectors to script's `commonClassSelectors`
+4. Re-run extraction → improved container detection
+
+### Step 3: Memory Check
+```bash
+# 1. Check if inputs cached in session memory
+IF session_has_inputs: SKIP Step 2 file reading
+
+# 2. Check if output already exists
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+IF exists: SKIP to completion
+```
+
+---
+
+**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+
+## Phase 1: Layout Concept Generation (Explore Mode Only)
 
 ### Step 1: Check Extraction Mode
 ```bash
@@ -87,83 +208,320 @@ bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists
 
 ### Step 2: Gather Layout Inspiration (Explore Mode)
 ```bash
-bash(mkdir -p {base_path}/layout-extraction/_inspirations)
+bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
 
 # For each target: Research via MCP
 # mcp__exa__web_search_exa(query="{target} layout patterns {device_type}", numResults=5)
 
 # Write inspiration file
-Write({base_path}/layout-extraction/_inspirations/{target}-layout-ideas.txt, inspiration_content)
+Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, inspiration_content)
 ```
 
-**Output**: Inspiration text files for each target (explore mode only)
-
-## Phase 2: Layout Analysis & Synthesis (Agent)
-
+### Step 3: Generate Layout Concept Options (Agent Task 1)
 **Executor**: `Task(ui-design-agent)`
 
-### Step 1: Launch Agent Task
+Launch agent to generate `variants_count` layout concept options for each target:
+
 ```javascript
 Task(ui-design-agent): `
-  [LAYOUT_EXTRACTION_TASK]
-  Analyze references and extract structural layout templates.
+  [LAYOUT_CONCEPT_GENERATION_TASK]
+  Generate {variants_count} structurally distinct layout concepts for each target
+
+  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+  TARGETS: {targets} | DEVICE_TYPE: {device_type}
+
+  ## Input Analysis
+  - Targets: {targets.join(", ")}
+  - Device type: {device_type}
+  - Layout inspiration: Read inspirations from {base_path}/.intermediates/layout-analysis/inspirations/
+  - Visual references: {loaded_images if available}
+  ${dom_structure_available ? "- DOM Structure: Read from .intermediates/layout-analysis/dom-structure-*.json" : ""}
+
+  ## Analysis Rules
+  - For EACH target, generate {variants_count} structurally DIFFERENT layout concepts
+  - Concepts must differ in: grid structure, component arrangement, visual hierarchy
+  - Each concept should have distinct navigation pattern, content flow, and responsive behavior
+
+  ## Generate for EACH Target
+  For target in {targets}:
+    For concept_index in 1..{variants_count}:
+      1. **Concept Definition**:
+         - concept_name (descriptive, e.g., "Classic Three-Column Holy Grail")
+         - design_philosophy (1-2 sentences explaining the structural approach)
+         - layout_pattern (e.g., "grid-3col", "flex-row", "single-column", "asymmetric-grid")
+         - key_components (array of main layout regions)
+         - structural_features (list of distinguishing characteristics)
+
+      2. **Wireframe Preview** (simple text representation):
+         - ascii_art (simple ASCII box diagram showing layout structure)
+         - Example:
+           ┌─────────────────┐
+           │     HEADER      │
+           ├──┬─────────┬────┤
+           │ L│  MAIN   │ R  │
+           └──┴─────────┴────┘
+
+  ## Output
+  Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json
+
+  Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)
+
+  CRITICAL: Use Write() tool immediately after generating complete JSON
+`
+```
+
+### Step 4: Verify Options File Created
+```bash
+bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")
+
+# Quick validation
+bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep -q "layout_concepts" && echo "valid")
+```
+
+**Output**: `analysis-options.json` with layout concept options for all targets
+
+---
+
+## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+
+**Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates
+
+### Step 1: Load and Present Options
+```bash
+# Read options file
+options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+
+# Parse layout concepts
+layout_concepts = options.layout_concepts
+```
+
+### Step 2: Present Options to User (Per Target)
+For each target, present layout concept options and capture selection:
+
+```
+📋 Layout Concept Options for Target: {target}
+
+We've generated {variants_count} structurally different layout concepts for review.
+Please select your preferred concept for this target.
+
+{FOR each concept in layout_concepts[target]:
+  ═══════════════════════════════════════════════════
+  Concept {concept.index}: {concept.concept_name}
+  ═══════════════════════════════════════════════════
+
+  Philosophy: {concept.design_philosophy}
+  Pattern: {concept.layout_pattern}
+
+  Components:
+  {FOR each component in concept.key_components:
+    • {component}
+  }
+
+  Features:
+  {FOR each feature in concept.structural_features:
+    • {feature}
+  }
+
+  Wireframe:
+  {concept.wireframe_preview.ascii_art}
+
+  ═══════════════════════════════════════════════════
+}
+```
+
+### Step 3: Capture User Selection (Per Target)
+```javascript
+// Use AskUserQuestion tool for each target
+FOR each target:
+  AskUserQuestion({
+    questions: [{
+      question: "Which layout concept do you prefer for '{target}'?",
+      header: "Layout for " + target,
+      multiSelect: false,
+      options: [
+        {FOR each concept in layout_concepts[target]:
+          label: "Concept {concept.index}: {concept.concept_name}",
+          description: "{concept.design_philosophy}"
+        }
+      ]
+    }]
+  })
+
+  // Parse user response
+  selected_option_text = user_answer
+
+  // Check for user cancellation
+  IF selected_option_text == null OR selected_option_text == "":
+      REPORT: "⚠️ User canceled selection. Workflow terminated."
+      EXIT workflow
+
+  // Extract concept index from response format "Concept N: Name"
+  match = selected_option_text.match(/Concept (\d+):/)
+  IF match:
+      selected_index = parseInt(match[1])
+  ELSE:
+      ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
+      EXIT workflow
+
+  // Store selection for this target
+  selections[target] = {
+    selected_index: selected_index,
+    concept_name: layout_concepts[target][selected_index-1].concept_name
+  }
+```
+
+### Step 4: Write User Selection File
+```bash
+# Create user selection JSON
+selection_data = {
+  "metadata": {
+    "selected_at": "{current_timestamp}",
+    "selection_type": "per_target",
+    "session_id": "{session_id}"
+  },
+  "selections": selections  // {target: {selected_index, concept_name}}
+}
+
+# Write to file
+bash(echo '{selection_data}' > {base_path}/.intermediates/layout-analysis/user-selection.json)
+
+# Verify
+bash(test -f {base_path}/.intermediates/layout-analysis/user-selection.json && echo "saved")
+```
+
+### Step 5: Confirmation Message
+```
+✅ Selections recorded!
+
+{FOR each target, selection in selections:
+  • {target}: Concept {selection.selected_index} - {selection.concept_name}
+}
+
+Proceeding to generate detailed layout templates based on your selections...
+```
+
+**Output**: `user-selection.json` with user's choices for all targets
+
+## Phase 2: Layout Template Generation (Agent Task 2)
+
+**Executor**: `Task(ui-design-agent)` for selected concept(s)
+
+### Step 1: Load User Selection (Explore Mode)
+```bash
+# For explore mode, read user selection
+IF extraction_mode == "explore":
+    selection = Read({base_path}/.intermediates/layout-analysis/user-selection.json)
+    selections_per_target = selection.selections
+
+    # Also read the selected concept details from options
+    options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+    layout_concepts = options.layout_concepts
+
+    # Build selected concepts map
+    selected_concepts = {}
+    FOR each target in targets:
+        selected_index = selections_per_target[target].selected_index
+        selected_concepts[target] = layout_concepts[target][selected_index-1]  # 0-indexed
+ELSE:
+    # Imitate mode - no selection needed
+    selected_concepts = null
+```
+
+### Step 2: Launch Agent Task
+Generate layout templates for selected concepts:
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_TEMPLATE_GENERATION_TASK]
+  Generate detailed layout templates based on user-selected concepts.
   Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
 
-  REFERENCES:
-  - Input: {reference_material}  // Images, URLs, or prompt
-  - Mode: {extraction_mode}  // 'imitate' or 'explore'
-  - Targets: {targets}  // List of page/component names
-  - Variants per Target: {variants_count}
-  - Device Type: {device_type}
-  ${exploration_mode ? "- Layout Inspiration: Read('" + base_path + "/layout-extraction/_inspirations/{target}-layout-ideas.txt')" : ""}
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+  DEVICE_TYPE: {device_type}
 
-  ## Analysis & Generation
-  For EACH target in {targets}:
-    For EACH variant (1 to {variants_count}):
-      1. **Analyze Structure**: Deconstruct reference to understand layout, hierarchy, responsiveness
-      2. **Define Philosophy**: Short description (e.g., "Asymmetrical grid with overlapping content areas")
-      3. **Generate DOM Structure**: JSON object representing semantic HTML5 structure
-         - Semantic tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
-         - ARIA roles and accessibility attributes
-         - Device-specific structure:
-           * mobile: Single column, stacked sections, touch targets ≥44px
-           * desktop: Multi-column grids, hover states, larger hit areas
-           * tablet: Hybrid layouts, flexible columns
-           * responsive: Breakpoint-driven adaptive layouts (mobile-first)
-         - In 'explore' mode: Each variant structurally DISTINCT
-      4. **Define Component Hierarchy**: High-level array of main layout regions
-         Example: ["header", "main-content", "sidebar", "footer"]
-      5. **Generate CSS Layout Rules**:
-         - Focus ONLY on layout (Grid, Flexbox, position, alignment, gap, etc.)
-         - Use CSS Custom Properties for spacing/breakpoints: var(--spacing-4), var(--breakpoint-md)
-         - Device-specific styles (mobile-first @media for responsive)
-         - NO colors, NO fonts, NO shadows - layout structure only
+  ${extraction_mode == "explore" ? `
+  USER SELECTIONS:
+  ${targets.map(target => `
+  Target: ${target}
+  - Selected Concept: ${selected_concepts[target].concept_name}
+  - Philosophy: ${selected_concepts[target].design_philosophy}
+  - Pattern: ${selected_concepts[target].layout_pattern}
+  - Key Components: ${selected_concepts[target].key_components.join(", ")}
+  - Structural Features: ${selected_concepts[target].structural_features.join(", ")}
+  `).join("\n")}
+  ` : `
+  MODE: Imitate - High-fidelity replication of reference layout structure
+  TARGETS: ${targets.join(", ")}
+  `}
+
+  ## Input Analysis
+  - Targets: {targets.join(", ")}
+  - Device type: {device_type}
+  - Visual references: {loaded_images if available}
+  ${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-*.json - USE THIS for accurate layout properties" : ""}
+
+  ## Generation Rules
+  ${extraction_mode == "explore" ? `
+  - **Explore Mode**: Develop each user-selected layout concept into a detailed template
+  - Use the selected concept's key_components as foundation
+  - Apply the selected layout_pattern (grid-3col, flex-row, etc.)
+  - Honor the structural_features defined in the concept
+  - Expand the concept with complete DOM structure and CSS layout rules
+  ` : `
+  - **Imitate Mode**: High-fidelity replication of reference layout structure
+  ${dom_structure_available ? "- Use DOM structure data as ground truth" : "- Use visual inference"}
+  `}
+  ${dom_structure_available ? `
+  - IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties
+  - Use DOM data as primary source for layout properties
+  - Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)
+  - Use actual element bounds for responsive breakpoint decisions
+  - Preserve identified patterns from DOM structure
+  ` : ""}
+
+  ## Generate for EACH Target
+  For target in {targets}:
+    ${extraction_mode == "explore" ? "Based on user-selected concept:" : "Based on reference:"}
+
+    1. **DOM Structure**:
+       - Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+       - ARIA roles and accessibility attributes
+       ${extraction_mode == "explore" ? "- Use key_components from selected concept" : ""}
+       ${dom_structure_available ? "- Base on extracted DOM tree from .intermediates" : "- Infer from visual analysis"}
+       - Device-specific optimizations for {device_type}
+
+    2. **Component Hierarchy**:
+       - Array of main layout regions
+       ${extraction_mode == "explore" ? "- Derived from selected concept's key_components" : ""}
+
+    3. **CSS Layout Rules**:
+       ${extraction_mode == "explore" ? "- Implement selected layout_pattern" : ""}
+       ${dom_structure_available ? "- Use real layout properties from DOM structure data" : "- Focus on Grid, Flexbox, position, alignment"}
+       - Use CSS Custom Properties: var(--spacing-*), var(--breakpoint-*)
+       - Device-specific styles (mobile-first @media for responsive)
+       - NO colors, NO fonts, NO shadows - layout structure only
 
   ## Output Format
-  Return JSON object with layout_templates array.
+  Write complete layout-templates.json with layout_templates array.
   Each template must include:
   - target (string)
-  - variant_id (string, e.g., "layout-1")
-  - source_image_path (string, REQUIRED): Path to the primary reference image used for this layout analysis
-    * For image input: Use the actual image file path from {images_pattern}
-    * For URL input: Use the screenshot path if available, or empty string
-    * For text/prompt input: Use empty string
-    * Example: "{base_path}/screenshots/home.png"
+  - variant_id: "layout-1" (always 1 since only selected concept is generated)
+  - source_image_path (string): Reference image path
   - device_type (string)
-  - design_philosophy (string)
+  - design_philosophy (string ${extraction_mode == "explore" ? "- from selected concept" : ""})
   - dom_structure (JSON object)
   - component_hierarchy (array of strings)
   - css_layout_rules (string)
 
-  ## Notes
-  - Structure only, no visual styling
-  - Use var() for all spacing/sizing
-  - Layouts must be structurally distinct in explore mode
-  - Write complete layout-templates.json
+  ## Critical Requirements
+  - ✅ Use Write() tool for layout-templates.json
+  - ✅ One template per target (only selected concept)
+  - ✅ Structure only, no visual styling
+  - ✅ Token-based CSS (var())
+  ${extraction_mode == "explore" ? "- ✅ Maintain consistency with selected concepts" : ""}
 `
 ```
 
-**Output**: Agent returns JSON with `layout_templates` array
+**Output**: Agent generates `layout-templates.json` with one template per target
 
 ### Step 2: Write Output File
 ```bash
@@ -200,6 +558,13 @@ Configuration:
 - Targets: {targets}
 - Variants per Target: {variants_count}
 - Total Templates: {targets.length × variants_count}
+{IF has_urls AND dom_structure_available:
+- 🔍 URL Mode: DOM structure extracted from {len(url_list)} URL(s)
+- Accuracy: Real flex/grid properties from live pages
+}
+{IF has_urls AND NOT dom_structure_available:
+- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
+}
 
 {IF extraction_mode == "explore":
 Layout Research:
@@ -212,6 +577,9 @@ Generated Templates:
 
 Output File:
 - {base_path}/layout-extraction/layout-templates.json
+{IF dom_structure_available:
+- {base_path}/.intermediates/layout-analysis/dom-structure-*.json ({len(url_list)} files)
+}
 
 Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
 ```
@@ -225,7 +593,7 @@ bash(find .workflow -type d -name "design-*" | head -1)
 
 # Create output directories
 bash(mkdir -p {base_path}/layout-extraction)
-bash(mkdir -p {base_path}/layout-extraction/_inspirations)  # explore mode only
+bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)  # explore mode only
 ```
 
 ### Validation Commands
@@ -247,7 +615,7 @@ bash(ls {images_pattern})
 Read({image_path})
 
 # Write inspiration files (explore mode)
-Write({base_path}/layout-extraction/_inspirations/{target}-layout-ideas.txt, content)
+Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, content)
 
 # Write layout templates
 bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
@@ -257,11 +625,14 @@ bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
 
 ```
 {base_path}/
-└── layout-extraction/
-    ├── layout-templates.json         # Structural layout templates
-    ├── layout-space-analysis.json    # Layout directions (explore mode only)
-    └── _inspirations/                 # Explore mode only
-        └── {target}-layout-ideas.txt  # Layout inspiration research
+├── .intermediates/                    # Intermediate analysis files
+│   └── layout-analysis/
+│       ├── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
+│       └── inspirations/                 # Explore mode only
+│           └── {target}-layout-ideas.txt # Layout inspiration research
+└── layout-extraction/                 # Final layout templates
+    ├── layout-templates.json          # Structural layout templates
+    └── layout-space-analysis.json     # Layout directions (explore mode only)
 ```
 
 ## layout-templates.json Format
@@ -343,10 +714,14 @@ ERROR: MCP search failed (explore mode)
 
 ## Key Features
 
+- **Auto-Trigger URL Mode** - Automatically extracts DOM structure when --urls provided (no manual flag needed)
+- **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
+- **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
 - **Separation of Concerns** - Decouples layout (structure) from style (visuals)
 - **Structural Exploration** - Explore mode enables A/B testing of different layouts
 - **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
 - **Device-Specific** - Tailored structures for different screen sizes
+- **Graceful Fallback** - Falls back to visual analysis if Chrome DevTools unavailable
 - **Foundation for Assembly** - Provides structural blueprint for refactored `generate` command
 - **Agent-Powered** - Deep structural analysis with AI
 
@@ -355,10 +730,9 @@ ERROR: MCP search failed (explore mode)
 **Workflow Position**: Between style extraction and prototype generation
 
 **New Workflow**:
-1. `/workflow:ui-design:style-extract` → `style-cards.json` (Visual tokens)
-2. `/workflow:ui-design:consolidate` → `design-tokens.json` (Final visual system)
-3. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
-4. `/workflow:ui-design:generate` (Refactored as assembler):
+1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md` (Complete design systems)
+2. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
+3. `/workflow:ui-design:generate` (Pure assembler):
    - **Reads**: `design-tokens.json` + `layout-templates.json`
    - **Action**: For each style × layout combination:
      1. Build HTML from `dom_structure`

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

@@ -1,27 +1,44 @@
 ---
 name: style-extract
 description: Extract design style from reference images or text prompts using Claude's analysis
-argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
+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(*)
 ---
 
 # Style Extraction Command
 
 ## Overview
-Extract design style from reference images or text prompts using Claude's built-in analysis. Generates `style-cards.json` with multiple design variants containing token proposals for consolidation.
+Extract design style from reference images or text prompts using Claude's built-in analysis. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
 
 **Strategy**: AI-Driven Design Space Exploration
 - **Claude-Native**: 100% Claude analysis, no external tools
-- **Single Output**: `style-cards.json` with embedded token proposals
+- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
 - **Flexible Input**: Images, text prompts, or both (hybrid mode)
 - **Maximum Contrast**: AI generates maximally divergent design directions
+- **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
 
 ## Phase 0: Setup & Input Validation
 
 ### Step 1: Detect Input Mode, Extraction Mode & Base Path
 ```bash
 # Detect input source
-# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
+# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            # Single URL without target
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+    primary_url = url_list[0].url  # First URL as primary source
+ELSE:
+    has_urls = false
 
 # Determine extraction mode
 # Priority: --mode parameter → default "imitate"
@@ -39,7 +56,64 @@ bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
 # OR use --base-path / --session parameters
 ```
 
-### Step 2: Load Inputs
+### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
+```bash
+# AUTO-TRIGGER: If URLs are available (from --urls parameter or capture metadata), automatically extract real CSS values
+# This provides accurate design tokens to supplement visual analysis
+
+# Priority 1: Check for --urls parameter
+IF has_urls:
+    url_to_extract = primary_url
+    url_source = "--urls parameter"
+
+# Priority 2: Check for URL metadata from capture phase
+ELSE IF exists({base_path}/.metadata/capture-urls.json):
+    capture_urls = Read({base_path}/.metadata/capture-urls.json)
+    url_to_extract = capture_urls[0]  # Use first URL
+    url_source = "capture metadata"
+ELSE:
+    url_to_extract = null
+
+# Execute extraction if URL available
+IF url_to_extract AND mcp_chrome_devtools_available:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting computed styles from {url_source}"
+    REPORT: "   URL: {url_to_extract}"
+
+    # Read extraction script
+    script_content = Read(~/.claude/scripts/extract-computed-styles.js)
+
+    # Open page in Chrome DevTools
+    mcp__chrome-devtools__navigate_page(url=url_to_extract)
+
+    # Execute extraction script directly
+    result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+    # Save computed styles to intermediates directory
+    bash(mkdir -p {base_path}/.intermediates/style-analysis)
+    Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
+
+    computed_styles_available = true
+    REPORT: "   ✅ Computed styles extracted and saved"
+ELSE:
+    computed_styles_available = false
+    IF url_to_extract:
+        REPORT: "⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `tokens`: Organized design tokens (colors, borderRadii, shadows, fontSizes, fontWeights, spacing)
+
+**Benefits**:
+- ✅ Pixel-perfect accuracy for border-radius, box-shadow, padding, etc.
+- ✅ Eliminates guessing from visual analysis
+- ✅ Provides ground truth for design tokens
+
+### Step 3: Load Inputs
 ```bash
 # For image mode
 bash(ls {images_pattern})  # Expand glob pattern
@@ -52,17 +126,21 @@ Read({image_path})  # Load each image
 bash(mkdir -p {base_path}/style-extraction/)
 ```
 
-### Step 3: Memory Check (Skip if Already Done)
+### Step 3: Memory Check
 ```bash
-# Check if already extracted
-bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
+# 1. Check if inputs cached in session memory
+IF session_has_inputs: SKIP Step 2 file reading
+
+# 2. Check if output already exists
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
+IF exists: SKIP to completion
 ```
 
-**If exists**: Skip to completion message
+---
 
-**Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`
+**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`, `has_urls`, `url_list[]`, `computed_styles_available`
 
-## Phase 1: Design Space Analysis (Explore Mode Only)
+## Phase 1: Design Direction Generation (Explore Mode Only)
 
 ### Step 1: Check Extraction Mode
 ```bash
@@ -79,56 +157,307 @@ bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
 bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
 ```
 
-### Step 3: Generate Divergent Directions (Claude Native)
-AI analyzes requirements and generates `variants_count` maximally contrasting design directions:
+### Step 3: Generate Design Direction Options (Agent Task 1)
+**Executor**: `Task(ui-design-agent)`
 
-**Input**: User prompt + project context + image count
-**Analysis**: 6D attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density)
-**Output**: JSON with divergent_directions, each having:
-- philosophy_name (2-3 words)
-- design_attributes (specific scores)
-- search_keywords (3-5 keywords)
-- anti_keywords (2-3 keywords)
-- rationale (contrast explanation)
+Launch agent to generate `variants_count` design direction options with previews:
 
-### Step 4: Write Design Space Analysis
-```bash
-bash(echo '{design_space_analysis}' > {base_path}/style-extraction/design-space-analysis.json)
+```javascript
+Task(ui-design-agent): `
+  [DESIGN_DIRECTION_GENERATION_TASK]
+  Generate {variants_count} maximally contrasting design directions with visual previews
 
-# Verify output
-bash(test -f design-space-analysis.json && echo "saved")
+  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+
+  ## Input Analysis
+  - User prompt: {prompt_guidance}
+  - Visual references: {loaded_images if available}
+  - Project context: {brainstorming_context if available}
+
+  ## Analysis Rules
+  - Analyze 6D attribute space: color saturation, visual weight, formality, organic/geometric, innovation, density
+  - Generate {variants_count} directions with MAXIMUM contrast
+  - Each direction must be distinctly different (min distance score: 0.7)
+
+  ## Generate for EACH Direction
+  1. **Core Philosophy**:
+     - philosophy_name (2-3 words, e.g., "Minimalist & Airy")
+     - design_attributes (6D scores 0-1)
+     - search_keywords (3-5 keywords)
+     - anti_keywords (2-3 keywords to avoid)
+     - rationale (why this is distinct from others)
+
+  2. **Visual Preview Elements**:
+     - primary_color (OKLCH format)
+     - secondary_color (OKLCH format)
+     - accent_color (OKLCH format)
+     - font_family_heading (specific font name)
+     - font_family_body (specific font name)
+     - border_radius_base (e.g., "0.5rem")
+     - mood_description (1-2 sentences describing the feel)
+
+  ## Output
+  Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+
+  Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
+
+  CRITICAL: Use Write() tool immediately after generating complete JSON
+`
 ```
 
-**Output**: `design-space-analysis.json` for consolidation phase
-
-## Phase 2: Style Synthesis & File Write
-
-### Step 1: Claude Native Analysis
-AI generates `variants_count` design style proposals:
-
-**Input**:
-- Input mode (image/text/hybrid)
-- Visual references or text guidance
-- Design space analysis (explore mode only)
-- Variant-specific directions (explore mode only)
-
-**Analysis Rules**:
-- **Explore mode**: Each variant follows pre-defined philosophy and attributes, maintains maximum contrast
-- **Imitate mode**: High-fidelity replication of reference design
-- OKLCH color format
-- Complete token proposals (colors, typography, spacing, border_radius, shadows, breakpoints)
-- WCAG AA accessibility (4.5:1 text, 3:1 UI)
-
-**Output Format**: `style-cards.json` with:
-- extraction_metadata (session_id, input_mode, extraction_mode, timestamp, variants_count)
-- style_cards[] (id, name, description, design_philosophy, preview, proposed_tokens)
-
-### Step 2: Write Style Cards
+### Step 4: Verify Options File Created
 ```bash
-bash(echo '{style_cards_json}' > {base_path}/style-extraction/style-cards.json)
+bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
+
+# Quick validation
+bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep -q "design_directions" && echo "valid")
 ```
 
-**Output**: `style-cards.json` with `variants_count` complete variants
+**Output**: `analysis-options.json` with design direction options
+
+---
+
+## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+
+**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
+
+### Step 1: Load and Present Options
+```bash
+# Read options file
+options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+
+# Parse design directions
+design_directions = options.design_directions
+```
+
+### Step 2: Present Options to User
+```
+📋 Design Direction Options
+
+We've generated {variants_count} contrasting design directions for your review.
+Please select the direction(s) you'd like to develop into complete design systems.
+
+{FOR each direction in design_directions:
+  ═══════════════════════════════════════════════════
+  Option {direction.index}: {direction.philosophy_name}
+  ═══════════════════════════════════════════════════
+
+  Philosophy: {direction.rationale}
+
+  Visual Preview:
+  • Colors: {direction.preview.primary_color} (primary), {direction.preview.accent_color} (accent)
+  • Typography: {direction.preview.font_family_heading} (headings), {direction.preview.font_family_body} (body)
+  • Border Radius: {direction.preview.border_radius_base}
+  • Mood: {direction.preview.mood_description}
+
+  Design Attributes:
+  • Color Saturation: {direction.design_attributes.color_saturation * 100}%
+  • Visual Weight: {direction.design_attributes.visual_weight * 100}%
+  • Formality: {direction.design_attributes.formality * 100}%
+  • Innovation: {direction.design_attributes.innovation * 100}%
+
+  Keywords: {join(direction.search_keywords, ", ")}
+  Avoiding: {join(direction.anti_keywords, ", ")}
+}
+
+═══════════════════════════════════════════════════
+```
+
+### Step 3: Capture User Selection
+```javascript
+// Use AskUserQuestion tool for selection
+AskUserQuestion({
+  questions: [{
+    question: "Which design direction would you like to develop into a complete design system?",
+    header: "Style Choice",
+    multiSelect: false,  // Single selection for Phase 1
+    options: [
+      {FOR each direction:
+        label: "Option {direction.index}: {direction.philosophy_name}",
+        description: "{direction.mood_description}"
+      }
+    ]
+  }]
+})
+
+// Parse user response (e.g., "Option 1: Minimalist & Airy")
+selected_option_text = user_answer
+
+// Check for user cancellation
+IF selected_option_text == null OR selected_option_text == "":
+    REPORT: "⚠️ User canceled selection. Workflow terminated."
+    EXIT workflow
+
+// Extract option index from response format "Option N: Name"
+match = selected_option_text.match(/Option (\d+):/)
+IF match:
+    selected_index = parseInt(match[1])
+ELSE:
+    ERROR: "Invalid selection format. Expected 'Option N: ...' format"
+    EXIT workflow
+```
+
+### Step 4: Write User Selection File
+```bash
+# Create user selection JSON
+selection_data = {
+  "metadata": {
+    "selected_at": "{current_timestamp}",
+    "selection_type": "single",
+    "session_id": "{session_id}"
+  },
+  "selected_indices": [selected_index],
+  "refinements": {
+    "enabled": false
+  }
+}
+
+# Write to file
+bash(echo '{selection_data}' > {base_path}/.intermediates/style-analysis/user-selection.json)
+
+# Verify
+bash(test -f {base_path}/.intermediates/style-analysis/user-selection.json && echo "saved")
+```
+
+### Step 5: Confirmation Message
+```
+✅ Selection recorded!
+
+You selected: Option {selected_index} - {selected_direction.philosophy_name}
+
+Proceeding to generate complete design system based on your selection...
+```
+
+**Output**: `user-selection.json` with user's choice
+
+## Phase 2: Design System Generation (Agent Task 2)
+
+**Executor**: `Task(ui-design-agent)` for selected variant(s)
+
+### Step 1: Load User Selection (Explore Mode)
+```bash
+# For explore mode, read user selection
+IF extraction_mode == "explore":
+    selection = Read({base_path}/.intermediates/style-analysis/user-selection.json)
+    selected_indices = selection.selected_indices
+    refinements = selection.refinements
+
+    # Also read the selected direction details from options
+    options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+    selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed
+
+    # For Phase 1, we only allow single selection
+    selected_direction = selected_directions[0]
+    actual_variants_count = 1
+ELSE:
+    # Imitate mode - generate single variant without selection
+    selected_direction = null
+    actual_variants_count = 1
+```
+
+### Step 2: Create Output Directory
+```bash
+# Create directory for selected variant only
+bash(mkdir -p {base_path}/style-extraction/style-1)
+```
+
+### Step 3: Launch Agent Task
+Generate design system for selected direction:
+```javascript
+Task(ui-design-agent): `
+  [DESIGN_SYSTEM_GENERATION_TASK]
+  Generate production-ready design system based on user-selected direction
+
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+
+  ${extraction_mode == "explore" ? `
+  USER SELECTION:
+  - Selected Direction: ${selected_direction.philosophy_name}
+  - Design Attributes: ${JSON.stringify(selected_direction.design_attributes)}
+  - Search Keywords: ${selected_direction.search_keywords.join(", ")}
+  - Anti-keywords: ${selected_direction.anti_keywords.join(", ")}
+  - Rationale: ${selected_direction.rationale}
+  - Preview Colors: Primary=${selected_direction.preview.primary_color}, Accent=${selected_direction.preview.accent_color}
+  - Preview Typography: Heading=${selected_direction.preview.font_family_heading}, Body=${selected_direction.preview.font_family_body}
+  - Preview Border Radius: ${selected_direction.preview.border_radius_base}
+
+  ${refinements.enabled ? `
+  USER REFINEMENTS:
+  ${refinements.primary_color ? "- Primary Color Override: " + refinements.primary_color : ""}
+  ${refinements.font_family_heading ? "- Heading Font Override: " + refinements.font_family_heading : ""}
+  ${refinements.font_family_body ? "- Body Font Override: " + refinements.font_family_body : ""}
+  ` : ""}
+  ` : ""}
+
+  ## Input Analysis
+  - Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
+  - Visual references: {loaded_images OR prompt_guidance}
+  ${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
+
+  ## Generation Rules
+  ${extraction_mode == "explore" ? `
+  - **Explore Mode**: Develop the selected design direction into a complete design system
+  - Use preview elements as foundation and expand with full token coverage
+  - Apply design_attributes to all token values:
+    * color_saturation → OKLCH chroma values
+    * visual_weight → font weights, shadow depths
+    * density → spacing scale compression/expansion
+    * formality → typography choices, border radius
+    * organic_geometric → border radius, shape patterns
+    * innovation → token naming, experimental values
+  - Honor search_keywords for design inspiration
+  - Avoid anti_keywords patterns
+  ` : `
+  - **Imitate Mode**: High-fidelity replication of reference design
+  ${computed_styles_available ? "- Use computed styles as ground truth for all measurements" : "- Use visual inference for measurements"}
+  `}
+  - All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
+  - WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
+
+  ## Generate
+  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)
+     - 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" : ""}
+
+  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
+     - Spacing system explanation
+     - Component examples and usage patterns
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for each file
+  - ✅ Write to style-1/ directory (single output)
+  - ❌ NO external research or MCP calls (pure AI generation)
+  - ✅ Maintain consistency with user-selected direction
+  ${refinements.enabled ? "- ✅ Apply user refinements precisely" : ""}
+`
+```
+
+**Output**: Agent generates 2 files (design-tokens.json, style-guide.md) for selected direction
+
+## Phase 3: Verify Output
+
+### Step 1: Check Files Created
+```bash
+# Verify all design systems created
+bash(ls {base_path}/style-extraction/style-*/design-tokens.json | wc -l)
+
+# Validate structure
+bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
+```
+
+### Step 2: Verify File Sizes
+```bash
+bash(ls -lh {base_path}/style-extraction/style-1/)
+```
+
+**Output**: `variants_count × 2` files verified
 
 ## Completion
 
@@ -137,7 +466,8 @@ bash(echo '{style_cards_json}' > {base_path}/style-extraction/style-cards.json)
 TodoWrite({todos: [
   {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
   {content: "Design space analysis (explore mode)", status: "completed", activeForm: "Analyzing design space"},
-  {content: "Style synthesis and file write", status: "completed", activeForm: "Generating style cards"}
+  {content: "Design system generation (agent)", status: "completed", activeForm: "Generating design systems"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
 ]});
 ```
 
@@ -148,23 +478,38 @@ TodoWrite({todos: [
 Configuration:
 - Session: {session_id}
 - Extraction Mode: {extraction_mode} (imitate/explore)
-- Input Mode: {input_mode} (image/text/hybrid)
+- Input Mode: {input_mode} (image/text/hybrid{"/url" if has_urls else ""})
 - Variants: {variants_count}
-
-{IF extraction_mode == "explore":
-Design Space Analysis:
-- {variants_count} maximally contrasting design directions
-- Min contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
+- Production-Ready: Complete design systems generated
+{IF has_urls AND computed_styles_available:
+- 🔍 URL Mode: Computed styles extracted from {len(url_list)} URL(s)
+- Accuracy: Pixel-perfect design tokens from DOM
+}
+{IF has_urls AND NOT computed_styles_available:
+- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
 }
 
-Generated Variants:
-{FOR each card: - {card.name} - {card.design_philosophy}}
+{IF extraction_mode == "explore":
+Design Direction Selection:
+- You selected: Option {selected_index} - {selected_direction.philosophy_name}
+- Generated from {variants_count} contrasting design direction options
+}
 
-Output Files:
-- {base_path}/style-extraction/style-cards.json
-{IF extraction_mode == "explore": - {base_path}/style-extraction/design-space-analysis.json}
+Generated Files:
+{base_path}/style-extraction/
+└── style-1/ (design-tokens.json, style-guide.md)
 
-Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count}
+{IF computed_styles_available:
+Intermediate Analysis:
+{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
+}
+{IF extraction_mode == "explore":
+{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options)
+{base_path}/.intermediates/style-analysis/user-selection.json (your selection)
+}
+
+Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
+  OR: /workflow:ui-design:generate --session {session_id}
 ```
 
 ## Simple Bash Commands
@@ -184,13 +529,13 @@ bash(mkdir -p {base_path}/style-extraction/)
 ### Validation Commands
 ```bash
 # Check if already extracted
-bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
 
 # Count variants
-bash(cat style-cards.json | grep -c "\"id\": \"variant-")
+bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 
-# Validate JSON
-bash(cat style-cards.json | grep -q "extraction_metadata" && echo "valid")
+# Validate JSON structure
+bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
 ```
 
 ### File Operations
@@ -198,46 +543,49 @@ bash(cat style-cards.json | grep -q "extraction_metadata" && echo "valid")
 # Load brainstorming context
 bash(test -f .brainstorming/synthesis-specification.md && cat it)
 
-# Write output
-bash(echo '{json}' > {base_path}/style-extraction/style-cards.json)
+# Create directories
+bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
 
 # Verify output
-bash(test -f design-space-analysis.json && echo "saved")
+bash(ls {base_path}/style-extraction/style-1/)
+bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "saved")
 ```
 
 ## Output Structure
 
 ```
-{base_path}/style-extraction/
-├── style-cards.json              # Complete style variants with token proposals
-└── design-space-analysis.json    # Design directions (explore mode only)
+{base_path}/
+├── .intermediates/                  # Intermediate analysis files
+│   └── style-analysis/
+│       ├── computed-styles.json     # Extracted CSS values from DOM (if URL available)
+│       ├── analysis-options.json    # Design direction options (explore mode only)
+│       └── user-selection.json      # User's selected direction (explore mode only)
+└── style-extraction/                # Final design system
+    └── style-1/
+        ├── design-tokens.json       # Production-ready design tokens
+        └── style-guide.md           # Design philosophy and usage guide
 ```
 
-## style-cards.json Format
+## design-tokens.json Format
 
 ```json
 {
-  "extraction_metadata": {"session_id": "...", "input_mode": "image|text|hybrid", "extraction_mode": "imitate|explore", "timestamp": "...", "variants_count": N},
-  "style_cards": [
-    {
-      "id": "variant-1", "name": "Style Name", "description": "...",
-      "design_philosophy": "Core principles",
-      "preview": {"primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..."},
-      "proposed_tokens": {
-        "colors": {"brand": {...}, "surface": {...}, "semantic": {...}, "text": {...}, "border": {...}},
-        "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
-        "spacing": {"0": "0", ..., "24": "6rem"},
-        "border_radius": {"none": "0", ..., "full": "9999px"},
-        "shadows": {"sm": "...", ..., "xl": "..."},
-        "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
-      }
-    }
-    // Repeat for all variants
-  ]
+  "colors": {
+    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+    "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": {...}},
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
 }
 ```
 
-**Requirements**: All colors in OKLCH format, complete token proposals, semantic naming
+**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance
 
 ## Error Handling
 
@@ -255,17 +603,22 @@ ERROR: Claude JSON parsing error
 
 ## Key Features
 
+- **Auto-Trigger URL Mode** - Automatically extracts computed styles when --urls provided (no manual flag needed)
+- **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
+- **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
+- **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
 - **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
 - **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
 - **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
-- **Claude-Native** - No external tools, fast deterministic synthesis
-- **Flexible Input** - Images, text, or hybrid mode
-- **Production-Ready** - OKLCH colors, WCAG AA, semantic naming
+- **Flexible Input** - Images, text, URLs, or hybrid mode
+- **Graceful Fallback** - Falls back to pure visual inference if Chrome DevTools unavailable
+- **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
+- **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
 
 ## Integration
 
 **Input**: Reference images or text prompts
-**Output**: `style-cards.json` for consolidation
-**Next**: `/workflow:ui-design:consolidate --session {session_id} --variants {count}`
+**Output**: `style-extraction/style-{N}/` with design-tokens.json + style-guide.md
+**Next**: `/workflow:ui-design:layout-extract --session {session_id}` OR `/workflow:ui-design:generate --session {session_id}`
 
-**Note**: This command only extracts visual style (colors, typography, spacing). For layout structure extraction, use `/workflow:ui-design:layout-extract`.
+**Note**: This command extracts visual style (colors, typography, spacing) and generates production-ready design systems. For layout structure extraction, use `/workflow:ui-design:layout-extract`.

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

@@ -30,13 +30,11 @@ CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active ses
 # Verify design artifacts in latest design run
 latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
 
-# Detect design system structure (unified vs separate)
-IF exists({latest_design}/style-consolidation/design-tokens.json):
-    design_system_mode = "unified"; design_tokens_path = "style-consolidation/design-tokens.json"; style_guide_path = "style-consolidation/style-guide.md"
-ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
-    design_system_mode = "separate"; design_tokens_path = "style-consolidation/style-1/design-tokens.json"; style_guide_path = "style-consolidation/style-1/style-guide.md"
+# Detect design system structure
+IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
+    design_system_mode = "separate"; design_tokens_path = "style-extraction/style-1/design-tokens.json"; style_guide_path = "style-extraction/style-1/style-guide.md"
 ELSE:
-    ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"
+    ERROR: "No design tokens found. Run /workflow:ui-design:style-extract first"
 
 VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
 
@@ -202,15 +200,15 @@ Next: /workflow:plan [--agent] "<task description>"
 
 **@ Reference Format** (synthesis-specification.md):
 ```
-@../design-{run_id}/style-consolidation/design-tokens.json
-@../design-{run_id}/style-consolidation/style-guide.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** (ui-designer/style-guide.md):
 ```
-@../../design-{run_id}/style-consolidation/design-tokens.json
-@../../design-{run_id}/style-consolidation/style-guide.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
 ```
 
@@ -230,8 +228,8 @@ After this update, `/workflow:plan` will discover design assets through:
   "task_id": "IMPL-001",
   "context": {
     "design_system": {
-      "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
-      "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
+      "tokens": "design-{run_id}/style-extraction/style-1/design-tokens.json",
+      "style_guide": "design-{run_id}/style-extraction/style-1/style-guide.md",
       "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
     }
   }
@@ -240,7 +238,7 @@ After this update, `/workflow:plan` will discover design assets through:
 
 ## Error Handling
 
-- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
+- **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
 - **ui-designer/ directory missing**: Create directory and file
 - **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
@@ -265,7 +263,7 @@ After update, verify:
 
 ## Integration Points
 
-- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
+- **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
 - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
 - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow

.claude/scripts/classify-folders.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Classify folders by type for documentation generation
+# Usage: get_modules_by_depth.sh | classify-folders.sh
+# Output: folder_path|folder_type|code:N|dirs:N
+
+while IFS='|' read -r depth_info path_info files_info types_info claude_info; do
+  # Extract folder path from format "path:./src/modules"
+  folder_path=$(echo "$path_info" | cut -d':' -f2-)
+
+  # Skip if path extraction failed
+  [[ -z "$folder_path" || ! -d "$folder_path" ]] && continue
+
+  # Count code files (maxdepth 1)
+  code_files=$(find "$folder_path" -maxdepth 1 -type f \
+    \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+       -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \
+       -o -name "*.c" -o -name "*.cpp" -o -name "*.cs" \) \
+    2>/dev/null | wc -l)
+
+  # Count subdirectories
+  subfolders=$(find "$folder_path" -maxdepth 1 -type d \
+    -not -path "$folder_path" 2>/dev/null | wc -l)
+
+  # Determine folder type
+  if [[ $code_files -gt 0 ]]; then
+    folder_type="code"  # API.md + README.md
+  elif [[ $subfolders -gt 0 ]]; then
+    folder_type="navigation"  # README.md only
+  else
+    folder_type="skip"  # Empty or no relevant content
+  fi
+
+  # Output classification result
+  echo "${folder_path}|${folder_type}|code:${code_files}|dirs:${subfolders}"
+done

.claude/scripts/detect_changed_modules.sh

@@ -2,32 +2,88 @@
 # Detect modules affected by git changes or recent modifications
 # Usage: detect_changed_modules.sh [format]
 #   format: list|grouped|paths (default: paths)
+#
+# Features:
+# - Respects .gitignore patterns (current directory or git root)
+# - Detects git changes (staged, unstaged, or last commit)
+# - Falls back to recently modified files (last 24 hours)
+
+# Build exclusion filters from .gitignore
+build_exclusion_filters() {
+    local filters=""
+
+    # Common system/cache directories to exclude
+    local system_excludes=(
+        ".git" "__pycache__" "node_modules" ".venv" "venv" "env"
+        "dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
+        "coverage" ".nyc_output" "logs" "tmp" "temp"
+    )
+
+    for exclude in "${system_excludes[@]}"; do
+        filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
+    done
+
+    # Find and parse .gitignore (current dir first, then git root)
+    local gitignore_file=""
+
+    # Check current directory first
+    if [ -f ".gitignore" ]; then
+        gitignore_file=".gitignore"
+    else
+        # Try to find git root and check for .gitignore there
+        local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
+        if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
+            gitignore_file="$git_root/.gitignore"
+        fi
+    fi
+
+    # Parse .gitignore if found
+    if [ -n "$gitignore_file" ]; then
+        while IFS= read -r line; do
+            # Skip empty lines and comments
+            [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+
+            # Remove trailing slash and whitespace
+            line=$(echo "$line" | sed 's|/$||' | xargs)
+
+            # Skip wildcards patterns (too complex for simple find)
+            [[ "$line" =~ \* ]] && continue
+
+            # Add to filters
+            filters+=" -not -path '*/$line' -not -path '*/$line/*'"
+        done < "$gitignore_file"
+    fi
+
+    echo "$filters"
+}
 
 detect_changed_modules() {
     local format="${1:-paths}"
     local changed_files=""
     local affected_dirs=""
-    
+    local exclusion_filters=$(build_exclusion_filters)
+
     # Step 1: Try to get git changes (staged + unstaged)
     if git rev-parse --git-dir > /dev/null 2>&1; then
         changed_files=$(git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null)
-        
+
         # If no changes in working directory, check last commit
         if [ -z "$changed_files" ]; then
             changed_files=$(git diff --name-only HEAD~1 HEAD 2>/dev/null)
         fi
     fi
-    
+
     # Step 2: If no git changes, find recently modified source files (last 24 hours)
+    # Apply exclusion filters from .gitignore
     if [ -z "$changed_files" ]; then
-        changed_files=$(find . -type f \( \
-            -name "*.md" -o \
-            -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o \
-            -name "*.py" -o -name "*.go" -o -name "*.rs" -o \
-            -name "*.java" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o \
-            -name "*.sh" -o -name "*.ps1" -o \
-            -name "*.json" -o -name "*.yaml" -o -name "*.yml" \
-        \) -not -path '*/.*' -mtime -1 2>/dev/null)
+        changed_files=$(eval "find . -type f \( \
+            -name '*.md' -o \
+            -name '*.js' -o -name '*.ts' -o -name '*.jsx' -o -name '*.tsx' -o \
+            -name '*.py' -o -name '*.go' -o -name '*.rs' -o \
+            -name '*.java' -o -name '*.cpp' -o -name '*.c' -o -name '*.h' -o \
+            -name '*.sh' -o -name '*.ps1' -o \
+            -name '*.json' -o -name '*.yaml' -o -name '*.yml' \
+        \) $exclusion_filters -mtime -1 2>/dev/null")
     fi
     
     # Step 3: Extract unique parent directories

.claude/scripts/extract-animations.js

@@ -0,0 +1,243 @@
+/**
+ * Animation & Transition Extraction Script
+ *
+ * Extracts CSS animations, transitions, and transform patterns from a live web page.
+ * This script runs in the browser context via Chrome DevTools Protocol.
+ *
+ * @returns {Object} Structured animation data
+ */
+(() => {
+  const extractionTimestamp = new Date().toISOString();
+  const currentUrl = window.location.href;
+
+  /**
+   * Parse transition shorthand or individual properties
+   */
+  function parseTransition(element, computedStyle) {
+    const transition = computedStyle.transition || computedStyle.webkitTransition;
+
+    if (!transition || transition === 'none' || transition === 'all 0s ease 0s') {
+      return null;
+    }
+
+    // Parse shorthand: "property duration easing delay"
+    const transitions = [];
+    const parts = transition.split(/,\s*/);
+
+    parts.forEach(part => {
+      const match = part.match(/^(\S+)\s+([\d.]+m?s)\s+(\S+)(?:\s+([\d.]+m?s))?/);
+      if (match) {
+        transitions.push({
+          property: match[1],
+          duration: match[2],
+          easing: match[3],
+          delay: match[4] || '0s'
+        });
+      }
+    });
+
+    return transitions.length > 0 ? transitions : null;
+  }
+
+  /**
+   * Extract animation name and properties
+   */
+  function parseAnimation(element, computedStyle) {
+    const animationName = computedStyle.animationName || computedStyle.webkitAnimationName;
+
+    if (!animationName || animationName === 'none') {
+      return null;
+    }
+
+    return {
+      name: animationName,
+      duration: computedStyle.animationDuration || computedStyle.webkitAnimationDuration,
+      easing: computedStyle.animationTimingFunction || computedStyle.webkitAnimationTimingFunction,
+      delay: computedStyle.animationDelay || computedStyle.webkitAnimationDelay || '0s',
+      iterationCount: computedStyle.animationIterationCount || computedStyle.webkitAnimationIterationCount || '1',
+      direction: computedStyle.animationDirection || computedStyle.webkitAnimationDirection || 'normal',
+      fillMode: computedStyle.animationFillMode || computedStyle.webkitAnimationFillMode || 'none'
+    };
+  }
+
+  /**
+   * Extract transform value
+   */
+  function parseTransform(computedStyle) {
+    const transform = computedStyle.transform || computedStyle.webkitTransform;
+
+    if (!transform || transform === 'none') {
+      return null;
+    }
+
+    return transform;
+  }
+
+  /**
+   * Get element selector (simplified for readability)
+   */
+  function getSelector(element) {
+    if (element.id) {
+      return `#${element.id}`;
+    }
+
+    if (element.className && typeof element.className === 'string') {
+      const classes = element.className.trim().split(/\s+/).slice(0, 2).join('.');
+      if (classes) {
+        return `.${classes}`;
+      }
+    }
+
+    return element.tagName.toLowerCase();
+  }
+
+  /**
+   * Extract all stylesheets and find @keyframes rules
+   */
+  function extractKeyframes() {
+    const keyframes = {};
+
+    try {
+      // Iterate through all stylesheets
+      Array.from(document.styleSheets).forEach(sheet => {
+        try {
+          // Skip external stylesheets due to CORS
+          if (sheet.href && !sheet.href.startsWith(window.location.origin)) {
+            return;
+          }
+
+          Array.from(sheet.cssRules || sheet.rules || []).forEach(rule => {
+            // Check for @keyframes rules
+            if (rule.type === CSSRule.KEYFRAMES_RULE || rule.type === CSSRule.WEBKIT_KEYFRAMES_RULE) {
+              const name = rule.name;
+              const frames = {};
+
+              Array.from(rule.cssRules || []).forEach(keyframe => {
+                const key = keyframe.keyText; // e.g., "0%", "50%", "100%"
+                frames[key] = keyframe.style.cssText;
+              });
+
+              keyframes[name] = frames;
+            }
+          });
+        } catch (e) {
+          // Skip stylesheets that can't be accessed (CORS)
+          console.warn('Cannot access stylesheet:', sheet.href, e.message);
+        }
+      });
+    } catch (e) {
+      console.error('Error extracting keyframes:', e);
+    }
+
+    return keyframes;
+  }
+
+  /**
+   * Scan visible elements for animations and transitions
+   */
+  function scanElements() {
+    const elements = document.querySelectorAll('*');
+    const transitionData = [];
+    const animationData = [];
+    const transformData = [];
+
+    const uniqueTransitions = new Set();
+    const uniqueAnimations = new Set();
+    const uniqueEasings = new Set();
+    const uniqueDurations = new Set();
+
+    elements.forEach(element => {
+      // Skip invisible elements
+      const rect = element.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        return;
+      }
+
+      const computedStyle = window.getComputedStyle(element);
+
+      // Extract transitions
+      const transitions = parseTransition(element, computedStyle);
+      if (transitions) {
+        const selector = getSelector(element);
+        transitions.forEach(t => {
+          const key = `${t.property}-${t.duration}-${t.easing}`;
+          if (!uniqueTransitions.has(key)) {
+            uniqueTransitions.add(key);
+            transitionData.push({
+              selector,
+              ...t
+            });
+            uniqueEasings.add(t.easing);
+            uniqueDurations.add(t.duration);
+          }
+        });
+      }
+
+      // Extract animations
+      const animation = parseAnimation(element, computedStyle);
+      if (animation) {
+        const selector = getSelector(element);
+        const key = `${animation.name}-${animation.duration}`;
+        if (!uniqueAnimations.has(key)) {
+          uniqueAnimations.add(key);
+          animationData.push({
+            selector,
+            ...animation
+          });
+          uniqueEasings.add(animation.easing);
+          uniqueDurations.add(animation.duration);
+        }
+      }
+
+      // Extract transforms (on hover/active, we only get current state)
+      const transform = parseTransform(computedStyle);
+      if (transform) {
+        const selector = getSelector(element);
+        transformData.push({
+          selector,
+          transform
+        });
+      }
+    });
+
+    return {
+      transitions: transitionData,
+      animations: animationData,
+      transforms: transformData,
+      uniqueEasings: Array.from(uniqueEasings),
+      uniqueDurations: Array.from(uniqueDurations)
+    };
+  }
+
+  /**
+   * Main extraction function
+   */
+  function extractAnimations() {
+    const elementData = scanElements();
+    const keyframes = extractKeyframes();
+
+    return {
+      metadata: {
+        timestamp: extractionTimestamp,
+        url: currentUrl,
+        method: 'chrome-devtools',
+        version: '1.0.0'
+      },
+      transitions: elementData.transitions,
+      animations: elementData.animations,
+      transforms: elementData.transforms,
+      keyframes: keyframes,
+      summary: {
+        total_transitions: elementData.transitions.length,
+        total_animations: elementData.animations.length,
+        total_transforms: elementData.transforms.length,
+        total_keyframes: Object.keys(keyframes).length,
+        unique_easings: elementData.uniqueEasings,
+        unique_durations: elementData.uniqueDurations
+      }
+    };
+  }
+
+  // Execute extraction
+  return extractAnimations();
+})();

.claude/scripts/extract-computed-styles.js

@@ -0,0 +1,118 @@
+/**
+ * Extract Computed Styles from DOM
+ *
+ * This script extracts real CSS computed styles from a webpage's DOM
+ * to provide accurate design tokens for UI replication.
+ *
+ * Usage: Execute this function via Chrome DevTools evaluate_script
+ */
+
+(() => {
+  /**
+   * Extract unique values from a set and sort them
+   */
+  const uniqueSorted = (set) => {
+    return Array.from(set)
+      .filter(v => v && v !== 'none' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)')
+      .sort();
+  };
+
+  /**
+   * Parse rgb/rgba to OKLCH format (placeholder - returns original for now)
+   */
+  const toOKLCH = (color) => {
+    // TODO: Implement actual RGB to OKLCH conversion
+    // For now, return the original color with a note
+    return `${color} /* TODO: Convert to OKLCH */`;
+  };
+
+  /**
+   * Extract only key styles from an element
+   */
+  const extractKeyStyles = (element) => {
+    const s = window.getComputedStyle(element);
+    return {
+      color: s.color,
+      bg: s.backgroundColor,
+      borderRadius: s.borderRadius,
+      boxShadow: s.boxShadow,
+      fontSize: s.fontSize,
+      fontWeight: s.fontWeight,
+      padding: s.padding,
+      margin: s.margin
+    };
+  };
+
+  /**
+   * Main extraction function - extract all critical design tokens
+   */
+  const extractDesignTokens = () => {
+    // Include all key UI elements
+    const selectors = [
+      'button', '.btn', '[role="button"]',
+      'input', 'textarea', 'select',
+      'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+      '.card', 'article', 'section',
+      'a', 'p', 'nav', 'header', 'footer'
+    ];
+
+    // Collect all design tokens
+    const tokens = {
+      colors: new Set(),
+      borderRadii: new Set(),
+      shadows: new Set(),
+      fontSizes: new Set(),
+      fontWeights: new Set(),
+      spacing: new Set()
+    };
+
+    // Extract from all elements
+    selectors.forEach(selector => {
+      try {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+          const s = extractKeyStyles(element);
+
+          // Collect all tokens (no limits)
+          if (s.color && s.color !== 'rgba(0, 0, 0, 0)') tokens.colors.add(s.color);
+          if (s.bg && s.bg !== 'rgba(0, 0, 0, 0)') tokens.colors.add(s.bg);
+          if (s.borderRadius && s.borderRadius !== '0px') tokens.borderRadii.add(s.borderRadius);
+          if (s.boxShadow && s.boxShadow !== 'none') tokens.shadows.add(s.boxShadow);
+          if (s.fontSize) tokens.fontSizes.add(s.fontSize);
+          if (s.fontWeight) tokens.fontWeights.add(s.fontWeight);
+
+          // Extract all spacing values
+          [s.padding, s.margin].forEach(val => {
+            if (val && val !== '0px') {
+              val.split(' ').forEach(v => {
+                if (v && v !== '0px') tokens.spacing.add(v);
+              });
+            }
+          });
+        });
+      } catch (e) {
+        console.warn(`Error: ${selector}`, e);
+      }
+    });
+
+    // Return all tokens (no element details to save context)
+    return {
+      metadata: {
+        extractedAt: new Date().toISOString(),
+        url: window.location.href,
+        method: 'computed-styles'
+      },
+      tokens: {
+        colors: uniqueSorted(tokens.colors),
+        borderRadii: uniqueSorted(tokens.borderRadii),  // ALL radius values
+        shadows: uniqueSorted(tokens.shadows),          // ALL shadows
+        fontSizes: uniqueSorted(tokens.fontSizes),
+        fontWeights: uniqueSorted(tokens.fontWeights),
+        spacing: uniqueSorted(tokens.spacing)
+      }
+    };
+  };
+
+  // Execute and return results
+  return extractDesignTokens();
+})();

.claude/scripts/extract-layout-structure.js

@@ -0,0 +1,411 @@
+/**
+ * Extract Layout Structure from DOM - Enhanced Version
+ *
+ * Extracts real layout information from DOM to provide accurate
+ * structural data for UI replication.
+ *
+ * Features:
+ * - Framework detection (Nuxt.js, Next.js, React, Vue, Angular)
+ * - Multi-strategy container detection (strict → relaxed → class-based → framework-specific)
+ * - Intelligent main content detection with common class names support
+ * - Supports modern SPA frameworks
+ * - Detects non-semantic main containers (.main, .content, etc.)
+ * - Progressive exploration: Auto-discovers missing selectors when standard patterns fail
+ * - Suggests new class names to add to script based on actual page structure
+ *
+ * Progressive Exploration:
+ * When fewer than 3 main containers are found, the script automatically:
+ * 1. Analyzes all large visible containers (≥500×300px)
+ * 2. Extracts class name patterns (main/content/wrapper/container/page/etc.)
+ * 3. Suggests new selectors to add to the script
+ * 4. Returns exploration data in result.exploration
+ *
+ * Usage: Execute via Chrome DevTools evaluate_script
+ * Version: 2.2.0
+ */
+
+(() => {
+  /**
+   * Get element's bounding box relative to viewport
+   */
+  const getBounds = (element) => {
+    const rect = element.getBoundingClientRect();
+    return {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height)
+    };
+  };
+
+  /**
+   * Extract layout properties from an element
+   */
+  const extractLayoutProps = (element) => {
+    const s = window.getComputedStyle(element);
+
+    return {
+      // Core layout
+      display: s.display,
+      position: s.position,
+
+      // Flexbox
+      flexDirection: s.flexDirection,
+      justifyContent: s.justifyContent,
+      alignItems: s.alignItems,
+      flexWrap: s.flexWrap,
+      gap: s.gap,
+
+      // Grid
+      gridTemplateColumns: s.gridTemplateColumns,
+      gridTemplateRows: s.gridTemplateRows,
+      gridAutoFlow: s.gridAutoFlow,
+
+      // Dimensions
+      width: s.width,
+      height: s.height,
+      maxWidth: s.maxWidth,
+      minWidth: s.minWidth,
+
+      // Spacing
+      padding: s.padding,
+      margin: s.margin
+    };
+  };
+
+  /**
+   * Identify layout pattern for an element
+   */
+  const identifyPattern = (props) => {
+    const { display, flexDirection, gridTemplateColumns } = props;
+
+    if (display === 'flex' || display === 'inline-flex') {
+      if (flexDirection === 'column') return 'flex-column';
+      if (flexDirection === 'row') return 'flex-row';
+      return 'flex';
+    }
+
+    if (display === 'grid') {
+      const cols = gridTemplateColumns;
+      if (cols && cols !== 'none') {
+        const colCount = cols.split(' ').length;
+        return `grid-${colCount}col`;
+      }
+      return 'grid';
+    }
+
+    if (display === 'block') return 'block';
+
+    return display;
+  };
+
+  /**
+   * Detect frontend framework
+   */
+  const detectFramework = () => {
+    if (document.querySelector('#__nuxt')) return { name: 'Nuxt.js', version: 'unknown' };
+    if (document.querySelector('#__next')) return { name: 'Next.js', version: 'unknown' };
+    if (document.querySelector('[data-reactroot]')) return { name: 'React', version: 'unknown' };
+    if (document.querySelector('[ng-version]')) return { name: 'Angular', version: 'unknown' };
+    if (window.Vue) return { name: 'Vue.js', version: window.Vue.version || 'unknown' };
+    return { name: 'Unknown', version: 'unknown' };
+  };
+
+  /**
+   * Build layout tree recursively
+   */
+  const buildLayoutTree = (element, depth = 0, maxDepth = 3) => {
+    if (depth > maxDepth) return null;
+
+    const props = extractLayoutProps(element);
+    const bounds = getBounds(element);
+    const pattern = identifyPattern(props);
+
+    // Get semantic role
+    const tagName = element.tagName.toLowerCase();
+    const classes = Array.from(element.classList).slice(0, 3); // Max 3 classes
+    const role = element.getAttribute('role');
+
+    // Build node
+    const node = {
+      tag: tagName,
+      classes: classes,
+      role: role,
+      pattern: pattern,
+      bounds: bounds,
+      layout: {
+        display: props.display,
+        position: props.position
+      }
+    };
+
+    // Add flex/grid specific properties
+    if (props.display === 'flex' || props.display === 'inline-flex') {
+      node.layout.flexDirection = props.flexDirection;
+      node.layout.justifyContent = props.justifyContent;
+      node.layout.alignItems = props.alignItems;
+      node.layout.gap = props.gap;
+    }
+
+    if (props.display === 'grid') {
+      node.layout.gridTemplateColumns = props.gridTemplateColumns;
+      node.layout.gridTemplateRows = props.gridTemplateRows;
+      node.layout.gap = props.gap;
+    }
+
+    // Process children for container elements
+    if (props.display === 'flex' || props.display === 'grid' || props.display === 'block') {
+      const children = Array.from(element.children);
+      if (children.length > 0 && children.length < 50) { // Limit to 50 children
+        node.children = children
+          .map(child => buildLayoutTree(child, depth + 1, maxDepth))
+          .filter(child => child !== null);
+      }
+    }
+
+    return node;
+  };
+
+  /**
+   * Find main layout containers with multi-strategy approach
+   */
+  const findMainContainers = () => {
+    const containers = [];
+    const found = new Set();
+
+    // Strategy 1: Strict selectors (body direct children)
+    const strictSelectors = [
+      'body > header',
+      'body > nav',
+      'body > main',
+      'body > footer'
+    ];
+
+    // Strategy 2: Relaxed selectors (any level)
+    const relaxedSelectors = [
+      'header',
+      'nav',
+      'main',
+      'footer',
+      '[role="banner"]',
+      '[role="navigation"]',
+      '[role="main"]',
+      '[role="contentinfo"]'
+    ];
+
+    // Strategy 3: Common class-based main content selectors
+    const commonClassSelectors = [
+      '.main',
+      '.content',
+      '.main-content',
+      '.page-content',
+      '.container.main',
+      '.wrapper > .main',
+      'div[class*="main-wrapper"]',
+      'div[class*="content-wrapper"]'
+    ];
+
+    // Strategy 4: Framework-specific selectors
+    const frameworkSelectors = [
+      '#__nuxt header', '#__nuxt .main', '#__nuxt main', '#__nuxt footer',
+      '#__next header', '#__next .main', '#__next main', '#__next footer',
+      '#app header', '#app .main', '#app main', '#app footer',
+      '[data-app] header', '[data-app] .main', '[data-app] main', '[data-app] footer'
+    ];
+
+    // Try all strategies
+    const allSelectors = [...strictSelectors, ...relaxedSelectors, ...commonClassSelectors, ...frameworkSelectors];
+
+    allSelectors.forEach(selector => {
+      try {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+          // Avoid duplicates and invisible elements
+          if (!found.has(element) && element.offsetParent !== null) {
+            found.add(element);
+            const tree = buildLayoutTree(element, 0, 3);
+            if (tree && tree.bounds.width > 0 && tree.bounds.height > 0) {
+              containers.push(tree);
+            }
+          }
+        });
+      } catch (e) {
+        console.warn(`Selector failed: ${selector}`, e);
+      }
+    });
+
+    // Fallback: If no containers found, use body's direct children
+    if (containers.length === 0) {
+      Array.from(document.body.children).forEach(child => {
+        if (child.offsetParent !== null && !found.has(child)) {
+          const tree = buildLayoutTree(child, 0, 2);
+          if (tree && tree.bounds.width > 100 && tree.bounds.height > 100) {
+            containers.push(tree);
+          }
+        }
+      });
+    }
+
+    return containers;
+  };
+
+  /**
+   * Progressive exploration: Discover main containers when standard selectors fail
+   * Analyzes large visible containers and suggests class name patterns
+   */
+  const exploreMainContainers = () => {
+    const candidates = [];
+    const minWidth = 500;
+    const minHeight = 300;
+
+    // Find all large visible divs
+    const allDivs = document.querySelectorAll('div');
+    allDivs.forEach(div => {
+      const rect = div.getBoundingClientRect();
+      const style = window.getComputedStyle(div);
+
+      // Filter: large size, visible, not header/footer
+      if (rect.width >= minWidth &&
+          rect.height >= minHeight &&
+          div.offsetParent !== null &&
+          !div.closest('header') &&
+          !div.closest('footer')) {
+
+        const classes = Array.from(div.classList);
+        const area = rect.width * rect.height;
+
+        candidates.push({
+          element: div,
+          classes: classes,
+          area: area,
+          bounds: {
+            width: Math.round(rect.width),
+            height: Math.round(rect.height)
+          },
+          display: style.display,
+          depth: getElementDepth(div)
+        });
+      }
+    });
+
+    // Sort by area (largest first) and take top candidates
+    candidates.sort((a, b) => b.area - a.area);
+
+    // Extract unique class patterns from top candidates
+    const classPatterns = new Set();
+    candidates.slice(0, 20).forEach(c => {
+      c.classes.forEach(cls => {
+        // Identify potential main content class patterns
+        if (cls.match(/main|content|container|wrapper|page|body|layout|app/i)) {
+          classPatterns.add(cls);
+        }
+      });
+    });
+
+    return {
+      candidates: candidates.slice(0, 10).map(c => ({
+        classes: c.classes,
+        bounds: c.bounds,
+        display: c.display,
+        depth: c.depth
+      })),
+      suggestedSelectors: Array.from(classPatterns).map(cls => `.${cls}`)
+    };
+  };
+
+  /**
+   * Get element depth in DOM tree
+   */
+  const getElementDepth = (element) => {
+    let depth = 0;
+    let current = element;
+    while (current.parentElement) {
+      depth++;
+      current = current.parentElement;
+    }
+    return depth;
+  };
+
+  /**
+   * Analyze layout patterns
+   */
+  const analyzePatterns = (containers) => {
+    const patterns = {
+      flexColumn: 0,
+      flexRow: 0,
+      grid: 0,
+      sticky: 0,
+      fixed: 0
+    };
+
+    const analyze = (node) => {
+      if (!node) return;
+
+      if (node.pattern === 'flex-column') patterns.flexColumn++;
+      if (node.pattern === 'flex-row') patterns.flexRow++;
+      if (node.pattern && node.pattern.startsWith('grid')) patterns.grid++;
+      if (node.layout.position === 'sticky') patterns.sticky++;
+      if (node.layout.position === 'fixed') patterns.fixed++;
+
+      if (node.children) {
+        node.children.forEach(analyze);
+      }
+    };
+
+    containers.forEach(analyze);
+    return patterns;
+  };
+
+  /**
+   * Main extraction function with progressive exploration
+   */
+  const extractLayout = () => {
+    const framework = detectFramework();
+    const containers = findMainContainers();
+    const patterns = analyzePatterns(containers);
+
+    // Progressive exploration: if too few containers found, explore and suggest
+    let exploration = null;
+    const minExpectedContainers = 3; // At least header, main, footer
+
+    if (containers.length < minExpectedContainers) {
+      exploration = exploreMainContainers();
+
+      // Add warning message
+      exploration.warning = `Only ${containers.length} containers found. Consider adding these selectors to the script:`;
+      exploration.recommendation = exploration.suggestedSelectors.join(', ');
+    }
+
+    const result = {
+      metadata: {
+        extractedAt: new Date().toISOString(),
+        url: window.location.href,
+        framework: framework,
+        method: 'layout-structure-enhanced',
+        version: '2.2.0'
+      },
+      statistics: {
+        totalContainers: containers.length,
+        patterns: patterns
+      },
+      structure: containers
+    };
+
+    // Add exploration results if triggered
+    if (exploration) {
+      result.exploration = {
+        triggered: true,
+        reason: 'Insufficient containers found with standard selectors',
+        discoveredCandidates: exploration.candidates,
+        suggestedSelectors: exploration.suggestedSelectors,
+        warning: exploration.warning,
+        recommendation: exploration.recommendation
+      };
+    }
+
+    return result;
+  };
+
+  // Execute and return results
+  return extractLayout();
+})();

.claude/scripts/gemini-wrapper

@@ -1,282 +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
-
-# 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/get_modules_by_depth.sh

@@ -58,7 +58,7 @@ build_exclusion_filters() {
 
         # OS and editor files
         ".DS_Store" "Thumbs.db" "desktop.ini"
-        "*.stackdump" "core" "*.core"
+        "*.stackdump" "*.core"
 
         # Cloud and deployment
         ".serverless" ".terraform" "terraform.tfstate"

.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/ui-generate-preview.sh

@@ -329,7 +329,7 @@ for style in $styles; do
 ### Style ${style}
 
 EOF3
-    style_guide="../style-consolidation/style-${style}/style-guide.md"
+    style_guide="../style-extraction/style-${style}/style-guide.md"
     if [[ -f "$style_guide" ]]; then
         head -n 10 "$style_guide" | tail -n +2 >> PREVIEW.md 2>/dev/null || echo "Design philosophy and tokens" >> PREVIEW.md
     else

.claude/scripts/ui-instantiate-prototypes.sh

@@ -52,7 +52,7 @@ auto_detect_pages() {
 # Auto-detect style variants count
 auto_detect_style_variants() {
     local base_path="$1"
-    local style_dir="$base_path/../style-consolidation"
+    local style_dir="$base_path/../style-extraction"
 
     if [ ! -d "$style_dir" ]; then
         log_warning "Style consolidation directory not found: $style_dir"
@@ -260,7 +260,7 @@ fi
 
 # Validate STYLE_VARIANTS against actual style directories
 if [ "$STYLE_VARIANTS" -gt 0 ]; then
-    style_dir="$BASE_PATH/../style-consolidation"
+    style_dir="$BASE_PATH/../style-extraction"
 
     if [ ! -d "$style_dir" ]; then
         log_error "Style consolidation directory not found: $style_dir"
@@ -337,7 +337,7 @@ for page in "${PAGE_ARRAY[@]}"; do
             # Define file paths
             TEMPLATE_HTML="_templates/${page}-layout-${l}.html"
             STRUCTURAL_CSS="_templates/${page}-layout-${l}.css"
-            TOKEN_CSS="../style-consolidation/style-${s}/tokens.css"
+            TOKEN_CSS="../style-extraction/style-${s}/tokens.css"
             OUTPUT_HTML="${page}-style-${s}-layout-${l}.html"
 
             # Copy template and replace placeholders
@@ -376,7 +376,7 @@ across all style variants. The HTML structure is identical for all ${page}-layou
 prototypes, with only the design tokens (colors, fonts, spacing) varying.
 
 ## Design System Reference
-Refer to \`../style-consolidation/style-${s}/style-guide.md\` for:
+Refer to \`../style-extraction/style-${s}/style-guide.md\` for:
 - Design philosophy
 - Token usage guidelines
 - Component patterns
@@ -742,9 +742,9 @@ for s in $(seq 1 "$STYLE_VARIANTS"); do
     cat >> PREVIEW.md <<STYLEEOF
 
 ### Style ${s}
-- **Tokens:** \`../style-consolidation/style-${s}/design-tokens.json\`
-- **CSS Variables:** \`../style-consolidation/style-${s}/tokens.css\`
-- **Style Guide:** \`../style-consolidation/style-${s}/style-guide.md\`
+- **Tokens:** \`../style-extraction/style-${s}/design-tokens.json\`
+- **CSS Variables:** \`../style-extraction/style-${s}/tokens.css\`
+- **Style Guide:** \`../style-extraction/style-${s}/style-guide.md\`
 STYLEEOF
 done
 

.claude/scripts/update_module_claude.sh

@@ -1,153 +1,295 @@
 #!/bin/bash
-# Update CLAUDE.md for a specific module with automatic layer detection
-# 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)
-#   Script automatically detects layer depth and selects appropriate template
+#   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:
+#   - Minimal prompts based on unified template
+#   - Respects .gitignore patterns
+#   - Path-focused processing (script only cares about paths)
+#   - Template-driven generation
 
-update_module_claude() {
-    local module_path="$1"
-    local update_type="${2:-full}"
-    local tool="${3:-gemini}"
-    
-    # Validate parameters
-    if [ -z "$module_path" ]; then
-        echo "❌ Error: Module path is required"
-        echo "Usage: update_module_claude.sh <module_path> [update_type]"
+# Build exclusion filters from .gitignore
+build_exclusion_filters() {
+    local filters=""
+
+    # Common system/cache directories to exclude
+    local system_excludes=(
+        ".git" "__pycache__" "node_modules" ".venv" "venv" "env"
+        "dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
+        "coverage" ".nyc_output" "logs" "tmp" "temp"
+    )
+
+    for exclude in "${system_excludes[@]}"; do
+        filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
+    done
+
+    # Find and parse .gitignore (current dir first, then git root)
+    local gitignore_file=""
+
+    # Check current directory first
+    if [ -f ".gitignore" ]; then
+        gitignore_file=".gitignore"
+    else
+        # Try to find git root and check for .gitignore there
+        local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
+        if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
+            gitignore_file="$git_root/.gitignore"
+        fi
+    fi
+
+    # Parse .gitignore if found
+    if [ -n "$gitignore_file" ]; then
+        while IFS= read -r line; do
+            # Skip empty lines and comments
+            [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+
+            # Remove trailing slash and whitespace
+            line=$(echo "$line" | sed 's|/$||' | xargs)
+
+            # Skip wildcards patterns (too complex for simple find)
+            [[ "$line" =~ \* ]] && continue
+
+            # Add to filters
+            filters+=" -not -path '*/$line' -not -path '*/$line/*'"
+        done < "$gitignore_file"
+    fi
+
+    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 strategy="$1"
+    local module_path="$2"
+    local tool="${3:-gemini}"
+    local model="$4"
+
+    # Validate parameters
+    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
+
     if [ ! -d "$module_path" ]; then
         echo "❌ Error: Directory '$module_path' does not exist"
         return 1
     fi
-    
-    # Check if directory has files
-    local file_count=$(find "$module_path" -maxdepth 1 -type f 2>/dev/null | wc -l)
+
+    # 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)
+
+    # Check if directory has files (excluding gitignored paths)
+    local file_count=$(eval "find \"$module_path\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
     if [ $file_count -eq 0 ]; then
-        echo "⚠️  Skipping '$module_path' - no files found"
+        echo "⚠️  Skipping '$module_path' - no files found (after .gitignore filtering)"
         return 0
     fi
-    
-    # Determine documentation layer based on path patterns
-    local layer=""
-    local template_path=""
-    local analysis_strategy=""
-    
-    # Clean path for pattern matching
-    local clean_path=$(echo "$module_path" | sed 's|^\./||')
-    
-    # Pattern-based layer detection
-    if [ "$module_path" = "." ]; then
-        # Root directory
-        layer="Layer 1 (Root)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer1-root.txt"
-        analysis_strategy="--all-files"
-    elif [[ "$clean_path" =~ ^[^/]+$ ]]; then
-        # Top-level directories (e.g., .claude, src, tests)
-        layer="Layer 2 (Domain)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer2-domain.txt"
-        analysis_strategy="@{*/CLAUDE.md}"
-    elif [[ "$clean_path" =~ ^[^/]+/[^/]+$ ]]; then
-        # Second-level directories (e.g., .claude/scripts, src/components)
-        layer="Layer 3 (Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer3-module.txt"
-        analysis_strategy="@{*/CLAUDE.md}"
+
+    # Use unified template for all modules
+    local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.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
-        # Deeper directories (e.g., .claude/workflows/cli-templates/prompts)
-        layer="Layer 4 (Sub-Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer4-submodule.txt"
-        analysis_strategy="--all-files"
+        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 "   Layer: $layer | Type: $update_type | Tool: $tool | Files: $file_count"
-    echo "   Template: $(basename "$template_path") | Strategy: $analysis_strategy"
-    
-    # Generate prompt with template injection
-    local template_content=""
-    if [ -f "$template_path" ]; then
-        template_content=$(cat "$template_path")
+    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"
+
+    # 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
-        echo "   ⚠️  Template not found: $template_path, using fallback"
-        template_content="Update CLAUDE.md documentation for this module following hierarchy standards."
+        # 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
-    
-    local update_context=""
-    if [ "$update_type" = "full" ]; then
-        update_context="
-        Update Mode: Complete refresh
-        - Perform comprehensive analysis of all content
-        - Document patterns, architecture, and purpose
-        - Consider existing documentation hierarchy
-        - 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 at any hierarchy level
-    2. NEVER modify source code files
-    3. Focus exclusively on updating documentation
-    4. Follow the template guidelines exactly
-    
-    $template_content
-    
-    $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
-        - Layer: $layer
-        - Tool: $tool
-        - Analysis Strategy: $analysis_strategy"
 
         # Execute with selected tool
+        # NOTE: Model parameter (-m) is placed AFTER the prompt
         case "$tool" in
             qwen)
-                if [ "$analysis_strategy" = "--all-files" ]; then
-                    qwen --all-files --yolo -p "$final_prompt" 2>&1
-                    tool_result=$?
+                if [ "$model" = "coder-model" ]; then
+                    # coder-model is default, -m is optional
+                    qwen -p "$final_prompt" --yolo 2>&1
                 else
-                    qwen --yolo -p "$analysis_strategy $final_prompt" 2>&1
-                    tool_result=$?
+                    qwen -p "$final_prompt" -m "$model" --yolo 2>&1
                 fi
+                tool_result=$?
                 ;;
             codex)
-                if [ "$analysis_strategy" = "--all-files" ]; then
-                    codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
-                    tool_result=$?
-                else
-                    codex --full-auto exec "$final_prompt CONTEXT: $analysis_strategy" --skip-git-repo-check -s danger-full-access 2>&1
-                    tool_result=$?
-                fi
+                codex --full-auto exec "$final_prompt" -m "$model" --skip-git-repo-check -s danger-full-access 2>&1
+                tool_result=$?
                 ;;
-            gemini|*)
-                if [ "$analysis_strategy" = "--all-files" ]; then
-                    gemini --all-files --yolo -p "$final_prompt" 2>&1
-                    tool_result=$?
-                else
-                    gemini --yolo -p "$analysis_strategy $final_prompt" 2>&1
-                    tool_result=$?
-                fi
+            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
 
@@ -170,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/prompt-enhancer/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: Prompt Enhancer
+description: Transform vague prompts into actionable specs using intelligent analysis and session memory. Use when user input contains -e or --enhance flag.
+allowed-tools: (none)
+---
+
+# Prompt Enhancer
+
+**Transform**: Vague intent → Structured specification (Memory-based, Direct Output)
+
+**Languages**: English + Chinese (中英文语义识别)
+
+## Process (Internal → Direct Output)
+
+**Internal Analysis**: Intelligently extract session context, identify tech stack, and structure into actionable format.
+
+**Output**: Direct structured prompt (no intermediate steps shown)
+
+## Output Format
+
+**Dynamic Structure**: Adapt fields based on task type and context needs. Not all fields are required.
+
+**Core Fields** (always present):
+- **INTENT**: One-sentence technical goal
+- **ACTION**: Concrete steps with technical details
+
+**Optional Fields** (include when relevant):
+- **TECH STACK**: Relevant technologies (when tech-specific)
+- **CONTEXT**: Session memory findings (when context matters)
+- **ATTENTION**: Critical constraints (when risks/requirements exist)
+- **SCOPE**: Affected modules/files (for multi-module tasks)
+- **METRICS**: Success criteria (for optimization/performance tasks)
+- **DEPENDENCIES**: Related components (for integration tasks)
+
+**Example (Simple Task)**:
+```
+📋 ENHANCED PROMPT
+
+INTENT: Fix authentication token validation in JWT middleware
+
+ACTION:
+1. Review token expiration logic in auth middleware
+2. Add proper error handling for expired tokens
+3. Test with valid/expired/malformed tokens
+```
+
+**Example (Complex Task)**:
+```
+📋 ENHANCED PROMPT
+
+INTENT: Optimize API performance with caching and database indexing
+
+TECH STACK:
+- Redis: Response caching
+- PostgreSQL: Query optimization
+
+CONTEXT:
+- API response times >2s mentioned in previous conversation
+- PostgreSQL slow query logs show N+1 problems
+
+ACTION:
+1. Profile endpoints to identify slow queries
+2. Add PostgreSQL indexes on frequently queried columns
+3. Implement Redis caching for read-heavy endpoints
+4. Add cache invalidation on data updates
+
+METRICS:
+- Target: <500ms API response time
+- Cache hit ratio: >80%
+
+ATTENTION:
+- Maintain backward compatibility with existing API contracts
+- Handle cache invalidation correctly to avoid stale data
+```
+## Workflow
+
+```
+Trigger (-e/--enhance) → Internal Analysis → Dynamic Output
+         ↓                       ↓                  ↓
+   User Input           Assess Task Type      Select Fields
+                    Extract Memory Context    Structure Prompt
+```
+
+1. **Detect**: User input contains `-e` or `--enhance`
+2. **Analyze**:
+   - Determine task type (fix/optimize/implement/refactor)
+   - Extract relevant session context
+   - Identify tech stack and constraints
+3. **Structure**:
+   - Always include: INTENT + ACTION
+   - Conditionally add: TECH STACK, CONTEXT, ATTENTION, METRICS, etc.
+4. **Output**: Present dynamically structured prompt
+
+## Enhancement Guidelines (Internal)
+
+**Always Include**:
+- Clear, actionable INTENT
+- Concrete ACTION steps with technical details
+
+**Add When Relevant**:
+- TECH STACK: Task involves specific technologies
+- CONTEXT: Session memory provides useful background
+- ATTENTION: Security/compatibility/performance concerns exist
+- SCOPE: Multi-module or cross-component changes
+- METRICS: Performance/optimization goals need measurement
+- DEPENDENCIES: Integration points matter
+
+**Quality Checks**:
+- Make vague intent explicit
+- Resolve ambiguous references
+- Add testing/validation steps
+- Include constraints from memory
+
+## Best Practices
+
+- ✅ Trigger only on `-e`/`--enhance` flags
+- ✅ Use **dynamic field selection** based on task type
+- ✅ Extract **memory context ONLY** (no file reading)
+- ✅ Always include INTENT + ACTION as core fields
+- ✅ Add optional fields only when relevant to task
+- ✅ Direct output (no intermediate steps shown)
+- ❌ NO tool calls
+- ❌ NO file operations (Bash, Read, Glob, Grep)
+- ❌ NO fixed template - adapt to task needs

.claude/workflows/cli-templates/planning-roles/synthesis-role.md

@@ -0,0 +1,393 @@
+# Synthesis Role Template
+
+## Purpose
+Generate comprehensive synthesis-specification.md that consolidates all role perspectives from brainstorming into actionable implementation specification.
+
+## Role Focus
+- **Cross-Role Integration**: Synthesize insights from all participating roles
+- **Decision Transparency**: Document both adopted and rejected alternatives
+- **Process Integration**: Include team capabilities, risks, and collaboration patterns
+- **Visual Documentation**: Key diagrams via Mermaid (architecture, data model, user journey)
+- **Priority Matrix**: Quantified recommendations with multi-dimensional evaluation
+- **Actionable Planning**: Phased implementation roadmap with clear next steps
+
+## Document Structure Template
+
+### synthesis-specification.md
+
+```markdown
+# [Topic] - Integrated Implementation Specification
+
+**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
+**Source Integration**: All brainstorming role perspectives consolidated
+**Document Type**: Requirements & Design Specification (WHAT to build)
+
+---
+
+## Executive Summary
+
+Provide strategic overview covering:
+- **Key Insights**: Major findings from cross-role analysis
+- **Breakthrough Opportunities**: Innovation opportunities identified
+- **Implementation Priorities**: High-level prioritization with rationale
+- **Strategic Direction**: Recommended approach and vision
+
+Include metrics from role synthesis:
+- Roles synthesized: [count]
+- Requirements captured: [FR/NFR/BR counts]
+- Controversial decisions: [count]
+- Risk factors identified: [count]
+
+---
+
+## Key Designs & Decisions
+
+### Core Architecture Diagram
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+*Reference: @system-architect/analysis.md#architecture-diagram*
+
+### User Journey Map
+![User Journey](./assets/user-journey.png)
+*Reference: @ux-expert/analysis.md#user-journey*
+
+### Data Model Overview
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+```
+*Reference: @data-architect/analysis.md#data-model*
+
+### Architecture Decision Records (ADRs)
+
+**ADR-01: [Decision Title]**
+- **Context**: Background and problem statement
+- **Decision**: Chosen approach
+- **Rationale**: Why this approach was selected
+- **Consequences**: Expected impacts and tradeoffs
+- **Reference**: @[role]/analysis.md#adr-01
+
+[Repeat for each major architectural decision]
+
+---
+
+## Controversial Points & Alternatives
+
+Document disagreements and alternative approaches considered:
+
+| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
+|-------|------------------|-------------------------|--------------------| -----------------|
+| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
+| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
+
+*This section preserves decision context and rejected alternatives for future reference.*
+
+**Analysis Guidelines**:
+- Identify where roles disagreed on approach
+- Document both solutions with equal respect
+- Explain why one was chosen over the other
+- Preserve dissenting perspectives for future consideration
+
+---
+
+## Requirements & Acceptance Criteria
+
+### Functional Requirements
+
+| ID | Description | Rationale Summary | Source | Priority | Acceptance Criteria | Dependencies |
+|----|-------------|-------------------|--------|----------|---------------------|--------------|
+| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password with MFA | None |
+| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON formats | FR-01 |
+
+**Guidelines**:
+- Extract from product-manager, product-owner, and other role analyses
+- Include rationale summary for immediate understanding
+- Specify clear, testable acceptance criteria
+- Map dependencies between requirements
+
+### Non-Functional Requirements
+
+| ID | Description | Rationale Summary | Target | Validation Method | Source |
+|----|-------------|-------------------|--------|-------------------|--------|
+| NFR-01 | Response time | UX research shows <200ms critical for engagement | <200ms | Load testing | @ux-expert/analysis.md |
+| NFR-02 | Data encryption | Compliance requirement (GDPR, HIPAA) | AES-256 | Security audit | @security-expert/analysis.md |
+
+**Guidelines**:
+- Extract performance, security, scalability requirements
+- Include specific, measurable targets
+- Reference source role for traceability
+
+### Business Requirements
+
+| ID | Description | Rationale Summary | Value | Success Metric | Source |
+|----|-------------|-------------------|-------|----------------|--------|
+| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
+| BR-02 | Revenue growth | Business case justification for investment | High | 25% MRR increase | @product-owner/analysis.md |
+
+**Guidelines**:
+- Capture business value and success metrics
+- Link to product-manager and product-owner analyses
+
+---
+
+## Design Specifications
+
+### UI/UX Guidelines
+**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md
+
+- **Component Specifications**: Reusable UI components and patterns
+- **Interaction Patterns**: User interaction flows and behaviors
+- **Visual Design System**: Colors, typography, spacing guidelines
+- **Accessibility Requirements**: WCAG compliance, screen reader support
+- **User Flow Specifications**: Step-by-step user journeys
+- **Responsive Design**: Mobile, tablet, desktop breakpoints
+
+### Architecture Design
+**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md
+
+- **System Architecture**: High-level component architecture and interactions
+- **Data Flow**: Data processing pipelines and transformations
+- **Storage Strategy**: Database selection, schema design, caching
+- **Technology Stack**: Languages, frameworks, infrastructure decisions
+- **Integration Patterns**: Service communication, API design
+- **Scalability Approach**: Horizontal/vertical scaling strategies
+
+### Domain Expertise & Standards
+**Consolidated from**: @subject-matter-expert/analysis.md
+
+- **Industry Standards**: Compliance requirements (HIPAA, GDPR, etc.)
+- **Best Practices**: Domain-specific proven patterns
+- **Regulatory Requirements**: Legal and compliance constraints
+- **Technical Quality**: Code quality, testing, documentation standards
+- **Domain-Specific Patterns**: Industry-proven architectural patterns
+
+---
+
+## Process & Collaboration Concerns
+**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
+
+### Team Capability Assessment
+
+| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
+|----------------|---------------|--------------|---------------------|-----------|
+| Kubernetes | Intermediate | Need advanced knowledge for scaling | Training + external consultant | @scrum-master/analysis.md |
+| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
+| GraphQL | Beginner | Significant gap for API layer | 2-week training + mentor pairing | @scrum-master/analysis.md |
+
+**Guidelines**:
+- Identify all required technical skills
+- Assess team's current capability level
+- Document gap and mitigation plan
+- Estimate timeline impact of skill gaps
+
+### Process Risks
+
+| Risk | Impact | Probability | Mitigation | Owner | Reference |
+|------|--------|-------------|------------|-------|-----------|
+| Cross-team API dependency | High | Medium | Early API contract definition | Tech Lead | @scrum-master/analysis.md |
+| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | Product Manager | @ux-expert/analysis.md |
+
+**Guidelines**:
+- Capture both technical and process risks
+- Include probability and impact assessment
+- Specify concrete mitigation strategies
+- Assign ownership for risk management
+
+### Collaboration Patterns
+
+Document recommended collaboration workflows:
+
+- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
+- **Architecture Reviews**: Weekly arch review for system-level decisions
+- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
+- **Code Review Process**: PR review within 24 hours, 2 approvals required
+- **Daily Standups**: 15-minute sync across all roles
+
+*Reference: @scrum-master/analysis.md#collaboration*
+
+### Timeline Constraints
+
+Document known constraints that affect planning:
+
+- **Blocking Dependencies**: Project-X API must complete before Phase 2
+- **Resource Constraints**: Only 2 backend developers available in Q1
+- **External Dependencies**: Third-party OAuth provider integration timeline (6 weeks)
+- **Hard Deadlines**: MVP launch date for investor demo (Q2 end)
+
+*Reference: @scrum-master/analysis.md#constraints*
+
+---
+
+## Implementation Roadmap (High-Level)
+
+### Development Phases
+
+**Phase 1** (0-3 months): Foundation and Core Features
+- Infrastructure setup and basic architecture
+- Core authentication and user management
+- Essential functional requirements (FR-01, FR-02, FR-03)
+- Foundational UI components
+
+**Phase 2** (3-6 months): Advanced Features and Integrations
+- Advanced functional requirements
+- Third-party integrations
+- Analytics and reporting
+- Advanced UI/UX enhancements
+
+**Phase 3** (6+ months): Optimization and Innovation
+- Performance optimization
+- Advanced analytics and ML features
+- Innovation opportunities from brainstorming
+- Technical debt reduction
+
+### Technical Guidelines
+
+**Development Standards**:
+- Code organization and project structure
+- Naming conventions and style guides
+- Version control and branching strategy
+- Development environment setup
+
+**Testing Strategy**:
+- Unit testing (80% coverage minimum)
+- Integration testing approach
+- E2E testing for critical paths
+- Performance testing benchmarks
+
+**Deployment Approach**:
+- CI/CD pipeline configuration
+- Staging and production environments
+- Monitoring and alerting setup
+- Rollback procedures
+
+### Feature Grouping (Epic-Level)
+
+**Epic 1: User Authentication & Authorization**
+- Requirements: FR-01, FR-03, NFR-02
+- Priority: High
+- Dependencies: None
+- Estimated Timeline: 4 weeks
+
+**Epic 2: Data Management & Export**
+- Requirements: FR-02, FR-05, NFR-01
+- Priority: Medium
+- Dependencies: Epic 1
+- Estimated Timeline: 6 weeks
+
+[Continue for all major feature groups]
+
+**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
+
+---
+
+## Risk Assessment & Mitigation
+
+### Critical Risks Identified
+
+**Technical Risks**:
+1. **Risk**: Database scalability under projected load
+   - **Impact**: High (system downtime, user dissatisfaction)
+   - **Probability**: Medium
+   - **Mitigation**: Early load testing, database sharding plan, caching strategy
+   - **Owner**: System Architect
+
+2. **Risk**: Third-party API reliability and rate limits
+   - **Impact**: Medium (feature degradation)
+   - **Probability**: High
+   - **Mitigation**: Implement circuit breakers, fallback mechanisms, local caching
+   - **Owner**: Backend Lead
+
+**Process Risks**:
+3. **Risk**: Cross-team coordination delays
+   - **Impact**: High (timeline slippage)
+   - **Probability**: Medium
+   - **Mitigation**: Weekly sync meetings, clear API contracts, buffer time in estimates
+   - **Owner**: Scrum Master
+
+4. **Risk**: Skill gap in new technologies
+   - **Impact**: Medium (quality issues, slower delivery)
+   - **Probability**: High
+   - **Mitigation**: Training program, pair programming, external consultant support
+   - **Owner**: Engineering Manager
+
+### Success Factors
+
+**Key factors for implementation success**:
+- Strong product-engineering collaboration with weekly syncs
+- Clear acceptance criteria and definition of done
+- Regular user testing and feedback integration
+- Proactive risk monitoring and mitigation
+
+**Continuous Monitoring Requirements**:
+- Sprint velocity and burndown tracking
+- Code quality metrics (coverage, complexity, tech debt)
+- Performance metrics (response time, error rate, uptime)
+- User satisfaction metrics (NPS, usage analytics)
+
+**Quality Gates and Validation Checkpoints**:
+- Code review approval before merge
+- Automated test suite passing (unit, integration, E2E)
+- Security scan and vulnerability assessment
+- Performance benchmark validation
+- Stakeholder demo and approval before production
+
+---
+
+*Complete implementation specification consolidating all role perspectives into actionable guidance*
+```
+
+## Analysis Guidelines for Agent
+
+### Cross-Role Synthesis Process
+
+1. **Load All Role Analyses**: Read topic-framework.md and all discovered */analysis.md files
+2. **Extract Key Insights**: Identify main recommendations, concerns, and innovations from each role
+3. **Identify Consensus Areas**: Find common themes across multiple roles
+4. **Document Disagreements**: Capture controversial points where roles differ
+5. **Prioritize Recommendations**: Use multi-dimensional scoring:
+   - Business impact (product-manager, product-owner)
+   - Technical feasibility (system-architect, data-architect)
+   - Implementation effort (scrum-master, developers)
+   - Risk assessment (security-expert, subject-matter-expert)
+6. **Create Comprehensive Roadmap**: Synthesize into phased implementation plan
+
+### Quality Standards
+
+- **Completeness**: Integrate ALL discovered role analyses without gaps
+- **Visual Clarity**: Include key diagrams (architecture, data model, user journey) via Mermaid or images
+- **Decision Transparency**: Document not just decisions, but alternatives and why they were rejected
+- **Insight Generation**: Identify cross-role patterns and deep insights beyond individual analyses
+- **Actionability**: Provide specific, executable recommendations with clear rationale
+- **Balance**: Give equal weight to all role perspectives (process, UX, compliance, functional)
+- **Forward-Looking**: Include long-term strategic and innovation considerations
+- **Traceability**: Every major decision links to source role analysis via @ references
+
+### @ Reference System
+
+Use @ references to link back to source role analyses:
+- `@role/analysis.md` - Reference entire role analysis
+- `@role/analysis.md#section` - Reference specific section
+- `@topic-framework.md#point-3` - Reference framework discussion point
+
+### Dynamic Role Handling
+
+- Not all roles participate in every brainstorming session
+- Synthesize only roles that produced analysis.md files
+- Adapt structure based on available role perspectives
+- If role missing, acknowledge gap if relevant to topic
+
+### Output Validation
+
+Before completing, verify:
+- [ ] All discovered role analyses integrated
+- [ ] Framework discussion points addressed across roles
+- [ ] Controversial points documented with dissenting roles identified
+- [ ] Process concerns (team skills, risks, collaboration) captured
+- [ ] Quantified priority recommendations with evaluation criteria
+- [ ] Actionable implementation plan with phased approach
+- [ ] Comprehensive risk assessment with mitigation strategies
+- [ ] @ references to source analyses throughout document

.claude/workflows/cli-templates/prompts/analysis/architecture.txt

@@ -1,16 +1,29 @@
-Analyze system architecture and design decisions:
+Analyze system architecture and design decisions.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Analyze system-wide structure, not just isolated components
+□ Provide file:line references for key architectural elements
+□ Distinguish between intended design and actual implementation
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify main architectural patterns and design principles
 2. Map module dependencies and component relationships
 3. Assess integration points and data flow patterns
 4. Evaluate scalability and maintainability aspects
 5. Document architectural trade-offs and design decisions
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Architectural diagrams or textual descriptions
 - Dependency mapping with specific file references
 - Integration point documentation with examples
 - Scalability assessment and bottleneck identification
+- Prioritized recommendations for architectural improvement
 
-Focus on high-level design patterns and system-wide architectural concerns.
+## VERIFICATION CHECKLIST ✓
+□ All major components and their relationships analyzed
+□ Key architectural decisions and trade-offs are documented
+□ Data flow and integration points are clearly mapped
+□ Scalability and maintainability findings are supported by evidence
+
+Focus: High-level design patterns and system-wide architectural concerns.

.claude/workflows/cli-templates/prompts/analysis/pattern.txt

@@ -1,16 +1,28 @@
-Analyze implementation patterns and code structure:
+Analyze implementation patterns and code structure.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Analyze ALL files in CONTEXT (not just samples)
+□ Provide file:line references for every pattern identified
+□ Distinguish between good patterns and anti-patterns
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify common code patterns and architectural decisions
 2. Extract reusable utilities and shared components
 3. Document existing conventions and coding standards
 4. Assess pattern consistency and identify anti-patterns
 5. Suggest improvements and optimization opportunities
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Specific file:line references for all findings
 - Code snippets demonstrating identified patterns
 - Clear recommendations for pattern improvements
-- Standards compliance assessment
+- Standards compliance assessment with priority levels
 
-Focus on actionable insights and concrete implementation guidance.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed (not partial coverage)
+□ Every pattern backed by code reference (file:line)
+□ Anti-patterns clearly distinguished from good patterns
+□ Recommendations prioritized by impact
+
+Focus: Actionable insights with concrete implementation guidance.

.claude/workflows/cli-templates/prompts/analysis/performance.txt

@@ -1,16 +1,29 @@
-Analyze performance characteristics and optimization opportunities:
+Analyze performance characteristics and optimization opportunities.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Focus on measurable metrics (e.g., latency, memory, CPU usage)
+□ Provide file:line references for all identified bottlenecks
+□ Distinguish between algorithmic and resource-based issues
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify performance bottlenecks and resource usage patterns
 2. Assess algorithm efficiency and data structure choices
 3. Evaluate caching strategies and optimization techniques
 4. Review memory management and resource cleanup
 5. Document performance metrics and improvement opportunities
 
-## Output Requirements:
-- Performance bottleneck identification with specific locations
+## OUTPUT REQUIREMENTS
+- Performance bottleneck identification with specific file:line locations
 - Algorithm complexity analysis and optimization suggestions
 - Caching pattern documentation and recommendations
 - Memory usage patterns and optimization opportunities
+- Prioritized list of performance improvements
 
-Focus on measurable performance improvements and concrete optimization strategies.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed for performance characteristics
+□ Every bottleneck is backed by a code reference (file:line)
+□ Both algorithmic and resource-related issues are covered
+□ Recommendations are prioritized by potential impact
+
+Focus: Measurable performance improvements and concrete optimization strategies.

.claude/workflows/cli-templates/prompts/analysis/quality.txt

@@ -1,16 +1,29 @@
-Analyze code quality and maintainability aspects:
+Analyze code quality and maintainability aspects.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Analyze against the project's established coding standards
+□ Provide file:line references for all quality issues
+□ Assess both implementation code and test coverage
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Assess code organization and structural quality
 2. Evaluate naming conventions and readability standards
 3. Review error handling and logging practices
 4. Analyze test coverage and testing strategies
 5. Document technical debt and improvement priorities
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Code quality metrics and specific improvement areas
 - Naming convention consistency analysis
-- Error handling pattern documentation
+- Error handling and logging pattern documentation
 - Test coverage assessment with gap identification
+- Prioritized list of technical debt to address
 
-Focus on maintainability improvements and long-term code health.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed for code quality
+□ Every finding is backed by a code reference (file:line)
+□ Both code and test quality have been evaluated
+□ Recommendations are prioritized by impact on maintainability
+
+Focus: Maintainability improvements and long-term code health.

.claude/workflows/cli-templates/prompts/analysis/security.txt

@@ -1,16 +1,29 @@
-Analyze security implementation and potential vulnerabilities:
+Analyze security implementation and potential vulnerabilities.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Identify all data entry points and external system interfaces
+□ Provide file:line references for all potential vulnerabilities
+□ Classify risks by severity and type (e.g., OWASP Top 10)
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify authentication and authorization mechanisms
 2. Assess input validation and sanitization practices
 3. Review data encryption and secure storage methods
 4. Evaluate API security and access control patterns
 5. Document security risks and compliance considerations
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Security vulnerability findings with file:line references
 - Authentication/authorization pattern documentation
-- Input validation examples and gaps
+- Input validation examples and identified gaps
 - Encryption usage patterns and recommendations
+- Prioritized remediation plan based on risk level
 
-Focus on identifying security gaps and providing actionable remediation steps.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed for security vulnerabilities
+□ Every finding is backed by a code reference (file:line)
+□ Both authentication and data handling are covered
+□ Recommendations include clear, actionable remediation steps
+
+Focus: Identifying security gaps and providing actionable remediation steps.

.claude/workflows/cli-templates/prompts/development/component.txt

@@ -1,37 +1,55 @@
-You are tasked with creating a reusable component in this codebase. Follow these guidelines:
+Create a reusable component following project conventions and best practices.
 
-## Design Phase:
+## CORE CHECKLIST ⚡
+□ Analyze existing component patterns BEFORE implementing
+□ Follow established naming conventions and prop patterns
+□ Include comprehensive tests (unit + visual + accessibility)
+□ Provide complete TypeScript types and documentation
+
+## IMPLEMENTATION PHASES
+
+### Design Phase
 1. Analyze existing component patterns and structures
 2. Identify reusable design principles and styling approaches
 3. Review component hierarchy and prop patterns
 4. Study existing component documentation and usage
 
-## Development Phase:
+### Development Phase
 1. Create component with proper TypeScript interfaces
 2. Implement following established naming conventions
 3. Add appropriate default props and validation
 4. Include comprehensive prop documentation
 
-## Styling Phase:
+### Styling Phase
 1. Follow existing styling methodology (CSS modules, styled-components, etc.)
 2. Ensure responsive design principles
 3. Add proper theming support if applicable
 4. Include accessibility considerations (ARIA, keyboard navigation)
 
-## Testing Phase:
+### Testing Phase
 1. Write component tests covering all props and states
 2. Test accessibility compliance
 3. Add visual regression tests if applicable
 4. Test component in different contexts and layouts
 
-## Documentation Phase:
+### Documentation Phase
 1. Create usage examples and code snippets
 2. Document all props and their purposes
 3. Include accessibility guidelines
 4. Add integration examples with other components
 
-## Output Requirements:
-- Provide complete component implementation
-- Include comprehensive TypeScript types
-- Show usage examples and integration patterns
-- Document component API and best practices
+## OUTPUT REQUIREMENTS
+- Complete component implementation with TypeScript types
+- Usage examples and integration patterns
+- Component API documentation and best practices
+- Test suite with accessibility validation
+- File:line references for pattern sources
+
+## VERIFICATION CHECKLIST ✓
+□ Implementation follows existing component patterns
+□ Complete TypeScript types and prop documentation
+□ Comprehensive tests (unit + visual + accessibility)
+□ Accessibility compliance (ARIA, keyboard navigation)
+□ Usage examples and integration documented
+
+Focus: Production-ready reusable component with comprehensive documentation and testing.

.claude/workflows/cli-templates/prompts/development/debugging.txt

@@ -1,37 +1,55 @@
-You are tasked with debugging and resolving issues in this codebase. Follow these systematic guidelines:
+Debug and resolve issues systematically in the codebase.
 
-## Issue Analysis Phase:
+## CORE CHECKLIST ⚡
+□ Identify and reproduce the issue completely before fixing
+□ Perform root cause analysis (not just symptom treatment)
+□ Provide file:line references for all changes
+□ Add tests to prevent regression of this specific issue
+
+## IMPLEMENTATION PHASES
+
+### Issue Analysis Phase
 1. Identify and reproduce the reported issue
 2. Analyze error logs and stack traces
 3. Study code flow and identify potential failure points
 4. Review recent changes that might have introduced the issue
 
-## Investigation Phase:
+### Investigation Phase
 1. Add strategic logging and debugging statements
 2. Use debugging tools and profilers as appropriate
 3. Test with different input conditions and edge cases
 4. Isolate the root cause through systematic elimination
 
-## Root Cause Analysis:
+### Root Cause Analysis
 1. Document the exact cause of the issue
 2. Identify contributing factors and conditions
 3. Assess impact scope and affected functionality
 4. Determine if similar issues exist elsewhere
 
-## Resolution Phase:
+### Resolution Phase
 1. Implement minimal, targeted fix for the root cause
 2. Ensure fix doesn't introduce new issues or regressions
 3. Add proper error handling and validation
 4. Include defensive programming measures
 
-## Prevention Phase:
+### Prevention Phase
 1. Add tests to prevent regression of this issue
 2. Improve error messages and logging
 3. Add monitoring or alerts for early detection
 4. Document lessons learned and prevention strategies
 
-## Output Requirements:
-- Provide detailed root cause analysis
-- Show exact code changes made to resolve the issue
-- Include new tests added to prevent regression
-- Document debugging process and lessons learned
+## OUTPUT REQUIREMENTS
+- Detailed root cause analysis with file:line references
+- Exact code changes made to resolve the issue
+- New tests added to prevent regression
+- Debugging process documentation and lessons learned
+- Impact assessment and affected functionality
+
+## VERIFICATION CHECKLIST ✓
+□ Root cause identified and documented (not just symptoms)
+□ Minimal fix applied without introducing new issues
+□ Tests added to prevent this specific regression
+□ Similar issues checked and addressed if found
+□ Prevention measures documented
+
+Focus: Systematic root cause resolution with regression prevention.

.claude/workflows/cli-templates/prompts/development/feature.txt

@@ -1,31 +1,49 @@
-You are tasked with implementing a new feature in this codebase. Follow these guidelines:
+Implement a new feature following project conventions and best practices.
 
-## Analysis Phase:
+## CORE CHECKLIST ⚡
+□ Study existing code patterns BEFORE implementing
+□ Follow established project conventions and architecture
+□ Include comprehensive tests (unit + integration)
+□ Provide file:line references for all changes
+
+## IMPLEMENTATION PHASES
+
+### Analysis Phase
 1. Study existing code patterns and conventions
 2. Identify similar features and their implementation approaches
 3. Review project architecture and design principles
 4. Understand dependencies and integration points
 
-## Implementation Phase:
+### Implementation Phase
 1. Create feature following established patterns
 2. Implement with proper error handling and validation
 3. Add comprehensive logging for debugging
 4. Follow security best practices
 
-## Integration Phase:
+### Integration Phase
 1. Ensure seamless integration with existing systems
 2. Update configuration files as needed
 3. Add proper TypeScript types and interfaces
 4. Update documentation and comments
 
-## Testing Phase:
+### Testing Phase
 1. Write unit tests covering edge cases
 2. Add integration tests for feature workflows
 3. Verify error scenarios are properly handled
 4. Test performance and security implications
 
-## Output Requirements:
-- Provide file:line references for all changes
-- Include code examples demonstrating key patterns
-- Explain architectural decisions made
-- Document any new dependencies or configurations
+## OUTPUT REQUIREMENTS
+- File:line references for all changes
+- Code examples demonstrating key patterns
+- Explanation of architectural decisions made
+- Documentation of new dependencies or configurations
+- Test coverage summary
+
+## VERIFICATION CHECKLIST ✓
+□ Implementation follows existing patterns (no divergence)
+□ Complete test coverage (unit + integration)
+□ Documentation updated (code comments + external docs)
+□ Integration verified (no breaking changes)
+□ Security and performance validated
+
+Focus: Production-ready implementation with comprehensive testing and documentation.

.claude/workflows/cli-templates/prompts/development/refactor.txt

@@ -1,37 +1,55 @@
-You are tasked with refactoring existing code to improve quality, performance, or maintainability. Follow these guidelines:
+Refactor existing code to improve quality, performance, or maintainability.
 
-## Analysis Phase:
+## CORE CHECKLIST ⚡
+□ Preserve existing functionality (no behavioral changes unless specified)
+□ Ensure all existing tests continue to pass
+□ Plan incremental changes (avoid big-bang refactoring)
+□ Provide file:line references for all modifications
+
+## IMPLEMENTATION PHASES
+
+### Analysis Phase
 1. Identify code smells and technical debt
 2. Analyze performance bottlenecks and inefficiencies
 3. Review code complexity and maintainability metrics
 4. Study existing test coverage and identify gaps
 
-## Planning Phase:
+### Planning Phase
 1. Create refactoring strategy preserving existing functionality
 2. Identify breaking changes and migration paths
 3. Plan incremental refactoring steps
 4. Consider backward compatibility requirements
 
-## Refactoring Phase:
+### Refactoring Phase
 1. Apply SOLID principles and design patterns
 2. Improve code readability and documentation
 3. Optimize performance while maintaining functionality
 4. Reduce code duplication and improve reusability
 
-## Validation Phase:
+### Validation Phase
 1. Ensure all existing tests continue to pass
 2. Add new tests for improved code coverage
 3. Verify performance improvements with benchmarks
 4. Test edge cases and error scenarios
 
-## Migration Phase:
+### Migration Phase
 1. Update dependent code to use refactored interfaces
 2. Update documentation and usage examples
 3. Provide migration guides for breaking changes
 4. Add deprecation warnings for old interfaces
 
-## Output Requirements:
-- Provide before/after code comparisons
-- Document performance improvements achieved
-- Include migration instructions for breaking changes
-- Show updated test coverage and quality metrics
+## OUTPUT REQUIREMENTS
+- Before/after code comparisons with file:line references
+- Performance improvements documented with benchmarks
+- Migration instructions for breaking changes
+- Updated test coverage and quality metrics
+- Technical debt reduction summary
+
+## VERIFICATION CHECKLIST ✓
+□ All existing tests pass (functionality preserved)
+□ New tests added for improved coverage
+□ Performance verified with benchmarks (if applicable)
+□ Backward compatibility maintained or migration provided
+□ Documentation updated with refactoring changes
+
+Focus: Incremental quality improvement while preserving functionality.

.claude/workflows/cli-templates/prompts/development/testing.txt

@@ -1,43 +1,61 @@
-You are tasked with creating comprehensive tests for this codebase. Follow these guidelines:
+Create comprehensive tests for the codebase.
 
-## Test Strategy Phase:
+## CORE CHECKLIST ⚡
+□ Analyze existing test coverage and identify gaps
+□ Follow project testing frameworks and conventions
+□ Include unit, integration, and end-to-end tests
+□ Ensure tests are reliable and deterministic
+
+## IMPLEMENTATION PHASES
+
+### Test Strategy Phase
 1. Analyze existing test coverage and identify gaps
 2. Study codebase architecture and critical paths
 3. Identify edge cases and error scenarios
 4. Review testing frameworks and conventions used
 
-## Unit Testing Phase:
+### Unit Testing Phase
 1. Write tests for individual functions and methods
 2. Test all branches and conditional logic
 3. Cover edge cases and boundary conditions
 4. Mock external dependencies appropriately
 
-## Integration Testing Phase:
+### Integration Testing Phase
 1. Test interactions between components and modules
 2. Verify API endpoints and data flow
 3. Test database operations and transactions
 4. Validate external service integrations
 
-## End-to-End Testing Phase:
+### End-to-End Testing Phase
 1. Test complete user workflows and scenarios
 2. Verify critical business logic and processes
 3. Test error handling and recovery mechanisms
 4. Validate performance under load
 
-## Quality Assurance:
+### Quality Assurance
 1. Ensure tests are reliable and deterministic
 2. Make tests readable and maintainable
 3. Add proper test documentation and comments
 4. Follow testing best practices and conventions
 
-## Test Data Management:
+### Test Data Management
 1. Create realistic test data and fixtures
 2. Ensure test isolation and cleanup
 3. Use factories or builders for complex objects
 4. Handle sensitive data appropriately in tests
 
-## Output Requirements:
-- Provide comprehensive test suite with high coverage
-- Include performance benchmarks where relevant
-- Document testing strategy and conventions used
-- Show test coverage metrics and quality improvements
+## OUTPUT REQUIREMENTS
+- Comprehensive test suite with high coverage
+- Performance benchmarks where relevant
+- Testing strategy and conventions documentation
+- Test coverage metrics and quality improvements
+- File:line references for tested code
+
+## VERIFICATION CHECKLIST ✓
+□ Test coverage gaps identified and filled
+□ All test types included (unit + integration + e2e)
+□ Tests are reliable and deterministic (no flaky tests)
+□ Test data properly managed (isolation + cleanup)
+□ Testing conventions followed consistently
+
+Focus: High-quality, reliable test suite with comprehensive coverage.

.claude/workflows/cli-templates/prompts/documentation/api.txt

@@ -1,337 +1,15 @@
-# Unified API Documentation Template
+Generate comprehensive API documentation for code or HTTP services.
 
-Generate comprehensive API documentation. This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
+## CORE CHECKLIST ⚡
+□ Include only sections relevant to the project type (Code API vs. HTTP API)
+□ Provide complete and runnable examples for HTTP APIs
+□ Use signatures-only for Code API documentation (no implementation)
+□ Document all public-facing APIs, not internal ones
 
----
+## UNIFIED API DOCUMENTATION TEMPLATE
 
-## Part A: Code API (For Libraries, Modules, SDKs)
+This template supports both **Code API** (for libraries/modules) and **HTTP API** (for web services). Include only the sections relevant to your project type.
 
-**Use this section when documenting**: Exported functions, classes, interfaces, and types from code modules.
+--- 
 
-**Omit this section if**: This is a pure web service with only HTTP endpoints and no programmatic API.
-
-### 1. Exported Functions
-
-For each exported function, provide:
-```typescript
-/**
- * Brief one-line description of what the function does
- * @param paramName - Parameter type and description
- * @returns Return type and description
- * @throws ErrorType - When this error occurs
- */
-export function functionName(paramName: ParamType): ReturnType;
-```
-
-**Example**:
-```typescript
-/**
- * Authenticates a user with email and password
- * @param credentials - User email and password
- * @returns Authentication token and user info
- * @throws AuthenticationError - When credentials are invalid
- */
-export function authenticate(credentials: Credentials): Promise<AuthResult>;
-```
-
-### 2. Exported Classes
-
-For each exported class, provide:
-```typescript
-/**
- * Brief one-line description of the class purpose
- */
-export class ClassName {
-  constructor(param: Type);
-
-  // Public properties
-  propertyName: Type;
-
-  // Public methods
-  methodName(param: Type): ReturnType;
-}
-```
-
-**Example**:
-```typescript
-/**
- * Manages user session lifecycle and token refresh
- */
-export class SessionManager {
-  constructor(config: SessionConfig);
-
-  // Current session state
-  isActive: boolean;
-
-  // Refresh the session token
-  refresh(): Promise<void>;
-
-  // Terminate the session
-  destroy(): void;
-}
-```
-
-### 3. Exported Interfaces
-
-For each exported interface, provide:
-```typescript
-/**
- * Brief description of what this interface represents
- */
-export interface InterfaceName {
-  field1: Type;  // Field description
-  field2: Type;  // Field description
-  method?: (param: Type) => ReturnType;  // Optional method
-}
-```
-
-### 4. Type Definitions
-
-For each exported type, provide:
-```typescript
-/**
- * Brief description of what this type represents
- */
-export type TypeName = string | number | CustomType;
-```
-
----
-
-## Part B: HTTP API (For Web Services, REST APIs, GraphQL)
-
-**Use this section when documenting**: HTTP endpoints, REST APIs, GraphQL APIs, webhooks.
-
-**Omit this section if**: This is a library/SDK with no HTTP interface.
-
-### 1. Overview
-
-[Brief description of the API's purpose and capabilities]
-
-**Base URL**:
-```
-Production: https://api.example.com/v1
-Staging: https://staging.api.example.com/v1
-Development: http://localhost:3000/api/v1
-```
-
-### 2. Authentication
-
-#### Authentication Method
-[e.g., JWT Bearer Token, OAuth2, API Keys]
-
-#### Obtaining Credentials
-```bash
-# Example: Login to get token
-curl -X POST https://api.example.com/v1/auth/login \
-  -H "Content-Type: application/json" \
-  -d '{"email": "user@example.com", "password": "password"}'
-```
-
-#### Using Credentials
-```http
-GET /api/resource HTTP/1.1
-Authorization: Bearer <token>
-```
-
-### 3. Common Response Codes
-
-| Code | Description | Common Causes |
-|------|-------------|---------------|
-| 200  | Success | Request completed successfully |
-| 201  | Created | Resource created successfully |
-| 400  | Bad Request | Invalid request body or parameters |
-| 401  | Unauthorized | Missing or invalid authentication |
-| 403  | Forbidden | Authenticated but not authorized |
-| 404  | Not Found | Resource does not exist |
-| 429  | Too Many Requests | Rate limit exceeded |
-| 500  | Internal Server Error | Server-side error |
-
-### 4. Endpoints
-
-#### Resource: [Resource Name, e.g., Users]
-
-##### GET /resource
-**Description**: [What this endpoint does]
-
-**Query Parameters**:
-| Parameter | Type | Required | Description | Default |
-|-----------|------|----------|-------------|---------|
-| `limit` | number | No | Number of results | 20 |
-| `offset` | number | No | Pagination offset | 0 |
-
-**Example Request**:
-```http
-GET /users?limit=10&offset=0 HTTP/1.1
-Authorization: Bearer <token>
-```
-
-**Response (200 OK)**:
-```json
-{
-  "data": [
-    {
-      "id": 1,
-      "name": "John Doe",
-      "email": "john@example.com"
-    }
-  ],
-  "pagination": {
-    "total": 100,
-    "limit": 10,
-    "offset": 0
-  }
-}
-```
-
-**Error Response (401 Unauthorized)**:
-```json
-{
-  "error": {
-    "code": "UNAUTHORIZED",
-    "message": "Invalid or expired token"
-  }
-}
-```
-
----
-
-##### POST /resource
-**Description**: [What this endpoint does]
-
-**Request Body**:
-```json
-{
-  "field1": "value",
-  "field2": 123
-}
-```
-
-**Validation Rules**:
-- `field1`: Required, 2-100 characters
-- `field2`: Required, positive integer
-
-**Response (201 Created)**:
-```json
-{
-  "id": 124,
-  "field1": "value",
-  "field2": 123,
-  "created_at": "2024-01-20T12:00:00Z"
-}
-```
-
----
-
-##### PUT /resource/:id
-**Description**: [What this endpoint does]
-
-**Path Parameters**:
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | number | Resource ID |
-
-**Request Body** (all fields optional):
-```json
-{
-  "field1": "new value"
-}
-```
-
-**Response (200 OK)**:
-```json
-{
-  "id": 124,
-  "field1": "new value",
-  "updated_at": "2024-01-21T09:15:00Z"
-}
-```
-
----
-
-##### DELETE /resource/:id
-**Description**: [What this endpoint does]
-
-**Path Parameters**:
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `id` | number | Resource ID |
-
-**Response (204 No Content)**:
-[Empty response body]
-
----
-
-### 5. Rate Limiting
-
-- **Limit**: 1000 requests per hour per API key
-- **Headers**:
-  - `X-RateLimit-Limit`: Total requests allowed
-  - `X-RateLimit-Remaining`: Requests remaining
-  - `X-RateLimit-Reset`: Unix timestamp when limit resets
-
-**Example Response Headers**:
-```http
-X-RateLimit-Limit: 1000
-X-RateLimit-Remaining: 847
-X-RateLimit-Reset: 1640000000
-```
-
-### 6. Webhooks (Optional)
-
-[Description of webhook system if applicable]
-
-**Webhook Events**:
-- `resource.created` - Triggered when a new resource is created
-- `resource.updated` - Triggered when a resource is updated
-- `resource.deleted` - Triggered when a resource is deleted
-
-**Webhook Payload Example**:
-```json
-{
-  "event": "resource.created",
-  "timestamp": "2024-01-20T12:00:00Z",
-  "data": {
-    "id": 124,
-    "field1": "value"
-  }
-}
-```
-
----
-
-## Rules
-
-1. **Include only relevant sections** - Skip Part A for pure web services, skip Part B for pure libraries
-2. **Signatures only in Part A** - No implementation code in Code API section
-3. **Complete examples in Part B** - All HTTP examples should be runnable
-4. **Consistent formatting** - Use language-specific code blocks (TypeScript, HTTP, JSON, bash)
-5. **Brief descriptions** - One line per item is sufficient for Code API
-6. **Detailed explanations for HTTP** - Include request/response examples, validation rules, error cases
-7. **Alphabetical order** - Sort items within each section for easy lookup
-8. **Public API only** - Do not document internal/private exports or endpoints
-
----
-
-## Template Usage Guidelines
-
-### For Module-Level API.md (Code API)
-**Use**: Part A only
-**Location**: `modules/[module-name]/API.md`
-**Focus**: Exported functions, classes, interfaces
-
-### For Project-Level HTTP API Documentation
-**Use**: Part B only
-**Location**: `.workflow/docs/api/README.md`
-**Focus**: REST/GraphQL endpoints, authentication
-
-### For Full-Stack Projects (Both Code and HTTP APIs)
-**Use**: Both Part A and Part B
-**Organization**:
-- Part A for SDK/client library APIs
-- Part B for HTTP endpoints
-
----
-
-**Last Updated**: [Auto-generated timestamp]
-**API Version**: [Version number]
-**Module/Service Path**: [Auto-fill with actual path]
+...(content truncated)...

.claude/workflows/cli-templates/prompts/documentation/folder-navigation.txt

@@ -1,68 +1,27 @@
-# Folder Navigation Documentation Template
+Generate a navigation README for directories that contain only subdirectories.
 
-Generate a navigation README for directories that contain only subdirectories (no code files). This serves as an index to help readers navigate to specific modules.
+## CORE CHECKLIST ⚡
+□ Keep the content brief and act as an index
+□ Use one-line descriptions for each module
+□ Ensure all mentioned modules link to their respective READMEs
+□ Use scannable formats like tables and lists
 
-## Structure
+## REQUIRED CONTENT
+1. **Overview**: Brief description of the directory's purpose.
+2. **Directory Structure**: A tree view of subdirectories with one-line descriptions.
+3. **Module Quick Reference**: A table with links, purposes, and key features.
+4. **How to Navigate**: Guidance on which module to explore for specific needs.
+5. **Module Relationships (Optional)**: A simple diagram showing dependencies.
 
-### 1. Overview
+## OUTPUT REQUIREMENTS
+- A scannable index for navigating subdirectories.
+- Links to each submodule's detailed documentation.
+- A clear, high-level overview of the directory's contents.
 
-Brief description of what this directory/category contains:
+## VERIFICATION CHECKLIST ✓
+□ The generated README is brief and serves as a scannable index
+□ All submodules are linked correctly
+□ Descriptions are concise and clear
+□ The structure follows the required content outline
 
-> The `modules/` directory contains the core business logic modules of the application. Each subdirectory represents a self-contained functional module with its own responsibilities.
-
-### 2. Directory Structure
-
-Provide a tree view of the subdirectories with brief descriptions:
-
-```
-modules/
-├── auth/              - User authentication and authorization
-├── api/               - API route handlers and middleware
-├── database/          - Database connections and ORM models
-└── utils/             - Shared utility functions
-```
-
-### 3. Module Quick Reference
-
-Table format for quick scanning:
-
-| Module | Purpose | Key Features |
-|--------|---------|--------------|
-| [auth](./auth/) | Authentication | JWT tokens, session management |
-| [api](./api/) | API routing | REST endpoints, validation |
-| [database](./database/) | Data layer | PostgreSQL, migrations |
-| [utils](./utils/) | Utilities | Logging, helpers |
-
-### 4. How to Navigate
-
-Guidance on which module to explore based on needs:
-
-- **For authentication logic** → [auth module](./auth/)
-- **For API endpoints** → [api module](./api/)
-- **For database queries** → [database module](./database/)
-- **For helper functions** → [utils module](./utils/)
-
-### 5. Module Relationships (Optional)
-
-If modules have significant dependencies, show them:
-
-```
-api → auth (uses for authentication)
-api → database (uses for data access)
-auth → database (uses for user storage)
-```
-
----
-
-## Rules
-
-1. **Keep it brief** - This is an index, not detailed documentation
-2. **One-line descriptions** - Each module gets a concise purpose statement
-3. **Scannable format** - Use tables and lists for quick navigation
-4. **Link to submodules** - Every module mentioned should link to its README
-5. **No code examples** - This is navigation only
-
----
-
-**Directory Path**: [Auto-fill with actual directory path]
-**Last Updated**: [Auto-generated timestamp]
+Focus: Creating a clear and concise navigation hub for parent directories.

.claude/workflows/cli-templates/prompts/documentation/module-readme.txt

@@ -1,98 +1,40 @@
-# Module README Documentation Template
+Generate comprehensive module documentation focused on understanding and usage.
 
-Generate comprehensive module documentation focused on understanding and usage. Explain WHAT the module does, WHY it exists, and HOW to use it. Do NOT duplicate API signatures (those belong in API.md).
+## CORE CHECKLIST ⚡
+□ Explain WHAT the module does, WHY it exists, and HOW to use it
+□ Do NOT duplicate API signatures from API.md; refer to it instead
+□ Provide practical, real-world usage examples
+□ Clearly define the module's boundaries and dependencies
 
-## Structure
+## DOCUMENTATION STRUCTURE
 
 ### 1. Purpose
-
-**What**: Clearly state what this module is responsible for
-**Why**: Explain why this module exists and what problems it solves
-**Boundaries**: Define what is IN scope and OUT of scope
-
-Example:
-> The `auth` module handles user authentication and authorization. It exists to centralize security logic and provide a consistent authentication interface across the application. It does NOT handle user profile management or session storage.
+- **What**: Clearly state what this module is responsible for.
+- **Why**: Explain the problem it solves.
+- **Boundaries**: Define what is in and out of scope.
 
 ### 2. Core Concepts
-
-List and explain key concepts, patterns, or abstractions used by this module:
-
-- **Concept 1**: [Brief explanation of important concept]
-- **Concept 2**: [Another key concept users should understand]
-- **Pattern**: [Architectural pattern used, e.g., "Uses middleware pattern for request processing"]
+- Explain key concepts, patterns, or abstractions.
 
 ### 3. Usage Scenarios
-
-Provide 2-4 common use cases with code examples:
-
-#### Scenario 1: [Common use case title]
-```typescript
-// Brief example showing how to use the module for this scenario
-import { functionName } from './module';
-
-const result = functionName(input);
-```
-
-#### Scenario 2: [Another common use case]
-```typescript
-// Another practical example
-```
+- Provide 2-4 common use cases with code examples.
 
 ### 4. Dependencies
-
-#### Internal Dependencies
-List other project modules this module depends on and explain why:
-- **[Module Name]** - [Why this dependency exists and what it provides]
-
-#### External Dependencies
-List third-party libraries and their purpose:
-- **[Library Name]** (`version`) - [What functionality it provides to this module]
+- List internal and external dependencies with explanations.
 
 ### 5. Configuration
-
-#### Environment Variables
-List any environment variables the module uses:
-- `ENV_VAR_NAME` - [Description, type, default value]
-
-#### Configuration Options
-If the module accepts configuration objects:
-```typescript
-// Example configuration
-const config = {
-  option1: value,  // Description of option1
-  option2: value,  // Description of option2
-};
-```
+- Document environment variables and configuration options.
 
 ### 6. Testing
-
-Explain how to test code that uses this module:
-```bash
-# Command to run tests for this module
-npm test -- path/to/module
-```
-
-**Test Coverage**: [Brief note on what's tested]
+- Explain how to run tests for the module.
 
 ### 7. Common Issues
+- List common problems and their solutions.
 
-List 2-3 common problems and their solutions:
+## VERIFICATION CHECKLIST ✓
+□ The module's purpose, scope, and boundaries are clearly defined
+□ Core concepts are explained for better understanding
+□ Usage examples are practical and demonstrate real-world scenarios
+□ All dependencies and configuration options are documented
 
-#### Issue: [Common problem description]
-**Solution**: [How to resolve it]
-
----
-
-## Rules
-
-1. **No API duplication** - Refer to API.md for signatures
-2. **Focus on understanding** - Explain concepts, not just code
-3. **Practical examples** - Show real usage, not trivial cases
-4. **Clear dependencies** - Help readers understand module relationships
-5. **Concise** - Each section should be scannable and to-the-point
-
----
-
-**Module Path**: [Auto-fill with actual module path]
-**Last Updated**: [Auto-generated timestamp]
-**See also**: [Link to API.md for interface details]
+Focus: Explaining the module's purpose and usage, not just its API.

.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt

@@ -1,167 +1,41 @@
-# Project Architecture Documentation Template
+Generate comprehensive architecture documentation for the entire project.
 
-Generate comprehensive architecture documentation that synthesizes information from all module documents. Focus on system-level design, module relationships, and aggregated API overview. This document should be created AFTER all module documentation is complete.
+## CORE CHECKLIST ⚡
+□ Synthesize information from all modules; do not duplicate content
+□ Maintain a system-level perspective, focusing on module interactions
+□ Use visual aids (like ASCII diagrams) to clarify structure
+□ Explain the WHY behind architectural decisions
 
-## Structure
+## DOCUMENTATION STRUCTURE
 
 ### 1. System Overview
-
-High-level description of the system architecture:
-
-**Architectural Style**: [e.g., Layered, Microservices, Event-Driven, Hexagonal]
-
-**Core Principles**:
-- [Principle 1, e.g., "Separation of concerns"]
-- [Principle 2, e.g., "Dependency inversion"]
-- [Principle 3, e.g., "Single responsibility"]
-
-**Technology Stack**:
-- **Languages**: [Primary programming languages]
-- **Frameworks**: [Key frameworks]
-- **Databases**: [Data storage solutions]
-- **Infrastructure**: [Deployment, hosting, CI/CD]
+- Architectural Style, Core Principles, and Technology Stack.
 
 ### 2. System Structure
-
-Visual representation of the system structure using text diagrams:
-
-```
-┌─────────────────────────────────────┐
-│         Application Layer           │
-│  (API Routes, Controllers)          │
-└────────────┬────────────────────────┘
-             │
-┌────────────▼────────────────────────┐
-│       Business Logic Layer          │
-│  (Modules: auth, orders, payments)  │
-└────────────┬────────────────────────┘
-             │
-┌────────────▼────────────────────────┐
-│        Data Access Layer            │
-│  (Database, ORM, Repositories)      │
-└─────────────────────────────────────┘
-```
+- Visual representation of the system's layers or components.
 
 ### 3. Module Map
-
-Comprehensive list of all modules with their responsibilities:
-
-| Module | Layer | Responsibility | Dependencies |
-|--------|-------|----------------|--------------|
-| `auth` | Business | Authentication & authorization | database, utils |
-| `api` | Application | HTTP routing & validation | auth, orders |
-| `database` | Data | Data persistence | - |
-| `utils` | Infrastructure | Shared utilities | - |
+- A table listing all modules, their layers, responsibilities, and dependencies.
 
 ### 4. Module Interactions
-
-Describe key interaction patterns between modules:
-
-#### Data Flow Example: User Authentication
-```
-1. Client → api/login endpoint
-2. api → auth.authenticateUser()
-3. auth → database.findUser()
-4. database → PostgreSQL
-5. auth → JWT token generation
-6. api → Response with token
-```
-
-#### Dependency Graph
-```
-api ──────┐
-          ├──→ auth ───→ database
-orders ───┤              ↑
-          └──────────────┘
-```
+- Describe key data flows and show a dependency graph.
 
 ### 5. Design Patterns
-
-Document key architectural patterns used:
-
-#### Pattern 1: [Pattern Name, e.g., "Repository Pattern"]
-- **Where**: [Which modules use this pattern]
-- **Why**: [Reason for using this pattern]
-- **How**: [Brief explanation of implementation]
-
-#### Pattern 2: [Another pattern]
-[Similar structure]
+- Document key architectural patterns used across the project.
 
 ### 6. Aggregated API Overview
-
-High-level summary of all public APIs across modules. Group by category:
-
-#### Authentication APIs
-- `auth.authenticate(credentials)` - Validate user credentials
-- `auth.authorize(user, permission)` - Check user permissions
-- `auth.generateToken(userId)` - Create JWT token
-
-#### Data APIs
-- `database.findOne(query)` - Find single record
-- `database.findMany(query)` - Find multiple records
-- `database.insert(data)` - Insert new record
-
-#### Utility APIs
-- `utils.logger.log(message)` - Application logging
-- `utils.validator.validate(data, schema)` - Data validation
-
-*Note: For detailed API signatures, refer to individual module API.md files*
+- A high-level summary of all public APIs, grouped by category.
 
 ### 7. Data Flow
+- Describe the typical request lifecycle or event flow.
 
-Describe how data moves through the system:
+### 8. Security and Scalability
+- Overview of security measures and scalability considerations.
 
-**Request Lifecycle**:
-1. HTTP request enters through API layer
-2. Request validation and authentication (auth module)
-3. Business logic processing (domain modules)
-4. Data persistence (database module)
-5. Response formatting and return
+## VERIFICATION CHECKLIST ✓
+□ The documentation provides a cohesive, system-level view
+□ Module interactions and dependencies are clearly illustrated
+□ The rationale behind major design patterns and decisions is explained
+□ The document synthesizes, rather than duplicates, module-level details
 
-**Event Flow** (if applicable):
-- [Describe event-driven flows if present]
-
-### 8. Security Architecture
-
-Overview of security measures:
-
-- **Authentication**: [JWT, OAuth2, etc.]
-- **Authorization**: [RBAC, ACL, etc.]
-- **Data Protection**: [Encryption, hashing]
-- **API Security**: [Rate limiting, CORS, etc.]
-
-### 9. Scalability Considerations
-
-Architectural decisions that support scalability:
-
-- [Horizontal scaling approach]
-- [Caching strategy]
-- [Database optimization]
-- [Load balancing]
-
----
-
-## Rules
-
-1. **Synthesize, don't duplicate** - Reference module docs, don't copy them
-2. **System-level perspective** - Focus on how modules work together
-3. **Visual aids** - Use diagrams for clarity (ASCII art is fine)
-4. **Aggregated APIs** - One-line summaries only, link to detailed docs
-5. **Design rationale** - Explain WHY decisions were made
-6. **Maintain consistency** - Ensure all module docs are considered
-
----
-
-## Required Inputs
-
-This document requires the following to be available:
-- All module README.md files (for understanding module purposes)
-- All module API.md files (for aggregating API overview)
-- Project README.md (for context and navigation)
-
----
-
-**Last Updated**: [Auto-generated timestamp]
-**See also**:
-- [Project README](./README.md) for project overview
-- [Module Documentation](./modules/) for detailed module docs
+Focus: Providing a holistic, system-level understanding of the project architecture.

.claude/workflows/cli-templates/prompts/documentation/project-examples.txt

@@ -1,205 +1,35 @@
-# Project Examples Documentation Template
+Generate practical, end-to-end examples demonstrating core project usage.
 
-Generate practical, end-to-end examples demonstrating core usage patterns of the project. Focus on realistic scenarios that span multiple modules. These examples should help users understand how to accomplish common tasks.
+## CORE CHECKLIST ⚡
+□ Provide complete, runnable code for every example
+□ Focus on realistic, real-world scenarios, not trivial cases
+□ Explain the flow and how different modules interact
+□ Include expected output to verify correctness
 
-## Structure
+## EXAMPLES STRUCTURE
 
 ### 1. Introduction
-
-Brief overview of what these examples cover:
-
-> This document provides complete, working examples for common use cases. Each example demonstrates how multiple modules work together to accomplish a specific task.
-
-**Prerequisites**:
-- [List required setup, e.g., "Project installed and configured"]
-- [Environment requirements, e.g., "PostgreSQL running on localhost"]
+- Overview of the examples and any prerequisites.
 
 ### 2. Quick Start Example
-
-The simplest possible working example to get started:
-
-```typescript
-// The minimal example to verify setup
-import { App } from './src';
-
-const app = new App();
-await app.start();
-console.log('Application running!');
-```
-
-**What this does**: [Brief explanation]
+- The simplest possible working example to verify setup.
 
 ### 3. Core Use Cases
+- 3-5 complete examples for common scenarios with code, output, and explanations.
 
-Provide 3-5 complete examples for common scenarios:
+### 4. Advanced & Integration Examples
+- Showcase more complex scenarios or integrations with external systems.
 
-#### Example 1: [Scenario Name, e.g., "User Registration and Login"]
+### 5. Testing Examples
+- Show how to test code that uses the project.
 
-**Objective**: [What this example accomplishes]
+### 6. Best Practices & Troubleshooting
+- Demonstrate recommended patterns and provide solutions to common issues.
 
-**Modules involved**: `auth`, `database`, `api`
+## VERIFICATION CHECKLIST ✓
+□ All examples are complete, runnable, and tested
+□ Scenarios are realistic and demonstrate key project features
+□ Explanations clarify module interactions and data flow
+□ Best practices and error handling are demonstrated
 
-**Complete code**:
-```typescript
-import { createUser, authenticateUser } from './modules/auth';
-import { startServer } from './modules/api';
-
-// Step 1: Initialize the application
-const app = await startServer({ port: 3000 });
-
-// Step 2: Register a new user
-const user = await createUser({
-  email: 'user@example.com',
-  password: 'securePassword123',
-  name: 'John Doe'
-});
-
-// Step 3: Authenticate the user
-const session = await authenticateUser({
-  email: 'user@example.com',
-  password: 'securePassword123'
-});
-
-// Step 4: Use the authentication token
-console.log('Login successful, token:', session.token);
-```
-
-**Expected output**:
-```
-Server started on port 3000
-User created: { id: 1, email: 'user@example.com', name: 'John Doe' }
-Login successful, token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
-```
-
-**Explanation**:
-1. [Step-by-step breakdown of what each part does]
-2. [How modules interact]
-3. [Common variations or customizations]
-
----
-
-#### Example 2: [Another Common Scenario]
-
-[Similar structure with complete code]
-
----
-
-#### Example 3: [Another Use Case]
-
-[Similar structure with complete code]
-
-### 4. Advanced Examples
-
-More complex scenarios for power users:
-
-#### Advanced Example 1: [Complex Scenario]
-
-**Objective**: [What this example accomplishes]
-
-**Modules involved**: [List]
-
-```typescript
-// Complete working code with detailed comments
-```
-
-**Key points**:
-- [Important concept or gotcha]
-- [Performance consideration]
-- [Security note]
-
-### 5. Integration Examples
-
-Examples showing how to integrate with external systems:
-
-#### Integration with [External System]
-
-```typescript
-// Example of integrating with a third-party service
-```
-
-### 6. Testing Examples
-
-Show how to test code that uses this project:
-
-```typescript
-// Example test case using the project
-import { describe, it, expect } from 'your-test-framework';
-
-describe('User authentication', () => {
-  it('should authenticate valid credentials', async () => {
-    const result = await authenticateUser({
-      email: 'test@example.com',
-      password: 'password123'
-    });
-
-    expect(result.success).toBe(true);
-    expect(result.token).toBeDefined();
-  });
-});
-```
-
-### 7. Best Practices
-
-Demonstrate recommended patterns:
-
-#### Pattern 1: [Best Practice Title]
-```typescript
-// Good: Recommended approach
-const result = await handleWithErrorRecovery(operation);
-
-// Bad: Anti-pattern to avoid
-const result = operation(); // No error handling
-```
-
-**Why**: [Explanation of why this is the best approach]
-
-#### Pattern 2: [Another Best Practice]
-[Similar structure]
-
-### 8. Troubleshooting Common Issues
-
-Example-based solutions to common problems:
-
-#### Issue: [Common Problem]
-
-**Symptom**: [What the user experiences]
-
-**Solution**:
-```typescript
-// Before: Code that causes the issue
-const broken = doSomethingWrong();
-
-// After: Corrected code
-const fixed = doSomethingRight();
-```
-
----
-
-## Rules
-
-1. **Complete, runnable code** - Every example should be copy-paste ready
-2. **Real-world scenarios** - Avoid trivial or contrived examples
-3. **Explain the flow** - Show how modules work together
-4. **Include output** - Show what users should expect to see
-5. **Error handling** - Demonstrate proper error handling patterns
-6. **Comment complex parts** - Help readers understand non-obvious code
-7. **Version compatibility** - Note if examples are version-specific
-
----
-
-## Code Quality Standards
-
-All example code should:
-- Follow project coding standards
-- Include proper error handling
-- Use async/await correctly
-- Show TypeScript types where applicable
-- Be tested and verified to work
-
----
-
-**Last Updated**: [Auto-generated timestamp]
-**See also**:
-- [Project README](./README.md) for getting started
-- [Architecture](./ARCHITECTURE.md) for understanding system design
-- [Module Documentation](./modules/) for API details
+Focus: Helping users accomplish common tasks through complete, practical examples.

.claude/workflows/cli-templates/prompts/documentation/project-readme.txt

@@ -1,58 +1,35 @@
-# Project-Level Documentation Template
+Generate a comprehensive project-level README documentation.
 
-Generate comprehensive project documentation following this structure:
+## CORE CHECKLIST ⚡
+□ Clearly state the project's purpose and target audience
+□ Provide clear, runnable instructions for getting started
+□ Outline the development workflow and coding standards
+□ Offer a high-level overview of the project structure and architecture
 
-## 1. Overview
-- **Purpose**: [High-level mission and goals of the project]
-- **Target Audience**: [Primary users, developers, stakeholders]
-- **Key Features**: [List of major functionalities and capabilities]
+## README STRUCTURE
 
-## 2. System Architecture
-- **Architectural Style**: [e.g., Monolith, Microservices, Layered, Event-Driven]
-- **Core Components**: [Diagram or list of major system parts and their interactions]
-- **Technology Stack**:
-  - Languages: [Programming languages used]
-  - Frameworks: [Key frameworks and libraries]
-  - Databases: [Data storage solutions]
-  - Infrastructure: [Deployment and hosting]
-- **Design Principles**: [Guiding principles like SOLID, DRY, separation of concerns]
+### 1. Overview
+- Purpose, Target Audience, and Key Features.
 
-## 3. Getting Started
-- **Prerequisites**: [Required software, tools, versions]
-- **Installation**:
-  ```bash
-  # Installation commands
-  ```
-- **Configuration**: [Environment setup, config files]
-- **Running the Project**:
-  ```bash
-  # Startup commands
-  ```
+### 2. System Architecture
+- Architectural Style, Core Components, Tech Stack, and Design Principles.
 
-## 4. Development Workflow
-- **Branching Strategy**: [e.g., GitFlow, trunk-based]
-- **Coding Standards**: [Style guide, linting rules]
-- **Testing**:
-  ```bash
-  # Test commands
-  ```
-- **Build & Deployment**: [CI/CD pipeline overview]
+### 3. Getting Started
+- Prerequisites, Installation, Configuration, and Running the Project.
 
-## 5. Project Structure
-```
-project-root/
-├── src/           # [Description]
-├── tests/         # [Description]
-├── docs/          # [Description]
-└── config/        # [Description]
-```
+### 4. Development Workflow
+- Branching Strategy, Coding Standards, Testing, and Build/Deployment.
 
-## 6. Navigation
-- [Module Documentation](./modules/)
-- [API Reference](./api/)
-- [Architecture Details](./architecture/)
-- [Contributing Guidelines](./CONTRIBUTING.md)
+### 5. Project Structure
+- A high-level tree view of the main directories.
 
----
-**Last Updated**: [Auto-generated timestamp]
-**Documentation Version**: [Project version]
+### 6. Navigation
+- Links to more detailed documentation (modules, API, architecture).
+
+## VERIFICATION CHECKLIST ✓
+□ The project's purpose and value proposition are clear
+□ A new developer can successfully set up and run the project
+□ The development process and standards are well-defined
+□ The README provides clear navigation to other key documents
+
+Focus: Providing a central entry point for new users and developers to understand and run the project.

.claude/workflows/cli-templates/prompts/implementation/component.txt

@@ -1,16 +1,28 @@
-Guide component implementation and development patterns:
+Guide component implementation and development patterns.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Define component interface and API requirements clearly
+□ Identify reusable patterns and composition strategies
+□ Plan state management and data flow before implementation
+□ Design a comprehensive testing and validation approach
+
+## REQUIRED ANALYSIS
 1. Define component interface and API requirements
 2. Identify reusable patterns and composition strategies
 3. Plan state management and data flow implementation
 4. Design component testing and validation approach
 5. Document integration points and usage examples
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Component specification with clear interface definition
 - Implementation patterns and best practices
 - State management strategy and data flow design
 - Testing approach and validation criteria
 
-Focus on reusable, maintainable component design with clear usage patterns.
+## VERIFICATION CHECKLIST ✓
+□ Component specification includes a clear interface definition
+□ Reusable implementation patterns and best practices are documented
+□ State management and data flow design is clear and robust
+□ A thorough testing and validation approach is defined
+
+Focus: Reusable, maintainable component design with clear usage patterns.

.claude/workflows/cli-templates/prompts/memory/claude-layer1-root.txt

@@ -1,63 +0,0 @@
-Create or update root-level CLAUDE.md documentation:
-
-## Layer 1: Root Level Documentation Requirements
-
-### Content Focus (MUST INCLUDE):
-1. **Project Overview and Purpose**
-   - High-level project description and mission
-   - Target audience and use cases
-   - Key value propositions
-
-2. **Technology Stack Summary**
-   - Primary programming languages and frameworks
-   - Key dependencies and tools
-   - Platform and runtime requirements
-
-3. **Architecture Decisions and Principles**
-   - Core architectural patterns used
-   - Design principles governing the codebase
-   - Major technical decisions and rationale
-
-4. **Development Workflow Overview**
-   - Build and deployment processes
-   - Testing approach and quality standards
-   - Contributing guidelines and processes
-
-5. **Quick Start Guide**
-   - Installation prerequisites
-   - Setup instructions
-   - Basic usage examples
-
-### Content Restrictions (STRICTLY AVOID):
-- Implementation details (belongs in module-level docs)
-- Module-specific patterns (belongs in module-level docs)
-- Code examples from specific modules (belongs in module-level docs)
-- Domain internal architecture (belongs in domain-level docs)
-
-### Documentation Style:
-- Use high-level, strategic perspective
-- Focus on "what" and "why" rather than "how"
-- Reference other documentation layers rather than duplicating content
-- Maintain concise, executive-summary style
-
-### Template Structure:
-```markdown
-# [Project Name] - Development Guidelines
-
-## 1. Project Overview and Purpose
-[Brief project description, mission, and target audience]
-
-## 2. Technology Stack Summary
-[Primary technologies, frameworks, and tools]
-
-## 3. Architecture Decisions and Principles
-[Core architectural patterns and design principles]
-
-## 4. Development Workflow Overview
-[Build, test, and deployment processes]
-
-## 5. Quick Start Guide
-[Installation and basic usage]
-```
-
-Remember: This is Layer 1 - stay at the strategic level and avoid diving into implementation details.

.claude/workflows/cli-templates/prompts/memory/claude-layer2-domain.txt

@@ -1,63 +0,0 @@
-Create or update domain-level CLAUDE.md documentation:
-
-## Layer 2: Domain Level Documentation Requirements
-
-### Content Focus (MUST INCLUDE):
-1. **Domain Architecture and Responsibilities**
-   - Domain's role within the larger system
-   - Core responsibilities and boundaries
-   - Key abstractions and concepts
-
-2. **Module Organization Within Domain**
-   - How modules are structured within this domain
-   - Module relationships and hierarchies
-   - Organizational patterns used
-
-3. **Inter-Module Communication Patterns**
-   - How modules within this domain communicate
-   - Data flow patterns and interfaces
-   - Shared resources and dependencies
-
-4. **Domain-Specific Conventions**
-   - Coding standards specific to this domain
-   - Naming conventions and patterns
-   - Testing approaches for this domain
-
-5. **Integration Points with Other Domains**
-   - External dependencies and interfaces
-   - Cross-domain communication protocols
-   - Shared contracts and data formats
-
-### Content Restrictions (STRICTLY AVOID):
-- Duplicating root project overview (belongs in root-level docs)
-- Component/function-level details (belongs in module-level docs)
-- Specific implementation code (belongs in module-level docs)
-- Module internal patterns (belongs in module-level docs)
-
-### Documentation Style:
-- Focus on domain-wide patterns and organization
-- Explain relationships between modules within the domain
-- Describe domain boundaries and responsibilities
-- Reference module-level docs for implementation details
-
-### Template Structure:
-```markdown
-# [Domain Name] - Domain Architecture
-
-## 1. Domain Overview
-[Domain's role and core responsibilities]
-
-## 2. Module Organization
-[How modules are structured within this domain]
-
-## 3. Inter-Module Communication
-[Communication patterns and data flow]
-
-## 4. Domain Conventions
-[Domain-specific standards and patterns]
-
-## 5. External Integration
-[Integration with other domains and systems]
-```
-
-Remember: This is Layer 2 - focus on domain-wide organization and avoid both high-level project details and low-level implementation specifics.

.claude/workflows/cli-templates/prompts/memory/claude-layer3-module.txt

@@ -1,66 +0,0 @@
-Create or update module-level CLAUDE.md documentation:
-
-## Layer 3: Module Level Documentation Requirements
-
-### Content Focus (MUST INCLUDE):
-1. **Module-Specific Implementation Patterns**
-   - Implementation patterns used within this module
-   - Common coding approaches and idioms
-   - Module-specific design patterns
-
-2. **Internal Architecture and Design Decisions**
-   - How the module is internally organized
-   - Key design decisions and their rationale
-   - Component relationships within the module
-
-3. **API Contracts and Interfaces**
-   - Public interfaces exposed by this module
-   - Input/output contracts and data formats
-   - Integration points with other modules
-
-4. **Module Dependencies and Relationships**
-   - Direct dependencies of this module
-   - How this module fits into the larger system
-   - Data flow in and out of the module
-
-5. **Testing Strategies for This Module**
-   - Testing approaches specific to this module
-   - Test coverage strategies and targets
-   - Module-specific testing tools and frameworks
-
-### Content Restrictions (STRICTLY AVOID):
-- Project overview content (belongs in root-level docs)
-- Domain-wide architectural patterns (belongs in domain-level docs)
-- Detailed function documentation (belongs in sub-module-level docs)
-- Configuration specifics (belongs in sub-module-level docs)
-
-### Documentation Style:
-- Focus on module-level architecture and patterns
-- Explain how components within the module work together
-- Document public interfaces and contracts
-- Reference sub-module docs for detailed implementation
-
-### Template Structure:
-```markdown
-# [Module Name] - Module Architecture
-
-## 1. Module Overview
-[Module's purpose and responsibilities]
-
-## 2. Implementation Patterns
-[Common patterns and approaches used]
-
-## 3. Internal Architecture
-[How the module is organized internally]
-
-## 4. Public Interfaces
-[APIs and contracts exposed by this module]
-
-## 5. Dependencies and Integration
-[Module dependencies and system integration]
-
-## 6. Testing Strategy
-[Testing approaches for this module]
-```
-
-Remember: This is Layer 3 - focus on module-level architecture and patterns, avoiding both domain-wide and detailed implementation concerns.

.claude/workflows/cli-templates/prompts/memory/claude-layer4-submodule.txt

@@ -1,69 +0,0 @@
-Create or update sub-module-level CLAUDE.md documentation:
-
-## Layer 4: Sub-Module Level Documentation Requirements
-
-### Content Focus (MUST INCLUDE):
-1. **Detailed Implementation Specifics**
-   - Specific implementation details and algorithms
-   - Code-level patterns and idioms
-   - Implementation trade-offs and decisions
-
-2. **Component/Function Documentation**
-   - Individual component descriptions
-   - Function signatures and behaviors
-   - Class/struct/interface documentation
-
-3. **Configuration Details and Examples**
-   - Configuration options and parameters
-   - Environment-specific settings
-   - Configuration examples and templates
-
-4. **Usage Examples and Patterns**
-   - Code examples and usage patterns
-   - Common use cases and scenarios
-   - Integration examples with other components
-
-5. **Performance Considerations**
-   - Performance characteristics and constraints
-   - Optimization strategies and techniques
-   - Resource usage and scalability notes
-
-### Content Restrictions (STRICTLY AVOID):
-- Architecture decisions (belong in higher levels)
-- Module-level organizational patterns (belong in module-level docs)
-- Domain or project overview content (belong in higher levels)
-- Cross-module architectural concerns (belong in higher levels)
-
-### Documentation Style:
-- Focus on detailed, actionable implementation information
-- Provide concrete examples and code snippets
-- Document specific behaviors and edge cases
-- Include troubleshooting and debugging guidance
-
-### Template Structure:
-```markdown
-# [Sub-Module/Component Name] - Implementation Guide
-
-## 1. Component Overview
-[Specific purpose and functionality]
-
-## 2. Implementation Details
-[Detailed implementation specifics]
-
-## 3. API Reference
-[Function/method documentation]
-
-## 4. Configuration
-[Configuration options and examples]
-
-## 5. Usage Examples
-[Code examples and patterns]
-
-## 6. Performance and Optimization
-[Performance considerations and tips]
-
-## 7. Troubleshooting
-[Common issues and solutions]
-```
-
-Remember: This is Layer 4 - focus on concrete, actionable implementation details and avoid architectural or organizational concerns.

.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt

@@ -0,0 +1,165 @@
+Create or update CLAUDE.md documentation using unified module/file template.
+
+## ⚠️ FILE NAMING RULE (CRITICAL)
+- Target file: MUST be named exactly `CLAUDE.md` in the current directory
+- NEVER create files like `ToolSidebar.CLAUDE.md` or `[filename].CLAUDE.md`
+- ALWAYS use the fixed name: `CLAUDE.md`
+
+## CORE CHECKLIST ⚡
+□ MUST create/update file named exactly 'CLAUDE.md' (not variants)
+□ MUST include all 6 sections: Purpose, Structure, Components, Dependencies, Integration, Implementation
+□ For code files: Document all public/exported APIs with complete parameter details
+□ For folders: Reference subdirectory CLAUDE.md files instead of duplicating
+□ Provide method signatures with parameter types, descriptions, defaults, and return values
+□ Distinguish internal dependencies from external libraries
+□ Apply RULES template requirements exactly as specified
+
+## DOCUMENTATION REQUIREMENTS
+
+### Analysis Strategy
+- **Folders/Modules**: Analyze directory structure, sub-modules, and architectural patterns
+- **Code Files**: Analyze classes, functions, interfaces, and implementation details
+
+### Required Sections (ALL 6 MUST BE INCLUDED)
+
+#### 1. Purpose and Scope
+- Clear description of what this module/file does
+- Main responsibilities and boundaries
+- Role within the larger system
+
+#### 2. Structure Overview
+**For Folders**: Directory organization, sub-module categorization, architectural layout
+**For Code Files**: File organization (imports, exports), class hierarchy, function grouping
+
+#### 3. Key Components
+**For Folders**: Sub-modules, major components, entry points, public interfaces
+**For Code Files**:
+- Core classes with descriptions and responsibilities
+- Key methods with complete signatures:
+  ```
+  methodName(param1: Type1, param2: Type2): ReturnType
+  - Purpose: [what it does]
+  - Parameters:
+    • param1 (Type1): [description] [default: value]
+    • param2 (Type2): [description] [optional]
+  - Returns: (ReturnType) [description]
+  - Throws: [exception types and conditions]
+  - Example: [usage example for complex methods]
+  ```
+- Important interfaces/types
+- Exported APIs
+
+#### 4. Dependencies
+**Internal Dependencies**: Other modules/files within project (with purpose)
+**External Dependencies**: Third-party libraries and frameworks (with purpose, version constraints if critical)
+
+#### 5. Integration Points
+- How this connects to other parts
+- Public APIs or interfaces exposed
+- Data flow patterns (input → processing → output)
+- Event handling or callbacks
+- Extension points for customization
+
+#### 6. Implementation Notes
+- Key design patterns used (e.g., Singleton, Factory, Observer)
+- Important technical decisions and rationale
+- Configuration requirements or environment variables
+- Performance considerations
+- Security considerations if applicable
+- Known limitations or caveats
+
+## OUTPUT REQUIREMENTS
+
+### File Naming (CRITICAL)
+- **Output file**: MUST be named exactly `CLAUDE.md` in the current directory
+- **Examples of WRONG naming**: `ToolSidebar.CLAUDE.md`, `index.CLAUDE.md`, `utils.CLAUDE.md`
+- **Correct naming**: `CLAUDE.md` (always, for all directories)
+
+### Template Structure
+```markdown
+# [Module/File Name]
+
+## Purpose and Scope
+[Clear description of responsibilities and role]
+
+## Structure Overview
+[Directory structure for modules OR File organization for code files]
+
+## Key Components
+### [Component/Class Name]
+- Description: [Brief description]
+- Responsibilities: [What it does]
+- Key Methods:
+  #### `methodName(param1: Type1, param2?: Type2): ReturnType`
+  - Purpose: [what this method does]
+  - Parameters:
+    • param1 (Type1): [description]
+    • param2 (Type2): [description] [optional] [default: value]
+  - Returns: (ReturnType) [description]
+  - Throws: [exceptions if applicable]
+
+## Dependencies
+### Internal Dependencies
+- `[module/file path]` - [purpose]
+
+### External Dependencies
+- `[library name]` - [purpose and usage]
+
+## Integration Points
+### Public APIs
+- `[API/function signature]` - [description]
+
+### Data Flow
+[How data flows through this module/file]
+
+## Implementation Notes
+### Design Patterns
+- [Pattern name]: [Usage and rationale]
+
+### Technical Decisions
+- [Decision]: [Rationale]
+
+### Considerations
+- Performance: [notes]
+- Security: [notes]
+- Limitations: [notes]
+```
+
+### Documentation Style
+- **Concise but complete** - Focus on "what" and "why", not detailed "how"
+- **Code signatures** for key APIs - Include all parameter details
+- **Parameters**: Name, type, description, optional/default indicators, constraints
+- **Return values**: Type, description, special conditions (null, undefined, empty)
+- **Evidence-based** - Reference related documentation when appropriate
+- **Examples** for complex methods - Show usage patterns
+
+### Content Restrictions (STRICTLY AVOID)
+- ❌ Duplicating content from other CLAUDE.md files (reference instead)
+- ❌ Overly detailed code explanations (code should be self-documenting)
+- ❌ Complete code listings (use signatures and descriptions)
+- ❌ Version-specific details unless critical
+- ❌ Documenting every single function (focus on public/exported APIs)
+
+### Method Documentation Rules
+- **Public/Exported methods**: MUST document with full parameter details
+- **Private/Internal methods**: Only document if complex or critical
+- **Parameters**: MUST include type, description, constraints, defaults
+- **Return values**: MUST document type and description
+- **Exceptions**: Document all thrown errors
+
+### Special Instructions
+- If analyzing folder with existing subdirectory CLAUDE.md files → reference them
+- For code files → prioritize exported/public APIs
+- Keep dependency lists focused on direct dependencies (not transitive)
+- Update existing CLAUDE.md files rather than creating duplicate sections
+
+## VERIFICATION CHECKLIST ✓
+□ Output file is named exactly 'CLAUDE.md' (not [filename].CLAUDE.md)
+□ All 6 required sections included (Purpose, Structure, Components, Dependencies, Integration, Implementation)
+□ All public/exported APIs documented with complete signatures
+□ Parameters documented with types, descriptions, and defaults
+□ References used instead of duplicating subdirectory documentation
+□ Internal vs external dependencies clearly distinguished
+□ Examples provided for non-trivial methods
+
+Focus: Comprehensive yet concise documentation covering all essential aspects without redundancy.

.claude/workflows/cli-templates/prompts/memory/hierarchy-analysis.txt

@@ -1,16 +0,0 @@
-Analyze project structure for memory hierarchy optimization:
-
-## Required Analysis:
-1. Assess project complexity and file organization patterns
-2. Identify logical module boundaries and responsibility separation
-3. Evaluate cross-module dependencies and integration complexity
-4. Determine optimal documentation depth and hierarchy levels
-5. Recommend content differentiation strategies across hierarchy levels
-
-## Output Requirements:
-- Project complexity classification with supporting metrics
-- Module boundary recommendations with responsibility mapping
-- Hierarchy depth recommendations with level-specific focus areas
-- Content strategy with redundancy elimination guidelines
-
-Focus on intelligent documentation hierarchy that scales with project complexity.

.claude/workflows/cli-templates/prompts/planning/concept-eval.txt

@@ -1,77 +1,78 @@
-CONCEPT EVALUATION FRAMEWORK
+Conduct comprehensive concept evaluation to assess feasibility, identify risks, and provide optimization recommendations.
 
-## EVALUATION DIRECTIVE
-You are conducting a comprehensive concept evaluation to assess feasibility, identify risks, and provide optimization recommendations before formal implementation planning begins.
+## CORE CHECKLIST ⚡
+□ Evaluate all 6 dimensions: Conceptual, Architectural, Technical, Resource, Risk, Dependency
+□ Provide quantified assessment scores (1-5 scale)
+□ Classify risks by severity (LOW/MEDIUM/HIGH/CRITICAL)
+□ Include specific, actionable recommendations
+□ Integrate session context and existing patterns
 
-## CORE EVALUATION DIMENSIONS
+## EVALUATION DIMENSIONS
 
-### 1. CONCEPTUAL INTEGRITY
-- **Design Coherence**: Are all components logically connected and consistent?
-- **Requirement Completeness**: Are all necessary requirements identified and defined?
-- **Scope Clarity**: Is the concept scope clearly defined and bounded?
-- **Success Criteria**: Are measurable success criteria clearly established?
+### 1. Conceptual Integrity
+- Design Coherence: Logical component connections
+- Requirement Completeness: All requirements identified
+- Scope Clarity: Defined and bounded scope
+- Success Criteria: Measurable metrics established
 
-### 2. ARCHITECTURAL SOUNDNESS
-- **System Integration**: How well does the concept integrate with existing architecture?
-- **Design Patterns**: Are appropriate and established design patterns utilized?
-- **Modularity**: Is the concept appropriately modular and maintainable?
-- **Scalability**: Can the concept scale to meet future requirements?
+### 2. Architectural Soundness
+- System Integration: Fit with existing architecture
+- Design Patterns: Appropriate pattern usage
+- Modularity: Maintainable structure
+- Scalability: Future requirement capacity
 
-### 3. TECHNICAL FEASIBILITY
-- **Implementation Complexity**: What is the technical difficulty level?
-- **Technology Maturity**: Are required technologies stable and well-supported?
-- **Skill Requirements**: Do we have the necessary technical expertise?
-- **Infrastructure Needs**: What infrastructure changes or additions are required?
+### 3. Technical Feasibility
+- Implementation Complexity: Difficulty level assessment
+- Technology Maturity: Stable, supported technologies
+- Skill Requirements: Team expertise availability
+- Infrastructure Needs: Required changes/additions
 
-### 4. RESOURCE ASSESSMENT
-- **Development Time**: Realistic time estimation for implementation
-- **Team Resources**: Required team size and skill composition
-- **Budget Impact**: Financial implications and resource allocation
-- **Opportunity Cost**: What other initiatives might be delayed or cancelled?
+### 4. Resource Assessment
+- Development Time: Realistic estimation
+- Team Resources: Size and skill composition
+- Budget Impact: Financial implications
+- Opportunity Cost: Delayed initiatives
 
-### 5. RISK IDENTIFICATION
-- **Technical Risks**: Technology limitations, complexity, and unknowns
-- **Business Risks**: Market timing, user adoption, and business impact
-- **Integration Risks**: Compatibility and system integration challenges
-- **Resource Risks**: Team availability, skill gaps, and timeline pressures
+### 5. Risk Identification
+- Technical Risks: Limitations, complexity, unknowns
+- Business Risks: Market timing, adoption, impact
+- Integration Risks: Compatibility challenges
+- Resource Risks: Availability, skills, timeline
 
-### 6. DEPENDENCY ANALYSIS
-- **External Dependencies**: Third-party services, libraries, and tools
-- **Internal Dependencies**: Other systems, teams, and organizational resources
-- **Temporal Dependencies**: Sequence requirements and timing constraints
-- **Critical Path**: Essential dependencies that could block progress
+### 6. Dependency Analysis
+- External Dependencies: Third-party services/tools
+- Internal Dependencies: Systems, teams, resources
+- Temporal Dependencies: Sequence and timing
+- Critical Path: Essential blocking dependencies
 
-## EVALUATION METHODOLOGY
+## ASSESSMENT METHODOLOGY
 
-### ASSESSMENT CRITERIA
-Rate each dimension on a scale of 1-5:
-- **5 - Excellent**: Minimal risk, well-defined, highly feasible
-- **4 - Good**: Low risk, mostly clear, feasible with minor adjustments
-- **3 - Average**: Moderate risk, some clarification needed, feasible with effort
-- **2 - Poor**: High risk, significant issues, major changes required
-- **1 - Critical**: Very high risk, fundamental problems, may not be feasible
+**Scoring Scale** (1-5):
+- 5 - Excellent: Minimal risk, well-defined, highly feasible
+- 4 - Good: Low risk, mostly clear, feasible
+- 3 - Average: Moderate risk, needs clarification
+- 2 - Poor: High risk, major changes required
+- 1 - Critical: Very high risk, fundamental problems
 
-### RISK CLASSIFICATION
-- **LOW**: Minor issues, easily addressable
-- **MEDIUM**: Manageable challenges requiring attention
-- **HIGH**: Significant concerns requiring major mitigation
-- **CRITICAL**: Fundamental problems threatening concept viability
+**Risk Levels**:
+- LOW: Minor issues, easily addressable
+- MEDIUM: Manageable challenges
+- HIGH: Significant concerns, major mitigation needed
+- CRITICAL: Fundamental viability threats
 
-### OPTIMIZATION PRIORITIES
-- **CRITICAL**: Must be addressed before planning
-- **IMPORTANT**: Should be addressed for optimal outcomes
-- **OPTIONAL**: Nice-to-have improvements
+**Optimization Priorities**:
+- CRITICAL: Must address before planning
+- IMPORTANT: Should address for optimal outcomes
+- OPTIONAL: Nice-to-have improvements
 
 ## OUTPUT REQUIREMENTS
 
-### EVALUATION SUMMARY
+### Evaluation Summary
 ```markdown
-# Concept Evaluation Summary
-
 ## Overall Assessment
-- **Feasibility Score**: X/5
-- **Risk Level**: LOW/MEDIUM/HIGH/CRITICAL
-- **Recommendation**: PROCEED/PROCEED_WITH_MODIFICATIONS/RECONSIDER/REJECT
+- Feasibility Score: X/5
+- Risk Level: LOW/MEDIUM/HIGH/CRITICAL
+- Recommendation: PROCEED/PROCEED_WITH_MODIFICATIONS/RECONSIDER/REJECT
 
 ## Dimension Scores
 - Conceptual Integrity: X/5
@@ -82,120 +83,45 @@ Rate each dimension on a scale of 1-5:
 - Dependency Complexity: X/5
 ```
 
-### DETAILED ANALYSIS
-For each dimension, provide:
-1. **Assessment**: Current state evaluation
-2. **Strengths**: What works well in the concept
-3. **Concerns**: Identified issues and risks
-4. **Recommendations**: Specific improvement suggestions
+### Detailed Analysis
+For each dimension:
+1. Assessment: Current state evaluation
+2. Strengths: What works well
+3. Concerns: Issues and risks
+4. Recommendations: Specific improvements
 
-### RISK MATRIX
-```markdown
+### Risk Matrix
 | Risk Category | Level | Impact | Mitigation Strategy |
-|---------------|-------|--------|-------------------|
-| Technical     | HIGH  | Delays | Proof of concept  |
-| Resource      | MED   | Budget | Phase approach    |
-```
+|---------------|-------|--------|---------------------|
+| Technical     | HIGH  | Delays | Proof of concept    |
+| Resource      | MED   | Budget | Phased approach     |
 
-### OPTIMIZATION ROADMAP
-Prioritized list of improvements:
-1. **CRITICAL**: [Issue] - [Recommendation] - [Impact]
-2. **IMPORTANT**: [Issue] - [Recommendation] - [Impact]
-3. **OPTIONAL**: [Issue] - [Recommendation] - [Impact]
+### Optimization Roadmap
+1. CRITICAL: [Issue] - [Recommendation] - [Impact]
+2. IMPORTANT: [Issue] - [Recommendation] - [Impact]
+3. OPTIONAL: [Issue] - [Recommendation] - [Impact]
 
-## CONTEXT INTEGRATION RULES
+## CONTEXT INTEGRATION
 
-### CLAUDE CODE MEMORY INTEGRATION
-- **Session Context**: Reference current conversation history and decisions made
-- **Project Memory**: Leverage knowledge from previous implementations and lessons learned
-- **Pattern Recognition**: Use identified successful approaches and anti-patterns from session memory
-- **Evaluation History**: Consider previous concept evaluations and their outcomes
-- **Technical Evolution**: Build on previous technical decisions and architectural changes
-- **Context Continuity**: Maintain consistency with established project direction and decisions
+**Session Memory**: Reference current conversation, decisions, patterns from session history
+**Existing Patterns**: Identify similar implementations, evaluate success/failure, leverage proven approaches
+**Architectural Alignment**: Ensure consistency, consider evolution, apply standards
+**Business Context**: Strategic fit, user impact, competitive advantage, timeline alignment
 
-### EXISTING PATTERNS
-- **Identify**: Find similar implementations in the codebase
-- **Analyze**: Evaluate success/failure patterns
-- **Leverage**: Recommend reusing successful approaches
-- **Avoid**: Flag problematic patterns to avoid
+## PROJECT TYPE CONSIDERATIONS
 
-### ARCHITECTURAL ALIGNMENT
-- **Consistency**: Ensure concept aligns with existing architecture
-- **Evolution**: Consider architectural evolution and migration paths
-- **Standards**: Apply established coding and design standards
-- **Integration**: Evaluate integration touchpoints and complexity
+**Innovation Projects**: Higher risk tolerance, learning focus, phased approach
+**Critical Business**: Lower risk tolerance, reliability focus, comprehensive mitigation
+**Integration Projects**: Compatibility focus, minimal disruption, rollback strategies
+**Greenfield Projects**: Architectural innovation, scalability, technology standardization
 
-### BUSINESS CONTEXT
-- **Strategic Fit**: Alignment with business objectives and priorities
-- **User Impact**: Effect on user experience and satisfaction
-- **Competitive Advantage**: Differentiation and market positioning
-- **Timeline**: Alignment with business timelines and milestones
+## VERIFICATION CHECKLIST ✓
+□ All 6 evaluation dimensions thoroughly assessed with scores
+□ Risk matrix completed with mitigation strategies
+□ Optimization recommendations prioritized (CRITICAL/IMPORTANT/OPTIONAL)
+□ Integration with existing systems evaluated
+□ Resource requirements and timeline implications identified
+□ Success criteria and validation metrics defined
+□ Next steps and decision points outlined
 
-## QUALITY STANDARDS
-
-### ANALYSIS DEPTH
-- Provide specific examples and evidence
-- Quantify assessments where possible
-- Consider multiple perspectives and scenarios
-- Base recommendations on concrete analysis
-
-### ACTIONABILITY
-- Make recommendations specific and implementable
-- Provide clear next steps and decision points
-- Identify responsible parties and timelines
-- Include success metrics and validation criteria
-
-### OBJECTIVITY
-- Balance optimism with realistic assessment
-- Acknowledge uncertainty and assumptions
-- Present multiple options where applicable
-- Focus on concept improvement rather than criticism
-
-## SPECIAL CONSIDERATIONS
-
-### INNOVATION PROJECTS
-- Higher tolerance for technical risk
-- Emphasis on learning and experimentation
-- Phased approach with validation milestones
-- Clear success/failure criteria
-
-### CRITICAL BUSINESS PROJECTS
-- Lower risk tolerance
-- Emphasis on reliability and predictability
-- Comprehensive risk mitigation strategies
-- Detailed contingency planning
-
-### INTEGRATION PROJECTS
-- Focus on compatibility and interoperability
-- Emphasis on minimizing system disruption
-- Careful change management planning
-- Rollback and recovery strategies
-
-### GREENFIELD PROJECTS
-- Opportunity for architectural innovation
-- Emphasis on future scalability and flexibility
-- Technology stack selection and standardization
-- Team skill development considerations
-
-## EVALUATION COMPLETION CHECKLIST
-
-- [ ] All six evaluation dimensions thoroughly assessed
-- [ ] Risk matrix completed with mitigation strategies
-- [ ] Optimization recommendations prioritized
-- [ ] Integration with existing systems evaluated
-- [ ] Resource requirements clearly identified
-- [ ] Timeline implications considered
-- [ ] Success criteria and validation metrics defined
-- [ ] Next steps and decision points outlined
-
-## OUTPUT FORMAT
-
-Provide a structured evaluation report that includes:
-1. Executive summary with overall recommendation
-2. Detailed dimension-by-dimension analysis
-3. Risk assessment and mitigation strategies
-4. Prioritized optimization recommendations
-5. Implementation roadmap and next steps
-6. Resource requirements and timeline implications
-
-Focus on providing actionable insights that will improve concept quality and reduce implementation risks during the formal planning phase.
+Focus: Actionable insights to improve concept quality and reduce implementation risks.

.claude/workflows/cli-templates/prompts/planning/migration.txt

@@ -1,16 +1,30 @@
-Plan system migration and modernization strategies:
+Plan system migration and modernization strategies.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Assess current system completely before planning migration
+□ Plan incremental migration (avoid big-bang approach)
+□ Include rollback plan for every migration step
+□ Provide file:line references for all affected code
+
+## REQUIRED ANALYSIS
 1. Assess current system architecture and migration requirements
 2. Identify migration paths and transformation strategies
 3. Plan data migration and system cutover procedures
 4. Evaluate compatibility and integration challenges
 5. Document rollback plans and risk mitigation strategies
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Migration strategy with step-by-step execution plan
 - Data migration procedures and validation checkpoints
-- Compatibility assessment and integration requirements
-- Risk analysis and rollback procedures
+- Compatibility assessment with file:line references
+- Risk analysis and rollback procedures for each phase
+- Testing strategy for migration validation
 
-Focus on low-risk migration strategies with comprehensive fallback options.
+## VERIFICATION CHECKLIST ✓
+□ Migration planned in incremental phases (not big-bang)
+□ Every phase has rollback plan documented
+□ Data migration validated with checkpoints
+□ Compatibility issues identified and mitigated
+□ Testing strategy covers all migration phases
+
+Focus: Low-risk incremental migration with comprehensive fallback options.

.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt

@@ -1,16 +1,30 @@
-Create detailed task breakdown and implementation planning:
+Create detailed task breakdown and implementation planning.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Break down tasks into manageable subtasks (3-8 hours each)
+□ Identify all dependencies and execution sequence
+□ Provide realistic effort estimates with buffer
+□ Document risks for each task
+
+## REQUIRED ANALYSIS
 1. Break down complex tasks into manageable subtasks
 2. Identify dependencies and execution sequence requirements
 3. Estimate effort and resource requirements for each task
 4. Map task relationships and critical path analysis
 5. Document risks and mitigation strategies
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Hierarchical task breakdown with specific deliverables
 - Dependency mapping and execution sequence
-- Effort estimation and resource allocation
-- Risk assessment and mitigation plans
+- Effort estimation with confidence levels
+- Resource allocation and skill requirements
+- Risk assessment and mitigation plans for each task
 
-Focus on actionable task planning with clear deliverables and timelines.
+## VERIFICATION CHECKLIST ✓
+□ All tasks broken down to manageable size (3-8 hours)
+□ Dependencies mapped and critical path identified
+□ Effort estimates realistic with buffer included
+□ Every task has clear deliverable defined
+□ Risks documented with mitigation strategies
+
+Focus: Actionable task planning with clear deliverables, dependencies, and realistic timelines.

.claude/workflows/cli-templates/prompts/review/code-review.txt

@@ -1,16 +1,28 @@
-Conduct comprehensive code review and quality assessment:
+Conduct comprehensive code review and quality assessment.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Review against established coding standards and conventions
+□ Assess logic correctness, including potential edge cases
+□ Evaluate security implications and vulnerability risks
+□ Check for performance bottlenecks and optimization opportunities
+
+## REQUIRED ANALYSIS
 1. Review code against established coding standards and conventions
 2. Assess logic correctness and potential edge cases
 3. Evaluate security implications and vulnerability risks
 4. Check performance characteristics and optimization opportunities
 5. Validate test coverage and documentation completeness
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Standards compliance assessment with specific violations
 - Logic review findings with potential issue identification
 - Security assessment with vulnerability documentation
 - Performance review with optimization recommendations
 
-Focus on actionable feedback with clear improvement priorities and implementation guidance.
+## VERIFICATION CHECKLIST ✓
+□ Code is assessed against established standards
+□ Logic, including edge cases, is thoroughly reviewed
+□ Security and performance have been evaluated
+□ Test coverage and documentation are validated
+
+Focus: Actionable feedback with clear improvement priorities and implementation guidance.

.claude/workflows/cli-templates/prompts/verification/codex-technical.txt

@@ -1,59 +1,28 @@
-Technical feasibility assessment of workflow implementation plan from code quality and execution perspective:
+Assess the technical feasibility of a workflow implementation plan.
 
-## Required Technical Analysis:
-1. **Implementation Complexity Assessment**
-   - Evaluate code complexity and technical difficulty
-   - Assess required technical skills and expertise levels
-   - Validate implementation approach feasibility
-   - Identify technical challenges and solutions
+## CORE CHECKLIST ⚡
+□ Evaluate implementation complexity and required skills
+□ Validate all technical dependencies and prerequisites
+□ Assess the proposed code structure and integration patterns
+□ Verify the completeness of the testing strategy
 
-2. **Technical Dependencies Validation**
-   - Review external library and framework dependencies
-   - Assess version compatibility and dependency conflicts
-   - Evaluate build system and deployment requirements
-   - Identify missing technical prerequisites
+## REQUIRED TECHNICAL ANALYSIS
+1. **Implementation Complexity**: Evaluate code difficulty and required skills.
+2. **Technical Dependencies**: Review libraries, versions, and build systems.
+3. **Code Structure**: Assess file organization, naming, and modularity.
+4. **Testing Completeness**: Evaluate test coverage, types, and gaps.
+5. **Execution Readiness**: Validate control flow, context, and file targets.
 
-3. **Code Structure Assessment**
-   - Evaluate proposed file organization and structure
-   - Assess naming conventions and code organization
-   - Validate integration with existing codebase patterns
-   - Review modularity and separation of concerns
+## OUTPUT REQUIREMENTS
+- **Technical Assessment Report**: Grades for implementation, complexity, and quality.
+- **Detailed Technical Findings**: Blocking issues, performance concerns, and improvements.
+- **Implementation Recommendations**: Prerequisites, best practices, and refactoring.
+- **Risk Mitigation**: Technical, dependency, integration, and quality risks.
 
-4. **Testing Completeness Evaluation**
-   - Assess test coverage and testing strategy completeness
-   - Evaluate test types and testing approach adequacy
-   - Review integration testing and end-to-end coverage
-   - Identify testing gaps and quality assurance needs
+## VERIFICATION CHECKLIST ✓
+□ Implementation complexity and feasibility have been thoroughly evaluated
+□ All technical dependencies and prerequisites are validated
+□ The proposed code structure aligns with project standards
+□ The testing plan is complete and adequate for the proposed changes
 
-5. **Execution Readiness Verification**
-   - Validate flow_control definitions and execution paths
-   - Assess task context completeness and adequacy
-   - Evaluate target_files specifications and accuracy
-   - Review implementation prerequisites and setup requirements
-
-## Output Requirements:
-### Technical Assessment Report:
-- **Implementation Grade** (A-F): Technical approach quality
-- **Complexity Score** (1-10): Implementation difficulty level
-- **Readiness Level** (1-5): Execution preparation completeness
-- **Quality Rating** (1-10): Code quality and maintainability projection
-
-### Detailed Technical Findings:
-- **Blocking Issues**: Technical problems that prevent implementation
-- **Performance Concerns**: Scalability and performance implications
-- **Quality Improvements**: Code quality and maintainability enhancements
-- **Testing Enhancements**: Testing strategy and coverage improvements
-
-### Implementation Recommendations:
-- **Prerequisites**: Required setup and configuration changes
-- **Best Practices**: Code patterns and conventions to follow
-- **Tool Requirements**: Additional tools or dependencies needed
-- **Refactoring Suggestions**: Code structure and organization improvements
-
-### Risk Mitigation:
-- **Technical Risks**: Implementation complexity and technical debt
-- **Dependency Risks**: External dependencies and compatibility issues
-- **Integration Risks**: Codebase integration and compatibility concerns
-- **Quality Risks**: Code quality and maintainability implications
-
-Focus on technical execution details, code quality concerns, and implementation feasibility. Provide specific, actionable recommendations with clear implementation guidance and priority levels.
+Focus: Technical execution details, code quality concerns, and implementation feasibility.

.claude/workflows/cli-templates/prompts/verification/cross-validation.txt

@@ -1,65 +1,28 @@
-Cross-validation analysis of gemini strategic and codex technical assessments for workflow implementation plan:
+Cross-validate strategic (Gemini) and technical (Codex) assessments.
 
-## Required Cross-Validation Analysis:
-1. **Consensus Identification**
-   - Identify areas where both analyses agree on issues or strengths
-   - Document shared concerns and aligned recommendations
-   - Highlight consistent risk assessments and mitigation strategies
-   - Establish priority consensus for implementation focus
+## CORE CHECKLIST ⚡
+□ Identify both consensus and conflict between the two analyses
+□ Synthesize a unified risk profile and recommendation set
+□ Resolve conflicting suggestions with a balanced approach
+□ Frame final decisions as clear choices for the user
 
-2. **Conflict Resolution Analysis**
-   - Identify discrepancies between strategic and technical perspectives
-   - Analyze root causes of conflicting assessments
-   - Evaluate trade-offs between strategic goals and technical constraints
-   - Provide balanced recommendations for resolution
+## REQUIRED CROSS-VALIDATION ANALYSIS
+1. **Consensus Identification**: Find where both analyses agree.
+2. **Conflict Resolution**: Analyze and resolve discrepancies.
+3. **Risk Level Synthesis**: Combine risk assessments into a single profile.
+4. **Recommendation Integration**: Synthesize recommendations into a unified plan.
+5. **Quality Assurance Framework**: Establish combined quality metrics.
 
-3. **Risk Level Synthesis**
-   - Combine strategic and technical risk assessments
-   - Establish overall implementation risk profile
-   - Prioritize risks by impact and probability
-   - Recommend risk mitigation strategies
+## OUTPUT REQUIREMENTS
+- **Cross-Validation Summary**: Overall grade, confidence score, and risk profile.
+- **Synthesis Report**: Consensus areas, conflict areas, and integrated recommendations.
+- **User Approval Framework**: A clear breakdown of changes for user approval.
+- **Modification Categories**: Classify changes by type (e.g., Task Structure, Technical).
 
-4. **Recommendation Integration**
-   - Synthesize strategic and technical recommendations
-   - Resolve conflicting suggestions with balanced approach
-   - Prioritize recommendations by impact and effort
-   - Establish implementation sequence and dependencies
+## VERIFICATION CHECKLIST ✓
+□ Both consensus and conflict between analyses are identified and documented
+□ Risks and recommendations are synthesized into a single, coherent plan
+□ Conflicting points are resolved with balanced, well-reasoned proposals
+□ Final output is structured to facilitate clear user decisions
 
-5. **Quality Assurance Framework**
-   - Establish combined quality metrics and success criteria
-   - Define validation checkpoints and review gates
-   - Recommend monitoring and feedback mechanisms
-   - Ensure both strategic and technical quality standards
-
-## Input Analysis Sources:
-- **Gemini Strategic Analysis**: Architecture, business alignment, strategic risks
-- **Codex Technical Analysis**: Implementation feasibility, code quality, technical risks
-- **Original Implementation Plan**: IMPL_PLAN.md, task definitions, context
-
-## Output Requirements:
-### Cross-Validation Summary:
-- **Overall Assessment Grade** (A-F): Combined strategic and technical evaluation
-- **Implementation Confidence** (1-10): Combined feasibility assessment
-- **Risk Profile**: High/Medium/Low with specific risk categories
-- **Recommendation Priority Matrix**: Urgent/Important classification
-
-### Synthesis Report:
-- **Consensus Areas**: Shared findings and aligned recommendations
-- **Conflict Areas**: Divergent perspectives requiring resolution
-- **Integrated Recommendations**: Balanced strategic and technical guidance
-- **Implementation Roadmap**: Phased approach balancing strategic and technical needs
-
-### User Approval Framework:
-- **Critical Changes**: Must-implement modifications (blocking issues)
-- **Important Improvements**: High-value enhancements (quality/efficiency)
-- **Optional Enhancements**: Nice-to-have improvements (future consideration)
-- **Trade-off Decisions**: User choice between competing approaches
-
-### Modification Categories:
-- **Task Structure**: Task merging, splitting, or reordering
-- **Dependencies**: Dependency additions, removals, or modifications
-- **Context Enhancement**: Requirements, acceptance criteria, or documentation
-- **Technical Adjustments**: Implementation approach or tool changes
-- **Strategic Alignment**: Business objective or success criteria refinement
-
-Focus on balanced integration of strategic and technical perspectives. Provide clear user decision points with impact analysis and implementation guidance. Prioritize recommendations by combined strategic and technical value.
+Focus: A balanced integration of strategic and technical perspectives to produce a single, actionable plan.

.claude/workflows/cli-templates/prompts/verification/gemini-strategic.txt

@@ -1,52 +1,27 @@
-Strategic validation of workflow implementation plan from architectural and business perspective:
+Validate the strategic and architectural soundness of a workflow implementation plan.
 
-## Required Strategic Analysis:
-1. **Architectural Soundness Assessment**
-   - Evaluate overall system design coherence
-   - Assess component interaction patterns
-   - Validate architectural decision consistency
-   - Identify potential design conflicts or gaps
+## CORE CHECKLIST ⚡
+□ Evaluate the plan against high-level system architecture
+□ Assess the logic of the task breakdown and dependencies
+□ Verify alignment with stated business objectives and success criteria
+□ Identify strategic risks, not just low-level technical ones
 
-2. **Task Decomposition Logic Evaluation**
-   - Review task breakdown methodology and rationale
-   - Assess functional completeness of each task
-   - Evaluate task granularity and scope appropriateness
-   - Identify missing or redundant decomposition elements
+## REQUIRED STRATEGIC ANALYSIS
+1. **Architectural Soundness**: Assess design coherence and pattern consistency.
+2. **Task Decomposition Logic**: Review task breakdown, granularity, and completeness.
+3. **Dependency Coherence**: Analyze task interdependencies and logical flow.
+4. **Business Alignment**: Validate against business objectives and requirements.
+5. **Strategic Risk Identification**: Identify architectural, resource, and timeline risks.
 
-3. **Dependency Coherence Analysis**
-   - Map task interdependencies and logical flow
-   - Validate dependency ordering and scheduling
-   - Assess circular dependency risks
-   - Evaluate parallel execution opportunities
+## OUTPUT REQUIREMENTS
+- **Strategic Assessment Report**: Grades for architecture, decomposition, and business alignment.
+- **Detailed Recommendations**: Critical issues, improvements, and alternative approaches.
+- **Action Items**: A prioritized list of changes (Immediate, Short-term, Long-term).
 
-4. **Business Alignment Verification**
-   - Validate alignment with stated business objectives
-   - Assess stakeholder requirement coverage
-   - Evaluate success criteria completeness and measurability
-   - Identify business risk and mitigation adequacy
+## VERIFICATION CHECKLIST ✓
+□ The plan's architectural soundness has been thoroughly assessed
+□ Task decomposition and dependencies are logical and coherent
+□ The plan is confirmed to be in alignment with business goals
+□ Strategic risks are identified with clear recommendations
 
-5. **Strategic Risk Identification**
-   - Identify architectural risks and technical debt implications
-   - Assess implementation complexity and resource requirements
-   - Evaluate timeline feasibility and milestone realism
-   - Document potential blockers and escalation scenarios
-
-## Output Requirements:
-### Strategic Assessment Report:
-- **Architecture Grade** (A-F): Overall design quality assessment
-- **Decomposition Grade** (A-F): Task breakdown effectiveness
-- **Risk Level** (Low/Medium/High): Combined implementation risk
-- **Business Alignment Score** (1-10): Requirement satisfaction level
-
-### Detailed Recommendations:
-- **Critical Issues**: Must-fix problems that could cause failure
-- **Improvement Opportunities**: Non-blocking enhancements
-- **Alternative Approaches**: Strategic alternatives worth considering
-- **Resource Implications**: Staffing and timeline considerations
-
-### Action Items:
-- **Immediate**: Changes needed before implementation starts
-- **Short-term**: Improvements for early phases
-- **Long-term**: Strategic enhancements for future iterations
-
-Focus on high-level strategic concerns, business alignment, and long-term architectural implications. Provide actionable recommendations with clear rationale and priority levels.
+Focus: High-level strategic concerns, business alignment, and long-term architectural implications.

.claude/workflows/cli-templates/prompts/workflow/analysis-results-structure.txt

@@ -0,0 +1,224 @@
+Generate ANALYSIS_RESULTS.md with comprehensive solution design and technical analysis.
+
+## OUTPUT FILE STRUCTURE
+
+### Required Sections
+
+```markdown
+# Technical Analysis & Solution Design
+
+## Executive Summary
+- **Analysis Focus**: {core_problem_or_improvement_area}
+- **Analysis Timestamp**: {timestamp}
+- **Tools Used**: {analysis_tools}
+- **Overall Assessment**: {feasibility_score}/5 - {recommendation_status}
+
+---
+
+## 1. Current State Analysis
+
+### Architecture Overview
+- **Existing Patterns**: {key_architectural_patterns}
+- **Code Structure**: {current_codebase_organization}
+- **Integration Points**: {system_integration_touchpoints}
+- **Technical Debt Areas**: {identified_debt_with_impact}
+
+### Compatibility & Dependencies
+- **Framework Alignment**: {framework_compatibility_assessment}
+- **Dependency Analysis**: {critical_dependencies_and_risks}
+- **Migration Considerations**: {backward_compatibility_concerns}
+
+### Critical Findings
+- **Strengths**: {what_works_well}
+- **Gaps**: {missing_capabilities_or_issues}
+- **Risks**: {identified_technical_and_business_risks}
+
+---
+
+## 2. Proposed Solution Design
+
+### Core Architecture Principles
+- **Design Philosophy**: {key_design_principles}
+- **Architectural Approach**: {chosen_architectural_pattern_with_rationale}
+- **Scalability Strategy**: {how_solution_scales}
+
+### System Design
+- **Component Architecture**: {high_level_component_design}
+- **Data Flow**: {data_flow_patterns_and_state_management}
+- **API Design**: {interface_contracts_and_specifications}
+- **Integration Strategy**: {how_components_integrate}
+
+### Key Design Decisions
+1. **Decision**: {critical_design_choice}
+   - **Rationale**: {why_this_approach}
+   - **Alternatives Considered**: {other_options_and_tradeoffs}
+   - **Impact**: {implications_on_architecture}
+
+2. **Decision**: {another_critical_choice}
+   - **Rationale**: {reasoning}
+   - **Alternatives Considered**: {tradeoffs}
+   - **Impact**: {consequences}
+
+### Technical Specifications
+- **Technology Stack**: {chosen_technologies_with_justification}
+- **Code Organization**: {module_structure_and_patterns}
+- **Testing Strategy**: {testing_approach_and_coverage}
+- **Performance Targets**: {performance_requirements_and_benchmarks}
+
+---
+
+## 3. Implementation Strategy
+
+### Development Approach
+- **Core Implementation Pattern**: {primary_implementation_strategy}
+- **Module Dependencies**: {dependency_graph_and_order}
+- **Quality Assurance**: {qa_approach_and_validation}
+
+### Code Modification Targets
+**Purpose**: Specific code locations for modification AND new files to create
+
+**Identified Targets**:
+1. **Target**: `src/module/File.ts:function:45-52`
+   - **Type**: Modify existing
+   - **Modification**: {what_to_change}
+   - **Rationale**: {why_change_needed}
+
+2. **Target**: `src/module/NewFile.ts`
+   - **Type**: Create new file
+   - **Purpose**: {file_purpose}
+   - **Rationale**: {why_new_file_needed}
+
+**Format Rules**:
+- Existing files: `file:function:lines` (with line numbers)
+- New files: `file` (no function or lines)
+- Unknown lines: `file:function:*`
+
+### Feasibility Assessment
+- **Technical Complexity**: {complexity_rating_and_analysis}
+- **Performance Impact**: {expected_performance_characteristics}
+- **Resource Requirements**: {development_resources_needed}
+- **Maintenance Burden**: {ongoing_maintenance_considerations}
+
+### Risk Mitigation
+- **Technical Risks**: {implementation_risks_and_mitigation}
+- **Integration Risks**: {compatibility_challenges_and_solutions}
+- **Performance Risks**: {performance_concerns_and_strategies}
+- **Security Risks**: {security_vulnerabilities_and_controls}
+
+---
+
+## 4. Solution Optimization
+
+### Performance Optimization
+- **Optimization Strategies**: {key_performance_improvements}
+- **Caching Strategy**: {caching_approach_and_invalidation}
+- **Resource Management**: {resource_utilization_optimization}
+- **Bottleneck Mitigation**: {identified_bottlenecks_and_solutions}
+
+### Security Enhancements
+- **Security Model**: {authentication_authorization_approach}
+- **Data Protection**: {data_security_and_encryption}
+- **Vulnerability Mitigation**: {known_vulnerabilities_and_controls}
+- **Compliance**: {regulatory_and_compliance_considerations}
+
+### Code Quality
+- **Code Standards**: {coding_conventions_and_patterns}
+- **Testing Coverage**: {test_strategy_and_coverage_goals}
+- **Documentation**: {documentation_requirements}
+- **Maintainability**: {maintainability_practices}
+
+---
+
+## 5. Critical Success Factors
+
+### Technical Requirements
+- **Must Have**: {essential_technical_capabilities}
+- **Should Have**: {important_but_not_critical_features}
+- **Nice to Have**: {optional_enhancements}
+
+### Quality Metrics
+- **Performance Benchmarks**: {measurable_performance_targets}
+- **Code Quality Standards**: {quality_metrics_and_thresholds}
+- **Test Coverage Goals**: {testing_coverage_requirements}
+- **Security Standards**: {security_compliance_requirements}
+
+### Success Validation
+- **Acceptance Criteria**: {how_to_validate_success}
+- **Testing Strategy**: {validation_testing_approach}
+- **Monitoring Plan**: {production_monitoring_strategy}
+- **Rollback Plan**: {failure_recovery_strategy}
+
+---
+
+## 6. Analysis Confidence & Recommendations
+
+### Assessment Scores
+- **Conceptual Integrity**: {score}/5 - {brief_assessment}
+- **Architectural Soundness**: {score}/5 - {brief_assessment}
+- **Technical Feasibility**: {score}/5 - {brief_assessment}
+- **Implementation Readiness**: {score}/5 - {brief_assessment}
+- **Overall Confidence**: {overall_score}/5
+
+### Final Recommendation
+**Status**: {PROCEED|PROCEED_WITH_MODIFICATIONS|RECONSIDER|REJECT}
+
+**Rationale**: {clear_explanation_of_recommendation}
+
+**Critical Prerequisites**: {what_must_be_resolved_before_proceeding}
+
+---
+
+## 7. Reference Information
+
+### Tool Analysis Summary
+- **Gemini Insights**: {key_architectural_and_pattern_insights}
+- **Codex Validation**: {technical_feasibility_and_implementation_notes}
+- **Consensus Points**: {agreements_between_tools}
+- **Conflicting Views**: {disagreements_and_resolution}
+
+### Context & Resources
+- **Analysis Context**: {context_package_reference}
+- **Documentation References**: {relevant_documentation}
+- **Related Patterns**: {similar_implementations_in_codebase}
+- **External Resources**: {external_references_and_best_practices}
+```
+
+## CONTENT REQUIREMENTS
+
+### Analysis Priority Sources
+1. **PRIMARY**: Individual role analysis.md files (system-architect, ui-designer, etc.) - technical details, ADRs, decision context
+2. **SECONDARY**: synthesis-specification.md - integrated requirements, cross-role alignment
+3. **REFERENCE**: topic-framework.md - discussion context
+
+### Focus Areas
+- **SOLUTION IMPROVEMENTS**: How to enhance current design
+- **KEY DESIGN DECISIONS**: Critical choices with rationale, alternatives, tradeoffs
+- **CRITICAL INSIGHTS**: Non-obvious findings, risks, opportunities
+- **OPTIMIZATION**: Performance, security, code quality recommendations
+
+### Exclusions
+- ❌ Task lists or implementation steps
+- ❌ Code examples or snippets
+- ❌ Project management timelines
+- ❌ Resource allocation details
+
+## OUTPUT VALIDATION
+
+### Completeness Checklist
+□ All 7 sections present with content
+□ Executive Summary with feasibility score
+□ Current State Analysis with findings
+□ Solution Design with 2+ key decisions
+□ Implementation Strategy with code targets
+□ Optimization recommendations in 3 areas
+□ Confidence scores with final recommendation
+□ Reference information included
+
+### Quality Standards
+□ Design decisions include rationale and alternatives
+□ Code targets specify file:function:lines format
+□ Risk assessment with mitigation strategies
+□ Quantified scores (X/5) for all assessments
+□ Clear PROCEED/RECONSIDER/REJECT recommendation
+
+Focus: Solution-focused technical analysis emphasizing design decisions and critical insights.