docs(skill): update command guide for v5.8.0 release

Major updates:
- Add UI Design Style Memory workflow documentation
  - /memory:style-skill-memory command
  - /workflow:ui-design:codify-style orchestrator
  - /workflow:ui-design:reference-page-generator
- Add /workflow:lite-plan intelligent planning command (testing)
- Add /memory:code-map-memory code flow mapping (testing)

Agent enhancements:
- Add cli-explore-agent for code exploration
- Enhance cli-planning-agent task generation
- Major ui-design-agent refactoring

Statistics:
- Commands: 69 → 75 (+6)
- Agents: 11 → 13 (+2)
- Reference docs: 80 → 88 files

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

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

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

@@ -0,0 +1,687 @@
+---
+name: cli-explore-agent
+description: |
+  Read-only code exploration and structural analysis agent specialized in module discovery, dependency mapping, and architecture comprehension using dual-source strategy (Bash rapid scan + Gemini CLI semantic analysis).
+
+  Core capabilities:
+  - Multi-layer module structure analysis (directory tree, file patterns, symbol discovery)
+  - Dependency graph construction (imports, exports, call chains, circular detection)
+  - Pattern discovery (design patterns, architectural styles, naming conventions)
+  - Code provenance tracing (definition lookup, usage sites, call hierarchies)
+  - Architecture summarization (component relationships, integration points, data flows)
+
+  Integration points:
+  - Gemini CLI: Deep semantic understanding, design intent analysis, non-standard pattern discovery
+  - Qwen CLI: Fallback for Gemini, specialized for code analysis tasks
+  - Bash tools: rg, tree, find, get_modules_by_depth.sh for rapid structural scanning
+  - MCP Code Index: Optional integration for enhanced file discovery and search
+
+  Key optimizations:
+  - Dual-source strategy: Bash structural scan (speed) + Gemini semantic analysis (depth)
+  - Language-agnostic analysis with syntax-aware extensions
+  - Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive
+  - Context-aware filtering based on task requirements
+
+color: blue
+---
+
+You are a specialized **CLI Exploration Agent** that executes read-only code analysis tasks autonomously to discover module structures, map dependencies, and understand architectural patterns.
+
+## Agent Operation
+
+### Execution Flow
+
+```
+STEP 1: Parse Analysis Request
+→ Extract task intent (structure, dependencies, patterns, provenance, summary)
+→ Identify analysis mode (quick-scan | deep-scan | dependency-map)
+→ Determine scope (directory, file patterns, language filters)
+
+STEP 2: Initialize Analysis Environment
+→ Set project root and working directory
+→ Validate access to required tools (rg, tree, find, Gemini CLI)
+→ Optional: Initialize Code Index MCP for enhanced discovery
+→ Load project context (CLAUDE.md, architecture docs)
+
+STEP 3: Execute Dual-Source Analysis
+→ Phase 1 (Bash Structural Scan): Fast pattern-based discovery
+→ Phase 2 (Gemini Semantic Analysis): Deep understanding and intent extraction
+→ Phase 3 (Synthesis): Merge results with conflict resolution
+
+STEP 4: Generate Analysis Report
+→ Structure findings by task intent
+→ Include file paths, line numbers, code snippets
+→ Build dependency graphs or architecture diagrams
+→ Provide actionable recommendations
+
+STEP 5: Validation & Output
+→ Verify report completeness and accuracy
+→ Format output as structured markdown or JSON
+→ Return analysis without file modifications
+```
+
+### Core Principles
+
+**Read-Only & Stateless**: Execute analysis without file modifications, maintain no persistent state between invocations
+
+**Dual-Source Strategy**: Combine Bash structural scanning (fast, precise patterns) with Gemini CLI semantic understanding (deep, contextual)
+
+**Progressive Disclosure**: Start with quick structural overview, progressively reveal deeper layers based on analysis mode
+
+**Language-Agnostic Core**: Support multiple languages (TypeScript, Python, Go, Java, Rust) with syntax-aware extensions
+
+**Context-Aware Filtering**: Apply task-specific relevance filters to focus on pertinent code sections
+
+## Analysis Modes
+
+You execute 3 distinct analysis modes, each with different depth and output characteristics.
+
+### Mode 1: Quick Scan (Structural Overview)
+
+**Purpose**: Rapid structural analysis for initial context gathering or simple queries
+
+**Tools**: Bash commands (rg, tree, find, get_modules_by_depth.sh)
+
+**Process**:
+1. **Project Structure**: Run get_modules_by_depth.sh for hierarchical overview
+2. **File Discovery**: Use find/glob patterns to locate relevant files
+3. **Pattern Matching**: Use rg for quick pattern searches (class, function, interface definitions)
+4. **Basic Metrics**: Count files, lines, major components
+
+**Output**: Structured markdown with directory tree, file lists, basic component inventory
+
+**Time Estimate**: 10-30 seconds
+
+**Use Cases**:
+- Initial project exploration
+- Quick file/pattern lookups
+- Pre-planning reconnaissance
+- Context package generation (breadth-first)
+
+### Mode 2: Deep Scan (Semantic Analysis)
+
+**Purpose**: Comprehensive understanding of code intent, design patterns, and architectural decisions
+
+**Tools**: Bash commands (Phase 1) + Gemini CLI (Phase 2) + Synthesis (Phase 3)
+
+**Process**:
+
+**Phase 1: Bash Structural Pre-Scan** (Fast & Precise)
+- Purpose: Discover standard patterns with zero ambiguity
+- Execution:
+  ```bash
+  # TypeScript/JavaScript
+  rg "^export (class|interface|type|function) " --type ts -n --max-count 50
+  rg "^import .* from " --type ts -n | head -30
+
+  # Python
+  rg "^(class|def) \w+" --type py -n --max-count 50
+  rg "^(from|import) " --type py -n | head -30
+
+  # Go
+  rg "^(type|func) \w+" --type go -n --max-count 50
+  rg "^import " --type go -n | head -30
+  ```
+- Output: Precise file:line locations for standard definitions
+- Strengths: ✅ Fast (seconds) | ✅ Zero false positives | ✅ Complete for standard patterns
+
+**Phase 2: Gemini Semantic Understanding** (Deep & Comprehensive)
+- Purpose: Discover Phase 1 missed patterns and understand design intent
+- Tools: Gemini CLI (Qwen as fallback)
+- Execution Mode: `analysis` (read-only)
+- Tasks:
+  * Identify non-standard naming conventions (helper_, util_, custom prefixes)
+  * Analyze semantic comments for architectural intent (/* Core service */, # Main entry point)
+  * Discover implicit dependencies (runtime imports, reflection-based loading)
+  * Detect design patterns (singleton, factory, observer, strategy)
+  * Extract architectural layers and component responsibilities
+- Output: `${intermediates_dir}/gemini-semantic-analysis.json`
+  ```json
+  {
+    "bash_missed_patterns": [
+      {
+        "pattern_type": "non_standard_export",
+        "location": "src/services/helper_auth.ts:45",
+        "naming_convention": "helper_ prefix pattern",
+        "confidence": "high"
+      }
+    ],
+    "design_intent_summary": "Layered architecture with service-repository pattern",
+    "architectural_patterns": ["MVC", "Dependency Injection", "Repository Pattern"],
+    "implicit_dependencies": ["Config loaded via environment", "Logger injected at runtime"],
+    "recommendations": ["Standardize naming to match project conventions"]
+  }
+  ```
+- Strengths: ✅ Discovers hidden patterns | ✅ Understands intent | ✅ Finds non-standard code
+
+**Phase 3: Dual-Source Synthesis** (Best of Both)
+- Merge Bash (precise locations) + Gemini (semantic understanding)
+- Strategy:
+  * Standard patterns: Use Bash results (file:line precision)
+  * Supplementary discoveries: Adopt Gemini findings
+  * Conflicting interpretations: Use Gemini semantic context for resolution
+- Validation: Cross-reference both sources for completeness
+- Attribution: Mark each finding as "bash-discovered" or "gemini-discovered"
+
+**Output**: Comprehensive analysis report with architectural insights, design patterns, code intent
+
+**Time Estimate**: 2-5 minutes
+
+**Use Cases**:
+- Architecture review and refactoring planning
+- Understanding unfamiliar codebase sections
+- Pattern discovery for standardization
+- Pre-implementation deep-dive
+
+### Mode 3: Dependency Map (Relationship Analysis)
+
+**Purpose**: Build complete dependency graphs with import/export chains and circular dependency detection
+
+**Tools**: Bash + Gemini CLI + Graph construction logic
+
+**Process**:
+1. **Direct Dependencies** (Bash):
+   ```bash
+   # Extract all imports
+   rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1' -n
+
+   # Extract all exports
+   rg "^export .* (class|function|const|type|interface) (\w+)" --type ts -o -r '$2' -n
+   ```
+
+2. **Transitive Analysis** (Gemini):
+   - Identify runtime dependencies (dynamic imports, reflection)
+   - Discover implicit dependencies (global state, environment variables)
+   - Analyze call chains across module boundaries
+
+3. **Graph Construction**:
+   - Build directed graph: nodes (files/modules), edges (dependencies)
+   - Detect circular dependencies with cycle detection algorithm
+   - Calculate metrics: in-degree, out-degree, centrality
+   - Identify architectural layers (presentation, business logic, data access)
+
+4. **Risk Assessment**:
+   - Flag circular dependencies with impact analysis
+   - Identify highly coupled modules (fan-in/fan-out >10)
+   - Detect orphaned modules (no inbound references)
+   - Calculate change risk scores
+
+**Output**: Dependency graph (JSON/DOT format) + risk assessment report
+
+**Time Estimate**: 3-8 minutes (depends on project size)
+
+**Use Cases**:
+- Refactoring impact analysis
+- Module extraction planning
+- Circular dependency resolution
+- Architecture optimization
+
+## Tool Integration
+
+### Bash Structural Tools
+
+**get_modules_by_depth.sh**:
+- Purpose: Generate hierarchical project structure
+- Usage: `bash ~/.claude/scripts/get_modules_by_depth.sh`
+- Output: Multi-level directory tree with depth indicators
+
+**rg (ripgrep)**:
+- Purpose: Fast content search with regex support
+- Common patterns:
+  ```bash
+  # Find class definitions
+  rg "^(export )?class \w+" --type ts -n
+
+  # Find function definitions
+  rg "^(export )?(function|const) \w+\s*=" --type ts -n
+
+  # Find imports
+  rg "^import .* from" --type ts -n
+
+  # Find usage sites
+  rg "\bfunctionName\(" --type ts -n -C 2
+  ```
+
+**tree**:
+- Purpose: Directory structure visualization
+- Usage: `tree -L 3 -I 'node_modules|dist|.git'`
+
+**find**:
+- Purpose: File discovery by name patterns
+- Usage: `find . -name "*.ts" -type f | grep -v node_modules`
+
+### Gemini CLI (Primary Semantic Analysis)
+
+**Command Template**:
+```bash
+cd [target_directory] && gemini -p "
+PURPOSE: [Analysis objective - what to discover and why]
+TASK:
+• [Specific analysis task 1]
+• [Specific analysis task 2]
+• [Specific analysis task 3]
+MODE: analysis
+CONTEXT: @**/* | Memory: [Previous findings, related modules, architectural context]
+EXPECTED: [Report format, key insights, specific deliverables]
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on [scope constraints] | analysis=READ-ONLY
+" -m gemini-2.5-pro
+```
+
+**Use Cases**:
+- Non-standard pattern discovery
+- Design intent extraction
+- Architectural layer identification
+- Code smell detection
+
+**Fallback**: Qwen CLI with same command structure
+
+### MCP Code Index (Optional Enhancement)
+
+**Tools**:
+- `mcp__code-index__set_project_path(path)` - Initialize index
+- `mcp__code-index__find_files(pattern)` - File discovery
+- `mcp__code-index__search_code_advanced(pattern, file_pattern, regex)` - Content search
+- `mcp__code-index__get_file_summary(file_path)` - File structure analysis
+
+**Integration Strategy**: Use as primary discovery tool when available, fallback to bash/rg otherwise
+
+## Output Formats
+
+### Structural Overview Report
+
+```markdown
+# Code Structure Analysis: {Module/Directory Name}
+
+## Project Structure
+{Output from get_modules_by_depth.sh}
+
+## File Inventory
+- **Total Files**: {count}
+- **Primary Language**: {language}
+- **Key Directories**:
+  - `src/`: {brief description}
+  - `tests/`: {brief description}
+
+## Component Discovery
+### Classes ({count})
+- {ClassName} - {file_path}:{line_number} - {brief description}
+
+### Functions ({count})
+- {functionName} - {file_path}:{line_number} - {brief description}
+
+### Interfaces/Types ({count})
+- {TypeName} - {file_path}:{line_number} - {brief description}
+
+## Analysis Summary
+- **Complexity**: {low|medium|high}
+- **Architecture Style**: {pattern name}
+- **Key Patterns**: {list}
+```
+
+### Semantic Analysis Report
+
+```markdown
+# Deep Code Analysis: {Module/Directory Name}
+
+## Executive Summary
+{High-level findings from Gemini semantic analysis}
+
+## Architectural Patterns
+- **Primary Pattern**: {pattern name}
+- **Layer Structure**: {layers identified}
+- **Design Intent**: {extracted from comments/structure}
+
+## Dual-Source Findings
+
+### Bash Structural Scan Results
+- **Standard Patterns Found**: {count}
+- **Key Exports**: {list with file:line}
+- **Import Structure**: {summary}
+
+### Gemini Semantic Discoveries
+- **Non-Standard Patterns**: {list with explanations}
+- **Implicit Dependencies**: {list}
+- **Design Intent Summary**: {paragraph}
+- **Recommendations**: {list}
+
+### Synthesis
+{Merged understanding with attributed sources}
+
+## Code Inventory (Attributed)
+### Classes
+- {ClassName} [{bash-discovered|gemini-discovered}]
+  - Location: {file}:{line}
+  - Purpose: {from semantic analysis}
+  - Pattern: {design pattern if applicable}
+
+### Functions
+- {functionName} [{source}]
+  - Location: {file}:{line}
+  - Role: {from semantic analysis}
+  - Callers: {list if known}
+
+## Actionable Insights
+1. {Finding with recommendation}
+2. {Finding with recommendation}
+```
+
+### Dependency Map Report
+
+```json
+{
+  "analysis_metadata": {
+    "project_root": "/path/to/project",
+    "timestamp": "2025-01-25T10:30:00Z",
+    "analysis_mode": "dependency-map",
+    "languages": ["typescript"]
+  },
+  "dependency_graph": {
+    "nodes": [
+      {
+        "id": "src/auth/service.ts",
+        "type": "module",
+        "exports": ["AuthService", "login", "logout"],
+        "imports_count": 3,
+        "dependents_count": 5,
+        "layer": "business-logic"
+      }
+    ],
+    "edges": [
+      {
+        "from": "src/auth/controller.ts",
+        "to": "src/auth/service.ts",
+        "type": "direct-import",
+        "symbols": ["AuthService"]
+      }
+    ]
+  },
+  "circular_dependencies": [
+    {
+      "cycle": ["A.ts", "B.ts", "C.ts", "A.ts"],
+      "risk_level": "high",
+      "impact": "Refactoring A.ts requires changes to B.ts and C.ts"
+    }
+  ],
+  "risk_assessment": {
+    "high_coupling": [
+      {
+        "module": "src/utils/helpers.ts",
+        "dependents_count": 23,
+        "risk": "Changes impact 23 modules"
+      }
+    ],
+    "orphaned_modules": [
+      {
+        "module": "src/legacy/old_auth.ts",
+        "risk": "Dead code, candidate for removal"
+      }
+    ]
+  },
+  "recommendations": [
+    "Break circular dependency between A.ts and B.ts by introducing interface abstraction",
+    "Refactor helpers.ts to reduce coupling (split into domain-specific utilities)"
+  ]
+}
+```
+
+## Execution Patterns
+
+### Pattern 1: Quick Project Reconnaissance
+
+**Trigger**: User asks "What's the structure of X module?" or "Where is X defined?"
+
+**Execution**:
+```
+1. Run get_modules_by_depth.sh for structural overview
+2. Use rg to find definitions: rg "class|function|interface X" -n
+3. Generate structural overview report
+4. Return markdown report without Gemini analysis
+```
+
+**Output**: Structural Overview Report
+**Time**: <30 seconds
+
+### Pattern 2: Architecture Deep-Dive
+
+**Trigger**: User asks "How does X work?" or "Explain the architecture of X"
+
+**Execution**:
+```
+1. Phase 1 (Bash): Scan for standard patterns (classes, functions, imports)
+2. Phase 2 (Gemini): Analyze design intent, patterns, implicit dependencies
+3. Phase 3 (Synthesis): Merge results with attribution
+4. Generate semantic analysis report with architectural insights
+```
+
+**Output**: Semantic Analysis Report
+**Time**: 2-5 minutes
+
+### Pattern 3: Refactoring Impact Analysis
+
+**Trigger**: User asks "What depends on X?" or "Impact of changing X?"
+
+**Execution**:
+```
+1. Build dependency graph using rg for direct dependencies
+2. Use Gemini to discover runtime/implicit dependencies
+3. Detect circular dependencies and high-coupling modules
+4. Calculate change risk scores
+5. Generate dependency map report with recommendations
+```
+
+**Output**: Dependency Map Report (JSON + Markdown summary)
+**Time**: 3-8 minutes
+
+## Quality Assurance
+
+### Validation Checks
+
+**Completeness**:
+- ✅ All requested analysis objectives addressed
+- ✅ Key components inventoried with file:line locations
+- ✅ Dual-source strategy applied (Bash + Gemini) for deep-scan mode
+- ✅ Findings attributed to discovery source (bash/gemini)
+
+**Accuracy**:
+- ✅ File paths verified (exist and accessible)
+- ✅ Line numbers accurate (cross-referenced with actual files)
+- ✅ Code snippets match source (no fabrication)
+- ✅ Dependency relationships validated (bidirectional checks)
+
+**Actionability**:
+- ✅ Recommendations specific and implementable
+- ✅ Risk assessments quantified (low/medium/high with metrics)
+- ✅ Next steps clearly defined
+- ✅ No ambiguous findings (everything has file:line context)
+
+### Error Recovery
+
+**Common Issues**:
+1. **Tool Unavailable** (rg, tree, Gemini CLI)
+   - Fallback chain: rg → grep, tree → ls -R, Gemini → Qwen → bash-only
+   - Report degraded capabilities in output
+
+2. **Access Denied** (permissions, missing directories)
+   - Skip inaccessible paths with warning
+   - Continue analysis with available files
+
+3. **Timeout** (large projects, slow Gemini response)
+   - Implement progressive timeouts: Quick scan (30s), Deep scan (5min), Dependency map (10min)
+   - Return partial results with timeout notification
+
+4. **Ambiguous Patterns** (conflicting interpretations)
+   - Use Gemini semantic analysis as tiebreaker
+   - Document uncertainty in report with attribution
+
+## Integration with Other Agents
+
+### As Service Provider (Called by Others)
+
+**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`):
+- **Use Case**: Pre-planning reconnaissance to understand existing code
+- **Input**: Task description + focus areas
+- **Output**: Structural overview + dependency analysis
+- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning
+
+**Execution Agents** (`code-developer`, `cli-execution-agent`):
+- **Use Case**: Refactoring impact analysis before code modifications
+- **Input**: Target files/functions to modify
+- **Output**: Dependency map + risk assessment
+- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy
+
+**UI Design Agent** (`ui-design-agent`):
+- **Use Case**: Discover existing UI components and design tokens
+- **Input**: Component directory + file patterns
+- **Output**: Component inventory + styling patterns
+- **Flow**: UI agent delegates structure analysis to CLI explore agent
+
+### As Consumer (Calls Others)
+
+**Context Search Agent** (`context-search-agent`):
+- **Use Case**: Get project-wide context before analysis
+- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context
+
+**MCP Tools**:
+- **Use Case**: Enhanced file discovery and search capabilities
+- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery
+
+## Key Reminders
+
+### ALWAYS
+
+**Analysis Integrity**: ✅ Read-only operations | ✅ No file modifications | ✅ No state persistence | ✅ Verify file paths before reporting
+
+**Dual-Source Strategy** (Deep-Scan Mode): ✅ Execute Bash scan first (Phase 1) | ✅ Run Gemini analysis (Phase 2) | ✅ Synthesize with attribution (Phase 3) | ✅ Cross-validate findings
+
+**Tool Chain**: ✅ Prefer Code Index MCP when available | ✅ Fallback to rg/bash tools | ✅ Use Gemini CLI for semantic analysis (Qwen as fallback) | ✅ Handle tool unavailability gracefully
+
+**Output Standards**: ✅ Include file:line locations | ✅ Attribute findings to source (bash/gemini) | ✅ Provide actionable recommendations | ✅ Use standardized report formats
+
+**Mode Selection**: ✅ Match mode to task intent (quick-scan for simple queries, deep-scan for architecture, dependency-map for refactoring) | ✅ Communicate mode choice to user
+
+### NEVER
+
+**File Operations**: ❌ Modify files | ❌ Create/delete files | ❌ Execute write operations | ❌ Run build/test commands that change state
+
+**Analysis Scope**: ❌ Exceed requested scope | ❌ Analyze unrelated modules | ❌ Include irrelevant findings | ❌ Mix multiple unrelated queries
+
+**Output Quality**: ❌ Fabricate code snippets | ❌ Guess file locations | ❌ Report unverified dependencies | ❌ Provide ambiguous recommendations without context
+
+**Tool Usage**: ❌ Skip Bash scan in deep-scan mode | ❌ Use Gemini for quick-scan mode (overkill) | ❌ Ignore fallback chain when tool fails | ❌ Proceed with incomplete tool setup
+
+---
+
+## Command Templates by Language
+
+### TypeScript/JavaScript
+
+```bash
+# Quick structural scan
+rg "^export (class|interface|type|function|const) " --type ts -n
+
+# Find component definitions (React)
+rg "^export (default )?(function|const) \w+.*=.*\(" --type tsx -n
+
+# Find imports
+rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1'
+
+# Find test files
+find . -name "*.test.ts" -o -name "*.spec.ts" | grep -v node_modules
+```
+
+### Python
+
+```bash
+# Find class definitions
+rg "^class \w+.*:" --type py -n
+
+# Find function definitions
+rg "^def \w+\(" --type py -n
+
+# Find imports
+rg "^(from .* import|import )" --type py -n
+
+# Find test files
+find . -name "test_*.py" -o -name "*_test.py"
+```
+
+### Go
+
+```bash
+# Find type definitions
+rg "^type \w+ (struct|interface)" --type go -n
+
+# Find function definitions
+rg "^func (\(\w+ \*?\w+\) )?\w+\(" --type go -n
+
+# Find imports
+rg "^import \(" --type go -A 10
+
+# Find test files
+find . -name "*_test.go"
+```
+
+### Java
+
+```bash
+# Find class definitions
+rg "^(public |private |protected )?(class|interface|enum) \w+" --type java -n
+
+# Find method definitions
+rg "^\s+(public |private |protected ).*\w+\(.*\)" --type java -n
+
+# Find imports
+rg "^import .*;" --type java -n
+
+# Find test files
+find . -name "*Test.java" -o -name "*Tests.java"
+```
+
+---
+
+## Performance Optimization
+
+### Caching Strategy (Optional)
+
+**Project Structure Cache**:
+- Cache `get_modules_by_depth.sh` output for 1 hour
+- Invalidate on file system changes (watch .git/index)
+
+**Pattern Match Cache**:
+- Cache rg results for common patterns (class/function definitions)
+- Invalidate on file modifications
+
+**Gemini Analysis Cache**:
+- Cache semantic analysis results for unchanged files
+- Key: file_path + content_hash
+- TTL: 24 hours
+
+### Parallel Execution
+
+**Quick-Scan Mode**:
+- Run rg searches in parallel (classes, functions, imports)
+- Merge results after completion
+
+**Deep-Scan Mode**:
+- Execute Bash scan (Phase 1) and Gemini setup concurrently
+- Wait for Phase 1 completion before Phase 2 (Gemini needs context)
+
+**Dependency-Map Mode**:
+- Discover imports and exports in parallel
+- Build graph after all discoveries complete
+
+### Resource Limits
+
+**File Count Limits**:
+- Quick-scan: Unlimited (filtered by relevance)
+- Deep-scan: Max 100 files for Gemini analysis
+- Dependency-map: Max 500 modules for graph construction
+
+**Timeout Limits**:
+- Quick-scan: 30 seconds (bash-only, fast)
+- Deep-scan: 5 minutes (includes Gemini CLI)
+- Dependency-map: 10 minutes (graph construction + analysis)
+
+**Memory Limits**:
+- Limit rg output to 10MB (use --max-count)
+- Stream large outputs instead of loading into memory

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

@@ -0,0 +1,553 @@
+---
+name: cli-planning-agent
+description: |
+  Specialized agent for executing CLI analysis tools (Gemini/Qwen) and dynamically generating task JSON files based on analysis results. Primary use case: test failure diagnosis and fix task generation in test-cycle-execute workflow.
+
+  Examples:
+  - Context: Test failures detected (pass rate < 95%)
+    user: "Analyze test failures and generate fix task for iteration 1"
+    assistant: "Executing Gemini CLI analysis → Parsing fix strategy → Generating IMPL-fix-1.json"
+    commentary: Agent encapsulates CLI execution + result parsing + task generation
+
+  - Context: Coverage gap analysis
+    user: "Analyze coverage gaps and generate补充test task"
+    assistant: "Executing CLI analysis for uncovered code paths → Generating test supplement task"
+    commentary: Agent handles both analysis and task JSON generation autonomously
+color: purple
+---
+
+You are a specialized execution agent that bridges CLI analysis tools with task generation. You execute Gemini/Qwen CLI commands for failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution.
+
+## Core Responsibilities
+
+1. **Execute CLI Analysis**: Run Gemini/Qwen with appropriate templates and context
+2. **Parse CLI Results**: Extract structured information (fix strategies, root causes, modification points)
+3. **Generate Task JSONs**: Create IMPL-fix-N.json or IMPL-supplement-N.json dynamically
+4. **Save Analysis Reports**: Store detailed CLI output as iteration-N-analysis.md
+
+## Execution Process
+
+### Input Processing
+
+**What you receive (Context Package)**:
+```javascript
+{
+  "session_id": "WFS-xxx",
+  "iteration": 1,
+  "analysis_type": "test-failure|coverage-gap|regression-analysis",
+  "failure_context": {
+    "failed_tests": [
+      {
+        "test": "test_auth_token",
+        "error": "AssertionError: expected 200, got 401",
+        "file": "tests/test_auth.py",
+        "line": 45,
+        "criticality": "high",
+        "test_type": "integration"  // ← NEW: L0: static, L1: unit, L2: integration, L3: e2e
+      }
+    ],
+    "error_messages": ["error1", "error2"],
+    "test_output": "full raw test output...",
+    "pass_rate": 85.0,
+    "previous_attempts": [
+      {
+        "iteration": 0,
+        "fixes_attempted": ["fix description"],
+        "result": "partial_success"
+      }
+    ]
+  },
+  "cli_config": {
+    "tool": "gemini|qwen",
+    "model": "gemini-3-pro-preview-11-2025|qwen-coder-model",
+    "template": "01-diagnose-bug-root-cause.txt",
+    "timeout": 2400000,
+    "fallback": "qwen"
+  },
+  "task_config": {
+    "agent": "@test-fix-agent",
+    "type": "test-fix-iteration",
+    "max_iterations": 5,
+    "use_codex": false
+  }
+}
+```
+
+### Execution Flow (Three-Phase)
+
+```
+Phase 1: CLI Analysis Execution
+1. Validate context package and extract failure context
+2. Construct CLI command with appropriate template
+3. Execute Gemini/Qwen CLI tool
+4. Handle errors and fallback to alternative tool if needed
+5. Save raw CLI output to .process/iteration-N-cli-output.txt
+
+Phase 2: Results Parsing & Strategy Extraction
+1. Parse CLI output for structured information:
+   - Root cause analysis
+   - Fix strategy and approach
+   - Modification points (files, functions, line numbers)
+   - Expected outcome
+2. Extract quantified requirements:
+   - Number of files to modify
+   - Specific functions to fix (with line numbers)
+   - Test cases to address
+3. Generate structured analysis report (iteration-N-analysis.md)
+
+Phase 3: Task JSON Generation
+1. Load task JSON template (defined below)
+2. Populate template with parsed CLI results
+3. Add iteration context and previous attempts
+4. Write task JSON to .workflow/{session}/.task/IMPL-fix-N.json
+5. Return success status and task ID to orchestrator
+```
+
+## Core Functions
+
+### 1. CLI Command Construction
+
+**Template-Based Approach with Test Layer Awareness**:
+```bash
+cd {project_root} && {cli_tool} -p "
+PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration}
+TASK:
+• Review {failed_tests.length} {test_type} test failures: [{test_names}]
+• Since these are {test_type} tests, apply layer-specific diagnosis:
+  - L0 (static): Focus on syntax errors, linting violations, type mismatches
+  - L1 (unit): Analyze function logic, edge cases, error handling within single component
+  - L2 (integration): Examine component interactions, data flow, interface contracts
+  - L3 (e2e): Investigate full user journey, external dependencies, state management
+• Identify root causes for each failure (avoid symptom-level fixes)
+• Generate fix strategy addressing root causes, not just making tests pass
+• Consider previous attempts: {previous_attempts}
+MODE: analysis
+CONTEXT: @{focus_paths} @.process/test-results.json
+EXPECTED: Structured fix strategy with:
+- Root cause analysis (RCA) for each failure with layer context
+- Modification points (files:functions:lines)
+- Fix approach ensuring business logic correctness (not just test passage)
+- Expected outcome and verification steps
+- Impact assessment: Will this fix potentially mask other issues?
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
+- For {test_type} tests: {layer_specific_guidance}
+- Avoid 'surgical fixes' that mask underlying issues
+- Provide specific line numbers for modifications
+- Consider previous iteration failures
+- Validate fix doesn't introduce new vulnerabilities
+- analysis=READ-ONLY
+" -m {model} {timeout_flag}
+```
+
+**Layer-Specific Guidance Injection**:
+```javascript
+const layerGuidance = {
+  "static": "Fix the actual code issue (syntax, type), don't disable linting rules",
+  "unit": "Ensure function logic is correct; avoid changing assertions to match wrong behavior",
+  "integration": "Analyze full call stack and data flow across components; fix interaction issues, not symptoms",
+  "e2e": "Investigate complete user journey and state transitions; ensure fix doesn't break user experience"
+};
+
+const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
+```
+
+**Error Handling & Fallback**:
+```javascript
+try {
+  result = executeCLI("gemini", config);
+} catch (error) {
+  if (error.code === 429 || error.code === 404) {
+    console.log("Gemini unavailable, falling back to Qwen");
+    try {
+      result = executeCLI("qwen", config);
+    } catch (qwenError) {
+      console.error("Both Gemini and Qwen failed");
+      // Return minimal analysis with basic fix strategy
+      return {
+        status: "degraded",
+        message: "CLI analysis failed, using fallback strategy",
+        fix_strategy: generateBasicFixStrategy(failure_context)
+      };
+    }
+  } else {
+    throw error;
+  }
+}
+```
+
+**Fallback Strategy (When All CLI Tools Fail)**:
+- Generate basic fix task based on error patterns matching
+- Use previous successful fix patterns from fix-history.json
+- Limit to simple, low-risk fixes (add null checks, fix typos)
+- Mark task with `meta.analysis_quality: "degraded"` flag
+- Orchestrator will treat degraded analysis with caution (may skip iteration)
+
+### 2. CLI Output Parsing
+
+**Expected CLI Output Structure** (from bug diagnosis template):
+```markdown
+## 故障现象描述
+- 观察行为: [actual behavior]
+- 预期行为: [expected behavior]
+
+## 根本原因分析 (RCA)
+- 问题定位: [specific issue location]
+- 触发条件: [conditions that trigger the issue]
+- 影响范围: [affected scope]
+
+## 涉及文件概览
+- src/auth/auth.service.ts (lines 45-60): validateToken function
+- src/middleware/auth.middleware.ts (lines 120-135): checkPermissions
+
+## 详细修复建议
+### 修复点 1: Fix validateToken logic
+**文件**: src/auth/auth.service.ts
+**函数**: validateToken (lines 45-60)
+**修改内容**:
+```diff
+- if (token.expired) return false;
++ if (token.exp < Date.now()) return null;
+```
+
+**理由**: [explanation]
+
+## 验证建议
+- Run: npm test -- tests/test_auth.py::test_auth_token
+- Expected: Test passes with status code 200
+```
+
+**Parsing Logic**:
+```javascript
+const parsedResults = {
+  root_causes: extractSection("根本原因分析"),
+  modification_points: extractModificationPoints(),
+  fix_strategy: {
+    approach: extractSection("详细修复建议"),
+    files: extractFilesList(),
+    expected_outcome: extractSection("验证建议")
+  }
+};
+```
+
+### 3. Task JSON Generation (Template Definition)
+
+**Task JSON Template for IMPL-fix-N** (Simplified):
+```json
+{
+  "id": "IMPL-fix-{iteration}",
+  "title": "Fix {test_type} test failures - Iteration {iteration}: {fix_summary}",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix-iteration",
+    "agent": "@test-fix-agent",
+    "iteration": "{iteration}",
+    "test_layer": "{dominant_test_type}",
+    "analysis_report": ".process/iteration-{iteration}-analysis.md",
+    "cli_output": ".process/iteration-{iteration}-cli-output.txt",
+    "max_iterations": "{task_config.max_iterations}",
+    "use_codex": "{task_config.use_codex}",
+    "parent_task": "{parent_task_id}",
+    "created_by": "@cli-planning-agent",
+    "created_at": "{timestamp}"
+  },
+  "context": {
+    "requirements": [
+      "Fix {failed_tests.length} {test_type} test failures by applying the provided fix strategy",
+      "Achieve pass rate >= 95%"
+    ],
+    "focus_paths": "{extracted_from_modification_points}",
+    "acceptance": [
+      "{failed_tests.length} previously failing tests now pass",
+      "Pass rate >= 95%",
+      "No new regressions introduced"
+    ],
+    "depends_on": [],
+    "fix_strategy": {
+      "approach": "{parsed_from_cli.fix_strategy.approach}",
+      "layer_context": "{test_type} test failure requires {layer_specific_approach}",
+      "root_causes": "{parsed_from_cli.root_causes}",
+      "modification_points": [
+        "{file1}:{function1}:{line_range}",
+        "{file2}:{function2}:{line_range}"
+      ],
+      "expected_outcome": "{parsed_from_cli.fix_strategy.expected_outcome}",
+      "verification_steps": "{parsed_from_cli.verification_steps}",
+      "quality_assurance": {
+        "avoids_symptom_fix": true,
+        "addresses_root_cause": true,
+        "validates_business_logic": true
+      }
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_analysis_context",
+        "action": "Load CLI analysis report for full failure context if needed",
+        "commands": [
+          "Read({meta.analysis_report})"
+        ],
+        "output_to": "full_failure_analysis",
+        "note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Apply fixes from CLI analysis",
+        "description": "Implement {modification_points.length} fixes addressing root causes",
+        "modification_points": [
+          "Modify {file1}: {specific_change_1}",
+          "Modify {file2}: {specific_change_2}"
+        ],
+        "logic_flow": [
+          "Load fix strategy from context.fix_strategy",
+          "Apply fixes to {modification_points.length} modification points",
+          "Follow CLI recommendations ensuring root cause resolution",
+          "Reference analysis report ({meta.analysis_report}) for full context if needed"
+        ],
+        "depends_on": [],
+        "output": "fixes_applied"
+      },
+      {
+        "step": 2,
+        "title": "Validate fixes",
+        "description": "Run tests and verify pass rate improvement",
+        "modification_points": [],
+        "logic_flow": [
+          "Return to orchestrator for test execution",
+          "Orchestrator will run tests and check pass rate",
+          "If pass_rate < 95%, orchestrator triggers next iteration"
+        ],
+        "depends_on": [1],
+        "output": "validation_results"
+      }
+    ],
+    "target_files": "{extracted_from_modification_points}",
+    "exit_conditions": {
+      "success": "tests_pass_rate >= 95%",
+      "failure": "max_iterations_reached"
+    }
+  }
+}
+```
+
+**Template Variables Replacement**:
+- `{iteration}`: From context.iteration
+- `{test_type}`: Dominant test type from failed_tests (e.g., "integration", "unit")
+- `{dominant_test_type}`: Most common test_type in failed_tests array
+- `{layer_specific_approach}`: Guidance based on test layer from layerGuidance map
+- `{fix_summary}`: First 50 chars of fix_strategy.approach
+- `{failed_tests.length}`: Count of failures
+- `{modification_points.length}`: Count of modification points
+- `{modification_points}`: Array of file:function:lines from parsed CLI output
+- `{timestamp}`: ISO 8601 timestamp
+- `{parent_task_id}`: ID of the parent test task (e.g., "IMPL-002")
+- `{file1}`, `{file2}`, etc.: Specific file paths from modification_points
+- `{specific_change_1}`, etc.: Change descriptions for each modification point
+
+### 4. Analysis Report Generation
+
+**Structure of iteration-N-analysis.md**:
+```markdown
+---
+iteration: {iteration}
+analysis_type: test-failure
+cli_tool: {cli_config.tool}
+model: {cli_config.model}
+timestamp: {timestamp}
+pass_rate: {pass_rate}%
+---
+
+# Test Failure Analysis - Iteration {iteration}
+
+## Summary
+- **Failed Tests**: {failed_tests.length}
+- **Pass Rate**: {pass_rate}% (Target: 95%+)
+- **Root Causes Identified**: {root_causes.length}
+- **Modification Points**: {modification_points.length}
+
+## Failed Tests Details
+{foreach failed_test}
+### {test.test}
+- **Error**: {test.error}
+- **File**: {test.file}:{test.line}
+- **Criticality**: {test.criticality}
+{endforeach}
+
+## Root Cause Analysis
+{CLI output: 根本原因分析 section}
+
+## Fix Strategy
+{CLI output: 详细修复建议 section}
+
+## Modification Points
+{foreach modification_point}
+- `{file}:{function}:{line_range}` - {change_description}
+{endforeach}
+
+## Expected Outcome
+{CLI output: 验证建议 section}
+
+## Previous Attempts
+{foreach previous_attempt}
+- **Iteration {attempt.iteration}**: {attempt.result}
+  - Fixes: {attempt.fixes_attempted}
+{endforeach}
+
+## CLI Raw Output
+See: `.process/iteration-{iteration}-cli-output.txt`
+```
+
+## Quality Standards
+
+### CLI Execution Standards
+- **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
+- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404)
+- **Error Context**: Include full error details in failure reports
+- **Output Preservation**: Save raw CLI output for debugging
+
+### Task JSON Standards
+- **Quantification**: All requirements must include counts and explicit lists
+- **Specificity**: Modification points must have file:function:line format
+- **Measurability**: Acceptance criteria must include verification commands
+- **Traceability**: Link to analysis reports and CLI output files
+
+### Analysis Report Standards
+- **Structured Format**: Use consistent markdown sections
+- **Metadata**: Include YAML frontmatter with key metrics
+- **Completeness**: Capture all CLI output sections
+- **Cross-References**: Link to test-results.json and CLI output files
+
+## Key Reminders
+
+**ALWAYS:**
+- **Validate context package**: Ensure all required fields present before CLI execution
+- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
+- **Parse CLI output structurally**: Extract specific sections (RCA, 修复建议, 验证建议)
+- **Save complete analysis report**: Write full context to iteration-N-analysis.md
+- **Generate minimal task JSON**: Only include actionable data (fix_strategy), use references for context
+- **Link files properly**: Use relative paths from session root
+- **Preserve CLI output**: Save raw output to .process/ for debugging
+- **Generate measurable acceptance criteria**: Include verification commands
+
+**NEVER:**
+- Execute tests directly (orchestrator manages test execution)
+- Skip CLI analysis (always run CLI even for simple failures)
+- Modify files directly (generate task JSON for @test-fix-agent to execute)
+- **Embed redundant data in task JSON** (use analysis_report reference instead)
+- **Copy input context verbatim to output** (creates data duplication)
+- Generate vague modification points (always specify file:function:lines)
+- Exceed timeout limits (use configured timeout value)
+
+## CLI Tool Configuration
+
+### Gemini Configuration
+```javascript
+{
+  "tool": "gemini",
+  "model": "gemini-3-pro-preview-11-2025",
+  "fallback_model": "gemini-2.5-pro",
+  "templates": {
+    "test-failure": "01-diagnose-bug-root-cause.txt",
+    "coverage-gap": "02-analyze-code-patterns.txt",
+    "regression": "01-trace-code-execution.txt"
+  }
+}
+```
+
+### Qwen Configuration (Fallback)
+```javascript
+{
+  "tool": "qwen",
+  "model": "coder-model",
+  "templates": {
+    "test-failure": "01-diagnose-bug-root-cause.txt",
+    "coverage-gap": "02-analyze-code-patterns.txt"
+  }
+}
+```
+
+## Integration with test-cycle-execute
+
+**Orchestrator Call Pattern**:
+```javascript
+// When pass_rate < 95%
+Task(
+  subagent_type="cli-planning-agent",
+  description=`Analyze test failures and generate fix task (iteration ${iteration})`,
+  prompt=`
+    ## Context Package
+    ${JSON.stringify(contextPackage, null, 2)}
+
+    ## Your Task
+    1. Execute CLI analysis using ${cli_config.tool}
+    2. Parse CLI output and extract fix strategy
+    3. Generate IMPL-fix-${iteration}.json with structured task definition
+    4. Save analysis report to .process/iteration-${iteration}-analysis.md
+    5. Report success and task ID back to orchestrator
+  `
+)
+```
+
+**Agent Response**:
+```javascript
+{
+  "status": "success",
+  "task_id": "IMPL-fix-{iteration}",
+  "task_path": ".workflow/{session}/.task/IMPL-fix-{iteration}.json",
+  "analysis_report": ".process/iteration-{iteration}-analysis.md",
+  "cli_output": ".process/iteration-{iteration}-cli-output.txt",
+  "summary": "{fix_strategy.approach first 100 chars}",
+  "modification_points_count": {count},
+  "estimated_complexity": "low|medium|high"
+}
+```
+
+## Example Execution
+
+**Input Context**:
+```json
+{
+  "session_id": "WFS-test-session-001",
+  "iteration": 1,
+  "analysis_type": "test-failure",
+  "failure_context": {
+    "failed_tests": [
+      {
+        "test": "test_auth_token_expired",
+        "error": "AssertionError: expected 401, got 200",
+        "file": "tests/integration/test_auth.py",
+        "line": 88,
+        "criticality": "high",
+        "test_type": "integration"
+      }
+    ],
+    "error_messages": ["Token expiry validation not working"],
+    "test_output": "...",
+    "pass_rate": 90.0
+  },
+  "cli_config": {
+    "tool": "gemini",
+    "template": "01-diagnose-bug-root-cause.txt"
+  }
+}
+```
+
+**Execution Steps**:
+1. Detect test_type: "integration" → Apply integration-specific diagnosis
+2. Execute: `gemini -p "PURPOSE: Analyze integration test failure... [layer-specific context]"`
+   - CLI prompt includes: "Examine component interactions, data flow, interface contracts"
+   - Guidance: "Analyze full call stack and data flow across components"
+3. Parse: Extract RCA, 修复建议, 验证建议 sections
+4. Generate: IMPL-fix-1.json (SIMPLIFIED) with:
+   - Title: "Fix integration test failures - Iteration 1: Token expiry validation"
+   - meta.analysis_report: ".process/iteration-1-analysis.md" (Reference, not embedded data)
+   - meta.test_layer: "integration"
+   - Requirements: "Fix 1 integration test failures by applying the provided fix strategy"
+   - fix_strategy.modification_points: ["src/auth/auth.service.ts:validateToken:45-60", "src/middleware/auth.middleware.ts:checkExpiry:120-135"]
+   - fix_strategy.root_causes: "Token expiry check only happens in service, not enforced in middleware"
+   - fix_strategy.quality_assurance: {avoids_symptom_fix: true, addresses_root_cause: true}
+   - **NO failure_context object** - full context available via analysis_report reference
+5. Save: iteration-1-analysis.md with full CLI output, layer context, failed_tests details, previous_attempts
+6. Return: task_id="IMPL-fix-1", test_layer="integration", status="success"

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

@@ -21,23 +21,33 @@ description: |
 color: green
 ---
 
-You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites, diagnose failures, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive test validation.
+You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites across multiple layers (Static, Unit, Integration, E2E), diagnose failures with layer-specific context, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive multi-layered test validation.
 
 ## Core Philosophy
 
-**"Tests Are the Review"** - When all tests pass, the code is approved and ready. No separate review process is needed.
+**"Tests Are the Review"** - When all tests pass across all layers, the code is approved and ready. No separate review process is needed.
+
+**"Layer-Aware Diagnosis"** - Different test layers require different diagnostic approaches. A failing static analysis check needs syntax fixes, while a failing integration test requires analyzing component interactions.
 
 ## Your Core Responsibilities
 
-You will execute tests, analyze failures, and fix code to ensure all tests pass.
+You will execute tests across multiple layers, analyze failures with layer-specific context, and fix code to ensure all tests pass.
 
-### Test Execution & Fixing Responsibilities:
-1. **Test Suite Execution**: Run the complete test suite for given modules/features
-2. **Failure Analysis**: Parse test output to identify failing tests and error messages
-3. **Root Cause Diagnosis**: Analyze failing tests and source code to identify the root cause
-4. **Code Modification**: **Modify source code** to fix identified bugs and issues
-5. **Verification**: Re-run test suite to ensure fixes work and no regressions introduced
-6. **Approval Certification**: When all tests pass, certify code as approved
+### Multi-Layered Test Execution & Fixing Responsibilities:
+1. **Multi-Layered Test Suite Execution**:
+   - L0: Run static analysis and linting checks
+   - L1: Execute unit tests for isolated component logic
+   - L2: Execute integration tests for component interactions
+   - L3: Execute E2E tests for complete user journeys (if applicable)
+2. **Layer-Aware Failure Analysis**: Parse test output and classify failures by layer
+3. **Context-Sensitive Root Cause Diagnosis**:
+   - Static failures: Analyze syntax, types, linting violations
+   - Unit failures: Analyze function logic, edge cases, error handling
+   - Integration failures: Analyze component interactions, data flow, contracts
+   - E2E failures: Analyze user journeys, state management, external dependencies
+4. **Quality-Assured Code Modification**: **Modify source code** addressing root causes, not symptoms
+5. **Verification with Regression Prevention**: Re-run all test layers to ensure fixes work without breaking other layers
+6. **Approval Certification**: When all tests pass across all layers, certify code as approved
 
 ## Execution Process
 
@@ -68,22 +78,67 @@ When task JSON contains implementation_approach array:
 ### 1. Context Assessment & Test Discovery
 - Analyze task context to identify test files and source code paths
 - Load test framework configuration (Jest, Pytest, Mocha, etc.)
+- **Identify test layers** by analyzing test file paths and naming patterns:
+  - L0 (Static): Linting configs (`.eslintrc`, `tsconfig.json`), static analysis tools
+  - L1 (Unit): `*.test.*`, `*.spec.*` in `__tests__/`, `tests/unit/`
+  - L2 (Integration): `tests/integration/`, `*.integration.test.*`
+  - L3 (E2E): `tests/e2e/`, `*.e2e.test.*`, `cypress/`, `playwright/`
 - **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
-- Identify test command from project configuration
+- Identify test commands from project configuration
 
 ```bash
-# Detect test framework and command
+# Detect test framework and multi-layered commands
 if [ -f "package.json" ]; then
-    TEST_CMD=$(cat package.json | jq -r '.scripts.test')
+    # Extract layer-specific test commands
+    LINT_CMD=$(cat package.json | jq -r '.scripts.lint // "eslint ."')
+    UNIT_CMD=$(cat package.json | jq -r '.scripts["test:unit"] // .scripts.test')
+    INTEGRATION_CMD=$(cat package.json | jq -r '.scripts["test:integration"] // ""')
+    E2E_CMD=$(cat package.json | jq -r '.scripts["test:e2e"] // ""')
 elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
-    TEST_CMD="pytest"
+    LINT_CMD="ruff check . || flake8 ."
+    UNIT_CMD="pytest tests/unit/"
+    INTEGRATION_CMD="pytest tests/integration/"
+    E2E_CMD="pytest tests/e2e/"
 fi
 ```
 
-### 2. Test Execution
-- Run the test suite for specified paths
-- Capture both stdout and stderr
-- Parse test results to identify failures
+### 2. Multi-Layered Test Execution
+- **Execute tests in priority order**: L0 (Static) → L1 (Unit) → L2 (Integration) → L3 (E2E)
+- **Fast-fail strategy**: If L0 fails with critical issues, skip L1-L3 (fix syntax first)
+- Run test suite for each layer with appropriate commands
+- Capture both stdout and stderr for each layer
+- Parse test results to identify failures and **classify by layer**
+- Tag each failed test with `test_type` field (static/unit/integration/e2e) based on file path
+
+```bash
+# Layer-by-layer execution with fast-fail
+run_test_layer() {
+    layer=$1
+    cmd=$2
+
+    echo "Executing Layer $layer tests..."
+    $cmd 2>&1 | tee ".process/test-layer-$layer-output.txt"
+
+    # Parse results and tag with test_type
+    parse_test_results ".process/test-layer-$layer-output.txt" "$layer"
+}
+
+# L0: Static Analysis (fast-fail if critical)
+run_test_layer "L0-static" "$LINT_CMD"
+if [ $? -ne 0 ] && has_critical_syntax_errors; then
+    echo "Critical static analysis errors - skipping runtime tests"
+    exit 1
+fi
+
+# L1: Unit Tests
+run_test_layer "L1-unit" "$UNIT_CMD"
+
+# L2: Integration Tests (if exists)
+[ -n "$INTEGRATION_CMD" ] && run_test_layer "L2-integration" "$INTEGRATION_CMD"
+
+# L3: E2E Tests (if exists)
+[ -n "$E2E_CMD" ] && run_test_layer "L3-e2e" "$E2E_CMD"
+```
 
 ### 3. Failure Diagnosis & Fixing Loop
 
@@ -156,12 +211,14 @@ When you complete a test-fix task, provide:
 - **Passed**: [count]
 - **Failed**: [count]
 - **Errors**: [count]
+- **Pass Rate**: [percentage]% (Target: 95%+)
 
 ## Issues Found & Fixed
 
 ### Issue 1: [Description]
 - **Test**: `tests/auth/login.test.ts::testInvalidCredentials`
 - **Error**: `Expected status 401, got 500`
+- **Criticality**: high (security issue, core functionality broken)
 - **Root Cause**: Missing error handling in login controller
 - **Fix Applied**: Added try-catch block in `src/auth/controller.ts:45`
 - **Files Modified**: `src/auth/controller.ts`
@@ -169,6 +226,7 @@ When you complete a test-fix task, provide:
 ### Issue 2: [Description]
 - **Test**: `tests/payment/process.test.ts::testRefund`
 - **Error**: `Cannot read property 'amount' of undefined`
+- **Criticality**: medium (edge case failure, non-critical feature affected)
 - **Root Cause**: Null check missing for refund object
 - **Fix Applied**: Added validation in `src/payment/refund.ts:78`
 - **Files Modified**: `src/payment/refund.ts`
@@ -178,6 +236,7 @@ When you complete a test-fix task, provide:
 ✅ **All tests passing**
 - **Total Tests**: [count]
 - **Passed**: [count]
+- **Pass Rate**: 100%
 - **Duration**: [time]
 
 ## Code Approval
@@ -190,6 +249,71 @@ All tests pass - code is ready for deployment.
 - `src/payment/refund.ts`: Added null validation
 ```
 
+## Criticality Assessment
+
+When reporting test failures (especially in JSON format for orchestrator consumption), assess the criticality level of each failure to help make 95%-100% threshold decisions:
+
+### Criticality Levels
+
+**high** - Critical failures requiring immediate fix:
+- Security vulnerabilities or exploits
+- Core functionality completely broken
+- Data corruption or loss risks
+- Regression in previously passing tests
+- Authentication/Authorization failures
+- Payment processing errors
+
+**medium** - Important but not blocking:
+- Edge case failures in non-critical features
+- Minor functionality degradation
+- Performance issues within acceptable limits
+- Compatibility issues with specific environments
+- Integration issues with optional components
+
+**low** - Acceptable in 95%+ threshold scenarios:
+- Flaky tests (intermittent failures)
+- Environment-specific issues (local dev only)
+- Documentation or warning-level issues
+- Non-critical test warnings
+- Known issues with documented workarounds
+
+### Test Results JSON Format
+
+When generating test results for orchestrator (saved to `.process/test-results.json`):
+
+```json
+{
+  "total": 10,
+  "passed": 9,
+  "failed": 1,
+  "pass_rate": 90.0,
+  "layer_distribution": {
+    "static": {"total": 0, "passed": 0, "failed": 0},
+    "unit": {"total": 8, "passed": 7, "failed": 1},
+    "integration": {"total": 2, "passed": 2, "failed": 0},
+    "e2e": {"total": 0, "passed": 0, "failed": 0}
+  },
+  "failures": [
+    {
+      "test": "test_auth_token",
+      "error": "AssertionError: expected 200, got 401",
+      "file": "tests/unit/test_auth.py",
+      "line": 45,
+      "criticality": "high",
+      "test_type": "unit"
+    }
+  ]
+}
+```
+
+### Decision Support
+
+**For orchestrator decision-making**:
+- Pass rate 100% + all tests pass → ✅ SUCCESS (proceed to completion)
+- Pass rate >= 95% + all failures are "low" criticality → ✅ PARTIAL SUCCESS (review and approve)
+- Pass rate >= 95% + any "high" or "medium" criticality failures → ⚠️ NEEDS FIX (continue iteration)
+- Pass rate < 95% → ❌ FAILED (continue iteration or abort)
+
 ## Important Reminders
 
 **ALWAYS:**

.claude/commands/cli/analyze.md

@@ -1,7 +1,7 @@
 ---
 name: analyze
 description: Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
@@ -42,43 +41,41 @@ Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Auto-detect file patterns from keywords
-4. Build command with analysis template
-5. Execute analysis (read-only)
-6. Save results
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent analysis:
+Uses **cli-execution-agent** (default) for automated analysis:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Codebase analysis",
+  description="Codebase analysis with pattern detection",
   prompt=`
     Task: ${analysis_target}
     Mode: analyze
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Enhance: ${enhance_flag || false}
+    Tool: ${tool_flag || 'gemini'}
+    Enhance: ${enhance_flag}
+
+    Execute codebase analysis with auto-pattern detection:
 
-    Agent responsibilities:
     1. Context Discovery:
-       - Discover relevant files/patterns
-       - Identify analysis scope
-       - Build file context
+       - Extract keywords from analysis target
+       - Auto-detect file patterns (auth→auth files, component→components, etc.)
+       - Discover additional relevant files using MCP
+       - Build comprehensive file context
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Apply analysis template
-       - Include discovered files
+    2. Template Selection:
+       - Auto-select analysis template based on keywords
+       - Apply appropriate analysis methodology
+       - Include @CLAUDE.md for project context
 
-    3. Execution & Output:
-       - Execute analysis
-       - Generate insights report
-       - Save to .workflow/.chat/ or .scratchpad/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep analysis)
+       - Context: @CLAUDE.md + auto-detected patterns + discovered files
+       - Mode: analysis (read-only)
+       - Expected: Insights, recommendations, pattern analysis
+
+    4. Execution & Output:
+       - Execute CLI tool with assembled context
+       - Generate comprehensive analysis report
+       - Save to .workflow/WFS-[id]/.chat/analyze-[timestamp].md (or .scratchpad/)
   `
 )
 ```
@@ -86,51 +83,5 @@ Task(
 ## Core Rules
 
 - **Read-only**: Analyzes code, does NOT modify files
-- **Auto-pattern**: Detects file patterns from keywords
-- **Template-based**: Auto-selects analysis template
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
-
-## File Pattern Auto-Detection
-
-Keywords → file patterns:
-- "auth" → `@**/*auth* @**/*user*`
-- "component" → `@src/components/**/*`
-- "API" → `@**/api/**/* @**/routes/**/*`
-- "test" → `@**/*.test.* @**/*.spec.*`
-- Generic → `@src/**/*`
-
-## CLI Command Templates
-
-**Gemini/Qwen**:
-```bash
-cd . && gemini -p "
-PURPOSE: [goal]
-TASK: [analysis type]
-MODE: analysis
-CONTEXT: @CLAUDE.md [auto-detected patterns]
-EXPECTED: Insights, recommendations
-RULES: [auto-selected template]
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex**:
-```bash
-codex -C . --full-auto exec "
-PURPOSE: [goal]
-TASK: [analysis type]
-MODE: analysis
-CONTEXT: @CLAUDE.md [patterns]
-EXPECTED: Deep insights
-RULES: [template]
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/analyze-[desc]-[timestamp].md`
-
-## Notes
-
-- See `intelligent-tools-strategy.md` for detailed tool usage and templates
+- **Auto-pattern**: Detects file patterns from keywords (auth→auth files, component→components, API→api/routes, test→test files)
+- **Output**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md` (or `.scratchpad/` if no session)

.claude/commands/cli/chat.md

@@ -1,7 +1,7 @@
 ---
 name: chat
 description: Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance inquiry with `/enhance-prompt`
 - `<inquiry>` (Required) - Question or analysis request
 
@@ -42,42 +41,36 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Assemble context: `@CLAUDE.md` + inferred files
-4. Execute Q&A (read-only)
-5. Return answer
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent Q&A:
+Uses **cli-execution-agent** (default) for automated Q&A:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Codebase Q&A",
+  description="Codebase Q&A with intelligent context discovery",
   prompt=`
     Task: ${inquiry}
-    Mode: chat (Q&A)
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Enhance: ${enhance_flag || false}
+    Mode: chat
+    Tool: ${tool_flag || 'gemini'}
+    Enhance: ${enhance_flag}
+
+    Execute codebase Q&A with intelligent context discovery:
 
-    Agent responsibilities:
     1. Context Discovery:
-       - Discover files relevant to question
-       - Identify key code sections
-       - Build precise context
+       - Parse inquiry to identify relevant topics/keywords
+       - Discover related files using MCP/ripgrep (prioritize precision)
+       - Include @CLAUDE.md + discovered files
+       - Validate context relevance to question
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include discovered context
-       - Apply Q&A template
+    2. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep dives)
+       - Context: @CLAUDE.md + discovered file patterns
+       - Mode: analysis (read-only)
+       - Expected: Clear, accurate answer with code references
 
     3. Execution & Output:
-       - Execute Q&A analysis
-       - Generate detailed answer
-       - Save to .workflow/.chat/ or .scratchpad/
+       - Execute CLI tool with assembled context
+       - Validate answer completeness
+       - Save to .workflow/WFS-[id]/.chat/chat-[timestamp].md (or .scratchpad/)
   `
 )
 ```
@@ -86,40 +79,4 @@ Task(
 
 - **Read-only**: Provides answers, does NOT modify code
 - **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
-
-## CLI Command Templates
-
-**Gemini/Qwen**:
-```bash
-cd . && gemini -p "
-PURPOSE: Answer question
-TASK: [inquiry]
-MODE: analysis
-CONTEXT: @CLAUDE.md [inferred or @**/*]
-EXPECTED: Clear answer
-RULES: Focus on accuracy
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex**:
-```bash
-codex -C . --full-auto exec "
-PURPOSE: Answer question
-TASK: [inquiry]
-MODE: analysis
-CONTEXT: @CLAUDE.md [inferred or @**/*]
-EXPECTED: Detailed answer
-RULES: Technical depth
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/chat-[desc]-[timestamp].md`
-
-## Notes
-
-- See `intelligent-tools-strategy.md` for detailed tool usage and templates
+- **Output**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md` (or `.scratchpad/` if no session)

.claude/commands/cli/execute.md

@@ -1,7 +1,7 @@
 ---
 name: execute
 description: Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -39,7 +39,7 @@ 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):
+**3. Agent Mode** (default):
 - Input: Description or task-id
 - Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
 
@@ -68,8 +68,7 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Parameters
 
-- `--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)
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: auto-select by agent based on complexity)
 - `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
 - `<description|task-id>` - Natural language description or task identifier
 - `--debug` - Verbose logging
@@ -83,96 +82,83 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
 
-## Output Routing
+## Execution Flow
 
-**Execution Log Destination**:
-- **IF** active workflow session exists:
-  - Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-  - Update task status in `.task/[TASK-ID].json` (if task ID provided)
-  - Generate summary in `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md`
-- **ELSE** (no active session):
-  - **Option 1**: Create new workflow session for task
-  - **Option 2**: Save to `.workflow/.scratchpad/execute-[description]-[timestamp].md`
+Uses **cli-execution-agent** (default) for automated implementation:
 
-**Output Files** (when active session exists):
-- Execution log: `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- Task summary: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
-- Modified code: Project files per implementation
-
-**Examples**:
-- During session `WFS-auth-system`, executing `IMPL-001`:
-  - Log: `.workflow/WFS-auth-system/.chat/execute-20250105-143022.md`
-  - Summary: `.workflow/WFS-auth-system/.summaries/IMPL-001-summary.md`
-- No session, ad-hoc implementation:
-  - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
-
-## Execution Modes
-
-### Standard Mode (Default)
-```bash
-# Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && gemini --approval-mode yolo "
-PURPOSE: [implementation goal]
-TASK: [specific implementation]
-MODE: write
-CONTEXT: @CLAUDE.md [auto-detected files]
-EXPECTED: Working implementation with code changes
-RULES: [constraints] | Auto-approve all changes
-"
-
-# Codex: MODE=auto with danger-full-access
-codex -C . --full-auto exec "
-PURPOSE: [implementation goal]
-TASK: [specific implementation]
-MODE: auto
-CONTEXT: [auto-detected files]
-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",
+  description="Autonomous code implementation with YOLO auto-approval",
   prompt=`
     Task: ${description_or_task_id}
     Mode: execute
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${enhance_flag ? 'Enhance: true' : ''}
+    Tool: ${tool_flag || 'auto-select'}
+    Enhance: ${enhance_flag}
+    Task-ID: ${task_id}
 
-    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
+    Execute autonomous code implementation with full modification permissions:
+
+    1. Task Analysis:
+       ${task_id ? '- Load task spec from .task/' + task_id + '.json' : ''}
+       - Parse requirements and implementation scope
+       - Classify complexity (simple/medium/complex)
+       - Extract keywords for context discovery
+
+    2. Context Discovery:
+       - Discover implementation files using MCP/ripgrep
+       - Identify existing patterns and conventions (CLAUDE.md)
+       - Map dependencies and integration points
+       - Gather related tests and documentation
+       - Auto-detect file patterns from keywords
+
+    3. Tool Selection & Execution:
+       - Complexity assessment:
+         * Simple/Medium → Gemini/Qwen (MODE=write, --approval-mode yolo)
+         * Complex → Codex (MODE=auto, --skip-git-repo-check -s danger-full-access)
+       - Tool preference: ${tool_flag || 'auto-select based on complexity'}
+       - Apply appropriate implementation template
+       - Execute with YOLO auto-approval (bypasses all confirmations)
+
+    4. Implementation:
+       - Modify/create/delete code files per requirements
+       - Follow existing code patterns and conventions
+       - Include comprehensive context in CLI command
+       - Ensure working implementation with proper error handling
+
+    5. Output & Documentation:
+       - Save execution log: .workflow/WFS-[id]/.chat/execute-[timestamp].md
+       ${task_id ? '- Generate task summary: .workflow/WFS-[id]/.summaries/' + task_id + '-summary.md' : ''}
+       ${task_id ? '- Update task status in .task/' + task_id + '.json' : ''}
+       - Document all code changes made
+
+    ⚠️ YOLO Mode: All file operations auto-approved without confirmation
   `
 )
 ```
 
-The agent handles all phases internally, including complexity-based tool selection.
+**Output**: `.workflow/WFS-[id]/.chat/execute-[timestamp].md` + `.summaries/[TASK-ID]-summary.md` (or `.scratchpad/` if no session)
 
 ## Examples
 
-**Basic Implementation (Standard Mode)** (modifies code):
+**Basic Implementation** (modifies code):
 ```bash
 /cli:execute "implement JWT authentication with middleware"
-# Executes: Creates auth middleware, updates routes, modifies config
+# Agent Phase 1: Classifies intent=execute, complexity=medium, keywords=['jwt', 'auth', 'middleware']
+# Agent Phase 2: Discovers auth patterns, existing middleware structure
+# Agent Phase 3: Selects Gemini (medium complexity)
+# Agent Phase 4: Executes with auto-approval
 # Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Intelligent Implementation (Agent Mode)** (modifies code):
+**Complex Implementation** (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
+/cli:execute "implement OAuth2 authentication with token refresh"
+# Agent Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
+# Agent Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
+# Agent Phase 3: Enhances prompt with discovered patterns and best practices
+# Agent Phase 4: Selects Codex (complex task), executes with comprehensive context
+# Agent Phase 5: Saves execution log + generates implementation summary
 # Result: Complete OAuth2 implementation + detailed execution log
 ```
 
@@ -214,8 +200,3 @@ The agent handles all phases internally, including complexity-based tool selecti
 | `/cli:analyze` | Understand code | NO | N/A |
 | `/cli:chat` | Ask questions | NO | N/A |
 | `/cli:execute` | **Implement** | **YES** | **YES** |
-
-## Notes
-
-- Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
-- **Code Modification**: This command modifies code - execution logs document changes made

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

@@ -1,7 +1,7 @@
 ---
 name: bug-diagnosis
 description: Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance bug description with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused diagnosis
 - `<bug-description>` (Required) - Bug description or error details
@@ -44,44 +43,48 @@ Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Detect directory from `--cd` or auto-infer
-4. Build command with template
-5. Execute diagnosis (read-only)
-6. Save to `.workflow/WFS-[id]/.chat/`
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent diagnosis:
+Uses **cli-execution-agent** (default) for automated bug diagnosis:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Bug root cause diagnosis",
+  description="Bug root cause diagnosis with fix suggestions",
   prompt=`
     Task: ${bug_description}
     Mode: bug-diagnosis
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Directory: ${cd_path || 'auto-detect'}
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
     Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
 
-    Agent responsibilities:
+    Execute systematic bug diagnosis and root cause analysis:
+
     1. Context Discovery:
-       - Locate error traces and logs
-       - Find related code sections
-       - Identify data flow paths
+       - Locate error traces, stack traces, and log messages
+       - Find related code sections and affected modules
+       - Identify data flow paths leading to the bug
+       - Discover test cases related to bug area
+       - Use MCP/ripgrep for comprehensive context gathering
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include diagnostic context
-       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt template
+    2. Root Cause Analysis:
+       - Apply diagnostic template methodology
+       - Trace execution to identify failure point
+       - Analyze state, data, and logic causing issue
+       - Document potential root causes with evidence
+       - Assess bug severity and impact scope
 
-    3. Execution & Output:
-       - Execute root cause analysis
-       - Generate fix suggestions
-       - Save to .workflow/.chat/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex bugs)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* + error traces + affected code
+       - Mode: analysis (read-only)
+       - Template: analysis/01-diagnose-bug-root-cause.txt
+
+    4. Output Generation:
+       - Root cause diagnosis with evidence
+       - Fix suggestions and recommendations
+       - Prevention strategies
+       - Save to .workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md (or .scratchpad/)
   `
 )
 ```
@@ -89,42 +92,5 @@ Task(
 ## Core Rules
 
 - **Read-only**: Diagnoses bugs, does NOT modify code
-- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` for root cause analysis
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-
-## CLI Command Templates
-
-**Gemini/Qwen** (default, diagnosis only):
-```bash
-cd [dir] && gemini -p "
-PURPOSE: [goal]
-TASK: Root cause analysis
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Diagnosis, fix plan
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex** (diagnosis + potential fixes):
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [goal]
-TASK: Bug diagnosis
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Diagnosis, fix suggestions
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/bug-diagnosis-[desc]-[timestamp].md`
-
-## Notes
-
-- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
-- See `intelligent-tools-strategy.md` for detailed tool usage
+- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
+- **Output**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -1,7 +1,7 @@
 ---
 name: code-analysis
 description: Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -21,7 +21,6 @@ Systematic code analysis with execution path tracing template (`~/.claude/workfl
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
@@ -47,91 +46,53 @@ Systematic code analysis with execution path tracing template (`~/.claude/workfl
 
 ## Execution Flow
 
-### Standard Mode (Default)
-
-1. Parse tool selection (default: gemini)
-2. Optional: enhance analysis target with `/enhance-prompt`
-3. Detect target directory from `--cd` or auto-infer
-4. Build command with template
-5. Execute analysis (read-only)
-6. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-
-### Agent Mode (`--agent` flag)
-
-Delegates to `cli-execution-agent` for intelligent context discovery and analysis.
-
-## Core Rules
-
-- **Read-only**: Analyzes code, does NOT modify files
-- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt` for systematic analysis
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-
-## CLI Command Templates
-
-**Gemini/Qwen** (default, read-only analysis):
-```bash
-cd [dir] && gemini -p "
-PURPOSE: [goal]
-TASK: Execution path tracing
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Trace, call diagram
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex** (analysis + optimization suggestions):
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [goal]
-TASK: Path analysis
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Trace, optimization
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Agent Execution Context
-
-When `--agent` flag is used, delegate to agent:
+Uses **cli-execution-agent** (default) for automated code analysis:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Code execution path analysis",
+  description="Execution path tracing and call flow analysis",
   prompt=`
     Task: ${analysis_target}
     Mode: code-analysis
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Directory: ${cd_path || 'auto-detect'}
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
     Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt
 
-    Agent responsibilities:
+    Execute systematic code analysis with execution path tracing:
+
     1. Context Discovery:
-       - Identify entry points and call chains
-       - Discover related files (MCP/ripgrep)
-       - Map execution flow paths
+       - Identify entry points and function signatures
+       - Trace call chains and execution flows
+       - Discover related files (implementations, dependencies, tests)
+       - Map data flow and state transformations
+       - Use MCP/ripgrep for comprehensive file discovery
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include discovered context
-       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt template
+    2. Analysis Execution:
+       - Apply execution tracing template
+       - Generate call flow diagrams (textual)
+       - Document execution paths and branching logic
+       - Identify optimization opportunities
 
-    3. Execution & Output:
-       - Execute analysis with selected tool
-       - Save to .workflow/WFS-[id]/.chat/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex analysis)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* + discovered execution context
+       - Mode: analysis (read-only)
+       - Template: analysis/01-trace-code-execution.txt
+
+    4. Output Generation:
+       - Execution trace documentation
+       - Call flow analysis with diagrams
+       - Performance and optimization insights
+       - Save to .workflow/WFS-[id]/.chat/code-analysis-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
-## Output
+## Core Rules
 
-- **With session**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/code-analysis-[desc]-[timestamp].md`
-
-## Notes
-
-- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
-- See `intelligent-tools-strategy.md` for detailed tool usage
+- **Read-only**: Analyzes code, does NOT modify files
+- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
+- **Output**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -1,7 +1,7 @@
 ---
 name: plan
 description: Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Strategic software architecture planning template (`~/.claude/workflows/cli-temp
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance task with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused planning
 - `<planning-task>` (Required) - Architecture planning task or modification requirements
@@ -43,87 +42,52 @@ Strategic software architecture planning template (`~/.claude/workflows/cli-temp
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Detect directory from `--cd` or auto-infer
-4. Build command with template
-5. Execute planning (read-only, no code generation)
-6. Save to `.workflow/WFS-[id]/.chat/`
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent planning:
+Uses **cli-execution-agent** (default) for automated planning:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Architecture modification planning",
+  description="Architecture planning with impact analysis",
   prompt=`
     Task: ${planning_task}
-    Mode: architecture-planning
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Directory: ${cd_path || 'auto-detect'}
+    Mode: plan
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
     Template: ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt
 
-    Agent responsibilities:
+    Execute strategic architecture planning:
+
     1. Context Discovery:
-       - Analyze current architecture
-       - Identify affected components
-       - Map dependencies and impacts
+       - Analyze current architecture structure
+       - Identify affected components and modules
+       - Map dependencies and integration points
+       - Assess modification impacts (scope, complexity, risks)
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include architecture context
-       - Apply ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt template
+    2. Planning Analysis:
+       - Apply strategic planning template
+       - Generate modification plan with phases
+       - Document architectural decisions and rationale
+       - Identify potential conflicts and mitigation strategies
 
-    3. Execution & Output:
-       - Execute strategic planning
-       - Generate modification plan
-       - Save to .workflow/.chat/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for implementation guidance)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* (full architecture context)
+       - Mode: analysis (read-only, no code generation)
+       - Template: planning/01-plan-architecture-design.txt
+
+    4. Output Generation:
+       - Strategic modification plan
+       - Impact analysis and risk assessment
+       - Implementation roadmap
+       - Save to .workflow/WFS-[id]/.chat/plan-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
 ## Core Rules
 
-- **Planning only**: Creates modification plans, does NOT generate code
-- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt` for strategic planning
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-
-## CLI Command Templates
-
-**Gemini/Qwen** (default, planning only):
-```bash
-cd [dir] && gemini -p "
-PURPOSE: [goal]
-TASK: Architecture planning
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Modification plan, impact analysis
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex** (planning + implementation guidance):
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [goal]
-TASK: Architecture planning
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Plan, implementation roadmap
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/plan-[desc]-[timestamp].md`
-
-## Notes
-
-- Template: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
-- See `intelligent-tools-strategy.md` for detailed tool usage
+- **Read-only**: Creates modification plans, does NOT generate code
+- **Template**: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
+- **Output**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md` (or `.scratchpad/` if no session)

.claude/commands/memory/code-map-memory.md

@@ -0,0 +1,764 @@
+---
+name: code-map-memory
+description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)
+argument-hint: "\"feature-keyword\" [--regenerate] [--tool <gemini|qwen>]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
+---
+
+# Code Flow Mapping Generator
+
+## Overview
+
+**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation.
+
+**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
+
+**Execution Paths**:
+- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag)
+- **Phase 3 Always Executes**: SKILL index is always generated or updated
+
+**Agent Responsibility** (cli-explore-agent):
+- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI)
+- Returns structured JSON with architecture, functions, data flow, conditionals, patterns
+- NO file writing - analysis only
+
+**Orchestrator Responsibility**:
+- Provides feature keyword and analysis scope to agent
+- Transforms agent's JSON into Mermaid-enriched markdown documentation
+- Writes all files (5 docs + metadata.json + SKILL.md)
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package
+3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode)
+4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files
+5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+6. **No User Prompts**: Never ask user questions or wait for input between phases
+7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional
+
+---
+
+## 3-Phase Execution
+
+### Phase 1: Parse Feature Keyword & Check Existing
+
+**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis
+
+**Step 1: Parse Feature Keyword**
+```bash
+# Get feature keyword from argument
+FEATURE_KEYWORD="$1"
+
+# Normalize: lowercase, spaces to hyphens
+normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
+
+# Example: "User Authentication" → "user-authentication"
+# Example: "支付处理" → "支付处理" (keep non-ASCII)
+```
+
+**Step 2: Set Tool Preference**
+```bash
+# Default to gemini unless --tool specified
+TOOL="${tool_flag:-gemini}"
+```
+
+**Step 3: Check Existing Codemap**
+```bash
+# Define codemap directory
+CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}"
+
+# Check if codemap exists
+bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists")
+
+# Count existing files
+bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Step 4: Skip Decision**
+```javascript
+if (existing_files > 0 && !regenerate_flag) {
+  SKIP_GENERATION = true
+  message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  bash(rm -rf "$CODEMAP_DIR")
+  SKIP_GENERATION = false
+  message = "Regenerating codemap from scratch."
+} else {
+  SKIP_GENERATION = false
+  message = "No existing codemap found, generating new code flow analysis."
+}
+```
+
+**Output Variables**:
+- `FEATURE_KEYWORD`: Original feature keyword
+- `normalized_feature`: Normalized feature name for directory
+- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}`
+- `TOOL`: CLI tool to use (gemini or qwen)
+- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
+
+**TodoWrite**:
+- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
+- If not skipping: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Code Flow Analysis & Documentation Generation
+
+**Skip Condition**: Skipped if `SKIP_GENERATION = true`
+
+**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation
+
+**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation)
+
+---
+
+#### Phase 2a: cli-explore-agent Analysis
+
+**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis
+
+**Agent Task Specification**:
+
+```
+Task(
+  subagent_type: "cli-explore-agent",
+  description: "Analyze code flow: {FEATURE_KEYWORD}",
+  prompt: "
+Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
+
+**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis)
+
+**Analysis Objectives**:
+1. **Module Architecture**: Identify high-level module organization, interactions, and entry points
+2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows
+3. **Data Transformations**: Map data structure changes and transformation stages
+4. **Conditional Paths**: Document decision trees, branches, and error handling strategies
+5. **Design Patterns**: Discover architectural patterns and extract design intent
+
+**Scope**:
+- Feature: {FEATURE_KEYWORD}
+- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model)
+- File Discovery: MCP Code Index (preferred) + rg fallback
+- Target: 5-15 most relevant files
+
+**Expected Output Format**:
+Return comprehensive analysis as structured JSON:
+{
+  \"feature\": \"{FEATURE_KEYWORD}\",
+  \"analysis_metadata\": {
+    \"tool_used\": \"gemini|qwen\",
+    \"timestamp\": \"ISO_TIMESTAMP\",
+    \"analysis_mode\": \"deep-scan\"
+  },
+  \"files_analyzed\": [
+    {\"file\": \"path/to/file.ts\", \"relevance\": \"high|medium|low\", \"role\": \"brief description\"}
+  ],
+  \"architecture\": {
+    \"overview\": \"High-level description\",
+    \"modules\": [
+      {\"name\": \"ModuleName\", \"file\": \"file:line\", \"responsibility\": \"description\", \"dependencies\": [...]}
+    ],
+    \"interactions\": [
+      {\"from\": \"ModuleA\", \"to\": \"ModuleB\", \"type\": \"import|call|data-flow\", \"description\": \"...\"}
+    ],
+    \"entry_points\": [
+      {\"function\": \"main\", \"file\": \"file:line\", \"description\": \"...\"}
+    ]
+  },
+  \"function_calls\": {
+    \"call_chains\": [
+      {
+        \"chain_id\": 1,
+        \"description\": \"User authentication flow\",
+        \"sequence\": [
+          {\"function\": \"login\", \"file\": \"file:line\", \"calls\": [\"validateCredentials\", \"createSession\"]}
+        ]
+      }
+    ],
+    \"sequences\": [
+      {\"from\": \"Client\", \"to\": \"AuthService\", \"method\": \"login(username, password)\", \"returns\": \"Session\"}
+    ]
+  },
+  \"data_flow\": {
+    \"structures\": [
+      {\"name\": \"UserData\", \"stage\": \"input\", \"shape\": {\"username\": \"string\", \"password\": \"string\"}}
+    ],
+    \"transformations\": [
+      {\"from\": \"RawInput\", \"to\": \"ValidatedData\", \"transformer\": \"validateUser\", \"file\": \"file:line\"}
+    ]
+  },
+  \"conditional_logic\": {
+    \"branches\": [
+      {\"condition\": \"isAuthenticated\", \"file\": \"file:line\", \"true_path\": \"...\", \"false_path\": \"...\"}
+    ],
+    \"error_handling\": [
+      {\"error_type\": \"AuthenticationError\", \"handler\": \"handleAuthError\", \"file\": \"file:line\", \"recovery\": \"retry|fail\"}
+    ]
+  },
+  \"design_patterns\": [
+    {\"pattern\": \"Repository Pattern\", \"location\": \"src/repositories\", \"description\": \"...\"}
+  ],
+  \"recommendations\": [
+    \"Consider extracting authentication logic into separate module\",
+    \"Add error recovery for network failures\"
+  ]
+}
+
+**Critical Requirements**:
+- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
+- Focus exclusively on {FEATURE_KEYWORD} feature flow
+- Include file:line references for ALL findings
+- Extract design intent from code structure and comments
+- NO FILE WRITING - return JSON analysis only
+- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback)
+  "
+)
+```
+
+**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns
+
+---
+
+#### Phase 2b: Orchestrator Documentation Generation
+
+**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation
+
+**Input**: Agent's JSON analysis result
+
+**Process**:
+
+1. **Parse Agent Analysis**:
+   ```javascript
+   const analysis = JSON.parse(agentResult)
+   const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis
+   ```
+
+2. **Generate Mermaid Diagrams from Structured Data**:
+
+   **a) architecture-flow.md** (~3K tokens):
+   ```javascript
+   // Convert architecture.modules + architecture.interactions → Mermaid graph TD
+   const architectureMermaid = `
+   graph TD
+   ${architecture.modules.map(m => `    ${m.name}[${m.name}]`).join('\n')}
+   ${architecture.interactions.map(i => `    ${i.from} -->|${i.type}| ${i.to}`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/architecture-flow.md`,
+     content: `---
+feature: ${feature}
+level: architecture
+detail: high-level module interactions
+---
+# Architecture Flow: ${feature}
+
+## Overview
+${architecture.overview}
+
+## Module Architecture
+${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')}
+
+## Flow Diagram
+\`\`\`mermaid
+${architectureMermaid}
+\`\`\`
+
+## Key Interactions
+${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')}
+
+## Entry Points
+${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')}
+`
+   })
+   ```
+
+   **b) function-calls.md** (~5K tokens):
+   ```javascript
+   // Convert function_calls.sequences → Mermaid sequenceDiagram
+   const sequenceMermaid = `
+   sequenceDiagram
+   ${function_calls.sequences.map(s => `    ${s.from}->>${s.to}: ${s.method}`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/function-calls.md`,
+     content: `---
+feature: ${feature}
+level: function
+detail: function-level call sequences
+---
+# Function Call Chains: ${feature}
+
+## Call Sequence Diagram
+\`\`\`mermaid
+${sequenceMermaid}
+\`\`\`
+
+## Detailed Call Chains
+${function_calls.call_chains.map(chain => `
+### Chain ${chain.chain_id}: ${chain.description}
+${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n  - Calls: ${fn.calls.join(', ')}`).join('\n')}
+`).join('\n')}
+
+## Parameters & Returns
+${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')}
+`
+   })
+   ```
+
+   **c) data-flow.md** (~4K tokens):
+   ```javascript
+   // Convert data_flow.transformations → Mermaid flowchart LR
+   const dataFlowMermaid = `
+   flowchart LR
+   ${data_flow.transformations.map((t, i) => `    Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/data-flow.md`,
+     content: `---
+feature: ${feature}
+level: data
+detail: data structure transformations
+---
+# Data Flow: ${feature}
+
+## Data Transformation Diagram
+\`\`\`mermaid
+${dataFlowMermaid}
+\`\`\`
+
+## Data Structures
+${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')}
+
+## Transformations
+${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')}
+`
+   })
+   ```
+
+   **d) conditional-paths.md** (~4K tokens):
+   ```javascript
+   // Convert conditional_logic.branches → Mermaid flowchart TD
+   const conditionalMermaid = `
+   flowchart TD
+       Start[Entry Point]
+   ${conditional_logic.branches.map((b, i) => `
+       Start --> Check${i}{${b.condition}}
+       Check${i} -->|Yes| Path${i}A[${b.true_path}]
+       Check${i} -->|No| Path${i}B[${b.false_path}]
+   `).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/conditional-paths.md`,
+     content: `---
+feature: ${feature}
+level: conditional
+detail: decision trees and error paths
+---
+# Conditional Paths: ${feature}
+
+## Decision Tree
+\`\`\`mermaid
+${conditionalMermaid}
+\`\`\`
+
+## Branch Conditions
+${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n  - True: ${b.true_path}\n  - False: ${b.false_path}`).join('\n')}
+
+## Error Handling
+${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')}
+`
+   })
+   ```
+
+   **e) complete-flow.md** (~8K tokens):
+   ```javascript
+   // Integrate all Mermaid diagrams
+   Write({
+     file_path: `${CODEMAP_DIR}/complete-flow.md`,
+     content: `---
+feature: ${feature}
+level: complete
+detail: integrated multi-level view
+---
+# Complete Flow: ${feature}
+
+## Integrated Flow Diagram
+\`\`\`mermaid
+graph TB
+    subgraph Architecture
+    ${architecture.modules.map(m => `    ${m.name}[${m.name}]`).join('\n')}
+    end
+
+    subgraph "Function Calls"
+    ${function_calls.call_chains[0]?.sequence.map(fn => `    ${fn.function}`).join('\n') || ''}
+    end
+
+    subgraph "Data Flow"
+    ${data_flow.structures.map(s => `    ${s.name}[${s.name}]`).join('\n')}
+    end
+\`\`\`
+
+## Complete Trace
+[Comprehensive end-to-end documentation combining all analysis layers]
+
+## Design Patterns Identified
+${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')}
+
+## Recommendations
+${analysis.recommendations.map(r => `- ${r}`).join('\n')}
+
+## Cross-References
+- [Architecture Flow](./architecture-flow.md) - High-level module structure
+- [Function Calls](./function-calls.md) - Detailed call chains
+- [Data Flow](./data-flow.md) - Data transformation stages
+- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling
+`
+   })
+   ```
+
+3. **Write metadata.json**:
+   ```javascript
+   Write({
+     file_path: `${CODEMAP_DIR}/metadata.json`,
+     content: JSON.stringify({
+       feature: feature,
+       normalized_name: normalized_feature,
+       generated_at: new Date().toISOString(),
+       tool_used: analysis.analysis_metadata.tool_used,
+       files_analyzed: files_analyzed.map(f => f.file),
+       analysis_summary: {
+         total_files: files_analyzed.length,
+         modules_traced: architecture.modules.length,
+         functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0),
+         patterns_discovered: design_patterns.length
+       }
+     }, null, 2)
+   })
+   ```
+
+4. **Report Phase 2 Completion**:
+   ```
+   Phase 2 Complete: Code flow analysis and documentation generated
+
+   - Agent Analysis: cli-explore-agent with {TOOL}
+   - Files Analyzed: {count}
+   - Documentation Generated: 5 markdown files + metadata.json
+   - Location: {CODEMAP_DIR}
+   ```
+
+**Completion Criteria**:
+- cli-explore-agent task completed successfully with JSON result
+- 5 documentation files written with valid Mermaid diagrams
+- metadata.json written with analysis summary
+- All files properly formatted and cross-referenced
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Generate SKILL.md Index
+
+**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
+
+**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading
+
+**Steps**:
+
+1. **Verify Generated Files**:
+   ```bash
+   bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort)
+   ```
+
+2. **Read metadata.json**:
+   ```javascript
+   Read({CODEMAP_DIR}/metadata.json)
+   // Extract: feature, normalized_name, files_analyzed, analysis_summary
+   ```
+
+3. **Read File Headers** (optional, first 30 lines):
+   ```javascript
+   Read({CODEMAP_DIR}/architecture-flow.md, limit: 30)
+   Read({CODEMAP_DIR}/function-calls.md, limit: 30)
+   // Extract overview and diagram counts
+   ```
+
+4. **Generate SKILL.md Index**:
+
+   Template structure:
+   ```yaml
+   ---
+   name: codemap-{normalized_feature}
+   description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory.
+   version: 1.0.0
+   generated_at: {ISO_TIMESTAMP}
+   ---
+   # Code Flow Map: {FEATURE_KEYWORD}
+
+   ## Feature: `{FEATURE_KEYWORD}`
+
+   **Analysis Date**: {DATE}
+   **Tool Used**: {TOOL}
+   **Files Analyzed**: {COUNT}
+
+   ## Progressive Loading
+
+   ### Level 0: Quick Overview (~2K tokens)
+   - [Architecture Flow](./architecture-flow.md) - High-level module interactions
+
+   ### Level 1: Core Flows (~10K tokens)
+   - [Architecture Flow](./architecture-flow.md) - Module architecture
+   - [Function Calls](./function-calls.md) - Function call chains
+
+   ### Level 2: Complete Analysis (~20K tokens)
+   - [Architecture Flow](./architecture-flow.md)
+   - [Function Calls](./function-calls.md)
+   - [Data Flow](./data-flow.md) - Data transformations
+
+   ### Level 3: Deep Dive (~30K tokens)
+   - [Architecture Flow](./architecture-flow.md)
+   - [Function Calls](./function-calls.md)
+   - [Data Flow](./data-flow.md)
+   - [Conditional Paths](./conditional-paths.md) - Branches and error handling
+   - [Complete Flow](./complete-flow.md) - Integrated comprehensive view
+
+   ## Usage
+
+   Load this SKILL package when:
+   - Analyzing {FEATURE_KEYWORD} implementation
+   - Tracing execution flow for debugging
+   - Understanding code dependencies
+   - Planning refactoring or enhancements
+
+   ## Analysis Summary
+
+   - **Modules Traced**: {modules_traced}
+   - **Functions Traced**: {functions_traced}
+   - **Files Analyzed**: {total_files}
+
+   ## Mermaid Diagrams Included
+
+   - Architecture flow diagram (graph TD)
+   - Function call sequence diagram (sequenceDiagram)
+   - Data transformation flowchart (flowchart LR)
+   - Conditional decision tree (flowchart TD)
+   - Complete integrated diagram (graph TB)
+   ```
+
+5. **Write SKILL.md**:
+   ```javascript
+   Write({
+     file_path: `{CODEMAP_DIR}/SKILL.md`,
+     content: generatedIndexMarkdown
+   })
+   ```
+
+**Completion Criteria**:
+- SKILL.md index written
+- All documentation files verified
+- Progressive loading levels (0-3) properly structured
+- Mermaid diagram references included
+
+**TodoWrite**: Mark phase 3 completed
+
+**Final Report**:
+```
+Code Flow Mapping Complete
+
+Feature: {FEATURE_KEYWORD}
+Location: .claude/skills/codemap-{normalized_feature}/
+
+Files Generated:
+- SKILL.md (index)
+- architecture-flow.md (with Mermaid diagram)
+- function-calls.md (with Mermaid sequence diagram)
+- data-flow.md (with Mermaid flowchart)
+- conditional-paths.md (with Mermaid decision tree)
+- complete-flow.md (with integrated Mermaid diagram)
+- metadata.json
+
+Analysis:
+- Files analyzed: {count}
+- Modules traced: {count}
+- Functions traced: {count}
+
+Usage: Skill(command: "codemap-{normalized_feature}")
+```
+
+---
+
+## Implementation Details
+
+### TodoWrite Patterns
+
+**Initialization** (Before Phase 1):
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"},
+  {"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
+]})
+```
+
+**Full Path** (SKIP_GENERATION = false):
+```javascript
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...},
+  {"content": "Generate SKILL.md index", "status": "pending", ...}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "completed", ...}
+]})
+```
+
+**Skip Path** (SKIP_GENERATION = true):
+```javascript
+// After Phase 1 (skip Phase 2)
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},  // Skipped
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+```
+
+### Execution Flow
+
+**Full Path**:
+```
+User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report
+```
+
+**Skip Path**:
+```
+User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
+```
+
+### Error Handling
+
+**Phase 1 Errors**:
+- Empty feature keyword: Report error, ask user to provide feature description
+- Invalid characters: Normalize and continue
+
+**Phase 2 Errors (Agent)**:
+- Agent task fails: Retry once, report if fails again
+- No files discovered: Warn user, ask for more specific feature keyword
+- CLI failures: Agent handles internally with retries
+- Invalid Mermaid syntax: Agent validates before writing
+
+**Phase 3 Errors**:
+- Write failures: Report which files failed
+- Missing files: Note in SKILL.md, suggest regeneration
+
+---
+
+## Parameters
+
+```bash
+/memory:code-map-memory "feature-keyword" [--regenerate] [--tool <gemini|qwen>]
+```
+
+**Arguments**:
+- **"feature-keyword"**: Feature or flow to analyze (required)
+  - Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"`
+  - Can be English, Chinese, or mixed
+  - Spaces and underscores normalized to hyphens
+- **--regenerate**: Force regenerate existing codemap (deletes and recreates)
+- **--tool**: CLI tool for analysis (default: gemini)
+  - `gemini`: Comprehensive flow analysis with gemini-2.5-pro
+  - `qwen`: Alternative with coder-model
+
+---
+
+## Examples
+
+**Generated File Structure** (for all examples):
+```
+.claude/skills/codemap-{feature}/
+├── SKILL.md                    # Index (Phase 3)
+├── architecture-flow.md        # Agent (Phase 2) - High-level flow
+├── function-calls.md           # Agent (Phase 2) - Function chains
+├── data-flow.md                # Agent (Phase 2) - Data transformations
+├── conditional-paths.md        # Agent (Phase 2) - Branches & errors
+├── complete-flow.md            # Agent (Phase 2) - Integrated view
+└── metadata.json               # Agent (Phase 2)
+```
+
+### Example 1: User Authentication Flow
+
+```bash
+/memory:code-map-memory "user authentication"
+```
+
+**Workflow**:
+1. Phase 1: Normalizes to "user-authentication", checks existing codemap
+2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid
+3. Phase 3: Generates SKILL.md index with progressive loading
+
+**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata
+
+
+### Example 3: Regenerate with Qwen
+
+```bash
+/memory:code-map-memory "payment processing" --regenerate --tool qwen
+```
+
+**Workflow**:
+1. Phase 1: Deletes existing codemap due to --regenerate
+2. Phase 2: Agent uses qwen with coder-model for fresh analysis
+3. Phase 3: Generates updated SKILL.md
+
+---
+
+## Benefits
+
+- **Per-Feature SKILL**: Independent packages for each analyzed feature
+- **Specialized Agent**: cli-explore-agent with Deep Scan mode (Bash + Gemini dual-source)
+- **Professional Analysis**: Pre-defined workflow for code exploration and structure analysis
+- **Clear Separation**: Agent analyzes (JSON) → Orchestrator documents (Mermaid markdown)
+- **Multi-Level Detail**: 4 levels (architecture → function → data → conditional)
+- **Visual Flow**: Embedded Mermaid diagrams for all flow types
+- **Progressive Loading**: Token-efficient context loading (2K → 30K)
+- **Auto-Continue**: Fully autonomous 3-phase execution
+- **Smart Skip**: Detects existing codemap, 10x faster index updates
+- **CLI Integration**: Gemini/Qwen for deep semantic understanding
+
+## Architecture
+
+```
+code-map-memory (orchestrator)
+  ├─ Phase 1: Parse & Check (bash commands, skip decision)
+  ├─ Phase 2: Code Analysis & Documentation (skippable)
+  │   ├─ Phase 2a: cli-explore-agent Analysis
+  │   │   └─ Deep Scan: Bash structural + Gemini semantic → JSON
+  │   └─ Phase 2b: Orchestrator Documentation
+  │       └─ Transform JSON → 5 Mermaid markdown files + metadata.json
+  └─ Phase 3: Write SKILL.md (index generation, always runs)
+
+Benefits:
+✅ Specialized agent: cli-explore-agent with dual-source strategy (Bash + Gemini)
+✅ Professional analysis: Pre-defined Deep Scan workflow
+✅ Clear separation: Agent analyzes (JSON) → Orchestrator documents (Mermaid)
+✅ Smart skip logic: 10x faster when codemap exists
+✅ Multi-level detail: Architecture → Functions → Data → Conditionals
+
+Output: .claude/skills/codemap-{feature}/
+```

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

@@ -0,0 +1,870 @@
+---
+name: style-skill-memory
+description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
+argument-hint: "[package-name] [--regenerate]"
+allowed-tools: Bash,Read,Write,TodoWrite
+auto-continue: true
+---
+
+# Memory: Style SKILL Memory Generator
+
+## Overview
+
+**Purpose**: Convert style reference package into SKILL memory for easy loading and context management.
+
+**Input**: Style reference package at `.workflow/reference_style/{package-name}/`
+
+**Output**: SKILL memory index at `.claude/skills/style-{package-name}/SKILL.md`
+
+**Use Case**: Load design system context when working with UI components, analyzing design patterns, or implementing style guidelines.
+
+**Key Features**:
+- Extracts primary design references (colors, typography, spacing, etc.)
+- Provides dynamic adjustment guidelines for design tokens
+- Progressive loading structure for efficient token usage
+- Interactive preview showcase
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+/memory:style-skill-memory [package-name] [--regenerate]
+
+# Arguments
+package-name    Style reference package name (required)
+--regenerate    Force regenerate SKILL.md even if it exists (optional)
+```
+
+### Usage Examples
+
+```bash
+# Generate SKILL memory for package
+/memory:style-skill-memory main-app-style-v1
+
+# Regenerate SKILL memory
+/memory:style-skill-memory main-app-style-v1 --regenerate
+
+# Package name from current directory or default
+/memory:style-skill-memory
+```
+
+---
+
+## Execution Process
+
+### Phase 1: Validate Package
+
+**Purpose**: Check if style reference package exists
+
+**TodoWrite** (First Action):
+```json
+[
+  {"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
+  {"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"},
+  {"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"}
+]
+```
+
+**Step 1: Parse Package Name**
+
+```bash
+# Get package name from argument or auto-detect
+bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//')
+```
+
+Store result as `package_name`
+
+**Step 2: Validate Package Exists**
+
+```bash
+bash(test -d .workflow/reference_style/${package_name} && echo "exists" || echo "missing")
+```
+
+**Error Handling**:
+```javascript
+if (package_not_exists) {
+  error("ERROR: Style reference package not found: ${package_name}")
+  error("HINT: Run '/workflow:ui-design:codify-style' first to create package")
+  error("Available packages:")
+  bash(ls -1 .workflow/reference_style/ 2>/dev/null || echo "  (none)")
+  exit(1)
+}
+```
+
+**Step 3: Check SKILL Already Exists**
+
+```bash
+bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "exists" || echo "missing")
+```
+
+**Decision Logic**:
+```javascript
+if (skill_exists && !regenerate_flag) {
+  echo("SKILL memory already exists for: ${package_name}")
+  echo("Use --regenerate to force regeneration")
+  exit(0)
+}
+
+if (regenerate_flag && skill_exists) {
+  echo("Regenerating SKILL memory for: ${package_name}")
+}
+```
+
+**Summary Variables**:
+- `PACKAGE_NAME`: Style reference package name
+- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}`
+- `SKILL_DIR`: `.claude/skills/style-${package_name}`
+- `REGENERATE`: `true` if --regenerate flag, `false` otherwise
+
+**TodoWrite Update**:
+```json
+[
+  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
+  {"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
+]
+```
+
+---
+
+### Phase 2: Read Package Data & Extract Design References
+
+**Purpose**: Extract package information and primary design references for SKILL description generation
+
+**Step 1: Count Components**
+
+```bash
+bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
+```
+
+Store result as `component_count`
+
+**Step 2: Extract Component Types and Classification**
+
+```bash
+# Extract component names from layout templates
+bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
+
+# Count universal vs specialized components
+bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
+bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
+
+# Extract universal component names only
+bash(jq -r '.layout_templates | to_entries | map(select(.value.component_type == "universal")) | .[].key' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
+```
+
+Store as:
+- `COMPONENT_TYPES`: List of available component types (all)
+- `UNIVERSAL_COUNT`: Number of universal (reusable) components
+- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
+- `UNIVERSAL_COMPONENTS`: List of universal component names
+
+**Step 3: Read Design Tokens**
+
+```bash
+Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
+```
+
+**Extract Primary Design References**:
+
+**Colors** (top 3-5 most important):
+```bash
+bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5)
+```
+
+**Typography** (heading and body fonts):
+```bash
+bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Spacing Scale** (base spacing values):
+```bash
+bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Border Radius** (base radius values):
+```bash
+bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Shadows** (elevation levels):
+```bash
+bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+Store extracted references as:
+- `PRIMARY_COLORS`: List of primary color tokens
+- `TYPOGRAPHY_FONTS`: Font family tokens
+- `SPACING_SCALE`: Base spacing values
+- `BORDER_RADIUS`: Radius values
+- `SHADOWS`: Shadow definitions
+
+**Step 4: Read Animation Tokens (if available)**
+
+```bash
+# Check if animation tokens exist
+bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
+```
+
+If available, extract:
+```bash
+Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
+
+# Extract primary animation values
+bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
+bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
+```
+
+Store as:
+- `ANIMATION_DURATIONS`: Animation duration tokens
+- `EASING_FUNCTIONS`: Easing function tokens
+
+**Step 5: Count Files**
+
+```bash
+bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
+```
+
+Store result as `file_count`
+
+**Summary Data Collected**:
+- `COMPONENT_COUNT`: Number of components in layout templates
+- `UNIVERSAL_COUNT`: Number of universal (reusable) components
+- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
+- `COMPONENT_TYPES`: List of component types (first 10)
+- `UNIVERSAL_COMPONENTS`: List of universal component names (first 10)
+- `FILE_COUNT`: Total files in package
+- `HAS_ANIMATIONS`: Whether animation tokens are available
+- `PRIMARY_COLORS`: Primary color tokens with values
+- `TYPOGRAPHY_FONTS`: Font family tokens
+- `SPACING_SCALE`: Base spacing scale
+- `BORDER_RADIUS`: Border radius values
+- `SHADOWS`: Shadow definitions
+- `ANIMATION_DURATIONS`: Animation durations (if available)
+- `EASING_FUNCTIONS`: Easing functions (if available)
+
+**TodoWrite Update**:
+```json
+[
+  {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
+  {"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]
+```
+
+---
+
+### Phase 3: Generate SKILL.md
+
+**Purpose**: Create SKILL memory index with progressive loading structure and design references
+
+**Step 1: Create SKILL Directory**
+
+```bash
+bash(mkdir -p .claude/skills/style-${package_name})
+```
+
+**Step 2: Generate Intelligent Description**
+
+**Format**:
+```
+{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
+```
+
+**Key Elements**:
+- **Universal Count**: Emphasize available reusable layout templates
+- **Project Independence**: Clearly state project-independent nature
+- **Specialized Exclusion**: Mention excluded project-specific components
+- **Path Reference**: Precise package location
+- **Trigger Keywords**: reusable UI components, design tokens, layout patterns, visual consistency
+- **Action Coverage**: working with, analyzing, implementing
+
+**Example**:
+```
+main-app-style-v1 project-independent design system with 5 universal layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes 3 project-specific components.
+```
+
+**Step 3: Write SKILL.md**
+
+Use Write tool to generate SKILL.md with the following complete content:
+
+```markdown
+---
+name: style-{package_name}
+description: {intelligent description from Step 2}
+---
+
+# {Package Name} Style SKILL Package
+
+## Documentation: `../../../.workflow/reference_style/{package_name}/`
+
+## Package Overview
+
+**Project-independent style reference package** extracted from codebase with reusable design patterns, tokens, and interactive preview.
+
+**Package Details**:
+- Package: {package_name}
+- Layout Templates: {component_count} total
+  - **Universal Components**: {universal_count} (reusable, project-independent)
+  - **Specialized Components**: {specialized_count} (project-specific, excluded from reference)
+- Universal Component Types: {comma-separated list of UNIVERSAL_COMPONENTS}
+- Files: {file_count}
+- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
+
+**⚠️ IMPORTANT - Project Independence**:
+This SKILL package represents a **pure style system** independent of any specific project implementation:
+- **Universal components** are generic, reusable patterns (buttons, inputs, cards, navigation)
+- **Specialized components** are project-specific implementations (excluded from this reference)
+- All design tokens and layout patterns are extracted for **reference purposes only**
+- Adapt and customize these references based on your project's specific requirements
+
+---
+
+## ⚡ Primary Design References
+
+**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints.
+
+### 🎨 Colors
+
+{FOR each color in PRIMARY_COLORS:
+  - **{color.key}**: `{color.value}`
+}
+
+**Usage Guidelines**:
+- These colors establish the foundation of the design system
+- Adjust saturation, lightness, or hue based on:
+  - Brand requirements and accessibility needs
+  - Context (light/dark mode, high-contrast themes)
+  - User feedback and A/B testing results
+- Use color theory principles to maintain harmony when modifying
+
+### 📝 Typography
+
+{FOR each font in TYPOGRAPHY_FONTS:
+  - **{font.key}**: `{font.value}`
+}
+
+**Usage Guidelines**:
+- Font families can be substituted based on:
+  - Brand identity and design language
+  - Performance requirements (web fonts vs. system fonts)
+  - Accessibility and readability considerations
+  - Platform-specific availability
+- Maintain hierarchy and scale relationships when changing fonts
+
+### 📏 Spacing Scale
+
+{FOR each spacing in SPACING_SCALE:
+  - **{spacing.key}**: `{spacing.value}`
+}
+
+**Usage Guidelines**:
+- Spacing values form a consistent rhythm system
+- Adjust scale based on:
+  - Target device (mobile vs. desktop vs. tablet)
+  - Content density requirements
+  - Component-specific needs (compact vs. comfortable layouts)
+- Maintain proportional relationships when scaling
+
+### 🔲 Border Radius
+
+{FOR each radius in BORDER_RADIUS:
+  - **{radius.key}**: `{radius.value}`
+}
+
+**Usage Guidelines**:
+- Border radius affects visual softness and modernity
+- Adjust based on:
+  - Design aesthetic (sharp vs. rounded vs. pill-shaped)
+  - Component type (buttons, cards, inputs have different needs)
+  - Platform conventions (iOS vs. Android vs. Web)
+
+### 🌫️ Shadows
+
+{FOR each shadow in SHADOWS:
+  - **{shadow.key}**: `{shadow.value}`
+}
+
+**Usage Guidelines**:
+- Shadows create elevation and depth perception
+- Adjust based on:
+  - Material design depth levels
+  - Light/dark mode contexts
+  - Performance considerations (complex shadows impact rendering)
+  - Visual hierarchy needs
+
+{IF HAS_ANIMATIONS:
+### ⏱️ Animation & Timing
+
+**Durations**:
+{FOR each duration in ANIMATION_DURATIONS:
+  - **{duration.key}**: `{duration.value}`
+}
+
+**Easing Functions**:
+{FOR each easing in EASING_FUNCTIONS:
+  - **{easing.key}**: `{easing.value}`
+}
+
+**Usage Guidelines**:
+- Animation timing affects perceived responsiveness and polish
+- Adjust based on:
+  - User expectations and platform conventions
+  - Accessibility preferences (reduced motion)
+  - Animation type (micro-interactions vs. page transitions)
+  - Performance constraints (mobile vs. desktop)
+}
+
+---
+
+## 🎯 Design Adaptation Strategies
+
+### When to Adjust Design References
+
+**Brand Alignment**:
+- Modify colors to match brand identity and guidelines
+- Adjust typography to reflect brand personality
+- Tune spacing and radius to align with brand aesthetic
+
+**Accessibility Requirements**:
+- Increase color contrast ratios for WCAG compliance
+- Adjust font sizes and spacing for readability
+- Modify animation durations for reduced-motion preferences
+
+**Platform Optimization**:
+- Adapt spacing for mobile touch targets (min 44x44px)
+- Adjust shadows and radius for platform conventions
+- Optimize animation performance for target devices
+
+**Context-Specific Needs**:
+- Dark mode: Adjust colors, shadows, and contrasts
+- High-density displays: Fine-tune spacing and sizing
+- Responsive design: Scale tokens across breakpoints
+
+### How to Apply Adjustments
+
+1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements
+2. **Maintain Relationships**: Preserve proportional relationships between related tokens
+3. **Test Thoroughly**: Validate changes across components and use cases
+4. **Document Changes**: Track modifications and rationale for team alignment
+5. **Iterate**: Refine based on user feedback and testing results
+
+---
+
+## Progressive Loading
+
+### Level 0: Design Tokens (~5K tokens)
+
+Essential design token system for consistent styling.
+
+**Files**:
+- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows, borders
+
+**Use when**: Quick token reference, applying consistent styles, color/typography queries
+
+---
+
+### Level 1: Universal Layout Templates (~12K tokens)
+
+**Project-independent** component layout patterns for reusable UI elements.
+
+**Files**:
+- Level 0 files
+- [Layout Templates](../../../.workflow/reference_style/{package_name}/layout-templates.json) - Component structures with HTML/CSS patterns
+
+**⚠️ Reference Strategy**:
+- **Only reference components with `component_type: "universal"`** - these are reusable, project-independent patterns
+- **Ignore components with `component_type: "specialized"`** - these are project-specific implementations
+- Universal components include: buttons, inputs, forms, cards, navigation, modals, etc.
+- Use universal patterns as **reference templates** to adapt for your specific project needs
+
+**Use when**: Building components, understanding component architecture, implementing layouts
+
+---
+
+### Level 2: Complete System (~20K tokens)
+
+Full design system with animations and interactive preview.
+
+**Files**:
+- All Level 1 files
+- [Animation Tokens](../../../.workflow/reference_style/{package_name}/animation-tokens.json) - Animation durations, easing, transitions _(if available)_
+- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive showcase (reference only)
+- [Preview CSS](../../../.workflow/reference_style/{package_name}/preview.css) - Showcase styling (reference only)
+
+**Use when**: Comprehensive analysis, animation development, complete design system understanding
+
+---
+
+## Interactive Preview
+
+**Location**: `.workflow/reference_style/{package_name}/preview.html`
+
+**View in Browser**:
+```bash
+cd .workflow/reference_style/{package_name}
+python -m http.server 8080
+# Open http://localhost:8080/preview.html
+```
+
+**Features**:
+- Color palette swatches with values
+- Typography scale and combinations
+- All components with variants and states
+- Spacing, radius, shadow visual examples
+- Interactive state demonstrations
+- Usage code snippets
+
+---
+
+## Usage Guidelines
+
+### Loading Levels
+
+**Level 0** (5K): Design tokens only
+```
+Load Level 0 for design token reference
+```
+
+**Level 1** (12K): Tokens + layout templates
+```
+Load Level 1 for layout templates and design tokens
+```
+
+**Level 2** (20K): Complete system with animations and preview
+```
+Load Level 2 for complete design system with preview reference
+```
+
+### Common Use Cases
+
+**Implementing UI Components**:
+- Load Level 1 for universal layout templates
+- **Only reference components with `component_type: "universal"`** in layout-templates.json
+- Apply design tokens from design-tokens.json
+- Adapt patterns to your project's specific requirements
+
+**Ensuring Style Consistency**:
+- Load Level 0 for design tokens
+- Use design-tokens.json for colors, typography, spacing
+- Check preview.html for visual reference (universal components only)
+
+**Analyzing Component Patterns**:
+- Load Level 2 for complete analysis
+- Review layout-templates.json for component architecture
+- **Filter for `component_type: "universal"` to exclude project-specific implementations**
+- Check preview.html for implementation examples
+
+**Animation Development**:
+- Load Level 2 for animation tokens (if available)
+- Reference animation-tokens.json for durations and easing
+- Apply consistent timing and transitions
+
+**⚠️ Critical Usage Rule**:
+This is a **project-independent style reference system**. When working with layout-templates.json:
+- **USE**: Components marked `component_type: "universal"` as reusable reference patterns
+- **IGNORE**: Components marked `component_type: "specialized"` (project-specific implementations)
+- **ADAPT**: All patterns should be customized for your specific project needs
+
+---
+
+## Package Structure
+
+```
+.workflow/reference_style/{package_name}/
+├── layout-templates.json   # Layout templates from codebase
+├── design-tokens.json     # Design token system
+├── animation-tokens.json  # Animation tokens (optional)
+├── preview.html          # Interactive showcase
+└── preview.css           # Showcase styling
+```
+
+---
+
+## Regeneration
+
+To update this SKILL memory after package changes:
+
+```bash
+/memory:style-skill-memory {package_name} --regenerate
+```
+
+---
+
+## Related Commands
+
+**Generate Package**:
+```bash
+/workflow:ui-design:codify-style --source ./src --package-name {package_name}
+```
+
+**Update Package**:
+Re-run codify-style with same package name to update extraction.
+```
+
+**Step 4: Verify SKILL.md Created**
+
+```bash
+bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed")
+```
+
+**TodoWrite Update**:
+```json
+[
+  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
+  {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
+  {"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"}
+]
+```
+
+**Final Action**: Report completion summary to user
+
+---
+
+## Completion Message
+
+Display extracted primary design references to user:
+
+```
+✅ SKILL memory generated successfully!
+
+Package: {package_name}
+SKILL Location: .claude/skills/style-{package_name}/SKILL.md
+
+📦 Package Details:
+- Layout Templates: {component_count} total
+  - Universal (reusable): {universal_count}
+  - Specialized (project-specific): {specialized_count}
+- Universal Component Types: {show first 5 UNIVERSAL_COMPONENTS, then "+ X more"}
+- Files: {file_count}
+- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
+
+🎨 Primary Design References Extracted:
+{IF PRIMARY_COLORS exists:
+Colors:
+  {show first 3 PRIMARY_COLORS with key: value}
+  {if more than 3: + X more colors}
+}
+
+{IF TYPOGRAPHY_FONTS exists:
+Typography:
+  {show all TYPOGRAPHY_FONTS}
+}
+
+{IF SPACING_SCALE exists:
+Spacing Scale:
+  {show first 3 SPACING_SCALE items}
+  {if more than 3: + X more spacing tokens}
+}
+
+{IF BORDER_RADIUS exists:
+Border Radius:
+  {show all BORDER_RADIUS}
+}
+
+{IF HAS_ANIMATIONS:
+Animation:
+  Durations: {count ANIMATION_DURATIONS} tokens
+  Easing: {count EASING_FUNCTIONS} functions
+}
+
+⚡ Progressive Loading Levels:
+- Level 0: Design Tokens (~5K tokens)
+- Level 1: Tokens + Layout Templates (~12K tokens)
+- Level 2: Complete System (~20K tokens)
+
+💡 Usage:
+Load design system context when working with:
+- UI component implementation
+- Layout pattern analysis
+- Design token application
+- Style consistency validation
+
+⚠️ IMPORTANT - Project Independence:
+This is a **project-independent style reference system**:
+- Only use universal components (component_type: "universal") as reference patterns
+- Ignore specialized components (component_type: "specialized") - they are project-specific
+- The extracted design references are REFERENCE VALUES, not fixed constraints
+- Dynamically adjust colors, spacing, typography, and other tokens based on:
+  - Brand requirements and accessibility needs
+  - Platform-specific conventions and optimizations
+  - Context (light/dark mode, responsive breakpoints)
+  - User feedback and testing results
+
+See SKILL.md for detailed adjustment guidelines and component filtering instructions.
+
+🎯 Preview:
+Open interactive showcase:
+  file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html
+
+📋 Next Steps:
+1. Load appropriate level based on your task context
+2. Review Primary Design References section for key design tokens
+3. Apply design tokens with dynamic adjustments as needed
+4. Reference layout-templates.json for component structures
+5. Use Design Adaptation Strategies when modifying tokens
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Package not found | Invalid package name or package doesn't exist | Run codify-style first to create package |
+| SKILL already exists | SKILL.md already generated | Use --regenerate to force regeneration |
+| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
+| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **Check Before Generate**: Verify package exists before attempting SKILL generation
+2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
+3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations)
+4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens
+5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates
+6. **Intelligent Description**: Extract component count and key features from metadata
+
+### SKILL Description Format
+
+**Template**:
+```
+{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
+```
+
+**Required Elements**:
+- Package name
+- Universal layout template count (emphasize reusability)
+- Project independence statement
+- Specialized component exclusion notice
+- Location (full path)
+- Trigger keywords (reusable UI components, design tokens, layout patterns, visual consistency)
+- Action verbs (working with, analyzing, implementing)
+
+### Primary Design References Extraction
+
+**Required Data Extraction** (from design-tokens.json):
+- Colors: Primary, secondary, accent colors (top 3-5)
+- Typography: Font families for headings and body text
+- Spacing Scale: Base spacing values (xs, sm, md, lg, xl)
+- Border Radius: All radius tokens
+- Shadows: Shadow definitions (top 3 elevation levels)
+
+**Component Classification Extraction** (from layout-templates.json):
+- Universal Count: Number of components with `component_type: "universal"`
+- Specialized Count: Number of components with `component_type: "specialized"`
+- Universal Component Names: List of universal component names (first 10)
+
+**Optional Data Extraction** (from animation-tokens.json if available):
+- Animation Durations: All duration tokens
+- Easing Functions: Top 3 easing functions
+
+**Extraction Format**:
+Use `jq` to extract tokens from JSON files. Each token should include key and value.
+For component classification, filter by `component_type` field.
+
+### Dynamic Adjustment Guidelines
+
+**Include in SKILL.md**:
+1. **Usage Guidelines per Category**: Specific guidance for each token category
+2. **Adjustment Strategies**: When to adjust design references
+3. **Practical Examples**: Context-specific adaptation scenarios
+4. **Best Practices**: How to maintain design system coherence while adjusting
+
+### Progressive Loading Structure
+
+**Level 0** (~5K tokens):
+- design-tokens.json
+
+**Level 1** (~12K tokens):
+- Level 0 files
+- layout-templates.json
+
+**Level 2** (~20K tokens):
+- Level 1 files
+- animation-tokens.json (if exists)
+- preview.html
+- preview.css
+
+---
+
+## Benefits
+
+- **Project Independence**: Clear separation between universal (reusable) and specialized (project-specific) components
+- **Component Filtering**: Automatic classification helps identify which patterns are truly reusable
+- **Fast Context Loading**: Progressive levels for efficient token usage
+- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently
+- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens
+- **Intelligent Triggering**: Keywords optimize SKILL activation
+- **Complete Reference**: All package files accessible through SKILL
+- **Easy Regeneration**: Simple --regenerate flag for updates
+- **Clear Structure**: Organized levels by use case with component type filtering
+- **Practical Usage Guidelines**: Context-specific adjustment strategies and component selection criteria
+
+---
+
+## Architecture
+
+```
+style-skill-memory
+  ├─ Phase 1: Validate
+  │   ├─ Parse package name from argument or auto-detect
+  │   ├─ Check package exists in .workflow/reference_style/
+  │   └─ Check if SKILL already exists (skip if exists and no --regenerate)
+  │
+  ├─ Phase 2: Read Package Data & Extract Primary References
+  │   ├─ Count components from layout-templates.json
+  │   ├─ Extract component types list
+  │   ├─ Extract primary colors from design-tokens.json (top 3-5)
+  │   ├─ Extract typography (font families)
+  │   ├─ Extract spacing scale (base values)
+  │   ├─ Extract border radius tokens
+  │   ├─ Extract shadow definitions (top 3)
+  │   ├─ Extract animation tokens (if available)
+  │   └─ Count total files in package
+  │
+  └─ Phase 3: Generate SKILL.md
+      ├─ Create SKILL directory
+      ├─ Generate intelligent description with keywords
+      ├─ Write SKILL.md with complete structure:
+      │   ├─ Package Overview
+      │   ├─ Primary Design References
+      │   │   ├─ Colors with usage guidelines
+      │   │   ├─ Typography with usage guidelines
+      │   │   ├─ Spacing with usage guidelines
+      │   │   ├─ Border Radius with usage guidelines
+      │   │   ├─ Shadows with usage guidelines
+      │   │   └─ Animation & Timing (if available)
+      │   ├─ Design Adaptation Strategies
+      │   │   ├─ When to adjust design references
+      │   │   └─ How to apply adjustments
+      │   ├─ Progressive Loading (3 levels)
+      │   ├─ Interactive Preview
+      │   ├─ Usage Guidelines
+      │   ├─ Package Structure
+      │   ├─ Regeneration
+      │   └─ Related Commands
+      ├─ Verify SKILL.md created successfully
+      └─ Display completion message with extracted design references
+
+Data Flow:
+  design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS,
+                                       SPACING_SCALE, BORDER_RADIUS, SHADOWS
+  animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS
+  layout-templates.json → jq extraction → COMPONENT_COUNT, UNIVERSAL_COUNT,
+                                         SPECIALIZED_COUNT, UNIVERSAL_COMPONENTS
+                       → component_type filtering → Universal vs Specialized classification
+
+  Extracted data → SKILL.md generation → Primary Design References section
+                                      → Component Classification section
+                                      → Dynamic Adjustment Guidelines
+                                      → Project Independence warnings
+                                      → Completion message display
+```

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

@@ -9,22 +9,32 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
+**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), coordinating specialized commands/agents through task attachment model.
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- Task agent execution **attaches analysis tasks** to orchestrator's TodoWrite
+- Phase 1: artifacts command attaches its internal tasks (Phase 1-5)
+- Phase 2: N conceptual-planning-agent tasks attached in parallel
+- Phase 3: synthesis command attaches its internal tasks
+- Orchestrator **executes these attached tasks** sequentially (Phase 1, 3) or in parallel (Phase 2)
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
 
 **Execution Model - Auto-Continue Workflow**:
 
 This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
 
 1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
-2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
-3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
-4. **Phase 3 executes** → Synthesis command → Reports final summary
+2. **Phase 1 executes** → artifacts command (tasks ATTACHED) → Auto-continues
+3. **Phase 2 executes** → Parallel role agents (N tasks ATTACHED concurrently) → Auto-continues
+4. **Phase 3 executes** → Synthesis command (tasks ATTACHED) → Reports final summary
 
 **Auto-Continue Mechanism**:
-- TodoList tracks current phase status
-- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
-- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
-- Progress updates shown at each phase for visibility
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When Phase 1 (artifacts) finishes executing, automatically load roles and launch Phase 2 agents
+- When Phase 2 (all agents) finishes executing, automatically execute Phase 3 synthesis
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -32,23 +42,26 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
 3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite after every phase completion
-6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **Task Attachment Model**: SlashCommand and Task invocations **attach** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
+8. **Parallel Execution**: Phase 2 attaches multiple agent tasks simultaneously for concurrent execution
 
 ## Usage
 
 ```bash
-/workflow:brainstorm:auto-parallel "<topic>" [--count N]
+/workflow:brainstorm:auto-parallel "<topic>" [--count N] [--style-skill package-name]
 ```
 
 **Recommended Structured Format**:
 ```bash
-/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
+/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name]
 ```
 
 **Parameters**:
 - `topic` (required): Topic or challenge description (structured format recommended)
 - `--count N` (optional): Number of roles to select (default: 3, max: 9)
+- `--style-skill package-name` (optional): Style SKILL package to load for UI design (located at `.claude/skills/style-{package-name}/`)
 
 ## 3-Phase Execution
 
@@ -74,15 +87,37 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 - workflow-session.json contains selected_roles[] (metadata only, no content duplication)
 - Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
 
-**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1.1: Topic analysis and question generation (artifacts)", "status": "in_progress", "activeForm": "Analyzing topic"},
+  {"content": "Phase 1.2: Role selection and user confirmation (artifacts)", "status": "pending", "activeForm": "Selecting roles"},
+  {"content": "Phase 1.3: Role questions and user decisions (artifacts)", "status": "pending", "activeForm": "Collecting role questions"},
+  {"content": "Phase 1.4: Conflict detection and resolution (artifacts)", "status": "pending", "activeForm": "Resolving conflicts"},
+  {"content": "Phase 1.5: Guidance specification generation (artifacts)", "status": "pending", "activeForm": "Generating guidance"},
+  {"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
 
-**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
+**Note**: SlashCommand invocation **attaches** artifacts' 5 internal tasks. Orchestrator **executes** these tasks sequentially.
 
-**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
-- Marking parent task "Execute artifacts..." as in_progress
-- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
-- PRESERVING all other auto-parallel tasks (role agents, synthesis)
-- When artifacts Phase 5 completes, marking parent task as completed
+**Next Action**: Tasks attached → **Execute Phase 1.1-1.5** sequentially
+
+**TodoWrite Update (Phase 1 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed to summary.
+
+**After Phase 1**: Auto-continue to Phase 2 (parallel role agent execution)
 
 ---
 
@@ -116,6 +151,12 @@ TOPIC: {user-provided-topic}
    - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context (contains original user prompt as PRIMARY reference)
 
+4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists)
+   - Action: Load style SKILL package for design system reference
+   - Command: Read(.claude/skills/style-{style_skill_package}/SKILL.md) AND Read(.workflow/reference_style/{style_skill_package}/design-tokens.json)
+   - Output: style_skill_content, design_tokens
+   - Usage: Apply design tokens in ui-designer analysis and artifacts
+
 ## Analysis Requirements
 **Primary Reference**: Original user prompt from workflow-session.json is authoritative
 **Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
@@ -143,8 +184,9 @@ TOPIC: {user-provided-topic}
 
 **Parallel Execution**:
 - Launch N agents simultaneously (one message with multiple Task calls)
+- Each agent task **attached** to orchestrator's TodoWrite
+- All agents execute concurrently, each attaching their own analysis sub-tasks
 - Each agent operates independently reading same guidance-specification.md
-- All agents update progress concurrently
 
 **Input**:
 - `selected_roles[]` from Phase 1
@@ -158,7 +200,33 @@ TOPIC: {user-provided-topic}
 - **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
 - All N role analyses completed
 
-**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
+**TodoWrite Update (Phase 2 agents invoked - tasks attached in parallel)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2.1: Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "Phase 2.2: Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Phase 2.3: Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Multiple Task invocations **attach** N role analysis tasks simultaneously. Orchestrator **executes** these tasks in parallel.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.N** concurrently
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 2 parallel tasks completed and collapsed to summary.
 
 **After Phase 2**: Auto-continue to Phase 3 (synthesis)
 
@@ -180,7 +248,33 @@ TOPIC: {user-provided-topic}
 - `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
 - Synthesis references all role analyses
 
-**TodoWrite**: Mark phase 3 completed
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3.1: Load role analysis files (synthesis)", "status": "in_progress", "activeForm": "Loading role analyses"},
+  {"content": "Phase 3.2: Integrate insights across roles (synthesis)", "status": "pending", "activeForm": "Integrating insights"},
+  {"content": "Phase 3.3: Generate synthesis specification (synthesis)", "status": "pending", "activeForm": "Generating synthesis"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** synthesis' internal tasks. Orchestrator **executes** these tasks sequentially.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "completed", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 **Return to User**:
 ```
@@ -195,49 +289,49 @@ Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
-  {"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
-  {"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
-  // Role agent tasks added dynamically after Phase 1 based on selected_roles count
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for parallel brainstorming workflow with interactive framework generation and concurrent role analysis.
 
-// After Phase 1 (artifacts completes, roles loaded)
-// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
-TodoWrite({todos: [
-  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
-  {"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
-  {"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
-  // ... (N role tasks based on --count parameter)
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+### Key Principles
 
-// After Phase 2 (all agents launched in parallel)
-TodoWrite({todos: [
-  // ... previous completed tasks
-  {"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
-  // ... (all N agents in_progress simultaneously)
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+1. **Task Attachment** (when SlashCommand/Task invoked):
+   - Sub-command's or agent's internal tasks are **attached** to orchestrator's TodoWrite
+   - Phase 1: `/workflow:brainstorm:artifacts` attaches 5 internal tasks (Phase 1.1-1.5)
+   - Phase 2: Multiple `Task(conceptual-planning-agent)` calls attach N role analysis tasks simultaneously
+   - Phase 3: `/workflow:brainstorm:synthesis` attaches 3 internal tasks (Phase 3.1-3.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks (sequentially for Phase 1, 3; in parallel for Phase 2)
 
-// After Phase 2 (all agents complete)
-TodoWrite({todos: [
-  // ... previous completed tasks
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
-  {"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
-]})
-```
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 1.1-1.5 collapse to "Execute artifacts interactive framework generation: completed"
+   - Phase 2: Multiple role tasks collapse to "Execute parallel role analysis: completed"
+   - Phase 3: Synthesis tasks collapse to "Execute synthesis integration: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase 1 invoked (artifacts tasks ATTACHED) → Artifacts sub-tasks executed → Phase 1 completed (tasks COLLAPSED) → Phase 2 invoked (N role tasks ATTACHED in parallel) → Role analyses executed concurrently → Phase 2 completed (tasks COLLAPSED) → Phase 3 invoked (synthesis tasks ATTACHED) → Synthesis sub-tasks executed → Phase 3 completed (tasks COLLAPSED) → Workflow complete.
+
+### Brainstorming Workflow Specific Features
+
+- **Phase 1**: Interactive framework generation with user Q&A (SlashCommand attachment)
+- **Phase 2**: Parallel role analysis execution with N concurrent agents (Task agent attachments)
+- **Phase 3**: Cross-role synthesis integration (SlashCommand attachment)
+- **Dynamic Role Count**: `--count N` parameter determines number of Phase 2 parallel tasks (default: 3, max: 9)
+- **Mixed Execution**: Sequential (Phase 1, 3) and Parallel (Phase 2) task execution
+
+**Benefits**:
+- Real-time visibility into attached tasks during execution
+- Clean orchestrator-level summary after tasks complete
+- Clear mental model: SlashCommand/Task = attach tasks, not delegate work
+- Parallel execution support for concurrent role analysis
+- Dynamic attachment/collapse maintains clarity
+
+**Note**: See individual Phase descriptions (Phase 1, 2, 3) for detailed TodoWrite Update examples with full JSON structures.
 
 ## Input Processing
 
@@ -255,6 +349,34 @@ ELSE:
 EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 ```
 
+**Style-Skill Parameter Parsing**:
+```javascript
+// Extract --style-skill from user input
+IF user_input CONTAINS "--style-skill":
+    EXTRACT style_skill_name FROM "--style-skill package-name" pattern
+
+    // Validate SKILL package exists
+    skill_path = ".claude/skills/style-{style_skill_name}/SKILL.md"
+    IF file_exists(skill_path):
+        style_skill_package = style_skill_name
+        style_reference_path = ".workflow/reference_style/{style_skill_name}"
+        echo("✓ Style SKILL package found: style-{style_skill_name}")
+        echo("  Design reference: {style_reference_path}")
+    ELSE:
+        echo("⚠ WARNING: Style SKILL package not found: {style_skill_name}")
+        echo("  Expected location: {skill_path}")
+        echo("  Continuing without style reference...")
+        style_skill_package = null
+ELSE:
+    style_skill_package = null
+    echo("No style-skill specified, ui-designer will use default workflow")
+
+// Store for Phase 2 ui-designer context
+CONTEXT_VARS:
+    - style_skill_package: {style_skill_package}
+    - style_reference_path: {style_reference_path}
+```
+
 **Topic Structuring**:
 1. **Already Structured** → Pass directly to artifacts
    ```
@@ -287,15 +409,17 @@ EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 
 **Phase 1 Output**:
 - `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
-- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
+- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
 
 **Phase 2 Output**:
 - `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
+- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
 
 **Phase 3 Output**:
 - `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
 
 **⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
+**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.claude/skills/style-{package-name}/`
 
 ## Available Roles
 

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

@@ -0,0 +1,962 @@
+---
+name: lite-plan
+description: Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation
+argument-hint: "[--tool claude|gemini|qwen|codex] [--quick] \"task description\"|file.md"
+allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)
+timeout: 180000
+color: cyan
+---
+
+# Workflow Lite-Plan Command (/workflow:lite-plan)
+
+## Overview
+
+Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity.
+
+**Key Characteristics**:
+- Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning
+- Smart Exploration: Calls cli-explore-agent only when task requires codebase context
+- Interactive Clarification: Asks user for more information after exploration if needed
+- Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent
+- Two-Dimensional Confirmation: User confirms task + selects execution method in one step
+- Direct Execution: Immediately starts execution (agent or CLI) after confirmation
+- Live Progress Tracking: Uses TodoWrite to track execution progress in real-time
+
+## Core Functionality
+
+- **Intelligent Task Analysis**: Automatically determines if exploration/planning agents are needed
+- **Dynamic Exploration**: Calls cli-explore-agent only when task requires codebase understanding
+- **Interactive Clarification**: Asks follow-up questions after exploration to gather missing information
+- **Adaptive Planning**:
+  - Simple tasks: Direct planning by current Claude
+  - Complex tasks: Delegates to cli-planning-agent for detailed breakdown
+- **Two-Dimensional Confirmation**: Single user interaction for task approval + execution method selection
+- **Direct Execution**: Immediate dispatch to selected execution method (agent or CLI)
+- **Live Progress Tracking**: Real-time TodoWrite updates during execution
+
+## Comparison with Other Commands
+
+| Feature | lite-plan | /cli:mode:plan | /workflow:plan |
+|---------|-----------|----------------|----------------|
+| Workflow Adaptation | Dynamic (intelligent) | Fixed | Fixed |
+| Code Exploration | Smart (when needed) | No | Always (context-search) |
+| Clarification | Yes (interactive) | No | No |
+| Planning Strategy | Adaptive (simple/complex) | Fixed template | Agent-based |
+| User Interaction | Two-dimensional | No | Minimal |
+| Direct Execution | Yes (immediate) | Yes (immediate) | No (requires /workflow:execute) |
+| Progress Tracking | Yes (TodoWrite live) | No | Yes (session-based) |
+| Execution Time | Fast (1-3 min) | Fast (2-5 min) | Slow (5-10 min) |
+| Tool Selection | User choice | --tool flag | Fixed (agent only) |
+| File Artifacts | No | No | Yes (IMPL_PLAN.md + JSON) |
+
+## Usage
+
+### Command Syntax
+```bash
+/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
+
+# Flags
+--tool <tool-name>         Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation
+--quick                    Skip code exploration phase (fast mode, completes within 60 seconds)
+
+# Arguments
+<task-description>         Task description or path to .md file (required)
+```
+
+### Usage Examples
+```bash
+# Standard planning with full interaction
+/workflow:lite-plan "Implement user authentication with JWT tokens"
+# -> Shows plan, user confirms, selects tool, immediate execution
+
+# Quick mode with preset tool
+/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance"
+# -> Skips exploration, user confirms plan, executes with Gemini
+
+# Codex direct execution preset
+/workflow:lite-plan --tool codex "Add unit tests for authentication service"
+# -> User only confirms plan, executes with Codex immediately
+
+# Agent mode with Claude
+/workflow:lite-plan "Design new API endpoints for payment processing"
+# -> User selects Claude agent, immediate execution
+```
+
+## Execution Process
+
+### Workflow Overview
+
+```
+User Input ("/workflow:lite-plan \"task\"")
+    |
+    v
+[Phase 1] Task Analysis & Exploration Decision (10-20 seconds)
+    -> Analyze task description
+    -> Decision: Need exploration? (Yes/No/--quick override)
+    -> If Yes: Launch cli-explore-agent
+    -> Output: exploration findings (if performed)
+    |
+    v
+[Phase 2] Clarification (Optional, user interaction)
+    -> If exploration revealed ambiguities or missing info
+    -> AskUserQuestion: Gather clarifications
+    -> Update task context with user responses
+    -> If no clarification needed: Skip to Phase 3
+    |
+    v
+[Phase 3] Complexity Assessment & Planning (20-60 seconds)
+    -> Assess task complexity (Low/Medium/High)
+    -> Decision: Planning strategy
+       - Low: Direct planning (current Claude)
+       - Medium/High: Delegate to cli-planning-agent
+    -> Output: Task breakdown with execution approach
+    |
+    v
+[Phase 4] Task Confirmation & Execution Selection (User interaction)
+    -> Display task breakdown and approach
+    -> AskUserQuestion: Two dimensions
+       1. Confirm task (Yes/Modify/Cancel)
+       2. Execution method (Direct/CLI)
+    -> If confirmed: Proceed to Phase 5
+    -> If modify: Re-run planning with feedback
+    -> If cancel: Exit
+    |
+    v
+[Phase 5] Execution & Progress Tracking
+    -> Create TodoWrite task list from breakdown
+    -> Launch selected execution (agent or CLI)
+    -> Track progress with TodoWrite updates
+    -> Real-time status displayed to user
+    |
+    v
+Execution Complete
+```
+
+### Task Management Pattern
+
+- TodoWrite creates task list before execution starts (Phase 5)
+- Tasks marked as in_progress/completed during execution
+- Real-time progress updates visible to user
+- No intermediate file artifacts generated
+
+## Detailed Phase Execution
+
+### Phase 1: Task Analysis & Exploration Decision
+
+**Operations**:
+- Analyze task description to determine if code exploration is needed
+- Decision logic:
+  ```javascript
+  needsExploration = (
+    task.mentions_specific_files ||
+    task.requires_codebase_context ||
+    task.needs_architecture_understanding ||
+    task.modifies_existing_code
+  ) && !flags.includes('--quick')
+  ```
+
+**Decision Criteria**:
+
+| Task Type | Needs Exploration | Reason |
+|-----------|-------------------|--------|
+| "Implement new feature X" | Maybe | Depends on integration with existing code |
+| "Refactor module Y" | Yes | Needs understanding of current implementation |
+| "Add tests for Z" | Yes | Needs to understand code structure |
+| "Create new standalone utility" | No | Self-contained, no existing code context |
+| "Update documentation" | No | Doesn't require code exploration |
+| "Fix bug in function F" | Yes | Needs to understand implementation |
+
+**If Exploration Needed**:
+- Launch cli-explore-agent with task-specific focus
+- Agent call format:
+  ```javascript
+  Task(
+    subagent_type="cli-explore-agent",
+    description="Analyze codebase for task context",
+    prompt=`
+    Task: ${task_description}
+
+    Analyze and return the following information in structured format:
+    1. Project Structure: Overall architecture and module organization
+    2. Relevant Files: List of files that will be affected by this task (with paths)
+    3. Current Implementation Patterns: Existing code patterns, conventions, and styles
+    4. Dependencies: External dependencies and internal module dependencies
+    5. Integration Points: Where this task connects with existing code
+    6. Architecture Constraints: Technical limitations or requirements
+    7. Clarification Needs: Ambiguities or missing information requiring user input
+
+    Time Limit: 60 seconds
+
+    Output Format: Return a JSON-like structured object with the above fields populated.
+    Include specific file paths, pattern examples, and clear questions for clarifications.
+    `
+  )
+  ```
+
+**Expected Return Structure**:
+```javascript
+explorationContext = {
+  project_structure: "Description of overall architecture",
+  relevant_files: ["src/auth/service.ts", "src/middleware/auth.ts", ...],
+  patterns: "Description of existing patterns (e.g., 'Uses dependency injection pattern', 'React hooks convention')",
+  dependencies: "List of dependencies and integration points",
+  integration_points: "Where this connects with existing code",
+  constraints: "Technical constraints (e.g., 'Must use existing auth library', 'No breaking changes')",
+  clarification_needs: [
+    {
+      question: "Which authentication method to use?",
+      context: "Found both JWT and Session patterns",
+      options: ["JWT tokens", "Session-based", "Hybrid approach"]
+    },
+    // ... more clarification questions
+  ]
+}
+```
+
+**Output Processing**:
+- Store exploration findings in `explorationContext`
+- Extract `clarification_needs` array from exploration results
+- Set `needsClarification = (clarification_needs.length > 0)`
+- Use clarification_needs to generate Phase 2 questions
+
+**Progress Tracking**:
+- Mark Phase 1 as completed
+- If needsClarification: Mark Phase 2 as in_progress
+- Else: Skip to Phase 3
+
+**Expected Duration**: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed)
+
+---
+
+### Phase 2: Clarification (Optional)
+
+**Skip Condition**: Only run if Phase 1 set `needsClarification = true`
+
+**Operations**:
+- Review `explorationContext.clarification_needs` from Phase 1
+- Generate AskUserQuestion based on exploration findings
+- Focus on ambiguities that affect implementation approach
+
+**AskUserQuestion Call** (simplified reference):
+```javascript
+// Use clarification_needs from exploration to build questions
+AskUserQuestion({
+  questions: explorationContext.clarification_needs.map(need => ({
+    question: `${need.context}\n\n${need.question}`,
+    header: "Clarification",
+    multiSelect: false,
+    options: need.options.map(opt => ({
+      label: opt,
+      description: `Use ${opt} approach`
+    }))
+  }))
+})
+```
+
+**Output Processing**:
+- Collect user responses and store in `clarificationContext`
+- Format: `{ question_id: selected_answer, ... }`
+- This context will be passed to Phase 3 planning
+
+**Progress Tracking**:
+- Mark Phase 2 as completed
+- Mark Phase 3 as in_progress
+
+**Expected Duration**: User-dependent (typically 30-60 seconds)
+
+---
+
+### Phase 3: Complexity Assessment & Planning
+
+**Operations**:
+- Assess task complexity based on multiple factors
+- Select appropriate planning strategy
+- Generate task breakdown using selected method
+
+**Complexity Assessment Factors**:
+```javascript
+complexityScore = {
+  file_count: exploration.files_to_modify.length,
+  integration_points: exploration.dependencies.length,
+  architecture_changes: exploration.requires_architecture_change,
+  technology_stack: exploration.unfamiliar_technologies.length,
+  task_scope: (task.estimated_steps > 5),
+  cross_cutting_concerns: exploration.affects_multiple_modules
+}
+
+// Calculate complexity
+if (complexityScore < 3) complexity = "Low"
+else if (complexityScore < 6) complexity = "Medium"
+else complexity = "High"
+```
+
+**Complexity Levels**:
+
+| Level | Characteristics | Planning Strategy |
+|-------|----------------|-------------------|
+| Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) |
+| Medium | 3-5 files, moderate integration, some ambiguity | Delegate to cli-planning-agent |
+| High | 6+ files, complex architecture, high uncertainty | Delegate to cli-planning-agent with detailed analysis |
+
+**Planning Execution**:
+
+**Option A: Direct Planning (Low Complexity)**
+```javascript
+// Current Claude generates plan directly
+planObject = {
+  summary: "Brief overview of what needs to be done",
+  approach: "Step-by-step implementation strategy",
+  tasks: [
+    "Task 1: Specific action with file references",
+    "Task 2: Specific action with file references",
+    // ... 3-5 tasks
+  ],
+  complexity: "Low",
+  estimated_time: "15-30 minutes"
+}
+```
+
+**Option B: Agent-Based Planning (Medium/High Complexity)**
+```javascript
+// Delegate to cli-planning-agent
+Task(
+  subagent_type="cli-planning-agent",
+  description="Generate detailed implementation plan",
+  prompt=`
+  Task: ${task_description}
+
+  Exploration Context:
+  ${JSON.stringify(explorationContext, null, 2)}
+
+  User Clarifications:
+  ${JSON.stringify(clarificationContext, null, 2) || "None provided"}
+
+  Complexity Level: ${complexity}
+
+  Generate a detailed implementation plan with the following components:
+
+  1. Summary: 2-3 sentence overview of the implementation
+  2. Approach: High-level implementation strategy
+  3. Task Breakdown: 5-10 specific, actionable tasks
+     - Each task should specify:
+       * What to do
+       * Which files to modify/create
+       * Dependencies on other tasks (if any)
+  4. Task Dependencies: Explicit ordering requirements (e.g., "Task 2 depends on Task 1")
+  5. Risks: Potential issues and mitigation strategies (for Medium/High complexity)
+  6. Estimated Time: Total implementation time estimate
+  7. Recommended Execution: "Direct" (agent) or "CLI" (autonomous tool)
+
+  Output Format: Return a structured object with these fields:
+  {
+    summary: string,
+    approach: string,
+    tasks: string[],
+    dependencies: string[] (optional),
+    risks: string[] (optional),
+    estimated_time: string,
+    recommended_execution: "Direct" | "CLI"
+  }
+
+  Ensure tasks are specific, with file paths and clear acceptance criteria.
+  `
+)
+
+// Agent returns detailed plan
+planObject = agent_output.parse()
+```
+
+**Expected Return Structure**:
+```javascript
+planObject = {
+  summary: "Implement JWT-based authentication system with middleware integration",
+  approach: "Create auth service layer, implement JWT utilities, add middleware, update routes",
+  tasks: [
+    "Create authentication service in src/auth/service.ts with login/logout/verify methods",
+    "Implement JWT token utilities in src/auth/jwt.ts (generate, verify, refresh)",
+    "Add authentication middleware to src/middleware/auth.ts",
+    "Update API routes in src/routes/*.ts to use auth middleware",
+    "Add integration tests for auth flow in tests/auth.test.ts"
+  ],
+  dependencies: [
+    "Task 3 depends on Task 2 (middleware needs JWT utilities)",
+    "Task 4 depends on Task 3 (routes need middleware)",
+    "Task 5 depends on Tasks 1-4 (tests need complete implementation)"
+  ],
+  risks: [
+    "Token refresh timing may conflict with existing session logic - test thoroughly",
+    "Breaking change if existing auth is in use - plan migration strategy"
+  ],
+  estimated_time: "30-45 minutes",
+  recommended_execution: "CLI"  // Based on clear requirements and straightforward implementation
+}
+```
+
+**Output Structure**:
+```javascript
+planObject = {
+  summary: "2-3 sentence overview",
+  approach: "Implementation strategy",
+  tasks: [
+    "Task 1: ...",
+    "Task 2: ...",
+    // ... 3-10 tasks based on complexity
+  ],
+  complexity: "Low|Medium|High",
+  dependencies: ["task1 -> task2", ...],  // if Medium/High
+  risks: ["risk1", "risk2", ...],         // if High
+  estimated_time: "X minutes",
+  recommended_execution: "Direct|CLI"
+}
+```
+
+**Progress Tracking**:
+- Mark Phase 3 as completed
+- Mark Phase 4 as in_progress
+
+**Expected Duration**:
+- Low complexity: 20-30 seconds (direct)
+- Medium/High complexity: 40-60 seconds (agent-based)
+
+---
+
+### Phase 4: Task Confirmation & Execution Selection
+
+**User Interaction Flow**: Two-dimensional confirmation (task + execution method)
+
+**Operations**:
+- Display plan summary with full task breakdown
+- Collect two-dimensional user input: Task confirmation + Execution method selection
+- Support modification flow if user requests changes
+
+**Question 1: Task Confirmation**
+
+Display plan to user and ask for confirmation:
+- Show: summary, approach, task breakdown, dependencies, risks, complexity, estimated time
+- Options: "Confirm" / "Modify" / "Cancel"
+- If Modify: Collect feedback via "Other" option, re-run Phase 3 with modifications
+- If Cancel: Exit workflow
+- If Confirm: Proceed to Question 2
+
+**Question 2: Execution Method Selection** (Only if task confirmed)
+
+Ask user to select execution method:
+- Show recommendation from `planObject.recommended_execution`
+- Options:
+  - "Direct - Execute with Agent" (@code-developer)
+  - "CLI - Gemini" (gemini-2.5-pro)
+  - "CLI - Codex" (gpt-5)
+  - "CLI - Qwen" (coder-model)
+- Store selection for Phase 5 execution
+
+**Simplified AskUserQuestion Reference**:
+```javascript
+// Question 1: Task Confirmation
+AskUserQuestion({
+  questions: [{
+    question: `[Display plan with all details]\n\nDo you confirm this plan?`,
+    header: "Confirm Plan",
+    options: [
+      { label: "Confirm", description: "Proceed to execution" },
+      { label: "Modify", description: "Adjust plan" },
+      { label: "Cancel", description: "Abort" }
+    ]
+  }]
+})
+
+// Question 2: Execution Method (if confirmed)
+AskUserQuestion({
+  questions: [{
+    question: `Select execution method:\n[Show recommendation and tool descriptions]`,
+    header: "Execution Method",
+    options: [
+      { label: "Direct - Agent", description: "Interactive execution" },
+      { label: "CLI - Gemini", description: "gemini-2.5-pro" },
+      { label: "CLI - Codex", description: "gpt-5" },
+      { label: "CLI - Qwen", description: "coder-model" }
+    ]
+  }]
+})
+```
+
+**Decision Flow**:
+```
+Task Confirmation:
+  ├─ Confirm → Execution Method Selection → Phase 5
+  ├─ Modify → Collect feedback → Re-run Phase 3
+  └─ Cancel → Exit (no execution)
+
+Execution Method Selection:
+  ├─ Direct - Execute with Agent → Launch @code-developer
+  ├─ CLI - Gemini → Build and execute Gemini command
+  ├─ CLI - Codex → Build and execute Codex command
+  └─ CLI - Qwen → Build and execute Qwen command
+```
+
+**Progress Tracking**:
+- Mark Phase 4 as completed
+- Mark Phase 5 as in_progress
+
+**Expected Duration**: User-dependent (1-3 minutes typical)
+
+---
+
+### Phase 5: Execution & Progress Tracking
+
+**Operations**:
+- Create TodoWrite task list from plan breakdown
+- Launch selected execution method (agent or CLI)
+- Track execution progress with real-time TodoWrite updates
+- Display status to user
+
+**Step 5.1: Create TodoWrite Task List**
+
+**Before execution starts**, create task list:
+```javascript
+TodoWrite({
+  todos: planObject.tasks.map((task, index) => ({
+    content: task,
+    status: "pending",
+    activeForm: task.replace(/^(.*?):/, "$1ing:")  // "Implement X" -> "Implementing X"
+  }))
+})
+```
+
+**Example Task List**:
+```
+[ ] Implement authentication service in src/auth/service.ts
+[ ] Create JWT token utilities in src/auth/jwt.ts
+[ ] Add authentication middleware to src/middleware/auth.ts
+[ ] Update API routes to use authentication
+[ ] Add integration tests for auth flow
+```
+
+**Step 5.2: Launch Execution**
+
+Based on user selection in Phase 4, execute appropriate method:
+
+#### Option A: Direct Execution with Agent
+
+**Operations**:
+- Launch @code-developer agent with full plan context
+- Agent receives exploration findings, clarifications, and task breakdown
+- Agent call format:
+  ```javascript
+  Task(
+    subagent_type="code-developer",
+    description="Implement planned tasks with progress tracking",
+    prompt=`
+    Implement the following tasks with TodoWrite progress updates:
+
+    Summary: ${planObject.summary}
+
+    Task Breakdown:
+    ${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
+
+    ${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
+
+    Implementation Approach:
+    ${planObject.approach}
+
+    Code Context:
+    ${explorationContext || "No exploration performed"}
+
+    ${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''}
+
+    ${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''}
+
+    IMPORTANT Instructions:
+    - Update TodoWrite as you complete each task (mark as completed)
+    - Follow task dependencies if specified
+    - Implement tasks in sequence unless independent
+    - Test functionality as you go
+    - Handle risks proactively
+    `
+  )
+  ```
+
+**Agent Responsibilities**:
+- Mark tasks as in_progress when starting
+- Mark tasks as completed when finished
+- Update TodoWrite in real-time for user visibility
+
+#### Option B: CLI Execution (Gemini/Codex/Qwen)
+
+**Operations**:
+- Build CLI command with comprehensive context
+- Execute CLI tool with write permissions
+- Monitor CLI output and update TodoWrite based on progress indicators
+- Parse CLI completion signals to mark tasks as done
+
+**Command Format (Gemini)** - Full context with exploration and clarifications:
+```bash
+gemini -p "
+PURPOSE: Implement planned tasks with full context from exploration and planning
+TASK:
+${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
+
+MODE: write
+
+CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow
+
+## Exploration Findings
+${explorationContext ? `
+Project Structure:
+${explorationContext.project_structure || 'Not available'}
+
+Relevant Files:
+${explorationContext.relevant_files?.join('\n') || 'Not specified'}
+
+Current Implementation Patterns:
+${explorationContext.patterns || 'Not analyzed'}
+
+Dependencies and Integration Points:
+${explorationContext.dependencies || 'Not specified'}
+
+Architecture Constraints:
+${explorationContext.constraints || 'None identified'}
+` : 'No exploration performed (task did not require codebase context)'}
+
+## User Clarifications
+${clarificationContext ? `
+The following clarifications were provided by the user after exploration:
+${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')}
+` : 'No clarifications needed'}
+
+## Implementation Plan Context
+Task Summary: ${planObject.summary}
+
+Implementation Approach:
+${planObject.approach}
+
+${planObject.dependencies ? `
+Task Dependencies (execute in order):
+${planObject.dependencies.join('\n')}
+` : ''}
+
+${planObject.risks ? `
+Identified Risks:
+${planObject.risks.join('\n')}
+` : ''}
+
+Complexity Level: ${planObject.complexity}
+Estimated Time: ${planObject.estimated_time}
+
+EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing
+
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE
+" -m gemini-2.5-pro --approval-mode yolo
+```
+
+**Command Format (Codex)** - Session-based with resume support:
+
+**First Execution (Establish Session)**:
+```bash
+codex --full-auto exec "
+TASK: ${planObject.summary}
+
+## Task Breakdown
+${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
+
+${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}
+
+## Implementation Approach
+${planObject.approach}
+
+## Code Context from Exploration
+${explorationContext ? `
+Project Structure: ${explorationContext.project_structure || 'Standard structure'}
+Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
+Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
+Integration Points: ${explorationContext.dependencies || 'None specified'}
+Constraints: ${explorationContext.constraints || 'None'}
+` : 'No prior exploration - analyze codebase as needed'}
+
+${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
+
+${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''}
+
+## Execution Instructions
+- Complete all tasks following the breakdown sequence
+- Respect task dependencies if specified
+- Test functionality as you implement
+- Handle identified risks proactively
+- Create session for potential resume if needed
+
+Complexity: ${planObject.complexity}
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+**Subsequent Executions (Resume if needed)**:
+```bash
+# If first execution fails or is interrupted, can resume:
+codex --full-auto exec "
+Continue implementation from previous session.
+
+Remaining tasks:
+${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
+
+Maintain context from previous execution.
+" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+**Codex Session Strategy**:
+- First execution establishes full context and creates session
+- If execution is interrupted or fails, use `resume --last` to continue
+- Resume inherits all context from original execution
+- Useful for complex tasks that may hit timeouts or require iteration
+
+**Command Format (Qwen)** - Full context similar to Gemini:
+```bash
+qwen -p "
+PURPOSE: Implement planned tasks with comprehensive context
+
+TASK:
+${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
+
+MODE: write
+
+CONTEXT: @**/* | Memory: Full implementation context from lite-plan
+
+## Code Exploration Results
+${explorationContext ? `
+Analyzed Project Structure:
+${explorationContext.project_structure || 'Standard structure'}
+
+Key Files to Modify:
+${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'}
+
+Existing Code Patterns:
+${explorationContext.patterns || 'Follow codebase conventions'}
+
+Dependencies:
+${explorationContext.dependencies || 'None specified'}
+
+Constraints:
+${explorationContext.constraints || 'None identified'}
+` : 'No exploration performed - analyze codebase patterns as you implement'}
+
+## Clarifications from User
+${clarificationContext ? `
+${Object.entries(clarificationContext).map(([question, answer]) => `
+Question: ${question}
+Answer: ${answer}
+`).join('\n')}
+` : 'No additional clarifications provided'}
+
+## Implementation Strategy
+Summary: ${planObject.summary}
+
+Approach:
+${planObject.approach}
+
+${planObject.dependencies ? `
+Task Order (follow sequence):
+${planObject.dependencies.join('\n')}
+` : ''}
+
+${planObject.risks ? `
+Risk Mitigation:
+${planObject.risks.join('\n')}
+` : ''}
+
+Task Complexity: ${planObject.complexity}
+Time Estimate: ${planObject.estimated_time}
+
+EXPECTED: Complete implementation with tests and proper error handling
+
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE
+" -m coder-model --approval-mode yolo
+```
+
+**Execution with Progress Tracking**:
+```javascript
+// Launch CLI in background
+bash_result = Bash(
+  command=cli_command,
+  timeout=600000,  // 10 minutes
+  run_in_background=true
+)
+
+// Monitor output and update TodoWrite
+// Parse CLI output for task completion indicators
+// Update TodoWrite when tasks complete
+// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed
+```
+
+**CLI Progress Monitoring**:
+- Parse CLI output for completion keywords ("done", "complete", "✓", etc.)
+- Update corresponding TodoWrite tasks based on progress
+- Provide real-time visibility to user
+
+**Step 5.3: Track Execution Progress**
+
+**Real-time TodoWrite Updates**:
+```javascript
+// As execution progresses, update task status:
+
+// Task started
+TodoWrite({
+  todos: [
+    { content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
+    { content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
+    // ...
+  ]
+})
+
+// Task completed
+TodoWrite({
+  todos: [
+    { content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
+    { content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
+    // ...
+  ]
+})
+```
+
+**User Visibility**:
+- User sees real-time task progress
+- Current task highlighted as "in_progress"
+- Completed tasks marked with checkmark
+- Pending tasks remain unchecked
+
+**Progress Tracking**:
+- Mark Phase 5 as in_progress throughout execution
+- Mark Phase 5 as completed when all tasks done
+- Final status summary displayed to user
+
+**Expected Duration**: Varies by task complexity and execution method
+- Low complexity: 5-15 minutes
+- Medium complexity: 15-45 minutes
+- High complexity: 45-120 minutes
+
+---
+
+## Best Practices
+
+### Workflow Intelligence
+
+1. **Dynamic Adaptation**: Workflow automatically adjusts based on task characteristics
+   - Smart exploration: Only runs when task requires codebase context
+   - Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent
+   - Context-aware clarification: Only asks questions when truly needed
+   - Reduces unnecessary steps while maintaining thoroughness
+
+2. **Progressive Clarification**: Gather information at the right time
+   - Phase 1: Explore codebase to understand current state
+   - Phase 2: Ask clarifying questions based on exploration findings
+   - Phase 3: Plan with complete context (task + exploration + clarifications)
+   - Avoids premature assumptions and reduces rework
+
+3. **Complexity-Aware Planning**: Planning strategy matches task complexity
+   - Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s)
+   - Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s)
+   - High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s)
+   - Balances speed and thoroughness appropriately
+
+4. **Two-Dimensional Confirmation**: Separate task approval from execution method
+   - First dimension: Confirm/Modify/Cancel plan
+   - Second dimension: Direct execution vs CLI execution
+   - Allows plan refinement without re-selecting execution method
+   - Supports iterative planning with user feedback
+
+### Task Management
+
+1. **Live Progress Tracking**: TodoWrite provides real-time execution visibility
+   - Tasks created before execution starts
+   - Updated in real-time as work progresses
+   - User sees current task being worked on
+   - Clear completion status throughout execution
+
+2. **Phase-Based Organization**: 5 distinct phases with clear transitions
+   - Phase 1: Task Analysis & Exploration (automatic)
+   - Phase 2: Clarification (conditional, interactive)
+   - Phase 3: Planning (automatic, adaptive)
+   - Phase 4: Confirmation (interactive, two-dimensional)
+   - Phase 5: Execution & Tracking (automatic with live updates)
+
+3. **Flexible Task Counts**: Task breakdown adapts to complexity
+   - Low complexity: 3-5 tasks (focused)
+   - Medium complexity: 5-7 tasks (detailed)
+   - High complexity: 7-10 tasks (comprehensive)
+   - Avoids artificial constraints while maintaining focus
+
+4. **Dependency Tracking**: Medium/High complexity tasks include dependencies
+   - Explicit task ordering when sequence matters
+   - Parallel execution hints when tasks are independent
+   - Risk flagging for complex interactions
+   - Helps agent/CLI execute correctly
+
+### Planning Standards
+
+1. **Context-Rich Planning**: Plans include all relevant context
+   - Exploration findings (code structure, patterns, constraints)
+   - User clarifications (requirements, preferences, decisions)
+   - Complexity assessment (risks, dependencies, time estimates)
+   - Execution recommendations (Direct vs CLI, specific tool)
+
+2. **Modification Support**: Plans can be iteratively refined
+   - User can request plan modifications in Phase 4
+   - Feedback incorporated into re-planning
+   - No need to restart from scratch
+   - Supports collaborative planning workflow
+
+3. **No File Artifacts**: All planning stays in memory
+   - Faster workflow without I/O overhead
+   - Cleaner workspace
+   - Plan context passed directly to execution
+   - Reduces complexity and maintenance
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Phase 1 Exploration Failure | cli-explore-agent unavailable or timeout | Skip exploration, set `explorationContext = null`, log warning, continue to Phase 2/3 with task description only |
+| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is without clarification, proceed to Phase 3 with warning |
+| Phase 3 Planning Agent Failure | cli-planning-agent unavailable or timeout | Fallback to direct planning by current Claude (simplified plan), continue to Phase 4 |
+| Phase 3 Planning Timeout | Planning takes > 90 seconds | Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail |
+| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save plan context to temporary var, display resume instructions, exit gracefully |
+| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using /workflow:plan for comprehensive planning |
+| Phase 5 CLI Tool Unavailable | Selected CLI tool not installed | Show installation instructions, offer to re-select (Direct execution or different CLI) |
+| Phase 5 Execution Failure | Agent/CLI crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry |
+
+## Input/Output
+
+### Input Requirements
+- Task description: String or path to .md file (required)
+  - Should be specific and concrete
+  - Can include context about existing code or requirements
+  - Examples:
+    - "Implement user authentication with JWT tokens"
+    - "Refactor logging module for better performance"
+    - "Add unit tests for authentication service"
+- Flags (optional):
+  - `--tool <name>`: Preset execution tool (claude|gemini|codex|qwen)
+  - `--quick`: Skip code exploration phase
+
+### Output Format
+
+**In-Memory Plan Object**:
+```javascript
+{
+  summary: "2-3 sentence overview of implementation",
+  approach: "High-level implementation strategy",
+  tasks: [
+    "Task 1: Specific action with file locations",
+    "Task 2: Specific action with file locations",
+    // ... 3-7 tasks total
+  ],
+  complexity: "Low|Medium|High",
+  recommended_tool: "Claude|Gemini|Codex|Qwen",
+  estimated_time: "X minutes"
+}
+```
+
+**Execution Result**:
+- Immediate dispatch to selected tool/agent with plan context
+- No file artifacts generated during planning phase
+- Execution starts immediately after user confirmation
+- Tool/agent handles implementation and any necessary file operations
+

.claude/commands/workflow/plan.md

@@ -22,11 +22,19 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
 5. **Phase 4 executes** → Task generation (task-generate-agent) → Reports final summary
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
 **Auto-Continue Mechanism**:
-- TodoList tracks current phase status
-- After each phase completion, automatically executes next pending phase
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
 - All phases run autonomously without user interaction (clarification handled in brainstorm phase)
 - Progress updates shown at each phase for visibility
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -34,8 +42,9 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 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/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
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 5-Phase Execution
 
@@ -84,9 +93,35 @@ CONTEXT: Existing user database schema, REST API endpoints
 - Context package path extracted
 - File exists and is valid JSON
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+<!-- TodoWrite: When context-gather invoked, INSERT 3 context-gather tasks, mark first as in_progress -->
 
-**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2.1: Analyze codebase structure (context-gather)", "status": "in_progress", "activeForm": "Analyzing codebase structure"},
+  {"content": "Phase 2.2: Identify integration points (context-gather)", "status": "pending", "activeForm": "Identifying integration points"},
+  {"content": "Phase 2.3: Generate context package (context-gather)", "status": "pending", "activeForm": "Generating context package"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** context-gather's 3 tasks. Orchestrator **executes** these tasks sequentially.
+
+<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3/4 (depending on conflict_risk)
 
 ---
 
@@ -112,7 +147,35 @@ CONTEXT: Existing user database schema, REST API endpoints
 - If conflict_risk is "none" or "low", skip directly to Phase 3.5
 - Display: "No significant conflicts detected, proceeding to clarification"
 
-**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
+<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "Phase 3.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "Phase 3.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks sequentially.
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 **After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
 
@@ -173,7 +236,35 @@ SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]
 - `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
 - `.workflow/[sessionId]/TODO_LIST.md` exists
 
-**TodoWrite**: Mark phase 4 completed
+<!-- TodoWrite: When task-generate-agent invoked, INSERT 3 task-generate-agent tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 4.1: Discovery - analyze requirements (task-generate-agent)", "status": "in_progress", "activeForm": "Analyzing requirements"},
+  {"content": "Phase 4.2: Planning - design tasks (task-generate-agent)", "status": "pending", "activeForm": "Designing tasks"},
+  {"content": "Phase 4.3: Output - generate JSONs (task-generate-agent)", "status": "pending", "activeForm": "Generating task JSONs"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** task-generate-agent's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "completed", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 **Return to User**:
 ```
@@ -191,39 +282,37 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (before Phase 1)
-// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  // Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
-  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for real-time visibility into workflow execution.
 
-// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
-  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
-]})
+### Key Principles
 
-// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
-]})
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-// After Phase 3 (if executed), continue to Phase 4
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
-  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
-]})
-```
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Execute context gathering: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+### Benefits
+
+- ✓ Real-time visibility into sub-task execution
+- ✓ Clear mental model: SlashCommand = attach → execute → collapse
+- ✓ Clean summary after completion
+- ✓ Easy to track workflow progress
+
+**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
 
 ## Input Processing
 
@@ -304,6 +393,55 @@ Return summary to user
 - **Traceability**: Easy to track what was requested
 - **Precision**: Better context gathering and analysis
 
+## Execution Flow Diagram
+
+```
+User triggers: /workflow:plan "Build authentication system"
+  ↓
+[TodoWrite Init] 3 orchestrator-level tasks
+  ↓
+Phase 1: Session Discovery
+  → sessionId extracted
+  ↓
+Phase 2: Context Gathering (SlashCommand invoked)
+  → ATTACH 3 tasks: ← ATTACHED
+    - Phase 2.1: Analyze codebase structure
+    - Phase 2.2: Identify integration points
+    - Phase 2.3: Generate context package
+  → Execute Phase 2.1-2.3
+  → COLLAPSE tasks ← COLLAPSED
+  → contextPath + conflict_risk extracted
+  ↓
+Conditional Branch: Check conflict_risk
+  ├─ IF conflict_risk ≥ medium:
+  │   Phase 3: Conflict Resolution (SlashCommand invoked)
+  │     → ATTACH 3 tasks: ← ATTACHED
+  │       - Phase 3.1: Detect conflicts with CLI analysis
+  │       - Phase 3.2: Present conflicts to user
+  │       - Phase 3.3: Apply resolution strategies
+  │     → Execute Phase 3.1-3.3
+  │     → COLLAPSE tasks ← COLLAPSED
+  │
+  └─ ELSE: Skip Phase 3, proceed to Phase 4
+  ↓
+Phase 4: Task Generation (SlashCommand invoked)
+  → ATTACH 3 tasks: ← ATTACHED
+    - Phase 4.1: Discovery - analyze requirements
+    - Phase 4.2: Planning - design tasks
+    - Phase 4.3: Output - generate JSONs
+  → Execute Phase 4.1-4.3
+  → COLLAPSE tasks ← COLLAPSED
+  → Outputs: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
+  ↓
+Return summary to user
+```
+
+**Key Points**:
+- **← ATTACHED**: Sub-tasks attached to TodoWrite when SlashCommand invoked
+- **← COLLAPSED**: Sub-tasks collapsed to summary after completion
+- **Conditional Branch**: Phase 3 only executes if conflict_risk ≥ medium
+- **Continuous Flow**: No user intervention between phases
+
 ## Error Handling
 
 - **Parsing Failure**: If output parsing fails, retry command once, then report error
@@ -320,7 +458,7 @@ Return summary to user
 - Parse context path from Phase 2 output, store in memory
 - **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
 - **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
-- Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
+- Wait for Phase 3 to finish executing (if executed), verify CONFLICT_RESOLUTION.md created
 - **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
 - **Build Phase 4 command**:
   - Base command: `/workflow:tools:task-generate-agent --session [sessionId]`

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

@@ -9,21 +9,35 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 5 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation.
+**This command is a pure orchestrator**: Execute 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
 
 **Execution Modes**:
 - **Agent Mode** (default): Use `/workflow:tools:task-generate-tdd` (autonomous agent-driven)
 - **CLI Mode** (`--cli-execute`): Use `/workflow:tools:task-generate-tdd --cli-execute` (Gemini/Qwen)
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 ## Core Rules
 
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data for next phase
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite after every phase completion
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 6. **TDD Context**: All descriptions include "TDD:" prefix
-7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
+7. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+8. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 6-Phase Execution (with Conflict Resolution)
 
@@ -85,9 +99,41 @@ TEST_FOCUS: [Test scenarios]
 - Prevents duplicate test creation
 - Enables integration with existing tests
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
 
-**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3.1: Detect test framework and conventions (test-context-gather)", "status": "in_progress", "activeForm": "Detecting test framework"},
+  {"content": "Phase 3.2: Analyze existing test coverage (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "Phase 3.3: Identify coverage gaps (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
+
+**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4/5 (depending on conflict_risk)
 
 ---
 
@@ -113,7 +159,41 @@ TEST_FOCUS: [Test scenarios]
 - If conflict_risk is "none" or "low", skip directly to Phase 5
 - Display: "No significant conflicts detected, proceeding to TDD task generation"
 
-**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
+<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "Phase 4.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "Phase 4.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 **After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
 
@@ -145,6 +225,40 @@ TEST_FOCUS: [Test scenarios]
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 - Task count ≤10 (compliance with task limit)
 
+<!-- TodoWrite: When task-generate-tdd invoked, INSERT 3 task-generate-tdd tasks -->
+
+**TodoWrite Update (Phase 5 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 5.1: Discovery - analyze TDD requirements (task-generate-tdd)", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
+  {"content": "Phase 5.2: Planning - design Red-Green-Refactor cycles (task-generate-tdd)", "status": "pending", "activeForm": "Designing TDD cycles"},
+  {"content": "Phase 5.3: Output - generate IMPL tasks with internal TDD phases (task-generate-tdd)", "status": "pending", "activeForm": "Generating TDD tasks"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** task-generate-tdd's 3 tasks. Orchestrator **executes** these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.
+
+**Next Action**: Tasks attached → **Execute Phase 5.1-5.3** sequentially
+
+<!-- TodoWrite: After Phase 5 tasks complete, REMOVE Phase 5.1-5.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 5 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "completed", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "in_progress", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 5 tasks completed and collapsed to summary. Each generated IMPL task contains complete Red-Green-Refactor cycle internally.
+
 ### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
@@ -202,45 +316,90 @@ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
-  // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
-  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for TDD workflow with test coverage analysis and Red-Green-Refactor cycle generation.
 
-// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
-  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+### Key Principles
 
-// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 3.1, 3.2, 3.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-// After Phase 4 (if executed), continue to Phase 5
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
-  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 3.1-3.3 collapse to "Execute test coverage analysis: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.
+
+### TDD-Specific Features
+
+- **Phase 3**: Test coverage analysis detects existing patterns and gaps
+- **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles
+- **Conditional Phase 4**: Conflict resolution only if conflict_risk ≥ medium
+
+### Benefits
+
+- ✓ Real-time visibility into TDD workflow execution
+- ✓ Clear mental model: SlashCommand = attach → execute → collapse
+- ✓ Test-aware planning with coverage analysis
+- ✓ Self-contained TDD cycles within each IMPL task
+
+**Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.
+
+## Execution Flow Diagram
+
+```
+TDD Workflow Orchestrator
+│
+├─ Phase 1: Session Discovery
+│  └─ /workflow:session:start --auto
+│     └─ Returns: sessionId
+│
+├─ Phase 2: Context Gathering
+│  └─ /workflow:tools:context-gather
+│     └─ Returns: context-package.json path
+│
+├─ Phase 3: Test Coverage Analysis                    ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-context-gather
+│     ├─ Phase 3.1: Detect test framework
+│     ├─ Phase 3.2: Analyze existing test coverage
+│     └─ Phase 3.3: Identify coverage gaps
+│     └─ Returns: test-context-package.json           ← COLLAPSED
+│
+├─ Phase 4: Conflict Resolution (conditional)
+│  IF conflict_risk ≥ medium:
+│  └─ /workflow:tools:conflict-resolution             ← ATTACHED (3 tasks)
+│     ├─ Phase 4.1: Detect conflicts with CLI
+│     ├─ Phase 4.2: Present conflicts to user
+│     └─ Phase 4.3: Apply resolution strategies
+│     └─ Returns: CONFLICT_RESOLUTION.md              ← COLLAPSED
+│  ELSE:
+│  └─ Skip to Phase 5
+│
+├─ Phase 5: TDD Task Generation                       ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:task-generate-tdd
+│     ├─ Phase 5.1: Discovery - analyze TDD requirements
+│     ├─ Phase 5.2: Planning - design Red-Green-Refactor cycles
+│     └─ Phase 5.3: Output - generate IMPL tasks with internal TDD phases
+│     └─ Returns: IMPL-*.json, IMPL_PLAN.md           ← COLLAPSED
+│        (Each IMPL task contains internal Red-Green-Refactor cycle)
+│
+└─ Phase 6: TDD Structure Validation
+   └─ Internal validation + summary returned
+   └─ Recommend: /workflow:action-plan-verify
+
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
+• TDD-specific: Each generated IMPL task contains complete Red-Green-Refactor cycle
 ```
 
 ## Input Processing

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

@@ -1,6 +1,6 @@
 ---
 name: test-cycle-execute
-description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.
 argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ---
@@ -10,10 +10,13 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ## Overview
 Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
 
+**Quality Gate**: Iterates until test pass rate >= 95% (with criticality assessment) or 100% for full approval.
+
 **CRITICAL - Orchestrator Boundary**:
 - This command is the **ONLY place** where test failures are handled
-- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
-- Agents (@test-fix-agent) only execute single tasks and return results
+- All failure analysis and fix task generation delegated to **@cli-planning-agent**
+- Orchestrator calculates pass rate, assesses criticality, and manages iteration loop
+- @test-fix-agent executes tests and applies fixes, reports results back
 - **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
@@ -35,44 +38,53 @@ Orchestrates dynamic test-fix workflow execution through iterative cycles of tes
 
 ### 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
+- **@test-fix-agent**: Executes tests, applies fixes, validates results, assigns criticality
+- **@cli-planning-agent**: Executes CLI analysis (Gemini/Qwen), parses results, generates fix task JSONs
 
 ## 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
+1. **Dynamic Task Generation**: Create intermediate fix tasks via @cli-planning-agent based on test failures
+2. **Iterative Execution**: Repeat test-fix cycles until pass rate >= 95% (with criticality assessment) or max iterations
+3. **Pass Rate Threshold**: Target 95%+ pass rate; 100% for full approval; assess criticality for 95-100% range
+4. **Agent-Based Analysis**: Delegate CLI execution and task generation to @cli-planning-agent
+5. **Agent Delegation**: All execution delegated to specialized agents (@cli-planning-agent, @test-fix-agent)
+6. **Context Accumulation**: Each iteration builds on previous attempt context
+7. **Autonomous Completion**: Continue until pass rate >= 95% 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
+- **Pass Rate Calculation**: Calculate test pass rate from test-results.json (passed/total * 100)
+- **Criticality Assessment**: Evaluate failure severity using test-results.json criticality field
+- **Threshold Decision**: Determine if pass rate >= 95% with criticality consideration
+- **Failure Analysis Delegation**: Invoke @cli-planning-agent for CLI analysis and task generation
+- **Iteration Control**: Manage fix cycles with max iteration limits (5 default)
+- **Context Propagation**: Pass failure context and fix history to @cli-planning-agent
 - **Progress Tracking**: TodoWrite updates for entire iteration cycle
-- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
+- **Session Auto-Complete**: Call `/workflow:session:complete` when pass rate >= 95% (or 100%)
 
 ## Responsibility Matrix
 
 **CRITICAL - Clear division of labor between orchestrator and agents:**
 
-| Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
-|----------------|----------------------------|---------------------------|
-| Manage iteration loop | Yes - Controls loop flow | No - Executes single task |
-| Run CLI analysis (Gemini/Qwen) | Yes - Runs between agent tasks | No - Not involved |
-| Generate IMPL-fix-N.json | Yes - Creates task files | No - Not involved |
-| Run tests | No - Delegates to agent | Yes - Executes test command |
-| Apply fixes | No - Delegates to agent | Yes - Modifies code |
-| Detect test failures | Yes - Analyzes results and decides next action | Yes - Executes tests and reports outcomes |
-| Add tasks to queue | Yes - Manages queue | No - Not involved |
-| Update iteration state | Yes - Maintains overall iteration state | Yes - Updates individual task status only |
+| Responsibility | test-cycle-execute (Orchestrator) | @cli-planning-agent | @test-fix-agent (Executor) |
+|----------------|----------------------------|---------------------|---------------------------|
+| Manage iteration loop | Yes - Controls loop flow | No - Not involved | No - Executes single task |
+| Calculate pass rate | Yes - From test-results.json | No - Not involved | No - Reports test results |
+| Assess criticality | Yes - From test-results.json | No - Not involved | Yes - Assigns criticality in test results |
+| Run CLI analysis (Gemini/Qwen) | No - Delegates to cli-planning-agent | Yes - Executes CLI internally | No - Not involved |
+| Parse CLI output | No - Delegated | Yes - Extracts fix strategy | No - Not involved |
+| Generate IMPL-fix-N.json | No - Delegated | Yes - Creates task files | No - Not involved |
+| Run tests | No - Delegates to agent | No - Not involved | Yes - Executes test command |
+| Apply fixes | No - Delegates to agent | No - Not involved | Yes - Modifies code |
+| Detect test failures | Yes - Analyzes pass rate and decides next action | No - Not involved | Yes - Executes tests and reports outcomes |
+| Add tasks to queue | Yes - Manages queue | No - Returns task ID | No - Not involved |
+| Update iteration state | Yes - Maintains overall iteration state | No - Not involved | Yes - Updates individual task status only |
 
-**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
+**Key Principles**:
+- Orchestrator manages the "what" (iteration flow, threshold decisions) and "when" (task scheduling)
+- @cli-planning-agent executes the "analysis" (CLI execution, result parsing, task generation)
+- @test-fix-agent executes the "how" (run tests, apply fixes)
 
 **ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
 
@@ -97,17 +109,29 @@ 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)
+  4. [Orchestrator] Collect agent results from .process/test-results.json
+  5. [Orchestrator] Calculate test pass rate:
+     a. Parse test-results.json: passRate = (passed / total) * 100
+     b. Assess failure criticality (from test-results.json)
+     c. Evaluate fix effectiveness (NEW):
+        - Compare passRate with previous iteration
+        - If passRate decreased by >10%: REGRESSION detected
+        - If regression: Rollback last fix, skip to next strategy
+  6. [Orchestrator] Make threshold decision:
+     IF passRate === 100%:
+       → SUCCESS: Mark task complete, update TodoWrite, continue
+     ELSE IF passRate >= 95%:
+       → REVIEW: Check failure criticality
+       → If all failures are "low" criticality: PARTIAL SUCCESS (approve with note)
+       → If any "high" or "medium" criticality: Enter fix loop (step 7)
+     ELSE IF passRate < 95%:
+       → FAILED: Enter fix loop (step 7)
+  7. If entering fix loop (pass rate < 95% OR critical failures exist):
+     a. [Orchestrator] Invoke @cli-planning-agent with failure context
+     b. [Agent] Executes CLI analysis + generates 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
+  8. [Orchestrator] Check max iterations limit (abort if exceeded)
 ```
 
 **Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
@@ -119,33 +143,33 @@ For each task in queue:
 #### Iteration Structure
 ```
 Iteration N (managed by test-cycle-execute orchestrator):
-├── 1. Test Execution
+├── 1. Test Execution & Pass Rate Validation
 │   ├── [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] Run test suite and save results to test-results.json
+│   ├── [Agent] Report completion back to orchestrator
+│   ├── [Orchestrator] Calculate pass rate: (passed / total) * 100
+│   └── [Orchestrator] Assess failure criticality from test-results.json
+├── 2. Failure Analysis & Task Generation (via @cli-planning-agent)
+│   ├── [Orchestrator] Assemble failure context package (tests, errors, pass_rate)
+│   ├── [Orchestrator] Invoke @cli-planning-agent with context
+│   ├── [@cli-planning-agent] Execute CLI tool (Gemini/Qwen) internally
+│   ├── [@cli-planning-agent] Parse CLI output for root causes and fix strategy
+│   ├── [@cli-planning-agent] Generate IMPL-fix-N.json with structured task
+│   ├── [@cli-planning-agent] Save analysis to iteration-N-analysis.md
+│   └── [Orchestrator] Receive task ID and insert into queue (front position)
+├── 3. Fix Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with IMPL-fix-N task
+│   ├── [Agent] Load fix strategy from task.context.fix_strategy
+│   ├── [Agent] Apply surgical fixes to identified files
 │   └── [Agent] Report completion
-└── 5. Re-test
+└── 4. Re-test
     └── [Orchestrator] Return to step 1 with updated code
 ```
 
-**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
+**Key Changes**:
+- CLI analysis + task generation encapsulated in @cli-planning-agent
+- Pass rate calculation added to test execution step
+- Orchestrator only assembles context and invokes agent
 
 #### Iteration Task JSON Template
 ```json
@@ -220,74 +244,139 @@ Iteration N (managed by test-cycle-execute orchestrator):
 }
 ```
 
-### Phase 4: CLI Analysis Integration
+### Phase 4: Agent-Based Failure Analysis & Task Generation
 
-**Orchestrator executes CLI analysis between agent tasks:**
+**Orchestrator delegates CLI analysis and task generation to @cli-planning-agent:**
 
-#### When Test Failures Occur
-1. **[Orchestrator]** Detects failures from agent test execution output
-2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
-3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
-4. **[Orchestrator]** Interprets CLI tool output to extract fix strategy
-5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
-6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
+#### When Test Failures Occur (Pass Rate < 95% OR Critical Failures)
+1. **[Orchestrator]** Detects failures from test-results.json
+2. **[Orchestrator]** Check for repeated failures (NEW):
+   - Compare failed_tests with previous 2 iterations
+   - If same test failed 3 times consecutively: Mark as "stuck"
+   - If >50% of failures are "stuck": Switch analysis strategy or abort
+3. **[Orchestrator]** Extracts failure context:
+   - Failed tests with criticality assessment
+   - Error messages and stack traces
+   - Current pass rate
+   - Previous iteration attempts (if any)
+   - Stuck test markers (NEW)
+4. **[Orchestrator]** Assembles context package for @cli-planning-agent
+5. **[Orchestrator]** Invokes @cli-planning-agent via Task tool
+6. **[@cli-planning-agent]** Executes internally:
+   - Runs Gemini/Qwen CLI analysis with bug diagnosis template
+   - Parses CLI output to extract root causes and fix strategy
+   - Generates `IMPL-fix-N.json` with structured task definition
+   - Saves analysis report to `.process/iteration-N-analysis.md`
+   - Saves raw CLI output to `.process/iteration-N-cli-output.txt`
+7. **[Orchestrator]** Receives task ID from agent and inserts into queue
 
-**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
+**Key Change**: CLI execution + result parsing + task generation are now encapsulated in @cli-planning-agent, simplifying orchestrator logic.
 
-#### 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
+#### Agent Invocation Pattern (executed by orchestrator)
+```javascript
+Task(
+  subagent_type="cli-planning-agent",
+  description=`Analyze test failures and generate fix task (iteration ${currentIteration})`,
+  prompt=`
+    ## Context Package
+    {
+      "session_id": "${sessionId}",
+      "iteration": ${currentIteration},
+      "analysis_type": "test-failure",
+      "failure_context": {
+        "failed_tests": ${JSON.stringify(failedTests)},
+        "error_messages": ${JSON.stringify(errorMessages)},
+        "test_output": "${testOutputPath}",
+        "pass_rate": ${passRate},
+        "previous_attempts": ${JSON.stringify(previousAttempts)}
+      },
+      "cli_config": {
+        "tool": "gemini",
+        "model": "gemini-3-pro-preview-11-2025",
+        "template": "01-diagnose-bug-root-cause.txt",
+        "timeout": 2400000,
+        "fallback": "qwen"
+      },
+      "task_config": {
+        "agent": "@test-fix-agent",
+        "type": "test-fix-iteration",
+        "max_iterations": ${maxIterations},
+        "use_codex": false
+      }
+    }
 
-[Test failure context and requirements...]
-
-EXPECTED: Detailed fix strategy in markdown format
-RULES: Focus on minimal changes, avoid over-engineering
-"
+    ## Your Task
+    1. Execute CLI analysis using Gemini (fallback to Qwen if needed)
+    2. Parse CLI output and extract fix strategy with specific modification points
+    3. Generate IMPL-fix-${currentIteration}.json using your internal task template
+    4. Save analysis report to .process/iteration-${currentIteration}-analysis.md
+    5. Report success and task ID back to orchestrator
+  `
+)
 ```
 
-#### Analysis Output Structure
+#### Agent Response
+```javascript
+{
+  "status": "success",
+  "task_id": "IMPL-fix-${iteration}",
+  "task_path": ".workflow/${session}/.task/IMPL-fix-${iteration}.json",
+  "analysis_report": ".process/iteration-${iteration}-analysis.md",
+  "cli_output": ".process/iteration-${iteration}-cli-output.txt",
+  "summary": "Fix authentication token validation and null check issues",
+  "modification_points_count": 2,
+  "estimated_complexity": "low"
+}
+```
+
+#### Generated Analysis Report Structure
+The @cli-planning-agent generates `.process/iteration-N-analysis.md`:
+
 ```markdown
-# Test Failure Analysis - Iteration {N}
+---
+iteration: N
+analysis_type: test-failure
+cli_tool: gemini
+model: gemini-3-pro-preview-11-2025
+timestamp: 2025-11-10T10:00:00Z
+pass_rate: 85.0%
+---
+
+# Test Failure Analysis - Iteration N
+
+## Summary
+- **Failed Tests**: 2
+- **Pass Rate**: 85.0% (Target: 95%+)
+- **Root Causes Identified**: 2
+- **Modification Points**: 2
+
+## Failed Tests Details
+
+### test_auth_flow
+- **Error**: Expected 200, got 401
+- **File**: tests/test_auth.test.ts:45
+- **Criticality**: high
+
+### test_data_validation
+- **Error**: TypeError: Cannot read property 'name' of undefined
+- **File**: tests/test_validators.test.ts:23
+- **Criticality**: medium
 
 ## 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`
+[CLI output: 根本原因分析 section]
 
 ## Fix Strategy
+[CLI output: 详细修复建议 section]
 
-### 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
+## Modification Points
+- `src/auth/client.ts:sendRequest:45-50` - Add authentication token header
+- `src/validators/user.ts:validateUser:23-25` - Add null check before property access
 
-### 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
+## Expected Outcome
+[CLI output: 验证建议 section]
 
-## 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
+## CLI Raw Output
+See: `.process/iteration-N-cli-output.txt`
 ```
 
 ### Phase 5: Task Queue Management
@@ -321,27 +410,56 @@ After IMPL-fix-2 execution (success):
 #### Success Conditions
 - All initial tasks completed
 - All generated fix tasks completed
-- All tests passing
+- **Test pass rate === 100%** (all tests passing)
 - No pending tasks in queue
 
+#### Partial Success Conditions (NEW)
+- All initial tasks completed
+- Test pass rate >= 95% AND < 100%
+- All failures are "low" criticality (flaky tests, env-specific issues)
+- **Automatic Approval with Warning**: System auto-approves but marks session with review flag
+- Note: Generate completion summary with detailed warnings about low-criticality failures
+
 #### 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`
+2. **Calculate Final Pass Rate**: Parse test-results.json
+3. **Assess Completion Status**:
+   - If pass_rate === 100% → Full Success
+   - If pass_rate >= 95% + all "low" criticality → Partial Success (add review note)
+   - If pass_rate >= 95% + any "high"/"medium" criticality → Continue iteration
+   - If pass_rate < 95% → Failure
+4. **Update Session State**: Mark all tasks completed (or blocked if failure)
+5. **Generate Summary**: Create session completion summary with pass rate metrics
+6. **Update TodoWrite**: Mark all items completed
+7. **Auto-Complete**: Call `/workflow:session:complete` (for Full or Partial Success)
 
 #### Failure Conditions
-- Max iterations reached without success
-- Unrecoverable test failures
+- Max iterations (5) reached without achieving 95% pass rate
+- **Test pass rate < 95% after max iterations** (NEW)
+- Pass rate >= 95% but critical failures exist and max iterations reached
+- Unrecoverable test failures (infinite loop detection)
 - 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
+1. **Document State**: Save current iteration context with final pass rate
+2. **Generate Failure Report**: Include:
+   - Final pass rate (e.g., "85% after 5 iterations")
+   - Remaining failures with criticality assessment
+   - Iteration history and attempted fixes
+   - CLI analysis quality (normal/degraded)
+   - Recommendations for manual intervention
+3. **Preserve Context**: Keep all iteration logs and analysis reports
 4. **Mark Blocked**: Update task status to blocked
-5. **Return Control**: Return to user with detailed report
+5. **Return Control**: Return to user with detailed failure report
+
+#### Degraded Analysis Handling (NEW)
+When @cli-planning-agent returns `status: "degraded"` (both Gemini and Qwen failed):
+1. **Log Warning**: Record CLI analysis failure in iteration-state.json
+2. **Assess Risk**: Check if degraded analysis is acceptable:
+   - If iteration < 3 AND pass_rate improved: Accept degraded analysis, continue
+   - If iteration >= 3 OR pass_rate stagnant: Skip iteration, mark as blocked
+3. **User Notification**: Include CLI failure in completion summary
+4. **Fallback Strategy**: Use basic pattern matching from fix-history.json
 
 ## TodoWrite Coordination
 

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

@@ -58,6 +58,19 @@ This command is a **pure planning coordinator**:
 - Creates independent test workflow session
 - **All execution delegated to `/workflow:test-cycle-execute`**
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 ---
 
 ## Usage
@@ -128,9 +141,11 @@ This command is a **pure planning coordinator**:
 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
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 7. **Automatic Detection**: Mode auto-detected from input pattern
 8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+9. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+10. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ### 5-Phase Execution
 
@@ -202,9 +217,25 @@ This command is a **pure planning coordinator**:
 **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`
+- Generate **multi-layered test requirements** (L0: Static Analysis, L1: Unit, L2: Integration, L3: E2E)
+- Design test generation strategy with quality assurance criteria
+- Generate `TEST_ANALYSIS_RESULTS.md` with structured test layers
+
+**Enhanced Test Requirements**:
+For each targeted file/function, Gemini MUST generate:
+1. **L0: Static Analysis Requirements**:
+   - Linting rules to enforce (ESLint, Prettier)
+   - Type checking requirements (TypeScript)
+   - Anti-pattern detection rules
+2. **L1: Unit Test Requirements**:
+   - Happy path scenarios (valid inputs → expected outputs)
+   - Negative path scenarios (invalid inputs → error handling)
+   - Edge cases (null, undefined, 0, empty strings/arrays)
+3. **L2: Integration Test Requirements**:
+   - Successful component interactions
+   - Failure handling scenarios (service unavailable, timeout)
+4. **L3: E2E Test Requirements** (if applicable):
+   - Key user journeys from start to finish
 
 **Parse Output**:
 - Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
@@ -213,9 +244,18 @@ This command is a **pure planning coordinator**:
 - TEST_ANALYSIS_RESULTS.md exists with complete sections:
   - Coverage Assessment
   - Test Framework & Conventions
-  - Test Requirements by File
+  - **Multi-Layered Test Plan** (NEW):
+    - L0: Static Analysis Plan
+    - L1: Unit Test Plan
+    - L2: Integration Test Plan
+    - L3: E2E Test Plan (if applicable)
+  - Test Requirements by File (with layer annotations)
   - Test Generation Strategy
   - Implementation Targets
+  - Quality Assurance Criteria (NEW):
+    - Minimum coverage thresholds
+    - Required test types per function
+    - Acceptance criteria for test quality
   - Success Criteria
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
@@ -232,16 +272,18 @@ This command is a **pure planning coordinator**:
 - `--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):
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3 (multi-layered test plan)
+- Generate **minimum 3 task JSON files** (expandable based on complexity):
   - **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
+  - **IMPL-001.5-review.json**: Test Quality Gate (`@test-fix-agent`) ← **NEW**
   - **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 `IMPL_PLAN.md` with multi-layered test strategy
 - Generate `TODO_LIST.md` with task checklist
 
 **Parse Output**:
 - Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.5-review.json` exists ← **NEW**
 - Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
 - Verify additional `.task/IMPL-*.json` if applicable
 - Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
@@ -262,11 +304,16 @@ Test Session: [testSessionId]
 
 Tasks Created:
 - IMPL-001: Test Understanding & Generation (@code-developer)
+- IMPL-001.5: Test Quality Gate - Static Analysis & Coverage (@test-fix-agent) ← NEW
 - IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
 [- IMPL-003+: Additional tasks if applicable]
 
+Test Strategy: Multi-Layered (L0: Static, L1: Unit, L2: Integration, L3: E2E)
 Test Framework: [detected framework]
 Test Files to Generate: [count]
+Quality Thresholds:
+- Minimum Coverage: 80%
+- Static Analysis: Zero critical issues
 Max Fix Iterations: 5
 Fix Mode: [Manual|Codex Automated]
 
@@ -275,11 +322,12 @@ Review artifacts:
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 
 CRITICAL - Next Steps:
-1. Review IMPL_PLAN.md
+1. Review IMPL_PLAN.md (now includes multi-layered test strategy)
 2. **MUST execute: /workflow:test-cycle-execute**
    - This command only generated task JSON files
    - Test execution and fix iterations happen in test-cycle-execute
    - Do NOT attempt to run tests or fixes in main workflow
+3. IMPL-001.5 will validate test quality before fix cycle begins
 ```
 
 **TodoWrite**: Mark phase 5 completed
@@ -291,52 +339,133 @@ CRITICAL - Next Steps:
 
 ---
 
-### TodoWrite Progress Tracking
+### TodoWrite Pattern
 
-Track all 5 phases:
+**Core Concept**: Dynamic task attachment and collapse for test-fix-gen workflow with dual-mode support (Session Mode and Prompt Mode).
 
-```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"}
-]})
-```
+#### Key Principles
 
-Update status to `in_progress` when starting each phase, `completed` when done.
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` (Session Mode) or `/workflow:tools:context-gather` (Prompt Mode) attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
+
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Gather test coverage context: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED with mode-specific context gathering) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+#### Test-Fix-Gen Specific Features
+
+- **Dual-Mode Support**: Automatic mode detection based on input pattern
+  - **Session Mode**: Input pattern `WFS-*` → uses `test-context-gather` for cross-session context
+  - **Prompt Mode**: Text or file path → uses `context-gather` for direct codebase analysis
+- **Phase 2**: Mode-specific context gathering (session summaries vs codebase analysis)
+- **Phase 3**: Multi-layered test requirements analysis (L0: Static, L1: Unit, L2: Integration, L3: E2E)
+- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
+- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+
+**Benefits**:
+- Real-time visibility into attached tasks during execution
+- Clean orchestrator-level summary after tasks complete
+- Clear mental model: SlashCommand = attach tasks, not delegate work
+- Dual-mode support: Both Session Mode and Prompt Mode use same attachment pattern
+- Dynamic attachment/collapse maintains clarity
+
+**Note**: Unlike other workflow orchestrators, this file consolidates TodoWrite examples in this section rather than distributing them across Phase descriptions for better dual-mode clarity.
 
 ---
 
 ## Task Specifications
 
-Generates minimum 2 tasks (expandable for complex projects):
+Generates minimum 3 tasks (expandable for complex projects):
 
 ### IMPL-001: Test Understanding & Generation
 
 **Agent**: `@code-developer`
 
-**Purpose**: Understand source implementation and generate test files
+**Purpose**: Understand source implementation and generate test files following multi-layered test strategy
 
 **Task Configuration**:
 - Task ID: `IMPL-001`
 - `meta.type: "test-gen"`
 - `meta.agent: "@code-developer"`
-- `context.requirements`: Understand source implementation and generate tests
+- `context.requirements`: Understand source implementation and generate tests across all layers (L0-L3)
 - `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
+   - Analyze multi-layered test requirements (L0: Static, L1: Unit, L2: Integration, L3: E2E)
+   - Identify test scenarios, edge cases, and error paths
 2. **Generation Phase**:
-   - Generate test files following existing patterns
-   - Ensure test coverage aligns with requirements
+   - Generate L1 unit test files following existing patterns
+   - Generate L2 integration test files (if applicable)
+   - Generate L3 E2E test files (if applicable)
+   - Ensure test coverage aligns with multi-layered requirements
+   - Include both positive and negative test cases
 3. **Verification Phase**:
    - Verify test completeness and correctness
+   - Ensure each test has meaningful assertions
+   - Check for test anti-patterns (tests without assertions, overly broad mocks)
+
+### IMPL-001.5: Test Quality Gate ← **NEW**
+
+**Agent**: `@test-fix-agent`
+
+**Purpose**: Validate test quality before entering fix cycle - prevent "hollow tests" from becoming the source of truth
+
+**Task Configuration**:
+- Task ID: `IMPL-001.5-review`
+- `meta.type: "test-quality-review"`
+- `meta.agent: "@test-fix-agent"`
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Validate generated tests meet quality standards
+- `context.quality_config`: Load from `.claude/workflows/test-quality-config.json`
+
+**Execution Flow**:
+1. **L0: Static Analysis**:
+   - Run linting on test files (ESLint, Prettier)
+   - Check for test anti-patterns:
+     - Tests without assertions (`expect()` missing)
+     - Empty test bodies (`it('should...', () => {})`)
+     - Disabled tests without justification (`it.skip`, `xit`)
+   - Verify TypeScript type safety (if applicable)
+2. **Coverage Analysis**:
+   - Run coverage analysis on generated tests
+   - Calculate coverage percentage for target source files
+   - Identify uncovered branches and edge cases
+3. **Test Quality Metrics**:
+   - Verify minimum coverage threshold met (default: 80%)
+   - Verify all critical functions have negative test cases
+   - Verify integration tests cover key component interactions
+4. **Quality Gate Decision**:
+   - **PASS**: Coverage ≥ 80%, zero critical anti-patterns → Proceed to IMPL-002
+   - **FAIL**: Coverage < 80% OR critical anti-patterns found → Loop back to IMPL-001 with feedback
+
+**Acceptance Criteria**:
+- Static analysis: Zero critical issues
+- Test coverage: ≥ 80% for target files
+- Test completeness: All targeted functions have unit tests
+- Negative test coverage: Each public API has at least one error handling test
+- Integration coverage: Key component interactions have integration tests (if applicable)
+
+**Failure Handling**:
+If quality gate fails:
+1. Generate detailed feedback report (`.process/test-quality-report.md`)
+2. Update IMPL-001 task with specific improvement requirements
+3. Trigger IMPL-001 re-execution with enhanced context
+4. Maximum 2 quality gate retries before escalating to user
 
 ### IMPL-002: Test Execution & Fix Cycle
 
@@ -412,18 +541,62 @@ WFS-test-[session]/
 - `workflow_type: "test_session"`
 - No `source_session_id` field
 
-### Complete Data Flow
+### Execution Flow Diagram
 
-**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
+```
+Test-Fix-Gen Workflow Orchestrator (Dual-Mode Support)
+│
+├─ Phase 1: Create Test Session
+│  ├─ Session Mode: /workflow:session:start --new (with source_session_id)
+│  └─ Prompt Mode: /workflow:session:start --new (without source_session_id)
+│     └─ Returns: testSessionId (WFS-test-[slug])
+│
+├─ Phase 2: Gather Context                                   ← ATTACHED (3 tasks)
+│  ├─ Session Mode: /workflow:tools:test-context-gather
+│  │  └─ Load source session summaries + analyze coverage
+│  └─ Prompt Mode: /workflow:tools:context-gather
+│     └─ Analyze codebase from description
+│     ├─ Phase 2.1: Load context and analyze coverage
+│     ├─ Phase 2.2: Detect test framework and conventions
+│     └─ Phase 2.3: Generate context package
+│     └─ Returns: [test-]context-package.json                ← COLLAPSED
+│
+├─ Phase 3: Test Generation Analysis                         ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-concept-enhanced
+│     ├─ Phase 3.1: Analyze coverage gaps with Gemini
+│     ├─ Phase 3.2: Study existing test patterns
+│     └─ Phase 3.3: Generate test generation strategy
+│     └─ Returns: TEST_ANALYSIS_RESULTS.md                   ← COLLAPSED
+│
+├─ Phase 4: Generate Test Tasks                              ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-task-generate
+│     ├─ Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md
+│     ├─ Phase 4.2: Generate task JSONs (IMPL-001, IMPL-002)
+│     └─ Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md
+│     └─ Returns: Task JSONs and plans                       ← COLLAPSED
+│
+└─ Phase 5: Return Summary
+   └─ Command ends, control returns to user
 
-**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
+Artifacts Created:
+├── .workflow/WFS-test-[session]/
+│   ├── workflow-session.json
+│   ├── IMPL_PLAN.md
+│   ├── TODO_LIST.md
+│   ├── .task/
+│   │   ├── IMPL-001.json (test understanding & generation)
+│   │   ├── IMPL-002.json (test execution & fix cycle)
+│   │   └── IMPL-003.json (optional: test review & certification)
+│   └── .process/
+│       ├── [test-]context-package.json
+│       └── TEST_ANALYSIS_RESULTS.md
 
-**Command completes after Phase 5**
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
+• Dual-Mode: Session Mode and Prompt Mode share same attachment pattern
+• Command Boundary: Execution delegated to /workflow:test-cycle-execute
+```
 
 ---
 

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

@@ -18,6 +18,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - **Parameter Simplification**: Tools auto-detect test session type via metadata, no manual cross-session parameters needed
 - **Manual First**: Default to manual fixes, use `--use-codex` flag for automated Codex fix application
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 **Execution Flow**:
 1. Initialize TodoWrite → Create test session → Parse session ID
 2. Gather cross-session context (automatic) → Parse context path
@@ -33,10 +46,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 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 5 completes (summary returned)
-6. **Track Progress**: Update TodoWrite after every phase completion
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 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.
+10. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+11. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 5-Phase Execution
 
@@ -89,7 +104,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - Test framework detected
 - Test conventions documented
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
+
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Phase 2.1: Load source session summaries (test-context-gather)", "status": "in_progress", "activeForm": "Loading source session summaries"},
+  {"content": "Phase 2.2: Analyze test coverage with MCP tools (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "Phase 2.3: Identify coverage gaps and framework (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.3** sequentially
+
+<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
 
 ---
 
@@ -121,7 +168,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
   - Implementation Targets (test files to create)
   - Success Criteria
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+<!-- TodoWrite: When test-concept-enhanced invoked, INSERT 3 concept-enhanced tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Phase 3.1: Analyze coverage gaps with Gemini (test-concept-enhanced)", "status": "in_progress", "activeForm": "Analyzing coverage gaps"},
+  {"content": "Phase 3.2: Study existing test patterns (test-concept-enhanced)", "status": "pending", "activeForm": "Studying test patterns"},
+  {"content": "Phase 3.3: Generate test generation strategy (test-concept-enhanced)", "status": "pending", "activeForm": "Generating test strategy"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-concept-enhanced's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 ---
 
@@ -173,7 +252,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
   - Phase 2: Iterative Gemini diagnosis + manual/Codex fixes (based on flag)
   - Phase 3: Final validation and certification
 
-**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
+<!-- TodoWrite: When test-task-generate invoked, INSERT 3 test-task-generate tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md (test-task-generate)", "status": "in_progress", "activeForm": "Parsing test analysis"},
+  {"content": "Phase 4.2: Generate IMPL-001.json and IMPL-002.json (test-task-generate)", "status": "pending", "activeForm": "Generating task JSONs"},
+  {"content": "Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md (test-task-generate)", "status": "pending", "activeForm": "Generating plan documents"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-task-generate's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "in_progress", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 ---
 
@@ -214,37 +325,76 @@ Ready for execution. Use appropriate workflow commands to proceed.
 
 ## TodoWrite Pattern
 
-Track progress through 5 phases:
+**Core Concept**: Dynamic task attachment and collapse for test-gen workflow with cross-session context gathering and test generation strategy.
 
-```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"}
-]})
-```
+### Key Principles
 
-Update status to `in_progress` when starting each phase, mark `completed` when done.
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-## Data Flow
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Gather test coverage context: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+### Test-Gen Specific Features
+
+- **Phase 2**: Cross-session context gathering from source implementation session
+- **Phase 3**: Test requirements analysis with Gemini for generation strategy
+- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
+- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+
+**Benefits**:
+- Real-time visibility into attached tasks during execution
+- Clean orchestrator-level summary after tasks complete
+- Clear mental model: SlashCommand = attach tasks, not delegate work
+- Dynamic attachment/collapse maintains clarity
+
+**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
+
+## Execution Flow Diagram
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│ /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
+Test-Gen Workflow Orchestrator
+│
+├─ Phase 1: Create Test Session
+│  └─ /workflow:session:start --new
+│     └─ Returns: testSessionId (WFS-test-[source])
+│
+├─ Phase 2: Gather Test Context                           ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-context-gather
+│     ├─ Phase 2.1: Load source session summaries
+│     ├─ Phase 2.2: Analyze test coverage with MCP tools
+│     └─ Phase 2.3: Identify coverage gaps and framework
+│     └─ Returns: test-context-package.json               ← COLLAPSED
+│
+├─ Phase 3: Test Generation Analysis                      ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-concept-enhanced
+│     ├─ Phase 3.1: Analyze coverage gaps with Gemini
+│     ├─ Phase 3.2: Study existing test patterns
+│     └─ Phase 3.3: Generate test generation strategy
+│     └─ Returns: TEST_ANALYSIS_RESULTS.md                ← COLLAPSED
+│
+├─ Phase 4: Generate Test Tasks                           ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-task-generate
+│     ├─ Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md
+│     ├─ Phase 4.2: Generate IMPL-001.json and IMPL-002.json
+│     └─ Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md
+│     └─ Returns: Task JSONs and plans                    ← COLLAPSED
+│
+└─ Phase 5: Return Summary
+   └─ Command ends, control returns to user
 
 Artifacts Created:
 ├── .workflow/WFS-test-[session]/
@@ -257,6 +407,10 @@ Artifacts Created:
 │   └── .process/
 │       ├── test-context-package.json
 │       └── TEST_ANALYSIS_RESULTS.md
+
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
 ```
 
 ## Session Metadata

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

@@ -463,10 +463,3 @@ If Edit tool fails mid-application:
 ✓ Error handling robust (validate/retry/degrade)
 ```
 
-## Related Commands
-| Command | Relationship |
-|---------|--------------|
-| `/workflow:tools:context-gather` | Generates input conflict_detection data |
-| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
-| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
-| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

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

@@ -509,9 +509,3 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
 - **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
 - **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
 
-## Related Commands
-- `/workflow:tdd-plan` - Orchestrates TDD workflow planning (6 phases)
-- `/workflow:tools:test-context-gather` - Analyzes test coverage
-- `/workflow:execute` - Executes TDD tasks in order
-- `/workflow:tdd-verify` - Verifies TDD compliance
-- `/workflow:test-gen` - Post-implementation test generation

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

@@ -275,7 +275,3 @@ Overall Compliance: 93/100
 Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
 ```
 
-## Related Commands
-- `/workflow:tdd-verify` - Uses this tool for verification
-- `/workflow:tools:task-generate-tdd` - Generates tasks this tool analyzes
-- `/workflow:execute` - Executes tasks before analysis

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

@@ -460,8 +460,3 @@ Synthesize Gemini analysis into standardized format:
 - ✅ Execution time < 20 minutes
 - ✅ Output follows existing test conventions
 
-## Related Commands
-
-- `/workflow:tools:test-context-gather` - Provides input context
-- `/workflow:tools:test-task-generate` - Consumes analysis results
-- `/workflow:test-gen` - Main test generation workflow

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

@@ -203,8 +203,3 @@ Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-pac
 - **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
 - **Coverage focus**: Primary goal is identifying implementation files without tests
 
-## Related Commands
-
-- `/workflow:test-gen` - Main test generation workflow
-- `/workflow:tools:test-concept-enhanced` - Test generation analysis
-- `/workflow:tools:test-task-generate` - Test task JSON generation

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

@@ -393,16 +393,6 @@ This section provides quick reference for test task JSON structure. For complete
 - Session state updated with test metadata
 - MCP enhancements integrated (if available)
 
-## Related Commands
-- `/workflow:test-gen` - Creates test session and calls this tool (Phase 4)
-- `/workflow:test-fix-gen` - Creates test-fix session and calls this tool (Phase 4)
-- `/workflow:tools:test-context-gather` - Gathers test coverage context
-- `/workflow:tools:test-concept-enhanced` - Generates test strategy analysis (TEST_ANALYSIS_RESULTS.md)
-- `/workflow:execute` - Executes the generated test-fix tasks
-- `/workflow:test-cycle-execute` - Executes test-fix cycle with iteration management
-- `@code-developer` - Agent that executes IMPL-001 (test generation)
-- `@test-fix-agent` - Agent that executes IMPL-002 (test execution & fix)
-
 ## Agent Execution Notes
 
 The `@test-fix-agent` will execute the task by following the `flow_control.implementation_approach` specification:

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

@@ -1,480 +0,0 @@
----
-name: batch-generate
-description: Prompt-driven batch UI generation using target-style-centric parallel execution with design token application
-argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
-allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
----
-
-# Batch Generate UI Prototypes (/workflow:ui-design:batch-generate)
-
-## Overview
-Prompt-driven UI generation with intelligent target extraction and **target-style-centric batch execution**. Each agent handles all layouts for one target × style combination.
-
-**Strategy**: Prompt → Targets → Batched Generation
-- **Prompt-driven**: Describe what to build, command extracts targets
-- **Agent scope**: Each of `T × S` agents generates `L` layouts
-- **Parallel batching**: Max 6 concurrent agents for optimal throughput
-- **Component isolation**: Complete task independence
-- **Style-aware**: HTML adapts to design_attributes
-- **Self-contained CSS**: Direct token values (no var() refs)
-
-**Supports**: Pages (full layouts) and components (isolated elements)
-
-## Phase 1: Setup & Validation
-
-### Step 1: Parse Prompt & Resolve Configuration
-```bash
-# Parse required parameters
-prompt_text = --prompt
-device_type = --device-type OR "responsive"
-
-# Extract targets from prompt
-IF --targets:
-    target_list = split_and_clean(--targets)
-ELSE:
-    target_list = extract_targets_from_prompt(prompt_text)  # See helpers
-    IF NOT target_list: target_list = ["home"]  # Fallback
-
-# Detect target type
-target_type = --target-type OR detect_target_type(target_list)
-
-# Resolve base path
-IF --base-path:
-    base_path = --base-path
-ELSE IF --session:
-    bash(find .workflow/WFS-{session} -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
-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-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: Validate Design Tokens
-```bash
-# Check design tokens exist
-bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
-
-# 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**: `design_tokens_valid`, `design_space_analysis`
-
-### Step 3: Gather Layout Inspiration (Reuse or Create)
-```bash
-# Check if layout inspirations already exist from layout-extract phase
-inspiration_source = "{base_path}/.intermediates/layout-analysis/inspirations"
-
-FOR target IN target_list:
-    # 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)
-
-        # 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 (reused or created in `.intermediates/layout-analysis/inspirations/`)
-
-## Phase 2: Target-Style-Centric Batch Generation (Agent)
-
-**Executor**: `Task(ui-design-agent)` × `T × S` tasks in **batched parallel** (max 6 concurrent)
-
-### Step 1: Calculate Batch Execution Plan
-```bash
-bash(mkdir -p {base_path}/prototypes)
-
-# Build task list: T × S combinations
-MAX_PARALLEL = 6
-total_tasks = T × S
-total_batches = ceil(total_tasks / MAX_PARALLEL)
-
-# Initialize batch tracking
-TodoWrite({todos: [
-  {content: "Batch 1/{batches}: Generate 6 tasks", status: "in_progress"},
-  {content: "Batch 2/{batches}: Generate 6 tasks", status: "pending"},
-  ...
-]})
-```
-
-### Step 2: Launch Batched Agent Tasks
-For each batch (up to 6 parallel tasks):
-```javascript
-Task(ui-design-agent): `
-  [TARGET_STYLE_UI_GENERATION_FROM_PROMPT]
-  🎯 ONE component: {target} × Style-{style_id} ({philosophy_name})
-  Generate: {layout_variants} × 2 files (HTML + CSS per layout)
-
-  PROMPT CONTEXT: {target_requirements}  # Extracted from original prompt
-  TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants}
-  BASE_PATH: {base_path}
-  DEVICE: {device_type}
-  ${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""}
-
-  ## Reference
-  - Layout inspiration: Read("{base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt")
-  - Design tokens: Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-    Parse ALL token values including:
-    * colors, typography (with combinations), spacing, opacity
-    * border_radius, shadows, breakpoints
-    * component_styles (button, card, input variants)
-  ${design_attributes ? "- Adapt DOM to: density, visual_weight, formality, organic_vs_geometric" : ""}
-
-  ## Generation
-  For EACH layout (1 to {layout_variants}):
-
-  1. HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
-     - Complete HTML5: <!DOCTYPE>, <head>, <body>
-     - CSS ref: <link href="{target}-style-{style_id}-layout-N.css">
-     - Semantic: <header>, <nav>, <main>, <footer>
-     - A11y: ARIA labels, landmarks, responsive meta
-     - Viewport: <meta name="viewport" content="width=device-width, initial-scale=1.0">
-     - Follow user requirements from prompt
-     ${design_attributes ? `
-     - DOM adaptation:
-       * density='spacious' → flatter hierarchy
-       * density='compact' → deeper nesting
-       * visual_weight='heavy' → extra wrappers
-       * visual_weight='minimal' → direct structure` : ""}
-     - Device-specific: Optimize for {device_type}
-
-  2. CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
-     - Self-contained: Direct token VALUES (no var())
-     - Use tokens: colors, fonts, spacing, opacity, borders, shadows
-     - IF tokens.component_styles exists: Use component presets for buttons, cards, inputs
-     - IF tokens.typography.combinations exists: Use typography presets for headings and body text
-     - Device-optimized: {device_type} styles
-     ${device_type === 'responsive' ? '- Responsive: Mobile-first @media' : '- Fixed: ' + device_type}
-     ${design_attributes ? `
-     - Token selection: density → spacing, visual_weight → shadows` : ""}
-
-  ## Notes
-  - ✅ Token VALUES directly from design-tokens.json (with typography.combinations, opacity, component_styles support)
-  - ✅ Follow prompt requirements for {target}
-  - ✅ Optimize for {device_type}
-  - ❌ NO var() refs, NO external deps
-  - Layouts structurally DISTINCT
-  - Write files IMMEDIATELY (per layout)
-  - CSS filename MUST match HTML <link href>
-`
-
-# After each batch completes
-TodoWrite: Mark batch completed, next batch in_progress
-```
-
-## Phase 3: Verify & Generate Previews
-
-### Step 1: Verify Generated Files
-```bash
-# Count expected vs found
-bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
-# Expected: S × L × T × 2
-
-# Validate samples
-Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
-# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
-```
-
-**Output**: `S × L × T × 2` files verified
-
-### Step 2: Run Preview Generation Script
-```bash
-bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
-```
-
-**Script generates**:
-- `compare.html` (interactive matrix)
-- `index.html` (navigation)
-- `PREVIEW.md` (instructions)
-
-### Step 3: Verify Preview Files
-```bash
-bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
-```
-
-**Output**: 3 preview files
-
-## Completion
-
-### Todo Update
-```javascript
-TodoWrite({todos: [
-  {content: "Setup and parse prompt", status: "completed", activeForm: "Parsing prompt"},
-  {content: "Detect token sources", status: "completed", activeForm: "Loading design systems"},
-  {content: "Gather layout inspiration", status: "completed", activeForm: "Researching layouts"},
-  {content: "Batch 1/{batches}: Generate 6 tasks", status: "completed", activeForm: "Generating batch 1"},
-  ... (all batches completed)
-  {content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
-]});
-```
-
-### Output Message
-```
-✅ Prompt-driven batch UI generation complete!
-
-Prompt: {prompt_text}
-
-Configuration:
-- Style Variants: {style_variants}
-- Layout Variants: {layout_variants}
-- Target Type: {target_type}
-- Device Type: {device_type}
-- Targets: {target_list} ({T} targets)
-- Total Prototypes: {S × L × T}
-
-Batch Execution:
-- Total tasks: {T × S} (targets × styles)
-- Batches: {batches} (max 6 parallel per batch)
-- Agent scope: {L} layouts per target×style
-- Component isolation: Complete task independence
-- Device-specific: All layouts optimized for {device_type}
-
-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: Production-ready (WCAG AA compliant)
-
-Generated Files:
-{base_path}/prototypes/
-├── {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
-3. Read PREVIEW.md
-
-Next: /workflow:ui-design:update
-```
-
-## Simple Bash Commands
-
-### Path Operations
-```bash
-# Find design directory
-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-extraction/style-* -d | wc -l)
-
-# Check design tokens exist
-bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
-```
-
-### Validation Commands
-```bash
-# Count generated files
-bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
-
-# Verify preview
-bash(test -f {base_path}/prototypes/compare.html && echo "exists")
-```
-
-### File Operations
-```bash
-# 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")
-```
-
-## Output Structure
-
-```
-{base_path}/
-├── .intermediates/
-│   └── layout-analysis/
-│       └── inspirations/
-│           └── {target}-layout-ideas.txt  # Layout inspiration (reused or created)
-├── prototypes/
-│   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
-│   ├── {target}-style-{s}-layout-{l}.css
-│   ├── compare.html
-│   ├── index.html
-│   └── PREVIEW.md
-└── style-extraction/
-    └── style-{s}/
-        ├── design-tokens.json
-        └── style-guide.md
-```
-
-## Error Handling
-
-### Common Errors
-```
-ERROR: No design tokens found
-→ Run /workflow:ui-design:style-extract first
-
-ERROR: No targets extracted from prompt
-→ Use --targets explicitly or rephrase prompt
-
-ERROR: MCP search failed
-→ Check network, retry
-
-ERROR: Batch {N} agent tasks failed
-→ Check agent output, retry specific target×style combinations
-
-ERROR: Script permission denied
-→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
-```
-
-### Recovery Strategies
-- **Partial success**: Keep successful target×style combinations
-- **Missing design_attributes**: Works without (less style-aware)
-- **Invalid tokens**: Validate design-tokens.json structure
-- **Failed batch**: Re-run command, only failed combinations will retry
-
-## Quality Checklist
-
-- [ ] Prompt clearly describes targets
-- [ ] CSS uses direct token values (no var())
-- [ ] HTML adapts to design_attributes (if available)
-- [ ] Semantic HTML5 structure
-- [ ] ARIA attributes present
-- [ ] Device-optimized layouts
-- [ ] Layouts structurally distinct
-- [ ] compare.html works
-
-## Key Features
-
-- **Prompt-Driven**: Describe what to build, command extracts targets
-- **Target-Style-Centric**: `T×S` agents, each handles `L` layouts
-- **Parallel Batching**: Max 6 concurrent agents with progress tracking
-- **Component Isolation**: Complete task independence
-- **Style-Aware**: HTML adapts to design_attributes
-- **Self-Contained CSS**: Direct token values (no var())
-- **Device-Specific**: Optimized for desktop/mobile/tablet/responsive
-- **Inspiration-Based**: MCP-powered layout research
-- **Production-Ready**: Semantic, accessible, responsive
-
-## Integration
-
-**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**: style-extract, explore-auto, imitate-auto outputs
-**Optimization**: Reuses layout inspirations from layout-extract phase, avoiding duplicate MCP searches
-
-## Usage Examples
-
-### Basic: Auto-detection
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "Dashboard with metric cards and charts"
-
-# Auto: latest design run, extracts "dashboard" target
-# Output: S × L × 1 prototypes
-```
-
-### With Session
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "Auth pages: login, signup, password reset" \
-  --session WFS-auth
-
-# Uses WFS-auth's design run
-# Extracts: ["login", "signup", "password-reset"]
-# Batches: 2 (if S=3: 9 tasks = 6+3)
-# Output: S × L × 3 prototypes
-```
-
-### Components with Device Type
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "Mobile UI components: navbar, card, footer" \
-  --target-type component \
-  --device-type mobile
-
-# Mobile-optimized component generation
-# Output: S × L × 3 prototypes
-```
-
-### Large Scale (Multi-batch)
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "E-commerce site" \
-  --targets "home,shop,product,cart,checkout" \
-  --style-variants 4 \
-  --layout-variants 2
-
-# Tasks: 5 × 4 = 20 (4 batches: 6+6+6+2)
-# Output: 4 × 2 × 5 = 40 prototypes
-```
-
-## Helper Functions Reference
-
-### Target Extraction
-```python
-# extract_targets_from_prompt(prompt_text)
-# Patterns: "Create X and Y", "Generate X, Y, Z pages", "Build X"
-# Returns: ["x", "y", "z"] (normalized lowercase with hyphens)
-
-# detect_target_type(target_list)
-# Keywords: page (home, dashboard, login) vs component (navbar, card, button)
-# Returns: "page" or "component"
-
-# extract_relevant_context_from_prompt(prompt_text, target)
-# Extracts sentences mentioning specific target
-# Returns: Relevant context string
-```
-
-## Batch Execution Details
-
-### Parallel Control
-- **Max concurrent**: 6 agents per batch
-- **Task distribution**: T × S tasks = ceil(T×S/6) batches
-- **Progress tracking**: TodoWrite per-batch status
-- **Examples**:
-  - 3 tasks → 1 batch
-  - 9 tasks → 2 batches (6+3)
-  - 20 tasks → 4 batches (6+6+6+2)
-
-### Performance
-| Tasks | Batches | Est. Time | Efficiency |
-|-------|---------|-----------|------------|
-| 1-6   | 1       | 3-5 min   | 100%       |
-| 7-12  | 2       | 6-10 min  | ~85%       |
-| 13-18 | 3       | 9-15 min  | ~80%       |
-| 19-30 | 4-5     | 12-25 min | ~75%       |
-
-### Optimization Tips
-1. **Reduce tasks**: Fewer targets or styles
-2. **Adjust layouts**: L=2 instead of L=3 for faster iteration
-3. **Stage generation**: Core pages first, secondary pages later
-
-## Notes
-
-- **Prompt quality**: Clear descriptions improve target extraction
-- **Token sources**: Consolidated (production) or proposed (fast-track)
-- **Batch parallelism**: Max 6 concurrent for stability
-- **Scalability**: Tested up to 30+ tasks (5+ batches)
-- **Dependencies**: MCP web search, ui-generate-preview.sh script

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

@@ -1,7 +1,7 @@
 ---
 name: capture
 description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping
-argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
+argument-hint: --url-map "target:url,..." [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
 ---
 
@@ -15,19 +15,38 @@ Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes
 
 ## Phase 1: Initialize & Parse
 
-### Step 1: Determine Base Path
+### Step 1: Determine Base Path & Generate Design ID
 ```bash
-# Priority: --base-path > session > standalone
-bash(if [ -n "$BASE_PATH" ]; then
-  echo "$BASE_PATH"
+# Priority: --design-id > session (latest) > standalone (create new)
+if [ -n "$DESIGN_ID" ]; then
+  # Use provided design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+  if [ -z "$relative_path" ]; then
+    echo "ERROR: Design run not found: $DESIGN_ID"
+    echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
+    exit 1
+  fi
 elif [ -n "$SESSION_ID" ]; then
-  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
-  echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d-%H%M%S)"
+  # Find latest in session or create new
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  if [ -z "$relative_path" ]; then
+    design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+    relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
+  fi
 else
-  echo ".workflow/.design/run-$(date +%Y%m%d-%H%M%S)"
-fi)
+  # Create new standalone design run
+  design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+  relative_path=".workflow/${design_id}"
+fi
 
-bash(mkdir -p $BASE_PATH/screenshots)
+# Create directory and convert to absolute path
+bash(mkdir -p "$relative_path"/screenshots)
+base_path=$(cd "$relative_path" && pwd)
+
+# Extract and display design_id
+design_id=$(basename "$base_path")
+echo "✓ Design ID: $design_id"
+echo "✓ Base path: $base_path"
 ```
 
 ### Step 2: Parse URL Map
@@ -187,7 +206,7 @@ bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$ur
 
 Failed URLs:
   home: https://linear.app
-  Save to: .workflow/.design/run-20250110/screenshots/home.png
+  Save to: .workflow/design-run-20250110/screenshots/home.png
 
 Steps:
   1. Visit URL in browser
@@ -270,7 +289,7 @@ Next: /workflow:ui-design:extract --images "screenshots/*.png"
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Create screenshot directory
 bash(mkdir -p $BASE_PATH/screenshots)

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

@@ -0,0 +1,666 @@
+---
+name: workflow:ui-design:codify-style
+description: Orchestrator to extract styles from code and generate shareable reference package with preview (automatic file discovery)
+argument-hint: "<path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+allowed-tools: SlashCommand,Bash,Read,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Codify Style (Orchestrator)
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Coordinates style extraction from codebase and generates shareable reference packages.
+
+**Pure Orchestrator Pattern**: Does NOT directly execute agent tasks. Delegates to specialized commands:
+1. `/workflow:ui-design:import-from-code` - Extract styles from source code
+2. `/workflow:ui-design:reference-page-generator` - Generate versioned reference package with interactive preview
+
+**Output**: Shareable, versioned style reference package at `.workflow/reference_style/{package-name}/`
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:codify-style <path> --package-name <name>`
+2. Phase 0: Parameter validation & preparation → **IMMEDIATELY triggers Phase 1**
+3. Phase 1 (import-from-code) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 2
+4. Phase 2 (reference-page-generator) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 3
+5. Phase 3 (cleanup & verification) → **Execute orchestrator task** → Reports completion
+
+**Phase Transition Mechanism**:
+- **Phase 0 (Validation)**: Validate parameters, prepare workspace → IMMEDIATELY triggers Phase 1
+- **Phase 1-2 (Task Attachment)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these tasks itself.
+- **Task Execution**: Orchestrator runs attached tasks sequentially, updating TodoWrite as each completes
+- **Task Collapse**: After all attached tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing completed tasks
+- No user interaction required after initial command
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 3.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 0 validation → Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - pure orchestrator pattern
+3. **Parse & Pass**: Extract required data from each command output (design run path, metadata)
+4. **Intelligent Validation**: Smart parameter validation with user-friendly error messages
+5. **Safety First**: Package overwrite protection, existence checks, fallback error handling
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+7. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+8. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 3.
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:codify-style <path> [OPTIONS]
+
+# Required
+<path>                  Source code directory to analyze
+
+# Optional
+--package-name <name>   Custom name for the style reference package
+                        (default: auto-generated from directory name)
+--output-dir <path>     Output directory (default: .workflow/reference_style)
+--overwrite             Overwrite existing package without prompting
+```
+
+**Note**: File discovery is fully automatic. The command will scan the source directory and find all style-related files (CSS, SCSS, JS, HTML) automatically.
+
+---
+
+## 4-Phase Execution
+
+### Phase 0: Intelligent Parameter Validation & Session Preparation
+
+**Goal**: Validate parameters, check safety constraints, prepare session, and get user confirmation
+
+**TodoWrite** (First Action):
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Orchestrator tracks only high-level phases. Sub-command details shown when executed.
+
+**Step 0a: Parse and Validate Required Parameters**
+
+```bash
+# Parse positional path parameter (first non-flag argument)
+source_path = FIRST_POSITIONAL_ARG
+
+# Validate source path
+IF NOT source_path:
+    REPORT: "❌ ERROR: Missing required parameter: <path>"
+    REPORT: "USAGE: /workflow:ui-design:codify-style <path> [OPTIONS]"
+    REPORT: "EXAMPLE: /workflow:ui-design:codify-style ./src"
+    REPORT: "EXAMPLE: /workflow:ui-design:codify-style ./app --package-name design-system-v2"
+    EXIT 1
+
+# Validate source path existence
+TRY:
+    source_exists = Bash(test -d "${source_path}" && echo "exists" || echo "not_exists")
+    IF source_exists != "exists":
+        REPORT: "❌ ERROR: Source directory not found: ${source_path}"
+        REPORT: "Please provide a valid directory path."
+        EXIT 1
+CATCH error:
+    REPORT: "❌ ERROR: Cannot validate source path: ${error}"
+    EXIT 1
+
+source = source_path
+STORE: source
+
+# Auto-generate package name if not provided
+IF NOT --package-name:
+    # Extract directory name from path
+    dir_name = Bash(basename "${source}")
+    # Normalize to package name format (lowercase, replace special chars with hyphens)
+    normalized_name = dir_name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+    # Add version suffix
+    package_name = "${normalized_name}-style-v1"
+
+    ELSE:
+    package_name = --package-name
+
+    # Validate custom package name format (lowercase, alphanumeric, hyphens only)
+    IF NOT package_name MATCHES /^[a-z0-9][a-z0-9-]*$/:
+        REPORT: "❌ ERROR: Invalid package name format: ${package_name}"
+        REPORT: "Requirements:"
+        REPORT: "  • Must start with lowercase letter or number"
+        REPORT: "  • Only lowercase letters, numbers, and hyphens allowed"
+        REPORT: "  • No spaces or special characters"
+        REPORT: "EXAMPLES: main-app-style-v1, design-system-v2, component-lib-v1"
+        EXIT 1
+
+STORE: package_name, output_dir (default: ".workflow/reference_style"), overwrite_flag
+```
+
+**Step 0b: Intelligent Package Safety Check**
+
+```bash
+# Set default output directory
+output_dir = --output-dir OR ".workflow/reference_style"
+package_path = "${output_dir}/${package_name}"
+
+TRY:
+    package_exists = Bash(test -d "${package_path}" && echo "exists" || echo "not_exists")
+
+    IF package_exists == "exists":
+        IF NOT --overwrite:
+            REPORT: "❌ ERROR: Package '${package_name}' already exists at ${package_path}/"
+            REPORT: "Use --overwrite flag to replace, or choose a different package name"
+            EXIT 1
+        ELSE:
+            REPORT: "⚠️  Overwriting existing package: ${package_name}"
+
+CATCH error:
+    REPORT: "⚠️  Warning: Cannot check package existence: ${error}"
+    REPORT: "Continuing with package creation..."
+```
+
+**Step 0c: Session Preparation**
+
+```bash
+# Create temporary workspace for processing
+TRY:
+    # Step 1: Ensure .workflow directory exists and generate unique ID
+    Bash(mkdir -p .workflow)
+    temp_id = Bash(echo "codify-temp-$(date +%Y%m%d-%H%M%S)")
+
+    # Step 2: Create temporary directory
+    Bash(mkdir -p ".workflow/${temp_id}")
+
+    # Step 3: Get absolute path using bash
+    design_run_path = Bash(cd ".workflow/${temp_id}" && pwd)
+
+CATCH error:
+    REPORT: "❌ ERROR: Failed to create temporary workspace: ${error}"
+    EXIT 1
+
+STORE: temp_id, design_run_path
+```
+
+**Summary Variables**:
+- `SOURCE`: Validated source directory path
+- `PACKAGE_NAME`: Validated package name (lowercase, alphanumeric, hyphens)
+- `PACKAGE_PATH`: Full output path `${output_dir}/${package_name}`
+- `OUTPUT_DIR`: `.workflow/reference_style` (default) or user-specified
+- `OVERWRITE`: `true` if --overwrite flag present
+- `CSS/SCSS/JS/HTML/STYLE_FILES`: Optional glob patterns
+- `TEMP_ID`: `codify-temp-{timestamp}` (temporary workspace identifier)
+- `DESIGN_RUN_PATH`: Absolute path to temporary workspace
+
+<!-- TodoWrite: Update Phase 0 → completed, Phase 1 → in_progress, INSERT import-from-code tasks -->
+
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1.0: Discover and categorize code files (import-from-code)", "status": "in_progress", "activeForm": "Discovering code files"},
+  {"content": "Phase 1.1: Style Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting style tokens"},
+  {"content": "Phase 1.2: Animation Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting animation tokens"},
+  {"content": "Phase 1.3: Layout Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting layout patterns"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** import-from-code's 4 tasks to current workflow. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 1.0-1.3** sequentially
+
+---
+
+### Phase 1: Style Extraction from Source Code
+
+**Goal**: Extract design tokens, style patterns, and component styles from codebase
+
+**Command Construction**:
+
+```bash
+# Build command with required parameters only
+# Use temp_id as design-id since it's the workspace directory name
+command = "/workflow:ui-design:import-from-code" +
+          " --design-id \"${temp_id}\"" +
+          " --source \"${source}\""
+```
+
+**Execute Command (Task Attachment Pattern)**:
+
+```bash
+TRY:
+    # SlashCommand invocation ATTACHES import-from-code's 4 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 1.0: Discover and categorize code files
+    #   2. Phase 1.1: Style Agent extraction
+    #   3. Phase 1.2: Animation Agent extraction
+    #   4. Phase 1.3: Layout Agent extraction
+    SlashCommand(command)
+
+    # After executing all attached tasks, verify extraction outputs
+    tokens_path = "${design_run_path}/style-extraction/style-1/design-tokens.json"
+    guide_path = "${design_run_path}/style-extraction/style-1/style-guide.md"
+
+    tokens_exists = Bash(test -f "${tokens_path}" && echo "exists" || echo "missing")
+    guide_exists = Bash(test -f "${guide_path}" && echo "exists" || echo "missing")
+
+    IF tokens_exists != "exists" OR guide_exists != "exists":
+        REPORT: "⚠️  WARNING: Expected extraction files not found"
+        REPORT: "Continuing with available outputs..."
+
+CATCH error:
+    REPORT: "❌ ERROR: Style extraction failed"
+    REPORT: "Error: ${error}"
+    REPORT: "Possible cause: Source directory contains no style files"
+    Bash(rm -rf .workflow/${temp_id})
+    EXIT 1
+```
+
+**Example Command**:
+```bash
+# Automatic file discovery
+/workflow:ui-design:import-from-code --design-id codify-temp-20250111-123456 --source ./src
+```
+
+**Completion Criteria**:
+- ✅ `import-from-code` command executed successfully
+- ✅ Design run created at `${design_run_path}`
+- ✅ Required files exist:
+  - `design-tokens.json` - Complete design token system
+  - `style-guide.md` - Style documentation
+- ⭕ Optional files:
+  - `animation-tokens.json` - Animation specifications
+  - `component-patterns.json` - Component catalog
+
+<!-- TodoWrite: REMOVE Phase 1.0-1.3 tasks, INSERT reference-page-generator tasks -->
+
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2.0: Setup and validation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 2.1: Prepare component data (reference-page-generator)", "status": "pending", "activeForm": "Copying layout templates"},
+  {"content": "Phase 2.2: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 3 tasks. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 2.0-2.2** sequentially
+
+---
+
+### Phase 2: Reference Package Generation
+
+**Goal**: Generate shareable reference package with interactive preview and documentation
+
+**Command Construction**:
+
+```bash
+command = "/workflow:ui-design:reference-page-generator " +
+          "--design-run \"${design_run_path}\" " +
+          "--package-name \"${package_name}\" " +
+          "--output-dir \"${output_dir}\""
+```
+
+**Execute Command (Task Attachment Pattern)**:
+
+```bash
+TRY:
+    # SlashCommand invocation ATTACHES reference-page-generator's 3 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 2.0: Setup and validation
+    #   2. Phase 2.1: Prepare component data
+    #   3. Phase 2.2: Generate preview pages
+    SlashCommand(command)
+
+    # After executing all attached tasks, verify package outputs
+    required_files = [
+        "layout-templates.json",
+        "design-tokens.json",
+        "preview.html",
+        "preview.css"
+    ]
+
+    missing_files = []
+    FOR file IN required_files:
+        file_path = "${package_path}/${file}"
+        exists = Bash(test -f "${file_path}" && echo "exists" || echo "missing")
+        IF exists != "exists":
+            missing_files.append(file)
+
+    IF missing_files.length > 0:
+        REPORT: "⚠️  WARNING: Some expected files are missing"
+        REPORT: "Package may be incomplete. Continuing with cleanup..."
+
+CATCH error:
+    REPORT: "❌ ERROR: Reference package generation failed"
+    REPORT: "Error: ${error}"
+    Bash(rm -rf .workflow/${temp_id})
+    EXIT 1
+```
+
+**Example Command**:
+```bash
+/workflow:ui-design:reference-page-generator \
+  --design-run .workflow/codify-temp-20250111-123456 \
+  --package-name main-app-style-v1 \
+  --output-dir .workflow/reference_style
+```
+
+**Completion Criteria**:
+- ✅ `reference-page-generator` executed successfully
+- ✅ Reference package created at `${package_path}/`
+- ✅ All required files present:
+  - `layout-templates.json` - Layout templates from design run
+  - `design-tokens.json` - Complete design token system
+  - `preview.html` - Interactive multi-component showcase
+  - `preview.css` - Showcase styling
+- ⭕ Optional files:
+  - `animation-tokens.json` - Animation specifications (if available from extraction)
+
+<!-- TodoWrite: REMOVE Phase 2.0-2.2 tasks, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "completed", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "in_progress", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**Next Action**: TodoWrite restored → **Execute Phase 3** (orchestrator's own task)
+
+---
+
+### Phase 3: Cleanup & Verification
+
+**Goal**: Clean up temporary workspace and report completion
+
+**Operations**:
+
+```bash
+# Cleanup temporary workspace
+TRY:
+    Bash(rm -rf .workflow/${temp_id})
+CATCH error:
+    # Silent failure - not critical
+
+# Quick verification
+package_exists = Bash(test -d "${package_path}" && echo "exists" || echo "missing")
+
+IF package_exists != "exists":
+    REPORT: "❌ ERROR: Package generation failed - directory not found"
+    EXIT 1
+
+# Get absolute path and component count for final report
+absolute_package_path = Bash(cd "${package_path}" && pwd 2>/dev/null || echo "${package_path}")
+component_count = Bash(jq -r '.layout_templates | length // "unknown"' "${package_path}/layout-templates.json" 2>/dev/null || echo "unknown")
+anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓" || echo "○")
+```
+
+<!-- TodoWrite: Update Phase 3 → completed -->
+
+**Final Action**: Display completion summary to user
+
+---
+
+## Completion Message
+
+```
+✅ Style reference package generated successfully
+
+📦 Package: {package_name}
+📂 Location: {absolute_package_path}/
+📄 Source: {source}
+📊 Components: {component_count}
+
+Files: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
+
+Preview: file://{absolute_package_path}/preview.html
+
+Next: /memory:style-skill-memory {package_name}
+```
+
+---
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize IMMEDIATELY at the start to track orchestrator workflow (4 high-level tasks)
+TodoWrite({todos: [
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]})
+
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// 1. INITIAL STATE: 4 orchestrator-level tasks only
+//
+// 2. PHASE 1 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+//    - TodoWrite expands to: Phase 0 (completed) + 4 import-from-code tasks + Phase 2 + Phase 3
+//    - Orchestrator EXECUTES these 4 tasks sequentially (Phase 1.0 → 1.1 → 1.2 → 1.3)
+//    - First attached task marked as in_progress
+//
+// 3. PHASE 1 TASKS COMPLETED:
+//    - All 4 import-from-code tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 1 summary
+//    - TodoWrite becomes: Phase 0-1 (completed) + Phase 2 + Phase 3
+//
+// 4. PHASE 2 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
+//    - TodoWrite expands to: Phase 0-1 (completed) + 3 reference-page-generator tasks + Phase 3
+//    - Orchestrator EXECUTES these 3 tasks sequentially (Phase 2.0 → 2.1 → 2.2)
+//
+// 5. PHASE 2 TASKS COMPLETED:
+//    - All 3 reference-page-generator tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 2 summary
+//    - TodoWrite returns to: Phase 0-2 (completed) + Phase 3 (in_progress)
+//
+// 6. PHASE 3 EXECUTION:
+//    - Orchestrator's own task (no SlashCommand attachment)
+//    - Mark Phase 3 as completed
+//    - Final state: All 4 orchestrator tasks completed
+//
+// Benefits:
+// ✓ Real-time visibility into attached tasks during execution
+// ✓ Clean orchestrator-level summary after tasks complete
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Dynamic attachment/collapse maintains clarity
+```
+
+---
+
+## Execution Flow Diagram
+
+```
+User triggers: /workflow:ui-design:codify-style ./src --package-name my-style-v1
+  ↓
+[TodoWrite Init] 4 orchestrator-level tasks
+  ├─ Phase 0: Validate parameters and prepare session (in_progress)
+  ├─ Phase 1: Style extraction from source code (pending)
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Phase 0] Parameter validation & preparation
+  ├─ Parse positional path parameter
+  ├─ Validate source directory exists
+  ├─ Auto-generate or validate package name
+  ├─ Check package overwrite protection
+  ├─ Create temporary workspace
+  └─ Display configuration summary
+  ↓
+[Phase 0 Complete] → TodoWrite: Phase 0 → completed
+  ↓
+[Phase 1 Invoke] → SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1.0: Discover and categorize code files (in_progress)  ← ATTACHED
+  ├─ Phase 1.1: Style Agent extraction (pending)                   ← ATTACHED
+  ├─ Phase 1.2: Animation Agent extraction (pending)               ← ATTACHED
+  ├─ Phase 1.3: Layout Agent extraction (pending)                  ← ATTACHED
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 1.0] → Discover files (orchestrator executes this)
+  ↓
+[Execute Phase 1.1-1.3] → Run 3 agents in parallel (orchestrator executes these)
+  └─ Outputs: design-tokens.json, style-guide.md, animation-tokens.json, layout-templates.json
+  ↓
+[Phase 1 Complete] → TodoWrite: COLLAPSE Phase 1.0-1.3 into Phase 1 summary
+  ↓
+[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)        ← COLLAPSED
+  ├─ Phase 2.0: Setup and validation (in_progress)                 ← ATTACHED
+  ├─ Phase 2.1: Prepare component data (pending)                   ← ATTACHED
+  ├─ Phase 2.2: Generate preview pages (pending)                   ← ATTACHED
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 2.0] → Setup and validation (orchestrator executes this)
+  ↓
+[Execute Phase 2.1] → Prepare component data (orchestrator executes this)
+  ↓
+[Execute Phase 2.2] → Generate preview pages (orchestrator executes this)
+  └─ Outputs: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
+  ↓
+[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.0-2.2 into Phase 2 summary
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)
+  ├─ Phase 2: Reference package generation (completed)             ← COLLAPSED
+  └─ Phase 3: Cleanup and verify package (in_progress)
+  ↓
+[Execute Phase 3] → Orchestrator's own task (no attachment needed)
+  ├─ Remove temporary workspace (.workflow/codify-temp-{timestamp}/)
+  ├─ Verify package directory
+  ├─ Extract component count
+  └─ Display completion summary
+  ↓
+[Phase 3 Complete] → TodoWrite: Phase 3 → completed
+  ├─ Phase 0 (completed)
+  ├─ Phase 1 (completed)
+  ├─ Phase 2 (completed)
+  └─ Phase 3 (completed)
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing --source or --package-name | Required parameters not provided | Provide both flags |
+| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
+| import-from-code failed | Source path invalid or no files found | Verify source path, check glob patterns |
+| reference-page-generator failed | Design run incomplete | Check import-from-code output, verify extraction files |
+| Package verification failed | Output directory creation failed | Check file permissions |
+
+### Error Recovery
+
+- If Phase 2 fails: Cleanup temporary session and report error
+- If Phase 3 fails: Keep design run for debugging, report error
+- User can manually inspect `${design_run_path}` if needed
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
+2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
+3. **Status-Driven Execution**: Check TodoList status after each phase
+4. **Phase Completion Pattern**:
+   ```
+   Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
+   ```
+
+### Parameter Pass-Through
+
+Only essential parameters are passed to `import-from-code`:
+- `--design-id` → temporary design run ID (auto-generated)
+- `--source` → user-specified source directory
+
+File discovery is fully automatic - no glob patterns needed.
+
+### Output Directory Structure
+
+```
+.workflow/
+├── reference_style/              # Default output directory
+│   └── {package-name}/
+│       ├── layout-templates.json
+│       ├── design-tokens.json
+│       ├── animation-tokens.json (optional)
+│       ├── preview.html
+│       └── preview.css
+│
+└── codify-temp-{timestamp}/      # Temporary workspace (cleaned up after completion)
+    ├── style-extraction/
+    ├── animation-extraction/
+    └── layout-extraction/
+```
+
+---
+
+## Benefits
+
+- **Simplified Interface**: Single path parameter with intelligent defaults
+- **Auto-Generation**: Package names auto-generated from directory names
+- **Automatic Discovery**: No need to specify file patterns - finds all style files automatically
+- **Pure Orchestrator**: No direct agent execution, delegates to specialized commands
+- **Auto-Continue**: Autonomous 4-phase execution without user interaction
+- **Safety First**: Overwrite protection, validation checks, error handling
+- **Code Reuse**: Leverages existing `import-from-code` and `reference-page-generator` commands
+- **Clean Separation**: Each command has single responsibility
+- **Easy Maintenance**: Changes to sub-commands automatically apply
+
+## Architecture
+
+```
+codify-style (orchestrator - simplified interface)
+  ├─ Phase 0: Intelligent Validation
+  │   ├─ Parse positional path parameter
+  │   ├─ Auto-generate package name (if not provided)
+  │   ├─ Safety checks (overwrite protection)
+  │   └─ User confirmation
+  ├─ Phase 1: /workflow:ui-design:import-from-code (style extraction)
+  │   ├─ Extract design tokens from source code
+  │   ├─ Generate style guide
+  │   └─ Extract component patterns
+  ├─ Phase 2: /workflow:ui-design:reference-page-generator (reference package)
+  │   ├─ Generate shareable package
+  │   ├─ Create interactive preview
+  │   └─ Generate documentation
+  └─ Phase 3: Cleanup & Verification
+      ├─ Remove temporary workspace
+      ├─ Verify package integrity
+      └─ Report completion
+
+Design Principles:
+✓ No task JSON created by this command
+✓ All extraction delegated to import-from-code
+✓ All packaging delegated to reference-page-generator
+✓ Pure orchestration with intelligent defaults
+✓ Single path parameter for maximum simplicity
+```

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

@@ -1,7 +1,7 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution
-argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
+description: Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection
+argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 
@@ -18,35 +18,60 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 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.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
-8. Phase 5 (batch-plan, optional) → Reports completion
+2. Phase 5: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 7**
+3. Phase 7 (style-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 8
+4. Phase 8 (animation-extract, conditional):
+   - **IF should_extract_animation**: **Attach tasks → Execute → Collapse** → Auto-continues to Phase 9
+   - **ELSE**: Skip (use code import) → Auto-continues to Phase 9
+5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
+6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 11
+7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
 
 **Phase Transition Mechanism**:
-- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
-- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
-- Upon each phase completion: Automatically process output and execute next phase
-- No additional user interaction after Phase 0c confirmation
+- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
+- **Phase 7-10 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
+- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
+- **Task Collapse**: After tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing
+- **Phase 11 (Script Execution)**: Execute preview generation script
+- No additional user interaction after Phase 5 confirmation
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (preview generation).
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
 
 **Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
 
 ## Core Rules
 
-1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+1. **Start Immediately**: TodoWrite initialization → Phase 7 execution
 2. **No Preliminary Validation**: Sub-commands handle their own validation
 3. **Parse & Pass**: Extract data from each output for next phase
 4. **Default to All**: When selecting variants/prototypes, use ALL generated items
-5. **Track Progress**: Update TodoWrite after each phase
-6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (preview generation).
 
 ## Parameter Requirements
 
+**Recommended Parameter**:
+- `--input "<value>"`: Unified input source (auto-detects type)
+  - **Glob pattern** (images): `"design-refs/*"`, `"screenshots/*.png"`
+  - **File/directory path** (code): `"./src/components"`, `"/path/to/styles"`
+  - **Text description** (prompt): `"modern dashboard with 3 styles"`, `"minimalist design"`
+  - **Combination**: `"design-refs/* modern dashboard"` (glob + description)
+  - Multiple inputs: Separate with `|` → `"design-refs/*|modern style"`
+
+**Detection Logic**:
+- Contains `*` or matches existing files → **glob pattern** (images)
+- Existing file/directory path → **code import**
+- Pure text without paths → **design prompt**
+- Contains `|` separator → **multiple inputs** (glob|prompt or path|prompt)
+
+**Legacy Parameters** (deprecated, use `--input` instead):
+- `--images "<glob>"`: Reference image paths (shows deprecation warning)
+- `--prompt "<description>"`: Design description (shows deprecation warning)
+
 **Optional Parameters** (all have smart defaults):
 - `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
 - `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
@@ -56,19 +81,16 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
   - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
   - **Responsive**: 1920×1080px base with mobile-first breakpoints
 - `--session <id>`: Workflow session ID (standalone mode if omitted)
-- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
-- `--prompt "<description>"`: Design style and target description
 - `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
 - `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
-- `--batch-plan`: Auto-generate implementation tasks after design-update
 
-**Legacy Parameters** (maintained for backward compatibility):
+**Legacy Target Parameters** (maintained for backward compatibility):
 - `--pages "<list>"`: Alias for `--targets` with `--target-type page`
 - `--components "<list>"`: Alias for `--targets` with `--target-type component`
 
 **Input Rules**:
-- Must provide at least one: `--images` or `--prompt` or `--targets`
-- Multiple parameters can be combined for guided analysis
+- Must provide: `--input` OR (legacy: `--images`/`--prompt`) OR `--targets`
+- `--input` can combine multiple input types
 - If `--targets` not provided, intelligently inferred from prompt/session
 
 **Supported Target Types**:
@@ -105,27 +127,63 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
 
-## 6-Phase Execution
+## 11-Phase Execution
 
-### Phase 0a: Intelligent Path Detection & Source Selection
+### Phase 1: Parameter Parsing & Input Detection
 ```bash
-# Step 1: Detect if prompt/images contain existing file paths
+# Step 0: Parse and normalize parameters
+images_input = null
+prompt_text = null
+
+# Handle legacy parameters with deprecation warning
+IF --images OR --prompt:
+    WARN: "⚠️  DEPRECATION: --images and --prompt are deprecated. Use --input instead."
+    WARN: "   Example: --input \"design-refs/*\" or --input \"modern dashboard\""
+    images_input = --images
+    prompt_text = --prompt
+
+# Parse unified --input parameter
+IF --input:
+    # Split by | separator for multiple inputs
+    input_parts = split(--input, "|")
+
+    FOR part IN input_parts:
+        part = trim(part)
+
+        # Detection logic
+        IF contains(part, "*") OR glob_matches_files(part):
+            # Glob pattern detected → images
+            images_input = part
+        ELSE IF file_or_directory_exists(part):
+            # File/directory path → will be handled in code detection
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+        ELSE:
+            # Pure text → prompt
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+
+# Step 1: Detect design source from parsed inputs
 code_files_detected = false
 code_base_path = null
 has_visual_input = false
 
-IF --prompt:
+IF prompt_text:
     # Extract potential file paths from prompt
-    potential_paths = extract_paths_from_text(--prompt)
+    potential_paths = extract_paths_from_text(prompt_text)
     FOR path IN potential_paths:
         IF file_or_directory_exists(path):
             code_files_detected = true
             code_base_path = path
             BREAK
 
-IF --images:
+IF images_input:
     # Check if images parameter points to existing files
-    IF glob_matches_files(--images):
+    IF glob_matches_files(images_input):
         has_visual_input = true
 
 # Step 2: Determine design source strategy
@@ -143,20 +201,23 @@ ELSE:
 STORE: design_source, code_base_path, has_visual_input
 ```
 
-### Phase 0a-2: Intelligent Prompt Parsing
+### Phase 2: Intelligent Prompt Parsing
 ```bash
 # Parse variant counts from prompt or use explicit/default values
-IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
-    style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
-    layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
+IF prompt_text AND (NOT --style-variants OR NOT --layout-variants):
+    style_variants = regex_extract(prompt_text, r"(\d+)\s*style") OR --style-variants OR 3
+    layout_variants = regex_extract(prompt_text, r"(\d+)\s*layout") OR --layout-variants OR 3
 ELSE:
     style_variants = --style-variants OR 3
     layout_variants = --layout-variants OR 3
 
 VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+
+# Interactive mode (always enabled)
+interactive_mode = true  # Always use interactive mode
 ```
 
-### Phase 0a-2: Device Type Inference
+### Phase 3: Device Type Inference
 ```bash
 # Device type inference
 device_type = "auto"
@@ -167,14 +228,14 @@ IF --device-type AND --device-type != "auto":
     device_source = "explicit"
 ELSE:
     # Step 2: Prompt analysis
-    IF --prompt:
+    IF prompt_text:
         device_keywords = {
             "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
             "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
             "tablet": ["tablet", "ipad", "medium screen"],
             "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
         }
-        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        detected_device = detect_device_from_prompt(prompt_text, device_keywords)
         IF detected_device:
             device_type = detected_device
             device_source = "prompt_inference"
@@ -201,27 +262,36 @@ STORE: device_type, device_source
 - Prompt contains "responsive", "adaptive" → responsive
 - Otherwise: Inferred from target type (components→desktop, pages→responsive)
 
-### Phase 0b: Run Initialization & Directory Setup
+### Phase 4: Run Initialization & Directory Setup
 ```bash
-run_id = "run-$(date +%Y%m%d-%H%M%S)"
-base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
+relative_base_path = --session ? ".workflow/WFS-{session}/${design_id}" : ".workflow/${design_id}"
 
-Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+# Create directory and convert to absolute path
+Bash(mkdir -p "${relative_base_path}/style-extraction")
+Bash(mkdir -p "${relative_base_path}/prototypes")
+base_path=$(cd "${relative_base_path}" && pwd)
 
 Write({base_path}/.run-metadata.json): {
-  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "design_id": "${design_id}", "session_id": "${session_id}", "timestamp": "...",
   "workflow": "ui-design:auto",
   "architecture": "style-centric-batch-generation",
   "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
                   "targets": "${inferred_target_list}", "target_type": "${target_type}",
-                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "prompt": "${prompt_text}", "images": "${images_input}",
+                  "input": "${--input}",
                   "device_type": "${device_type}", "device_source": "${device_source}" },
   "status": "in_progress",
   "performance_mode": "optimized"
 }
+
+# Initialize default flags for animation extraction logic
+animation_complete = false  # Default: always extract animations unless code import proves complete
+needs_visual_supplement = false  # Will be set to true in hybrid mode
+skip_animation_extraction = false  # User preference for code import scenario
 ```
 
-### Phase 0c: Unified Target Inference with Intelligent Type Detection
+### Phase 5: Unified Target Inference with Intelligent Type Detection
 ```bash
 # Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
 target_list = []; target_type = "auto"; target_source = "none"
@@ -234,8 +304,8 @@ ELSE IF --targets:
     target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
 
 # Step 3: Prompt analysis (Claude internal analysis)
-ELSE IF --prompt:
-    analysis_result = analyze_prompt("{prompt_text}")  # Extract targets, types, purpose
+ELSE IF prompt_text:
+    analysis_result = analyze_prompt(prompt_text)  # Extract targets, types, purpose
     target_list = analysis_result.targets
     target_type = analysis_result.primary_type OR detect_target_type(target_list)
     target_source = "prompt_analysis"
@@ -286,7 +356,7 @@ MATCH user_input:
 
 STORE: inferred_target_list, target_type, target_inference_source
 
-# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 7
 # This is the only user interaction point in the workflow
 # After this point, all subsequent phases execute automatically without user intervention
 ```
@@ -303,17 +373,35 @@ detect_target_type(target_list):
     RETURN "component" IF component_matches > page_matches ELSE "page"
 ```
 
-### Phase 0d: Code Import & Completeness Assessment (Conditional)
+### Phase 6: Code Import & Completeness Assessment (Conditional)
 ```bash
 IF design_source IN ["code_only", "hybrid"]:
-    REPORT: "🔍 Phase 0d: Code Import ({design_source})"
-    command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" --base-path \"{code_base_path}\""
-    SlashCommand(command)
+    REPORT: "🔍 Phase 6: Code Import ({design_source})"
+    command = "/workflow:ui-design:import-from-code --design-id \"{design_id}\" --source \"{code_base_path}\""
+
+    TRY:
+        # SlashCommand invocation ATTACHES import-from-code's tasks to current workflow
+        # Orchestrator will EXECUTE these attached tasks itself:
+        #   - Phase 0: Discover and categorize code files
+        #   - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
+        SlashCommand(command)
+    CATCH error:
+        WARN: "⚠️ Code import failed: {error}"
+        WARN: "Cleaning up incomplete import directories"
+        Bash(rm -rf "{base_path}/style-extraction" "{base_path}/animation-extraction" "{base_path}/layout-extraction" 2>/dev/null)
+
+        IF design_source == "code_only":
+            REPORT: "Cannot proceed with code-only mode after import failure"
+            EXIT 1
+        ELSE:  # hybrid mode
+            WARN: "Continuing with visual-only mode"
+            design_source = "visual_only"
 
     # Check file existence and assess completeness
     style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
     animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
-    layout_exists = exists("{base_path}/layout-extraction/layout-templates.json")
+    layout_count = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
+    layout_exists = (layout_count > 0)
 
     style_complete = false
     animation_complete = false
@@ -349,14 +437,16 @@ IF design_source IN ["code_only", "hybrid"]:
 
     # Layout completeness check
     IF layout_exists:
-        layouts = Read("{base_path}/layout-extraction/layout-templates.json")
+        # Read first layout file to verify structure
+        first_layout = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | head -1)
+        layout_data = Read(first_layout)
         layout_complete = (
-            layouts.layout_templates?.length >= 3 &&
-            layouts.extraction_metadata?.layout_system?.type &&
-            layouts.extraction_metadata?.responsive?.breakpoints
+            layout_count >= 1 &&
+            layout_data.template?.dom_structure &&
+            layout_data.template?.css_layout_rules
         )
-        IF NOT layout_complete AND layouts.extraction_metadata?.completeness?.missing_items:
-            missing_categories.extend(layouts.extraction_metadata.completeness.missing_items)
+        IF NOT layout_complete:
+            missing_categories.push("complete layout structure")
     ELSE:
         missing_categories.push("layout templates")
 
@@ -374,169 +464,206 @@ IF design_source IN ["code_only", "hybrid"]:
     ELSE IF design_source == "hybrid":
         needs_visual_supplement = true
 
-    STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete
+    # Animation reuse confirmation (code import with complete animations)
+    IF design_source == "code_only" AND animation_complete:
+        REPORT: "✅ 检测到完整的动画系统（来自代码导入）"
+        REPORT: "   Duration scales: {duration_count} | Easing functions: {easing_count}"
+        REPORT: ""
+        REPORT: "Options:"
+        REPORT: "  • 'reuse' (默认) - 复用已有动画系统"
+        REPORT: "  • 'regenerate' - 重新生成动画系统（交互式）"
+        REPORT: "  • 'cancel' - 取消工作流"
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+            "reuse" → skip_animation_extraction = true
+            "regenerate" → skip_animation_extraction = false
+            "cancel" → EXIT 0
+            default → skip_animation_extraction = true  # Default: reuse
+
+    STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete, skip_animation_extraction
 ```
 
-### Phase 1: Style Extraction
+### Phase 7: Style Extraction
 ```bash
 IF design_source == "visual_only" OR needs_visual_supplement:
-    REPORT: "🎨 Phase 1: Style Extraction (variants: {style_variants})"
-    command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
-              (--images ? "--images \"{images}\" " : "") +
-              (--prompt ? "--prompt \"{prompt}\" " : "") +
-              "--mode explore --variants {style_variants}"
+    REPORT: "🎨 Phase 7: Style Extraction (variants: {style_variants})"
+    command = "/workflow:ui-design:style-extract --design-id \"{design_id}\" " +
+              (images_input ? "--images \"{images_input}\" " : "") +
+              (prompt_text ? "--prompt \"{prompt_text}\" " : "") +
+              "--variants {style_variants} --interactive"
+
+    # SlashCommand invocation ATTACHES style-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
 ELSE:
-    REPORT: "✅ Phase 1: Style (Using Code Import)"
+    REPORT: "✅ Phase 7: Style (Using Code Import)"
 ```
 
-### Phase 2.3: Animation Extraction
+### Phase 8: Animation Extraction
 ```bash
-IF design_source == "visual_only" OR NOT animation_complete:
-    REPORT: "🚀 Phase 2.3: Animation Extraction"
-    command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
+# Determine if animation extraction is needed
+should_extract_animation = false
+
+IF (design_source == "visual_only" OR needs_visual_supplement):
+    # Pure visual input or hybrid mode requiring visual supplement
+    should_extract_animation = true
+ELSE IF NOT animation_complete:
+    # Code import but animations are incomplete
+    should_extract_animation = true
+ELSE IF design_source == "code_only" AND animation_complete AND NOT skip_animation_extraction:
+    # Code import with complete animations, but user chose to regenerate
+    should_extract_animation = true
+
+IF should_extract_animation:
+    REPORT: "🚀 Phase 8: Animation Extraction"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:animation-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    command_parts.append("--interactive")
+
+    command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES animation-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
 ELSE:
-    REPORT: "✅ Phase 2.3: Animation (Using Code Import)"
+    REPORT: "✅ Phase 8: Animation (Using Code Import)"
 
 # Output: animation-tokens.json + animation-guide.md
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
+# When phase finishes, IMMEDIATELY execute Phase 9 (auto-continue)
 ```
 
-### Phase 2.5: Layout Extraction
+### Phase 9: Layout Extraction
 ```bash
 targets_string = ",".join(inferred_target_list)
 
 IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_complete):
-    REPORT: "🚀 Phase 2.5: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})"
-    command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
-              (--images ? "--images \"{images}\" " : "") +
-              (--prompt ? "--prompt \"{prompt}\" " : "") +
-              "--targets \"{targets_string}\" --mode explore --variants {layout_variants} --device-type \"{device_type}\""
+    REPORT: "🚀 Phase 9: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})"
+    command = "/workflow:ui-design:layout-extract --design-id \"{design_id}\" " +
+              (images_input ? "--images \"{images_input}\" " : "") +
+              (prompt_text ? "--prompt \"{prompt_text}\" " : "") +
+              "--targets \"{targets_string}\" --variants {layout_variants} --device-type \"{device_type}\" --interactive"
+
+    # SlashCommand invocation ATTACHES layout-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
 ELSE:
-    REPORT: "✅ Phase 2.5: Layout (Using Code Import)"
+    REPORT: "✅ Phase 9: Layout (Using Code Import)"
 ```
 
-### Phase 3: UI Assembly
+### Phase 10: UI Assembly
 ```bash
-command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
-          "--style-variants {style_variants} --layout-variants {layout_variants}"
+command = "/workflow:ui-design:generate --design-id \"{design_id}\"" + (--session ? " --session {session_id}" : "")
 
 total = style_variants × layout_variants × len(inferred_target_list)
 
-REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "🚀 Phase 10: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
 REPORT: "   → Pure assembly: Combining layout templates + design tokens"
 REPORT: "   → Device: {device_type} (from layout templates)"
 REPORT: "   → Assembly tasks: {total} combinations"
 
+# SlashCommand invocation ATTACHES generate's tasks to current workflow
+# Orchestrator will EXECUTE these attached tasks itself
 SlashCommand(command)
 
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
+# After executing all attached tasks, collapse them into phase summary
+# When phase finishes, IMMEDIATELY execute Phase 11 (auto-continue)
 # Output:
 # - {target}-style-{s}-layout-{l}.html (assembled prototypes)
 # - {target}-style-{s}-layout-{l}.css
-# - compare.html (interactive matrix view)
-# - PREVIEW.md (usage instructions)
+# Note: compare.html and PREVIEW.md will be generated in Phase 11
 ```
 
-### Phase 4: Design System Integration
+### Phase 11: Generate Preview Files
 ```bash
-command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
-SlashCommand(command)
+REPORT: "🚀 Phase 11: Generate Preview Files"
 
-# SlashCommand blocks until phase complete
-# Upon completion:
-#   - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
-#   - If no --batch-plan: Workflow complete, display final report
-```
+# Update TodoWrite to reflect preview generation phase
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
+  {"content": "Generate preview files", "status": "in_progress", "activeForm": "Generating preview files"}
+]})
 
-### Phase 5: Batch Task Generation (Optional)
-```bash
-IF --batch-plan:
-    FOR target IN inferred_target_list:
-        task_desc = "Implement {target} {target_type} based on design system"
-        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
+# Execute preview generation script
+Bash(~/.claude/scripts/ui-generate-preview.sh "${base_path}/prototypes")
+
+# Verify output files
+IF NOT exists("${base_path}/prototypes/compare.html"):
+    ERROR: "Preview generation failed: compare.html not found"
+    EXIT 1
+
+IF NOT exists("${base_path}/prototypes/PREVIEW.md"):
+    ERROR: "Preview generation failed: PREVIEW.md not found"
+    EXIT 1
+
+# Mark preview generation as complete
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
+  {"content": "Generate preview files", "status": "completed", "activeForm": "Generating preview files"}
+]})
+
+REPORT: "✅ Preview files generated successfully"
+REPORT: "   → compare.html (interactive matrix view)"
+REPORT: "   → PREVIEW.md (usage instructions)"
+
+# Workflow complete, display final report
 ```
 
 ## TodoWrite Pattern
 ```javascript
-// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
+// Initialize IMMEDIATELY after Phase 5 user confirmation to track multi-phase execution (5 orchestrator-level tasks)
 TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "in_progress", "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..."}
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "pending", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"},
+  {"content": "Generate preview files", "status": "pending", "activeForm": "Generating preview files"}
 ]})
 
-// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
-// 1. SlashCommand blocks and returns when phase is complete
-// 2. Update current phase: status → "completed"
-// 3. Update next phase: status → "in_progress"
-// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
-// This ensures continuous workflow tracking and prevents premature stopping
-```
-
-## Key Features
-
-- **🚀 Performance**: Style-centric batch generation with S agent calls
-- **🎨 Style-Aware**: HTML structure adapts to design_attributes
-- **✅ Perfect Consistency**: Each style by single agent
-- **📦 Autonomous**: No user intervention required between phases
-- **🧠 Intelligent**: Parses natural language, infers targets/types
-- **🔄 Reproducible**: Deterministic flow with isolated run directories
-- **🎯 Flexible**: Supports pages, components, or mixed targets
-
-## Examples
-
-### 1. Page Mode (Prompt Inference)
-```bash
-/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
-# Result: 27 prototypes (3×3×3) - responsive layouts (default)
-```
-
-### 2. Mobile-First Design
-```bash
-/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
-# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
-```
-
-### 3. Desktop Application
-```bash
-/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
-# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
-```
-
-### 4. Tablet Interface
-```bash
-/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
-# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
-```
-
-### 5. Custom Matrix with Session
-```bash
-/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
-# Result: 2×2×N prototypes - device type inferred from session
-```
-
-### 6. Component Mode (Desktop)
-```bash
-/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
-# Result: 12 prototypes (3×2×2) - desktop components
-```
-
-### 7. Intelligent Parsing + Batch Planning
-```bash
-/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
-# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
-```
-
-### 8. Large Scale Responsive
-```bash
-/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
-# Result: 36 prototypes (3×3×4) - responsive layouts
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// Phase 7-10 SlashCommand Invocation Pattern:
+// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
+// 2. TodoWrite expands to include attached tasks
+// 3. Orchestrator EXECUTES attached tasks sequentially
+// 4. After all attached tasks complete, COLLAPSE them into phase summary
+// 5. Update next phase to in_progress
+// 6. IMMEDIATELY execute next phase (auto-continue)
+//
+// Phase 11 Script Execution Pattern:
+// 1. Mark "Generate preview files" as in_progress
+// 2. Execute preview generation script via Bash tool
+// 3. Verify output files (compare.html, PREVIEW.md)
+// 4. Mark "Generate preview files" as completed
+//
+// Benefits:
+// ✓ Real-time visibility into sub-command task progress
+// ✓ Clean orchestrator-level summary after each phase
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Script execution for preview generation (no delegation)
+// ✓ Dynamic attachment/collapse maintains clarity
 ```
 
 ## Completion Output
@@ -547,34 +674,37 @@ 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} complete design systems (style-extract)
-Phase 2: {n×l} layout templates (layout-extract explore mode)
+Phase 7: {s} complete design systems (style-extract with multi-select)
+Phase 9: {n×l} layout templates (layout-extract with multi-select)
   - Device: {device_type} layouts
   - {n} targets × {l} layout variants = {n×l} structural templates
-Phase 3: UI Assembly (generate)
+  - User-selected concepts generated in parallel
+Phase 10: UI Assembly (generate)
   - Pure assembly: layout templates + design tokens
   - {s}×{l}×{n} = {total} final prototypes
-Phase 4: Brainstorming artifacts updated
-[Phase 5: {n} implementation tasks created]  # if --batch-plan
+Phase 11: Preview files generated (compare.html, PREVIEW.md)
 
 Assembly Process:
 ✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
 ✅ Layout Extraction: {n×l} reusable structural templates
+✅ Multi-Selection Workflow: User selects multiple variants from generated options
 ✅ Pure Assembly: No design decisions in generate phase
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 Design Quality:
 ✅ Token-Driven Styling: 100% var() usage
-✅ Structural Variety: {l} distinct layouts per target
-✅ Style Variety: {s} independent design systems
+✅ Structural Variety: {l} distinct layouts per target (user-selected)
+✅ Style Variety: {s} independent design systems (user-selected)
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 📂 {base_path}/
   ├── .intermediates/          (Intermediate analysis files)
-  │   ├── style-analysis/      (computed-styles.json, design-space-analysis.json)
-  │   └── layout-analysis/     (dom-structure-*.json, inspirations/*.txt)
+  │   ├── style-analysis/      (analysis-options.json with embedded user_selection, computed-styles.json if URL mode)
+  │   ├── animation-analysis/  (analysis-options.json with embedded user_selection, animations-*.json if URL mode)
+  │   └── layout-analysis/     (analysis-options.json with embedded user_selection, dom-structure-*.json if URL mode)
   ├── style-extraction/        ({s} complete design systems)
-  ├── layout-extraction/       ({n×l} layout templates + layout-space-analysis.json)
+  ├── animation-extraction/    (animation-tokens.json, animation-guide.md)
+  ├── layout-extraction/       ({n×l} layout template files: layout-{target}-{variant}.json)
   ├── prototypes/              ({total} assembled prototypes)
   └── .run-metadata.json       (includes device type)
 
@@ -590,6 +720,6 @@ Design Quality:
   - Layout plans stored as structured JSON
   - Optimized for {device_type} viewing
 
-Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+Next: Open compare.html to preview all design variants
 ```
 

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

@@ -1,7 +1,7 @@
 ---
 name: explore-layers
 description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer
-argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
+argument-hint: --url <url> --depth <1-5> [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
 ---
 
@@ -38,17 +38,39 @@ IF depth NOT IN [1, 2, 3, 4, 5]:
 
 ### Step 2: Determine Base Path
 ```bash
-bash(if [ -n "$BASE_PATH" ]; then
-  echo "$BASE_PATH"
+# Priority: --design-id > --session > create new
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+  if [ -z "$relative_path" ]; then
+    echo "ERROR: Design run not found: $DESIGN_ID"
+    echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
+    exit 1
+  fi
 elif [ -n "$SESSION_ID" ]; then
-  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
-  echo ".workflow/WFS-$SESSION_ID/design-layers-$(date +%Y%m%d-%H%M%S)"
+  # Find latest in session or create new
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  if [ -z "$relative_path" ]; then
+    design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+    relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
+  fi
 else
-  echo ".workflow/.design/layers-$(date +%Y%m%d-%H%M%S)"
-fi)
+  # Create new standalone design run
+  design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+  relative_path=".workflow/${design_id}"
+fi
+
+# Create directory structure and convert to absolute path
+bash(mkdir -p "$relative_path")
+base_path=$(cd "$relative_path" && pwd)
+
+# Extract and display design_id
+design_id=$(basename "$base_path")
+echo "✓ Design ID: $design_id"
+echo "✓ Base path: $base_path"
 
 # Create depth directories
-bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
+bash(for i in $(seq 1 $depth); do mkdir -p "$base_path"/screenshots/depth-$i; done)
 ```
 
 **Output**: `url`, `depth`, `base_path`

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

@@ -1,7 +1,7 @@
 ---
 name: generate
-description: Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation
-argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+description: Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation
+argument-hint: [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---
 
@@ -11,7 +11,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
 
 **Strategy**: Pure Assembly
-- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available)
+- **Input**: `layout-*.json` files + `design-tokens.json` (+ reference images if available)
 - **Process**: Combine structure (DOM) with style (tokens)
 - **Output**: Complete HTML/CSS prototypes
 - **No Design Logic**: All layout and style decisions already made
@@ -25,23 +25,48 @@ Pure assembler that combines pre-extracted layout templates with design tokens t
 
 ### Step 1: Resolve Base Path & Parse Configuration
 ```bash
-# Determine working directory
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 
 # Get style count
-bash(ls {base_path}/style-extraction/style-* -d | wc -l)
+bash(ls "$base_path"/style-extraction/style-* -d | wc -l)
 
 # Image reference auto-detected from layout template source_image_path
 ```
 
 ### Step 2: Load Layout Templates
 ```bash
-# Check layout templates exist
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# Check layout templates exist (multi-file pattern)
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 
-# Load layout templates
-Read({base_path}/layout-extraction/layout-templates.json)
-# Extract: targets, layout_variants count, device_type, template structures
+# Get list of all layout files
+bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null)
+
+# Load each layout template file
+FOR each layout_file in layout_files:
+    template_data = Read(layout_file)
+    # Extract: target, variant_id, device_type, dom_structure, css_layout_rules
+
+# Aggregate: targets[], layout_variants count, device_type, all template structures
 ```
 
 **Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
@@ -74,30 +99,97 @@ ELSE:
 
 ## Phase 2: Assembly (Agent)
 
-**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
+**Executor**: `Task(ui-design-agent)` grouped by `target × style` (max 10 layouts per agent, max 6 concurrent agents)
 
-### Step 1: Launch Assembly Tasks
-```bash
-bash(mkdir -p {base_path}/prototypes)
+**⚠️ Core Principle**: **Each agent processes ONLY ONE style** (but can process multiple layouts for that style)
+
+### Agent Grouping Strategy
+
+**Grouping Rules**:
+1. **Style Isolation**: Each agent processes ONLY ONE style (never mixed)
+2. **Balanced Distribution**: Layouts evenly split (e.g., 12→6+6, not 10+2)
+3. **Target Separation**: Different targets use different agents
+
+**Distribution Formula**:
+```
+agents_needed = ceil(layout_count / MAX_LAYOUTS_PER_AGENT)
+base_count = floor(layout_count / agents_needed)
+remainder = layout_count % agents_needed
+# First 'remainder' agents get (base_count + 1), others get base_count
 ```
 
-For each `target × style_id × layout_id`:
+**Examples** (MAX=10):
+
+| Scenario | Result | Explanation |
+|----------|--------|-------------|
+| 3 styles × 3 layouts | 3 agents | Each style: 1 agent (3 layouts) |
+| 3 styles × 12 layouts | 6 agents | Each style: 2 agents (6+6 layouts) |
+| 2 styles × 5 layouts × 2 targets | 4 agents | Each (target, style): 1 agent (5 layouts) |
+
+### Step 1: Calculate Agent Grouping Plan
+```bash
+bash(mkdir -p {base_path}/prototypes)
+
+MAX_LAYOUTS_PER_AGENT = 10
+MAX_PARALLEL = 6
+
+agent_groups = []
+FOR each target in targets:
+  FOR each style_id in [1..S]:
+    layouts_for_this_target_style = filter layouts by current target
+    layout_count = len(layouts_for_this_target_style)
+
+    # Balanced distribution (e.g., 12 layouts → 6+6)
+    agents_needed = ceil(layout_count / MAX_LAYOUTS_PER_AGENT)
+    base_count = floor(layout_count / agents_needed)
+    remainder = layout_count % agents_needed
+
+    layout_chunks = []
+    start_idx = 0
+    FOR i in range(agents_needed):
+      chunk_size = base_count + 1 if i < remainder else base_count
+      layout_chunks.append(layouts[start_idx : start_idx + chunk_size])
+      start_idx += chunk_size
+
+    FOR each chunk in layout_chunks:
+      agent_groups.append({
+        target: target,           # Single target
+        style_id: style_id,       # Single style
+        layout_ids: chunk         # Balanced layouts (≤10)
+      })
+
+total_agents = len(agent_groups)
+total_batches = ceil(total_agents / MAX_PARALLEL)
+
+TodoWrite({todos: [
+  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
+  {content: "Batch 1/{total_batches}: Assemble up to 6 agent groups", status: "in_progress", activeForm: "Assembling batch 1"},
+  {content: "Batch 2/{total_batches}: Assemble up to 6 agent groups", status: "pending", activeForm: "Assembling batch 2"},
+  ... (continue for all batches)
+]})
+```
+
+### Step 2: Launch Batched Assembly Tasks
+
+For each batch (up to 6 parallel agents per batch):
+For each agent group `{target, style_id, layout_ids[]}` in current batch:
 ```javascript
 Task(ui-design-agent): `
   [LAYOUT_STYLE_ASSEMBLY]
-  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
-  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
+  🎯 {target} × Style-{style_id} × Layouts-{layout_ids}
+  ⚠️ CONSTRAINT: Use ONLY style-{style_id}/design-tokens.json (never mix styles)
 
-  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
+  TARGET: {target} | STYLE: {style_id} | LAYOUTS: {layout_ids} (max 10)
   BASE_PATH: {base_path}
 
   ## Inputs (READ ONLY - NO DESIGN DECISIONS)
-  1. Layout Template:
-     Read("{base_path}/layout-extraction/layout-templates.json")
-     Find template where: target={target} AND variant_id="layout-{layout_id}"
-     Extract: dom_structure, css_layout_rules, device_type, source_image_path
+  1. Layout Templates (LOOP THROUGH):
+     FOR each layout_id in layout_ids:
+       Read("{base_path}/layout-extraction/layout-{target}-{layout_id}.json")
+       This file contains the specific layout template for this target and variant.
+       Extract: dom_structure, css_layout_rules, device_type, source_image_path (from template field)
 
-  2. Design Tokens:
+  2. Design Tokens (SHARED - READ ONCE):
      Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
      Extract: ALL token values including:
        * colors, typography (with combinations), spacing, opacity
@@ -121,61 +213,70 @@ Task(ui-design-agent): `
      ELSE:
        Use generic placeholder content
 
-  ## Assembly Process
-  1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
-     - Recursively build from template.dom_structure
-     - Add: <!DOCTYPE html>, <head>, <meta viewport>
-     - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
-     - Inject placeholder content:
-       * Default: Use Lorem ipsum, generic sample data
-       * If reference image available: Generate more contextually appropriate placeholders
-         (e.g., realistic headings, meaningful text snippets that match the visual context)
-     - Preserve all attributes from dom_structure
+  ## Assembly Process (LOOP FOR EACH LAYOUT)
+  FOR each layout_id in layout_ids:
 
-  2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
-     - Start with template.css_layout_rules
-     - Replace ALL var(--*) with actual token values from design-tokens.json
-       Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
-       Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
-       Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
-     - Add visual styling using design tokens:
-       * Colors: tokens.colors.*
-       * Typography: tokens.typography.* (including combinations)
-       * Opacity: tokens.opacity.*
-       * Shadows: tokens.shadows.*
-       * Border radius: tokens.border_radius.*
-     - IF tokens.component_styles exists: Add component style classes
-       * Generate classes for button variants (.btn-primary, .btn-secondary)
-       * Generate classes for card variants (.card-default, .card-interactive)
-       * Generate classes for input variants (.input-default, .input-focus, .input-error)
-       * Use var() references that resolve to actual token values
-     - IF tokens.typography.combinations exists: Add typography preset classes
-       * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
-       * Use var() references for family, size, weight, line-height, letter-spacing
-     - IF has_animations == true: Inject animation tokens
-       * Add CSS Custom Properties for animations at :root level:
-         --duration-instant, --duration-fast, --duration-normal, etc.
-         --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
+    1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
+       - Recursively build from template.dom_structure
+       - Add: <!DOCTYPE html>, <head>, <meta viewport>
+       - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
+       - Inject placeholder content:
+         * Default: Use Lorem ipsum, generic sample data
+         * If reference image available: Generate more contextually appropriate placeholders
+           (e.g., realistic headings, meaningful text snippets that match the visual context)
+       - Preserve all attributes from dom_structure
+
+    2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
+       - Start with template.css_layout_rules
+       - Replace ALL var(--*) with actual token values from design-tokens.json
+         Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
+         Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+         Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
+       - Add visual styling using design tokens:
+         * Colors: tokens.colors.*
+         * Typography: tokens.typography.* (including combinations)
+         * Opacity: tokens.opacity.*
+         * Shadows: tokens.shadows.*
+         * Border radius: tokens.border_radius.*
+       - IF tokens.component_styles exists: Add component style classes
+         * Generate classes for button variants (.btn-primary, .btn-secondary)
+         * Generate classes for card variants (.card-default, .card-interactive)
+         * Generate classes for input variants (.input-default, .input-focus, .input-error)
+         * Use var() references that resolve to actual token values
+       - IF tokens.typography.combinations exists: Add typography preset classes
+         * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
+         * Use var() references for family, size, weight, line-height, letter-spacing
+       - IF has_animations == true: Inject animation tokens (ONCE, shared across layouts)
+         * 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
+
+    3. Write files IMMEDIATELY after each layout completes
 
   ## Assembly Rules
-  - ✅ Pure assembly: Combine existing structure + existing style
-  - ❌ NO layout design decisions (structure pre-defined)
-  - ❌ NO style design decisions (tokens pre-defined)
+  - ✅ Pure assembly: Combine pre-extracted structure + tokens
+  - ❌ NO design decisions (layout/style pre-defined)
+  - ✅ Read tokens ONCE, apply to all layouts in this batch
   - ✅ Replace var() with actual values
-  - ✅ Add placeholder content only
-  - Write files IMMEDIATELY
-  - CSS filename MUST match HTML <link href="...">
+  - ✅ CSS filename MUST match HTML <link href="...">
+
+  ## Output
+  - Files: {len(layout_ids) × 2} (HTML + CSS pairs)
+  - Each layout generates 2 files independently
 `
+
+# After each batch completes
+TodoWrite: Mark current batch completed, next batch in_progress
 ```
 
-### Step 2: Verify Generated Files
+### Step 3: Verify Generated Files
 ```bash
-# Count expected vs found
+# Count expected vs found (should equal S × L × T)
 bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
 
 # Validate samples
@@ -183,7 +284,7 @@ Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
 # Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
 ```
 
-**Output**: `S × L × T × 2` files verified
+**Output**: `total_files = S × L × T × 2` files verified (HTML + CSS pairs)
 
 ## Phase 3: Generate Preview Files
 
@@ -210,10 +311,10 @@ bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {b
 ```javascript
 TodoWrite({todos: [
   {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
-  {content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
-  {content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
-  {content: "Verify files", status: "completed", activeForm: "Validating output"},
-  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
+  {content: "Batch 1/{total_batches}: Assemble 6 tasks", status: "completed", activeForm: "Assembling batch 1"},
+  {content: "Batch 2/{total_batches}: Assemble 6 tasks", status: "completed", activeForm: "Assembling batch 2"},
+  ... (all batches completed)
+  {content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
 ]});
 ```
 
@@ -223,33 +324,41 @@ TodoWrite({todos: [
 
 Configuration:
 - Style Variants: {style_variants}
-- Layout Variants: {layout_variants} (from layout-templates.json)
+- Layout Variants: {layout_variants} (from layout-*.json files)
 - Device Type: {device_type}
 - Targets: {targets}
 - Total Prototypes: {S × L × T}
 - Image Reference: Auto-detected (uses source images when available in layout templates)
+- Animation Support: {has_animations ? 'Enabled (animation-tokens.json loaded)' : 'Not available'}
 
 Assembly Process:
 - Pure assembly: Combined pre-extracted layouts + design tokens
-- No design decisions: All structure and style pre-defined
-- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations
+- Agent grouping: target × style (max 10 layouts per agent)
+- Balanced distribution: Layouts evenly split (e.g., 12 → 6+6, not 10+2)
+
+Batch Execution:
+- Total agents: {total_agents} (each processes ONE style only)
+- Batches: {total_batches} (max 6 agents parallel)
+- Token efficiency: Read once per agent, apply to all layouts
 
 Quality:
 - Structure: From layout-extract (DOM, CSS layout rules)
 - Style: From style-extract (design tokens)
 - CSS: Token values directly applied (var() replaced)
 - Device-optimized: Layouts match device_type from templates
+- Animations: {has_animations ? 'CSS custom properties and @keyframes injected' : 'Static styles only'}
 
 Generated Files:
 {base_path}/prototypes/
-├── _templates/
-│   └── layout-templates.json (input, pre-extracted)
 ├── {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)
 
+Input Files (from layout-extraction/):
+├── layout-{target}-{variant}.json (multiple files, one per target-variant combination)
+
 Preview:
 1. Open compare.html (recommended)
 2. Open index.html
@@ -263,7 +372,7 @@ Next: /workflow:ui-design:update
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Count style variants
 bash(ls {base_path}/style-extraction/style-* -d | wc -l)
@@ -271,8 +380,11 @@ bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 
 ### Validation Commands
 ```bash
-# Check layout templates exist
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# Check layout templates exist (multi-file pattern)
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
+
+# Count layout files
+bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
 
 # Check design tokens exist
 bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
@@ -298,10 +410,10 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 ```
 {base_path}/
 ├── layout-extraction/
-│   └── layout-templates.json      # Input (from layout-extract)
+│   └── layout-{target}-{variant}.json  # Input (multiple files from layout-extract)
 ├── style-extraction/
 │   └── style-{s}/
-│       ├── design-tokens.json     # Input (from style-extract)
+│       ├── design-tokens.json          # Input (from style-extract)
 │       └── style-guide.md
 └── prototypes/
     ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
@@ -330,7 +442,7 @@ ERROR: Script permission denied
 
 ### Recovery Strategies
 - **Partial success**: Keep successful assembly combinations
-- **Invalid template structure**: Validate layout-templates.json
+- **Invalid template structure**: Validate layout-*.json files
 - **Invalid tokens**: Validate design-tokens.json structure
 
 ## Quality Checklist
@@ -346,18 +458,17 @@ ERROR: Script permission denied
 ## Key Features
 
 - **Pure Assembly**: No design decisions, only combination
-- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
-- **Token Resolution**: var() placeholders replaced with actual values
-- **Pre-validated**: Inputs already validated by extract/consolidate
-- **Efficient**: Simple assembly vs complex generation
+- **Token Resolution**: var() → actual values
+- **Efficient Grouping**: target × style (max 10 layouts/agent, balanced split)
+- **Style Isolation**: Each agent processes ONE style only
 - **Production-Ready**: Semantic, accessible, token-driven
 
 ## Integration
 
 **Prerequisites**:
 - `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
-- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+- `/workflow:ui-design:layout-extract` → `layout-{target}-{variant}.json` files
 
-**Input**: `layout-templates.json` + `design-tokens.json`
+**Input**: `layout-*.json` files + `design-tokens.json`
 **Output**: S×L×T prototypes for `/workflow:ui-design:update`
 **Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`

.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 capture and design token extraction
-argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt "<desc>"]
+description: UI design workflow with direct code/image input for design token extraction and prototype generation
+argument-hint: "[--input "<value>"] [--session <id>]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ---
 
@@ -9,79 +9,85 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 
 ## Overview & Execution Model
 
-**Fully autonomous replication orchestrator**: Efficiently replicate multiple web pages through sequential execution from screenshot capture to design integration.
+**Fully autonomous design orchestrator**: Efficiently create UI prototypes through sequential execution from design token extraction to system integration.
 
-**Dual Capture Strategy**: Supports two capture modes for different use cases:
-- **Batch Mode** (default): Fast multi-URL screenshot capture via `/workflow:ui-design:capture`
-- **Deep Mode**: Interactive layer exploration for single URL via `/workflow:ui-design:explore-layers`
+**Direct Input Strategy**: Accepts local code files and images:
+- **Code Files**: Detect file paths in `--prompt` parameter
+- **Images**: Reference images via `--images` glob pattern
+- **Hybrid**: Combine both code and visual inputs
 
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
-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 (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
+1. User triggers: `/workflow:ui-design:imitate-auto [--input "..."]`
+2. Phase 0: Initialize and detect input sources
+3. Phase 2: Style extraction → **Attach tasks → Execute → Collapse** → Auto-continues
+4. Phase 2.3: Animation extraction → **Attach tasks → Execute → Collapse** → Auto-continues
+5. Phase 2.5: Layout extraction → **Attach tasks → Execute → Collapse** → Auto-continues
+6. Phase 3: Batch UI assembly → **Attach tasks → Execute → Collapse** → Auto-continues
+7. Phase 4: Design system integration → **Execute orchestrator task** → Reports completion
 
 **Phase Transition Mechanism**:
-- `SlashCommand` is BLOCKING - execution pauses until completion
-- Upon each phase completion: Automatically process output and execute next phase
+- **Task Attachment**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
+- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
+- **Task Collapse**: After tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing
 - No user interaction required after initial parameter parsing
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 5.
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 4.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
 
 ## Core Rules
 
-1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+1. **Start Immediately**: TodoWrite initialization → Phase 2 execution
 2. **No Preliminary Validation**: Sub-commands handle their own validation
 3. **Parse & Pass**: Extract data from each output for next phase
-4. **Track Progress**: Update TodoWrite after each phase
-5. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 5.
+4. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+5. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 4.
 
 ## Parameter Requirements
 
-**Required Parameters**:
-- `--url-map "<map>"`: Target page mapping
-  - Format: `"target1:url1, target2:url2, ..."`
-  - Example: `"home:https://linear.app, pricing:https://linear.app/pricing"`
-  - First target serves as primary style source
+**Recommended Parameter**:
+- `--input "<value>"`: Unified input source (auto-detects type)
+  - **Glob pattern** (images): `"design-refs/*"`, `"screenshots/*.png"`
+  - **File/directory path** (code): `"./src/components"`, `"/path/to/styles"`
+  - **Text description** (prompt): `"Focus on dark mode"`, `"Emphasize minimalist design"`
+  - **Combination**: `"design-refs/* modern dashboard style"` (glob + description)
+  - Multiple inputs: Separate with `|` → `"design-refs/*|modern style"`
+
+**Detection Logic**:
+- Contains `*` or matches existing files → **glob pattern** (images)
+- Existing file/directory path → **code import**
+- Pure text without paths → **design prompt**
+- Contains `|` separator → **multiple inputs** (glob|prompt or path|prompt)
+
+**Legacy Parameters** (deprecated, use `--input` instead):
+- `--images "<glob>"`: Reference image paths (shows deprecation warning)
+- `--prompt "<desc>"`: Design description (shows deprecation warning)
 
 **Optional Parameters**:
-- `--capture-mode <batch|deep>` (Optional, default: batch): Screenshot capture strategy
-  - `batch` (default): Multi-URL fast batch capture via `/workflow:ui-design:capture`
-  - `deep`: Single-URL interactive depth exploration via `/workflow:ui-design:explore-layers`
-  - **Note**: `deep` mode only uses first URL from url-map
-
-- `--depth <1-5>` (Optional, default: 3): Capture depth for deep mode
-  - `1`: Page level (full-page screenshot)
-  - `2`: Element level (+ key components)
-  - `3`: Interaction level (+ modals, dropdowns)
-  - `4`: Embedded level (+ iframes)
-  - `5`: Shadow DOM (+ web components)
-  - **Only applies when** `--capture-mode deep`
-
-- `--session <id>` (Optional): Workflow session ID
+- `--session <id>`: Workflow session ID
   - Integrate into existing session (`.workflow/WFS-{session}/`)
-  - Enable automatic design system integration (Phase 5)
-  - If not provided: standalone mode (`.workflow/.design/`)
+  - Enable automatic design system integration (Phase 4)
+  - If not provided: standalone mode (`.workflow/`)
 
-- `--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)
+**Input Rules**:
+- Must provide: `--input` OR (legacy: `--images`/`--prompt`)
+- `--input` can combine multiple input types
+- File paths are automatically detected and trigger code import
 
 ## Execution Modes
 
-**Capture Modes**:
-- **Batch Mode** (default): Multi-URL screenshot capture for fast replication
-  - Uses `/workflow:ui-design:capture` for parallel screenshot capture
-  - Optimized for replicating multiple pages efficiently
-- **Deep Mode**: Single-URL layer exploration for detailed analysis
-  - Uses `/workflow:ui-design:explore-layers` for interactive depth traversal
-  - Captures page layers at different depths (1-5)
-  - Only processes first URL from url-map
+**Input Sources**:
+- **Code Files**: Automatically detected from `--prompt` file paths
+  - Triggers `/workflow:ui-design:import-from-code` for token extraction
+  - Analyzes existing CSS/JS/HTML files
+- **Visual Input**: Images via `--images` glob pattern
+  - Reference images for style extraction
+  - Screenshots or design mockups
+- **Hybrid Mode**: Combines code import with visual supplements
+  - Code provides base tokens
+  - Images supplement missing design elements
 
 **Token Processing**:
 - **Direct Generation**: Complete design systems generated in style-extract phase
@@ -92,123 +98,134 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 **Session Integration**:
 - `--session` flag determines session integration or standalone execution
 - Integrated: Design system automatically added to session artifacts
-- Standalone: Output in `.workflow/.design/{run_id}/`
+- Standalone: Output in `.workflow/{run_id}/`
 
-## 6-Phase Execution
+## 5-Phase Execution
 
-### Phase 0: Initialization and Target Parsing
+### Phase 0: Parameter Parsing & Input Detection
 
 ```bash
-# Generate run ID
-run_id = "run-$(date +%Y%m%d-%H%M%S)"
+# Step 0: Parse and normalize parameters
+images_input = null
+prompt_text = null
 
-# Determine base path and session mode
-IF --session:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/design-{run_id}"
-    session_mode = "integrated"
-ELSE:
-    session_id = null
-    base_path = ".workflow/.design/{run_id}"
-    session_mode = "standalone"
+# Handle legacy parameters with deprecation warning
+IF --images OR --prompt:
+    WARN: "⚠️  DEPRECATION: --images and --prompt are deprecated. Use --input instead."
+    WARN: "   Example: --input \"design-refs/*\" or --input \"modern dashboard\""
+    images_input = --images
+    prompt_text = --prompt
 
-# Create base directory
-Bash(mkdir -p "{base_path}")
+# Parse unified --input parameter
+IF --input:
+    # Split by | separator for multiple inputs
+    input_parts = split(--input, "|")
 
-# Step 0.1: Intelligent Path Detection
+    FOR part IN input_parts:
+        part = trim(part)
+
+        # Detection logic
+        IF contains(part, "*") OR glob_matches_files(part):
+            # Glob pattern detected → images
+            images_input = part
+        ELSE IF file_or_directory_exists(part):
+            # File/directory path → will be handled in code detection
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+        ELSE:
+            # Pure text → prompt
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+
+# Validation
+IF NOT images_input AND NOT prompt_text:
+    ERROR: "No input provided. Use --input with glob pattern, file path, or text description"
+    EXIT 1
+
+# Step 1: Detect design source from parsed inputs
 code_files_detected = false
 code_base_path = null
-design_source = "web"  # Default for imitate-auto
+has_visual_input = false
 
-IF --prompt:
+IF prompt_text:
     # Extract potential file paths from prompt
-    potential_paths = extract_paths_from_text(--prompt)
+    potential_paths = extract_paths_from_text(prompt_text)
     FOR path IN potential_paths:
         IF file_or_directory_exists(path):
             code_files_detected = true
             code_base_path = path
-            design_source = "hybrid"  # Web + Code
             BREAK
 
-STORE: design_source, code_base_path
+IF images_input:
+    # Check if images parameter points to existing files
+    IF glob_matches_files(images_input):
+        has_visual_input = true
 
-# Parse url-map
-url_map_string = {--url-map}
-VALIDATE: url_map_string is not empty, "--url-map parameter is required"
-
-# Parse target:url pairs
-url_map = {}  # {target_name: url}
-target_names = []
-
-FOR pair IN split(url_map_string, ","):
-    pair = pair.strip()
-
-    IF ":" NOT IN pair:
-        ERROR: "Invalid url-map format: '{pair}'"
-        ERROR: "Expected format: 'target:url'"
-        ERROR: "Example: 'home:https://example.com, pricing:https://example.com/pricing'"
-        EXIT 1
-
-    target, url = pair.split(":", 1)
-    target = target.strip().lower().replace(" ", "-")
-    url = url.strip()
-
-    url_map[target] = url
-    target_names.append(target)
-
-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
-
-# Parse capture mode
-capture_mode = --capture-mode OR "batch"
-depth = int(--depth OR 3)
-
-# Validate capture mode
-IF capture_mode NOT IN ["batch", "deep"]:
-    ERROR: "Invalid --capture-mode: {capture_mode}"
-    ERROR: "Valid options: batch, deep"
+# Step 2: Determine design source strategy
+design_source = "unknown"
+IF code_files_detected AND has_visual_input:
+    design_source = "hybrid"  # Both code and visual
+ELSE IF code_files_detected:
+    design_source = "code_only"  # Only code files
+ELSE IF has_visual_input OR --prompt:
+    design_source = "visual_only"  # Only visual/prompt
+ELSE:
+    ERROR: "No design source provided (code files, images, or prompt required)"
     EXIT 1
 
-# Validate depth (only for deep mode)
-IF capture_mode == "deep":
-    IF depth NOT IN [1, 2, 3, 4, 5]:
-        ERROR: "Invalid --depth: {depth}"
-        ERROR: "Valid range: 1-5"
-        EXIT 1
+STORE: design_source, code_base_path, has_visual_input
 
-    # Warn if multiple URLs in deep mode
-    IF len(target_names) > 1:
-        WARN: "⚠️ Deep mode only uses first URL: '{primary_target}'"
-        WARN: "   Other URLs will be ignored: {', '.join(target_names[1:])}"
-        WARN: "   For multi-URL, use --capture-mode batch"
+# Step 3: Initialize directories
+design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
+
+IF --session:
+    session_id = {provided_session}
+    relative_base_path = ".workflow/WFS-{session_id}/{design_id}"
+    session_mode = "integrated"
+ELSE:
+    session_id = null
+    relative_base_path = ".workflow/{design_id}"
+    session_mode = "standalone"
+
+# Create base directory and convert to absolute path
+Bash(mkdir -p "{relative_base_path}")
+base_path=$(cd "{relative_base_path}" && pwd)
 
 # Write metadata
 metadata = {
     "workflow": "imitate-auto",
-    "run_id": run_id,
+    "run_id": design_id,
     "session_id": session_id,
     "timestamp": current_timestamp(),
     "parameters": {
-        "url_map": url_map,
-        "capture_mode": capture_mode,
-        "depth": depth IF capture_mode == "deep" ELSE null,
-        "prompt": --prompt OR null
+        "design_source": design_source,
+        "code_base_path": code_base_path,
+        "images": images_input OR null,
+        "prompt": prompt_text OR null,
+        "input": --input OR null  # Store original --input for reference
     },
-    "targets": target_names,
     "status": "in_progress"
 }
 
 Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
 
+# Initialize default flags
+animation_complete = false
+needs_visual_supplement = false
+style_complete = false
+layout_complete = false
+
 # 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: "Initialize and detect design source", status: "completed", activeForm: "Initializing"},
   {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: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
+  {content: "Assemble UI prototypes", status: "pending", activeForm: "Assembling UI"},
   {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
 ]})
 ```
@@ -224,10 +241,14 @@ IF design_source == "hybrid":
     REPORT: "   → Source: {code_base_path}"
     REPORT: "   → Mode: Hybrid (Web + Code)"
 
-    command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" " +
-              "--base-path \"{code_base_path}\""
+    command = "/workflow:ui-design:import-from-code --design-id \"{design_id}\" " +
+              "--source \"{code_base_path}\""
 
     TRY:
+        # SlashCommand invocation ATTACHES import-from-code's tasks to current workflow
+        # Orchestrator will EXECUTE these attached tasks itself:
+        #   - Phase 0: Discover and categorize code files
+        #   - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
         SlashCommand(command)
     CATCH error:
         WARN: "Code import failed: {error}"
@@ -238,7 +259,8 @@ IF design_source == "hybrid":
         # Check file existence and assess completeness
         style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
         animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
-        layout_exists = exists("{base_path}/layout-extraction/layout-templates.json")
+        layout_count = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
+        layout_exists = (layout_count > 0)
 
         style_complete = false
         animation_complete = false
@@ -274,14 +296,16 @@ IF design_source == "hybrid":
 
         # Layout completeness check
         IF layout_exists:
-            layouts = Read("{base_path}/layout-extraction/layout-templates.json")
+            # Read first layout file to verify structure
+            first_layout = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | head -1)
+            layout_data = Read(first_layout)
             layout_complete = (
-                layouts.layout_templates?.length >= 3 &&
-                layouts.extraction_metadata?.layout_system?.type &&
-                layouts.extraction_metadata?.responsive?.breakpoints
+                layout_count >= 1 &&
+                layout_data.template?.dom_structure &&
+                layout_data.template?.css_layout_rules
             )
-            IF NOT layout_complete AND layouts.extraction_metadata?.completeness?.missing_items:
-                missing_categories.extend(layouts.extraction_metadata.completeness.missing_items)
+            IF NOT layout_complete:
+                missing_categories.push("complete layout structure")
         ELSE:
             missing_categories.push("layout templates")
 
@@ -306,148 +330,120 @@ IF design_source == "hybrid":
 
         STORE: style_complete, animation_complete, layout_complete
 
-TodoWrite(mark_completed: "Initialize and parse url-map",
-          mark_in_progress: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})")
-```
-
-### Phase 1: Screenshot Capture (Dual Mode)
-
-```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 1: Screenshot Capture"
-IF design_source == "hybrid":
-    REPORT: "   → Purpose: Verify and supplement code analysis"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-IF capture_mode == "batch":
-    # Mode A: Batch Multi-URL Capture
-    url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
-    capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
-
-    TRY:
-        SlashCommand(capture_command)
-    CATCH error:
-        ERROR: "Batch capture failed: {error}"
-        ERROR: "Cannot proceed without screenshots"
-        EXIT 1
-
-    # Verify batch capture results
-    screenshot_metadata_path = "{base_path}/screenshots/capture-metadata.json"
-
-    IF NOT exists(screenshot_metadata_path):
-        ERROR: "capture command did not generate metadata file"
-        ERROR: "Expected: {screenshot_metadata_path}"
-        EXIT 1
-
-    screenshot_metadata = Read(screenshot_metadata_path)
-    captured_count = screenshot_metadata.total_captured
-    total_requested = screenshot_metadata.total_requested
-    missing_count = total_requested - captured_count
-
-    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)}"
-
-    IF captured_count == 0:
-        ERROR: "No screenshots captured - cannot proceed"
-        EXIT 1
-
-ELSE:  # capture_mode == "deep"
-    # Mode B: Deep Interactive Layer Exploration
-    primary_url = url_map[primary_target]
-    explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
-
-    TRY:
-        SlashCommand(explore_command)
-    CATCH error:
-        ERROR: "Deep exploration failed: {error}"
-        ERROR: "Cannot proceed without screenshots"
-        EXIT 1
-
-    # Verify deep exploration results
-    layer_map_path = "{base_path}/screenshots/layer-map.json"
-
-    IF NOT exists(layer_map_path):
-        ERROR: "explore-layers did not generate layer-map.json"
-        ERROR: "Expected: {layer_map_path}"
-        EXIT 1
-
-    layer_map = Read(layer_map_path)
-    captured_count = layer_map.summary.total_captures
-    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})",
-          mark_in_progress: "Extract style (visual tokens)")
+TodoWrite(mark_completed: "Initialize and detect design source",
+          mark_in_progress: "Extract style (complete design systems)")
 ```
 
 ### Phase 2: Style Extraction
 
 ```bash
 # Determine if style extraction needed
-skip_style = (design_source == "hybrid" AND style_complete)
+skip_style = (design_source == "code_only" AND style_complete)
 
 IF skip_style:
     REPORT: "✅ Phase 2: Style (Using Code Import)"
 ELSE:
     REPORT: "🚀 Phase 2: Style Extraction"
-    IF capture_mode == "batch":
-        images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
-    ELSE:
-        images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"
 
-    IF --prompt:
-        extraction_prompt = f"Extract visual style tokens from '{primary_target}'. {--prompt}"
-    ELSE:
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:style-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        extraction_prompt = prompt_text
         IF design_source == "hybrid":
-            extraction_prompt = f"Extract visual style tokens from '{primary_target}' to supplement code-imported design tokens."
-        ELSE:
-            extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
+            extraction_prompt = f"{prompt_text} (supplement code-imported tokens)"
+        command_parts.append(f"--prompt \"{extraction_prompt}\"")
 
-    url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()])
-    extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate"
+    command_parts.extend(["--variants 1", "--refine", "--interactive"])
+
+    extract_command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES style-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(extract_command)
 
-TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation")
+    # After executing all attached tasks, collapse them into phase summary
+    TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation")
 ```
 
 ### Phase 2.3: Animation Extraction
 
 ```bash
-skip_animation = (design_source == "hybrid" AND animation_complete)
+skip_animation = (design_source == "code_only" AND animation_complete)
 
 IF skip_animation:
     REPORT: "✅ Phase 2.3: Animation (Using Code Import)"
 ELSE:
     REPORT: "🚀 Phase 2.3: Animation Extraction"
-    url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()])
-    animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:animation-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    command_parts.extend(["--refine", "--interactive"])
+
+    animation_extract_command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES animation-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(animation_extract_command)
 
+    # After executing all attached tasks, collapse them into phase summary
+    TodoWrite(mark_completed: "Extract animation", mark_in_progress: "Extract layout")
 ```
 
 ### Phase 2.5: Layout Extraction
 
 ```bash
-skip_layout = (design_source == "hybrid" AND layout_complete)
+skip_layout = (design_source == "code_only" AND layout_complete)
 
 IF skip_layout:
     REPORT: "✅ Phase 2.5: Layout (Using Code Import)"
 ELSE:
     REPORT: "🚀 Phase 2.5: Layout Extraction"
-    url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
-    layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:layout-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    # Default target if not specified
+    command_parts.append("--targets \"home\"")
+    command_parts.extend(["--variants 1", "--refine", "--interactive"])
+
+    layout_extract_command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES layout-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(layout_extract_command)
 
-TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI")
+    # After executing all attached tasks, collapse them into phase summary
+    TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI")
 ```
 
 ### Phase 3: UI Assembly
 
 ```bash
 REPORT: "🚀 Phase 3: UI Assembly"
-generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"
+generate_command = f"/workflow:ui-design:generate --design-id \"{design_id}\""
+
+# SlashCommand invocation ATTACHES generate's tasks to current workflow
+# Orchestrator will EXECUTE these attached tasks itself
 SlashCommand(generate_command)
 
+# After executing all attached tasks, collapse them into phase summary
 TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integrate design system" : "Completion")
 ```
 
@@ -457,6 +453,9 @@ TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integra
 IF session_id:
     REPORT: "🚀 Phase 4: Design System Integration"
     update_command = f"/workflow:ui-design:update --session {session_id}"
+
+    # SlashCommand invocation ATTACHES update's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(update_command)
 
 # Update metadata
@@ -486,7 +485,7 @@ TodoWrite({todos: [
 ]})
 ```
 
-### Phase 6: Completion Report
+### Phase 4: Completion Report
 
 **Completion Message**:
 ```
@@ -496,26 +495,24 @@ TodoWrite({todos: [
 
 ━━━ 📊 Workflow Summary ━━━
 
-Mode: {capture_mode == "batch" ? "Batch Multi-Page Replication" : f"Deep Interactive Exploration (depth {depth})"}
+Mode: Direct Input ({design_source})
 Session: {session_id or "standalone"}
 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 0 - Input Detection: ✅ {design_source} mode
+  {IF design_source == "code_only": "Code files imported" ELSE IF design_source == "hybrid": "Code + visual inputs" ELSE: "Visual inputs"}
 
 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 2.3 - Animation Extraction: ✅ CSS animations and transitions
+Phase 2.3 - Animation Extraction: ✅ Animation tokens
   Output: animation-extraction/ (animation-tokens.json + animation-guide.md)
-  Method: Auto-extracted from live URLs via Chrome DevTools
 
 Phase 2.5 - Layout Extraction: ✅ Structure templates
   Templates: {template_count} layout structures
 
-Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
-  Targets: {', '.join(target_names)}
+Phase 3 - UI Assembly: ✅ {generated_count} prototypes assembled
   Configuration: 1 style × 1 layout × {generated_count} pages
 
 Phase 4 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
@@ -523,20 +520,6 @@ Phase 4 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭
 ━━━ 📂 Output Structure ━━━
 
 {base_path}/
-├── screenshots/                    # {captured_count} screenshots
-{IF capture_mode == "batch":
-│   ├── {target1}.png
-│   ├── {target2}.png
-│   └── capture-metadata.json
-ELSE:
-│   ├── depth-1/
-│   │   └── full-page.png
-│   ├── depth-2/
-│   │   └── {elements}.png
-│   ├── depth-{depth}/
-│   │   └── {layers}.png
-│   └── layer-map.json
-}
 ├── style-extraction/               # Production-ready design systems
 │   └── style-1/
 │       ├── design-tokens.json
@@ -545,19 +528,18 @@ ELSE:
 │   ├── animation-tokens.json
 │   └── animation-guide.md
 ├── layout-extraction/              # Structure templates
-│   └── layout-templates.json
+│   └── layout-home-1.json          # Layout templates
 └── prototypes/                     # {generated_count} HTML/CSS files
-    ├── {target1}-style-1-layout-1.html + .css
-    ├── {target2}-style-1-layout-1.html + .css
+    ├── home-style-1-layout-1.html + .css
     ├── compare.html                # Interactive preview
     └── index.html                  # Quick navigation
 
 ━━━ ⚡ Performance ━━━
 
 Total workflow time: ~{estimate_total_time()} minutes
-  Screenshot capture: ~{capture_time}
   Style extraction: ~{extract_time}
-  Token processing: ~{token_processing_time}
+  Animation extraction: ~{animation_time}
+  Layout extraction: ~{layout_time}
   UI generation: ~{generate_time}
 
 ━━━ 🌐 Next Steps ━━━
@@ -586,103 +568,81 @@ ELSE:
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution
+// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution (6 orchestrator-level tasks)
 TodoWrite({todos: [
-  {content: "Initialize and parse url-map", status: "in_progress", activeForm: "Initializing"},
-  {content: "Batch screenshot capture", status: "pending", activeForm: "Capturing screenshots"},
+  {content: "Initialize and detect design source", status: "in_progress", activeForm: "Initializing"},
   {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: "Assemble UI for all targets", status: "pending", activeForm: "Assembling UI"},
+  {content: "Assemble UI prototypes", status: "pending", activeForm: "Assembling UI"},
   {content: "Integrate design system", status: "pending", activeForm: "Integrating"}
 ]})
 
-// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
-// 1. SlashCommand blocks and returns when phase is complete
-// 2. Update current phase: status → "completed"
-// 3. Update next phase: status → "in_progress"
-// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
-// This ensures continuous workflow tracking and prevents premature stopping
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// Phase 2-4 SlashCommand Invocation Pattern:
+// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
+// 2. TodoWrite expands to include attached tasks
+// 3. Orchestrator EXECUTES attached tasks sequentially
+// 4. After all attached tasks complete, COLLAPSE them into phase summary
+// 5. Update next phase to in_progress
+// 6. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+//
+// Benefits:
+// ✓ Real-time visibility into sub-command task progress
+// ✓ Clean orchestrator-level summary after each phase
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Dynamic attachment/collapse maintains clarity
 ```
 
 ## Error Handling
 
 ### Pre-execution Checks
-- **url-map format validation**: Clear error message with format example
-- **Empty url-map**: Error and exit
-- **Invalid target names**: Regex validation with suggestions
+- **Input validation**: Must provide at least one of --images or --prompt
+- **Design source detection**: Error if no valid inputs found
+- **Code import failure**: Fallback to visual-only mode in hybrid, error in code-only mode
 
 ### Phase-Specific Errors
-- **Screenshot capture failure (Phase 1)**:
-  - If total_captured == 0: Terminate workflow
-  - If partial failure: Warn but continue with available screenshots
+- **Code import failure (Phase 0.5)**:
+  - code_only mode: Terminate with clear error
+  - hybrid mode: Warn and fallback to visual-only mode
 
 - **Style extraction failure (Phase 2)**:
   - If extract fails: Terminate with clear error
-  - If style-cards.json missing: Terminate with debugging info
+  - If design-tokens.json missing: Terminate with debugging info
 
-- **Token processing failure (Phase 3)**:
-  - Consolidate mode: Terminate if consolidate fails
-  - Fast mode: Validate proposed_tokens exist before copying
+- **Animation extraction failure (Phase 2.3)**:
+  - Non-critical: Warn but continue
+  - Can proceed without animation tokens
 
-- **UI generation failure (Phase 4)**:
+- **Layout extraction failure (Phase 2.5)**:
+  - If extract fails: Terminate with error
+  - Need layout templates for assembly
+
+- **UI generation failure (Phase 3)**:
   - If generate fails: Terminate with error
-  - If generated_count < target_count: Warn but proceed
+  - If generated_count < expected: Warn but proceed
 
-- **Integration failure (Phase 5)**:
+- **Integration failure (Phase 4)**:
   - Non-blocking: Warn but don't terminate
   - Prototypes already available
 
 ### Recovery Strategies
-- **Partial screenshot failure**: Continue with available screenshots, list missing in warning
-- **Generate failure**: Report specific target failures, user can re-generate individually
+- **Code import failure**: Automatic fallback to visual-only in hybrid mode
+- **Generate failure**: Report specific failures, user can re-generate individually
 - **Integration failure**: Prototypes still usable, can integrate manually
 
-
-## Key Features
-
-- **🚀 Dual Capture**: Batch mode for speed, deep mode for detail
-- **⚡ 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
-- **🎯 Flexible**: Standalone or session-integrated modes
-
-## Examples
-
-### 1. Basic Multi-Page Replication
-```bash
-/workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
-# Result: 2 prototypes with fast-track tokens
-```
-
-### 2. Session Integration
-```bash
-/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
-```bash
-/workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
-# Result: Interactive layer capture + prototype
-```
-
-### 4. Guided Style Extraction
-```bash
-/workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
-# Result: 2 prototypes with minimalist style focus
-```
-
 ## Integration Points
 
-- **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)
+- **Input**: `--images` (glob pattern) and/or `--prompt` (text/file paths) + optional `--session`
+- **Output**: Complete design system in `{base_path}/` (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)
+  1. `/workflow:ui-design:import-from-code` (Phase 0.5, conditional - if code files detected)
   2. `/workflow:ui-design:style-extract` (Phase 2 - complete design systems)
-  3. `/workflow:ui-design:animation-extract` (Phase 2.3 - CSS animations and transitions)
+  3. `/workflow:ui-design:animation-extract` (Phase 2.3 - animation tokens)
   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)
@@ -692,30 +652,31 @@ TodoWrite({todos: [
 ```
 ✅ UI Design Imitate-Auto Workflow Complete!
 
-Mode: {capture_mode} | Session: {session_id or "standalone"}
+Mode: Direct Input ({design_source}) | Session: {session_id or "standalone"}
 Run ID: {run_id}
 
-Phase 1 - Screenshot Capture: ✅ {captured_count} screenshots
+Phase 0 - Input Detection: ✅ {design_source} mode
 Phase 2 - Style Extraction: ✅ Production-ready design systems
+Phase 2.3 - Animation Extraction: ✅ Animation tokens
 Phase 2.5 - Layout Extraction: ✅ Structure templates
-Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
+Phase 3 - UI Assembly: ✅ {generated_count} prototypes 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
 ✅ Production-Ready: WCAG AA compliant, OKLCH colors
+✅ Multi-Source: Code import + visual extraction
 
 📂 {base_path}/
-  ├── screenshots/                  # {captured_count} screenshots
   ├── style-extraction/style-1/     # Production-ready design system
+  ├── animation-extraction/         # Animation tokens
   ├── layout-extraction/            # Structure templates
   └── prototypes/                   # {generated_count} HTML/CSS files
 
 🌐 Preview: {base_path}/prototypes/compare.html
   - Interactive preview
-  - Side-by-side comparison
-  - {generated_count} replicated pages
+  - Design token driven
+  - {generated_count} assembled prototypes
 
 Next: [/workflow:execute] OR [Open compare.html → /workflow:plan]
 ```

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

@@ -1,23 +1,25 @@
 ---
 name: layout-extract
-description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis
-argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
+description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode
+argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
 ---
 
 # 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`).
+Extract structural layout information from reference images, URLs, or text prompts using AI analysis. Supports two modes:
+1. **Exploration Mode** (default): Generate multiple contrasting layout variants
+2. **Refinement Mode** (`--refine`): Refine a single existing layout through detailed adjustments
+
+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
-  - `explore`: Multiple structurally distinct layout variations
-- **Single Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
+- **Dual Mode**: Exploration (multiple contrasting variants) or Refinement (single layout fine-tuning)
+- **Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
 - **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
 - **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
 
@@ -45,15 +47,19 @@ ELSE:
     has_urls = false
     url_list = []
 
-# Determine extraction mode
-extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+# Detect refinement mode
+refine_mode = --refine OR false
 
-# Set variants count based on mode
-IF extraction_mode == "imitate":
-    variants_count = 1  # Force single variant (ignore --variants)
-ELSE IF extraction_mode == "explore":
-    variants_count = --variants OR 3  # Default to 3
+# Set variants count
+# Refinement mode: Force variants_count = 1 (ignore user-provided --variants)
+# Exploration mode: Use --variants or default to 3 (range: 1-5)
+IF refine_mode:
+    variants_count = 1
+    REPORT: "🔧 Refinement mode enabled: Will generate 1 refined layout per target"
+ELSE:
+    variants_count = --variants OR 3
     VALIDATE: 1 <= variants_count <= 5
+    REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting layout concepts per target"
 
 # Resolve targets
 # Priority: --targets → url_list targets → prompt analysis → default ["page"]
@@ -62,6 +68,9 @@ IF --targets:
 ELSE IF has_urls:
     targets = [url_info.target for url_info in url_list]
 ELSE IF --prompt:
+    # Extract targets from prompt using pattern matching
+    # Looks for keywords: "page names", target descriptors (login, dashboard, etc.)
+    # Returns lowercase, hyphenated strings (e.g., ["login", "dashboard"])
     targets = extract_from_prompt(--prompt)
 ELSE:
     targets = ["page"]
@@ -69,9 +78,27 @@ ELSE:
 # Resolve device type
 device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
 
-# Determine base path
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
-# OR use --base-path / --session parameters
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 ```
 
 ### Step 2: Load Inputs & Create Directories
@@ -188,58 +215,54 @@ IF result.exploration?.triggered:
 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")
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 IF exists: SKIP to completion
 ```
 
 ---
 
-**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+**Phase 0 Output**: `input_mode`, `base_path`, `variants_count`, `targets[]`, `device_type`, loaded inputs
 
-## Phase 1: Layout Concept Generation (Explore Mode Only)
+## Phase 1: Layout Concept or Refinement Options Generation
 
-### Step 1: Check Extraction Mode
+### Step 0.5: Load Existing Layout (Refinement Mode)
 ```bash
-# extraction_mode == "imitate" → skip this phase
-# extraction_mode == "explore" → execute this phase
+IF refine_mode:
+    # Load existing layout for refinement
+    existing_layouts = {}
+    FOR target IN targets:
+        layout_files = bash(find {base_path}/layout-extraction -name "layout-{target}-*.json" -print)
+        IF layout_files:
+            # Use first/latest layout file for this target
+            existing_layouts[target] = Read(first_layout_file)
 ```
 
-**If imitate mode**: Skip to Phase 2
-
-### Step 2: Gather Layout Inspiration (Explore Mode)
-```bash
-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}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, inspiration_content)
-```
-
-### Step 3: Generate Layout Concept Options (Agent Task 1)
+### Step 1: Generate Options (Agent Task 1 - Mode-Specific)
 **Executor**: `Task(ui-design-agent)`
 
-Launch agent to generate `variants_count` layout concept options for each target:
+**Exploration Mode** (default): Generate contrasting layout concepts
+**Refinement Mode** (`--refine`): Generate refinement options for existing layouts
 
 ```javascript
-Task(ui-design-agent): `
-  [LAYOUT_CONCEPT_GENERATION_TASK]
-  Generate {variants_count} structurally distinct layout concepts for each target
+// Conditional agent task based on refine_mode
+IF NOT refine_mode:
+    // EXPLORATION MODE
+    Task(ui-design-agent): `
+      [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}
+      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" : ""}
+      ## Input Analysis
+      - Targets: {targets.join(", ")}
+      - Device type: {device_type}
+      - 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
+      ## 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
@@ -267,10 +290,74 @@ Task(ui-design-agent): `
   Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)
 
   CRITICAL: Use Write() tool immediately after generating complete JSON
-`
+    `
+ELSE:
+    // REFINEMENT MODE
+    Task(ui-design-agent): `
+      [LAYOUT_REFINEMENT_OPTIONS_TASK]
+      Generate refinement options for existing layout(s)
+
+      SESSION: {session_id} | MODE: refine | BASE_PATH: {base_path}
+      TARGETS: {targets} | DEVICE_TYPE: {device_type}
+
+      ## Existing Layouts
+      ${FOR target IN targets: "- {target}: {existing_layouts[target]}"}
+
+      ## Input Guidance
+      - User prompt: {prompt_guidance if available}
+      - Visual references: {loaded_images if available}
+
+      ## Refinement Categories
+      Generate 8-12 refinement options per target across these categories:
+
+      1. **Density Adjustments** (2-3 options per target):
+         - More compact: Tighter spacing, reduced whitespace
+         - More spacious: Increased margins, breathing room
+         - Balanced: Moderate adjustments
+
+      2. **Responsiveness Tuning** (2-3 options per target):
+         - Breakpoint behavior: Earlier/later column stacking
+         - Mobile layout: Different navigation/content priority
+         - Tablet optimization: Hybrid desktop/mobile approach
+
+      3. **Grid/Flex Specifics** (2-3 options per target):
+         - Column counts: 2-col ↔ 3-col ↔ 4-col
+         - Gap sizes: Tighter ↔ wider gutters
+         - Alignment: Different flex/grid justification
+
+      4. **Component Arrangement** (1-2 options per target):
+         - Navigation placement: Top ↔ side ↔ bottom
+         - Sidebar position: Left ↔ right ↔ none
+         - Content hierarchy: Different section ordering
+
+      ## Output Format
+      Each option (per target):
+      - target: Which target this refinement applies to
+      - category: "density|responsiveness|grid|arrangement"
+      - option_id: unique identifier
+      - label: Short descriptive name (e.g., "More Compact Spacing")
+      - description: What changes (2-3 sentences)
+      - preview_changes: Key structural adjustments
+      - impact_scope: Which layout regions affected
+
+      ## Output
+      Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json
+
+      Use refinement schema:
+      {
+        "mode": "refinement",
+        "device_type": "{device_type}",
+        "refinement_options": {
+          "{target1}": [array of refinement options],
+          "{target2}": [array of refinement options]
+        }
+      }
+
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
 ```
 
-### Step 4: Verify Options File Created
+### Step 2: Verify Options File Created
 ```bash
 bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")
 
@@ -282,17 +369,40 @@ bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep
 
 ---
 
-## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+## Phase 1.5: User Confirmation (Optional - Triggered by --interactive)
 
-**Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates
+**Purpose**:
+- **Exploration Mode**: Allow user to select preferred layout concept(s) per target
+- **Refinement Mode**: Allow user to select refinement options to apply per target
 
-### Step 1: Load and Present Options
+**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present
+
+### Step 1: Check Interactive Flag
+```bash
+# Skip this entire phase if --interactive flag is not present
+IF NOT --interactive:
+    SKIP to Phase 2
+    IF refine_mode:
+        REPORT: "ℹ️ Non-interactive refinement mode: Will apply all suggested refinements"
+    ELSE:
+        REPORT: "ℹ️ Non-interactive mode: Will generate all {variants_count} variants per target"
+
+# Interactive mode enabled
+REPORT: "🎯 Interactive mode: User selection required for {targets.length} target(s)"
+```
+
+### Step 2: Load and Present Options (Mode-Specific)
 ```bash
 # Read options file
 options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
 
-# Parse layout concepts
-layout_concepts = options.layout_concepts
+# Branch based on mode
+IF NOT refine_mode:
+    # EXPLORATION MODE
+    layout_concepts = options.layout_concepts
+ELSE:
+    # REFINEMENT MODE
+    refinement_options = options.refinement_options
 ```
 
 ### Step 2: Present Options to User (Per Target)
@@ -329,15 +439,34 @@ Please select your preferred concept for this target.
 }
 ```
 
-### Step 3: Capture User Selection (Per Target)
+### Step 3: Capture User Selection and Update Options File (Per Target)
+
+**Interaction Strategy**: If total concepts > 4 OR any target has > 3 concepts, use batch text format:
+
+```
+【目标[N] - [target]】选择布局方案
+[key]) Concept [index]: [concept_name]
+   [design_philosophy]
+[key]) Concept [index]: [concept_name]
+   [design_philosophy]
+...
+请回答 (格式: 1a 2b 或 1a,b 2c 多选)：
+
+User input:
+  "[N][key] [N][key] ..." → Single selection per target
+  "[N][key1,key2] [N][key3] ..." → Multi-selection per target
+```
+
+Otherwise, use `AskUserQuestion` below.
+
 ```javascript
-// Use AskUserQuestion tool for each target
+// Use AskUserQuestion tool for each target (multi-select enabled)
 FOR each target:
   AskUserQuestion({
     questions: [{
-      question: "Which layout concept do you prefer for '{target}'?",
+      question: "Which layout concept(s) do you prefer for '{target}'?",
       header: "Layout for " + target,
-      multiSelect: false,
+      multiSelect: true,  // Multi-selection enabled (default behavior)
       options: [
         {FOR each concept in layout_concepts[target]:
           label: "Concept {concept.index}: {concept.concept_name}",
@@ -347,193 +476,218 @@ FOR each target:
     }]
   })
 
-  // Parse user response
-  selected_option_text = user_answer
+  // Parse user response (array of selections)
+  selected_options = user_answer
 
   // Check for user cancellation
-  IF selected_option_text == null OR selected_option_text == "":
+  IF selected_options == null OR selected_options.length == 0:
       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
+  // Extract concept indices from array
+  selected_indices = []
+  FOR each selected_option_text IN selected_options:
+      match = selected_option_text.match(/Concept (\d+):/)
+      IF match:
+          selected_indices.push(parseInt(match[1]))
+      ELSE:
+          ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
+          EXIT workflow
 
-  // Store selection for this target
+  // Store selections for this target (array of indices)
   selections[target] = {
-    selected_index: selected_index,
-    concept_name: layout_concepts[target][selected_index-1].concept_name
+    selected_indices: selected_indices,  // Array of selected indices
+    concept_names: selected_indices.map(i => layout_concepts[target][i-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}}
+  REPORT: "✅ Selected {selected_indices.length} layout(s) for {target}"
+
+// Calculate total selections across all targets
+total_selections = sum([len(selections[t].selected_indices) for t in targets])
+
+// Update analysis-options.json with user selection (embedded in same file)
+options_file = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": "{current_timestamp}",
+  "selection_type": "per_target_multi",
+  "session_id": "{session_id}",
+  "total_selections": total_selections,
+  "selected_variants": selections  // {target: {selected_indices: [...], concept_names: [...]}}
 }
 
-# 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")
+// Write updated file back
+Write({base_path}/.intermediates/layout-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
 ```
 
-### Step 5: Confirmation Message
+### Step 4: Confirmation Message
 ```
-✅ Selections recorded!
+✅ Selections recorded! Total: {total_selections} layout(s)
 
 {FOR each target, selection in selections:
-  • {target}: Concept {selection.selected_index} - {selection.concept_name}
+  • {target}: {selection.selected_indices.length} layout(s) selected
+    {FOR each index IN selection.selected_indices:
+      - Concept {index}: {layout_concepts[target][index-1].concept_name}
+    }
 }
 
-Proceeding to generate detailed layout templates based on your selections...
+Proceeding to generate {total_selections} detailed layout template(s)...
 ```
 
-**Output**: `user-selection.json` with user's choices for all targets
+**Output**: `analysis-options.json` updated with embedded `user_selection` field
 
 ## Phase 2: Layout Template Generation (Agent Task 2)
 
-**Executor**: `Task(ui-design-agent)` for selected concept(s)
+**Executor**: `Task(ui-design-agent)` × `Total_Selected_Templates` in **parallel**
 
-### Step 1: Load User Selection (Explore Mode)
+### Step 1: Load User Selections or Default to All
 ```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
+# Read analysis-options.json which may contain user_selection
+options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+layout_concepts = options.layout_concepts
 
-    # 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
+# Check if user_selection field exists (interactive mode)
+IF options.user_selection AND options.user_selection.selected_variants:
+    # Interactive mode: Use user-selected variants
+    selections_per_target = options.user_selection.selected_variants
+    total_selections = options.user_selection.total_selections
 ELSE:
-    # Imitate mode - no selection needed
-    selected_concepts = null
+    # Non-interactive mode: Generate ALL variants for ALL targets (default behavior)
+    selections_per_target = {}
+    total_selections = 0
+
+    FOR each target in targets:
+        selections_per_target[target] = {
+            "selected_indices": [1, 2, ..., variants_count],  # All indices
+            "concept_names": []  # Will be filled from options
+        }
+        total_selections += variants_count
+
+# Build task list for all selected concepts across all targets
+task_list = []
+FOR each target in targets:
+    selected_indices = selections_per_target[target].selected_indices  # Array
+    concept_names = selections_per_target[target].concept_names        # Array
+
+    FOR i in range(len(selected_indices)):
+        idx = selected_indices[i]
+        concept = layout_concepts[target][idx - 1]  # 0-indexed array
+        variant_id = i + 1  # 1-based variant numbering
+
+        task_list.push({
+            target: target,
+            variant_id: variant_id,
+            concept: concept,
+            output_file: "{base_path}/layout-extraction/layout-{target}-{variant_id}.json"
+        })
+
+total_tasks = task_list.length
+REPORT: "Generating {total_tasks} layout templates across {targets.length} targets"
 ```
 
-### Step 2: Launch Agent Task
-Generate layout templates for selected concepts:
+### Step 2: Launch Parallel Agent Tasks
+Generate layout templates for ALL selected concepts in parallel:
 ```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.).
+FOR each task in task_list:
+    Task(ui-design-agent): `
+      [LAYOUT_TEMPLATE_GENERATION_TASK #{task.variant_id} for {task.target}]
+      Generate detailed layout template based on user-selected concept.
+      Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
 
-  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
-  DEVICE_TYPE: {device_type}
+      SESSION: {session_id} | BASE_PATH: {base_path}
+      TARGET: {task.target} | VARIANT: {task.variant_id}
+      DEVICE_TYPE: {device_type}
 
-  ${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(", ")}
-  `}
+      USER SELECTION:
+      - Selected Concept: {task.concept.concept_name}
+      - Philosophy: {task.concept.design_philosophy}
+      - Pattern: {task.concept.layout_pattern}
+      - Key Components: {task.concept.key_components.join(", ")}
+      - Structural Features: {task.concept.structural_features.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" : ""}
+      ## Input Analysis
+      - Target: {task.target}
+      - Device type: {device_type}
+      - Visual references: {loaded_images if available}
+      ${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-{task.target}.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
-  ` : ""}
+      ## Generation Rules
+      - Develop the 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
+      ${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:"}
+      ## Template Generation
 
-    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}
+      1. **DOM Structure**:
+         - Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+         - ARIA roles and accessibility attributes
+         - 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" : ""}
+      2. **Component Hierarchy**:
+         - Array of main layout regions
+         - 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
+      3. **CSS Layout Rules**:
+         - 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
-  Write complete layout-templates.json with layout_templates array.
-  Each template must include:
-  - target (string)
-  - 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 ${extraction_mode == "explore" ? "- from selected concept" : ""})
-  - dom_structure (JSON object)
-  - component_hierarchy (array of strings)
-  - css_layout_rules (string)
+      ## Output Files
 
-  ## 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" : ""}
-`
+      Generate 2 files:
+
+      1. **layout-templates.json** - {task.output_file}
+         Write single-template JSON object with:
+         - target: "{task.target}"
+         - variant_id: "layout-{task.variant_id}"
+         - source_image_path (string): Reference image path
+         - device_type: "{device_type}"
+         - design_philosophy (string from selected concept)
+         - dom_structure (JSON object)
+         - component_hierarchy (array of strings)
+         - css_layout_rules (string)
+
+      ## Critical Requirements
+      - ✅ Use Write() tool to generate JSON file
+      - ✅ Single template for {task.target} variant {task.variant_id}
+      - ✅ Structure only, no visual styling
+      - ✅ Token-based CSS (var())
+      - ✅ Can use Exa MCP to research modern layout patterns and obtain code examples (Explore/Text mode)
+      - ✅ Maintain consistency with selected concept
+    `
 ```
 
-**Output**: Agent generates `layout-templates.json` with one template per target
+**Output**: Agent generates multiple layout template files (one per selected concept)
 
-### Step 2: Write Output File
+### Step 3: Verify Output Files
 ```bash
-# Take JSON output from agent
-bash(echo '{agent_json_output}' > {base_path}/layout-extraction/layout-templates.json)
+# Count generated files
+expected_count = total_tasks
+actual_count = bash(ls {base_path}/layout-extraction/layout-*.json | wc -l)
 
-# Verify output
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
-bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_templates" && echo "valid")
+# Verify all files were created
+IF actual_count == expected_count:
+    REPORT: "✓ All {expected_count} layout template files generated"
+ELSE:
+    ERROR: "Expected {expected_count} files, found {actual_count}"
+
+# Verify file structure (sample check)
+bash(cat {base_path}/layout-extraction/layout-{first_target}-1.json | grep -q "variant_id" && echo "valid structure")
 ```
 
-**Output**: `layout-templates.json` created and verified
+**Output**: All layout template files created and verified (one file per selected concept)
 
 ## Completion
 
@@ -541,9 +695,10 @@ bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_t
 ```javascript
 TodoWrite({todos: [
   {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
-  {content: "Layout research (explore mode)", status: "completed", activeForm: "Researching layout patterns"},
-  {content: "Layout analysis and synthesis (agent)", status: "completed", activeForm: "Generating layout templates"},
-  {content: "Write layout-templates.json", status: "completed", activeForm: "Saving templates"}
+  {content: "Layout concept analysis (agent)", status: "completed", activeForm: "Analyzing layout patterns"},
+  {content: "User selection confirmation", status: "completed", activeForm: "Confirming selections"},
+  {content: "Generate layout templates (parallel)", status: "completed", activeForm: "Generating templates"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
 ]});
 ```
 
@@ -553,11 +708,9 @@ TodoWrite({todos: [
 
 Configuration:
 - Session: {session_id}
-- Extraction Mode: {extraction_mode} (imitate/explore)
 - Device Type: {device_type}
-- Targets: {targets}
-- Variants per Target: {variants_count}
-- Total Templates: {targets.length × variants_count}
+- Targets: {targets.join(", ")}
+- Total Templates: {total_tasks} ({targets.length} targets with multi-selection)
 {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
@@ -566,22 +719,27 @@ Configuration:
 - ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
 }
 
-{IF extraction_mode == "explore":
-Layout Research:
-- {targets.length} inspiration files generated
-- Pattern search focused on {device_type} layouts
+User Selections:
+{FOR each target in targets:
+- {target}: {selections_per_target[target].concept_names.join(", ")} ({selections_per_target[target].selected_indices.length} variants)
 }
 
 Generated Templates:
-{FOR each template: - Target: {template.target} | Variant: {template.variant_id} | Philosophy: {template.design_philosophy}}
-
-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)
+{base_path}/layout-extraction/
+{FOR each target in targets:
+  {FOR each variant_id in range(1, selections_per_target[target].selected_indices.length + 1):
+    └── layout-{target}-{variant_id}.json
+  }
 }
 
-Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
+Intermediate Files:
+- {base_path}/.intermediates/layout-analysis/
+  ├── analysis-options.json (concept proposals + user selections embedded)
+  {IF dom_structure_available:
+  ├── dom-structure-*.json ({len(url_list)} DOM extracts)
+  }
+
+Next: /workflow:ui-design:generate will combine these structural templates with design systems to produce final prototypes.
 ```
 
 ## Simple Bash Commands
@@ -589,23 +747,22 @@ Next: /workflow:ui-design:generate will combine these structural templates with
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Create output directories
 bash(mkdir -p {base_path}/layout-extraction)
-bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)  # explore mode only
 ```
 
 ### Validation Commands
 ```bash
 # Check if already extracted
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 
-# Validate JSON structure
-bash(cat layout-templates.json | grep -q "layout_templates" && echo "valid")
+# Count generated files
+bash(ls {base_path}/layout-extraction/layout-*.json | wc -l)
 
-# Count templates
-bash(cat layout-templates.json | grep -c "\"target\":")
+# Validate JSON structure (sample check)
+bash(cat {base_path}/layout-extraction/layout-{first_target}-1.json | grep -q "variant_id" && echo "valid")
 ```
 
 ### File Operations
@@ -614,9 +771,6 @@ bash(cat layout-templates.json | grep -c "\"target\":")
 bash(ls {images_pattern})
 Read({image_path})
 
-# Write inspiration files (explore mode)
-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)
 ```
@@ -627,28 +781,27 @@ bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
 {base_path}/
 ├── .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
+│       ├── analysis-options.json      # Generated layout concepts + user selections (embedded)
+│       └── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
 └── layout-extraction/                 # Final layout templates
-    ├── layout-templates.json          # Structural layout templates
-    └── layout-space-analysis.json     # Layout directions (explore mode only)
+    └── layout-{target}-{variant}.json # Structural layout template JSON
 ```
 
-## layout-templates.json Format
+## Layout Template File Format
+
+Each `layout-{target}-{variant}.json` file contains a single template:
 
 ```json
 {
   "extraction_metadata": {
     "session_id": "...",
     "input_mode": "image|url|prompt|hybrid",
-    "extraction_mode": "imitate|explore",
     "device_type": "desktop|mobile|tablet|responsive",
     "timestamp": "...",
-    "variants_count": 3,
-    "targets": ["home", "dashboard"]
+    "target": "home",
+    "variant_id": "layout-1"
   },
-  "layout_templates": [
+  "template":
     {
       "target": "home",
       "variant_id": "layout-1",
@@ -703,8 +856,8 @@ ERROR: Invalid target name
 ERROR: Agent task failed
 → Check agent output, retry with simplified prompt
 
-ERROR: MCP search failed (explore mode)
-→ Check network, retry
+ERROR: MCP search failed
+→ Check network connection, retry command
 ```
 
 ### Recovery Strategies
@@ -718,29 +871,12 @@ ERROR: MCP search failed (explore mode)
 - **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
+- **Multi-Selection Workflow** - Generate N concepts → User selects multiple → Parallel template generation
+- **Structural Exploration** - Enables A/B testing of different layouts through multi-selection
 - **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
+- **Foundation for Assembly** - Provides structural blueprint for prototype generation
 - **Agent-Powered** - Deep structural analysis with AI
 
-## Integration
 
-**Workflow Position**: Between style extraction and prototype generation
-
-**New Workflow**:
-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`
-     2. Create layout CSS from `css_layout_rules`
-     3. Link design tokens CSS
-     4. Inject placeholder content
-   - **Output**: Complete token-driven HTML/CSS prototypes
-
-**Input**: Reference images, URLs, or text prompts
-**Output**: `layout-templates.json` for `/workflow:ui-design:generate`
-**Next**: `/workflow:ui-design:generate --session {session_id}`

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

@@ -0,0 +1,174 @@
+---
+name: list
+description: List all available design runs with metadata (session, created time, prototype count)
+argument-hint: [--session <id>]
+allowed-tools: Bash(*), Read(*)
+---
+
+# List Design Runs (/workflow:ui-design:list)
+
+## Overview
+List all available UI design runs across sessions or within a specific session. Displays design IDs with metadata for easy reference.
+
+**Output**: Formatted list with design-id, session, created time, and prototype count
+
+## Implementation
+
+### Step 1: Determine Search Scope
+```bash
+# Priority: --session > all sessions
+search_path=$(if [ -n "$SESSION_ID" ]; then
+  echo ".workflow/WFS-$SESSION_ID"
+else
+  echo ".workflow"
+fi)
+```
+
+### Step 2: Find and Display Design Runs
+```bash
+echo "Available design runs:"
+echo ""
+
+# Find all design-run directories
+found_count=0
+while IFS= read -r line; do
+  timestamp=$(echo "$line" | cut -d' ' -f1)
+  path=$(echo "$line" | cut -d' ' -f2-)
+
+  # Extract design_id from path
+  design_id=$(basename "$path")
+
+  # Extract session from path
+  session_id=$(echo "$path" | grep -oP 'WFS-\K[^/]+' || echo "standalone")
+
+  # Format created date
+  created_at=$(date -d "@${timestamp%.*}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "unknown")
+
+  # Count prototypes
+  prototype_count=$(find "$path/prototypes" -name "*.html" 2>/dev/null | wc -l)
+
+  # Display formatted output
+  echo "  - $design_id"
+  echo "      Session: $session_id"
+  echo "      Created: $created_at"
+  echo "      Prototypes: $prototype_count"
+  echo ""
+
+  found_count=$((found_count + 1))
+done < <(find "$search_path" -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr)
+
+# Summary
+if [ $found_count -eq 0 ]; then
+  echo "  No design runs found."
+  echo ""
+  if [ -n "$SESSION_ID" ]; then
+    echo "💡 HINT: Try running '/workflow:ui-design:explore-auto' to create a design run"
+  else
+    echo "💡 HINT: Try running '/workflow:ui-design:explore-auto --session <id>' to create a design run"
+  fi
+else
+  echo "Total: $found_count design run(s)"
+  echo ""
+  echo "💡 USE: /workflow:ui-design:generate --design-id \"<id>\""
+  echo "      OR: /workflow:ui-design:generate --session \"<session>\""
+fi
+```
+
+### Step 3: Execute List Command
+```bash
+Bash(
+  description: "List all UI design runs with metadata",
+  command: "
+    search_path=\"${search_path}\"
+    SESSION_ID=\"${SESSION_ID:-}\"
+
+    echo 'Available design runs:'
+    echo ''
+
+    found_count=0
+    while IFS= read -r line; do
+      timestamp=\$(echo \"\$line\" | cut -d' ' -f1)
+      path=\$(echo \"\$line\" | cut -d' ' -f2-)
+
+      design_id=\$(basename \"\$path\")
+      session_id=\$(echo \"\$path\" | grep -oP 'WFS-\\K[^/]+' || echo 'standalone')
+      created_at=\$(date -d \"@\${timestamp%.*}\" '+%Y-%m-%d %H:%M' 2>/dev/null || echo 'unknown')
+      prototype_count=\$(find \"\$path/prototypes\" -name '*.html' 2>/dev/null | wc -l)
+
+      echo \"  - \$design_id\"
+      echo \"      Session: \$session_id\"
+      echo \"      Created: \$created_at\"
+      echo \"      Prototypes: \$prototype_count\"
+      echo ''
+
+      found_count=\$((found_count + 1))
+    done < <(find \"\$search_path\" -name 'design-run-*' -type d -printf '%T@ %p\\n' 2>/dev/null | sort -nr)
+
+    if [ \$found_count -eq 0 ]; then
+      echo '  No design runs found.'
+      echo ''
+      if [ -n \"\$SESSION_ID\" ]; then
+        echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto\\' to create a design run'
+      else
+        echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto --session <id>\\' to create a design run'
+      fi
+    else
+      echo \"Total: \$found_count design run(s)\"
+      echo ''
+      echo '💡 USE: /workflow:ui-design:generate --design-id \"<id>\"'
+      echo '      OR: /workflow:ui-design:generate --session \"<session>\"'
+    fi
+  "
+)
+```
+
+## Example Output
+
+### With Session Filter
+```
+$ /workflow:ui-design:list --session ui-redesign
+
+Available design runs:
+
+  - design-run-20250109-143052
+      Session: ui-redesign
+      Created: 2025-01-09 14:30
+      Prototypes: 12
+
+  - design-run-20250109-101534
+      Session: ui-redesign
+      Created: 2025-01-09 10:15
+      Prototypes: 6
+
+Total: 2 design run(s)
+
+💡 USE: /workflow:ui-design:generate --design-id "<id>"
+      OR: /workflow:ui-design:generate --session "<session>"
+```
+
+### All Sessions
+```
+$ /workflow:ui-design:list
+
+Available design runs:
+
+  - design-run-20250109-143052
+      Session: ui-redesign
+      Created: 2025-01-09 14:30
+      Prototypes: 12
+
+  - design-run-20250108-092314
+      Session: landing-page
+      Created: 2025-01-08 09:23
+      Prototypes: 3
+
+  - design-run-20250107-155623
+      Session: standalone
+      Created: 2025-01-07 15:56
+      Prototypes: 8
+
+Total: 3 design run(s)
+
+💡 USE: /workflow:ui-design:generate --design-id "<id>"
+      OR: /workflow:ui-design:generate --session "<session>"
+```

.claude/commands/workflow/ui-design/reference-page-generator.md

@@ -0,0 +1,333 @@
+---
+name: workflow:ui-design:reference-page-generator
+description: Generate multi-component reference pages and documentation from design run extraction
+argument-hint: "[--design-run <path>] [--package-name <name>] [--output-dir <path>]"
+allowed-tools: Read,Write,Bash,Task,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Reference Page Generator
+
+## Overview
+
+Converts design run extraction results into shareable reference package with:
+- Interactive multi-component preview (preview.html + preview.css)
+- Component layout templates (layout-templates.json)
+
+**Role**: Takes existing design run (from `import-from-code` or other extraction commands) and generates preview pages for easy reference.
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:reference-page-generator [FLAGS]
+
+# Flags
+--design-run <path>      Design run directory path (required)
+--package-name <name>    Package name for reference (required)
+--output-dir <path>      Output directory (default: .workflow/reference_style)
+```
+
+---
+
+## Execution Process
+
+### Phase 0: Setup & Validation
+
+**Purpose**: Validate inputs, prepare output directory
+
+**Operations**:
+
+```bash
+# 1. Validate required parameters
+if [ -z "$design_run" ] || [ -z "$package_name" ]; then
+  echo "ERROR: --design-run and --package-name are required"
+  echo "USAGE: /workflow:ui-design:reference-page-generator --design-run <path> --package-name <name>"
+  exit 1
+fi
+
+# 2. Validate package name format (lowercase, alphanumeric, hyphens only)
+if ! [[ "$package_name" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+  echo "ERROR: Invalid package name. Use lowercase, alphanumeric, and hyphens only."
+  echo "EXAMPLE: main-app-style-v1"
+  exit 1
+fi
+
+# 3. Validate design run exists
+if [ ! -d "$design_run" ]; then
+  echo "ERROR: Design run not found: $design_run"
+  echo "HINT: Run '/workflow:ui-design:import-from-code' first to create design run"
+  exit 1
+fi
+
+# 4. Check required extraction files exist
+required_files=(
+  "$design_run/style-extraction/style-1/design-tokens.json"
+  "$design_run/layout-extraction/layout-templates.json"
+)
+
+for file in "${required_files[@]}"; do
+  if [ ! -f "$file" ]; then
+    echo "ERROR: Required file not found: $file"
+    echo "HINT: Ensure design run has style and layout extraction results"
+    exit 1
+  fi
+done
+
+# 5. Setup output directory and validate
+output_dir="${output_dir:-.workflow/reference_style}"
+package_dir="${output_dir}/${package_name}"
+
+# Check if package directory exists and is not empty
+if [ -d "$package_dir" ] && [ "$(ls -A $package_dir 2>/dev/null)" ]; then
+  # Directory exists - check if it's a valid package or just a directory
+  if [ -f "$package_dir/metadata.json" ]; then
+    # Valid package - safe to overwrite
+    existing_version=$(jq -r '.version // "unknown"' "$package_dir/metadata.json" 2>/dev/null || echo "unknown")
+    echo "INFO: Overwriting existing package '$package_name' (version: $existing_version)"
+  else
+    # Directory exists but not a valid package
+    echo "ERROR: Directory '$package_dir' exists but is not a valid package"
+    echo "Use a different package name or remove the directory manually"
+    exit 1
+  fi
+fi
+
+mkdir -p "$package_dir"
+
+echo "[Phase 0] Setup Complete"
+echo "  Design Run: $design_run"
+echo "  Package: $package_name"
+echo "  Output: $package_dir"
+```
+
+<!-- TodoWrite: Initialize todo list -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
+  {"content": "Phase 1: 准备组件数据", "status": "in_progress", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "pending", "activeForm": "生成预览"}
+]
+```
+
+---
+
+### Phase 1: Prepare Component Data
+
+**Purpose**: Copy required files from design run to package directory
+
+**Operations**:
+
+```bash
+echo "[Phase 1] Preparing component data from design run"
+
+# 1. Copy layout templates as component patterns
+cp "${design_run}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json"
+
+if [ ! -f "${package_dir}/layout-templates.json" ]; then
+  echo "ERROR: Failed to copy layout templates"
+  exit 1
+fi
+
+# Count components from layout templates
+component_count=$(jq -r '.layout_templates | length // 0' "${package_dir}/layout-templates.json" 2>/dev/null || echo 0)
+echo "  ✓ Layout templates copied (${component_count} components)"
+
+# 2. Copy design tokens (required for preview generation)
+cp "${design_run}/style-extraction/style-1/design-tokens.json" "${package_dir}/design-tokens.json"
+
+if [ ! -f "${package_dir}/design-tokens.json" ]; then
+  echo "ERROR: Failed to copy design tokens"
+  exit 1
+fi
+echo "  ✓ Design tokens copied"
+
+# 3. Copy animation tokens if exists (optional)
+if [ -f "${design_run}/animation-extraction/animation-tokens.json" ]; then
+  cp "${design_run}/animation-extraction/animation-tokens.json" "${package_dir}/animation-tokens.json"
+  echo "  ✓ Animation tokens copied"
+else
+  echo "  ○ Animation tokens not found (optional)"
+fi
+
+echo "[Phase 1] Component data preparation complete"
+```
+
+<!-- TodoWrite: Mark Phase 1 complete, start Phase 2 -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "in_progress", "activeForm": "生成预览"}
+]
+```
+
+---
+
+### Phase 2: Preview Generation (Final Phase)
+
+**Purpose**: Generate interactive multi-component preview (preview.html + preview.css)
+
+**Agent Task**:
+
+```javascript
+Task(ui-design-agent): `
+  [PREVIEW_SHOWCASE_GENERATION]
+  Generate interactive multi-component showcase panel for reference package
+
+  PACKAGE_DIR: ${package_dir} | PACKAGE_NAME: ${package_name}
+
+  ## Input Files (MUST READ ALL)
+
+  1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED)
+  2. ${package_dir}/design-tokens.json (design tokens - REQUIRED)
+  3. ${package_dir}/animation-tokens.json (optional, if exists)
+
+  ## Generation Task
+
+  Create interactive showcase with these sections:
+
+  ### Section 1: Colors
+  - Display all color categories as color swatches
+  - Show hex/rgb values
+  - Group by: brand, semantic, surface, text, border
+
+  ### Section 2: Typography
+  - Display typography scale (font sizes, weights)
+  - Show typography combinations if available
+  - Include font family examples
+  - **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
+    * Common sizes table (small_text, body_text, heading)
+    * Common combinations with use cases
+
+  ### Section 3: Components
+  - Render all components from layout-templates.json (use layout_templates field)
+  - **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
+    * **Display usage_guide** (from layout-templates.json):
+      - Common sizes table with dimensions and use cases
+      - Variant recommendations (when to use primary/secondary/etc)
+      - Usage context list (typical scenarios)
+      - Accessibility tips checklist
+  - **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
+  - Display all variants side-by-side
+  - Show DOM structure with proper styling
+  - Include usage code snippets in <details> tags
+  - Clearly label component types (universal vs specialized)
+
+  ### Section 4: Spacing & Layout
+  - Visual spacing scale
+  - Border radius examples
+  - Shadow depth examples
+  - **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
+    * Size guide table (tight/normal/loose categories)
+    * Common patterns with use cases and pixel values
+
+  ### Section 5: Animations (if available)
+  - Animation duration examples
+  - Easing function demonstrations
+
+  ## Output Requirements
+
+  Generate 2 files:
+  1. ${package_dir}/preview.html
+  2. ${package_dir}/preview.css
+
+  ### preview.html Structure:
+  - Complete standalone HTML file
+  - Responsive design with mobile-first approach
+  - Sticky navigation for sections
+  - Interactive component demonstrations
+  - Code snippets in collapsible <details> elements
+  - Footer with package metadata
+
+  ### preview.css Structure:
+  - CSS Custom Properties from design-tokens.json
+  - Typography combination classes
+  - Component classes from layout-templates.json
+  - Preview page layout styles
+  - Interactive demo styles
+
+  ## Critical Requirements
+  - ✅ Read ALL input files (layout-templates.json, design-tokens.json, animation-tokens.json if exists)
+  - ✅ Generate complete, interactive showcase HTML
+  - ✅ All CSS uses var() references to design tokens
+  - ✅ Display ALL components from layout-templates.json
+  - ✅ **Separate universal components from specialized components** in the showcase
+  - ✅ Display component DOM structures with proper styling
+  - ✅ Include usage code snippets
+  - ✅ Label each component type clearly (Universal / Specialized)
+  - ✅ **Display usage recommendations** when available:
+    - Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
+    - Components: usage_guide for universal components (from layout-templates)
+    - Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
+  - ✅ Gracefully handle missing usage data (display sections only if data exists)
+  - ✅ Use Write() to save both files:
+    - ${package_dir}/preview.html
+    - ${package_dir}/preview.css
+  - ❌ NO external research or MCP calls
+`
+```
+
+<!-- TodoWrite: Mark all complete -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
+  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"}
+]
+```
+
+---
+
+## Output Structure
+
+```
+${output_dir}/
+└── ${package_name}/
+    ├── layout-templates.json    # Layout templates (copied from design run)
+    ├── design-tokens.json       # Design tokens (copied from design run)
+    ├── animation-tokens.json    # Animation tokens (copied from design run, optional)
+    ├── preview.html             # Interactive showcase (NEW)
+    └── preview.css              # Showcase styling (NEW)
+```
+
+## Completion Message
+
+```
+✅ Preview package generated!
+
+Package: {package_name}
+Location: {package_dir}
+
+Files:
+✓ layout-templates.json    {component_count} components
+✓ design-tokens.json       Design tokens
+✓ animation-tokens.json    Animation tokens {if exists: "✓" else: "○ (not found)"}
+✓ preview.html             Interactive showcase
+✓ preview.css              Showcase styling
+
+Open preview:
+  file://{absolute_path_to_package_dir}/preview.html
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing --design-run or --package-name | Required parameters not provided | Provide both flags |
+| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
+| Design run not found | Incorrect path or design run doesn't exist | Verify design run path, run import-from-code first |
+| Missing extraction files | Design run incomplete | Ensure design run has style-extraction and layout-extraction results |
+| Layout templates copy failed | layout-templates.json not found | Run import-from-code with Layout Agent first |
+| Preview generation failed | Invalid design tokens | Check design-tokens.json format |
+
+---
+

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

@@ -1,20 +1,22 @@
 ---
 name: style-extract
-description: Extract design style from reference images or text prompts using Claude analysis with variant generation
-argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+description: Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode
+argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*), 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. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
+Extract design style from reference images or text prompts using Claude's built-in analysis. Supports two modes:
+1. **Exploration Mode** (default): Generate multiple contrasting design variants
+2. **Refinement Mode** (`--refine`): Refine a single existing design through detailed adjustments
 
 **Strategy**: AI-Driven Design Space Exploration
 - **Claude-Native**: 100% Claude analysis, no external tools
-- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
+- **Direct Output**: Complete design systems (design-tokens.json)
 - **Flexible Input**: Images, text prompts, or both (hybrid mode)
-- **Maximum Contrast**: AI generates maximally divergent design directions
+- **Dual Mode**: Exploration (multiple contrasting variants) or Refinement (single design fine-tuning)
 - **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
 
 ## Phase 0: Setup & Input Validation
@@ -40,20 +42,41 @@ IF --urls:
 ELSE:
     has_urls = false
 
-# Determine extraction mode
-# Priority: --mode parameter → default "imitate"
-extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+# Detect refinement mode
+refine_mode = --refine OR false
 
-# Set variants count based on mode
-IF extraction_mode == "imitate":
-    variants_count = 1  # Force single variant for imitate mode (ignore --variants)
-ELSE IF extraction_mode == "explore":
-    variants_count = --variants OR 3  # Default to 3 for explore mode
+# Set variants count
+# Refinement mode: Force variants_count = 1 (ignore user-provided --variants)
+# Exploration mode: Use --variants or default to 3 (range: 1-5)
+IF refine_mode:
+    variants_count = 1
+    REPORT: "🔧 Refinement mode enabled: Will generate 1 refined design system"
+ELSE:
+    variants_count = --variants OR 3
     VALIDATE: 1 <= variants_count <= 5
+    REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting design directions"
 
-# Determine base path
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
-# OR use --base-path / --session parameters
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 ```
 
 ### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
@@ -140,72 +163,131 @@ IF exists: SKIP to completion
 
 **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 Direction Generation (Explore Mode Only)
+## Phase 1: Design Direction or Refinement Options Generation
 
-### Step 1: Check Extraction Mode
-```bash
-# Check extraction mode
-# extraction_mode == "imitate" → skip this phase
-# extraction_mode == "explore" → execute this phase
-```
-
-**If imitate mode**: Skip to Phase 2
-
-### Step 2: Load Project Context (Explore Mode)
+### Step 1: Load Project Context
 ```bash
 # Load brainstorming context if available
 bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
+
+# Load existing design system if refinement mode
+IF refine_mode:
+    existing_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
 ```
 
-### Step 3: Generate Design Direction Options (Agent Task 1)
+### Step 2: Generate Options (Agent Task 1 - Mode-Specific)
 **Executor**: `Task(ui-design-agent)`
 
-Launch agent to generate `variants_count` design direction options with previews:
+**Exploration Mode** (default): Generate contrasting design directions
+**Refinement Mode** (`--refine`): Generate refinement options for existing design
 
 ```javascript
-Task(ui-design-agent): `
-  [DESIGN_DIRECTION_GENERATION_TASK]
-  Generate {variants_count} maximally contrasting design directions with visual previews
+// Conditional agent task based on refine_mode
+IF NOT refine_mode:
+    // EXPLORATION MODE
+    Task(ui-design-agent): `
+      [DESIGN_DIRECTION_GENERATION_TASK]
+      Generate {variants_count} maximally contrasting design directions with visual previews
 
-  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+      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}
+      ## 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)
+      ## 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)
+      ## 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)
+      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
+      ## 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)
+      Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
 
-  CRITICAL: Use Write() tool immediately after generating complete JSON
-`
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
+ELSE:
+    // REFINEMENT MODE
+    Task(ui-design-agent): `
+      [DESIGN_REFINEMENT_OPTIONS_TASK]
+      Generate refinement options for existing design system
+
+      SESSION: {session_id} | MODE: refine | BASE_PATH: {base_path}
+
+      ## Existing Design System
+      - design-tokens.json: {existing_tokens}
+
+      ## Input Guidance
+      - User prompt: {prompt_guidance}
+      - Visual references: {loaded_images if available}
+
+      ## Refinement Categories
+      Generate 8-12 refinement options across these categories:
+
+      1. **Intensity/Degree Adjustments** (2-3 options):
+         - Color intensity: more vibrant ↔ more muted
+         - Visual weight: bolder ↔ lighter
+         - Density: more compact ↔ more spacious
+
+      2. **Specific Attribute Tuning** (3-4 options):
+         - Border radius: sharper corners ↔ rounder edges
+         - Shadow depth: subtler shadows ↔ deeper elevation
+         - Typography scale: tighter scale ↔ more contrast
+         - Spacing scale: tighter rhythm ↔ more breathing room
+
+      3. **Context-Specific Variations** (2-3 options):
+         - Dark mode optimization
+         - Mobile-specific adjustments
+         - High-contrast accessibility mode
+
+      4. **Component-Level Customization** (1-2 options):
+         - Button styling emphasis
+         - Card/container treatment
+         - Form input refinements
+
+      ## Output Format
+      Each option:
+      - category: "intensity|attribute|context|component"
+      - option_id: unique identifier
+      - label: Short descriptive name (e.g., "More Vibrant Colors")
+      - description: What changes (2-3 sentences)
+      - preview_changes: Key token adjustments preview
+      - impact_scope: Which tokens affected
+
+      ## Output
+      Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+
+      Use refinement schema:
+      {
+        "mode": "refinement",
+        "base_design": "style-1",
+        "refinement_options": [array of refinement options]
+      }
+
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
 ```
 
-### Step 4: Verify Options File Created
+### Step 3: Verify Options File Created
 ```bash
 bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
 
@@ -217,20 +299,44 @@ bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep
 
 ---
 
-## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+## Phase 1.5: User Confirmation (Optional - Triggered by --interactive)
 
-**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
+**Purpose**:
+- **Exploration Mode**: Allow user to select preferred design direction(s)
+- **Refinement Mode**: Allow user to select refinement options to apply
 
-### Step 1: Load and Present Options
+**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present
+
+### Step 1: Check Interactive Flag
+```bash
+# Skip this entire phase if --interactive flag is not present
+IF NOT --interactive:
+    SKIP to Phase 2
+    IF refine_mode:
+        REPORT: "ℹ️ Non-interactive refinement mode: Will apply all suggested refinements"
+    ELSE:
+        REPORT: "ℹ️ Non-interactive mode: Will generate all {variants_count} variants"
+
+REPORT: "🎯 Interactive mode enabled: User selection required"
+```
+
+### Step 2: Load and Present Options (Mode-Specific)
 ```bash
 # Read options file
 options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
 
-# Parse design directions
-design_directions = options.design_directions
+# Branch based on mode
+IF NOT refine_mode:
+    # EXPLORATION MODE
+    design_directions = options.design_directions
+ELSE:
+    # REFINEMENT MODE
+    refinement_options = options.refinement_options
 ```
 
-### Step 2: Present Options to User
+### Step 3: Present Options to User (Mode-Specific)
+
+**Exploration Mode**:
 ```
 📋 Design Direction Options
 
@@ -263,14 +369,39 @@ Please select the direction(s) you'd like to develop into complete design system
 ═══════════════════════════════════════════════════
 ```
 
-### Step 3: Capture User Selection
+**Refinement Mode**:
+```
+📋 Design Refinement Options
+
+We've analyzed your existing design system and generated refinement options.
+Please select the refinement(s) you'd like to apply.
+
+Base Design: style-1
+
+{FOR each option in refinement_options grouped by category:
+  ━━━ {category_name} ━━━
+
+  {FOR each refinement in category_options:
+    [{refinement.option_id}] {refinement.label}
+    {refinement.description}
+    Preview: {refinement.preview_changes}
+    Affects: {refinement.impact_scope}
+  }
+}
+
+═══════════════════════════════════════════════════
+```
+
+### Step 4: Capture User Selection and Update Analysis JSON
+
+**Exploration Mode Interaction**:
 ```javascript
-// Use AskUserQuestion tool for selection
+// Use AskUserQuestion tool for multi-selection
 AskUserQuestion({
   questions: [{
-    question: "Which design direction would you like to develop into a complete design system?",
+    question: "Which design direction(s) would you like to develop into complete design systems?",
     header: "Style Choice",
-    multiSelect: false,  // Single selection for Phase 1
+    multiSelect: true,  // Multi-selection enabled
     options: [
       {FOR each direction:
         label: "Option {direction.index}: {direction.philosophy_name}",
@@ -280,142 +411,187 @@ AskUserQuestion({
   }]
 })
 
-// Parse user response (e.g., "Option 1: Minimalist & Airy")
-selected_option_text = user_answer
+// Parse user response (array of selections)
+selected_options = user_answer
 
 // Check for user cancellation
-IF selected_option_text == null OR selected_option_text == "":
+IF selected_options == null OR selected_options.length == 0:
     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
-```
+// Extract option indices
+selected_indices = []
+FOR each selected_option_text IN selected_options:
+    match = selected_option_text.match(/Option (\d+):/)
+    IF match:
+        selected_indices.push(parseInt(match[1]))
 
-### 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
-  }
+REPORT: "✅ Selected {selected_indices.length} design direction(s)"
+
+// Update analysis-options.json
+options_file = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": NOW(),
+  "selected_indices": selected_indices,
+  "selection_count": selected_indices.length
 }
-
-# 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")
+Write({base_path}/.intermediates/style-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
 ```
 
-### Step 5: Confirmation Message
+**Refinement Mode Interaction**:
+```javascript
+// Use AskUserQuestion tool for multi-selection of refinements
+AskUserQuestion({
+  questions: [{
+    question: "Which refinement(s) would you like to apply to your design system?",
+    header: "Refinements",
+    multiSelect: true,  // Multi-selection enabled
+    options: [
+      {FOR each refinement:
+        label: "{refinement.label}",
+        description: "{refinement.description} (Affects: {refinement.impact_scope})"
+      }
+    ]
+  }]
+})
+
+// Parse user response
+selected_refinements = user_answer
+
+// Check for user cancellation
+IF selected_refinements == null OR selected_refinements.length == 0:
+    REPORT: "⚠️ User canceled selection. Workflow terminated."
+    EXIT workflow
+
+// Extract refinement option_ids
+selected_option_ids = []
+FOR each selected_text IN selected_refinements:
+    # Match against refinement labels to find option_ids
+    FOR each refinement IN refinement_options:
+        IF refinement.label IN selected_text:
+            selected_option_ids.push(refinement.option_id)
+
+REPORT: "✅ Selected {selected_option_ids.length} refinement(s)"
+
+// Update analysis-options.json
+options_file = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": NOW(),
+  "selected_option_ids": selected_option_ids,
+  "selection_count": selected_option_ids.length
+}
+Write({base_path}/.intermediates/style-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
+```
+
+### Step 5: Confirmation Message (Mode-Specific)
+
+**Exploration Mode**:
 ```
 ✅ Selection recorded!
 
-You selected: Option {selected_index} - {selected_direction.philosophy_name}
+You selected {selected_indices.length} design direction(s):
+{FOR each index IN selected_indices:
+  • Option {index} - {design_directions[index-1].philosophy_name}
+}
 
-Proceeding to generate complete design system based on your selection...
+Proceeding to generate {selected_indices.length} complete design system(s)...
 ```
 
-**Output**: `user-selection.json` with user's choice
+**Refinement Mode**:
+```
+✅ Selection recorded!
+
+You selected {selected_option_ids.length} refinement(s):
+{FOR each id IN selected_option_ids:
+  • {refinement_by_id[id].label} ({refinement_by_id[id].category})
+}
+
+Proceeding to apply refinements and generate updated design system...
+```
+
+**Output**: Updated `analysis-options.json` with user's selection embedded
 
 ## Phase 2: Design System Generation (Agent Task 2)
 
 **Executor**: `Task(ui-design-agent)` for selected variant(s)
 
-### Step 1: Load User Selection (Explore Mode)
+### Step 1: Load User Selection or Default to All
 ```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
+# Read analysis-options.json which may contain user_selection
+options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
 
-    # 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
+# Check if user_selection field exists (interactive mode)
+IF options.user_selection AND options.user_selection.selected_indices:
+    # Interactive mode: Use user-selected variants
+    selected_indices = options.user_selection.selected_indices  # Array of selected indices (e.g., [1, 3])
 
-    # For Phase 1, we only allow single selection
-    selected_direction = selected_directions[0]
-    actual_variants_count = 1
+    REPORT: "🎯 Interactive mode: Using {selected_indices.length} user-selected variant(s)"
 ELSE:
-    # Imitate mode - generate single variant without selection
-    selected_direction = null
-    actual_variants_count = 1
+    # Non-interactive mode: Generate ALL variants (default behavior)
+    selected_indices = [1, 2, ..., variants_count]  # All indices from 1 to variants_count
+
+    REPORT: "ℹ️ Non-interactive mode: Generating all {variants_count} variant(s)"
+
+# Extract the selected direction details from options
+selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed array
+
+actual_variants_count = selected_indices.length
+REPORT: "📦 Generating {actual_variants_count} design system(s)..."
 ```
 
-### Step 2: Create Output Directory
+### Step 2: Create Output Directories
 ```bash
-# Create directory for selected variant only
-bash(mkdir -p {base_path}/style-extraction/style-1)
+# Create directories for each selected variant
+FOR index IN 1..actual_variants_count:
+    bash(mkdir -p {base_path}/style-extraction/style-{index})
 ```
 
-### Step 3: Launch Agent Task
-Generate design system for selected direction:
+### Step 3: Launch Agent Tasks (Parallel)
+Generate design systems for ALL selected directions in parallel (max 5 concurrent):
+
 ```javascript
-Task(ui-design-agent): `
-  [DESIGN_SYSTEM_GENERATION_TASK]
-  Generate production-ready design system based on user-selected direction
+// Launch parallel tasks, one for each selected direction
+FOR variant_index IN 1..actual_variants_count:
+    selected_direction = selected_directions[variant_index - 1]  // 0-indexed
 
-  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+    Task(ui-design-agent): `
+      [DESIGN_SYSTEM_GENERATION_TASK #{variant_index}/{actual_variants_count}]
+      Generate production-ready design system based on user-selected direction
 
-  ${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}
+      SESSION: {session_id} | VARIANT: {variant_index}/{actual_variants_count} | BASE_PATH: {base_path}
 
-  ${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 : ""}
-  ` : ""}
-  ` : ""}
+      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}
 
-  ## 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)" : ""}
+      ## 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
+      ## Generation Rules
+      - 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
+      - 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/
+      ## Generate
+      Create complete design system in {base_path}/style-extraction/style-{variant_index}/
 
   1. **design-tokens.json**:
      - Complete token structure with ALL fields:
@@ -433,29 +609,15 @@ Task(ui-design-agent): `
      ${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
      - Common Tailwind CSS usage patterns in project (if extracting from existing project)
 
-  2. **style-guide.md**:
-     - Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
-     - Complete color system documentation with accessibility notes
-     - Typography scale and usage guidelines
-     - Typography Combinations section: Document each preset (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) with usage context and code examples
-     - Spacing system explanation
-     - Opacity & Transparency section: Opacity scale usage, common use cases (disabled states, overlays, hover effects), accessibility considerations
-     - Shadows & Elevation section: Shadow hierarchy and semantic usage
-     - Component Styles section: Document button, card, and input variants with code examples and visual descriptions
-     - Border Radius system and semantic usage
-     - Component examples and usage patterns
-     - Common Tailwind CSS patterns (if applicable)
-
   ## Critical Requirements
   - ✅ Use Write() tool immediately for each file
-  - ✅ Write to style-1/ directory (single output)
-  - ❌ NO external research or MCP calls (pure AI generation)
+  - ✅ Write to style-{variant_index}/ directory
+  - ✅ Can use Exa MCP to research modern design patterns and obtain code examples (Explore/Text mode)
   - ✅ 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
+**Output**: {actual_variants_count} parallel agent tasks generate design-tokens.json for each variant
 
 ## Phase 3: Verify Output
 
@@ -513,15 +675,14 @@ Design Direction Selection:
 
 Generated Files:
 {base_path}/style-extraction/
-└── style-1/ (design-tokens.json, style-guide.md)
+└── style-1/design-tokens.json
 
 {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)
+{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options + user selection)
 }
 
 Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
@@ -533,7 +694,7 @@ Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Expand image pattern
 bash(ls {images_pattern})
@@ -559,8 +720,10 @@ bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colo
 # Load brainstorming context
 bash(test -f .brainstorming/role analysis documents && cat it)
 
-# Create directories
-bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
+# Create directories (example for multiple variants)
+bash(mkdir -p {base_path}/style-extraction/style-1)
+bash(mkdir -p {base_path}/style-extraction/style-2)
+bash(mkdir -p {base_path}/style-extraction/style-3)
 
 # Verify output
 bash(ls {base_path}/style-extraction/style-1/)
@@ -574,12 +737,10 @@ bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json &&
 ├── .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)
+│       └── analysis-options.json    # Design direction options + user selection (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
+        └── design-tokens.json       # Production-ready design tokens
 ```
 
 ## design-tokens.json Format
@@ -662,10 +823,4 @@ ERROR: Claude JSON parsing error
 - **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-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 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

@@ -28,7 +28,7 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
 
 # Verify design artifacts in latest design run
-latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-run-*")
 
 # Detect design system structure
 IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
@@ -89,8 +89,8 @@ Update `.brainstorming/role analysis documents` with design system references.
 ## UI/UX Guidelines
 
 ### Design System Reference
-**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../design-{run_id}/{style_guide_path}
+**Finalized Design Tokens**: @../{design_id}/{design_tokens_path}
+**Style Guide**: @../{design_id}/{style_guide_path}
 **Design System Mode**: {design_system_mode}
 
 ### Implementation Requirements
@@ -101,12 +101,12 @@ Update `.brainstorming/role analysis documents` with design system references.
 
 ### Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
+- **{page_name}**: @../{design_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
 }
 
 ### Design System Assets
 ```json
-{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
+{"design_tokens": "{design_id}/{design_tokens_path}", "style_guide": "{design_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "{design_id}/prototypes/{prototype}.html"}]}
 ```
 ```
 
@@ -145,9 +145,9 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Design System Implementation Reference
 
-**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../../design-{run_id}/{style_guide_path}
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Design Tokens**: @../../{design_id}/{design_tokens_path}
+**Style Guide**: @../../{design_id}/{style_guide_path}
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -156,8 +156,8 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Animation & Interaction Reference
 
-**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Animations**: @../../{design_id}/animation-extraction/animation-tokens.json
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -166,7 +166,7 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Layout Structure Reference
 
-**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
+**Layout Templates**: @../../{design_id}/layout-extraction/layout-templates.json
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -175,7 +175,7 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Prototype Validation Reference
 
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -197,8 +197,8 @@ Create or update `.brainstorming/ui-designer/design-system-reference.md`:
 ## Design System Integration
 This style guide references the finalized design system from the design refinement phase.
 
-**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Design Tokens**: @../../{design_id}/{design_tokens_path}
+**Style Guide**: @../../{design_id}/{style_guide_path}
 **Design System Mode**: {design_system_mode}
 
 ## Implementation Guidelines
@@ -209,13 +209,13 @@ This style guide references the finalized design system from the design refineme
 
 ## Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
+- **{page_name}**: @../../{design_id}/prototypes/{prototype}.html
 }
 
 ## Token System
 For complete token definitions and usage examples, see:
-- Design Tokens: @../../design-{run_id}/{design_tokens_path}
-- Style Guide: @../../design-{run_id}/{style_guide_path}
+- Design Tokens: @../../{design_id}/{design_tokens_path}
+- Style Guide: @../../{design_id}/{style_guide_path}
 
 ---
 *Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
@@ -271,24 +271,24 @@ Next: /workflow:plan [--agent] "<task description>"
 
 **@ Reference Format** (role analysis documents):
 ```
-@../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../design-{run_id}/style-extraction/style-1/style-guide.md
-@../design-{run_id}/prototypes/{prototype}.html
+@../{design_id}/style-extraction/style-1/design-tokens.json
+@../{design_id}/style-extraction/style-1/style-guide.md
+@../{design_id}/prototypes/{prototype}.html
 ```
 
 **@ Reference Format** (ui-designer/design-system-reference.md):
 ```
-@../../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../../design-{run_id}/style-extraction/style-1/style-guide.md
-@../../design-{run_id}/prototypes/{prototype}.html
+@../../{design_id}/style-extraction/style-1/design-tokens.json
+@../../{design_id}/style-extraction/style-1/style-guide.md
+@../../{design_id}/prototypes/{prototype}.html
 ```
 
 **@ Reference Format** (role analysis.md files):
 ```
-@../../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../../design-{run_id}/animation-extraction/animation-tokens.json
-@../../design-{run_id}/layout-extraction/layout-templates.json
-@../../design-{run_id}/prototypes/{prototype}.html
+@../../{design_id}/style-extraction/style-1/design-tokens.json
+@../../{design_id}/animation-extraction/animation-tokens.json
+@../../{design_id}/layout-extraction/layout-templates.json
+@../../{design_id}/prototypes/{prototype}.html
 ```
 
 ## Integration with /workflow:plan
@@ -307,9 +307,9 @@ After this update, `/workflow:plan` will discover design assets through:
   "task_id": "IMPL-001",
   "context": {
     "design_system": {
-      "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"]
+      "tokens": "{design_id}/style-extraction/style-1/design-tokens.json",
+      "style_guide": "{design_id}/style-extraction/style-1/style-guide.md",
+      "prototypes": ["{design_id}/prototypes/dashboard-variant-1.html"]
     }
   }
 }

.claude/scripts/discover-design-files.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# discover-design-files.sh - Discover design-related files and output JSON
+# Usage: discover-design-files.sh <source_dir> <output_json>
+
+set -euo pipefail
+
+source_dir="${1:-.}"
+output_json="${2:-discovered-files.json}"
+
+# Function to find and format files as JSON array
+find_files() {
+  local pattern="$1"
+  local files
+  files=$(eval "find \"$source_dir\" -type f $pattern \
+    ! -path \"*/node_modules/*\" \
+    ! -path \"*/dist/*\" \
+    ! -path \"*/.git/*\" \
+    ! -path \"*/build/*\" \
+    ! -path \"*/coverage/*\" \
+    2>/dev/null | sort || true")
+
+  local count
+  if [ -z "$files" ]; then
+    count=0
+  else
+    count=$(echo "$files" | grep -c . || echo 0)
+  fi
+  local json_files=""
+
+  if [ "$count" -gt 0 ]; then
+    json_files=$(echo "$files" | awk '{printf "\"%s\"%s\n", $0, (NR<'$count'?",":"")}' | tr '\n' ' ')
+  fi
+
+  echo "$count|$json_files"
+}
+
+# Discover CSS/SCSS files
+css_result=$(find_files '\( -name "*.css" -o -name "*.scss" \)')
+css_count=${css_result%%|*}
+css_files=${css_result#*|}
+
+# Discover JS/TS files (all framework files)
+js_result=$(find_files '\( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.mjs" -o -name "*.cjs" -o -name "*.vue" -o -name "*.svelte" \)')
+js_count=${js_result%%|*}
+js_files=${js_result#*|}
+
+# Discover HTML files
+html_result=$(find_files '-name "*.html"')
+html_count=${html_result%%|*}
+html_files=${html_result#*|}
+
+# Calculate total
+total_count=$((css_count + js_count + html_count))
+
+# Generate JSON
+cat > "$output_json" << EOF
+{
+  "discovery_time": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "source_directory": "$(cd "$source_dir" && pwd)",
+  "file_types": {
+    "css": {
+      "count": $css_count,
+      "files": [${css_files}]
+    },
+    "js": {
+      "count": $js_count,
+      "files": [${js_files}]
+    },
+    "html": {
+      "count": $html_count,
+      "files": [${html_files}]
+    }
+  },
+  "total_files": $total_count
+}
+EOF
+
+# Ensure file is fully written and synchronized to disk
+# This prevents race conditions when the file is immediately read by another process
+sync "$output_json" 2>/dev/null || sync  # Sync specific file, fallback to full sync
+sleep 0.1  # Additional safety: 100ms delay for filesystem metadata update
+
+echo "Discovered: CSS=$css_count, JS=$js_count, HTML=$html_count (Total: $total_count)" >&2

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

@@ -126,13 +126,13 @@ Options:
 
 Examples:
   # Simple usage (auto-detect everything)
-  ui-instantiate-prototypes.sh .design/prototypes
+  ui-instantiate-prototypes.sh .workflow/design-run-*/prototypes
 
   # With options
-  ui-instantiate-prototypes.sh .design/prototypes --session-id WFS-auth
+  ui-instantiate-prototypes.sh .workflow/design-run-*/prototypes --session-id WFS-auth
 
   # Full manual mode
-  ui-instantiate-prototypes.sh .design/prototypes "login,dashboard" 3 3 --session-id WFS-auth
+  ui-instantiate-prototypes.sh .workflow/design-run-*/prototypes "login,dashboard" 3 3 --session-id WFS-auth
 EOF
 }
 

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

@@ -1,12 +1,47 @@
 ---
 name: command-guide
-description: Workflow command guide for Claude DMS3 (69 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
+description: Workflow command guide for Claude DMS3 (75 commands). Search/browse commands, get next-step recommendations, view documentation, report issues. Triggers "CCW-help", "CCW-issue", "ccw-help", "ccw-issue", "ccw"
 allowed-tools: Read, Grep, Glob, AskUserQuestion
+version: 5.8.0
 ---
 
 # Command Guide Skill
 
-Comprehensive command guide for Claude DMS3 workflow system covering 69 commands across 4 categories (workflow, cli, memory, task).
+Comprehensive command guide for Claude DMS3 workflow system covering 75 commands across 4 categories (workflow, cli, memory, task).
+
+## 🆕 What's New in v5.8.0
+
+### Major Features
+
+**🎨 UI Design Style Memory Workflow** (Primary Focus)
+- **`/memory:style-skill-memory`** - Generate reusable SKILL packages from design systems
+- **`/workflow:ui-design:codify-style`** - Extract design tokens from code with automatic file discovery
+- **`/workflow:ui-design:reference-page-generator`** - Generate multi-component reference pages
+- **Workflow**: Design extraction → Token documentation → SKILL package → Easy loading
+- **Benefits**: Consistent design system usage, shareable style references, progressive loading
+
+**⚡ `/workflow:lite-plan`** - Intelligent Planning & Execution (Testing Phase)
+- Dynamic workflow adaptation (smart exploration, adaptive planning, progressive clarification)
+- Two-dimensional confirmation (task approval + execution method selection)
+- Direct execution with live TodoWrite progress tracking
+- Faster than `/workflow:plan` (1-3 min vs 5-10 min) for simple to medium tasks
+
+**🗺️ `/memory:code-map-memory`** - Code Flow Mapping Generator (Testing Phase)
+- Uses cli-explore-agent for deep code flow analysis with dual-source strategy
+- Generates Mermaid diagrams for architecture, functions, data flow, conditional paths
+- Creates feature-specific SKILL packages for code understanding
+- Progressive loading (2K → 30K tokens) for efficient context management
+
+### Agent Enhancements
+
+- **cli-explore-agent** (New) - Specialized code exploration with Deep Scan mode (Bash + Gemini)
+- **cli-planning-agent** - Enhanced task generation with improved context handling
+- **ui-design-agent** - Major refactoring for better design system extraction
+
+### Additional Improvements
+- Enhanced brainstorming workflows with parallel execution
+- Improved test workflow documentation and task attachment models
+- Updated CLI tool default models (Gemini 2.5-pro)
 
 ## 🧠 Core Principle: Intelligent Integration
 
@@ -242,12 +277,13 @@ All command metadata is stored in JSON indexes for fast querying:
 
 Complete backup of all command and agent documentation for deep analysis:
 
-- **[reference/agents/](reference/agents/)** - 11 agent markdown files with implementation details
-- **[reference/commands/](reference/commands/)** - 69 command markdown files organized by category
+- **[reference/agents/](reference/agents/)** - 13 agent markdown files with implementation details
+  - **New in v5.8**: cli-explore-agent (code exploration), cli-planning-agent (enhanced)
+- **[reference/commands/](reference/commands/)** - 75 command markdown files organized by category
   - `cli/` - CLI tool commands (9 files)
-  - `memory/` - Memory management commands (8 files)
+  - `memory/` - Memory management commands (10 files) - **New**: code-map-memory, style-skill-memory
   - `task/` - Task management commands (4 files)
-  - `workflow/` - Workflow commands (46 files)
+  - `workflow/` - Workflow commands (50 files) - **New**: lite-plan, ui-design enhancements
 
 **Installation Path**: `~/.claude/skills/command-guide/` (skill designed for global installation)
 
@@ -278,13 +314,13 @@ Templates are auto-populated during Mode 5 (Issue Reporting) interaction.
 
 ## 📊 System Statistics
 
-- **Total Commands**: 69
-- **Total Agents**: 11
-- **Categories**: 4 (workflow: 46, cli: 9, memory: 8, task: 4, general: 2)
-- **Use Cases**: 5 (planning, implementation, testing, documentation, session-management)
+- **Total Commands**: 75
+- **Total Agents**: 13
+- **Categories**: 4 (workflow: 50, cli: 9, memory: 10, task: 4, general: 2)
+- **Use Cases**: 7 (planning, implementation, testing, documentation, session-management, analysis, ui-design)
 - **Difficulty Levels**: 3 (Beginner, Intermediate, Advanced)
 - **Essential Commands**: 14
-- **Reference Docs**: 80 markdown files (11 agents + 69 commands)
+- **Reference Docs**: 88 markdown files (13 agents + 75 commands)
 
 ---
 
@@ -295,7 +331,8 @@ Templates are auto-populated during Mode 5 (Issue Reporting) interaction.
 When commands are added/modified/removed:
 
 ```bash
-bash scripts/update-index.sh
+cd /d/Claude_dms3/.claude/skills/command-guide
+python scripts/analyze_commands.py
 ```
 
 This script:
@@ -307,7 +344,7 @@ This script:
 ### Committing Updates
 
 ```bash
-git add .claude/skills/command-guide/index/
+git add .claude/skills/command-guide/
 git commit -m "docs: update command indexes"
 git push
 ```
@@ -325,23 +362,28 @@ Team members get latest indexes via `git pull`.
 
 ---
 
-**Version**: 1.3.1 (Path configuration for global installation)
-**Last Updated**: 2025-11-06
+## 🔄 Maintenance
+
+### Documentation Updates
+
+This SKILL documentation is kept in sync with command implementations through a standardized update process.
+
+**Update Guideline**: See [UPDATE-GUIDELINE.md](UPDATE-GUIDELINE.md) for the complete documentation maintenance process.
+
+**Update Process**:
+1. **Analyze**: Identify changed commands/agents from git commits
+2. **Extract**: Gather change information and impact assessment
+3. **Update**: Sync reference docs, guides, and examples
+4. **Regenerate**: Run `scripts/analyze_commands.py` to rebuild indexes
+5. **Validate**: Test examples and verify consistency
+6. **Commit**: Follow standardized commit message format
+
+**Key Capabilities**:
+- 6 operation modes (Search, Recommendations, Full Docs, Onboarding, Issue Reporting, Deep Analysis)
+- 80 reference documentation files (11 agents + 69 commands)
+- 5 JSON indexes for fast command lookup
+- 8 comprehensive guides covering all workflow patterns
+- 4 issue templates for standardized problem reporting
+- CLI-assisted complex query analysis with gemini/qwen integration
+
 **Maintainer**: Claude DMS3 Team
-
-**Changelog v1.3.1**:
-- ✅ Updated all paths to use absolute paths (`~/.claude/skills/command-guide/`)
-- ✅ CLI commands now use `--include-directories` with absolute reference path
-- ✅ Ensures skill works correctly when installed in `~/.claude/skills/`
-
-**Changelog v1.3.0**:
-- ✅ Added Mode 6: Deep Command Analysis with CLI-assisted queries
-- ✅ Created reference documentation backup (80 files: 11 agents + 69 commands)
-- ✅ Support simple queries (direct file lookup) and complex queries (CLI analysis)
-- ✅ Integrated gemini/qwen for cross-command analysis and best practices
-
-**Changelog v1.2.0**:
-- ✅ Added Interactive Diagnosis template with decision tree
-- ✅ Enhanced all templates with complete command history sections
-- ✅ Added privacy protection guidelines for sensitive information
-- ✅ Integrated execution flow emphasis across all issue templates

.claude/skills/command-guide/UPDATE-GUIDELINE.md

@@ -0,0 +1,592 @@
+# Command Guide Update Guideline
+
+## 📋 Purpose
+
+This document defines a **standardized, repeatable process** for updating command-guide documentation when command changes are detected. Use this guideline every time you need to update command-guide SKILL documentation to ensure consistency and completeness.
+
+---
+
+## 🎯 Update Trigger Conditions
+
+Execute this update process when ANY of the following conditions are met:
+
+1. **New commands added** to `.claude/commands/`
+2. **Command parameters changed** (new flags, modified behavior)
+3. **Command architecture refactored** (workflow reorganization)
+4. **Agent implementations updated** in `.claude/agents/`
+5. **User explicitly requests** command-guide update
+
+---
+
+## 📊 Phase 1: Analysis & Discovery
+
+### Step 1.1: Identify Changed Files
+
+**Objective**: Discover what has changed since last update
+
+**Actions**:
+```bash
+# Find recent commits affecting commands/agents
+git log --oneline --since="<last-update-date>" --grep="command\|agent\|workflow" -20
+
+# Show detailed changes
+git diff <last-commit>..<current-commit> --stat .claude/commands/ .claude/agents/
+
+# Identify modified command files
+git diff <last-commit>..<current-commit> --name-only .claude/commands/
+```
+
+**Output**: List of changed files and commit messages
+
+**Document**:
+- Changed command files
+- Changed agent files
+- Key commit messages
+- Change patterns (new features, refactoring, fixes)
+
+---
+
+### Step 1.2: Analyze Change Scope
+
+**Objective**: Understand the nature and impact of changes
+
+**Questions to Answer**:
+1. **What changed?** (parameters, workflow, architecture, behavior)
+2. **Why changed?** (new feature, optimization, bug fix, refactoring)
+3. **Impact scope?** (single command, workflow pattern, system-wide)
+4. **User-facing?** (affects user commands, internal only)
+
+**Analysis Matrix**:
+
+| Change Type | Detection Method | Impact Level |
+|-------------|--------------------|--------------|
+| **New Parameter** | Diff `argument-hint` field | Medium |
+| **Workflow Reorganization** | Multiple command changes | High |
+| **Architecture Change** | Agent file changes + command changes | High |
+| **Bug Fix** | Single file, small change | Low |
+| **New Command** | New file in `.claude/commands/` | Medium-High |
+
+**Output**: Change classification and impact assessment
+
+---
+
+### Step 1.3: Map Affected Documentation
+
+**Objective**: Identify which documentation files need updates
+
+**Mapping Rules**:
+
+**Command Changes** → Affects:
+- `reference/commands/<category>/<command-name>.md` (copy from source)
+- `index/all-commands.json` (regenerate)
+- `index/by-category.json` (if new category)
+- `guides/ui-design-workflow-guide.md` (if UI workflow affected)
+- `guides/workflow-patterns.md` (if workflow pattern changed)
+
+**Agent Changes** → Affects:
+- `reference/agents/<agent-name>.md` (copy from source)
+- `guides/implementation-details.md` (if agent behavior changed)
+
+**Workflow Reorganization** → Affects:
+- All related command references
+- Workflow guides
+- Examples in guides
+
+**Output**: Checklist of files to update
+
+---
+
+## 🔧 Phase 2: Content Preparation
+
+### Step 2.1: Extract Key Information
+
+**Objective**: Gather information needed for documentation updates
+
+**Extract from Git Commits**:
+```bash
+# Get commit details
+git show <commit-hash> --stat
+
+# Extract commit message
+git log --format=%B -n 1 <commit-hash>
+```
+
+**Information to Extract**:
+1. **Feature Name** (from commit message)
+2. **Change Description** (what was added/modified/removed)
+3. **Rationale** (why the change was made)
+4. **New Parameters** (from diff)
+5. **Breaking Changes** (backward compatibility impact)
+6. **Usage Examples** (from commit or command file)
+
+**Output**: Structured data for documentation
+
+---
+
+### Step 2.2: Categorize Changes
+
+**Objective**: Organize changes into logical categories
+
+**Categories**:
+
+1. **Major Features**
+   - New commands
+   - New workflows
+   - Architecture changes
+   - User-facing feature additions
+
+2. **Enhancements**
+   - New parameters
+   - Improved behavior
+   - Performance optimizations
+   - Better error handling
+
+3. **Refactoring**
+   - Code reorganization (no user impact)
+   - Internal structure changes
+   - Consistency improvements
+
+4. **Bug Fixes**
+   - Corrected behavior
+   - Fixed edge cases
+   - Parameter validation fixes
+
+5. **Documentation**
+   - Updated descriptions
+   - New examples
+   - Clarified usage
+
+**Output**: Changes grouped by category with priority
+
+---
+
+### Step 2.3: Analyze User Impact
+
+**Objective**: Determine what users need to know
+
+**User Impact Questions**:
+1. **Do existing workflows break?** → Migration guide needed
+2. **Are new features optional?** → Enhancement documentation
+3. **Is behavior significantly different?** → Usage pattern updates
+4. **Do examples need updates?** → Example refresh required
+
+**Impact Levels**:
+- **Critical** (Breaking changes, migration required)
+- **Important** (New features users should adopt)
+- **Nice-to-have** (Enhancements, optional)
+- **Internal** (No user action needed)
+
+**Output**: User-facing change summary with impact levels
+
+---
+
+## 📝 Phase 3: Documentation Updates
+
+### Step 3.1: Update Reference Documentation
+
+**Objective**: Sync reference docs with source command files
+
+**Actions**:
+
+1. **Run Python Script to Sync & Rebuild**:
+   ```bash
+   cd /d/Claude_dms3/.claude/skills/command-guide
+   python scripts/analyze_commands.py
+   ```
+
+   This script automatically:
+   - Deletes existing `reference/` directory
+   - Copies all agent files from `.claude/agents/` to `reference/agents/`
+   - Copies all command files from `.claude/commands/` to `reference/commands/`
+   - Regenerates all 5 index files with updated metadata
+
+2. **Verify Completeness**:
+   - Check sync output for file counts (11 agents + 70 commands)
+   - Verify all 5 index files regenerated successfully
+   - Ensure YAML frontmatter integrity in copied files
+
+**Output**: Updated reference documentation matching source + regenerated indexes
+
+---
+
+### Step 3.2: Update Workflow Guides
+
+**Objective**: Reflect changes in user-facing workflow guides
+
+**Workflow Guide Update Pattern**:
+
+**IF** (UI workflow commands changed):
+1. Open `guides/ui-design-workflow-guide.md`
+2. Locate affected workflow pattern sections
+3. Update examples to use new parameters/behavior
+4. Add "New!" badges for new features
+5. Update performance metrics if applicable
+6. Add troubleshooting entries for new issues
+
+**IF** (General workflow patterns changed):
+1. Open `guides/workflow-patterns.md`
+2. Update affected workflow examples
+3. Add new pattern sections if applicable
+
+**Update Template for New Features**:
+```markdown
+### [Feature Name] (New!)
+
+**Purpose**: [What this feature enables]
+
+**Usage**:
+```bash
+[Example command with new feature]
+```
+
+**Benefits**:
+- [Benefit 1]
+- [Benefit 2]
+
+**When to Use**:
+- [Use case 1]
+- [Use case 2]
+```
+
+**Output**: Updated workflow guides with new features documented
+
+---
+
+### Step 3.3: Update Examples and Best Practices
+
+**Objective**: Ensure examples reflect current best practices
+
+**Example Update Checklist**:
+- [ ] Remove deprecated parameter usage
+- [ ] Add examples for new parameters
+- [ ] Update command syntax if changed
+- [ ] Verify all examples are runnable
+- [ ] Add "Note" sections for common pitfalls
+
+**Best Practices Update**:
+- [ ] Add recommendations for new features
+- [ ] Update "When to Use" guidelines
+- [ ] Revise performance optimization tips
+- [ ] Update troubleshooting entries
+
+**Output**: Current, runnable examples
+
+---
+
+### Step 3.4: Update SKILL.md Metadata
+
+**Objective**: Keep SKILL.md current without version-specific details
+
+**Update Sections**:
+
+1. **Supporting Guides** (if new guide added):
+   ```markdown
+   - **[New Guide Name](guides/new-guide.md)** - Description
+   ```
+
+2. **System Statistics** (if counts changed):
+   ```markdown
+   - **Total Commands**: <new-count>
+   - **Total Agents**: <new-count>
+   ```
+
+3. **Remove Old Changelog Entries**:
+   - Keep only last 3 changelog entries
+   - Archive older entries to separate file if needed
+
+**DO NOT**:
+- Add version numbers
+- Add specific dates
+- Create time-based changelog entries
+
+**Output**: Updated SKILL.md metadata
+
+---
+
+## 🧪 Phase 4: Validation
+
+### Step 4.1: Consistency Check
+
+**Objective**: Ensure documentation is internally consistent
+
+**Checklist**:
+- [ ] All command references use correct names
+- [ ] Parameter descriptions match command files
+- [ ] Examples use valid parameter combinations
+- [ ] Links between documents are not broken
+- [ ] Index files reflect current command count
+
+**Validation Commands**:
+```bash
+# Check for broken internal links
+grep -r "\[.*\](.*\.md)" guides/ reference/ | grep -v "http"
+
+# Verify command count consistency
+actual=$(find ../../commands -name "*.md" | wc -l)
+indexed=$(jq '.commands | length' index/all-commands.json)
+echo "Actual: $actual, Indexed: $indexed"
+```
+
+**Output**: Validation report
+
+---
+
+### Step 4.2: Example Testing
+
+**Objective**: Verify all examples are runnable
+
+**Test Cases**:
+- [ ] Copy example commands from guides
+- [ ] Run in test environment
+- [ ] Verify expected output
+- [ ] Document any prerequisites
+
+**Note**: Some examples may be illustrative only; mark these clearly
+
+**Output**: Tested examples
+
+---
+
+### Step 4.3: Peer Review Checklist
+
+**Objective**: Prepare documentation for review
+
+**Review Points**:
+- [ ] Is the change clearly explained?
+- [ ] Are examples helpful and clear?
+- [ ] Is migration guidance complete (if breaking)?
+- [ ] Are troubleshooting tips adequate?
+- [ ] Is the documentation easy to scan?
+
+**Output**: Review-ready documentation
+
+---
+
+## 📤 Phase 5: Commit & Distribution
+
+### Step 5.1: Git Commit Structure
+
+**Objective**: Create clear, traceable commits
+
+**Commit Pattern**:
+```bash
+git add .claude/skills/command-guide/
+
+# Commit message format
+git commit -m "docs(command-guide): update for <feature-name> changes
+
+- Update reference docs for <changed-commands>
+- Enhance <guide-name> with <feature> documentation
+- Regenerate indexes (new count: <count>)
+- Add troubleshooting for <new-issues>
+
+Refs: <commit-hashes-of-source-changes>
+"
+```
+
+**Commit Message Rules**:
+- **Type**: `docs(command-guide)`
+- **Scope**: Always `command-guide`
+- **Summary**: Concise, imperative mood
+- **Body**: Bullet points for each change type
+- **Refs**: Link to source change commits
+
+**Output**: Clean commit history
+
+---
+
+### Step 5.2: Update Distribution
+
+**Objective**: Make updates available to users
+
+**Actions**:
+```bash
+# Push to remote
+git push origin main
+
+# Verify GitHub reflects changes
+# Check: https://github.com/<org>/<repo>/tree/main/.claude/skills/command-guide
+```
+
+**User Notification** (if breaking changes):
+- Update project README
+- Add note to main documentation
+- Consider announcement in team channels
+
+**Output**: Published updates
+
+---
+
+## 🔄 Phase 6: Iteration & Improvement
+
+### Step 6.1: Gather Feedback
+
+**Objective**: Improve documentation based on usage
+
+**Feedback Sources**:
+- User questions about changed commands
+- Confusion points in examples
+- Missing information requests
+- Error reports
+
+**Track**:
+- Common questions → Add to troubleshooting
+- Confusing examples → Simplify or expand
+- Missing use cases → Add to guides
+
+**Output**: Improvement backlog
+
+---
+
+### Step 6.2: Continuous Refinement
+
+**Objective**: Keep documentation evolving
+
+**Regular Tasks**:
+- [ ] Review index statistics monthly
+- [ ] Update examples with real-world usage
+- [ ] Consolidate redundant sections
+- [ ] Expand troubleshooting based on issues
+- [ ] Refresh screenshots/outputs if UI changed
+
+**Output**: Living documentation
+
+---
+
+## 📐 Update Decision Matrix
+
+Use this matrix to determine update depth:
+
+| Change Scope | Reference Docs | Workflow Guides | Examples | Indexes | Migration Guide |
+|--------------|----------------|-----------------|----------|---------|-----------------|
+| **New Parameter** | Update command file | Add parameter note | Add usage example | Regenerate | No |
+| **Workflow Refactor** | Update all affected | Major revision | Update all examples | Regenerate | If breaking |
+| **New Command** | Copy new file | Add workflow pattern | Add examples | Regenerate | No |
+| **Architecture Change** | Update all affected | Major revision | Comprehensive update | Regenerate | Yes |
+| **Bug Fix** | Update description | Add note if user-visible | Fix incorrect examples | No change | No |
+| **New Feature** | Update affected files | Add feature section | Add feature examples | Regenerate | No |
+
+---
+
+## 🎯 Quality Gates
+
+Before considering documentation update complete, verify:
+
+### Gate 1: Completeness
+- [ ] All changed commands have updated reference docs
+- [ ] All new features are documented in guides
+- [ ] All examples are current and correct
+- [ ] Indexes reflect current state
+
+### Gate 2: Clarity
+- [ ] Non-expert can understand changes
+- [ ] Examples demonstrate key use cases
+- [ ] Migration path is clear (if breaking)
+- [ ] Troubleshooting covers common issues
+
+### Gate 3: Consistency
+- [ ] Terminology is consistent across docs
+- [ ] Parameter descriptions match everywhere
+- [ ] Cross-references are accurate
+- [ ] Formatting follows established patterns
+
+### Gate 4: Accessibility
+- [ ] Table of contents is current
+- [ ] Search/navigation works
+- [ ] Related docs are linked
+- [ ] Issue templates reference new content
+
+---
+
+## 🚀 Quick Start Template
+
+When updates are needed, follow this abbreviated workflow:
+
+```bash
+# 1. ANALYZE (5 min)
+git log --oneline --since="<last-update>" --grep="command\|agent" -20
+# → Identify what changed
+
+# 2. EXTRACT (10 min)
+git show <commit-hash> --stat
+git diff <commit>..HEAD --stat .claude/commands/
+# → Understand changes
+
+# 3. UPDATE (30 min)
+# - Update affected guide sections (ui-design-workflow-guide.md, etc.)
+# - Add examples for new features
+# - Document parameter changes
+
+# 4. SYNC & REGENERATE (2 min)
+cd /d/Claude_dms3/.claude/skills/command-guide
+python scripts/analyze_commands.py
+# → Syncs reference docs + regenerates all 5 indexes
+
+# 5. VALIDATE (10 min)
+# - Test examples
+# - Check consistency
+# - Verify links
+
+# 6. COMMIT (5 min)
+git add .claude/skills/command-guide/
+git commit -m "docs(command-guide): update for <feature> changes"
+git push origin main
+```
+
+**Total Time**: ~1 hour for typical update
+
+---
+
+## 🔗 Related Resources
+
+- **Python Index Script**: `.claude/skills/command-guide/scripts/analyze_commands.py`
+- **Issue Templates**: `.claude/skills/command-guide/templates/`
+- **SKILL Entry Point**: `.claude/skills/command-guide/SKILL.md`
+- **Reference Source**: `.claude/commands/` and `.claude/agents/`
+
+---
+
+## 📌 Appendix: Common Patterns
+
+### Pattern 1: New Parameter Addition
+
+**Example**: `--interactive` flag added to `explore-auto`
+
+**Update Sequence**:
+1. Update `guides/ui-design-workflow-guide.md` with interactive examples
+2. Add "When to Use" guidance
+3. Run Python script to sync reference docs and regenerate indexes
+4. Update argument-hint in examples
+
+---
+
+### Pattern 2: Workflow Reorganization
+
+**Example**: Layout extraction split into concept generation + selection
+
+**Update Sequence**:
+1. Major revision of workflow guide section
+2. Update all workflow examples
+3. Add migration notes for existing users
+4. Update troubleshooting
+5. Run Python script to sync and regenerate indexes
+
+---
+
+### Pattern 3: Architecture Change
+
+**Example**: Agent execution model changed
+
+**Update Sequence**:
+1. Update `guides/implementation-details.md`
+2. Revise all workflow patterns using affected agents
+3. Create migration guide
+4. Update examples comprehensively
+5. Run Python script to sync and regenerate indexes
+6. Add extensive troubleshooting
+
+---
+
+**End of Update Guideline**
+
+This guideline is a living document. Improve it based on update experience.

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

@@ -12,7 +12,6 @@ These commands automate end-to-end processes by chaining specialized sub-command
 
 - **`/workflow:ui-design:explore-auto`**: For creating *new* designs. Generates multiple style and layout variants from a prompt to explore design directions.
 - **`/workflow:ui-design:imitate-auto`**: For *replicating* existing designs. High-fidelity cloning of target URLs into a reusable design system.
-- **`/workflow:ui-design:batch-generate`**: For rapid, high-volume prototype generation based on established design tokens.
 
 ### 2. Core Extractors (Specialized Analysis)
 
@@ -55,7 +54,7 @@ Tools for combining components and integrating results.
 4. **Assembly**: System generates a matrix of prototypes (3 styles × 1 layout = 3 prototypes).
 5. **Review**: User views `compare.html` to select the best direction.
 
-**Example:**
+**Example (Non-Interactive - Default):**
 
 ```bash
 /workflow:ui-design:explore-auto \
@@ -71,6 +70,30 @@ Tools for combining components and integrating results.
 - 6 HTML prototypes (3 × 2 combinations)
 - `compare.html` for side-by-side comparison
 
+**Example (Interactive Mode):**
+
+```bash
+/workflow:ui-design:explore-auto \
+  --prompt "Modern SaaS landing page with hero, features, pricing sections" \
+  --style-variants 5 \
+  --layout-variants 4 \
+  --interactive \
+  --session WFS-001
+```
+
+**Interactive Flow:**
+1. System generates 5 style concepts
+2. **User selects** 2-3 preferred styles (multi-select)
+3. System generates 4 layout concepts
+4. **User selects** 2 preferred layouts (multi-select)
+5. System generates only 4-6 final prototypes (selected combinations)
+
+**Benefits:**
+- Reduces unnecessary generation (from 20 to 4-6 prototypes)
+- Focuses resources on preferred design directions
+- Saves 70-80% computation time
+- Better exploration quality
+
 ---
 
 ### Workflow B: Design Replication (Imitation)
@@ -132,36 +155,6 @@ Tools for combining components and integrating results.
 
 ---
 
-### Workflow D: Batch Generation (High Volume)
-
-**Goal:** Generate multiple UI prototypes based on established design tokens.
-
-**Primary Command:** `batch-generate`
-
-**Steps:**
-
-1. **Prerequisites**: Have `design-tokens.json` ready (from previous extraction or manual creation)
-2. **Initiate**: User runs `/workflow:ui-design:batch-generate --targets "dashboard,settings,profile" --style-variants 2`
-3. **Parallel Generation**: System generates all targets in parallel, applying style variants
-4. **Review**: User reviews generated prototypes
-
-**Example:**
-
-```bash
-/workflow:ui-design:batch-generate \
-  --targets "login-page,dashboard,settings,profile,notifications" \
-  --target-type page \
-  --style-variants 2 \
-  --device-type responsive \
-  --session WFS-004
-```
-
-**Output:**
-- 10 HTML prototypes (5 targets × 2 styles)
-- All using the same design system for consistency
-
----
-
 ## Architecture & Best Practices
 
 ### Separation of Concerns
@@ -201,7 +194,7 @@ Generated CSS should primarily use CSS custom properties:
 
 For high-volume generation:
 - Group tasks by style to minimize context switching
-- Use `batch-generate` with multiple targets
+- Use parallel generation with multiple targets
 - Reuse existing layout inspirations
 
 ### Input Quality Guidelines
@@ -237,14 +230,15 @@ You can run UI design workflows within an existing workflow session:
 
 ### Combining Workflows
 
-**Example: Imitation + Custom Variants**
+**Example: Imitation + Custom Extraction**
 
 ```bash
 # 1. Replicate existing design
 /workflow:ui-design:imitate-auto --url-map "ref:https://example.com"
 
-# 2. Generate additional variants with batch-generate
-/workflow:ui-design:batch-generate --targets "new-page-1,new-page-2" --style-variants 1
+# 2. Extract additional layouts and generate prototypes
+/workflow:ui-design:layout-extract --targets "new-page-1,new-page-2"
+/workflow:ui-design:generate
 ```
 
 ### Deep Interactive Capture
@@ -279,7 +273,6 @@ For complex UIs with overlays, modals, or dynamic content:
 ### Orchestrators
 - `/workflow:ui-design:explore-auto` - Create new designs from prompts
 - `/workflow:ui-design:imitate-auto` - Replicate existing designs
-- `/workflow:ui-design:batch-generate` - High-volume prototype generation
 
 ### Extractors
 - `/workflow:ui-design:style-extract` - Extract visual design tokens
@@ -306,7 +299,7 @@ The system is designed to run extraction phases in parallel:
 
 ### Reuse Intermediates
 
-- `batch-generate` reuses existing layout inspirations
+- Generation commands reuse existing layout inspirations
 - Cached screenshots avoid redundant captures
 - Token files can be versioned and reused
 

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

@@ -3,7 +3,7 @@
     "name": "analyze",
     "command": "/cli:analyze",
     "description": "Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] analysis target",
     "category": "cli",
     "subcategory": null,
     "usage_scenario": "analysis",
@@ -14,7 +14,7 @@
     "name": "chat",
     "command": "/cli:chat",
     "description": "Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] inquiry",
     "category": "cli",
     "subcategory": null,
     "usage_scenario": "general",
@@ -58,7 +58,7 @@
     "name": "execute",
     "command": "/cli:execute",
     "description": "Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] description or task-id",
     "category": "cli",
     "subcategory": null,
     "usage_scenario": "implementation",
@@ -69,7 +69,7 @@
     "name": "bug-diagnosis",
     "command": "/cli:mode:bug-diagnosis",
     "description": "Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
     "category": "cli",
     "subcategory": "mode",
     "usage_scenario": "analysis",
@@ -80,7 +80,7 @@
     "name": "code-analysis",
     "command": "/cli:mode:code-analysis",
     "description": "Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
     "category": "cli",
     "subcategory": "mode",
     "usage_scenario": "general",
@@ -91,7 +91,7 @@
     "name": "plan",
     "command": "/cli:mode:plan",
     "description": "Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
     "category": "cli",
     "subcategory": "mode",
     "usage_scenario": "planning",
@@ -109,6 +109,17 @@
     "difficulty": "Intermediate",
     "file_path": "enhance-prompt.md"
   },
+  {
+    "name": "code-map-memory",
+    "command": "/memory:code-map-memory",
+    "description": "3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)",
+    "arguments": "\\\"feature-keyword\\\" [--regenerate] [--tool <gemini|qwen>]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/code-map-memory.md"
+  },
   {
     "name": "docs",
     "command": "/memory:docs",
@@ -153,6 +164,17 @@
     "difficulty": "Intermediate",
     "file_path": "memory/skill-memory.md"
   },
+  {
+    "name": "style-skill-memory",
+    "command": "/memory:style-skill-memory",
+    "description": "Generate SKILL memory package from style reference for easy loading and consistent design system usage",
+    "arguments": "[package-name] [--regenerate]",
+    "category": "memory",
+    "subcategory": null,
+    "usage_scenario": "documentation",
+    "difficulty": "Intermediate",
+    "file_path": "memory/style-skill-memory.md"
+  },
   {
     "name": "tech-research",
     "command": "/memory:tech-research",
@@ -406,11 +428,22 @@
     "difficulty": "Intermediate",
     "file_path": "workflow/execute.md"
   },
+  {
+    "name": "lite-plan",
+    "command": "/workflow:lite-plan",
+    "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
+    "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
+    "category": "workflow",
+    "subcategory": null,
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/lite-plan.md"
+  },
   {
     "name": "plan",
     "command": "/workflow:plan",
-    "description": "5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
-    "arguments": "[--agent] [--cli-execute] \\\"text description\\\"|file.md",
+    "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
+    "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
     "category": "workflow",
     "subcategory": null,
     "usage_scenario": "planning",
@@ -498,7 +531,7 @@
     "name": "tdd-plan",
     "command": "/workflow:tdd-plan",
     "description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
-    "arguments": "[--agent] \\\"feature description\\\"|file.md",
+    "arguments": "[--cli-execute] \\\"feature description\\\"|file.md",
     "category": "workflow",
     "subcategory": null,
     "usage_scenario": "planning",
@@ -519,7 +552,7 @@
   {
     "name": "test-cycle-execute",
     "command": "/workflow:test-cycle-execute",
-    "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached",
+    "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.",
     "arguments": "[--resume-session=\\\"session-id\\\"] [--max-iterations=N]",
     "category": "workflow",
     "subcategory": null,
@@ -585,8 +618,8 @@
   {
     "name": "task-generate-tdd",
     "command": "/workflow:tools:task-generate-tdd",
-    "description": "Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation",
-    "arguments": "--session WFS-session-id [--agent]",
+    "description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation",
+    "arguments": "--session WFS-session-id [--cli-execute]",
     "category": "workflow",
     "subcategory": "tools",
     "usage_scenario": "implementation",
@@ -640,7 +673,7 @@
   {
     "name": "test-task-generate",
     "command": "/workflow:tools:test-task-generate",
-    "description": "Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex",
+    "description": "Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase",
     "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
     "category": "workflow",
     "subcategory": "tools",
@@ -651,41 +684,41 @@
   {
     "name": "animation-extract",
     "command": "/workflow:ui-design:animation-extract",
-    "description": "Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation",
-    "arguments": "[--base-path <path>] [--session <id>] [--urls \"<list>\"] [--mode <auto|interactive>] [--focus \"<types>\"]",
+    "description": "Extract animation and transition patterns from prompt inference and image references for design system documentation",
+    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--focus \"<types>\"] [--interactive] [--refine]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/animation-extract.md"
   },
-  {
-    "name": "batch-generate",
-    "command": "/workflow:ui-design:batch-generate",
-    "description": "Prompt-driven batch UI generation using target-style-centric parallel execution with design token application",
-    "arguments": "[--targets \"<list>\"] [--target-type \"page|component\"] [--device-type \"desktop|mobile|tablet|responsive\"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
-    "category": "workflow",
-    "subcategory": "ui-design",
-    "usage_scenario": "implementation",
-    "difficulty": "Intermediate",
-    "file_path": "workflow/ui-design/batch-generate.md"
-  },
   {
     "name": "capture",
     "command": "/workflow:ui-design:capture",
     "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
-    "arguments": "--url-map \"target:url,...\" [--base-path path] [--session id]",
+    "arguments": "--url-map \"target:url,...\" [--design-id <id>] [--session <id>]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/capture.md"
   },
+  {
+    "name": "workflow:ui-design:codify-style",
+    "command": "/workflow:ui-design:codify-style",
+    "description": "Orchestrator to extract styles from code and generate shareable reference package with preview (automatic file discovery)",
+    "arguments": "<path> [--package-name <name>] [--output-dir <path>] [--overwrite]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/codify-style.md"
+  },
   {
     "name": "explore-auto",
     "command": "/workflow:ui-design:explore-auto",
-    "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution",
-    "arguments": "[--prompt \"<desc>\"] [--images \"<glob>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
+    "description": "Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection",
+    "arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
@@ -696,7 +729,7 @@
     "name": "explore-layers",
     "command": "/workflow:ui-design:explore-layers",
     "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
-    "arguments": "--url <url> --depth <1-5> [--session id] [--base-path path]",
+    "arguments": "--url <url> --depth <1-5> [--design-id <id>] [--session <id>]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
@@ -706,8 +739,8 @@
   {
     "name": "generate",
     "command": "/workflow:ui-design:generate",
-    "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation",
-    "arguments": "[--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+    "description": "Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation",
+    "arguments": "[--design-id <id>] [--session <id>]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "implementation",
@@ -717,8 +750,8 @@
   {
     "name": "imitate-auto",
     "command": "/workflow:ui-design:imitate-auto",
-    "description": "High-speed multi-page UI replication with batch screenshot capture and design token extraction",
-    "arguments": "--url-map \"<map>\" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt \"<desc>\"]",
+    "description": "UI design workflow with direct code/image input for design token extraction and prototype generation",
+    "arguments": "[--input \"<value>\"] [--session <id>]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
@@ -728,8 +761,8 @@
   {
     "name": "workflow:ui-design:import-from-code",
     "command": "/workflow:ui-design:import-from-code",
-    "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis",
-    "arguments": "[--base-path <path>] [--css \\\"<glob>\\\"] [--js \\\"<glob>\\\"] [--scss \\\"<glob>\\\"] [--html \\\"<glob>\\\"] [--style-files \\\"<glob>\\\"] [--session <id>]",
+    "description": "Import design system from code files (CSS/JS/HTML/SCSS) with automatic file discovery and parallel agent analysis",
+    "arguments": "[--design-id <id>] [--session <id>] [--source <path>]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "planning",
@@ -739,19 +772,41 @@
   {
     "name": "layout-extract",
     "command": "/workflow:ui-design:layout-extract",
-    "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis",
-    "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]",
+    "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode",
+    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",
     "difficulty": "Intermediate",
     "file_path": "workflow/ui-design/layout-extract.md"
   },
+  {
+    "name": "list",
+    "command": "/workflow:ui-design:list",
+    "description": "List all available design runs with metadata (session, created time, prototype count)",
+    "arguments": "[--session <id>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "general",
+    "difficulty": "Beginner",
+    "file_path": "workflow/ui-design/list.md"
+  },
+  {
+    "name": "workflow:ui-design:reference-page-generator",
+    "command": "/workflow:ui-design:reference-page-generator",
+    "description": "Generate multi-component reference pages and documentation from design run extraction",
+    "arguments": "[--design-run <path>] [--package-name <name>] [--output-dir <path>]",
+    "category": "workflow",
+    "subcategory": "ui-design",
+    "usage_scenario": "planning",
+    "difficulty": "Intermediate",
+    "file_path": "workflow/ui-design/reference-page-generator.md"
+  },
   {
     "name": "style-extract",
     "command": "/workflow:ui-design:style-extract",
-    "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation",
-    "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--mode <imitate|explore>] [--variants <count>]",
+    "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode",
+    "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
     "category": "workflow",
     "subcategory": "ui-design",
     "usage_scenario": "general",

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

@@ -5,7 +5,7 @@
         "name": "analyze",
         "command": "/cli:analyze",
         "description": "Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection",
-        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] analysis target",
         "category": "cli",
         "subcategory": null,
         "usage_scenario": "analysis",
@@ -16,7 +16,7 @@
         "name": "chat",
         "command": "/cli:chat",
         "description": "Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference",
-        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] inquiry",
         "category": "cli",
         "subcategory": null,
         "usage_scenario": "general",
@@ -60,7 +60,7 @@
         "name": "execute",
         "command": "/cli:execute",
         "description": "Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection",
-        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] description or task-id",
         "category": "cli",
         "subcategory": null,
         "usage_scenario": "implementation",
@@ -73,7 +73,7 @@
         "name": "bug-diagnosis",
         "command": "/cli:mode:bug-diagnosis",
         "description": "Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions",
-        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
         "category": "cli",
         "subcategory": "mode",
         "usage_scenario": "analysis",
@@ -84,7 +84,7 @@
         "name": "code-analysis",
         "command": "/cli:mode:code-analysis",
         "description": "Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization",
-        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
         "category": "cli",
         "subcategory": "mode",
         "usage_scenario": "general",
@@ -95,7 +95,7 @@
         "name": "plan",
         "command": "/cli:mode:plan",
         "description": "Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis",
-        "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
+        "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
         "category": "cli",
         "subcategory": "mode",
         "usage_scenario": "planning",
@@ -132,6 +132,17 @@
   },
   "memory": {
     "_root": [
+      {
+        "name": "code-map-memory",
+        "command": "/memory:code-map-memory",
+        "description": "3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)",
+        "arguments": "\\\"feature-keyword\\\" [--regenerate] [--tool <gemini|qwen>]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/code-map-memory.md"
+      },
       {
         "name": "docs",
         "command": "/memory:docs",
@@ -176,6 +187,17 @@
         "difficulty": "Intermediate",
         "file_path": "memory/skill-memory.md"
       },
+      {
+        "name": "style-skill-memory",
+        "command": "/memory:style-skill-memory",
+        "description": "Generate SKILL memory package from style reference for easy loading and consistent design system usage",
+        "arguments": "[package-name] [--regenerate]",
+        "category": "memory",
+        "subcategory": null,
+        "usage_scenario": "documentation",
+        "difficulty": "Intermediate",
+        "file_path": "memory/style-skill-memory.md"
+      },
       {
         "name": "tech-research",
         "command": "/memory:tech-research",
@@ -294,11 +316,22 @@
         "difficulty": "Intermediate",
         "file_path": "workflow/execute.md"
       },
+      {
+        "name": "lite-plan",
+        "command": "/workflow:lite-plan",
+        "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
+        "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
+        "category": "workflow",
+        "subcategory": null,
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/lite-plan.md"
+      },
       {
         "name": "plan",
         "command": "/workflow:plan",
-        "description": "5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
-        "arguments": "[--agent] [--cli-execute] \\\"text description\\\"|file.md",
+        "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
+        "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
         "category": "workflow",
         "subcategory": null,
         "usage_scenario": "planning",
@@ -342,7 +375,7 @@
         "name": "tdd-plan",
         "command": "/workflow:tdd-plan",
         "description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
-        "arguments": "[--agent] \\\"feature description\\\"|file.md",
+        "arguments": "[--cli-execute] \\\"feature description\\\"|file.md",
         "category": "workflow",
         "subcategory": null,
         "usage_scenario": "planning",
@@ -363,7 +396,7 @@
       {
         "name": "test-cycle-execute",
         "command": "/workflow:test-cycle-execute",
-        "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached",
+        "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.",
         "arguments": "[--resume-session=\\\"session-id\\\"] [--max-iterations=N]",
         "category": "workflow",
         "subcategory": null,
@@ -611,8 +644,8 @@
       {
         "name": "task-generate-tdd",
         "command": "/workflow:tools:task-generate-tdd",
-        "description": "Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation",
-        "arguments": "--session WFS-session-id [--agent]",
+        "description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation",
+        "arguments": "--session WFS-session-id [--cli-execute]",
         "category": "workflow",
         "subcategory": "tools",
         "usage_scenario": "implementation",
@@ -666,7 +699,7 @@
       {
         "name": "test-task-generate",
         "command": "/workflow:tools:test-task-generate",
-        "description": "Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex",
+        "description": "Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase",
         "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
         "category": "workflow",
         "subcategory": "tools",
@@ -679,41 +712,41 @@
       {
         "name": "animation-extract",
         "command": "/workflow:ui-design:animation-extract",
-        "description": "Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation",
-        "arguments": "[--base-path <path>] [--session <id>] [--urls \"<list>\"] [--mode <auto|interactive>] [--focus \"<types>\"]",
+        "description": "Extract animation and transition patterns from prompt inference and image references for design system documentation",
+        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--focus \"<types>\"] [--interactive] [--refine]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/animation-extract.md"
       },
-      {
-        "name": "batch-generate",
-        "command": "/workflow:ui-design:batch-generate",
-        "description": "Prompt-driven batch UI generation using target-style-centric parallel execution with design token application",
-        "arguments": "[--targets \"<list>\"] [--target-type \"page|component\"] [--device-type \"desktop|mobile|tablet|responsive\"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
-        "category": "workflow",
-        "subcategory": "ui-design",
-        "usage_scenario": "implementation",
-        "difficulty": "Intermediate",
-        "file_path": "workflow/ui-design/batch-generate.md"
-      },
       {
         "name": "capture",
         "command": "/workflow:ui-design:capture",
         "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
-        "arguments": "--url-map \"target:url,...\" [--base-path path] [--session id]",
+        "arguments": "--url-map \"target:url,...\" [--design-id <id>] [--session <id>]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/capture.md"
       },
+      {
+        "name": "workflow:ui-design:codify-style",
+        "command": "/workflow:ui-design:codify-style",
+        "description": "Orchestrator to extract styles from code and generate shareable reference package with preview (automatic file discovery)",
+        "arguments": "<path> [--package-name <name>] [--output-dir <path>] [--overwrite]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/codify-style.md"
+      },
       {
         "name": "explore-auto",
         "command": "/workflow:ui-design:explore-auto",
-        "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution",
-        "arguments": "[--prompt \"<desc>\"] [--images \"<glob>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
+        "description": "Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection",
+        "arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
@@ -724,7 +757,7 @@
         "name": "explore-layers",
         "command": "/workflow:ui-design:explore-layers",
         "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
-        "arguments": "--url <url> --depth <1-5> [--session id] [--base-path path]",
+        "arguments": "--url <url> --depth <1-5> [--design-id <id>] [--session <id>]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
@@ -734,8 +767,8 @@
       {
         "name": "generate",
         "command": "/workflow:ui-design:generate",
-        "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation",
-        "arguments": "[--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+        "description": "Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation",
+        "arguments": "[--design-id <id>] [--session <id>]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "implementation",
@@ -745,8 +778,8 @@
       {
         "name": "imitate-auto",
         "command": "/workflow:ui-design:imitate-auto",
-        "description": "High-speed multi-page UI replication with batch screenshot capture and design token extraction",
-        "arguments": "--url-map \"<map>\" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt \"<desc>\"]",
+        "description": "UI design workflow with direct code/image input for design token extraction and prototype generation",
+        "arguments": "[--input \"<value>\"] [--session <id>]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
@@ -756,8 +789,8 @@
       {
         "name": "workflow:ui-design:import-from-code",
         "command": "/workflow:ui-design:import-from-code",
-        "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis",
-        "arguments": "[--base-path <path>] [--css \\\"<glob>\\\"] [--js \\\"<glob>\\\"] [--scss \\\"<glob>\\\"] [--html \\\"<glob>\\\"] [--style-files \\\"<glob>\\\"] [--session <id>]",
+        "description": "Import design system from code files (CSS/JS/HTML/SCSS) with automatic file discovery and parallel agent analysis",
+        "arguments": "[--design-id <id>] [--session <id>] [--source <path>]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "planning",
@@ -767,19 +800,41 @@
       {
         "name": "layout-extract",
         "command": "/workflow:ui-design:layout-extract",
-        "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis",
-        "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]",
+        "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode",
+        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",
         "difficulty": "Intermediate",
         "file_path": "workflow/ui-design/layout-extract.md"
       },
+      {
+        "name": "list",
+        "command": "/workflow:ui-design:list",
+        "description": "List all available design runs with metadata (session, created time, prototype count)",
+        "arguments": "[--session <id>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "general",
+        "difficulty": "Beginner",
+        "file_path": "workflow/ui-design/list.md"
+      },
+      {
+        "name": "workflow:ui-design:reference-page-generator",
+        "command": "/workflow:ui-design:reference-page-generator",
+        "description": "Generate multi-component reference pages and documentation from design run extraction",
+        "arguments": "[--design-run <path>] [--package-name <name>] [--output-dir <path>]",
+        "category": "workflow",
+        "subcategory": "ui-design",
+        "usage_scenario": "planning",
+        "difficulty": "Intermediate",
+        "file_path": "workflow/ui-design/reference-page-generator.md"
+      },
       {
         "name": "style-extract",
         "command": "/workflow:ui-design:style-extract",
-        "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation",
-        "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--mode <imitate|explore>] [--variants <count>]",
+        "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode",
+        "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
         "category": "workflow",
         "subcategory": "ui-design",
         "usage_scenario": "general",

.claude/skills/command-guide/index/by-use-case.json

@@ -4,7 +4,7 @@
       "name": "analyze",
       "command": "/cli:analyze",
       "description": "Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection",
-      "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] analysis target",
       "category": "cli",
       "subcategory": null,
       "usage_scenario": "analysis",
@@ -15,7 +15,7 @@
       "name": "bug-diagnosis",
       "command": "/cli:mode:bug-diagnosis",
       "description": "Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions",
-      "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description",
       "category": "cli",
       "subcategory": "mode",
       "usage_scenario": "analysis",
@@ -39,7 +39,7 @@
       "name": "chat",
       "command": "/cli:chat",
       "description": "Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference",
-      "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] inquiry",
       "category": "cli",
       "subcategory": null,
       "usage_scenario": "general",
@@ -61,7 +61,7 @@
       "name": "code-analysis",
       "command": "/cli:mode:code-analysis",
       "description": "Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization",
-      "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target",
       "category": "cli",
       "subcategory": "mode",
       "usage_scenario": "general",
@@ -291,8 +291,8 @@
     {
       "name": "animation-extract",
       "command": "/workflow:ui-design:animation-extract",
-      "description": "Extract animation and transition patterns from URLs, CSS, or interactive questioning for design system documentation",
-      "arguments": "[--base-path <path>] [--session <id>] [--urls \"<list>\"] [--mode <auto|interactive>] [--focus \"<types>\"]",
+      "description": "Extract animation and transition patterns from prompt inference and image references for design system documentation",
+      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--focus \"<types>\"] [--interactive] [--refine]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
@@ -303,7 +303,7 @@
       "name": "capture",
       "command": "/workflow:ui-design:capture",
       "description": "Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping",
-      "arguments": "--url-map \"target:url,...\" [--base-path path] [--session id]",
+      "arguments": "--url-map \"target:url,...\" [--design-id <id>] [--session <id>]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
@@ -313,8 +313,8 @@
     {
       "name": "explore-auto",
       "command": "/workflow:ui-design:explore-auto",
-      "description": "Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution",
-      "arguments": "[--prompt \"<desc>\"] [--images \"<glob>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]",
+      "description": "Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection",
+      "arguments": "[--input \"<value>\"] [--targets \"<list>\"] [--target-type \"page|component\"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
@@ -325,7 +325,7 @@
       "name": "explore-layers",
       "command": "/workflow:ui-design:explore-layers",
       "description": "Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer",
-      "arguments": "--url <url> --depth <1-5> [--session id] [--base-path path]",
+      "arguments": "--url <url> --depth <1-5> [--design-id <id>] [--session <id>]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
@@ -335,8 +335,8 @@
     {
       "name": "imitate-auto",
       "command": "/workflow:ui-design:imitate-auto",
-      "description": "High-speed multi-page UI replication with batch screenshot capture and design token extraction",
-      "arguments": "--url-map \"<map>\" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt \"<desc>\"]",
+      "description": "UI design workflow with direct code/image input for design token extraction and prototype generation",
+      "arguments": "[--input \"<value>\"] [--session <id>]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
@@ -346,19 +346,30 @@
     {
       "name": "layout-extract",
       "command": "/workflow:ui-design:layout-extract",
-      "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis",
-      "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]",
+      "description": "Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode",
+      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--targets \"<list>\"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/layout-extract.md"
     },
+    {
+      "name": "list",
+      "command": "/workflow:ui-design:list",
+      "description": "List all available design runs with metadata (session, created time, prototype count)",
+      "arguments": "[--session <id>]",
+      "category": "workflow",
+      "subcategory": "ui-design",
+      "usage_scenario": "general",
+      "difficulty": "Beginner",
+      "file_path": "workflow/ui-design/list.md"
+    },
     {
       "name": "style-extract",
       "command": "/workflow:ui-design:style-extract",
-      "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation",
-      "arguments": "[--base-path <path>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--mode <imitate|explore>] [--variants <count>]",
+      "description": "Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode",
+      "arguments": "[--design-id <id>] [--session <id>] [--images \"<glob>\"] [--urls \"<list>\"] [--prompt \"<desc>\"] [--variants <count>] [--interactive] [--refine]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "general",
@@ -393,7 +404,7 @@
       "name": "execute",
       "command": "/cli:execute",
       "description": "Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection",
-      "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] description or task-id",
       "category": "cli",
       "subcategory": null,
       "usage_scenario": "implementation",
@@ -436,7 +447,7 @@
     {
       "name": "test-cycle-execute",
       "command": "/workflow:test-cycle-execute",
-      "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached",
+      "description": "Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.",
       "arguments": "[--resume-session=\\\"session-id\\\"] [--max-iterations=N]",
       "category": "workflow",
       "subcategory": null,
@@ -458,8 +469,8 @@
     {
       "name": "task-generate-tdd",
       "command": "/workflow:tools:task-generate-tdd",
-      "description": "Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation",
-      "arguments": "--session WFS-session-id [--agent]",
+      "description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation",
+      "arguments": "--session WFS-session-id [--cli-execute]",
       "category": "workflow",
       "subcategory": "tools",
       "usage_scenario": "implementation",
@@ -480,7 +491,7 @@
     {
       "name": "test-task-generate",
       "command": "/workflow:tools:test-task-generate",
-      "description": "Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex",
+      "description": "Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase",
       "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
       "category": "workflow",
       "subcategory": "tools",
@@ -488,22 +499,11 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/tools/test-task-generate.md"
     },
-    {
-      "name": "batch-generate",
-      "command": "/workflow:ui-design:batch-generate",
-      "description": "Prompt-driven batch UI generation using target-style-centric parallel execution with design token application",
-      "arguments": "[--targets \"<list>\"] [--target-type \"page|component\"] [--device-type \"desktop|mobile|tablet|responsive\"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
-      "category": "workflow",
-      "subcategory": "ui-design",
-      "usage_scenario": "implementation",
-      "difficulty": "Intermediate",
-      "file_path": "workflow/ui-design/batch-generate.md"
-    },
     {
       "name": "generate",
       "command": "/workflow:ui-design:generate",
-      "description": "Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation",
-      "arguments": "[--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]",
+      "description": "Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation",
+      "arguments": "[--design-id <id>] [--session <id>]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "implementation",
@@ -527,7 +527,7 @@
       "name": "plan",
       "command": "/cli:mode:plan",
       "description": "Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis",
-      "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
+      "arguments": "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic",
       "category": "cli",
       "subcategory": "mode",
       "usage_scenario": "planning",
@@ -589,11 +589,22 @@
       "difficulty": "Intermediate",
       "file_path": "workflow/brainstorm/ui-designer.md"
     },
+    {
+      "name": "lite-plan",
+      "command": "/workflow:lite-plan",
+      "description": "Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation",
+      "arguments": "[--tool claude|gemini|qwen|codex] [--quick] \\\"task description\\\"|file.md",
+      "category": "workflow",
+      "subcategory": null,
+      "usage_scenario": "planning",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/lite-plan.md"
+    },
     {
       "name": "plan",
       "command": "/workflow:plan",
-      "description": "5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
-      "arguments": "[--agent] [--cli-execute] \\\"text description\\\"|file.md",
+      "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
+      "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
       "category": "workflow",
       "subcategory": null,
       "usage_scenario": "planning",
@@ -604,26 +615,59 @@
       "name": "tdd-plan",
       "command": "/workflow:tdd-plan",
       "description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
-      "arguments": "[--agent] \\\"feature description\\\"|file.md",
+      "arguments": "[--cli-execute] \\\"feature description\\\"|file.md",
       "category": "workflow",
       "subcategory": null,
       "usage_scenario": "planning",
       "difficulty": "Advanced",
       "file_path": "workflow/tdd-plan.md"
     },
+    {
+      "name": "workflow:ui-design:codify-style",
+      "command": "/workflow:ui-design:codify-style",
+      "description": "Orchestrator to extract styles from code and generate shareable reference package with preview (automatic file discovery)",
+      "arguments": "<path> [--package-name <name>] [--output-dir <path>] [--overwrite]",
+      "category": "workflow",
+      "subcategory": "ui-design",
+      "usage_scenario": "planning",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/ui-design/codify-style.md"
+    },
     {
       "name": "workflow:ui-design:import-from-code",
       "command": "/workflow:ui-design:import-from-code",
-      "description": "Import design system from code files (CSS/JS/HTML/SCSS) using parallel agent analysis with final synthesis",
-      "arguments": "[--base-path <path>] [--css \\\"<glob>\\\"] [--js \\\"<glob>\\\"] [--scss \\\"<glob>\\\"] [--html \\\"<glob>\\\"] [--style-files \\\"<glob>\\\"] [--session <id>]",
+      "description": "Import design system from code files (CSS/JS/HTML/SCSS) with automatic file discovery and parallel agent analysis",
+      "arguments": "[--design-id <id>] [--session <id>] [--source <path>]",
       "category": "workflow",
       "subcategory": "ui-design",
       "usage_scenario": "planning",
       "difficulty": "Intermediate",
       "file_path": "workflow/ui-design/import-from-code.md"
+    },
+    {
+      "name": "workflow:ui-design:reference-page-generator",
+      "command": "/workflow:ui-design:reference-page-generator",
+      "description": "Generate multi-component reference pages and documentation from design run extraction",
+      "arguments": "[--design-run <path>] [--package-name <name>] [--output-dir <path>]",
+      "category": "workflow",
+      "subcategory": "ui-design",
+      "usage_scenario": "planning",
+      "difficulty": "Intermediate",
+      "file_path": "workflow/ui-design/reference-page-generator.md"
     }
   ],
   "documentation": [
+    {
+      "name": "code-map-memory",
+      "command": "/memory:code-map-memory",
+      "description": "3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)",
+      "arguments": "\\\"feature-keyword\\\" [--regenerate] [--tool <gemini|qwen>]",
+      "category": "memory",
+      "subcategory": null,
+      "usage_scenario": "documentation",
+      "difficulty": "Intermediate",
+      "file_path": "memory/code-map-memory.md"
+    },
     {
       "name": "docs",
       "command": "/memory:docs",
@@ -657,6 +701,17 @@
       "difficulty": "Intermediate",
       "file_path": "memory/skill-memory.md"
     },
+    {
+      "name": "style-skill-memory",
+      "command": "/memory:style-skill-memory",
+      "description": "Generate SKILL memory package from style reference for easy loading and consistent design system usage",
+      "arguments": "[package-name] [--regenerate]",
+      "category": "memory",
+      "subcategory": null,
+      "usage_scenario": "documentation",
+      "difficulty": "Intermediate",
+      "file_path": "memory/style-skill-memory.md"
+    },
     {
       "name": "workflow-skill-memory",
       "command": "/memory:workflow-skill-memory",

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

@@ -2,8 +2,8 @@
   {
     "name": "plan",
     "command": "/workflow:plan",
-    "description": "5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
-    "arguments": "[--agent] [--cli-execute] \\\"text description\\\"|file.md",
+    "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
+    "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
     "category": "workflow",
     "subcategory": null,
     "usage_scenario": "planning",
@@ -58,7 +58,7 @@
     "name": "analyze",
     "command": "/cli:analyze",
     "description": "Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] analysis target",
     "category": "cli",
     "subcategory": null,
     "usage_scenario": "analysis",
@@ -69,7 +69,7 @@
     "name": "chat",
     "command": "/cli:chat",
     "description": "Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference",
-    "arguments": "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry",
+    "arguments": "[--tool codex|gemini|qwen] [--enhance] inquiry",
     "category": "cli",
     "subcategory": null,
     "usage_scenario": "general",

.claude/skills/command-guide/reference/agents/action-planning-agent.md

@@ -151,9 +151,17 @@ Generate individual `.task/IMPL-*.json` files with:
     "agent": "@code-developer"
   },
   "context": {
-    "requirements": ["from analysis_results"],
-    "focus_paths": ["src/paths"],
-    "acceptance": ["measurable criteria"],
+    "requirements": [
+      "Implement 3 features: [authentication, authorization, session management]",
+      "Create 5 files: [auth.service.ts, auth.controller.ts, auth.middleware.ts, auth.types.ts, auth.test.ts]",
+      "Modify 2 existing functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]"
+    ],
+    "focus_paths": ["src/auth", "tests/auth"],
+    "acceptance": [
+      "3 features implemented: verify by npm test -- auth (exit code 0)",
+      "5 files created: verify by ls src/auth/*.ts | wc -l = 5",
+      "Test coverage >=80%: verify by npm test -- --coverage | grep auth"
+    ],
     "depends_on": ["IMPL-N"],
     "artifacts": [
       {
@@ -181,23 +189,50 @@ Generate individual `.task/IMPL-*.json` files with:
       {
         "step": 1,
         "title": "Load and analyze role analyses",
-        "description": "Load role analyses from artifacts and extract requirements",
-        "modification_points": ["Load role analyses", "Extract requirements and design patterns"],
-        "logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
+        "description": "Load 3 role analysis files and extract quantified requirements",
+        "modification_points": [
+          "Load 3 role analysis files: [system-architect/analysis.md, product-manager/analysis.md, ui-designer/analysis.md]",
+          "Extract 15 requirements from role analyses",
+          "Parse 8 architecture decisions from system-architect analysis"
+        ],
+        "logic_flow": [
+          "Read 3 role analyses from artifacts inventory",
+          "Parse architecture decisions (8 total)",
+          "Extract implementation requirements (15 total)",
+          "Build consolidated requirements list"
+        ],
         "depends_on": [],
         "output": "synthesis_requirements"
       },
       {
         "step": 2,
         "title": "Implement following specification",
-        "description": "Implement task requirements following consolidated role analyses",
-        "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
-        "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
+        "description": "Implement 3 features across 5 files following consolidated role analyses",
+        "modification_points": [
+          "Create 5 new files in src/auth/: [auth.service.ts (180 lines), auth.controller.ts (120 lines), auth.middleware.ts (60 lines), auth.types.ts (40 lines), auth.test.ts (200 lines)]",
+          "Modify 2 functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]",
+          "Implement 3 core features: [JWT authentication, role-based authorization, session management]"
+        ],
+        "logic_flow": [
+          "Apply 15 requirements from [synthesis_requirements]",
+          "Implement 3 features across 5 new files (600 total lines)",
+          "Modify 2 existing functions (30 lines total)",
+          "Write 25 test cases covering all features",
+          "Validate against 3 acceptance criteria"
+        ],
         "depends_on": [1],
         "output": "implementation"
       }
     ],
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
+    "target_files": [
+      "src/auth/auth.service.ts",
+      "src/auth/auth.controller.ts",
+      "src/auth/auth.middleware.ts",
+      "src/auth/auth.types.ts",
+      "tests/auth/auth.test.ts",
+      "src/users/users.service.ts:validateUser:45-60",
+      "src/utils/utils.ts:hashPassword:120-135"
+    ]
   }
 }
 ```
@@ -285,6 +320,35 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Re-scope required**: Maximum 10 tasks hard limit
 - If analysis_results contains >10 tasks, consolidate or request re-scoping
 
+## Quantification Requirements (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
+
+**Core Rules**:
+1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
+2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
+3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
+4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
+5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
+
+**Standard Formats**:
+- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
+- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
+- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
+
+**Validation Checklist** (Apply to every generated task JSON):
+- [ ] Every requirement contains explicit count or enumerated list
+- [ ] Every acceptance criterion is measurable with verification command
+- [ ] Every modification_point specifies exact targets (files/functions/lines)
+- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
+- [ ] Each implementation step has its own acceptance criteria
+
+**Examples**:
+- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"`
+- ❌ BAD: `"Implement new commands"`
+- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"`
+- ❌ BAD: `"All commands implemented successfully"`
+
 ## Quality Standards
 
 **Planning Principles:**
@@ -305,6 +369,7 @@ Use `analysis_results.complexity` or task count to determine structure:
 ## Key Reminders
 
 **ALWAYS:**
+- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations
 - **Use provided context package**: Extract all information from structured context
 - **Respect memory-first rule**: Use provided content (already loaded from memory/file)
 - **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
@@ -313,6 +378,7 @@ Use `analysis_results.complexity` or task count to determine structure:
 - **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
 - **Use session paths**: Construct all paths using provided session_id
 - **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
+- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
 
 **NEVER:**
 - Load files directly (use provided context package instead)

.claude/skills/command-guide/reference/agents/cli-explore-agent.md

@@ -0,0 +1,687 @@
+---
+name: cli-explore-agent
+description: |
+  Read-only code exploration and structural analysis agent specialized in module discovery, dependency mapping, and architecture comprehension using dual-source strategy (Bash rapid scan + Gemini CLI semantic analysis).
+
+  Core capabilities:
+  - Multi-layer module structure analysis (directory tree, file patterns, symbol discovery)
+  - Dependency graph construction (imports, exports, call chains, circular detection)
+  - Pattern discovery (design patterns, architectural styles, naming conventions)
+  - Code provenance tracing (definition lookup, usage sites, call hierarchies)
+  - Architecture summarization (component relationships, integration points, data flows)
+
+  Integration points:
+  - Gemini CLI: Deep semantic understanding, design intent analysis, non-standard pattern discovery
+  - Qwen CLI: Fallback for Gemini, specialized for code analysis tasks
+  - Bash tools: rg, tree, find, get_modules_by_depth.sh for rapid structural scanning
+  - MCP Code Index: Optional integration for enhanced file discovery and search
+
+  Key optimizations:
+  - Dual-source strategy: Bash structural scan (speed) + Gemini semantic analysis (depth)
+  - Language-agnostic analysis with syntax-aware extensions
+  - Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive
+  - Context-aware filtering based on task requirements
+
+color: blue
+---
+
+You are a specialized **CLI Exploration Agent** that executes read-only code analysis tasks autonomously to discover module structures, map dependencies, and understand architectural patterns.
+
+## Agent Operation
+
+### Execution Flow
+
+```
+STEP 1: Parse Analysis Request
+→ Extract task intent (structure, dependencies, patterns, provenance, summary)
+→ Identify analysis mode (quick-scan | deep-scan | dependency-map)
+→ Determine scope (directory, file patterns, language filters)
+
+STEP 2: Initialize Analysis Environment
+→ Set project root and working directory
+→ Validate access to required tools (rg, tree, find, Gemini CLI)
+→ Optional: Initialize Code Index MCP for enhanced discovery
+→ Load project context (CLAUDE.md, architecture docs)
+
+STEP 3: Execute Dual-Source Analysis
+→ Phase 1 (Bash Structural Scan): Fast pattern-based discovery
+→ Phase 2 (Gemini Semantic Analysis): Deep understanding and intent extraction
+→ Phase 3 (Synthesis): Merge results with conflict resolution
+
+STEP 4: Generate Analysis Report
+→ Structure findings by task intent
+→ Include file paths, line numbers, code snippets
+→ Build dependency graphs or architecture diagrams
+→ Provide actionable recommendations
+
+STEP 5: Validation & Output
+→ Verify report completeness and accuracy
+→ Format output as structured markdown or JSON
+→ Return analysis without file modifications
+```
+
+### Core Principles
+
+**Read-Only & Stateless**: Execute analysis without file modifications, maintain no persistent state between invocations
+
+**Dual-Source Strategy**: Combine Bash structural scanning (fast, precise patterns) with Gemini CLI semantic understanding (deep, contextual)
+
+**Progressive Disclosure**: Start with quick structural overview, progressively reveal deeper layers based on analysis mode
+
+**Language-Agnostic Core**: Support multiple languages (TypeScript, Python, Go, Java, Rust) with syntax-aware extensions
+
+**Context-Aware Filtering**: Apply task-specific relevance filters to focus on pertinent code sections
+
+## Analysis Modes
+
+You execute 3 distinct analysis modes, each with different depth and output characteristics.
+
+### Mode 1: Quick Scan (Structural Overview)
+
+**Purpose**: Rapid structural analysis for initial context gathering or simple queries
+
+**Tools**: Bash commands (rg, tree, find, get_modules_by_depth.sh)
+
+**Process**:
+1. **Project Structure**: Run get_modules_by_depth.sh for hierarchical overview
+2. **File Discovery**: Use find/glob patterns to locate relevant files
+3. **Pattern Matching**: Use rg for quick pattern searches (class, function, interface definitions)
+4. **Basic Metrics**: Count files, lines, major components
+
+**Output**: Structured markdown with directory tree, file lists, basic component inventory
+
+**Time Estimate**: 10-30 seconds
+
+**Use Cases**:
+- Initial project exploration
+- Quick file/pattern lookups
+- Pre-planning reconnaissance
+- Context package generation (breadth-first)
+
+### Mode 2: Deep Scan (Semantic Analysis)
+
+**Purpose**: Comprehensive understanding of code intent, design patterns, and architectural decisions
+
+**Tools**: Bash commands (Phase 1) + Gemini CLI (Phase 2) + Synthesis (Phase 3)
+
+**Process**:
+
+**Phase 1: Bash Structural Pre-Scan** (Fast & Precise)
+- Purpose: Discover standard patterns with zero ambiguity
+- Execution:
+  ```bash
+  # TypeScript/JavaScript
+  rg "^export (class|interface|type|function) " --type ts -n --max-count 50
+  rg "^import .* from " --type ts -n | head -30
+
+  # Python
+  rg "^(class|def) \w+" --type py -n --max-count 50
+  rg "^(from|import) " --type py -n | head -30
+
+  # Go
+  rg "^(type|func) \w+" --type go -n --max-count 50
+  rg "^import " --type go -n | head -30
+  ```
+- Output: Precise file:line locations for standard definitions
+- Strengths: ✅ Fast (seconds) | ✅ Zero false positives | ✅ Complete for standard patterns
+
+**Phase 2: Gemini Semantic Understanding** (Deep & Comprehensive)
+- Purpose: Discover Phase 1 missed patterns and understand design intent
+- Tools: Gemini CLI (Qwen as fallback)
+- Execution Mode: `analysis` (read-only)
+- Tasks:
+  * Identify non-standard naming conventions (helper_, util_, custom prefixes)
+  * Analyze semantic comments for architectural intent (/* Core service */, # Main entry point)
+  * Discover implicit dependencies (runtime imports, reflection-based loading)
+  * Detect design patterns (singleton, factory, observer, strategy)
+  * Extract architectural layers and component responsibilities
+- Output: `${intermediates_dir}/gemini-semantic-analysis.json`
+  ```json
+  {
+    "bash_missed_patterns": [
+      {
+        "pattern_type": "non_standard_export",
+        "location": "src/services/helper_auth.ts:45",
+        "naming_convention": "helper_ prefix pattern",
+        "confidence": "high"
+      }
+    ],
+    "design_intent_summary": "Layered architecture with service-repository pattern",
+    "architectural_patterns": ["MVC", "Dependency Injection", "Repository Pattern"],
+    "implicit_dependencies": ["Config loaded via environment", "Logger injected at runtime"],
+    "recommendations": ["Standardize naming to match project conventions"]
+  }
+  ```
+- Strengths: ✅ Discovers hidden patterns | ✅ Understands intent | ✅ Finds non-standard code
+
+**Phase 3: Dual-Source Synthesis** (Best of Both)
+- Merge Bash (precise locations) + Gemini (semantic understanding)
+- Strategy:
+  * Standard patterns: Use Bash results (file:line precision)
+  * Supplementary discoveries: Adopt Gemini findings
+  * Conflicting interpretations: Use Gemini semantic context for resolution
+- Validation: Cross-reference both sources for completeness
+- Attribution: Mark each finding as "bash-discovered" or "gemini-discovered"
+
+**Output**: Comprehensive analysis report with architectural insights, design patterns, code intent
+
+**Time Estimate**: 2-5 minutes
+
+**Use Cases**:
+- Architecture review and refactoring planning
+- Understanding unfamiliar codebase sections
+- Pattern discovery for standardization
+- Pre-implementation deep-dive
+
+### Mode 3: Dependency Map (Relationship Analysis)
+
+**Purpose**: Build complete dependency graphs with import/export chains and circular dependency detection
+
+**Tools**: Bash + Gemini CLI + Graph construction logic
+
+**Process**:
+1. **Direct Dependencies** (Bash):
+   ```bash
+   # Extract all imports
+   rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1' -n
+
+   # Extract all exports
+   rg "^export .* (class|function|const|type|interface) (\w+)" --type ts -o -r '$2' -n
+   ```
+
+2. **Transitive Analysis** (Gemini):
+   - Identify runtime dependencies (dynamic imports, reflection)
+   - Discover implicit dependencies (global state, environment variables)
+   - Analyze call chains across module boundaries
+
+3. **Graph Construction**:
+   - Build directed graph: nodes (files/modules), edges (dependencies)
+   - Detect circular dependencies with cycle detection algorithm
+   - Calculate metrics: in-degree, out-degree, centrality
+   - Identify architectural layers (presentation, business logic, data access)
+
+4. **Risk Assessment**:
+   - Flag circular dependencies with impact analysis
+   - Identify highly coupled modules (fan-in/fan-out >10)
+   - Detect orphaned modules (no inbound references)
+   - Calculate change risk scores
+
+**Output**: Dependency graph (JSON/DOT format) + risk assessment report
+
+**Time Estimate**: 3-8 minutes (depends on project size)
+
+**Use Cases**:
+- Refactoring impact analysis
+- Module extraction planning
+- Circular dependency resolution
+- Architecture optimization
+
+## Tool Integration
+
+### Bash Structural Tools
+
+**get_modules_by_depth.sh**:
+- Purpose: Generate hierarchical project structure
+- Usage: `bash ~/.claude/scripts/get_modules_by_depth.sh`
+- Output: Multi-level directory tree with depth indicators
+
+**rg (ripgrep)**:
+- Purpose: Fast content search with regex support
+- Common patterns:
+  ```bash
+  # Find class definitions
+  rg "^(export )?class \w+" --type ts -n
+
+  # Find function definitions
+  rg "^(export )?(function|const) \w+\s*=" --type ts -n
+
+  # Find imports
+  rg "^import .* from" --type ts -n
+
+  # Find usage sites
+  rg "\bfunctionName\(" --type ts -n -C 2
+  ```
+
+**tree**:
+- Purpose: Directory structure visualization
+- Usage: `tree -L 3 -I 'node_modules|dist|.git'`
+
+**find**:
+- Purpose: File discovery by name patterns
+- Usage: `find . -name "*.ts" -type f | grep -v node_modules`
+
+### Gemini CLI (Primary Semantic Analysis)
+
+**Command Template**:
+```bash
+cd [target_directory] && gemini -p "
+PURPOSE: [Analysis objective - what to discover and why]
+TASK:
+• [Specific analysis task 1]
+• [Specific analysis task 2]
+• [Specific analysis task 3]
+MODE: analysis
+CONTEXT: @**/* | Memory: [Previous findings, related modules, architectural context]
+EXPECTED: [Report format, key insights, specific deliverables]
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on [scope constraints] | analysis=READ-ONLY
+" -m gemini-2.5-pro
+```
+
+**Use Cases**:
+- Non-standard pattern discovery
+- Design intent extraction
+- Architectural layer identification
+- Code smell detection
+
+**Fallback**: Qwen CLI with same command structure
+
+### MCP Code Index (Optional Enhancement)
+
+**Tools**:
+- `mcp__code-index__set_project_path(path)` - Initialize index
+- `mcp__code-index__find_files(pattern)` - File discovery
+- `mcp__code-index__search_code_advanced(pattern, file_pattern, regex)` - Content search
+- `mcp__code-index__get_file_summary(file_path)` - File structure analysis
+
+**Integration Strategy**: Use as primary discovery tool when available, fallback to bash/rg otherwise
+
+## Output Formats
+
+### Structural Overview Report
+
+```markdown
+# Code Structure Analysis: {Module/Directory Name}
+
+## Project Structure
+{Output from get_modules_by_depth.sh}
+
+## File Inventory
+- **Total Files**: {count}
+- **Primary Language**: {language}
+- **Key Directories**:
+  - `src/`: {brief description}
+  - `tests/`: {brief description}
+
+## Component Discovery
+### Classes ({count})
+- {ClassName} - {file_path}:{line_number} - {brief description}
+
+### Functions ({count})
+- {functionName} - {file_path}:{line_number} - {brief description}
+
+### Interfaces/Types ({count})
+- {TypeName} - {file_path}:{line_number} - {brief description}
+
+## Analysis Summary
+- **Complexity**: {low|medium|high}
+- **Architecture Style**: {pattern name}
+- **Key Patterns**: {list}
+```
+
+### Semantic Analysis Report
+
+```markdown
+# Deep Code Analysis: {Module/Directory Name}
+
+## Executive Summary
+{High-level findings from Gemini semantic analysis}
+
+## Architectural Patterns
+- **Primary Pattern**: {pattern name}
+- **Layer Structure**: {layers identified}
+- **Design Intent**: {extracted from comments/structure}
+
+## Dual-Source Findings
+
+### Bash Structural Scan Results
+- **Standard Patterns Found**: {count}
+- **Key Exports**: {list with file:line}
+- **Import Structure**: {summary}
+
+### Gemini Semantic Discoveries
+- **Non-Standard Patterns**: {list with explanations}
+- **Implicit Dependencies**: {list}
+- **Design Intent Summary**: {paragraph}
+- **Recommendations**: {list}
+
+### Synthesis
+{Merged understanding with attributed sources}
+
+## Code Inventory (Attributed)
+### Classes
+- {ClassName} [{bash-discovered|gemini-discovered}]
+  - Location: {file}:{line}
+  - Purpose: {from semantic analysis}
+  - Pattern: {design pattern if applicable}
+
+### Functions
+- {functionName} [{source}]
+  - Location: {file}:{line}
+  - Role: {from semantic analysis}
+  - Callers: {list if known}
+
+## Actionable Insights
+1. {Finding with recommendation}
+2. {Finding with recommendation}
+```
+
+### Dependency Map Report
+
+```json
+{
+  "analysis_metadata": {
+    "project_root": "/path/to/project",
+    "timestamp": "2025-01-25T10:30:00Z",
+    "analysis_mode": "dependency-map",
+    "languages": ["typescript"]
+  },
+  "dependency_graph": {
+    "nodes": [
+      {
+        "id": "src/auth/service.ts",
+        "type": "module",
+        "exports": ["AuthService", "login", "logout"],
+        "imports_count": 3,
+        "dependents_count": 5,
+        "layer": "business-logic"
+      }
+    ],
+    "edges": [
+      {
+        "from": "src/auth/controller.ts",
+        "to": "src/auth/service.ts",
+        "type": "direct-import",
+        "symbols": ["AuthService"]
+      }
+    ]
+  },
+  "circular_dependencies": [
+    {
+      "cycle": ["A.ts", "B.ts", "C.ts", "A.ts"],
+      "risk_level": "high",
+      "impact": "Refactoring A.ts requires changes to B.ts and C.ts"
+    }
+  ],
+  "risk_assessment": {
+    "high_coupling": [
+      {
+        "module": "src/utils/helpers.ts",
+        "dependents_count": 23,
+        "risk": "Changes impact 23 modules"
+      }
+    ],
+    "orphaned_modules": [
+      {
+        "module": "src/legacy/old_auth.ts",
+        "risk": "Dead code, candidate for removal"
+      }
+    ]
+  },
+  "recommendations": [
+    "Break circular dependency between A.ts and B.ts by introducing interface abstraction",
+    "Refactor helpers.ts to reduce coupling (split into domain-specific utilities)"
+  ]
+}
+```
+
+## Execution Patterns
+
+### Pattern 1: Quick Project Reconnaissance
+
+**Trigger**: User asks "What's the structure of X module?" or "Where is X defined?"
+
+**Execution**:
+```
+1. Run get_modules_by_depth.sh for structural overview
+2. Use rg to find definitions: rg "class|function|interface X" -n
+3. Generate structural overview report
+4. Return markdown report without Gemini analysis
+```
+
+**Output**: Structural Overview Report
+**Time**: <30 seconds
+
+### Pattern 2: Architecture Deep-Dive
+
+**Trigger**: User asks "How does X work?" or "Explain the architecture of X"
+
+**Execution**:
+```
+1. Phase 1 (Bash): Scan for standard patterns (classes, functions, imports)
+2. Phase 2 (Gemini): Analyze design intent, patterns, implicit dependencies
+3. Phase 3 (Synthesis): Merge results with attribution
+4. Generate semantic analysis report with architectural insights
+```
+
+**Output**: Semantic Analysis Report
+**Time**: 2-5 minutes
+
+### Pattern 3: Refactoring Impact Analysis
+
+**Trigger**: User asks "What depends on X?" or "Impact of changing X?"
+
+**Execution**:
+```
+1. Build dependency graph using rg for direct dependencies
+2. Use Gemini to discover runtime/implicit dependencies
+3. Detect circular dependencies and high-coupling modules
+4. Calculate change risk scores
+5. Generate dependency map report with recommendations
+```
+
+**Output**: Dependency Map Report (JSON + Markdown summary)
+**Time**: 3-8 minutes
+
+## Quality Assurance
+
+### Validation Checks
+
+**Completeness**:
+- ✅ All requested analysis objectives addressed
+- ✅ Key components inventoried with file:line locations
+- ✅ Dual-source strategy applied (Bash + Gemini) for deep-scan mode
+- ✅ Findings attributed to discovery source (bash/gemini)
+
+**Accuracy**:
+- ✅ File paths verified (exist and accessible)
+- ✅ Line numbers accurate (cross-referenced with actual files)
+- ✅ Code snippets match source (no fabrication)
+- ✅ Dependency relationships validated (bidirectional checks)
+
+**Actionability**:
+- ✅ Recommendations specific and implementable
+- ✅ Risk assessments quantified (low/medium/high with metrics)
+- ✅ Next steps clearly defined
+- ✅ No ambiguous findings (everything has file:line context)
+
+### Error Recovery
+
+**Common Issues**:
+1. **Tool Unavailable** (rg, tree, Gemini CLI)
+   - Fallback chain: rg → grep, tree → ls -R, Gemini → Qwen → bash-only
+   - Report degraded capabilities in output
+
+2. **Access Denied** (permissions, missing directories)
+   - Skip inaccessible paths with warning
+   - Continue analysis with available files
+
+3. **Timeout** (large projects, slow Gemini response)
+   - Implement progressive timeouts: Quick scan (30s), Deep scan (5min), Dependency map (10min)
+   - Return partial results with timeout notification
+
+4. **Ambiguous Patterns** (conflicting interpretations)
+   - Use Gemini semantic analysis as tiebreaker
+   - Document uncertainty in report with attribution
+
+## Integration with Other Agents
+
+### As Service Provider (Called by Others)
+
+**Planning Agents** (`action-planning-agent`, `conceptual-planning-agent`):
+- **Use Case**: Pre-planning reconnaissance to understand existing code
+- **Input**: Task description + focus areas
+- **Output**: Structural overview + dependency analysis
+- **Flow**: Planning agent → CLI explore agent (quick-scan) → Context for planning
+
+**Execution Agents** (`code-developer`, `cli-execution-agent`):
+- **Use Case**: Refactoring impact analysis before code modifications
+- **Input**: Target files/functions to modify
+- **Output**: Dependency map + risk assessment
+- **Flow**: Execution agent → CLI explore agent (dependency-map) → Safe modification strategy
+
+**UI Design Agent** (`ui-design-agent`):
+- **Use Case**: Discover existing UI components and design tokens
+- **Input**: Component directory + file patterns
+- **Output**: Component inventory + styling patterns
+- **Flow**: UI agent delegates structure analysis to CLI explore agent
+
+### As Consumer (Calls Others)
+
+**Context Search Agent** (`context-search-agent`):
+- **Use Case**: Get project-wide context before analysis
+- **Flow**: CLI explore agent → Context search agent → Enhanced analysis with full context
+
+**MCP Tools**:
+- **Use Case**: Enhanced file discovery and search capabilities
+- **Flow**: CLI explore agent → Code Index MCP → Faster pattern discovery
+
+## Key Reminders
+
+### ALWAYS
+
+**Analysis Integrity**: ✅ Read-only operations | ✅ No file modifications | ✅ No state persistence | ✅ Verify file paths before reporting
+
+**Dual-Source Strategy** (Deep-Scan Mode): ✅ Execute Bash scan first (Phase 1) | ✅ Run Gemini analysis (Phase 2) | ✅ Synthesize with attribution (Phase 3) | ✅ Cross-validate findings
+
+**Tool Chain**: ✅ Prefer Code Index MCP when available | ✅ Fallback to rg/bash tools | ✅ Use Gemini CLI for semantic analysis (Qwen as fallback) | ✅ Handle tool unavailability gracefully
+
+**Output Standards**: ✅ Include file:line locations | ✅ Attribute findings to source (bash/gemini) | ✅ Provide actionable recommendations | ✅ Use standardized report formats
+
+**Mode Selection**: ✅ Match mode to task intent (quick-scan for simple queries, deep-scan for architecture, dependency-map for refactoring) | ✅ Communicate mode choice to user
+
+### NEVER
+
+**File Operations**: ❌ Modify files | ❌ Create/delete files | ❌ Execute write operations | ❌ Run build/test commands that change state
+
+**Analysis Scope**: ❌ Exceed requested scope | ❌ Analyze unrelated modules | ❌ Include irrelevant findings | ❌ Mix multiple unrelated queries
+
+**Output Quality**: ❌ Fabricate code snippets | ❌ Guess file locations | ❌ Report unverified dependencies | ❌ Provide ambiguous recommendations without context
+
+**Tool Usage**: ❌ Skip Bash scan in deep-scan mode | ❌ Use Gemini for quick-scan mode (overkill) | ❌ Ignore fallback chain when tool fails | ❌ Proceed with incomplete tool setup
+
+---
+
+## Command Templates by Language
+
+### TypeScript/JavaScript
+
+```bash
+# Quick structural scan
+rg "^export (class|interface|type|function|const) " --type ts -n
+
+# Find component definitions (React)
+rg "^export (default )?(function|const) \w+.*=.*\(" --type tsx -n
+
+# Find imports
+rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1'
+
+# Find test files
+find . -name "*.test.ts" -o -name "*.spec.ts" | grep -v node_modules
+```
+
+### Python
+
+```bash
+# Find class definitions
+rg "^class \w+.*:" --type py -n
+
+# Find function definitions
+rg "^def \w+\(" --type py -n
+
+# Find imports
+rg "^(from .* import|import )" --type py -n
+
+# Find test files
+find . -name "test_*.py" -o -name "*_test.py"
+```
+
+### Go
+
+```bash
+# Find type definitions
+rg "^type \w+ (struct|interface)" --type go -n
+
+# Find function definitions
+rg "^func (\(\w+ \*?\w+\) )?\w+\(" --type go -n
+
+# Find imports
+rg "^import \(" --type go -A 10
+
+# Find test files
+find . -name "*_test.go"
+```
+
+### Java
+
+```bash
+# Find class definitions
+rg "^(public |private |protected )?(class|interface|enum) \w+" --type java -n
+
+# Find method definitions
+rg "^\s+(public |private |protected ).*\w+\(.*\)" --type java -n
+
+# Find imports
+rg "^import .*;" --type java -n
+
+# Find test files
+find . -name "*Test.java" -o -name "*Tests.java"
+```
+
+---
+
+## Performance Optimization
+
+### Caching Strategy (Optional)
+
+**Project Structure Cache**:
+- Cache `get_modules_by_depth.sh` output for 1 hour
+- Invalidate on file system changes (watch .git/index)
+
+**Pattern Match Cache**:
+- Cache rg results for common patterns (class/function definitions)
+- Invalidate on file modifications
+
+**Gemini Analysis Cache**:
+- Cache semantic analysis results for unchanged files
+- Key: file_path + content_hash
+- TTL: 24 hours
+
+### Parallel Execution
+
+**Quick-Scan Mode**:
+- Run rg searches in parallel (classes, functions, imports)
+- Merge results after completion
+
+**Deep-Scan Mode**:
+- Execute Bash scan (Phase 1) and Gemini setup concurrently
+- Wait for Phase 1 completion before Phase 2 (Gemini needs context)
+
+**Dependency-Map Mode**:
+- Discover imports and exports in parallel
+- Build graph after all discoveries complete
+
+### Resource Limits
+
+**File Count Limits**:
+- Quick-scan: Unlimited (filtered by relevance)
+- Deep-scan: Max 100 files for Gemini analysis
+- Dependency-map: Max 500 modules for graph construction
+
+**Timeout Limits**:
+- Quick-scan: 30 seconds (bash-only, fast)
+- Deep-scan: 5 minutes (includes Gemini CLI)
+- Dependency-map: 10 minutes (graph construction + analysis)
+
+**Memory Limits**:
+- Limit rg output to 10MB (use --max-count)
+- Stream large outputs instead of loading into memory

.claude/skills/command-guide/reference/agents/cli-planning-agent.md

@@ -0,0 +1,553 @@
+---
+name: cli-planning-agent
+description: |
+  Specialized agent for executing CLI analysis tools (Gemini/Qwen) and dynamically generating task JSON files based on analysis results. Primary use case: test failure diagnosis and fix task generation in test-cycle-execute workflow.
+
+  Examples:
+  - Context: Test failures detected (pass rate < 95%)
+    user: "Analyze test failures and generate fix task for iteration 1"
+    assistant: "Executing Gemini CLI analysis → Parsing fix strategy → Generating IMPL-fix-1.json"
+    commentary: Agent encapsulates CLI execution + result parsing + task generation
+
+  - Context: Coverage gap analysis
+    user: "Analyze coverage gaps and generate补充test task"
+    assistant: "Executing CLI analysis for uncovered code paths → Generating test supplement task"
+    commentary: Agent handles both analysis and task JSON generation autonomously
+color: purple
+---
+
+You are a specialized execution agent that bridges CLI analysis tools with task generation. You execute Gemini/Qwen CLI commands for failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution.
+
+## Core Responsibilities
+
+1. **Execute CLI Analysis**: Run Gemini/Qwen with appropriate templates and context
+2. **Parse CLI Results**: Extract structured information (fix strategies, root causes, modification points)
+3. **Generate Task JSONs**: Create IMPL-fix-N.json or IMPL-supplement-N.json dynamically
+4. **Save Analysis Reports**: Store detailed CLI output as iteration-N-analysis.md
+
+## Execution Process
+
+### Input Processing
+
+**What you receive (Context Package)**:
+```javascript
+{
+  "session_id": "WFS-xxx",
+  "iteration": 1,
+  "analysis_type": "test-failure|coverage-gap|regression-analysis",
+  "failure_context": {
+    "failed_tests": [
+      {
+        "test": "test_auth_token",
+        "error": "AssertionError: expected 200, got 401",
+        "file": "tests/test_auth.py",
+        "line": 45,
+        "criticality": "high",
+        "test_type": "integration"  // ← NEW: L0: static, L1: unit, L2: integration, L3: e2e
+      }
+    ],
+    "error_messages": ["error1", "error2"],
+    "test_output": "full raw test output...",
+    "pass_rate": 85.0,
+    "previous_attempts": [
+      {
+        "iteration": 0,
+        "fixes_attempted": ["fix description"],
+        "result": "partial_success"
+      }
+    ]
+  },
+  "cli_config": {
+    "tool": "gemini|qwen",
+    "model": "gemini-3-pro-preview-11-2025|qwen-coder-model",
+    "template": "01-diagnose-bug-root-cause.txt",
+    "timeout": 2400000,
+    "fallback": "qwen"
+  },
+  "task_config": {
+    "agent": "@test-fix-agent",
+    "type": "test-fix-iteration",
+    "max_iterations": 5,
+    "use_codex": false
+  }
+}
+```
+
+### Execution Flow (Three-Phase)
+
+```
+Phase 1: CLI Analysis Execution
+1. Validate context package and extract failure context
+2. Construct CLI command with appropriate template
+3. Execute Gemini/Qwen CLI tool
+4. Handle errors and fallback to alternative tool if needed
+5. Save raw CLI output to .process/iteration-N-cli-output.txt
+
+Phase 2: Results Parsing & Strategy Extraction
+1. Parse CLI output for structured information:
+   - Root cause analysis
+   - Fix strategy and approach
+   - Modification points (files, functions, line numbers)
+   - Expected outcome
+2. Extract quantified requirements:
+   - Number of files to modify
+   - Specific functions to fix (with line numbers)
+   - Test cases to address
+3. Generate structured analysis report (iteration-N-analysis.md)
+
+Phase 3: Task JSON Generation
+1. Load task JSON template (defined below)
+2. Populate template with parsed CLI results
+3. Add iteration context and previous attempts
+4. Write task JSON to .workflow/{session}/.task/IMPL-fix-N.json
+5. Return success status and task ID to orchestrator
+```
+
+## Core Functions
+
+### 1. CLI Command Construction
+
+**Template-Based Approach with Test Layer Awareness**:
+```bash
+cd {project_root} && {cli_tool} -p "
+PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration}
+TASK:
+• Review {failed_tests.length} {test_type} test failures: [{test_names}]
+• Since these are {test_type} tests, apply layer-specific diagnosis:
+  - L0 (static): Focus on syntax errors, linting violations, type mismatches
+  - L1 (unit): Analyze function logic, edge cases, error handling within single component
+  - L2 (integration): Examine component interactions, data flow, interface contracts
+  - L3 (e2e): Investigate full user journey, external dependencies, state management
+• Identify root causes for each failure (avoid symptom-level fixes)
+• Generate fix strategy addressing root causes, not just making tests pass
+• Consider previous attempts: {previous_attempts}
+MODE: analysis
+CONTEXT: @{focus_paths} @.process/test-results.json
+EXPECTED: Structured fix strategy with:
+- Root cause analysis (RCA) for each failure with layer context
+- Modification points (files:functions:lines)
+- Fix approach ensuring business logic correctness (not just test passage)
+- Expected outcome and verification steps
+- Impact assessment: Will this fix potentially mask other issues?
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
+- For {test_type} tests: {layer_specific_guidance}
+- Avoid 'surgical fixes' that mask underlying issues
+- Provide specific line numbers for modifications
+- Consider previous iteration failures
+- Validate fix doesn't introduce new vulnerabilities
+- analysis=READ-ONLY
+" -m {model} {timeout_flag}
+```
+
+**Layer-Specific Guidance Injection**:
+```javascript
+const layerGuidance = {
+  "static": "Fix the actual code issue (syntax, type), don't disable linting rules",
+  "unit": "Ensure function logic is correct; avoid changing assertions to match wrong behavior",
+  "integration": "Analyze full call stack and data flow across components; fix interaction issues, not symptoms",
+  "e2e": "Investigate complete user journey and state transitions; ensure fix doesn't break user experience"
+};
+
+const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
+```
+
+**Error Handling & Fallback**:
+```javascript
+try {
+  result = executeCLI("gemini", config);
+} catch (error) {
+  if (error.code === 429 || error.code === 404) {
+    console.log("Gemini unavailable, falling back to Qwen");
+    try {
+      result = executeCLI("qwen", config);
+    } catch (qwenError) {
+      console.error("Both Gemini and Qwen failed");
+      // Return minimal analysis with basic fix strategy
+      return {
+        status: "degraded",
+        message: "CLI analysis failed, using fallback strategy",
+        fix_strategy: generateBasicFixStrategy(failure_context)
+      };
+    }
+  } else {
+    throw error;
+  }
+}
+```
+
+**Fallback Strategy (When All CLI Tools Fail)**:
+- Generate basic fix task based on error patterns matching
+- Use previous successful fix patterns from fix-history.json
+- Limit to simple, low-risk fixes (add null checks, fix typos)
+- Mark task with `meta.analysis_quality: "degraded"` flag
+- Orchestrator will treat degraded analysis with caution (may skip iteration)
+
+### 2. CLI Output Parsing
+
+**Expected CLI Output Structure** (from bug diagnosis template):
+```markdown
+## 故障现象描述
+- 观察行为: [actual behavior]
+- 预期行为: [expected behavior]
+
+## 根本原因分析 (RCA)
+- 问题定位: [specific issue location]
+- 触发条件: [conditions that trigger the issue]
+- 影响范围: [affected scope]
+
+## 涉及文件概览
+- src/auth/auth.service.ts (lines 45-60): validateToken function
+- src/middleware/auth.middleware.ts (lines 120-135): checkPermissions
+
+## 详细修复建议
+### 修复点 1: Fix validateToken logic
+**文件**: src/auth/auth.service.ts
+**函数**: validateToken (lines 45-60)
+**修改内容**:
+```diff
+- if (token.expired) return false;
++ if (token.exp < Date.now()) return null;
+```
+
+**理由**: [explanation]
+
+## 验证建议
+- Run: npm test -- tests/test_auth.py::test_auth_token
+- Expected: Test passes with status code 200
+```
+
+**Parsing Logic**:
+```javascript
+const parsedResults = {
+  root_causes: extractSection("根本原因分析"),
+  modification_points: extractModificationPoints(),
+  fix_strategy: {
+    approach: extractSection("详细修复建议"),
+    files: extractFilesList(),
+    expected_outcome: extractSection("验证建议")
+  }
+};
+```
+
+### 3. Task JSON Generation (Template Definition)
+
+**Task JSON Template for IMPL-fix-N** (Simplified):
+```json
+{
+  "id": "IMPL-fix-{iteration}",
+  "title": "Fix {test_type} test failures - Iteration {iteration}: {fix_summary}",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix-iteration",
+    "agent": "@test-fix-agent",
+    "iteration": "{iteration}",
+    "test_layer": "{dominant_test_type}",
+    "analysis_report": ".process/iteration-{iteration}-analysis.md",
+    "cli_output": ".process/iteration-{iteration}-cli-output.txt",
+    "max_iterations": "{task_config.max_iterations}",
+    "use_codex": "{task_config.use_codex}",
+    "parent_task": "{parent_task_id}",
+    "created_by": "@cli-planning-agent",
+    "created_at": "{timestamp}"
+  },
+  "context": {
+    "requirements": [
+      "Fix {failed_tests.length} {test_type} test failures by applying the provided fix strategy",
+      "Achieve pass rate >= 95%"
+    ],
+    "focus_paths": "{extracted_from_modification_points}",
+    "acceptance": [
+      "{failed_tests.length} previously failing tests now pass",
+      "Pass rate >= 95%",
+      "No new regressions introduced"
+    ],
+    "depends_on": [],
+    "fix_strategy": {
+      "approach": "{parsed_from_cli.fix_strategy.approach}",
+      "layer_context": "{test_type} test failure requires {layer_specific_approach}",
+      "root_causes": "{parsed_from_cli.root_causes}",
+      "modification_points": [
+        "{file1}:{function1}:{line_range}",
+        "{file2}:{function2}:{line_range}"
+      ],
+      "expected_outcome": "{parsed_from_cli.fix_strategy.expected_outcome}",
+      "verification_steps": "{parsed_from_cli.verification_steps}",
+      "quality_assurance": {
+        "avoids_symptom_fix": true,
+        "addresses_root_cause": true,
+        "validates_business_logic": true
+      }
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_analysis_context",
+        "action": "Load CLI analysis report for full failure context if needed",
+        "commands": [
+          "Read({meta.analysis_report})"
+        ],
+        "output_to": "full_failure_analysis",
+        "note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Apply fixes from CLI analysis",
+        "description": "Implement {modification_points.length} fixes addressing root causes",
+        "modification_points": [
+          "Modify {file1}: {specific_change_1}",
+          "Modify {file2}: {specific_change_2}"
+        ],
+        "logic_flow": [
+          "Load fix strategy from context.fix_strategy",
+          "Apply fixes to {modification_points.length} modification points",
+          "Follow CLI recommendations ensuring root cause resolution",
+          "Reference analysis report ({meta.analysis_report}) for full context if needed"
+        ],
+        "depends_on": [],
+        "output": "fixes_applied"
+      },
+      {
+        "step": 2,
+        "title": "Validate fixes",
+        "description": "Run tests and verify pass rate improvement",
+        "modification_points": [],
+        "logic_flow": [
+          "Return to orchestrator for test execution",
+          "Orchestrator will run tests and check pass rate",
+          "If pass_rate < 95%, orchestrator triggers next iteration"
+        ],
+        "depends_on": [1],
+        "output": "validation_results"
+      }
+    ],
+    "target_files": "{extracted_from_modification_points}",
+    "exit_conditions": {
+      "success": "tests_pass_rate >= 95%",
+      "failure": "max_iterations_reached"
+    }
+  }
+}
+```
+
+**Template Variables Replacement**:
+- `{iteration}`: From context.iteration
+- `{test_type}`: Dominant test type from failed_tests (e.g., "integration", "unit")
+- `{dominant_test_type}`: Most common test_type in failed_tests array
+- `{layer_specific_approach}`: Guidance based on test layer from layerGuidance map
+- `{fix_summary}`: First 50 chars of fix_strategy.approach
+- `{failed_tests.length}`: Count of failures
+- `{modification_points.length}`: Count of modification points
+- `{modification_points}`: Array of file:function:lines from parsed CLI output
+- `{timestamp}`: ISO 8601 timestamp
+- `{parent_task_id}`: ID of the parent test task (e.g., "IMPL-002")
+- `{file1}`, `{file2}`, etc.: Specific file paths from modification_points
+- `{specific_change_1}`, etc.: Change descriptions for each modification point
+
+### 4. Analysis Report Generation
+
+**Structure of iteration-N-analysis.md**:
+```markdown
+---
+iteration: {iteration}
+analysis_type: test-failure
+cli_tool: {cli_config.tool}
+model: {cli_config.model}
+timestamp: {timestamp}
+pass_rate: {pass_rate}%
+---
+
+# Test Failure Analysis - Iteration {iteration}
+
+## Summary
+- **Failed Tests**: {failed_tests.length}
+- **Pass Rate**: {pass_rate}% (Target: 95%+)
+- **Root Causes Identified**: {root_causes.length}
+- **Modification Points**: {modification_points.length}
+
+## Failed Tests Details
+{foreach failed_test}
+### {test.test}
+- **Error**: {test.error}
+- **File**: {test.file}:{test.line}
+- **Criticality**: {test.criticality}
+{endforeach}
+
+## Root Cause Analysis
+{CLI output: 根本原因分析 section}
+
+## Fix Strategy
+{CLI output: 详细修复建议 section}
+
+## Modification Points
+{foreach modification_point}
+- `{file}:{function}:{line_range}` - {change_description}
+{endforeach}
+
+## Expected Outcome
+{CLI output: 验证建议 section}
+
+## Previous Attempts
+{foreach previous_attempt}
+- **Iteration {attempt.iteration}**: {attempt.result}
+  - Fixes: {attempt.fixes_attempted}
+{endforeach}
+
+## CLI Raw Output
+See: `.process/iteration-{iteration}-cli-output.txt`
+```
+
+## Quality Standards
+
+### CLI Execution Standards
+- **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
+- **Fallback Chain**: Gemini → Qwen (if Gemini fails with 429/404)
+- **Error Context**: Include full error details in failure reports
+- **Output Preservation**: Save raw CLI output for debugging
+
+### Task JSON Standards
+- **Quantification**: All requirements must include counts and explicit lists
+- **Specificity**: Modification points must have file:function:line format
+- **Measurability**: Acceptance criteria must include verification commands
+- **Traceability**: Link to analysis reports and CLI output files
+
+### Analysis Report Standards
+- **Structured Format**: Use consistent markdown sections
+- **Metadata**: Include YAML frontmatter with key metrics
+- **Completeness**: Capture all CLI output sections
+- **Cross-References**: Link to test-results.json and CLI output files
+
+## Key Reminders
+
+**ALWAYS:**
+- **Validate context package**: Ensure all required fields present before CLI execution
+- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
+- **Parse CLI output structurally**: Extract specific sections (RCA, 修复建议, 验证建议)
+- **Save complete analysis report**: Write full context to iteration-N-analysis.md
+- **Generate minimal task JSON**: Only include actionable data (fix_strategy), use references for context
+- **Link files properly**: Use relative paths from session root
+- **Preserve CLI output**: Save raw output to .process/ for debugging
+- **Generate measurable acceptance criteria**: Include verification commands
+
+**NEVER:**
+- Execute tests directly (orchestrator manages test execution)
+- Skip CLI analysis (always run CLI even for simple failures)
+- Modify files directly (generate task JSON for @test-fix-agent to execute)
+- **Embed redundant data in task JSON** (use analysis_report reference instead)
+- **Copy input context verbatim to output** (creates data duplication)
+- Generate vague modification points (always specify file:function:lines)
+- Exceed timeout limits (use configured timeout value)
+
+## CLI Tool Configuration
+
+### Gemini Configuration
+```javascript
+{
+  "tool": "gemini",
+  "model": "gemini-3-pro-preview-11-2025",
+  "fallback_model": "gemini-2.5-pro",
+  "templates": {
+    "test-failure": "01-diagnose-bug-root-cause.txt",
+    "coverage-gap": "02-analyze-code-patterns.txt",
+    "regression": "01-trace-code-execution.txt"
+  }
+}
+```
+
+### Qwen Configuration (Fallback)
+```javascript
+{
+  "tool": "qwen",
+  "model": "coder-model",
+  "templates": {
+    "test-failure": "01-diagnose-bug-root-cause.txt",
+    "coverage-gap": "02-analyze-code-patterns.txt"
+  }
+}
+```
+
+## Integration with test-cycle-execute
+
+**Orchestrator Call Pattern**:
+```javascript
+// When pass_rate < 95%
+Task(
+  subagent_type="cli-planning-agent",
+  description=`Analyze test failures and generate fix task (iteration ${iteration})`,
+  prompt=`
+    ## Context Package
+    ${JSON.stringify(contextPackage, null, 2)}
+
+    ## Your Task
+    1. Execute CLI analysis using ${cli_config.tool}
+    2. Parse CLI output and extract fix strategy
+    3. Generate IMPL-fix-${iteration}.json with structured task definition
+    4. Save analysis report to .process/iteration-${iteration}-analysis.md
+    5. Report success and task ID back to orchestrator
+  `
+)
+```
+
+**Agent Response**:
+```javascript
+{
+  "status": "success",
+  "task_id": "IMPL-fix-{iteration}",
+  "task_path": ".workflow/{session}/.task/IMPL-fix-{iteration}.json",
+  "analysis_report": ".process/iteration-{iteration}-analysis.md",
+  "cli_output": ".process/iteration-{iteration}-cli-output.txt",
+  "summary": "{fix_strategy.approach first 100 chars}",
+  "modification_points_count": {count},
+  "estimated_complexity": "low|medium|high"
+}
+```
+
+## Example Execution
+
+**Input Context**:
+```json
+{
+  "session_id": "WFS-test-session-001",
+  "iteration": 1,
+  "analysis_type": "test-failure",
+  "failure_context": {
+    "failed_tests": [
+      {
+        "test": "test_auth_token_expired",
+        "error": "AssertionError: expected 401, got 200",
+        "file": "tests/integration/test_auth.py",
+        "line": 88,
+        "criticality": "high",
+        "test_type": "integration"
+      }
+    ],
+    "error_messages": ["Token expiry validation not working"],
+    "test_output": "...",
+    "pass_rate": 90.0
+  },
+  "cli_config": {
+    "tool": "gemini",
+    "template": "01-diagnose-bug-root-cause.txt"
+  }
+}
+```
+
+**Execution Steps**:
+1. Detect test_type: "integration" → Apply integration-specific diagnosis
+2. Execute: `gemini -p "PURPOSE: Analyze integration test failure... [layer-specific context]"`
+   - CLI prompt includes: "Examine component interactions, data flow, interface contracts"
+   - Guidance: "Analyze full call stack and data flow across components"
+3. Parse: Extract RCA, 修复建议, 验证建议 sections
+4. Generate: IMPL-fix-1.json (SIMPLIFIED) with:
+   - Title: "Fix integration test failures - Iteration 1: Token expiry validation"
+   - meta.analysis_report: ".process/iteration-1-analysis.md" (Reference, not embedded data)
+   - meta.test_layer: "integration"
+   - Requirements: "Fix 1 integration test failures by applying the provided fix strategy"
+   - fix_strategy.modification_points: ["src/auth/auth.service.ts:validateToken:45-60", "src/middleware/auth.middleware.ts:checkExpiry:120-135"]
+   - fix_strategy.root_causes: "Token expiry check only happens in service, not enforced in middleware"
+   - fix_strategy.quality_assurance: {avoids_symptom_fix: true, addresses_root_cause: true}
+   - **NO failure_context object** - full context available via analysis_report reference
+5. Save: iteration-1-analysis.md with full CLI output, layer context, failed_tests details, previous_attempts
+6. Return: task_id="IMPL-fix-1", test_layer="integration", status="success"

.claude/skills/command-guide/reference/agents/test-fix-agent.md

@@ -21,23 +21,33 @@ description: |
 color: green
 ---
 
-You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites, diagnose failures, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive test validation.
+You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites across multiple layers (Static, Unit, Integration, E2E), diagnose failures with layer-specific context, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive multi-layered test validation.
 
 ## Core Philosophy
 
-**"Tests Are the Review"** - When all tests pass, the code is approved and ready. No separate review process is needed.
+**"Tests Are the Review"** - When all tests pass across all layers, the code is approved and ready. No separate review process is needed.
+
+**"Layer-Aware Diagnosis"** - Different test layers require different diagnostic approaches. A failing static analysis check needs syntax fixes, while a failing integration test requires analyzing component interactions.
 
 ## Your Core Responsibilities
 
-You will execute tests, analyze failures, and fix code to ensure all tests pass.
+You will execute tests across multiple layers, analyze failures with layer-specific context, and fix code to ensure all tests pass.
 
-### Test Execution & Fixing Responsibilities:
-1. **Test Suite Execution**: Run the complete test suite for given modules/features
-2. **Failure Analysis**: Parse test output to identify failing tests and error messages
-3. **Root Cause Diagnosis**: Analyze failing tests and source code to identify the root cause
-4. **Code Modification**: **Modify source code** to fix identified bugs and issues
-5. **Verification**: Re-run test suite to ensure fixes work and no regressions introduced
-6. **Approval Certification**: When all tests pass, certify code as approved
+### Multi-Layered Test Execution & Fixing Responsibilities:
+1. **Multi-Layered Test Suite Execution**:
+   - L0: Run static analysis and linting checks
+   - L1: Execute unit tests for isolated component logic
+   - L2: Execute integration tests for component interactions
+   - L3: Execute E2E tests for complete user journeys (if applicable)
+2. **Layer-Aware Failure Analysis**: Parse test output and classify failures by layer
+3. **Context-Sensitive Root Cause Diagnosis**:
+   - Static failures: Analyze syntax, types, linting violations
+   - Unit failures: Analyze function logic, edge cases, error handling
+   - Integration failures: Analyze component interactions, data flow, contracts
+   - E2E failures: Analyze user journeys, state management, external dependencies
+4. **Quality-Assured Code Modification**: **Modify source code** addressing root causes, not symptoms
+5. **Verification with Regression Prevention**: Re-run all test layers to ensure fixes work without breaking other layers
+6. **Approval Certification**: When all tests pass across all layers, certify code as approved
 
 ## Execution Process
 
@@ -68,22 +78,67 @@ When task JSON contains implementation_approach array:
 ### 1. Context Assessment & Test Discovery
 - Analyze task context to identify test files and source code paths
 - Load test framework configuration (Jest, Pytest, Mocha, etc.)
+- **Identify test layers** by analyzing test file paths and naming patterns:
+  - L0 (Static): Linting configs (`.eslintrc`, `tsconfig.json`), static analysis tools
+  - L1 (Unit): `*.test.*`, `*.spec.*` in `__tests__/`, `tests/unit/`
+  - L2 (Integration): `tests/integration/`, `*.integration.test.*`
+  - L3 (E2E): `tests/e2e/`, `*.e2e.test.*`, `cypress/`, `playwright/`
 - **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
-- Identify test command from project configuration
+- Identify test commands from project configuration
 
 ```bash
-# Detect test framework and command
+# Detect test framework and multi-layered commands
 if [ -f "package.json" ]; then
-    TEST_CMD=$(cat package.json | jq -r '.scripts.test')
+    # Extract layer-specific test commands
+    LINT_CMD=$(cat package.json | jq -r '.scripts.lint // "eslint ."')
+    UNIT_CMD=$(cat package.json | jq -r '.scripts["test:unit"] // .scripts.test')
+    INTEGRATION_CMD=$(cat package.json | jq -r '.scripts["test:integration"] // ""')
+    E2E_CMD=$(cat package.json | jq -r '.scripts["test:e2e"] // ""')
 elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
-    TEST_CMD="pytest"
+    LINT_CMD="ruff check . || flake8 ."
+    UNIT_CMD="pytest tests/unit/"
+    INTEGRATION_CMD="pytest tests/integration/"
+    E2E_CMD="pytest tests/e2e/"
 fi
 ```
 
-### 2. Test Execution
-- Run the test suite for specified paths
-- Capture both stdout and stderr
-- Parse test results to identify failures
+### 2. Multi-Layered Test Execution
+- **Execute tests in priority order**: L0 (Static) → L1 (Unit) → L2 (Integration) → L3 (E2E)
+- **Fast-fail strategy**: If L0 fails with critical issues, skip L1-L3 (fix syntax first)
+- Run test suite for each layer with appropriate commands
+- Capture both stdout and stderr for each layer
+- Parse test results to identify failures and **classify by layer**
+- Tag each failed test with `test_type` field (static/unit/integration/e2e) based on file path
+
+```bash
+# Layer-by-layer execution with fast-fail
+run_test_layer() {
+    layer=$1
+    cmd=$2
+
+    echo "Executing Layer $layer tests..."
+    $cmd 2>&1 | tee ".process/test-layer-$layer-output.txt"
+
+    # Parse results and tag with test_type
+    parse_test_results ".process/test-layer-$layer-output.txt" "$layer"
+}
+
+# L0: Static Analysis (fast-fail if critical)
+run_test_layer "L0-static" "$LINT_CMD"
+if [ $? -ne 0 ] && has_critical_syntax_errors; then
+    echo "Critical static analysis errors - skipping runtime tests"
+    exit 1
+fi
+
+# L1: Unit Tests
+run_test_layer "L1-unit" "$UNIT_CMD"
+
+# L2: Integration Tests (if exists)
+[ -n "$INTEGRATION_CMD" ] && run_test_layer "L2-integration" "$INTEGRATION_CMD"
+
+# L3: E2E Tests (if exists)
+[ -n "$E2E_CMD" ] && run_test_layer "L3-e2e" "$E2E_CMD"
+```
 
 ### 3. Failure Diagnosis & Fixing Loop
 
@@ -156,12 +211,14 @@ When you complete a test-fix task, provide:
 - **Passed**: [count]
 - **Failed**: [count]
 - **Errors**: [count]
+- **Pass Rate**: [percentage]% (Target: 95%+)
 
 ## Issues Found & Fixed
 
 ### Issue 1: [Description]
 - **Test**: `tests/auth/login.test.ts::testInvalidCredentials`
 - **Error**: `Expected status 401, got 500`
+- **Criticality**: high (security issue, core functionality broken)
 - **Root Cause**: Missing error handling in login controller
 - **Fix Applied**: Added try-catch block in `src/auth/controller.ts:45`
 - **Files Modified**: `src/auth/controller.ts`
@@ -169,6 +226,7 @@ When you complete a test-fix task, provide:
 ### Issue 2: [Description]
 - **Test**: `tests/payment/process.test.ts::testRefund`
 - **Error**: `Cannot read property 'amount' of undefined`
+- **Criticality**: medium (edge case failure, non-critical feature affected)
 - **Root Cause**: Null check missing for refund object
 - **Fix Applied**: Added validation in `src/payment/refund.ts:78`
 - **Files Modified**: `src/payment/refund.ts`
@@ -178,6 +236,7 @@ When you complete a test-fix task, provide:
 ✅ **All tests passing**
 - **Total Tests**: [count]
 - **Passed**: [count]
+- **Pass Rate**: 100%
 - **Duration**: [time]
 
 ## Code Approval
@@ -190,6 +249,71 @@ All tests pass - code is ready for deployment.
 - `src/payment/refund.ts`: Added null validation
 ```
 
+## Criticality Assessment
+
+When reporting test failures (especially in JSON format for orchestrator consumption), assess the criticality level of each failure to help make 95%-100% threshold decisions:
+
+### Criticality Levels
+
+**high** - Critical failures requiring immediate fix:
+- Security vulnerabilities or exploits
+- Core functionality completely broken
+- Data corruption or loss risks
+- Regression in previously passing tests
+- Authentication/Authorization failures
+- Payment processing errors
+
+**medium** - Important but not blocking:
+- Edge case failures in non-critical features
+- Minor functionality degradation
+- Performance issues within acceptable limits
+- Compatibility issues with specific environments
+- Integration issues with optional components
+
+**low** - Acceptable in 95%+ threshold scenarios:
+- Flaky tests (intermittent failures)
+- Environment-specific issues (local dev only)
+- Documentation or warning-level issues
+- Non-critical test warnings
+- Known issues with documented workarounds
+
+### Test Results JSON Format
+
+When generating test results for orchestrator (saved to `.process/test-results.json`):
+
+```json
+{
+  "total": 10,
+  "passed": 9,
+  "failed": 1,
+  "pass_rate": 90.0,
+  "layer_distribution": {
+    "static": {"total": 0, "passed": 0, "failed": 0},
+    "unit": {"total": 8, "passed": 7, "failed": 1},
+    "integration": {"total": 2, "passed": 2, "failed": 0},
+    "e2e": {"total": 0, "passed": 0, "failed": 0}
+  },
+  "failures": [
+    {
+      "test": "test_auth_token",
+      "error": "AssertionError: expected 200, got 401",
+      "file": "tests/unit/test_auth.py",
+      "line": 45,
+      "criticality": "high",
+      "test_type": "unit"
+    }
+  ]
+}
+```
+
+### Decision Support
+
+**For orchestrator decision-making**:
+- Pass rate 100% + all tests pass → ✅ SUCCESS (proceed to completion)
+- Pass rate >= 95% + all failures are "low" criticality → ✅ PARTIAL SUCCESS (review and approve)
+- Pass rate >= 95% + any "high" or "medium" criticality failures → ⚠️ NEEDS FIX (continue iteration)
+- Pass rate < 95% → ❌ FAILED (continue iteration or abort)
+
 ## Important Reminders
 
 **ALWAYS:**

.claude/skills/command-guide/reference/commands/cli/analyze.md

@@ -1,7 +1,7 @@
 ---
 name: analyze
 description: Read-only codebase analysis using Gemini (default), Qwen, or Codex with auto-pattern detection and template selection
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
@@ -42,43 +41,41 @@ Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Auto-detect file patterns from keywords
-4. Build command with analysis template
-5. Execute analysis (read-only)
-6. Save results
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent analysis:
+Uses **cli-execution-agent** (default) for automated analysis:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Codebase analysis",
+  description="Codebase analysis with pattern detection",
   prompt=`
     Task: ${analysis_target}
     Mode: analyze
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Enhance: ${enhance_flag || false}
+    Tool: ${tool_flag || 'gemini'}
+    Enhance: ${enhance_flag}
+
+    Execute codebase analysis with auto-pattern detection:
 
-    Agent responsibilities:
     1. Context Discovery:
-       - Discover relevant files/patterns
-       - Identify analysis scope
-       - Build file context
+       - Extract keywords from analysis target
+       - Auto-detect file patterns (auth→auth files, component→components, etc.)
+       - Discover additional relevant files using MCP
+       - Build comprehensive file context
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Apply analysis template
-       - Include discovered files
+    2. Template Selection:
+       - Auto-select analysis template based on keywords
+       - Apply appropriate analysis methodology
+       - Include @CLAUDE.md for project context
 
-    3. Execution & Output:
-       - Execute analysis
-       - Generate insights report
-       - Save to .workflow/.chat/ or .scratchpad/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep analysis)
+       - Context: @CLAUDE.md + auto-detected patterns + discovered files
+       - Mode: analysis (read-only)
+       - Expected: Insights, recommendations, pattern analysis
+
+    4. Execution & Output:
+       - Execute CLI tool with assembled context
+       - Generate comprehensive analysis report
+       - Save to .workflow/WFS-[id]/.chat/analyze-[timestamp].md (or .scratchpad/)
   `
 )
 ```
@@ -86,51 +83,5 @@ Task(
 ## Core Rules
 
 - **Read-only**: Analyzes code, does NOT modify files
-- **Auto-pattern**: Detects file patterns from keywords
-- **Template-based**: Auto-selects analysis template
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
-
-## File Pattern Auto-Detection
-
-Keywords → file patterns:
-- "auth" → `@**/*auth* @**/*user*`
-- "component" → `@src/components/**/*`
-- "API" → `@**/api/**/* @**/routes/**/*`
-- "test" → `@**/*.test.* @**/*.spec.*`
-- Generic → `@src/**/*`
-
-## CLI Command Templates
-
-**Gemini/Qwen**:
-```bash
-cd . && gemini -p "
-PURPOSE: [goal]
-TASK: [analysis type]
-MODE: analysis
-CONTEXT: @CLAUDE.md [auto-detected patterns]
-EXPECTED: Insights, recommendations
-RULES: [auto-selected template]
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex**:
-```bash
-codex -C . --full-auto exec "
-PURPOSE: [goal]
-TASK: [analysis type]
-MODE: analysis
-CONTEXT: @CLAUDE.md [patterns]
-EXPECTED: Deep insights
-RULES: [template]
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/analyze-[desc]-[timestamp].md`
-
-## Notes
-
-- See `intelligent-tools-strategy.md` for detailed tool usage and templates
+- **Auto-pattern**: Detects file patterns from keywords (auth→auth files, component→components, API→api/routes, test→test files)
+- **Output**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md` (or `.scratchpad/` if no session)

.claude/skills/command-guide/reference/commands/cli/chat.md

@@ -1,7 +1,7 @@
 ---
 name: chat
 description: Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance inquiry with `/enhance-prompt`
 - `<inquiry>` (Required) - Question or analysis request
 
@@ -42,42 +41,36 @@ Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Assemble context: `@CLAUDE.md` + inferred files
-4. Execute Q&A (read-only)
-5. Return answer
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent Q&A:
+Uses **cli-execution-agent** (default) for automated Q&A:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Codebase Q&A",
+  description="Codebase Q&A with intelligent context discovery",
   prompt=`
     Task: ${inquiry}
-    Mode: chat (Q&A)
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Enhance: ${enhance_flag || false}
+    Mode: chat
+    Tool: ${tool_flag || 'gemini'}
+    Enhance: ${enhance_flag}
+
+    Execute codebase Q&A with intelligent context discovery:
 
-    Agent responsibilities:
     1. Context Discovery:
-       - Discover files relevant to question
-       - Identify key code sections
-       - Build precise context
+       - Parse inquiry to identify relevant topics/keywords
+       - Discover related files using MCP/ripgrep (prioritize precision)
+       - Include @CLAUDE.md + discovered files
+       - Validate context relevance to question
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include discovered context
-       - Apply Q&A template
+    2. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep dives)
+       - Context: @CLAUDE.md + discovered file patterns
+       - Mode: analysis (read-only)
+       - Expected: Clear, accurate answer with code references
 
     3. Execution & Output:
-       - Execute Q&A analysis
-       - Generate detailed answer
-       - Save to .workflow/.chat/ or .scratchpad/
+       - Execute CLI tool with assembled context
+       - Validate answer completeness
+       - Save to .workflow/WFS-[id]/.chat/chat-[timestamp].md (or .scratchpad/)
   `
 )
 ```
@@ -86,40 +79,4 @@ Task(
 
 - **Read-only**: Provides answers, does NOT modify code
 - **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
-
-## CLI Command Templates
-
-**Gemini/Qwen**:
-```bash
-cd . && gemini -p "
-PURPOSE: Answer question
-TASK: [inquiry]
-MODE: analysis
-CONTEXT: @CLAUDE.md [inferred or @**/*]
-EXPECTED: Clear answer
-RULES: Focus on accuracy
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex**:
-```bash
-codex -C . --full-auto exec "
-PURPOSE: Answer question
-TASK: [inquiry]
-MODE: analysis
-CONTEXT: @CLAUDE.md [inferred or @**/*]
-EXPECTED: Detailed answer
-RULES: Technical depth
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/chat-[desc]-[timestamp].md`
-
-## Notes
-
-- See `intelligent-tools-strategy.md` for detailed tool usage and templates
+- **Output**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md` (or `.scratchpad/` if no session)

.claude/skills/command-guide/reference/commands/cli/execute.md

@@ -1,7 +1,7 @@
 ---
 name: execute
 description: Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -39,7 +39,7 @@ 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):
+**3. Agent Mode** (default):
 - Input: Description or task-id
 - Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
 
@@ -68,8 +68,7 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Parameters
 
-- `--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)
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: auto-select by agent based on complexity)
 - `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
 - `<description|task-id>` - Natural language description or task identifier
 - `--debug` - Verbose logging
@@ -83,96 +82,83 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
 
-## Output Routing
+## Execution Flow
 
-**Execution Log Destination**:
-- **IF** active workflow session exists:
-  - Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-  - Update task status in `.task/[TASK-ID].json` (if task ID provided)
-  - Generate summary in `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md`
-- **ELSE** (no active session):
-  - **Option 1**: Create new workflow session for task
-  - **Option 2**: Save to `.workflow/.scratchpad/execute-[description]-[timestamp].md`
+Uses **cli-execution-agent** (default) for automated implementation:
 
-**Output Files** (when active session exists):
-- Execution log: `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- Task summary: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
-- Modified code: Project files per implementation
-
-**Examples**:
-- During session `WFS-auth-system`, executing `IMPL-001`:
-  - Log: `.workflow/WFS-auth-system/.chat/execute-20250105-143022.md`
-  - Summary: `.workflow/WFS-auth-system/.summaries/IMPL-001-summary.md`
-- No session, ad-hoc implementation:
-  - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
-
-## Execution Modes
-
-### Standard Mode (Default)
-```bash
-# Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && gemini --approval-mode yolo "
-PURPOSE: [implementation goal]
-TASK: [specific implementation]
-MODE: write
-CONTEXT: @CLAUDE.md [auto-detected files]
-EXPECTED: Working implementation with code changes
-RULES: [constraints] | Auto-approve all changes
-"
-
-# Codex: MODE=auto with danger-full-access
-codex -C . --full-auto exec "
-PURPOSE: [implementation goal]
-TASK: [specific implementation]
-MODE: auto
-CONTEXT: [auto-detected files]
-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",
+  description="Autonomous code implementation with YOLO auto-approval",
   prompt=`
     Task: ${description_or_task_id}
     Mode: execute
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${enhance_flag ? 'Enhance: true' : ''}
+    Tool: ${tool_flag || 'auto-select'}
+    Enhance: ${enhance_flag}
+    Task-ID: ${task_id}
 
-    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
+    Execute autonomous code implementation with full modification permissions:
+
+    1. Task Analysis:
+       ${task_id ? '- Load task spec from .task/' + task_id + '.json' : ''}
+       - Parse requirements and implementation scope
+       - Classify complexity (simple/medium/complex)
+       - Extract keywords for context discovery
+
+    2. Context Discovery:
+       - Discover implementation files using MCP/ripgrep
+       - Identify existing patterns and conventions (CLAUDE.md)
+       - Map dependencies and integration points
+       - Gather related tests and documentation
+       - Auto-detect file patterns from keywords
+
+    3. Tool Selection & Execution:
+       - Complexity assessment:
+         * Simple/Medium → Gemini/Qwen (MODE=write, --approval-mode yolo)
+         * Complex → Codex (MODE=auto, --skip-git-repo-check -s danger-full-access)
+       - Tool preference: ${tool_flag || 'auto-select based on complexity'}
+       - Apply appropriate implementation template
+       - Execute with YOLO auto-approval (bypasses all confirmations)
+
+    4. Implementation:
+       - Modify/create/delete code files per requirements
+       - Follow existing code patterns and conventions
+       - Include comprehensive context in CLI command
+       - Ensure working implementation with proper error handling
+
+    5. Output & Documentation:
+       - Save execution log: .workflow/WFS-[id]/.chat/execute-[timestamp].md
+       ${task_id ? '- Generate task summary: .workflow/WFS-[id]/.summaries/' + task_id + '-summary.md' : ''}
+       ${task_id ? '- Update task status in .task/' + task_id + '.json' : ''}
+       - Document all code changes made
+
+    ⚠️ YOLO Mode: All file operations auto-approved without confirmation
   `
 )
 ```
 
-The agent handles all phases internally, including complexity-based tool selection.
+**Output**: `.workflow/WFS-[id]/.chat/execute-[timestamp].md` + `.summaries/[TASK-ID]-summary.md` (or `.scratchpad/` if no session)
 
 ## Examples
 
-**Basic Implementation (Standard Mode)** (modifies code):
+**Basic Implementation** (modifies code):
 ```bash
 /cli:execute "implement JWT authentication with middleware"
-# Executes: Creates auth middleware, updates routes, modifies config
+# Agent Phase 1: Classifies intent=execute, complexity=medium, keywords=['jwt', 'auth', 'middleware']
+# Agent Phase 2: Discovers auth patterns, existing middleware structure
+# Agent Phase 3: Selects Gemini (medium complexity)
+# Agent Phase 4: Executes with auto-approval
 # Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Intelligent Implementation (Agent Mode)** (modifies code):
+**Complex Implementation** (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
+/cli:execute "implement OAuth2 authentication with token refresh"
+# Agent Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
+# Agent Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
+# Agent Phase 3: Enhances prompt with discovered patterns and best practices
+# Agent Phase 4: Selects Codex (complex task), executes with comprehensive context
+# Agent Phase 5: Saves execution log + generates implementation summary
 # Result: Complete OAuth2 implementation + detailed execution log
 ```
 
@@ -214,8 +200,3 @@ The agent handles all phases internally, including complexity-based tool selecti
 | `/cli:analyze` | Understand code | NO | N/A |
 | `/cli:chat` | Ask questions | NO | N/A |
 | `/cli:execute` | **Implement** | **YES** | **YES** |
-
-## Notes
-
-- Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
-- **Code Modification**: This command modifies code - execution logs document changes made

.claude/skills/command-guide/reference/commands/cli/mode/bug-diagnosis.md

@@ -1,7 +1,7 @@
 ---
 name: bug-diagnosis
 description: Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance bug description with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused diagnosis
 - `<bug-description>` (Required) - Bug description or error details
@@ -44,44 +43,48 @@ Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Detect directory from `--cd` or auto-infer
-4. Build command with template
-5. Execute diagnosis (read-only)
-6. Save to `.workflow/WFS-[id]/.chat/`
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent diagnosis:
+Uses **cli-execution-agent** (default) for automated bug diagnosis:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Bug root cause diagnosis",
+  description="Bug root cause diagnosis with fix suggestions",
   prompt=`
     Task: ${bug_description}
     Mode: bug-diagnosis
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Directory: ${cd_path || 'auto-detect'}
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
     Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
 
-    Agent responsibilities:
+    Execute systematic bug diagnosis and root cause analysis:
+
     1. Context Discovery:
-       - Locate error traces and logs
-       - Find related code sections
-       - Identify data flow paths
+       - Locate error traces, stack traces, and log messages
+       - Find related code sections and affected modules
+       - Identify data flow paths leading to the bug
+       - Discover test cases related to bug area
+       - Use MCP/ripgrep for comprehensive context gathering
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include diagnostic context
-       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt template
+    2. Root Cause Analysis:
+       - Apply diagnostic template methodology
+       - Trace execution to identify failure point
+       - Analyze state, data, and logic causing issue
+       - Document potential root causes with evidence
+       - Assess bug severity and impact scope
 
-    3. Execution & Output:
-       - Execute root cause analysis
-       - Generate fix suggestions
-       - Save to .workflow/.chat/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex bugs)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* + error traces + affected code
+       - Mode: analysis (read-only)
+       - Template: analysis/01-diagnose-bug-root-cause.txt
+
+    4. Output Generation:
+       - Root cause diagnosis with evidence
+       - Fix suggestions and recommendations
+       - Prevention strategies
+       - Save to .workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md (or .scratchpad/)
   `
 )
 ```
@@ -89,42 +92,5 @@ Task(
 ## Core Rules
 
 - **Read-only**: Diagnoses bugs, does NOT modify code
-- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt` for root cause analysis
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-
-## CLI Command Templates
-
-**Gemini/Qwen** (default, diagnosis only):
-```bash
-cd [dir] && gemini -p "
-PURPOSE: [goal]
-TASK: Root cause analysis
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Diagnosis, fix plan
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex** (diagnosis + potential fixes):
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [goal]
-TASK: Bug diagnosis
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Diagnosis, fix suggestions
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt)
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/bug-diagnosis-[desc]-[timestamp].md`
-
-## Notes
-
-- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
-- See `intelligent-tools-strategy.md` for detailed tool usage
+- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
+- **Output**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md` (or `.scratchpad/` if no session)

.claude/skills/command-guide/reference/commands/cli/mode/code-analysis.md

@@ -1,7 +1,7 @@
 ---
 name: code-analysis
 description: Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -21,7 +21,6 @@ Systematic code analysis with execution path tracing template (`~/.claude/workfl
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
@@ -47,91 +46,53 @@ Systematic code analysis with execution path tracing template (`~/.claude/workfl
 
 ## Execution Flow
 
-### Standard Mode (Default)
-
-1. Parse tool selection (default: gemini)
-2. Optional: enhance analysis target with `/enhance-prompt`
-3. Detect target directory from `--cd` or auto-infer
-4. Build command with template
-5. Execute analysis (read-only)
-6. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-
-### Agent Mode (`--agent` flag)
-
-Delegates to `cli-execution-agent` for intelligent context discovery and analysis.
-
-## Core Rules
-
-- **Read-only**: Analyzes code, does NOT modify files
-- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt` for systematic analysis
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-
-## CLI Command Templates
-
-**Gemini/Qwen** (default, read-only analysis):
-```bash
-cd [dir] && gemini -p "
-PURPOSE: [goal]
-TASK: Execution path tracing
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Trace, call diagram
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex** (analysis + optimization suggestions):
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [goal]
-TASK: Path analysis
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Trace, optimization
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt)
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Agent Execution Context
-
-When `--agent` flag is used, delegate to agent:
+Uses **cli-execution-agent** (default) for automated code analysis:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Code execution path analysis",
+  description="Execution path tracing and call flow analysis",
   prompt=`
     Task: ${analysis_target}
     Mode: code-analysis
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Directory: ${cd_path || 'auto-detect'}
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
     Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt
 
-    Agent responsibilities:
+    Execute systematic code analysis with execution path tracing:
+
     1. Context Discovery:
-       - Identify entry points and call chains
-       - Discover related files (MCP/ripgrep)
-       - Map execution flow paths
+       - Identify entry points and function signatures
+       - Trace call chains and execution flows
+       - Discover related files (implementations, dependencies, tests)
+       - Map data flow and state transformations
+       - Use MCP/ripgrep for comprehensive file discovery
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include discovered context
-       - Apply ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt template
+    2. Analysis Execution:
+       - Apply execution tracing template
+       - Generate call flow diagrams (textual)
+       - Document execution paths and branching logic
+       - Identify optimization opportunities
 
-    3. Execution & Output:
-       - Execute analysis with selected tool
-       - Save to .workflow/WFS-[id]/.chat/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex analysis)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* + discovered execution context
+       - Mode: analysis (read-only)
+       - Template: analysis/01-trace-code-execution.txt
+
+    4. Output Generation:
+       - Execution trace documentation
+       - Call flow analysis with diagrams
+       - Performance and optimization insights
+       - Save to .workflow/WFS-[id]/.chat/code-analysis-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
-## Output
+## Core Rules
 
-- **With session**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/code-analysis-[desc]-[timestamp].md`
-
-## Notes
-
-- Template: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
-- See `intelligent-tools-strategy.md` for detailed tool usage
+- **Read-only**: Analyzes code, does NOT modify files
+- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
+- **Output**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md` (or `.scratchpad/` if no session)

.claude/skills/command-guide/reference/commands/cli/mode/plan.md

@@ -1,7 +1,7 @@
 ---
 name: plan
 description: Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -19,7 +19,6 @@ Strategic software architecture planning template (`~/.claude/workflows/cli-temp
 ## Parameters
 
 - `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
-- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance task with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused planning
 - `<planning-task>` (Required) - Architecture planning task or modification requirements
@@ -43,87 +42,52 @@ Strategic software architecture planning template (`~/.claude/workflows/cli-temp
 
 ## Execution Flow
 
-### Standard Mode
-1. Parse tool selection (default: gemini)
-2. Optional: enhance with `/enhance-prompt`
-3. Detect directory from `--cd` or auto-infer
-4. Build command with template
-5. Execute planning (read-only, no code generation)
-6. Save to `.workflow/WFS-[id]/.chat/`
-
-### Agent Mode (`--agent`)
-
-Delegates to agent for intelligent planning:
+Uses **cli-execution-agent** (default) for automated planning:
 
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Architecture modification planning",
+  description="Architecture planning with impact analysis",
   prompt=`
     Task: ${planning_task}
-    Mode: architecture-planning
-    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
-    Directory: ${cd_path || 'auto-detect'}
+    Mode: plan
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
     Template: ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt
 
-    Agent responsibilities:
+    Execute strategic architecture planning:
+
     1. Context Discovery:
-       - Analyze current architecture
-       - Identify affected components
-       - Map dependencies and impacts
+       - Analyze current architecture structure
+       - Identify affected components and modules
+       - Map dependencies and integration points
+       - Assess modification impacts (scope, complexity, risks)
 
-    2. CLI Command Generation:
-       - Build Gemini/Qwen/Codex command
-       - Include architecture context
-       - Apply ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt template
+    2. Planning Analysis:
+       - Apply strategic planning template
+       - Generate modification plan with phases
+       - Document architectural decisions and rationale
+       - Identify potential conflicts and mitigation strategies
 
-    3. Execution & Output:
-       - Execute strategic planning
-       - Generate modification plan
-       - Save to .workflow/.chat/
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for implementation guidance)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* (full architecture context)
+       - Mode: analysis (read-only, no code generation)
+       - Template: planning/01-plan-architecture-design.txt
+
+    4. Output Generation:
+       - Strategic modification plan
+       - Impact analysis and risk assessment
+       - Implementation roadmap
+       - Save to .workflow/WFS-[id]/.chat/plan-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
 ## Core Rules
 
-- **Planning only**: Creates modification plans, does NOT generate code
-- **Template**: Uses `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt` for strategic planning
-- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
-
-## CLI Command Templates
-
-**Gemini/Qwen** (default, planning only):
-```bash
-cd [dir] && gemini -p "
-PURPOSE: [goal]
-TASK: Architecture planning
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Modification plan, impact analysis
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
-"
-# Qwen: Replace 'gemini' with 'qwen'
-```
-
-**Codex** (planning + implementation guidance):
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [goal]
-TASK: Architecture planning
-MODE: analysis
-CONTEXT: @**/*
-EXPECTED: Plan, implementation roadmap
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt)
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-## Output
-
-- **With session**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-- **No session**: `.workflow/.scratchpad/plan-[desc]-[timestamp].md`
-
-## Notes
-
-- Template: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
-- See `intelligent-tools-strategy.md` for detailed tool usage
+- **Read-only**: Creates modification plans, does NOT generate code
+- **Template**: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
+- **Output**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md` (or `.scratchpad/` if no session)

.claude/skills/command-guide/reference/commands/memory/code-map-memory.md

@@ -0,0 +1,764 @@
+---
+name: code-map-memory
+description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)
+argument-hint: "\"feature-keyword\" [--regenerate] [--tool <gemini|qwen>]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
+---
+
+# Code Flow Mapping Generator
+
+## Overview
+
+**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation.
+
+**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
+
+**Execution Paths**:
+- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag)
+- **Phase 3 Always Executes**: SKILL index is always generated or updated
+
+**Agent Responsibility** (cli-explore-agent):
+- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI)
+- Returns structured JSON with architecture, functions, data flow, conditionals, patterns
+- NO file writing - analysis only
+
+**Orchestrator Responsibility**:
+- Provides feature keyword and analysis scope to agent
+- Transforms agent's JSON into Mermaid-enriched markdown documentation
+- Writes all files (5 docs + metadata.json + SKILL.md)
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package
+3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode)
+4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files
+5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+6. **No User Prompts**: Never ask user questions or wait for input between phases
+7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional
+
+---
+
+## 3-Phase Execution
+
+### Phase 1: Parse Feature Keyword & Check Existing
+
+**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis
+
+**Step 1: Parse Feature Keyword**
+```bash
+# Get feature keyword from argument
+FEATURE_KEYWORD="$1"
+
+# Normalize: lowercase, spaces to hyphens
+normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
+
+# Example: "User Authentication" → "user-authentication"
+# Example: "支付处理" → "支付处理" (keep non-ASCII)
+```
+
+**Step 2: Set Tool Preference**
+```bash
+# Default to gemini unless --tool specified
+TOOL="${tool_flag:-gemini}"
+```
+
+**Step 3: Check Existing Codemap**
+```bash
+# Define codemap directory
+CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}"
+
+# Check if codemap exists
+bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists")
+
+# Count existing files
+bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Step 4: Skip Decision**
+```javascript
+if (existing_files > 0 && !regenerate_flag) {
+  SKIP_GENERATION = true
+  message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  bash(rm -rf "$CODEMAP_DIR")
+  SKIP_GENERATION = false
+  message = "Regenerating codemap from scratch."
+} else {
+  SKIP_GENERATION = false
+  message = "No existing codemap found, generating new code flow analysis."
+}
+```
+
+**Output Variables**:
+- `FEATURE_KEYWORD`: Original feature keyword
+- `normalized_feature`: Normalized feature name for directory
+- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}`
+- `TOOL`: CLI tool to use (gemini or qwen)
+- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
+
+**TodoWrite**:
+- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
+- If not skipping: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Code Flow Analysis & Documentation Generation
+
+**Skip Condition**: Skipped if `SKIP_GENERATION = true`
+
+**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation
+
+**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation)
+
+---
+
+#### Phase 2a: cli-explore-agent Analysis
+
+**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis
+
+**Agent Task Specification**:
+
+```
+Task(
+  subagent_type: "cli-explore-agent",
+  description: "Analyze code flow: {FEATURE_KEYWORD}",
+  prompt: "
+Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
+
+**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis)
+
+**Analysis Objectives**:
+1. **Module Architecture**: Identify high-level module organization, interactions, and entry points
+2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows
+3. **Data Transformations**: Map data structure changes and transformation stages
+4. **Conditional Paths**: Document decision trees, branches, and error handling strategies
+5. **Design Patterns**: Discover architectural patterns and extract design intent
+
+**Scope**:
+- Feature: {FEATURE_KEYWORD}
+- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model)
+- File Discovery: MCP Code Index (preferred) + rg fallback
+- Target: 5-15 most relevant files
+
+**Expected Output Format**:
+Return comprehensive analysis as structured JSON:
+{
+  \"feature\": \"{FEATURE_KEYWORD}\",
+  \"analysis_metadata\": {
+    \"tool_used\": \"gemini|qwen\",
+    \"timestamp\": \"ISO_TIMESTAMP\",
+    \"analysis_mode\": \"deep-scan\"
+  },
+  \"files_analyzed\": [
+    {\"file\": \"path/to/file.ts\", \"relevance\": \"high|medium|low\", \"role\": \"brief description\"}
+  ],
+  \"architecture\": {
+    \"overview\": \"High-level description\",
+    \"modules\": [
+      {\"name\": \"ModuleName\", \"file\": \"file:line\", \"responsibility\": \"description\", \"dependencies\": [...]}
+    ],
+    \"interactions\": [
+      {\"from\": \"ModuleA\", \"to\": \"ModuleB\", \"type\": \"import|call|data-flow\", \"description\": \"...\"}
+    ],
+    \"entry_points\": [
+      {\"function\": \"main\", \"file\": \"file:line\", \"description\": \"...\"}
+    ]
+  },
+  \"function_calls\": {
+    \"call_chains\": [
+      {
+        \"chain_id\": 1,
+        \"description\": \"User authentication flow\",
+        \"sequence\": [
+          {\"function\": \"login\", \"file\": \"file:line\", \"calls\": [\"validateCredentials\", \"createSession\"]}
+        ]
+      }
+    ],
+    \"sequences\": [
+      {\"from\": \"Client\", \"to\": \"AuthService\", \"method\": \"login(username, password)\", \"returns\": \"Session\"}
+    ]
+  },
+  \"data_flow\": {
+    \"structures\": [
+      {\"name\": \"UserData\", \"stage\": \"input\", \"shape\": {\"username\": \"string\", \"password\": \"string\"}}
+    ],
+    \"transformations\": [
+      {\"from\": \"RawInput\", \"to\": \"ValidatedData\", \"transformer\": \"validateUser\", \"file\": \"file:line\"}
+    ]
+  },
+  \"conditional_logic\": {
+    \"branches\": [
+      {\"condition\": \"isAuthenticated\", \"file\": \"file:line\", \"true_path\": \"...\", \"false_path\": \"...\"}
+    ],
+    \"error_handling\": [
+      {\"error_type\": \"AuthenticationError\", \"handler\": \"handleAuthError\", \"file\": \"file:line\", \"recovery\": \"retry|fail\"}
+    ]
+  },
+  \"design_patterns\": [
+    {\"pattern\": \"Repository Pattern\", \"location\": \"src/repositories\", \"description\": \"...\"}
+  ],
+  \"recommendations\": [
+    \"Consider extracting authentication logic into separate module\",
+    \"Add error recovery for network failures\"
+  ]
+}
+
+**Critical Requirements**:
+- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
+- Focus exclusively on {FEATURE_KEYWORD} feature flow
+- Include file:line references for ALL findings
+- Extract design intent from code structure and comments
+- NO FILE WRITING - return JSON analysis only
+- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback)
+  "
+)
+```
+
+**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns
+
+---
+
+#### Phase 2b: Orchestrator Documentation Generation
+
+**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation
+
+**Input**: Agent's JSON analysis result
+
+**Process**:
+
+1. **Parse Agent Analysis**:
+   ```javascript
+   const analysis = JSON.parse(agentResult)
+   const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis
+   ```
+
+2. **Generate Mermaid Diagrams from Structured Data**:
+
+   **a) architecture-flow.md** (~3K tokens):
+   ```javascript
+   // Convert architecture.modules + architecture.interactions → Mermaid graph TD
+   const architectureMermaid = `
+   graph TD
+   ${architecture.modules.map(m => `    ${m.name}[${m.name}]`).join('\n')}
+   ${architecture.interactions.map(i => `    ${i.from} -->|${i.type}| ${i.to}`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/architecture-flow.md`,
+     content: `---
+feature: ${feature}
+level: architecture
+detail: high-level module interactions
+---
+# Architecture Flow: ${feature}
+
+## Overview
+${architecture.overview}
+
+## Module Architecture
+${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')}
+
+## Flow Diagram
+\`\`\`mermaid
+${architectureMermaid}
+\`\`\`
+
+## Key Interactions
+${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')}
+
+## Entry Points
+${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')}
+`
+   })
+   ```
+
+   **b) function-calls.md** (~5K tokens):
+   ```javascript
+   // Convert function_calls.sequences → Mermaid sequenceDiagram
+   const sequenceMermaid = `
+   sequenceDiagram
+   ${function_calls.sequences.map(s => `    ${s.from}->>${s.to}: ${s.method}`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/function-calls.md`,
+     content: `---
+feature: ${feature}
+level: function
+detail: function-level call sequences
+---
+# Function Call Chains: ${feature}
+
+## Call Sequence Diagram
+\`\`\`mermaid
+${sequenceMermaid}
+\`\`\`
+
+## Detailed Call Chains
+${function_calls.call_chains.map(chain => `
+### Chain ${chain.chain_id}: ${chain.description}
+${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n  - Calls: ${fn.calls.join(', ')}`).join('\n')}
+`).join('\n')}
+
+## Parameters & Returns
+${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')}
+`
+   })
+   ```
+
+   **c) data-flow.md** (~4K tokens):
+   ```javascript
+   // Convert data_flow.transformations → Mermaid flowchart LR
+   const dataFlowMermaid = `
+   flowchart LR
+   ${data_flow.transformations.map((t, i) => `    Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/data-flow.md`,
+     content: `---
+feature: ${feature}
+level: data
+detail: data structure transformations
+---
+# Data Flow: ${feature}
+
+## Data Transformation Diagram
+\`\`\`mermaid
+${dataFlowMermaid}
+\`\`\`
+
+## Data Structures
+${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')}
+
+## Transformations
+${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')}
+`
+   })
+   ```
+
+   **d) conditional-paths.md** (~4K tokens):
+   ```javascript
+   // Convert conditional_logic.branches → Mermaid flowchart TD
+   const conditionalMermaid = `
+   flowchart TD
+       Start[Entry Point]
+   ${conditional_logic.branches.map((b, i) => `
+       Start --> Check${i}{${b.condition}}
+       Check${i} -->|Yes| Path${i}A[${b.true_path}]
+       Check${i} -->|No| Path${i}B[${b.false_path}]
+   `).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/conditional-paths.md`,
+     content: `---
+feature: ${feature}
+level: conditional
+detail: decision trees and error paths
+---
+# Conditional Paths: ${feature}
+
+## Decision Tree
+\`\`\`mermaid
+${conditionalMermaid}
+\`\`\`
+
+## Branch Conditions
+${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n  - True: ${b.true_path}\n  - False: ${b.false_path}`).join('\n')}
+
+## Error Handling
+${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')}
+`
+   })
+   ```
+
+   **e) complete-flow.md** (~8K tokens):
+   ```javascript
+   // Integrate all Mermaid diagrams
+   Write({
+     file_path: `${CODEMAP_DIR}/complete-flow.md`,
+     content: `---
+feature: ${feature}
+level: complete
+detail: integrated multi-level view
+---
+# Complete Flow: ${feature}
+
+## Integrated Flow Diagram
+\`\`\`mermaid
+graph TB
+    subgraph Architecture
+    ${architecture.modules.map(m => `    ${m.name}[${m.name}]`).join('\n')}
+    end
+
+    subgraph "Function Calls"
+    ${function_calls.call_chains[0]?.sequence.map(fn => `    ${fn.function}`).join('\n') || ''}
+    end
+
+    subgraph "Data Flow"
+    ${data_flow.structures.map(s => `    ${s.name}[${s.name}]`).join('\n')}
+    end
+\`\`\`
+
+## Complete Trace
+[Comprehensive end-to-end documentation combining all analysis layers]
+
+## Design Patterns Identified
+${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')}
+
+## Recommendations
+${analysis.recommendations.map(r => `- ${r}`).join('\n')}
+
+## Cross-References
+- [Architecture Flow](./architecture-flow.md) - High-level module structure
+- [Function Calls](./function-calls.md) - Detailed call chains
+- [Data Flow](./data-flow.md) - Data transformation stages
+- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling
+`
+   })
+   ```
+
+3. **Write metadata.json**:
+   ```javascript
+   Write({
+     file_path: `${CODEMAP_DIR}/metadata.json`,
+     content: JSON.stringify({
+       feature: feature,
+       normalized_name: normalized_feature,
+       generated_at: new Date().toISOString(),
+       tool_used: analysis.analysis_metadata.tool_used,
+       files_analyzed: files_analyzed.map(f => f.file),
+       analysis_summary: {
+         total_files: files_analyzed.length,
+         modules_traced: architecture.modules.length,
+         functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0),
+         patterns_discovered: design_patterns.length
+       }
+     }, null, 2)
+   })
+   ```
+
+4. **Report Phase 2 Completion**:
+   ```
+   Phase 2 Complete: Code flow analysis and documentation generated
+
+   - Agent Analysis: cli-explore-agent with {TOOL}
+   - Files Analyzed: {count}
+   - Documentation Generated: 5 markdown files + metadata.json
+   - Location: {CODEMAP_DIR}
+   ```
+
+**Completion Criteria**:
+- cli-explore-agent task completed successfully with JSON result
+- 5 documentation files written with valid Mermaid diagrams
+- metadata.json written with analysis summary
+- All files properly formatted and cross-referenced
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Generate SKILL.md Index
+
+**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
+
+**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading
+
+**Steps**:
+
+1. **Verify Generated Files**:
+   ```bash
+   bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort)
+   ```
+
+2. **Read metadata.json**:
+   ```javascript
+   Read({CODEMAP_DIR}/metadata.json)
+   // Extract: feature, normalized_name, files_analyzed, analysis_summary
+   ```
+
+3. **Read File Headers** (optional, first 30 lines):
+   ```javascript
+   Read({CODEMAP_DIR}/architecture-flow.md, limit: 30)
+   Read({CODEMAP_DIR}/function-calls.md, limit: 30)
+   // Extract overview and diagram counts
+   ```
+
+4. **Generate SKILL.md Index**:
+
+   Template structure:
+   ```yaml
+   ---
+   name: codemap-{normalized_feature}
+   description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory.
+   version: 1.0.0
+   generated_at: {ISO_TIMESTAMP}
+   ---
+   # Code Flow Map: {FEATURE_KEYWORD}
+
+   ## Feature: `{FEATURE_KEYWORD}`
+
+   **Analysis Date**: {DATE}
+   **Tool Used**: {TOOL}
+   **Files Analyzed**: {COUNT}
+
+   ## Progressive Loading
+
+   ### Level 0: Quick Overview (~2K tokens)
+   - [Architecture Flow](./architecture-flow.md) - High-level module interactions
+
+   ### Level 1: Core Flows (~10K tokens)
+   - [Architecture Flow](./architecture-flow.md) - Module architecture
+   - [Function Calls](./function-calls.md) - Function call chains
+
+   ### Level 2: Complete Analysis (~20K tokens)
+   - [Architecture Flow](./architecture-flow.md)
+   - [Function Calls](./function-calls.md)
+   - [Data Flow](./data-flow.md) - Data transformations
+
+   ### Level 3: Deep Dive (~30K tokens)
+   - [Architecture Flow](./architecture-flow.md)
+   - [Function Calls](./function-calls.md)
+   - [Data Flow](./data-flow.md)
+   - [Conditional Paths](./conditional-paths.md) - Branches and error handling
+   - [Complete Flow](./complete-flow.md) - Integrated comprehensive view
+
+   ## Usage
+
+   Load this SKILL package when:
+   - Analyzing {FEATURE_KEYWORD} implementation
+   - Tracing execution flow for debugging
+   - Understanding code dependencies
+   - Planning refactoring or enhancements
+
+   ## Analysis Summary
+
+   - **Modules Traced**: {modules_traced}
+   - **Functions Traced**: {functions_traced}
+   - **Files Analyzed**: {total_files}
+
+   ## Mermaid Diagrams Included
+
+   - Architecture flow diagram (graph TD)
+   - Function call sequence diagram (sequenceDiagram)
+   - Data transformation flowchart (flowchart LR)
+   - Conditional decision tree (flowchart TD)
+   - Complete integrated diagram (graph TB)
+   ```
+
+5. **Write SKILL.md**:
+   ```javascript
+   Write({
+     file_path: `{CODEMAP_DIR}/SKILL.md`,
+     content: generatedIndexMarkdown
+   })
+   ```
+
+**Completion Criteria**:
+- SKILL.md index written
+- All documentation files verified
+- Progressive loading levels (0-3) properly structured
+- Mermaid diagram references included
+
+**TodoWrite**: Mark phase 3 completed
+
+**Final Report**:
+```
+Code Flow Mapping Complete
+
+Feature: {FEATURE_KEYWORD}
+Location: .claude/skills/codemap-{normalized_feature}/
+
+Files Generated:
+- SKILL.md (index)
+- architecture-flow.md (with Mermaid diagram)
+- function-calls.md (with Mermaid sequence diagram)
+- data-flow.md (with Mermaid flowchart)
+- conditional-paths.md (with Mermaid decision tree)
+- complete-flow.md (with integrated Mermaid diagram)
+- metadata.json
+
+Analysis:
+- Files analyzed: {count}
+- Modules traced: {count}
+- Functions traced: {count}
+
+Usage: Skill(command: "codemap-{normalized_feature}")
+```
+
+---
+
+## Implementation Details
+
+### TodoWrite Patterns
+
+**Initialization** (Before Phase 1):
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"},
+  {"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
+]})
+```
+
+**Full Path** (SKIP_GENERATION = false):
+```javascript
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...},
+  {"content": "Generate SKILL.md index", "status": "pending", ...}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "completed", ...}
+]})
+```
+
+**Skip Path** (SKIP_GENERATION = true):
+```javascript
+// After Phase 1 (skip Phase 2)
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},  // Skipped
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+```
+
+### Execution Flow
+
+**Full Path**:
+```
+User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report
+```
+
+**Skip Path**:
+```
+User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
+```
+
+### Error Handling
+
+**Phase 1 Errors**:
+- Empty feature keyword: Report error, ask user to provide feature description
+- Invalid characters: Normalize and continue
+
+**Phase 2 Errors (Agent)**:
+- Agent task fails: Retry once, report if fails again
+- No files discovered: Warn user, ask for more specific feature keyword
+- CLI failures: Agent handles internally with retries
+- Invalid Mermaid syntax: Agent validates before writing
+
+**Phase 3 Errors**:
+- Write failures: Report which files failed
+- Missing files: Note in SKILL.md, suggest regeneration
+
+---
+
+## Parameters
+
+```bash
+/memory:code-map-memory "feature-keyword" [--regenerate] [--tool <gemini|qwen>]
+```
+
+**Arguments**:
+- **"feature-keyword"**: Feature or flow to analyze (required)
+  - Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"`
+  - Can be English, Chinese, or mixed
+  - Spaces and underscores normalized to hyphens
+- **--regenerate**: Force regenerate existing codemap (deletes and recreates)
+- **--tool**: CLI tool for analysis (default: gemini)
+  - `gemini`: Comprehensive flow analysis with gemini-2.5-pro
+  - `qwen`: Alternative with coder-model
+
+---
+
+## Examples
+
+**Generated File Structure** (for all examples):
+```
+.claude/skills/codemap-{feature}/
+├── SKILL.md                    # Index (Phase 3)
+├── architecture-flow.md        # Agent (Phase 2) - High-level flow
+├── function-calls.md           # Agent (Phase 2) - Function chains
+├── data-flow.md                # Agent (Phase 2) - Data transformations
+├── conditional-paths.md        # Agent (Phase 2) - Branches & errors
+├── complete-flow.md            # Agent (Phase 2) - Integrated view
+└── metadata.json               # Agent (Phase 2)
+```
+
+### Example 1: User Authentication Flow
+
+```bash
+/memory:code-map-memory "user authentication"
+```
+
+**Workflow**:
+1. Phase 1: Normalizes to "user-authentication", checks existing codemap
+2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid
+3. Phase 3: Generates SKILL.md index with progressive loading
+
+**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata
+
+
+### Example 3: Regenerate with Qwen
+
+```bash
+/memory:code-map-memory "payment processing" --regenerate --tool qwen
+```
+
+**Workflow**:
+1. Phase 1: Deletes existing codemap due to --regenerate
+2. Phase 2: Agent uses qwen with coder-model for fresh analysis
+3. Phase 3: Generates updated SKILL.md
+
+---
+
+## Benefits
+
+- **Per-Feature SKILL**: Independent packages for each analyzed feature
+- **Specialized Agent**: cli-explore-agent with Deep Scan mode (Bash + Gemini dual-source)
+- **Professional Analysis**: Pre-defined workflow for code exploration and structure analysis
+- **Clear Separation**: Agent analyzes (JSON) → Orchestrator documents (Mermaid markdown)
+- **Multi-Level Detail**: 4 levels (architecture → function → data → conditional)
+- **Visual Flow**: Embedded Mermaid diagrams for all flow types
+- **Progressive Loading**: Token-efficient context loading (2K → 30K)
+- **Auto-Continue**: Fully autonomous 3-phase execution
+- **Smart Skip**: Detects existing codemap, 10x faster index updates
+- **CLI Integration**: Gemini/Qwen for deep semantic understanding
+
+## Architecture
+
+```
+code-map-memory (orchestrator)
+  ├─ Phase 1: Parse & Check (bash commands, skip decision)
+  ├─ Phase 2: Code Analysis & Documentation (skippable)
+  │   ├─ Phase 2a: cli-explore-agent Analysis
+  │   │   └─ Deep Scan: Bash structural + Gemini semantic → JSON
+  │   └─ Phase 2b: Orchestrator Documentation
+  │       └─ Transform JSON → 5 Mermaid markdown files + metadata.json
+  └─ Phase 3: Write SKILL.md (index generation, always runs)
+
+Benefits:
+✅ Specialized agent: cli-explore-agent with dual-source strategy (Bash + Gemini)
+✅ Professional analysis: Pre-defined Deep Scan workflow
+✅ Clear separation: Agent analyzes (JSON) → Orchestrator documents (Mermaid)
+✅ Smart skip logic: 10x faster when codemap exists
+✅ Multi-level detail: Architecture → Functions → Data → Conditionals
+
+Output: .claude/skills/codemap-{feature}/
+```

.claude/skills/command-guide/reference/commands/memory/style-skill-memory.md

@@ -0,0 +1,870 @@
+---
+name: style-skill-memory
+description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
+argument-hint: "[package-name] [--regenerate]"
+allowed-tools: Bash,Read,Write,TodoWrite
+auto-continue: true
+---
+
+# Memory: Style SKILL Memory Generator
+
+## Overview
+
+**Purpose**: Convert style reference package into SKILL memory for easy loading and context management.
+
+**Input**: Style reference package at `.workflow/reference_style/{package-name}/`
+
+**Output**: SKILL memory index at `.claude/skills/style-{package-name}/SKILL.md`
+
+**Use Case**: Load design system context when working with UI components, analyzing design patterns, or implementing style guidelines.
+
+**Key Features**:
+- Extracts primary design references (colors, typography, spacing, etc.)
+- Provides dynamic adjustment guidelines for design tokens
+- Progressive loading structure for efficient token usage
+- Interactive preview showcase
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+/memory:style-skill-memory [package-name] [--regenerate]
+
+# Arguments
+package-name    Style reference package name (required)
+--regenerate    Force regenerate SKILL.md even if it exists (optional)
+```
+
+### Usage Examples
+
+```bash
+# Generate SKILL memory for package
+/memory:style-skill-memory main-app-style-v1
+
+# Regenerate SKILL memory
+/memory:style-skill-memory main-app-style-v1 --regenerate
+
+# Package name from current directory or default
+/memory:style-skill-memory
+```
+
+---
+
+## Execution Process
+
+### Phase 1: Validate Package
+
+**Purpose**: Check if style reference package exists
+
+**TodoWrite** (First Action):
+```json
+[
+  {"content": "Validate style reference package", "status": "in_progress", "activeForm": "Validating package"},
+  {"content": "Read package data and extract design references", "status": "pending", "activeForm": "Reading package data"},
+  {"content": "Generate SKILL.md with progressive loading", "status": "pending", "activeForm": "Generating SKILL.md"}
+]
+```
+
+**Step 1: Parse Package Name**
+
+```bash
+# Get package name from argument or auto-detect
+bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//')
+```
+
+Store result as `package_name`
+
+**Step 2: Validate Package Exists**
+
+```bash
+bash(test -d .workflow/reference_style/${package_name} && echo "exists" || echo "missing")
+```
+
+**Error Handling**:
+```javascript
+if (package_not_exists) {
+  error("ERROR: Style reference package not found: ${package_name}")
+  error("HINT: Run '/workflow:ui-design:codify-style' first to create package")
+  error("Available packages:")
+  bash(ls -1 .workflow/reference_style/ 2>/dev/null || echo "  (none)")
+  exit(1)
+}
+```
+
+**Step 3: Check SKILL Already Exists**
+
+```bash
+bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "exists" || echo "missing")
+```
+
+**Decision Logic**:
+```javascript
+if (skill_exists && !regenerate_flag) {
+  echo("SKILL memory already exists for: ${package_name}")
+  echo("Use --regenerate to force regeneration")
+  exit(0)
+}
+
+if (regenerate_flag && skill_exists) {
+  echo("Regenerating SKILL memory for: ${package_name}")
+}
+```
+
+**Summary Variables**:
+- `PACKAGE_NAME`: Style reference package name
+- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}`
+- `SKILL_DIR`: `.claude/skills/style-${package_name}`
+- `REGENERATE`: `true` if --regenerate flag, `false` otherwise
+
+**TodoWrite Update**:
+```json
+[
+  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
+  {"content": "Read package data and extract design references", "status": "in_progress", "activeForm": "Reading package data"}
+]
+```
+
+---
+
+### Phase 2: Read Package Data & Extract Design References
+
+**Purpose**: Extract package information and primary design references for SKILL description generation
+
+**Step 1: Count Components**
+
+```bash
+bash(jq '.layout_templates | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
+```
+
+Store result as `component_count`
+
+**Step 2: Extract Component Types and Classification**
+
+```bash
+# Extract component names from layout templates
+bash(jq -r '.layout_templates | keys[]' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
+
+# Count universal vs specialized components
+bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
+bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null || echo 0)
+
+# Extract universal component names only
+bash(jq -r '.layout_templates | to_entries | map(select(.value.component_type == "universal")) | .[].key' .workflow/reference_style/${package_name}/layout-templates.json 2>/dev/null | head -10)
+```
+
+Store as:
+- `COMPONENT_TYPES`: List of available component types (all)
+- `UNIVERSAL_COUNT`: Number of universal (reusable) components
+- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
+- `UNIVERSAL_COMPONENTS`: List of universal component names
+
+**Step 3: Read Design Tokens**
+
+```bash
+Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
+```
+
+**Extract Primary Design References**:
+
+**Colors** (top 3-5 most important):
+```bash
+bash(jq -r '.colors | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null | head -5)
+```
+
+**Typography** (heading and body fonts):
+```bash
+bash(jq -r '.typography | to_entries | select(.key | contains("family")) | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Spacing Scale** (base spacing values):
+```bash
+bash(jq -r '.spacing | to_entries | .[0:5] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Border Radius** (base radius values):
+```bash
+bash(jq -r '.border_radius | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+**Shadows** (elevation levels):
+```bash
+bash(jq -r '.shadows | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/design-tokens.json 2>/dev/null)
+```
+
+Store extracted references as:
+- `PRIMARY_COLORS`: List of primary color tokens
+- `TYPOGRAPHY_FONTS`: Font family tokens
+- `SPACING_SCALE`: Base spacing values
+- `BORDER_RADIUS`: Radius values
+- `SHADOWS`: Shadow definitions
+
+**Step 4: Read Animation Tokens (if available)**
+
+```bash
+# Check if animation tokens exist
+bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "available" || echo "not_available")
+```
+
+If available, extract:
+```bash
+Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")
+
+# Extract primary animation values
+bash(jq -r '.duration | to_entries | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
+bash(jq -r '.easing | to_entries | .[0:3] | .[] | "\(.key): \(.value)"' .workflow/reference_style/${package_name}/animation-tokens.json 2>/dev/null)
+```
+
+Store as:
+- `ANIMATION_DURATIONS`: Animation duration tokens
+- `EASING_FUNCTIONS`: Easing function tokens
+
+**Step 5: Count Files**
+
+```bash
+bash(cd .workflow/reference_style/${package_name} && ls -1 *.json *.html *.css 2>/dev/null | wc -l)
+```
+
+Store result as `file_count`
+
+**Summary Data Collected**:
+- `COMPONENT_COUNT`: Number of components in layout templates
+- `UNIVERSAL_COUNT`: Number of universal (reusable) components
+- `SPECIALIZED_COUNT`: Number of specialized (project-specific) components
+- `COMPONENT_TYPES`: List of component types (first 10)
+- `UNIVERSAL_COMPONENTS`: List of universal component names (first 10)
+- `FILE_COUNT`: Total files in package
+- `HAS_ANIMATIONS`: Whether animation tokens are available
+- `PRIMARY_COLORS`: Primary color tokens with values
+- `TYPOGRAPHY_FONTS`: Font family tokens
+- `SPACING_SCALE`: Base spacing scale
+- `BORDER_RADIUS`: Border radius values
+- `SHADOWS`: Shadow definitions
+- `ANIMATION_DURATIONS`: Animation durations (if available)
+- `EASING_FUNCTIONS`: Easing functions (if available)
+
+**TodoWrite Update**:
+```json
+[
+  {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
+  {"content": "Generate SKILL.md with progressive loading", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]
+```
+
+---
+
+### Phase 3: Generate SKILL.md
+
+**Purpose**: Create SKILL memory index with progressive loading structure and design references
+
+**Step 1: Create SKILL Directory**
+
+```bash
+bash(mkdir -p .claude/skills/style-${package_name})
+```
+
+**Step 2: Generate Intelligent Description**
+
+**Format**:
+```
+{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
+```
+
+**Key Elements**:
+- **Universal Count**: Emphasize available reusable layout templates
+- **Project Independence**: Clearly state project-independent nature
+- **Specialized Exclusion**: Mention excluded project-specific components
+- **Path Reference**: Precise package location
+- **Trigger Keywords**: reusable UI components, design tokens, layout patterns, visual consistency
+- **Action Coverage**: working with, analyzing, implementing
+
+**Example**:
+```
+main-app-style-v1 project-independent design system with 5 universal layout templates and interactive preview (located at .workflow/reference_style/main-app-style-v1). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes 3 project-specific components.
+```
+
+**Step 3: Write SKILL.md**
+
+Use Write tool to generate SKILL.md with the following complete content:
+
+```markdown
+---
+name: style-{package_name}
+description: {intelligent description from Step 2}
+---
+
+# {Package Name} Style SKILL Package
+
+## Documentation: `../../../.workflow/reference_style/{package_name}/`
+
+## Package Overview
+
+**Project-independent style reference package** extracted from codebase with reusable design patterns, tokens, and interactive preview.
+
+**Package Details**:
+- Package: {package_name}
+- Layout Templates: {component_count} total
+  - **Universal Components**: {universal_count} (reusable, project-independent)
+  - **Specialized Components**: {specialized_count} (project-specific, excluded from reference)
+- Universal Component Types: {comma-separated list of UNIVERSAL_COMPONENTS}
+- Files: {file_count}
+- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
+
+**⚠️ IMPORTANT - Project Independence**:
+This SKILL package represents a **pure style system** independent of any specific project implementation:
+- **Universal components** are generic, reusable patterns (buttons, inputs, cards, navigation)
+- **Specialized components** are project-specific implementations (excluded from this reference)
+- All design tokens and layout patterns are extracted for **reference purposes only**
+- Adapt and customize these references based on your project's specific requirements
+
+---
+
+## ⚡ Primary Design References
+
+**IMPORTANT**: These are **reference values** extracted from the codebase. They should be **dynamically adjusted** based on your specific design needs, not treated as fixed constraints.
+
+### 🎨 Colors
+
+{FOR each color in PRIMARY_COLORS:
+  - **{color.key}**: `{color.value}`
+}
+
+**Usage Guidelines**:
+- These colors establish the foundation of the design system
+- Adjust saturation, lightness, or hue based on:
+  - Brand requirements and accessibility needs
+  - Context (light/dark mode, high-contrast themes)
+  - User feedback and A/B testing results
+- Use color theory principles to maintain harmony when modifying
+
+### 📝 Typography
+
+{FOR each font in TYPOGRAPHY_FONTS:
+  - **{font.key}**: `{font.value}`
+}
+
+**Usage Guidelines**:
+- Font families can be substituted based on:
+  - Brand identity and design language
+  - Performance requirements (web fonts vs. system fonts)
+  - Accessibility and readability considerations
+  - Platform-specific availability
+- Maintain hierarchy and scale relationships when changing fonts
+
+### 📏 Spacing Scale
+
+{FOR each spacing in SPACING_SCALE:
+  - **{spacing.key}**: `{spacing.value}`
+}
+
+**Usage Guidelines**:
+- Spacing values form a consistent rhythm system
+- Adjust scale based on:
+  - Target device (mobile vs. desktop vs. tablet)
+  - Content density requirements
+  - Component-specific needs (compact vs. comfortable layouts)
+- Maintain proportional relationships when scaling
+
+### 🔲 Border Radius
+
+{FOR each radius in BORDER_RADIUS:
+  - **{radius.key}**: `{radius.value}`
+}
+
+**Usage Guidelines**:
+- Border radius affects visual softness and modernity
+- Adjust based on:
+  - Design aesthetic (sharp vs. rounded vs. pill-shaped)
+  - Component type (buttons, cards, inputs have different needs)
+  - Platform conventions (iOS vs. Android vs. Web)
+
+### 🌫️ Shadows
+
+{FOR each shadow in SHADOWS:
+  - **{shadow.key}**: `{shadow.value}`
+}
+
+**Usage Guidelines**:
+- Shadows create elevation and depth perception
+- Adjust based on:
+  - Material design depth levels
+  - Light/dark mode contexts
+  - Performance considerations (complex shadows impact rendering)
+  - Visual hierarchy needs
+
+{IF HAS_ANIMATIONS:
+### ⏱️ Animation & Timing
+
+**Durations**:
+{FOR each duration in ANIMATION_DURATIONS:
+  - **{duration.key}**: `{duration.value}`
+}
+
+**Easing Functions**:
+{FOR each easing in EASING_FUNCTIONS:
+  - **{easing.key}**: `{easing.value}`
+}
+
+**Usage Guidelines**:
+- Animation timing affects perceived responsiveness and polish
+- Adjust based on:
+  - User expectations and platform conventions
+  - Accessibility preferences (reduced motion)
+  - Animation type (micro-interactions vs. page transitions)
+  - Performance constraints (mobile vs. desktop)
+}
+
+---
+
+## 🎯 Design Adaptation Strategies
+
+### When to Adjust Design References
+
+**Brand Alignment**:
+- Modify colors to match brand identity and guidelines
+- Adjust typography to reflect brand personality
+- Tune spacing and radius to align with brand aesthetic
+
+**Accessibility Requirements**:
+- Increase color contrast ratios for WCAG compliance
+- Adjust font sizes and spacing for readability
+- Modify animation durations for reduced-motion preferences
+
+**Platform Optimization**:
+- Adapt spacing for mobile touch targets (min 44x44px)
+- Adjust shadows and radius for platform conventions
+- Optimize animation performance for target devices
+
+**Context-Specific Needs**:
+- Dark mode: Adjust colors, shadows, and contrasts
+- High-density displays: Fine-tune spacing and sizing
+- Responsive design: Scale tokens across breakpoints
+
+### How to Apply Adjustments
+
+1. **Identify Need**: Determine which tokens need adjustment based on your specific requirements
+2. **Maintain Relationships**: Preserve proportional relationships between related tokens
+3. **Test Thoroughly**: Validate changes across components and use cases
+4. **Document Changes**: Track modifications and rationale for team alignment
+5. **Iterate**: Refine based on user feedback and testing results
+
+---
+
+## Progressive Loading
+
+### Level 0: Design Tokens (~5K tokens)
+
+Essential design token system for consistent styling.
+
+**Files**:
+- [Design Tokens](../../../.workflow/reference_style/{package_name}/design-tokens.json) - Colors, typography, spacing, shadows, borders
+
+**Use when**: Quick token reference, applying consistent styles, color/typography queries
+
+---
+
+### Level 1: Universal Layout Templates (~12K tokens)
+
+**Project-independent** component layout patterns for reusable UI elements.
+
+**Files**:
+- Level 0 files
+- [Layout Templates](../../../.workflow/reference_style/{package_name}/layout-templates.json) - Component structures with HTML/CSS patterns
+
+**⚠️ Reference Strategy**:
+- **Only reference components with `component_type: "universal"`** - these are reusable, project-independent patterns
+- **Ignore components with `component_type: "specialized"`** - these are project-specific implementations
+- Universal components include: buttons, inputs, forms, cards, navigation, modals, etc.
+- Use universal patterns as **reference templates** to adapt for your specific project needs
+
+**Use when**: Building components, understanding component architecture, implementing layouts
+
+---
+
+### Level 2: Complete System (~20K tokens)
+
+Full design system with animations and interactive preview.
+
+**Files**:
+- All Level 1 files
+- [Animation Tokens](../../../.workflow/reference_style/{package_name}/animation-tokens.json) - Animation durations, easing, transitions _(if available)_
+- [Preview HTML](../../../.workflow/reference_style/{package_name}/preview.html) - Interactive showcase (reference only)
+- [Preview CSS](../../../.workflow/reference_style/{package_name}/preview.css) - Showcase styling (reference only)
+
+**Use when**: Comprehensive analysis, animation development, complete design system understanding
+
+---
+
+## Interactive Preview
+
+**Location**: `.workflow/reference_style/{package_name}/preview.html`
+
+**View in Browser**:
+```bash
+cd .workflow/reference_style/{package_name}
+python -m http.server 8080
+# Open http://localhost:8080/preview.html
+```
+
+**Features**:
+- Color palette swatches with values
+- Typography scale and combinations
+- All components with variants and states
+- Spacing, radius, shadow visual examples
+- Interactive state demonstrations
+- Usage code snippets
+
+---
+
+## Usage Guidelines
+
+### Loading Levels
+
+**Level 0** (5K): Design tokens only
+```
+Load Level 0 for design token reference
+```
+
+**Level 1** (12K): Tokens + layout templates
+```
+Load Level 1 for layout templates and design tokens
+```
+
+**Level 2** (20K): Complete system with animations and preview
+```
+Load Level 2 for complete design system with preview reference
+```
+
+### Common Use Cases
+
+**Implementing UI Components**:
+- Load Level 1 for universal layout templates
+- **Only reference components with `component_type: "universal"`** in layout-templates.json
+- Apply design tokens from design-tokens.json
+- Adapt patterns to your project's specific requirements
+
+**Ensuring Style Consistency**:
+- Load Level 0 for design tokens
+- Use design-tokens.json for colors, typography, spacing
+- Check preview.html for visual reference (universal components only)
+
+**Analyzing Component Patterns**:
+- Load Level 2 for complete analysis
+- Review layout-templates.json for component architecture
+- **Filter for `component_type: "universal"` to exclude project-specific implementations**
+- Check preview.html for implementation examples
+
+**Animation Development**:
+- Load Level 2 for animation tokens (if available)
+- Reference animation-tokens.json for durations and easing
+- Apply consistent timing and transitions
+
+**⚠️ Critical Usage Rule**:
+This is a **project-independent style reference system**. When working with layout-templates.json:
+- **USE**: Components marked `component_type: "universal"` as reusable reference patterns
+- **IGNORE**: Components marked `component_type: "specialized"` (project-specific implementations)
+- **ADAPT**: All patterns should be customized for your specific project needs
+
+---
+
+## Package Structure
+
+```
+.workflow/reference_style/{package_name}/
+├── layout-templates.json   # Layout templates from codebase
+├── design-tokens.json     # Design token system
+├── animation-tokens.json  # Animation tokens (optional)
+├── preview.html          # Interactive showcase
+└── preview.css           # Showcase styling
+```
+
+---
+
+## Regeneration
+
+To update this SKILL memory after package changes:
+
+```bash
+/memory:style-skill-memory {package_name} --regenerate
+```
+
+---
+
+## Related Commands
+
+**Generate Package**:
+```bash
+/workflow:ui-design:codify-style --source ./src --package-name {package_name}
+```
+
+**Update Package**:
+Re-run codify-style with same package name to update extraction.
+```
+
+**Step 4: Verify SKILL.md Created**
+
+```bash
+bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed")
+```
+
+**TodoWrite Update**:
+```json
+[
+  {"content": "Validate style reference package", "status": "completed", "activeForm": "Validating package"},
+  {"content": "Read package data and extract design references", "status": "completed", "activeForm": "Reading package data"},
+  {"content": "Generate SKILL.md with progressive loading", "status": "completed", "activeForm": "Generating SKILL.md"}
+]
+```
+
+**Final Action**: Report completion summary to user
+
+---
+
+## Completion Message
+
+Display extracted primary design references to user:
+
+```
+✅ SKILL memory generated successfully!
+
+Package: {package_name}
+SKILL Location: .claude/skills/style-{package_name}/SKILL.md
+
+📦 Package Details:
+- Layout Templates: {component_count} total
+  - Universal (reusable): {universal_count}
+  - Specialized (project-specific): {specialized_count}
+- Universal Component Types: {show first 5 UNIVERSAL_COMPONENTS, then "+ X more"}
+- Files: {file_count}
+- Animation Tokens: {has_animations ? "✓ Available" : "Not available"}
+
+🎨 Primary Design References Extracted:
+{IF PRIMARY_COLORS exists:
+Colors:
+  {show first 3 PRIMARY_COLORS with key: value}
+  {if more than 3: + X more colors}
+}
+
+{IF TYPOGRAPHY_FONTS exists:
+Typography:
+  {show all TYPOGRAPHY_FONTS}
+}
+
+{IF SPACING_SCALE exists:
+Spacing Scale:
+  {show first 3 SPACING_SCALE items}
+  {if more than 3: + X more spacing tokens}
+}
+
+{IF BORDER_RADIUS exists:
+Border Radius:
+  {show all BORDER_RADIUS}
+}
+
+{IF HAS_ANIMATIONS:
+Animation:
+  Durations: {count ANIMATION_DURATIONS} tokens
+  Easing: {count EASING_FUNCTIONS} functions
+}
+
+⚡ Progressive Loading Levels:
+- Level 0: Design Tokens (~5K tokens)
+- Level 1: Tokens + Layout Templates (~12K tokens)
+- Level 2: Complete System (~20K tokens)
+
+💡 Usage:
+Load design system context when working with:
+- UI component implementation
+- Layout pattern analysis
+- Design token application
+- Style consistency validation
+
+⚠️ IMPORTANT - Project Independence:
+This is a **project-independent style reference system**:
+- Only use universal components (component_type: "universal") as reference patterns
+- Ignore specialized components (component_type: "specialized") - they are project-specific
+- The extracted design references are REFERENCE VALUES, not fixed constraints
+- Dynamically adjust colors, spacing, typography, and other tokens based on:
+  - Brand requirements and accessibility needs
+  - Platform-specific conventions and optimizations
+  - Context (light/dark mode, responsive breakpoints)
+  - User feedback and testing results
+
+See SKILL.md for detailed adjustment guidelines and component filtering instructions.
+
+🎯 Preview:
+Open interactive showcase:
+  file://{absolute_path}/.workflow/reference_style/{package_name}/preview.html
+
+📋 Next Steps:
+1. Load appropriate level based on your task context
+2. Review Primary Design References section for key design tokens
+3. Apply design tokens with dynamic adjustments as needed
+4. Reference layout-templates.json for component structures
+5. Use Design Adaptation Strategies when modifying tokens
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Package not found | Invalid package name or package doesn't exist | Run codify-style first to create package |
+| SKILL already exists | SKILL.md already generated | Use --regenerate to force regeneration |
+| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
+| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **Check Before Generate**: Verify package exists before attempting SKILL generation
+2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
+3. **Extract Primary References**: Always extract and display key design values (colors, typography, spacing, border radius, shadows, animations)
+4. **Include Adjustment Guidance**: Provide clear guidelines on when and how to dynamically adjust design tokens
+5. **Progressive Loading**: Always include all 3 levels (0-2) with clear token estimates
+6. **Intelligent Description**: Extract component count and key features from metadata
+
+### SKILL Description Format
+
+**Template**:
+```
+{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
+```
+
+**Required Elements**:
+- Package name
+- Universal layout template count (emphasize reusability)
+- Project independence statement
+- Specialized component exclusion notice
+- Location (full path)
+- Trigger keywords (reusable UI components, design tokens, layout patterns, visual consistency)
+- Action verbs (working with, analyzing, implementing)
+
+### Primary Design References Extraction
+
+**Required Data Extraction** (from design-tokens.json):
+- Colors: Primary, secondary, accent colors (top 3-5)
+- Typography: Font families for headings and body text
+- Spacing Scale: Base spacing values (xs, sm, md, lg, xl)
+- Border Radius: All radius tokens
+- Shadows: Shadow definitions (top 3 elevation levels)
+
+**Component Classification Extraction** (from layout-templates.json):
+- Universal Count: Number of components with `component_type: "universal"`
+- Specialized Count: Number of components with `component_type: "specialized"`
+- Universal Component Names: List of universal component names (first 10)
+
+**Optional Data Extraction** (from animation-tokens.json if available):
+- Animation Durations: All duration tokens
+- Easing Functions: Top 3 easing functions
+
+**Extraction Format**:
+Use `jq` to extract tokens from JSON files. Each token should include key and value.
+For component classification, filter by `component_type` field.
+
+### Dynamic Adjustment Guidelines
+
+**Include in SKILL.md**:
+1. **Usage Guidelines per Category**: Specific guidance for each token category
+2. **Adjustment Strategies**: When to adjust design references
+3. **Practical Examples**: Context-specific adaptation scenarios
+4. **Best Practices**: How to maintain design system coherence while adjusting
+
+### Progressive Loading Structure
+
+**Level 0** (~5K tokens):
+- design-tokens.json
+
+**Level 1** (~12K tokens):
+- Level 0 files
+- layout-templates.json
+
+**Level 2** (~20K tokens):
+- Level 1 files
+- animation-tokens.json (if exists)
+- preview.html
+- preview.css
+
+---
+
+## Benefits
+
+- **Project Independence**: Clear separation between universal (reusable) and specialized (project-specific) components
+- **Component Filtering**: Automatic classification helps identify which patterns are truly reusable
+- **Fast Context Loading**: Progressive levels for efficient token usage
+- **Primary Design References**: Extracted key design values (colors, typography, spacing, etc.) displayed prominently
+- **Dynamic Adjustment Guidance**: Clear instructions on when and how to adjust design tokens
+- **Intelligent Triggering**: Keywords optimize SKILL activation
+- **Complete Reference**: All package files accessible through SKILL
+- **Easy Regeneration**: Simple --regenerate flag for updates
+- **Clear Structure**: Organized levels by use case with component type filtering
+- **Practical Usage Guidelines**: Context-specific adjustment strategies and component selection criteria
+
+---
+
+## Architecture
+
+```
+style-skill-memory
+  ├─ Phase 1: Validate
+  │   ├─ Parse package name from argument or auto-detect
+  │   ├─ Check package exists in .workflow/reference_style/
+  │   └─ Check if SKILL already exists (skip if exists and no --regenerate)
+  │
+  ├─ Phase 2: Read Package Data & Extract Primary References
+  │   ├─ Count components from layout-templates.json
+  │   ├─ Extract component types list
+  │   ├─ Extract primary colors from design-tokens.json (top 3-5)
+  │   ├─ Extract typography (font families)
+  │   ├─ Extract spacing scale (base values)
+  │   ├─ Extract border radius tokens
+  │   ├─ Extract shadow definitions (top 3)
+  │   ├─ Extract animation tokens (if available)
+  │   └─ Count total files in package
+  │
+  └─ Phase 3: Generate SKILL.md
+      ├─ Create SKILL directory
+      ├─ Generate intelligent description with keywords
+      ├─ Write SKILL.md with complete structure:
+      │   ├─ Package Overview
+      │   ├─ Primary Design References
+      │   │   ├─ Colors with usage guidelines
+      │   │   ├─ Typography with usage guidelines
+      │   │   ├─ Spacing with usage guidelines
+      │   │   ├─ Border Radius with usage guidelines
+      │   │   ├─ Shadows with usage guidelines
+      │   │   └─ Animation & Timing (if available)
+      │   ├─ Design Adaptation Strategies
+      │   │   ├─ When to adjust design references
+      │   │   └─ How to apply adjustments
+      │   ├─ Progressive Loading (3 levels)
+      │   ├─ Interactive Preview
+      │   ├─ Usage Guidelines
+      │   ├─ Package Structure
+      │   ├─ Regeneration
+      │   └─ Related Commands
+      ├─ Verify SKILL.md created successfully
+      └─ Display completion message with extracted design references
+
+Data Flow:
+  design-tokens.json → jq extraction → PRIMARY_COLORS, TYPOGRAPHY_FONTS,
+                                       SPACING_SCALE, BORDER_RADIUS, SHADOWS
+  animation-tokens.json → jq extraction → ANIMATION_DURATIONS, EASING_FUNCTIONS
+  layout-templates.json → jq extraction → COMPONENT_COUNT, UNIVERSAL_COUNT,
+                                         SPECIALIZED_COUNT, UNIVERSAL_COMPONENTS
+                       → component_type filtering → Universal vs Specialized classification
+
+  Extracted data → SKILL.md generation → Primary Design References section
+                                      → Component Classification section
+                                      → Dynamic Adjustment Guidelines
+                                      → Project Independence warnings
+                                      → Completion message display
+```

.claude/skills/command-guide/reference/commands/workflow/brainstorm/auto-parallel.md

@@ -9,22 +9,32 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
+**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), coordinating specialized commands/agents through task attachment model.
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- Task agent execution **attaches analysis tasks** to orchestrator's TodoWrite
+- Phase 1: artifacts command attaches its internal tasks (Phase 1-5)
+- Phase 2: N conceptual-planning-agent tasks attached in parallel
+- Phase 3: synthesis command attaches its internal tasks
+- Orchestrator **executes these attached tasks** sequentially (Phase 1, 3) or in parallel (Phase 2)
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
 
 **Execution Model - Auto-Continue Workflow**:
 
 This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
 
 1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
-2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
-3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
-4. **Phase 3 executes** → Synthesis command → Reports final summary
+2. **Phase 1 executes** → artifacts command (tasks ATTACHED) → Auto-continues
+3. **Phase 2 executes** → Parallel role agents (N tasks ATTACHED concurrently) → Auto-continues
+4. **Phase 3 executes** → Synthesis command (tasks ATTACHED) → Reports final summary
 
 **Auto-Continue Mechanism**:
-- TodoList tracks current phase status
-- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
-- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
-- Progress updates shown at each phase for visibility
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When Phase 1 (artifacts) finishes executing, automatically load roles and launch Phase 2 agents
+- When Phase 2 (all agents) finishes executing, automatically execute Phase 3 synthesis
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -32,23 +42,26 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
 3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite after every phase completion
-6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **Task Attachment Model**: SlashCommand and Task invocations **attach** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
+8. **Parallel Execution**: Phase 2 attaches multiple agent tasks simultaneously for concurrent execution
 
 ## Usage
 
 ```bash
-/workflow:brainstorm:auto-parallel "<topic>" [--count N]
+/workflow:brainstorm:auto-parallel "<topic>" [--count N] [--style-skill package-name]
 ```
 
 **Recommended Structured Format**:
 ```bash
-/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
+/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name]
 ```
 
 **Parameters**:
 - `topic` (required): Topic or challenge description (structured format recommended)
 - `--count N` (optional): Number of roles to select (default: 3, max: 9)
+- `--style-skill package-name` (optional): Style SKILL package to load for UI design (located at `.claude/skills/style-{package-name}/`)
 
 ## 3-Phase Execution
 
@@ -74,15 +87,37 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 - workflow-session.json contains selected_roles[] (metadata only, no content duplication)
 - Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
 
-**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1.1: Topic analysis and question generation (artifacts)", "status": "in_progress", "activeForm": "Analyzing topic"},
+  {"content": "Phase 1.2: Role selection and user confirmation (artifacts)", "status": "pending", "activeForm": "Selecting roles"},
+  {"content": "Phase 1.3: Role questions and user decisions (artifacts)", "status": "pending", "activeForm": "Collecting role questions"},
+  {"content": "Phase 1.4: Conflict detection and resolution (artifacts)", "status": "pending", "activeForm": "Resolving conflicts"},
+  {"content": "Phase 1.5: Guidance specification generation (artifacts)", "status": "pending", "activeForm": "Generating guidance"},
+  {"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
 
-**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
+**Note**: SlashCommand invocation **attaches** artifacts' 5 internal tasks. Orchestrator **executes** these tasks sequentially.
 
-**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
-- Marking parent task "Execute artifacts..." as in_progress
-- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
-- PRESERVING all other auto-parallel tasks (role agents, synthesis)
-- When artifacts Phase 5 completes, marking parent task as completed
+**Next Action**: Tasks attached → **Execute Phase 1.1-1.5** sequentially
+
+**TodoWrite Update (Phase 1 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed to summary.
+
+**After Phase 1**: Auto-continue to Phase 2 (parallel role agent execution)
 
 ---
 
@@ -116,6 +151,12 @@ TOPIC: {user-provided-topic}
    - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context (contains original user prompt as PRIMARY reference)
 
+4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists)
+   - Action: Load style SKILL package for design system reference
+   - Command: Read(.claude/skills/style-{style_skill_package}/SKILL.md) AND Read(.workflow/reference_style/{style_skill_package}/design-tokens.json)
+   - Output: style_skill_content, design_tokens
+   - Usage: Apply design tokens in ui-designer analysis and artifacts
+
 ## Analysis Requirements
 **Primary Reference**: Original user prompt from workflow-session.json is authoritative
 **Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
@@ -143,8 +184,9 @@ TOPIC: {user-provided-topic}
 
 **Parallel Execution**:
 - Launch N agents simultaneously (one message with multiple Task calls)
+- Each agent task **attached** to orchestrator's TodoWrite
+- All agents execute concurrently, each attaching their own analysis sub-tasks
 - Each agent operates independently reading same guidance-specification.md
-- All agents update progress concurrently
 
 **Input**:
 - `selected_roles[]` from Phase 1
@@ -158,7 +200,33 @@ TOPIC: {user-provided-topic}
 - **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
 - All N role analyses completed
 
-**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
+**TodoWrite Update (Phase 2 agents invoked - tasks attached in parallel)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2.1: Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "Phase 2.2: Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Phase 2.3: Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Multiple Task invocations **attach** N role analysis tasks simultaneously. Orchestrator **executes** these tasks in parallel.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.N** concurrently
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 2 parallel tasks completed and collapsed to summary.
 
 **After Phase 2**: Auto-continue to Phase 3 (synthesis)
 
@@ -180,7 +248,33 @@ TOPIC: {user-provided-topic}
 - `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
 - Synthesis references all role analyses
 
-**TodoWrite**: Mark phase 3 completed
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3.1: Load role analysis files (synthesis)", "status": "in_progress", "activeForm": "Loading role analyses"},
+  {"content": "Phase 3.2: Integrate insights across roles (synthesis)", "status": "pending", "activeForm": "Integrating insights"},
+  {"content": "Phase 3.3: Generate synthesis specification (synthesis)", "status": "pending", "activeForm": "Generating synthesis"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** synthesis' internal tasks. Orchestrator **executes** these tasks sequentially.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "completed", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 **Return to User**:
 ```
@@ -195,49 +289,49 @@ Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
-  {"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
-  {"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
-  // Role agent tasks added dynamically after Phase 1 based on selected_roles count
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for parallel brainstorming workflow with interactive framework generation and concurrent role analysis.
 
-// After Phase 1 (artifacts completes, roles loaded)
-// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
-TodoWrite({todos: [
-  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
-  {"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
-  {"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
-  // ... (N role tasks based on --count parameter)
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+### Key Principles
 
-// After Phase 2 (all agents launched in parallel)
-TodoWrite({todos: [
-  // ... previous completed tasks
-  {"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
-  // ... (all N agents in_progress simultaneously)
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+1. **Task Attachment** (when SlashCommand/Task invoked):
+   - Sub-command's or agent's internal tasks are **attached** to orchestrator's TodoWrite
+   - Phase 1: `/workflow:brainstorm:artifacts` attaches 5 internal tasks (Phase 1.1-1.5)
+   - Phase 2: Multiple `Task(conceptual-planning-agent)` calls attach N role analysis tasks simultaneously
+   - Phase 3: `/workflow:brainstorm:synthesis` attaches 3 internal tasks (Phase 3.1-3.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks (sequentially for Phase 1, 3; in parallel for Phase 2)
 
-// After Phase 2 (all agents complete)
-TodoWrite({todos: [
-  // ... previous completed tasks
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
-  {"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
-]})
-```
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 1.1-1.5 collapse to "Execute artifacts interactive framework generation: completed"
+   - Phase 2: Multiple role tasks collapse to "Execute parallel role analysis: completed"
+   - Phase 3: Synthesis tasks collapse to "Execute synthesis integration: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase 1 invoked (artifacts tasks ATTACHED) → Artifacts sub-tasks executed → Phase 1 completed (tasks COLLAPSED) → Phase 2 invoked (N role tasks ATTACHED in parallel) → Role analyses executed concurrently → Phase 2 completed (tasks COLLAPSED) → Phase 3 invoked (synthesis tasks ATTACHED) → Synthesis sub-tasks executed → Phase 3 completed (tasks COLLAPSED) → Workflow complete.
+
+### Brainstorming Workflow Specific Features
+
+- **Phase 1**: Interactive framework generation with user Q&A (SlashCommand attachment)
+- **Phase 2**: Parallel role analysis execution with N concurrent agents (Task agent attachments)
+- **Phase 3**: Cross-role synthesis integration (SlashCommand attachment)
+- **Dynamic Role Count**: `--count N` parameter determines number of Phase 2 parallel tasks (default: 3, max: 9)
+- **Mixed Execution**: Sequential (Phase 1, 3) and Parallel (Phase 2) task execution
+
+**Benefits**:
+- Real-time visibility into attached tasks during execution
+- Clean orchestrator-level summary after tasks complete
+- Clear mental model: SlashCommand/Task = attach tasks, not delegate work
+- Parallel execution support for concurrent role analysis
+- Dynamic attachment/collapse maintains clarity
+
+**Note**: See individual Phase descriptions (Phase 1, 2, 3) for detailed TodoWrite Update examples with full JSON structures.
 
 ## Input Processing
 
@@ -255,6 +349,34 @@ ELSE:
 EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 ```
 
+**Style-Skill Parameter Parsing**:
+```javascript
+// Extract --style-skill from user input
+IF user_input CONTAINS "--style-skill":
+    EXTRACT style_skill_name FROM "--style-skill package-name" pattern
+
+    // Validate SKILL package exists
+    skill_path = ".claude/skills/style-{style_skill_name}/SKILL.md"
+    IF file_exists(skill_path):
+        style_skill_package = style_skill_name
+        style_reference_path = ".workflow/reference_style/{style_skill_name}"
+        echo("✓ Style SKILL package found: style-{style_skill_name}")
+        echo("  Design reference: {style_reference_path}")
+    ELSE:
+        echo("⚠ WARNING: Style SKILL package not found: {style_skill_name}")
+        echo("  Expected location: {skill_path}")
+        echo("  Continuing without style reference...")
+        style_skill_package = null
+ELSE:
+    style_skill_package = null
+    echo("No style-skill specified, ui-designer will use default workflow")
+
+// Store for Phase 2 ui-designer context
+CONTEXT_VARS:
+    - style_skill_package: {style_skill_package}
+    - style_reference_path: {style_reference_path}
+```
+
 **Topic Structuring**:
 1. **Already Structured** → Pass directly to artifacts
    ```
@@ -287,15 +409,17 @@ EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 
 **Phase 1 Output**:
 - `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
-- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
+- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
 
 **Phase 2 Output**:
 - `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
+- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
 
 **Phase 3 Output**:
 - `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
 
 **⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
+**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.claude/skills/style-{package-name}/`
 
 ## Available Roles
 

.claude/skills/command-guide/reference/commands/workflow/lite-plan.md

@@ -0,0 +1,962 @@
+---
+name: lite-plan
+description: Lightweight interactive planning and execution workflow with in-memory planning, code exploration, and immediate execution after user confirmation
+argument-hint: "[--tool claude|gemini|qwen|codex] [--quick] \"task description\"|file.md"
+allowed-tools: TodoWrite(*), Task(*), Bash(*), AskUserQuestion(*)
+timeout: 180000
+color: cyan
+---
+
+# Workflow Lite-Plan Command (/workflow:lite-plan)
+
+## Overview
+
+Intelligent lightweight planning and execution command with dynamic workflow adaptation based on task complexity.
+
+**Key Characteristics**:
+- Dynamic Workflow: Automatically decides whether to use exploration, clarification, and detailed planning
+- Smart Exploration: Calls cli-explore-agent only when task requires codebase context
+- Interactive Clarification: Asks user for more information after exploration if needed
+- Adaptive Planning: Simple tasks get direct planning, complex tasks use cli-planning-agent
+- Two-Dimensional Confirmation: User confirms task + selects execution method in one step
+- Direct Execution: Immediately starts execution (agent or CLI) after confirmation
+- Live Progress Tracking: Uses TodoWrite to track execution progress in real-time
+
+## Core Functionality
+
+- **Intelligent Task Analysis**: Automatically determines if exploration/planning agents are needed
+- **Dynamic Exploration**: Calls cli-explore-agent only when task requires codebase understanding
+- **Interactive Clarification**: Asks follow-up questions after exploration to gather missing information
+- **Adaptive Planning**:
+  - Simple tasks: Direct planning by current Claude
+  - Complex tasks: Delegates to cli-planning-agent for detailed breakdown
+- **Two-Dimensional Confirmation**: Single user interaction for task approval + execution method selection
+- **Direct Execution**: Immediate dispatch to selected execution method (agent or CLI)
+- **Live Progress Tracking**: Real-time TodoWrite updates during execution
+
+## Comparison with Other Commands
+
+| Feature | lite-plan | /cli:mode:plan | /workflow:plan |
+|---------|-----------|----------------|----------------|
+| Workflow Adaptation | Dynamic (intelligent) | Fixed | Fixed |
+| Code Exploration | Smart (when needed) | No | Always (context-search) |
+| Clarification | Yes (interactive) | No | No |
+| Planning Strategy | Adaptive (simple/complex) | Fixed template | Agent-based |
+| User Interaction | Two-dimensional | No | Minimal |
+| Direct Execution | Yes (immediate) | Yes (immediate) | No (requires /workflow:execute) |
+| Progress Tracking | Yes (TodoWrite live) | No | Yes (session-based) |
+| Execution Time | Fast (1-3 min) | Fast (2-5 min) | Slow (5-10 min) |
+| Tool Selection | User choice | --tool flag | Fixed (agent only) |
+| File Artifacts | No | No | Yes (IMPL_PLAN.md + JSON) |
+
+## Usage
+
+### Command Syntax
+```bash
+/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
+
+# Flags
+--tool <tool-name>         Preset CLI tool (claude|gemini|qwen|codex); if not provided, user selects during confirmation
+--quick                    Skip code exploration phase (fast mode, completes within 60 seconds)
+
+# Arguments
+<task-description>         Task description or path to .md file (required)
+```
+
+### Usage Examples
+```bash
+# Standard planning with full interaction
+/workflow:lite-plan "Implement user authentication with JWT tokens"
+# -> Shows plan, user confirms, selects tool, immediate execution
+
+# Quick mode with preset tool
+/workflow:lite-plan --quick --tool gemini "Refactor logging module for better performance"
+# -> Skips exploration, user confirms plan, executes with Gemini
+
+# Codex direct execution preset
+/workflow:lite-plan --tool codex "Add unit tests for authentication service"
+# -> User only confirms plan, executes with Codex immediately
+
+# Agent mode with Claude
+/workflow:lite-plan "Design new API endpoints for payment processing"
+# -> User selects Claude agent, immediate execution
+```
+
+## Execution Process
+
+### Workflow Overview
+
+```
+User Input ("/workflow:lite-plan \"task\"")
+    |
+    v
+[Phase 1] Task Analysis & Exploration Decision (10-20 seconds)
+    -> Analyze task description
+    -> Decision: Need exploration? (Yes/No/--quick override)
+    -> If Yes: Launch cli-explore-agent
+    -> Output: exploration findings (if performed)
+    |
+    v
+[Phase 2] Clarification (Optional, user interaction)
+    -> If exploration revealed ambiguities or missing info
+    -> AskUserQuestion: Gather clarifications
+    -> Update task context with user responses
+    -> If no clarification needed: Skip to Phase 3
+    |
+    v
+[Phase 3] Complexity Assessment & Planning (20-60 seconds)
+    -> Assess task complexity (Low/Medium/High)
+    -> Decision: Planning strategy
+       - Low: Direct planning (current Claude)
+       - Medium/High: Delegate to cli-planning-agent
+    -> Output: Task breakdown with execution approach
+    |
+    v
+[Phase 4] Task Confirmation & Execution Selection (User interaction)
+    -> Display task breakdown and approach
+    -> AskUserQuestion: Two dimensions
+       1. Confirm task (Yes/Modify/Cancel)
+       2. Execution method (Direct/CLI)
+    -> If confirmed: Proceed to Phase 5
+    -> If modify: Re-run planning with feedback
+    -> If cancel: Exit
+    |
+    v
+[Phase 5] Execution & Progress Tracking
+    -> Create TodoWrite task list from breakdown
+    -> Launch selected execution (agent or CLI)
+    -> Track progress with TodoWrite updates
+    -> Real-time status displayed to user
+    |
+    v
+Execution Complete
+```
+
+### Task Management Pattern
+
+- TodoWrite creates task list before execution starts (Phase 5)
+- Tasks marked as in_progress/completed during execution
+- Real-time progress updates visible to user
+- No intermediate file artifacts generated
+
+## Detailed Phase Execution
+
+### Phase 1: Task Analysis & Exploration Decision
+
+**Operations**:
+- Analyze task description to determine if code exploration is needed
+- Decision logic:
+  ```javascript
+  needsExploration = (
+    task.mentions_specific_files ||
+    task.requires_codebase_context ||
+    task.needs_architecture_understanding ||
+    task.modifies_existing_code
+  ) && !flags.includes('--quick')
+  ```
+
+**Decision Criteria**:
+
+| Task Type | Needs Exploration | Reason |
+|-----------|-------------------|--------|
+| "Implement new feature X" | Maybe | Depends on integration with existing code |
+| "Refactor module Y" | Yes | Needs understanding of current implementation |
+| "Add tests for Z" | Yes | Needs to understand code structure |
+| "Create new standalone utility" | No | Self-contained, no existing code context |
+| "Update documentation" | No | Doesn't require code exploration |
+| "Fix bug in function F" | Yes | Needs to understand implementation |
+
+**If Exploration Needed**:
+- Launch cli-explore-agent with task-specific focus
+- Agent call format:
+  ```javascript
+  Task(
+    subagent_type="cli-explore-agent",
+    description="Analyze codebase for task context",
+    prompt=`
+    Task: ${task_description}
+
+    Analyze and return the following information in structured format:
+    1. Project Structure: Overall architecture and module organization
+    2. Relevant Files: List of files that will be affected by this task (with paths)
+    3. Current Implementation Patterns: Existing code patterns, conventions, and styles
+    4. Dependencies: External dependencies and internal module dependencies
+    5. Integration Points: Where this task connects with existing code
+    6. Architecture Constraints: Technical limitations or requirements
+    7. Clarification Needs: Ambiguities or missing information requiring user input
+
+    Time Limit: 60 seconds
+
+    Output Format: Return a JSON-like structured object with the above fields populated.
+    Include specific file paths, pattern examples, and clear questions for clarifications.
+    `
+  )
+  ```
+
+**Expected Return Structure**:
+```javascript
+explorationContext = {
+  project_structure: "Description of overall architecture",
+  relevant_files: ["src/auth/service.ts", "src/middleware/auth.ts", ...],
+  patterns: "Description of existing patterns (e.g., 'Uses dependency injection pattern', 'React hooks convention')",
+  dependencies: "List of dependencies and integration points",
+  integration_points: "Where this connects with existing code",
+  constraints: "Technical constraints (e.g., 'Must use existing auth library', 'No breaking changes')",
+  clarification_needs: [
+    {
+      question: "Which authentication method to use?",
+      context: "Found both JWT and Session patterns",
+      options: ["JWT tokens", "Session-based", "Hybrid approach"]
+    },
+    // ... more clarification questions
+  ]
+}
+```
+
+**Output Processing**:
+- Store exploration findings in `explorationContext`
+- Extract `clarification_needs` array from exploration results
+- Set `needsClarification = (clarification_needs.length > 0)`
+- Use clarification_needs to generate Phase 2 questions
+
+**Progress Tracking**:
+- Mark Phase 1 as completed
+- If needsClarification: Mark Phase 2 as in_progress
+- Else: Skip to Phase 3
+
+**Expected Duration**: 10-20 seconds (analysis) + 30-60 seconds (exploration if needed)
+
+---
+
+### Phase 2: Clarification (Optional)
+
+**Skip Condition**: Only run if Phase 1 set `needsClarification = true`
+
+**Operations**:
+- Review `explorationContext.clarification_needs` from Phase 1
+- Generate AskUserQuestion based on exploration findings
+- Focus on ambiguities that affect implementation approach
+
+**AskUserQuestion Call** (simplified reference):
+```javascript
+// Use clarification_needs from exploration to build questions
+AskUserQuestion({
+  questions: explorationContext.clarification_needs.map(need => ({
+    question: `${need.context}\n\n${need.question}`,
+    header: "Clarification",
+    multiSelect: false,
+    options: need.options.map(opt => ({
+      label: opt,
+      description: `Use ${opt} approach`
+    }))
+  }))
+})
+```
+
+**Output Processing**:
+- Collect user responses and store in `clarificationContext`
+- Format: `{ question_id: selected_answer, ... }`
+- This context will be passed to Phase 3 planning
+
+**Progress Tracking**:
+- Mark Phase 2 as completed
+- Mark Phase 3 as in_progress
+
+**Expected Duration**: User-dependent (typically 30-60 seconds)
+
+---
+
+### Phase 3: Complexity Assessment & Planning
+
+**Operations**:
+- Assess task complexity based on multiple factors
+- Select appropriate planning strategy
+- Generate task breakdown using selected method
+
+**Complexity Assessment Factors**:
+```javascript
+complexityScore = {
+  file_count: exploration.files_to_modify.length,
+  integration_points: exploration.dependencies.length,
+  architecture_changes: exploration.requires_architecture_change,
+  technology_stack: exploration.unfamiliar_technologies.length,
+  task_scope: (task.estimated_steps > 5),
+  cross_cutting_concerns: exploration.affects_multiple_modules
+}
+
+// Calculate complexity
+if (complexityScore < 3) complexity = "Low"
+else if (complexityScore < 6) complexity = "Medium"
+else complexity = "High"
+```
+
+**Complexity Levels**:
+
+| Level | Characteristics | Planning Strategy |
+|-------|----------------|-------------------|
+| Low | 1-2 files, simple changes, clear requirements | Direct planning (current Claude) |
+| Medium | 3-5 files, moderate integration, some ambiguity | Delegate to cli-planning-agent |
+| High | 6+ files, complex architecture, high uncertainty | Delegate to cli-planning-agent with detailed analysis |
+
+**Planning Execution**:
+
+**Option A: Direct Planning (Low Complexity)**
+```javascript
+// Current Claude generates plan directly
+planObject = {
+  summary: "Brief overview of what needs to be done",
+  approach: "Step-by-step implementation strategy",
+  tasks: [
+    "Task 1: Specific action with file references",
+    "Task 2: Specific action with file references",
+    // ... 3-5 tasks
+  ],
+  complexity: "Low",
+  estimated_time: "15-30 minutes"
+}
+```
+
+**Option B: Agent-Based Planning (Medium/High Complexity)**
+```javascript
+// Delegate to cli-planning-agent
+Task(
+  subagent_type="cli-planning-agent",
+  description="Generate detailed implementation plan",
+  prompt=`
+  Task: ${task_description}
+
+  Exploration Context:
+  ${JSON.stringify(explorationContext, null, 2)}
+
+  User Clarifications:
+  ${JSON.stringify(clarificationContext, null, 2) || "None provided"}
+
+  Complexity Level: ${complexity}
+
+  Generate a detailed implementation plan with the following components:
+
+  1. Summary: 2-3 sentence overview of the implementation
+  2. Approach: High-level implementation strategy
+  3. Task Breakdown: 5-10 specific, actionable tasks
+     - Each task should specify:
+       * What to do
+       * Which files to modify/create
+       * Dependencies on other tasks (if any)
+  4. Task Dependencies: Explicit ordering requirements (e.g., "Task 2 depends on Task 1")
+  5. Risks: Potential issues and mitigation strategies (for Medium/High complexity)
+  6. Estimated Time: Total implementation time estimate
+  7. Recommended Execution: "Direct" (agent) or "CLI" (autonomous tool)
+
+  Output Format: Return a structured object with these fields:
+  {
+    summary: string,
+    approach: string,
+    tasks: string[],
+    dependencies: string[] (optional),
+    risks: string[] (optional),
+    estimated_time: string,
+    recommended_execution: "Direct" | "CLI"
+  }
+
+  Ensure tasks are specific, with file paths and clear acceptance criteria.
+  `
+)
+
+// Agent returns detailed plan
+planObject = agent_output.parse()
+```
+
+**Expected Return Structure**:
+```javascript
+planObject = {
+  summary: "Implement JWT-based authentication system with middleware integration",
+  approach: "Create auth service layer, implement JWT utilities, add middleware, update routes",
+  tasks: [
+    "Create authentication service in src/auth/service.ts with login/logout/verify methods",
+    "Implement JWT token utilities in src/auth/jwt.ts (generate, verify, refresh)",
+    "Add authentication middleware to src/middleware/auth.ts",
+    "Update API routes in src/routes/*.ts to use auth middleware",
+    "Add integration tests for auth flow in tests/auth.test.ts"
+  ],
+  dependencies: [
+    "Task 3 depends on Task 2 (middleware needs JWT utilities)",
+    "Task 4 depends on Task 3 (routes need middleware)",
+    "Task 5 depends on Tasks 1-4 (tests need complete implementation)"
+  ],
+  risks: [
+    "Token refresh timing may conflict with existing session logic - test thoroughly",
+    "Breaking change if existing auth is in use - plan migration strategy"
+  ],
+  estimated_time: "30-45 minutes",
+  recommended_execution: "CLI"  // Based on clear requirements and straightforward implementation
+}
+```
+
+**Output Structure**:
+```javascript
+planObject = {
+  summary: "2-3 sentence overview",
+  approach: "Implementation strategy",
+  tasks: [
+    "Task 1: ...",
+    "Task 2: ...",
+    // ... 3-10 tasks based on complexity
+  ],
+  complexity: "Low|Medium|High",
+  dependencies: ["task1 -> task2", ...],  // if Medium/High
+  risks: ["risk1", "risk2", ...],         // if High
+  estimated_time: "X minutes",
+  recommended_execution: "Direct|CLI"
+}
+```
+
+**Progress Tracking**:
+- Mark Phase 3 as completed
+- Mark Phase 4 as in_progress
+
+**Expected Duration**:
+- Low complexity: 20-30 seconds (direct)
+- Medium/High complexity: 40-60 seconds (agent-based)
+
+---
+
+### Phase 4: Task Confirmation & Execution Selection
+
+**User Interaction Flow**: Two-dimensional confirmation (task + execution method)
+
+**Operations**:
+- Display plan summary with full task breakdown
+- Collect two-dimensional user input: Task confirmation + Execution method selection
+- Support modification flow if user requests changes
+
+**Question 1: Task Confirmation**
+
+Display plan to user and ask for confirmation:
+- Show: summary, approach, task breakdown, dependencies, risks, complexity, estimated time
+- Options: "Confirm" / "Modify" / "Cancel"
+- If Modify: Collect feedback via "Other" option, re-run Phase 3 with modifications
+- If Cancel: Exit workflow
+- If Confirm: Proceed to Question 2
+
+**Question 2: Execution Method Selection** (Only if task confirmed)
+
+Ask user to select execution method:
+- Show recommendation from `planObject.recommended_execution`
+- Options:
+  - "Direct - Execute with Agent" (@code-developer)
+  - "CLI - Gemini" (gemini-2.5-pro)
+  - "CLI - Codex" (gpt-5)
+  - "CLI - Qwen" (coder-model)
+- Store selection for Phase 5 execution
+
+**Simplified AskUserQuestion Reference**:
+```javascript
+// Question 1: Task Confirmation
+AskUserQuestion({
+  questions: [{
+    question: `[Display plan with all details]\n\nDo you confirm this plan?`,
+    header: "Confirm Plan",
+    options: [
+      { label: "Confirm", description: "Proceed to execution" },
+      { label: "Modify", description: "Adjust plan" },
+      { label: "Cancel", description: "Abort" }
+    ]
+  }]
+})
+
+// Question 2: Execution Method (if confirmed)
+AskUserQuestion({
+  questions: [{
+    question: `Select execution method:\n[Show recommendation and tool descriptions]`,
+    header: "Execution Method",
+    options: [
+      { label: "Direct - Agent", description: "Interactive execution" },
+      { label: "CLI - Gemini", description: "gemini-2.5-pro" },
+      { label: "CLI - Codex", description: "gpt-5" },
+      { label: "CLI - Qwen", description: "coder-model" }
+    ]
+  }]
+})
+```
+
+**Decision Flow**:
+```
+Task Confirmation:
+  ├─ Confirm → Execution Method Selection → Phase 5
+  ├─ Modify → Collect feedback → Re-run Phase 3
+  └─ Cancel → Exit (no execution)
+
+Execution Method Selection:
+  ├─ Direct - Execute with Agent → Launch @code-developer
+  ├─ CLI - Gemini → Build and execute Gemini command
+  ├─ CLI - Codex → Build and execute Codex command
+  └─ CLI - Qwen → Build and execute Qwen command
+```
+
+**Progress Tracking**:
+- Mark Phase 4 as completed
+- Mark Phase 5 as in_progress
+
+**Expected Duration**: User-dependent (1-3 minutes typical)
+
+---
+
+### Phase 5: Execution & Progress Tracking
+
+**Operations**:
+- Create TodoWrite task list from plan breakdown
+- Launch selected execution method (agent or CLI)
+- Track execution progress with real-time TodoWrite updates
+- Display status to user
+
+**Step 5.1: Create TodoWrite Task List**
+
+**Before execution starts**, create task list:
+```javascript
+TodoWrite({
+  todos: planObject.tasks.map((task, index) => ({
+    content: task,
+    status: "pending",
+    activeForm: task.replace(/^(.*?):/, "$1ing:")  // "Implement X" -> "Implementing X"
+  }))
+})
+```
+
+**Example Task List**:
+```
+[ ] Implement authentication service in src/auth/service.ts
+[ ] Create JWT token utilities in src/auth/jwt.ts
+[ ] Add authentication middleware to src/middleware/auth.ts
+[ ] Update API routes to use authentication
+[ ] Add integration tests for auth flow
+```
+
+**Step 5.2: Launch Execution**
+
+Based on user selection in Phase 4, execute appropriate method:
+
+#### Option A: Direct Execution with Agent
+
+**Operations**:
+- Launch @code-developer agent with full plan context
+- Agent receives exploration findings, clarifications, and task breakdown
+- Agent call format:
+  ```javascript
+  Task(
+    subagent_type="code-developer",
+    description="Implement planned tasks with progress tracking",
+    prompt=`
+    Implement the following tasks with TodoWrite progress updates:
+
+    Summary: ${planObject.summary}
+
+    Task Breakdown:
+    ${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
+
+    ${planObject.dependencies ? `\nTask Dependencies:\n${planObject.dependencies.join('\n')}` : ''}
+
+    Implementation Approach:
+    ${planObject.approach}
+
+    Code Context:
+    ${explorationContext || "No exploration performed"}
+
+    ${clarificationContext ? `\nClarifications:\n${clarificationContext}` : ''}
+
+    ${planObject.risks ? `\nRisks to Consider:\n${planObject.risks.join('\n')}` : ''}
+
+    IMPORTANT Instructions:
+    - Update TodoWrite as you complete each task (mark as completed)
+    - Follow task dependencies if specified
+    - Implement tasks in sequence unless independent
+    - Test functionality as you go
+    - Handle risks proactively
+    `
+  )
+  ```
+
+**Agent Responsibilities**:
+- Mark tasks as in_progress when starting
+- Mark tasks as completed when finished
+- Update TodoWrite in real-time for user visibility
+
+#### Option B: CLI Execution (Gemini/Codex/Qwen)
+
+**Operations**:
+- Build CLI command with comprehensive context
+- Execute CLI tool with write permissions
+- Monitor CLI output and update TodoWrite based on progress indicators
+- Parse CLI completion signals to mark tasks as done
+
+**Command Format (Gemini)** - Full context with exploration and clarifications:
+```bash
+gemini -p "
+PURPOSE: Implement planned tasks with full context from exploration and planning
+TASK:
+${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
+
+MODE: write
+
+CONTEXT: @**/* | Memory: Implementation plan from lite-plan workflow
+
+## Exploration Findings
+${explorationContext ? `
+Project Structure:
+${explorationContext.project_structure || 'Not available'}
+
+Relevant Files:
+${explorationContext.relevant_files?.join('\n') || 'Not specified'}
+
+Current Implementation Patterns:
+${explorationContext.patterns || 'Not analyzed'}
+
+Dependencies and Integration Points:
+${explorationContext.dependencies || 'Not specified'}
+
+Architecture Constraints:
+${explorationContext.constraints || 'None identified'}
+` : 'No exploration performed (task did not require codebase context)'}
+
+## User Clarifications
+${clarificationContext ? `
+The following clarifications were provided by the user after exploration:
+${Object.entries(clarificationContext).map(([q, a]) => `Q: ${q}\nA: ${a}`).join('\n\n')}
+` : 'No clarifications needed'}
+
+## Implementation Plan Context
+Task Summary: ${planObject.summary}
+
+Implementation Approach:
+${planObject.approach}
+
+${planObject.dependencies ? `
+Task Dependencies (execute in order):
+${planObject.dependencies.join('\n')}
+` : ''}
+
+${planObject.risks ? `
+Identified Risks:
+${planObject.risks.join('\n')}
+` : ''}
+
+Complexity Level: ${planObject.complexity}
+Estimated Time: ${planObject.estimated_time}
+
+EXPECTED: All tasks implemented following the plan approach, with proper error handling and testing
+
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow implementation approach exactly | Handle identified risks proactively | write=CREATE/MODIFY/DELETE
+" -m gemini-2.5-pro --approval-mode yolo
+```
+
+**Command Format (Codex)** - Session-based with resume support:
+
+**First Execution (Establish Session)**:
+```bash
+codex --full-auto exec "
+TASK: ${planObject.summary}
+
+## Task Breakdown
+${planObject.tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
+
+${planObject.dependencies ? `\n## Task Dependencies\n${planObject.dependencies.join('\n')}` : ''}
+
+## Implementation Approach
+${planObject.approach}
+
+## Code Context from Exploration
+${explorationContext ? `
+Project Structure: ${explorationContext.project_structure || 'Standard structure'}
+Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
+Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
+Integration Points: ${explorationContext.dependencies || 'None specified'}
+Constraints: ${explorationContext.constraints || 'None'}
+` : 'No prior exploration - analyze codebase as needed'}
+
+${clarificationContext ? `\n## User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
+
+${planObject.risks ? `\n## Risks to Handle\n${planObject.risks.join('\n')}` : ''}
+
+## Execution Instructions
+- Complete all tasks following the breakdown sequence
+- Respect task dependencies if specified
+- Test functionality as you implement
+- Handle identified risks proactively
+- Create session for potential resume if needed
+
+Complexity: ${planObject.complexity}
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+**Subsequent Executions (Resume if needed)**:
+```bash
+# If first execution fails or is interrupted, can resume:
+codex --full-auto exec "
+Continue implementation from previous session.
+
+Remaining tasks:
+${remaining_tasks.map((t, i) => `${i+1}. ${t}`).join('\n')}
+
+Maintain context from previous execution.
+" resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+**Codex Session Strategy**:
+- First execution establishes full context and creates session
+- If execution is interrupted or fails, use `resume --last` to continue
+- Resume inherits all context from original execution
+- Useful for complex tasks that may hit timeouts or require iteration
+
+**Command Format (Qwen)** - Full context similar to Gemini:
+```bash
+qwen -p "
+PURPOSE: Implement planned tasks with comprehensive context
+
+TASK:
+${planObject.tasks.map((t, i) => `• ${t}`).join('\n')}
+
+MODE: write
+
+CONTEXT: @**/* | Memory: Full implementation context from lite-plan
+
+## Code Exploration Results
+${explorationContext ? `
+Analyzed Project Structure:
+${explorationContext.project_structure || 'Standard structure'}
+
+Key Files to Modify:
+${explorationContext.relevant_files?.join('\n') || 'To be determined during implementation'}
+
+Existing Code Patterns:
+${explorationContext.patterns || 'Follow codebase conventions'}
+
+Dependencies:
+${explorationContext.dependencies || 'None specified'}
+
+Constraints:
+${explorationContext.constraints || 'None identified'}
+` : 'No exploration performed - analyze codebase patterns as you implement'}
+
+## Clarifications from User
+${clarificationContext ? `
+${Object.entries(clarificationContext).map(([question, answer]) => `
+Question: ${question}
+Answer: ${answer}
+`).join('\n')}
+` : 'No additional clarifications provided'}
+
+## Implementation Strategy
+Summary: ${planObject.summary}
+
+Approach:
+${planObject.approach}
+
+${planObject.dependencies ? `
+Task Order (follow sequence):
+${planObject.dependencies.join('\n')}
+` : ''}
+
+${planObject.risks ? `
+Risk Mitigation:
+${planObject.risks.join('\n')}
+` : ''}
+
+Task Complexity: ${planObject.complexity}
+Time Estimate: ${planObject.estimated_time}
+
+EXPECTED: Complete implementation with tests and proper error handling
+
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/02-implement-feature.txt) | Follow approach strictly | Test thoroughly | write=CREATE/MODIFY/DELETE
+" -m coder-model --approval-mode yolo
+```
+
+**Execution with Progress Tracking**:
+```javascript
+// Launch CLI in background
+bash_result = Bash(
+  command=cli_command,
+  timeout=600000,  // 10 minutes
+  run_in_background=true
+)
+
+// Monitor output and update TodoWrite
+// Parse CLI output for task completion indicators
+// Update TodoWrite when tasks complete
+// Example: When CLI outputs "✓ Task 1 complete" -> Mark task 1 as completed
+```
+
+**CLI Progress Monitoring**:
+- Parse CLI output for completion keywords ("done", "complete", "✓", etc.)
+- Update corresponding TodoWrite tasks based on progress
+- Provide real-time visibility to user
+
+**Step 5.3: Track Execution Progress**
+
+**Real-time TodoWrite Updates**:
+```javascript
+// As execution progresses, update task status:
+
+// Task started
+TodoWrite({
+  todos: [
+    { content: "Implement auth service", status: "in_progress", activeForm: "Implementing auth service" },
+    { content: "Create JWT utilities", status: "pending", activeForm: "Creating JWT utilities" },
+    // ...
+  ]
+})
+
+// Task completed
+TodoWrite({
+  todos: [
+    { content: "Implement auth service", status: "completed", activeForm: "Implementing auth service" },
+    { content: "Create JWT utilities", status: "in_progress", activeForm: "Creating JWT utilities" },
+    // ...
+  ]
+})
+```
+
+**User Visibility**:
+- User sees real-time task progress
+- Current task highlighted as "in_progress"
+- Completed tasks marked with checkmark
+- Pending tasks remain unchecked
+
+**Progress Tracking**:
+- Mark Phase 5 as in_progress throughout execution
+- Mark Phase 5 as completed when all tasks done
+- Final status summary displayed to user
+
+**Expected Duration**: Varies by task complexity and execution method
+- Low complexity: 5-15 minutes
+- Medium complexity: 15-45 minutes
+- High complexity: 45-120 minutes
+
+---
+
+## Best Practices
+
+### Workflow Intelligence
+
+1. **Dynamic Adaptation**: Workflow automatically adjusts based on task characteristics
+   - Smart exploration: Only runs when task requires codebase context
+   - Adaptive planning: Simple tasks get direct planning, complex tasks use specialized agent
+   - Context-aware clarification: Only asks questions when truly needed
+   - Reduces unnecessary steps while maintaining thoroughness
+
+2. **Progressive Clarification**: Gather information at the right time
+   - Phase 1: Explore codebase to understand current state
+   - Phase 2: Ask clarifying questions based on exploration findings
+   - Phase 3: Plan with complete context (task + exploration + clarifications)
+   - Avoids premature assumptions and reduces rework
+
+3. **Complexity-Aware Planning**: Planning strategy matches task complexity
+   - Low complexity (1-2 files): Direct planning by current Claude (fast, 20-30s)
+   - Medium complexity (3-5 files): CLI planning agent (detailed, 40-50s)
+   - High complexity (6+ files): CLI planning agent with risk analysis (thorough, 50-60s)
+   - Balances speed and thoroughness appropriately
+
+4. **Two-Dimensional Confirmation**: Separate task approval from execution method
+   - First dimension: Confirm/Modify/Cancel plan
+   - Second dimension: Direct execution vs CLI execution
+   - Allows plan refinement without re-selecting execution method
+   - Supports iterative planning with user feedback
+
+### Task Management
+
+1. **Live Progress Tracking**: TodoWrite provides real-time execution visibility
+   - Tasks created before execution starts
+   - Updated in real-time as work progresses
+   - User sees current task being worked on
+   - Clear completion status throughout execution
+
+2. **Phase-Based Organization**: 5 distinct phases with clear transitions
+   - Phase 1: Task Analysis & Exploration (automatic)
+   - Phase 2: Clarification (conditional, interactive)
+   - Phase 3: Planning (automatic, adaptive)
+   - Phase 4: Confirmation (interactive, two-dimensional)
+   - Phase 5: Execution & Tracking (automatic with live updates)
+
+3. **Flexible Task Counts**: Task breakdown adapts to complexity
+   - Low complexity: 3-5 tasks (focused)
+   - Medium complexity: 5-7 tasks (detailed)
+   - High complexity: 7-10 tasks (comprehensive)
+   - Avoids artificial constraints while maintaining focus
+
+4. **Dependency Tracking**: Medium/High complexity tasks include dependencies
+   - Explicit task ordering when sequence matters
+   - Parallel execution hints when tasks are independent
+   - Risk flagging for complex interactions
+   - Helps agent/CLI execute correctly
+
+### Planning Standards
+
+1. **Context-Rich Planning**: Plans include all relevant context
+   - Exploration findings (code structure, patterns, constraints)
+   - User clarifications (requirements, preferences, decisions)
+   - Complexity assessment (risks, dependencies, time estimates)
+   - Execution recommendations (Direct vs CLI, specific tool)
+
+2. **Modification Support**: Plans can be iteratively refined
+   - User can request plan modifications in Phase 4
+   - Feedback incorporated into re-planning
+   - No need to restart from scratch
+   - Supports collaborative planning workflow
+
+3. **No File Artifacts**: All planning stays in memory
+   - Faster workflow without I/O overhead
+   - Cleaner workspace
+   - Plan context passed directly to execution
+   - Reduces complexity and maintenance
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Phase 1 Exploration Failure | cli-explore-agent unavailable or timeout | Skip exploration, set `explorationContext = null`, log warning, continue to Phase 2/3 with task description only |
+| Phase 2 Clarification Timeout | User no response > 5 minutes | Use exploration findings as-is without clarification, proceed to Phase 3 with warning |
+| Phase 3 Planning Agent Failure | cli-planning-agent unavailable or timeout | Fallback to direct planning by current Claude (simplified plan), continue to Phase 4 |
+| Phase 3 Planning Timeout | Planning takes > 90 seconds | Generate simplified direct plan, mark as "Quick Plan", continue to Phase 4 with reduced detail |
+| Phase 4 Confirmation Timeout | User no response > 5 minutes | Save plan context to temporary var, display resume instructions, exit gracefully |
+| Phase 4 Modification Loop | User requests modify > 3 times | Suggest breaking task into smaller pieces or using /workflow:plan for comprehensive planning |
+| Phase 5 CLI Tool Unavailable | Selected CLI tool not installed | Show installation instructions, offer to re-select (Direct execution or different CLI) |
+| Phase 5 Execution Failure | Agent/CLI crashes or errors | Display error details, save partial progress from TodoWrite, suggest manual recovery or retry |
+
+## Input/Output
+
+### Input Requirements
+- Task description: String or path to .md file (required)
+  - Should be specific and concrete
+  - Can include context about existing code or requirements
+  - Examples:
+    - "Implement user authentication with JWT tokens"
+    - "Refactor logging module for better performance"
+    - "Add unit tests for authentication service"
+- Flags (optional):
+  - `--tool <name>`: Preset execution tool (claude|gemini|codex|qwen)
+  - `--quick`: Skip code exploration phase
+
+### Output Format
+
+**In-Memory Plan Object**:
+```javascript
+{
+  summary: "2-3 sentence overview of implementation",
+  approach: "High-level implementation strategy",
+  tasks: [
+    "Task 1: Specific action with file locations",
+    "Task 2: Specific action with file locations",
+    // ... 3-7 tasks total
+  ],
+  complexity: "Low|Medium|High",
+  recommended_tool: "Claude|Gemini|Codex|Qwen",
+  estimated_time: "X minutes"
+}
+```
+
+**Execution Result**:
+- Immediate dispatch to selected tool/agent with plan context
+- No file artifacts generated during planning phase
+- Execution starts immediately after user confirmation
+- Tool/agent handles implementation and any necessary file operations
+

.claude/skills/command-guide/reference/commands/workflow/plan.md

@@ -1,7 +1,7 @@
 ---
 name: plan
-description: 5-phase planning workflow with Gemini analysis and action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
-argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
+description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
+argument-hint: "[--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -20,18 +20,21 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 2. **Phase 1 executes** → Session discovery → Auto-continues
 3. **Phase 2 executes** → Context gathering → Auto-continues
 4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
-5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
+5. **Phase 4 executes** → Task generation (task-generate-agent) → Reports final summary
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
 
 **Auto-Continue Mechanism**:
-- TodoList tracks current phase status
-- After each phase completion, automatically executes next pending phase
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
 - All phases run autonomously without user interaction (clarification handled in brainstorm phase)
 - Progress updates shown at each phase for visibility
-
-**Execution Modes**:
-- **Manual Mode** (default): Use `/workflow:tools:task-generate`
-- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
-- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -39,8 +42,9 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 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/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
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 5-Phase Execution
 
@@ -89,9 +93,35 @@ CONTEXT: Existing user database schema, REST API endpoints
 - Context package path extracted
 - File exists and is valid JSON
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+<!-- TodoWrite: When context-gather invoked, INSERT 3 context-gather tasks, mark first as in_progress -->
 
-**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2.1: Analyze codebase structure (context-gather)", "status": "in_progress", "activeForm": "Analyzing codebase structure"},
+  {"content": "Phase 2.2: Identify integration points (context-gather)", "status": "pending", "activeForm": "Identifying integration points"},
+  {"content": "Phase 2.3: Generate context package (context-gather)", "status": "pending", "activeForm": "Generating context package"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** context-gather's 3 tasks. Orchestrator **executes** these tasks sequentially.
+
+<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3/4 (depending on conflict_risk)
 
 ---
 
@@ -117,7 +147,35 @@ CONTEXT: Existing user database schema, REST API endpoints
 - If conflict_risk is "none" or "low", skip directly to Phase 3.5
 - Display: "No significant conflicts detected, proceeding to clarification"
 
-**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
+<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "Phase 3.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "Phase 3.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks sequentially.
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 **After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
 
@@ -159,24 +217,18 @@ CONTEXT: Existing user database schema, REST API endpoints
 - Task generation translates high-level role analyses into concrete, actionable work items
 - **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
 
-**Command Selection**:
-- Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
-- Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
-- CLI Execute: Add `--cli-execute` flag to either command
-
-**Flag Combination**:
-- `--cli-execute` alone: Manual task generation with CLI execution
-- `--agent --cli-execute`: Agent task generation with CLI execution
-
-**Command Examples**:
+**Command**:
 ```bash
-# Manual with CLI execution
-/workflow:tools:task-generate --session WFS-auth --cli-execute
+# Default (agent mode)
+SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")
 
-# Agent with CLI execution
-/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+# With CLI execution
+SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId] --cli-execute")
 ```
 
+**Flag**:
+- `--cli-execute`: Generate tasks with Codex execution commands
+
 **Input**: `sessionId` from Phase 1
 
 **Validation**:
@@ -184,7 +236,35 @@ CONTEXT: Existing user database schema, REST API endpoints
 - `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
 - `.workflow/[sessionId]/TODO_LIST.md` exists
 
-**TodoWrite**: Mark phase 4 completed
+<!-- TodoWrite: When task-generate-agent invoked, INSERT 3 task-generate-agent tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 4.1: Discovery - analyze requirements (task-generate-agent)", "status": "in_progress", "activeForm": "Analyzing requirements"},
+  {"content": "Phase 4.2: Planning - design tasks (task-generate-agent)", "status": "pending", "activeForm": "Designing tasks"},
+  {"content": "Phase 4.3: Output - generate JSONs (task-generate-agent)", "status": "pending", "activeForm": "Generating task JSONs"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** task-generate-agent's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "completed", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 **Return to User**:
 ```
@@ -202,39 +282,37 @@ Quality Gate: Consider running /workflow:action-plan-verify to catch issues earl
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (before Phase 1)
-// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  // Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
-  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for real-time visibility into workflow execution.
 
-// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
-  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
-]})
+### Key Principles
 
-// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
-]})
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-// After Phase 3 (if executed), continue to Phase 4
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
-  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
-]})
-```
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Execute context gathering: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+### Benefits
+
+- ✓ Real-time visibility into sub-task execution
+- ✓ Clear mental model: SlashCommand = attach → execute → collapse
+- ✓ Clean summary after completion
+- ✓ Easy to track workflow progress
+
+**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
 
 ## Input Processing
 
@@ -296,7 +374,7 @@ Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
     ↓ Output: Modified brainstorm artifacts (NO report file)
     ↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
     ↓
-Phase 4: task-generate[--agent] --session sessionId
+Phase 4: task-generate-agent --session sessionId [--cli-execute]
     ↓ Input: sessionId + resolved brainstorm artifacts + session memory
     ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
     ↓
@@ -315,6 +393,55 @@ Return summary to user
 - **Traceability**: Easy to track what was requested
 - **Precision**: Better context gathering and analysis
 
+## Execution Flow Diagram
+
+```
+User triggers: /workflow:plan "Build authentication system"
+  ↓
+[TodoWrite Init] 3 orchestrator-level tasks
+  ↓
+Phase 1: Session Discovery
+  → sessionId extracted
+  ↓
+Phase 2: Context Gathering (SlashCommand invoked)
+  → ATTACH 3 tasks: ← ATTACHED
+    - Phase 2.1: Analyze codebase structure
+    - Phase 2.2: Identify integration points
+    - Phase 2.3: Generate context package
+  → Execute Phase 2.1-2.3
+  → COLLAPSE tasks ← COLLAPSED
+  → contextPath + conflict_risk extracted
+  ↓
+Conditional Branch: Check conflict_risk
+  ├─ IF conflict_risk ≥ medium:
+  │   Phase 3: Conflict Resolution (SlashCommand invoked)
+  │     → ATTACH 3 tasks: ← ATTACHED
+  │       - Phase 3.1: Detect conflicts with CLI analysis
+  │       - Phase 3.2: Present conflicts to user
+  │       - Phase 3.3: Apply resolution strategies
+  │     → Execute Phase 3.1-3.3
+  │     → COLLAPSE tasks ← COLLAPSED
+  │
+  └─ ELSE: Skip Phase 3, proceed to Phase 4
+  ↓
+Phase 4: Task Generation (SlashCommand invoked)
+  → ATTACH 3 tasks: ← ATTACHED
+    - Phase 4.1: Discovery - analyze requirements
+    - Phase 4.2: Planning - design tasks
+    - Phase 4.3: Output - generate JSONs
+  → Execute Phase 4.1-4.3
+  → COLLAPSE tasks ← COLLAPSED
+  → Outputs: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
+  ↓
+Return summary to user
+```
+
+**Key Points**:
+- **← ATTACHED**: Sub-tasks attached to TodoWrite when SlashCommand invoked
+- **← COLLAPSED**: Sub-tasks collapsed to summary after completion
+- **Conditional Branch**: Phase 3 only executes if conflict_risk ≥ medium
+- **Continuous Flow**: No user intervention between phases
+
 ## Error Handling
 
 - **Parsing Failure**: If output parsing fails, retry command once, then report error
@@ -331,11 +458,10 @@ Return summary to user
 - Parse context path from Phase 2 output, store in memory
 - **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
 - **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
-- Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
+- Wait for Phase 3 to finish executing (if executed), verify CONFLICT_RESOLUTION.md created
 - **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
-- **Build Phase 4 command** based on flags:
-  - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
-  - Add `--session [sessionId]`
+- **Build Phase 4 command**:
+  - Base command: `/workflow:tools:task-generate-agent --session [sessionId]`
   - Add `--cli-execute` if flag present
 - Pass session ID to Phase 4 command
 - Verify all Phase 4 outputs
@@ -380,8 +506,7 @@ CONSTRAINTS: [Limitations or boundaries]
 - `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
 - `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
 - `/compact` - Phase 3: Memory optimization (if context approaching limits)
-- `/workflow:tools:task-generate` - Phase 4: Generate task JSON files with manual approach
-- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach (when `--agent` flag used)
+- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach
 
 **Follow-up Commands**:
 - `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution

.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md

@@ -1,7 +1,7 @@
 ---
 name: tdd-plan
 description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
-argument-hint: "[--agent] \"feature description\"|file.md"
+argument-hint: "[--cli-execute] \"feature description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -9,11 +9,24 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 5 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation.
+**This command is a pure orchestrator**: Execute 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
 
 **Execution Modes**:
-- **Manual Mode** (default): Use `/workflow:tools:task-generate-tdd`
-- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-tdd --agent`
+- **Agent Mode** (default): Use `/workflow:tools:task-generate-tdd` (autonomous agent-driven)
+- **CLI Mode** (`--cli-execute`): Use `/workflow:tools:task-generate-tdd --cli-execute` (Gemini/Qwen)
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -21,9 +34,10 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data 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
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 6. **TDD Context**: All descriptions include "TDD:" prefix
-7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
+7. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+8. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 6-Phase Execution (with Conflict Resolution)
 
@@ -85,9 +99,41 @@ TEST_FOCUS: [Test scenarios]
 - Prevents duplicate test creation
 - Enables integration with existing tests
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
 
-**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3.1: Detect test framework and conventions (test-context-gather)", "status": "in_progress", "activeForm": "Detecting test framework"},
+  {"content": "Phase 3.2: Analyze existing test coverage (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "Phase 3.3: Identify coverage gaps (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
+
+**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4/5 (depending on conflict_risk)
 
 ---
 
@@ -113,7 +159,41 @@ TEST_FOCUS: [Test scenarios]
 - If conflict_risk is "none" or "low", skip directly to Phase 5
 - Display: "No significant conflicts detected, proceeding to TDD task generation"
 
-**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
+<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "Phase 4.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "Phase 4.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 **After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
 
@@ -129,8 +209,8 @@ TEST_FOCUS: [Test scenarios]
 
 ### Phase 5: TDD Task Generation
 **Command**:
-- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
-- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
+- Agent Mode (default): `/workflow:tools:task-generate-tdd --session [sessionId]`
+- CLI Mode (`--cli-execute`): `/workflow:tools:task-generate-tdd --session [sessionId] --cli-execute`
 
 **Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
 
@@ -145,6 +225,40 @@ TEST_FOCUS: [Test scenarios]
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 - Task count ≤10 (compliance with task limit)
 
+<!-- TodoWrite: When task-generate-tdd invoked, INSERT 3 task-generate-tdd tasks -->
+
+**TodoWrite Update (Phase 5 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 5.1: Discovery - analyze TDD requirements (task-generate-tdd)", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
+  {"content": "Phase 5.2: Planning - design Red-Green-Refactor cycles (task-generate-tdd)", "status": "pending", "activeForm": "Designing TDD cycles"},
+  {"content": "Phase 5.3: Output - generate IMPL tasks with internal TDD phases (task-generate-tdd)", "status": "pending", "activeForm": "Generating TDD tasks"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** task-generate-tdd's 3 tasks. Orchestrator **executes** these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.
+
+**Next Action**: Tasks attached → **Execute Phase 5.1-5.3** sequentially
+
+<!-- TodoWrite: After Phase 5 tasks complete, REMOVE Phase 5.1-5.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 5 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "completed", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "in_progress", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 5 tasks completed and collapsed to summary. Each generated IMPL task contains complete Red-Green-Refactor cycle internally.
+
 ### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
@@ -202,45 +316,90 @@ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
-  // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
-  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for TDD workflow with test coverage analysis and Red-Green-Refactor cycle generation.
 
-// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
-  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+### Key Principles
 
-// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 3.1, 3.2, 3.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-// After Phase 4 (if executed), continue to Phase 5
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
-  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 3.1-3.3 collapse to "Execute test coverage analysis: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.
+
+### TDD-Specific Features
+
+- **Phase 3**: Test coverage analysis detects existing patterns and gaps
+- **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles
+- **Conditional Phase 4**: Conflict resolution only if conflict_risk ≥ medium
+
+### Benefits
+
+- ✓ Real-time visibility into TDD workflow execution
+- ✓ Clear mental model: SlashCommand = attach → execute → collapse
+- ✓ Test-aware planning with coverage analysis
+- ✓ Self-contained TDD cycles within each IMPL task
+
+**Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.
+
+## Execution Flow Diagram
+
+```
+TDD Workflow Orchestrator
+│
+├─ Phase 1: Session Discovery
+│  └─ /workflow:session:start --auto
+│     └─ Returns: sessionId
+│
+├─ Phase 2: Context Gathering
+│  └─ /workflow:tools:context-gather
+│     └─ Returns: context-package.json path
+│
+├─ Phase 3: Test Coverage Analysis                    ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-context-gather
+│     ├─ Phase 3.1: Detect test framework
+│     ├─ Phase 3.2: Analyze existing test coverage
+│     └─ Phase 3.3: Identify coverage gaps
+│     └─ Returns: test-context-package.json           ← COLLAPSED
+│
+├─ Phase 4: Conflict Resolution (conditional)
+│  IF conflict_risk ≥ medium:
+│  └─ /workflow:tools:conflict-resolution             ← ATTACHED (3 tasks)
+│     ├─ Phase 4.1: Detect conflicts with CLI
+│     ├─ Phase 4.2: Present conflicts to user
+│     └─ Phase 4.3: Apply resolution strategies
+│     └─ Returns: CONFLICT_RESOLUTION.md              ← COLLAPSED
+│  ELSE:
+│  └─ Skip to Phase 5
+│
+├─ Phase 5: TDD Task Generation                       ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:task-generate-tdd
+│     ├─ Phase 5.1: Discovery - analyze TDD requirements
+│     ├─ Phase 5.2: Planning - design Red-Green-Refactor cycles
+│     └─ Phase 5.3: Output - generate IMPL tasks with internal TDD phases
+│     └─ Returns: IMPL-*.json, IMPL_PLAN.md           ← COLLAPSED
+│        (Each IMPL task contains internal Red-Green-Refactor cycle)
+│
+└─ Phase 6: TDD Structure Validation
+   └─ Internal validation + summary returned
+   └─ Recommend: /workflow:action-plan-verify
+
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
+• TDD-specific: Each generated IMPL task contains complete Red-Green-Refactor cycle
 ```
 
 ## Input Processing
@@ -373,8 +532,8 @@ Supports action-planning-agent for more autonomous TDD planning with:
 - `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
 - `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
 - `/compact` - Phase 4: Memory optimization (if context approaching limits)
-- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD task chains with Red-Green-Refactor cycles
-- `/workflow:tools:task-generate-tdd --agent` - Phase 5: Generate TDD tasks with agent-driven approach (when `--agent` flag used)
+- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks with agent-driven approach (default, autonomous)
+- `/workflow:tools:task-generate-tdd --cli-execute` - Phase 5: Generate TDD tasks with CLI tools (Gemini/Qwen, when `--cli-execute` flag used)
 
 **Follow-up Commands**:
 - `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution

.claude/skills/command-guide/reference/commands/workflow/test-cycle-execute.md

@@ -1,6 +1,6 @@
 ---
 name: test-cycle-execute
-description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until all tests pass or max iterations reached
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.
 argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ---
@@ -10,10 +10,13 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ## Overview
 Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
 
+**Quality Gate**: Iterates until test pass rate >= 95% (with criticality assessment) or 100% for full approval.
+
 **CRITICAL - Orchestrator Boundary**:
 - This command is the **ONLY place** where test failures are handled
-- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
-- Agents (@test-fix-agent) only execute single tasks and return results
+- All failure analysis and fix task generation delegated to **@cli-planning-agent**
+- Orchestrator calculates pass rate, assesses criticality, and manages iteration loop
+- @test-fix-agent executes tests and applies fixes, reports results back
 - **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
@@ -35,44 +38,53 @@ Orchestrates dynamic test-fix workflow execution through iterative cycles of tes
 
 ### 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
+- **@test-fix-agent**: Executes tests, applies fixes, validates results, assigns criticality
+- **@cli-planning-agent**: Executes CLI analysis (Gemini/Qwen), parses results, generates fix task JSONs
 
 ## 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
+1. **Dynamic Task Generation**: Create intermediate fix tasks via @cli-planning-agent based on test failures
+2. **Iterative Execution**: Repeat test-fix cycles until pass rate >= 95% (with criticality assessment) or max iterations
+3. **Pass Rate Threshold**: Target 95%+ pass rate; 100% for full approval; assess criticality for 95-100% range
+4. **Agent-Based Analysis**: Delegate CLI execution and task generation to @cli-planning-agent
+5. **Agent Delegation**: All execution delegated to specialized agents (@cli-planning-agent, @test-fix-agent)
+6. **Context Accumulation**: Each iteration builds on previous attempt context
+7. **Autonomous Completion**: Continue until pass rate >= 95% 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
+- **Pass Rate Calculation**: Calculate test pass rate from test-results.json (passed/total * 100)
+- **Criticality Assessment**: Evaluate failure severity using test-results.json criticality field
+- **Threshold Decision**: Determine if pass rate >= 95% with criticality consideration
+- **Failure Analysis Delegation**: Invoke @cli-planning-agent for CLI analysis and task generation
+- **Iteration Control**: Manage fix cycles with max iteration limits (5 default)
+- **Context Propagation**: Pass failure context and fix history to @cli-planning-agent
 - **Progress Tracking**: TodoWrite updates for entire iteration cycle
-- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
+- **Session Auto-Complete**: Call `/workflow:session:complete` when pass rate >= 95% (or 100%)
 
 ## Responsibility Matrix
 
 **CRITICAL - Clear division of labor between orchestrator and agents:**
 
-| Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
-|----------------|----------------------------|---------------------------|
-| Manage iteration loop | Yes - Controls loop flow | No - Executes single task |
-| Run CLI analysis (Gemini/Qwen) | Yes - Runs between agent tasks | No - Not involved |
-| Generate IMPL-fix-N.json | Yes - Creates task files | No - Not involved |
-| Run tests | No - Delegates to agent | Yes - Executes test command |
-| Apply fixes | No - Delegates to agent | Yes - Modifies code |
-| Detect test failures | Yes - Analyzes results and decides next action | Yes - Executes tests and reports outcomes |
-| Add tasks to queue | Yes - Manages queue | No - Not involved |
-| Update iteration state | Yes - Maintains overall iteration state | Yes - Updates individual task status only |
+| Responsibility | test-cycle-execute (Orchestrator) | @cli-planning-agent | @test-fix-agent (Executor) |
+|----------------|----------------------------|---------------------|---------------------------|
+| Manage iteration loop | Yes - Controls loop flow | No - Not involved | No - Executes single task |
+| Calculate pass rate | Yes - From test-results.json | No - Not involved | No - Reports test results |
+| Assess criticality | Yes - From test-results.json | No - Not involved | Yes - Assigns criticality in test results |
+| Run CLI analysis (Gemini/Qwen) | No - Delegates to cli-planning-agent | Yes - Executes CLI internally | No - Not involved |
+| Parse CLI output | No - Delegated | Yes - Extracts fix strategy | No - Not involved |
+| Generate IMPL-fix-N.json | No - Delegated | Yes - Creates task files | No - Not involved |
+| Run tests | No - Delegates to agent | No - Not involved | Yes - Executes test command |
+| Apply fixes | No - Delegates to agent | No - Not involved | Yes - Modifies code |
+| Detect test failures | Yes - Analyzes pass rate and decides next action | No - Not involved | Yes - Executes tests and reports outcomes |
+| Add tasks to queue | Yes - Manages queue | No - Returns task ID | No - Not involved |
+| Update iteration state | Yes - Maintains overall iteration state | No - Not involved | Yes - Updates individual task status only |
 
-**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
+**Key Principles**:
+- Orchestrator manages the "what" (iteration flow, threshold decisions) and "when" (task scheduling)
+- @cli-planning-agent executes the "analysis" (CLI execution, result parsing, task generation)
+- @test-fix-agent executes the "how" (run tests, apply fixes)
 
 **ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
 
@@ -97,17 +109,29 @@ 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)
+  4. [Orchestrator] Collect agent results from .process/test-results.json
+  5. [Orchestrator] Calculate test pass rate:
+     a. Parse test-results.json: passRate = (passed / total) * 100
+     b. Assess failure criticality (from test-results.json)
+     c. Evaluate fix effectiveness (NEW):
+        - Compare passRate with previous iteration
+        - If passRate decreased by >10%: REGRESSION detected
+        - If regression: Rollback last fix, skip to next strategy
+  6. [Orchestrator] Make threshold decision:
+     IF passRate === 100%:
+       → SUCCESS: Mark task complete, update TodoWrite, continue
+     ELSE IF passRate >= 95%:
+       → REVIEW: Check failure criticality
+       → If all failures are "low" criticality: PARTIAL SUCCESS (approve with note)
+       → If any "high" or "medium" criticality: Enter fix loop (step 7)
+     ELSE IF passRate < 95%:
+       → FAILED: Enter fix loop (step 7)
+  7. If entering fix loop (pass rate < 95% OR critical failures exist):
+     a. [Orchestrator] Invoke @cli-planning-agent with failure context
+     b. [Agent] Executes CLI analysis + generates 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
+  8. [Orchestrator] Check max iterations limit (abort if exceeded)
 ```
 
 **Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
@@ -119,33 +143,33 @@ For each task in queue:
 #### Iteration Structure
 ```
 Iteration N (managed by test-cycle-execute orchestrator):
-├── 1. Test Execution
+├── 1. Test Execution & Pass Rate Validation
 │   ├── [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] Run test suite and save results to test-results.json
+│   ├── [Agent] Report completion back to orchestrator
+│   ├── [Orchestrator] Calculate pass rate: (passed / total) * 100
+│   └── [Orchestrator] Assess failure criticality from test-results.json
+├── 2. Failure Analysis & Task Generation (via @cli-planning-agent)
+│   ├── [Orchestrator] Assemble failure context package (tests, errors, pass_rate)
+│   ├── [Orchestrator] Invoke @cli-planning-agent with context
+│   ├── [@cli-planning-agent] Execute CLI tool (Gemini/Qwen) internally
+│   ├── [@cli-planning-agent] Parse CLI output for root causes and fix strategy
+│   ├── [@cli-planning-agent] Generate IMPL-fix-N.json with structured task
+│   ├── [@cli-planning-agent] Save analysis to iteration-N-analysis.md
+│   └── [Orchestrator] Receive task ID and insert into queue (front position)
+├── 3. Fix Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with IMPL-fix-N task
+│   ├── [Agent] Load fix strategy from task.context.fix_strategy
+│   ├── [Agent] Apply surgical fixes to identified files
 │   └── [Agent] Report completion
-└── 5. Re-test
+└── 4. Re-test
     └── [Orchestrator] Return to step 1 with updated code
 ```
 
-**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
+**Key Changes**:
+- CLI analysis + task generation encapsulated in @cli-planning-agent
+- Pass rate calculation added to test execution step
+- Orchestrator only assembles context and invokes agent
 
 #### Iteration Task JSON Template
 ```json
@@ -220,74 +244,139 @@ Iteration N (managed by test-cycle-execute orchestrator):
 }
 ```
 
-### Phase 4: CLI Analysis Integration
+### Phase 4: Agent-Based Failure Analysis & Task Generation
 
-**Orchestrator executes CLI analysis between agent tasks:**
+**Orchestrator delegates CLI analysis and task generation to @cli-planning-agent:**
 
-#### When Test Failures Occur
-1. **[Orchestrator]** Detects failures from agent test execution output
-2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
-3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
-4. **[Orchestrator]** Interprets CLI tool output to extract fix strategy
-5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
-6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
+#### When Test Failures Occur (Pass Rate < 95% OR Critical Failures)
+1. **[Orchestrator]** Detects failures from test-results.json
+2. **[Orchestrator]** Check for repeated failures (NEW):
+   - Compare failed_tests with previous 2 iterations
+   - If same test failed 3 times consecutively: Mark as "stuck"
+   - If >50% of failures are "stuck": Switch analysis strategy or abort
+3. **[Orchestrator]** Extracts failure context:
+   - Failed tests with criticality assessment
+   - Error messages and stack traces
+   - Current pass rate
+   - Previous iteration attempts (if any)
+   - Stuck test markers (NEW)
+4. **[Orchestrator]** Assembles context package for @cli-planning-agent
+5. **[Orchestrator]** Invokes @cli-planning-agent via Task tool
+6. **[@cli-planning-agent]** Executes internally:
+   - Runs Gemini/Qwen CLI analysis with bug diagnosis template
+   - Parses CLI output to extract root causes and fix strategy
+   - Generates `IMPL-fix-N.json` with structured task definition
+   - Saves analysis report to `.process/iteration-N-analysis.md`
+   - Saves raw CLI output to `.process/iteration-N-cli-output.txt`
+7. **[Orchestrator]** Receives task ID from agent and inserts into queue
 
-**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
+**Key Change**: CLI execution + result parsing + task generation are now encapsulated in @cli-planning-agent, simplifying orchestrator logic.
 
-#### 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
+#### Agent Invocation Pattern (executed by orchestrator)
+```javascript
+Task(
+  subagent_type="cli-planning-agent",
+  description=`Analyze test failures and generate fix task (iteration ${currentIteration})`,
+  prompt=`
+    ## Context Package
+    {
+      "session_id": "${sessionId}",
+      "iteration": ${currentIteration},
+      "analysis_type": "test-failure",
+      "failure_context": {
+        "failed_tests": ${JSON.stringify(failedTests)},
+        "error_messages": ${JSON.stringify(errorMessages)},
+        "test_output": "${testOutputPath}",
+        "pass_rate": ${passRate},
+        "previous_attempts": ${JSON.stringify(previousAttempts)}
+      },
+      "cli_config": {
+        "tool": "gemini",
+        "model": "gemini-3-pro-preview-11-2025",
+        "template": "01-diagnose-bug-root-cause.txt",
+        "timeout": 2400000,
+        "fallback": "qwen"
+      },
+      "task_config": {
+        "agent": "@test-fix-agent",
+        "type": "test-fix-iteration",
+        "max_iterations": ${maxIterations},
+        "use_codex": false
+      }
+    }
 
-[Test failure context and requirements...]
-
-EXPECTED: Detailed fix strategy in markdown format
-RULES: Focus on minimal changes, avoid over-engineering
-"
+    ## Your Task
+    1. Execute CLI analysis using Gemini (fallback to Qwen if needed)
+    2. Parse CLI output and extract fix strategy with specific modification points
+    3. Generate IMPL-fix-${currentIteration}.json using your internal task template
+    4. Save analysis report to .process/iteration-${currentIteration}-analysis.md
+    5. Report success and task ID back to orchestrator
+  `
+)
 ```
 
-#### Analysis Output Structure
+#### Agent Response
+```javascript
+{
+  "status": "success",
+  "task_id": "IMPL-fix-${iteration}",
+  "task_path": ".workflow/${session}/.task/IMPL-fix-${iteration}.json",
+  "analysis_report": ".process/iteration-${iteration}-analysis.md",
+  "cli_output": ".process/iteration-${iteration}-cli-output.txt",
+  "summary": "Fix authentication token validation and null check issues",
+  "modification_points_count": 2,
+  "estimated_complexity": "low"
+}
+```
+
+#### Generated Analysis Report Structure
+The @cli-planning-agent generates `.process/iteration-N-analysis.md`:
+
 ```markdown
-# Test Failure Analysis - Iteration {N}
+---
+iteration: N
+analysis_type: test-failure
+cli_tool: gemini
+model: gemini-3-pro-preview-11-2025
+timestamp: 2025-11-10T10:00:00Z
+pass_rate: 85.0%
+---
+
+# Test Failure Analysis - Iteration N
+
+## Summary
+- **Failed Tests**: 2
+- **Pass Rate**: 85.0% (Target: 95%+)
+- **Root Causes Identified**: 2
+- **Modification Points**: 2
+
+## Failed Tests Details
+
+### test_auth_flow
+- **Error**: Expected 200, got 401
+- **File**: tests/test_auth.test.ts:45
+- **Criticality**: high
+
+### test_data_validation
+- **Error**: TypeError: Cannot read property 'name' of undefined
+- **File**: tests/test_validators.test.ts:23
+- **Criticality**: medium
 
 ## 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`
+[CLI output: 根本原因分析 section]
 
 ## Fix Strategy
+[CLI output: 详细修复建议 section]
 
-### 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
+## Modification Points
+- `src/auth/client.ts:sendRequest:45-50` - Add authentication token header
+- `src/validators/user.ts:validateUser:23-25` - Add null check before property access
 
-### 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
+## Expected Outcome
+[CLI output: 验证建议 section]
 
-## 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
+## CLI Raw Output
+See: `.process/iteration-N-cli-output.txt`
 ```
 
 ### Phase 5: Task Queue Management
@@ -321,27 +410,56 @@ After IMPL-fix-2 execution (success):
 #### Success Conditions
 - All initial tasks completed
 - All generated fix tasks completed
-- All tests passing
+- **Test pass rate === 100%** (all tests passing)
 - No pending tasks in queue
 
+#### Partial Success Conditions (NEW)
+- All initial tasks completed
+- Test pass rate >= 95% AND < 100%
+- All failures are "low" criticality (flaky tests, env-specific issues)
+- **Automatic Approval with Warning**: System auto-approves but marks session with review flag
+- Note: Generate completion summary with detailed warnings about low-criticality failures
+
 #### 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`
+2. **Calculate Final Pass Rate**: Parse test-results.json
+3. **Assess Completion Status**:
+   - If pass_rate === 100% → Full Success
+   - If pass_rate >= 95% + all "low" criticality → Partial Success (add review note)
+   - If pass_rate >= 95% + any "high"/"medium" criticality → Continue iteration
+   - If pass_rate < 95% → Failure
+4. **Update Session State**: Mark all tasks completed (or blocked if failure)
+5. **Generate Summary**: Create session completion summary with pass rate metrics
+6. **Update TodoWrite**: Mark all items completed
+7. **Auto-Complete**: Call `/workflow:session:complete` (for Full or Partial Success)
 
 #### Failure Conditions
-- Max iterations reached without success
-- Unrecoverable test failures
+- Max iterations (5) reached without achieving 95% pass rate
+- **Test pass rate < 95% after max iterations** (NEW)
+- Pass rate >= 95% but critical failures exist and max iterations reached
+- Unrecoverable test failures (infinite loop detection)
 - 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
+1. **Document State**: Save current iteration context with final pass rate
+2. **Generate Failure Report**: Include:
+   - Final pass rate (e.g., "85% after 5 iterations")
+   - Remaining failures with criticality assessment
+   - Iteration history and attempted fixes
+   - CLI analysis quality (normal/degraded)
+   - Recommendations for manual intervention
+3. **Preserve Context**: Keep all iteration logs and analysis reports
 4. **Mark Blocked**: Update task status to blocked
-5. **Return Control**: Return to user with detailed report
+5. **Return Control**: Return to user with detailed failure report
+
+#### Degraded Analysis Handling (NEW)
+When @cli-planning-agent returns `status: "degraded"` (both Gemini and Qwen failed):
+1. **Log Warning**: Record CLI analysis failure in iteration-state.json
+2. **Assess Risk**: Check if degraded analysis is acceptable:
+   - If iteration < 3 AND pass_rate improved: Accept degraded analysis, continue
+   - If iteration >= 3 OR pass_rate stagnant: Skip iteration, mark as blocked
+3. **User Notification**: Include CLI failure in completion summary
+4. **Fallback Strategy**: Use basic pattern matching from fix-history.json
 
 ## TodoWrite Coordination
 

.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md

@@ -58,6 +58,19 @@ This command is a **pure planning coordinator**:
 - Creates independent test workflow session
 - **All execution delegated to `/workflow:test-cycle-execute`**
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 ---
 
 ## Usage
@@ -128,9 +141,11 @@ This command is a **pure planning coordinator**:
 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
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 7. **Automatic Detection**: Mode auto-detected from input pattern
 8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+9. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+10. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ### 5-Phase Execution
 
@@ -202,9 +217,25 @@ This command is a **pure planning coordinator**:
 **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`
+- Generate **multi-layered test requirements** (L0: Static Analysis, L1: Unit, L2: Integration, L3: E2E)
+- Design test generation strategy with quality assurance criteria
+- Generate `TEST_ANALYSIS_RESULTS.md` with structured test layers
+
+**Enhanced Test Requirements**:
+For each targeted file/function, Gemini MUST generate:
+1. **L0: Static Analysis Requirements**:
+   - Linting rules to enforce (ESLint, Prettier)
+   - Type checking requirements (TypeScript)
+   - Anti-pattern detection rules
+2. **L1: Unit Test Requirements**:
+   - Happy path scenarios (valid inputs → expected outputs)
+   - Negative path scenarios (invalid inputs → error handling)
+   - Edge cases (null, undefined, 0, empty strings/arrays)
+3. **L2: Integration Test Requirements**:
+   - Successful component interactions
+   - Failure handling scenarios (service unavailable, timeout)
+4. **L3: E2E Test Requirements** (if applicable):
+   - Key user journeys from start to finish
 
 **Parse Output**:
 - Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
@@ -213,9 +244,18 @@ This command is a **pure planning coordinator**:
 - TEST_ANALYSIS_RESULTS.md exists with complete sections:
   - Coverage Assessment
   - Test Framework & Conventions
-  - Test Requirements by File
+  - **Multi-Layered Test Plan** (NEW):
+    - L0: Static Analysis Plan
+    - L1: Unit Test Plan
+    - L2: Integration Test Plan
+    - L3: E2E Test Plan (if applicable)
+  - Test Requirements by File (with layer annotations)
   - Test Generation Strategy
   - Implementation Targets
+  - Quality Assurance Criteria (NEW):
+    - Minimum coverage thresholds
+    - Required test types per function
+    - Acceptance criteria for test quality
   - Success Criteria
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
@@ -232,16 +272,18 @@ This command is a **pure planning coordinator**:
 - `--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):
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3 (multi-layered test plan)
+- Generate **minimum 3 task JSON files** (expandable based on complexity):
   - **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
+  - **IMPL-001.5-review.json**: Test Quality Gate (`@test-fix-agent`) ← **NEW**
   - **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 `IMPL_PLAN.md` with multi-layered test strategy
 - Generate `TODO_LIST.md` with task checklist
 
 **Parse Output**:
 - Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.5-review.json` exists ← **NEW**
 - Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
 - Verify additional `.task/IMPL-*.json` if applicable
 - Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
@@ -262,11 +304,16 @@ Test Session: [testSessionId]
 
 Tasks Created:
 - IMPL-001: Test Understanding & Generation (@code-developer)
+- IMPL-001.5: Test Quality Gate - Static Analysis & Coverage (@test-fix-agent) ← NEW
 - IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
 [- IMPL-003+: Additional tasks if applicable]
 
+Test Strategy: Multi-Layered (L0: Static, L1: Unit, L2: Integration, L3: E2E)
 Test Framework: [detected framework]
 Test Files to Generate: [count]
+Quality Thresholds:
+- Minimum Coverage: 80%
+- Static Analysis: Zero critical issues
 Max Fix Iterations: 5
 Fix Mode: [Manual|Codex Automated]
 
@@ -275,11 +322,12 @@ Review artifacts:
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 
 CRITICAL - Next Steps:
-1. Review IMPL_PLAN.md
+1. Review IMPL_PLAN.md (now includes multi-layered test strategy)
 2. **MUST execute: /workflow:test-cycle-execute**
    - This command only generated task JSON files
    - Test execution and fix iterations happen in test-cycle-execute
    - Do NOT attempt to run tests or fixes in main workflow
+3. IMPL-001.5 will validate test quality before fix cycle begins
 ```
 
 **TodoWrite**: Mark phase 5 completed
@@ -291,52 +339,133 @@ CRITICAL - Next Steps:
 
 ---
 
-### TodoWrite Progress Tracking
+### TodoWrite Pattern
 
-Track all 5 phases:
+**Core Concept**: Dynamic task attachment and collapse for test-fix-gen workflow with dual-mode support (Session Mode and Prompt Mode).
 
-```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"}
-]})
-```
+#### Key Principles
 
-Update status to `in_progress` when starting each phase, `completed` when done.
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` (Session Mode) or `/workflow:tools:context-gather` (Prompt Mode) attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
+
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Gather test coverage context: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED with mode-specific context gathering) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+#### Test-Fix-Gen Specific Features
+
+- **Dual-Mode Support**: Automatic mode detection based on input pattern
+  - **Session Mode**: Input pattern `WFS-*` → uses `test-context-gather` for cross-session context
+  - **Prompt Mode**: Text or file path → uses `context-gather` for direct codebase analysis
+- **Phase 2**: Mode-specific context gathering (session summaries vs codebase analysis)
+- **Phase 3**: Multi-layered test requirements analysis (L0: Static, L1: Unit, L2: Integration, L3: E2E)
+- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
+- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+
+**Benefits**:
+- Real-time visibility into attached tasks during execution
+- Clean orchestrator-level summary after tasks complete
+- Clear mental model: SlashCommand = attach tasks, not delegate work
+- Dual-mode support: Both Session Mode and Prompt Mode use same attachment pattern
+- Dynamic attachment/collapse maintains clarity
+
+**Note**: Unlike other workflow orchestrators, this file consolidates TodoWrite examples in this section rather than distributing them across Phase descriptions for better dual-mode clarity.
 
 ---
 
 ## Task Specifications
 
-Generates minimum 2 tasks (expandable for complex projects):
+Generates minimum 3 tasks (expandable for complex projects):
 
 ### IMPL-001: Test Understanding & Generation
 
 **Agent**: `@code-developer`
 
-**Purpose**: Understand source implementation and generate test files
+**Purpose**: Understand source implementation and generate test files following multi-layered test strategy
 
 **Task Configuration**:
 - Task ID: `IMPL-001`
 - `meta.type: "test-gen"`
 - `meta.agent: "@code-developer"`
-- `context.requirements`: Understand source implementation and generate tests
+- `context.requirements`: Understand source implementation and generate tests across all layers (L0-L3)
 - `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
+   - Analyze multi-layered test requirements (L0: Static, L1: Unit, L2: Integration, L3: E2E)
+   - Identify test scenarios, edge cases, and error paths
 2. **Generation Phase**:
-   - Generate test files following existing patterns
-   - Ensure test coverage aligns with requirements
+   - Generate L1 unit test files following existing patterns
+   - Generate L2 integration test files (if applicable)
+   - Generate L3 E2E test files (if applicable)
+   - Ensure test coverage aligns with multi-layered requirements
+   - Include both positive and negative test cases
 3. **Verification Phase**:
    - Verify test completeness and correctness
+   - Ensure each test has meaningful assertions
+   - Check for test anti-patterns (tests without assertions, overly broad mocks)
+
+### IMPL-001.5: Test Quality Gate ← **NEW**
+
+**Agent**: `@test-fix-agent`
+
+**Purpose**: Validate test quality before entering fix cycle - prevent "hollow tests" from becoming the source of truth
+
+**Task Configuration**:
+- Task ID: `IMPL-001.5-review`
+- `meta.type: "test-quality-review"`
+- `meta.agent: "@test-fix-agent"`
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Validate generated tests meet quality standards
+- `context.quality_config`: Load from `.claude/workflows/test-quality-config.json`
+
+**Execution Flow**:
+1. **L0: Static Analysis**:
+   - Run linting on test files (ESLint, Prettier)
+   - Check for test anti-patterns:
+     - Tests without assertions (`expect()` missing)
+     - Empty test bodies (`it('should...', () => {})`)
+     - Disabled tests without justification (`it.skip`, `xit`)
+   - Verify TypeScript type safety (if applicable)
+2. **Coverage Analysis**:
+   - Run coverage analysis on generated tests
+   - Calculate coverage percentage for target source files
+   - Identify uncovered branches and edge cases
+3. **Test Quality Metrics**:
+   - Verify minimum coverage threshold met (default: 80%)
+   - Verify all critical functions have negative test cases
+   - Verify integration tests cover key component interactions
+4. **Quality Gate Decision**:
+   - **PASS**: Coverage ≥ 80%, zero critical anti-patterns → Proceed to IMPL-002
+   - **FAIL**: Coverage < 80% OR critical anti-patterns found → Loop back to IMPL-001 with feedback
+
+**Acceptance Criteria**:
+- Static analysis: Zero critical issues
+- Test coverage: ≥ 80% for target files
+- Test completeness: All targeted functions have unit tests
+- Negative test coverage: Each public API has at least one error handling test
+- Integration coverage: Key component interactions have integration tests (if applicable)
+
+**Failure Handling**:
+If quality gate fails:
+1. Generate detailed feedback report (`.process/test-quality-report.md`)
+2. Update IMPL-001 task with specific improvement requirements
+3. Trigger IMPL-001 re-execution with enhanced context
+4. Maximum 2 quality gate retries before escalating to user
 
 ### IMPL-002: Test Execution & Fix Cycle
 
@@ -412,18 +541,62 @@ WFS-test-[session]/
 - `workflow_type: "test_session"`
 - No `source_session_id` field
 
-### Complete Data Flow
+### Execution Flow Diagram
 
-**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
+```
+Test-Fix-Gen Workflow Orchestrator (Dual-Mode Support)
+│
+├─ Phase 1: Create Test Session
+│  ├─ Session Mode: /workflow:session:start --new (with source_session_id)
+│  └─ Prompt Mode: /workflow:session:start --new (without source_session_id)
+│     └─ Returns: testSessionId (WFS-test-[slug])
+│
+├─ Phase 2: Gather Context                                   ← ATTACHED (3 tasks)
+│  ├─ Session Mode: /workflow:tools:test-context-gather
+│  │  └─ Load source session summaries + analyze coverage
+│  └─ Prompt Mode: /workflow:tools:context-gather
+│     └─ Analyze codebase from description
+│     ├─ Phase 2.1: Load context and analyze coverage
+│     ├─ Phase 2.2: Detect test framework and conventions
+│     └─ Phase 2.3: Generate context package
+│     └─ Returns: [test-]context-package.json                ← COLLAPSED
+│
+├─ Phase 3: Test Generation Analysis                         ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-concept-enhanced
+│     ├─ Phase 3.1: Analyze coverage gaps with Gemini
+│     ├─ Phase 3.2: Study existing test patterns
+│     └─ Phase 3.3: Generate test generation strategy
+│     └─ Returns: TEST_ANALYSIS_RESULTS.md                   ← COLLAPSED
+│
+├─ Phase 4: Generate Test Tasks                              ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-task-generate
+│     ├─ Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md
+│     ├─ Phase 4.2: Generate task JSONs (IMPL-001, IMPL-002)
+│     └─ Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md
+│     └─ Returns: Task JSONs and plans                       ← COLLAPSED
+│
+└─ Phase 5: Return Summary
+   └─ Command ends, control returns to user
 
-**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
+Artifacts Created:
+├── .workflow/WFS-test-[session]/
+│   ├── workflow-session.json
+│   ├── IMPL_PLAN.md
+│   ├── TODO_LIST.md
+│   ├── .task/
+│   │   ├── IMPL-001.json (test understanding & generation)
+│   │   ├── IMPL-002.json (test execution & fix cycle)
+│   │   └── IMPL-003.json (optional: test review & certification)
+│   └── .process/
+│       ├── [test-]context-package.json
+│       └── TEST_ANALYSIS_RESULTS.md
 
-**Command completes after Phase 5**
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
+• Dual-Mode: Session Mode and Prompt Mode share same attachment pattern
+• Command Boundary: Execution delegated to /workflow:test-cycle-execute
+```
 
 ---
 
@@ -473,9 +646,9 @@ WFS-test-[session]/
 - `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
 - `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
 - `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
-- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs with fix cycle specification
-- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
-- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
 
 **Follow-up Commands**:
 - `/workflow:status` - Review generated test tasks

.claude/skills/command-guide/reference/commands/workflow/test-gen.md

@@ -18,6 +18,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - **Parameter Simplification**: Tools auto-detect test session type via metadata, no manual cross-session parameters needed
 - **Manual First**: Default to manual fixes, use `--use-codex` flag for automated Codex fix application
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 **Execution Flow**:
 1. Initialize TodoWrite → Create test session → Parse session ID
 2. Gather cross-session context (automatic) → Parse context path
@@ -33,10 +46,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 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 5 completes (summary returned)
-6. **Track Progress**: Update TodoWrite after every phase completion
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 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.
+10. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+11. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 5-Phase Execution
 
@@ -89,7 +104,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - Test framework detected
 - Test conventions documented
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
+
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Phase 2.1: Load source session summaries (test-context-gather)", "status": "in_progress", "activeForm": "Loading source session summaries"},
+  {"content": "Phase 2.2: Analyze test coverage with MCP tools (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "Phase 2.3: Identify coverage gaps and framework (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.3** sequentially
+
+<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
 
 ---
 
@@ -121,7 +168,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
   - Implementation Targets (test files to create)
   - Success Criteria
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+<!-- TodoWrite: When test-concept-enhanced invoked, INSERT 3 concept-enhanced tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Phase 3.1: Analyze coverage gaps with Gemini (test-concept-enhanced)", "status": "in_progress", "activeForm": "Analyzing coverage gaps"},
+  {"content": "Phase 3.2: Study existing test patterns (test-concept-enhanced)", "status": "pending", "activeForm": "Studying test patterns"},
+  {"content": "Phase 3.3: Generate test generation strategy (test-concept-enhanced)", "status": "pending", "activeForm": "Generating test strategy"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-concept-enhanced's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 ---
 
@@ -173,7 +252,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
   - Phase 2: Iterative Gemini diagnosis + manual/Codex fixes (based on flag)
   - Phase 3: Final validation and certification
 
-**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
+<!-- TodoWrite: When test-task-generate invoked, INSERT 3 test-task-generate tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md (test-task-generate)", "status": "in_progress", "activeForm": "Parsing test analysis"},
+  {"content": "Phase 4.2: Generate IMPL-001.json and IMPL-002.json (test-task-generate)", "status": "pending", "activeForm": "Generating task JSONs"},
+  {"content": "Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md (test-task-generate)", "status": "pending", "activeForm": "Generating plan documents"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-task-generate's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "in_progress", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 ---
 
@@ -214,37 +325,76 @@ Ready for execution. Use appropriate workflow commands to proceed.
 
 ## TodoWrite Pattern
 
-Track progress through 5 phases:
+**Core Concept**: Dynamic task attachment and collapse for test-gen workflow with cross-session context gathering and test generation strategy.
 
-```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"}
-]})
-```
+### Key Principles
 
-Update status to `in_progress` when starting each phase, mark `completed` when done.
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-## Data Flow
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Gather test coverage context: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+### Test-Gen Specific Features
+
+- **Phase 2**: Cross-session context gathering from source implementation session
+- **Phase 3**: Test requirements analysis with Gemini for generation strategy
+- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
+- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+
+**Benefits**:
+- Real-time visibility into attached tasks during execution
+- Clean orchestrator-level summary after tasks complete
+- Clear mental model: SlashCommand = attach tasks, not delegate work
+- Dynamic attachment/collapse maintains clarity
+
+**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
+
+## Execution Flow Diagram
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│ /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
+Test-Gen Workflow Orchestrator
+│
+├─ Phase 1: Create Test Session
+│  └─ /workflow:session:start --new
+│     └─ Returns: testSessionId (WFS-test-[source])
+│
+├─ Phase 2: Gather Test Context                           ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-context-gather
+│     ├─ Phase 2.1: Load source session summaries
+│     ├─ Phase 2.2: Analyze test coverage with MCP tools
+│     └─ Phase 2.3: Identify coverage gaps and framework
+│     └─ Returns: test-context-package.json               ← COLLAPSED
+│
+├─ Phase 3: Test Generation Analysis                      ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-concept-enhanced
+│     ├─ Phase 3.1: Analyze coverage gaps with Gemini
+│     ├─ Phase 3.2: Study existing test patterns
+│     └─ Phase 3.3: Generate test generation strategy
+│     └─ Returns: TEST_ANALYSIS_RESULTS.md                ← COLLAPSED
+│
+├─ Phase 4: Generate Test Tasks                           ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-task-generate
+│     ├─ Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md
+│     ├─ Phase 4.2: Generate IMPL-001.json and IMPL-002.json
+│     └─ Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md
+│     └─ Returns: Task JSONs and plans                    ← COLLAPSED
+│
+└─ Phase 5: Return Summary
+   └─ Command ends, control returns to user
 
 Artifacts Created:
 ├── .workflow/WFS-test-[session]/
@@ -257,6 +407,10 @@ Artifacts Created:
 │   └── .process/
 │       ├── test-context-package.json
 │       └── TEST_ANALYSIS_RESULTS.md
+
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
 ```
 
 ## Session Metadata
@@ -337,9 +491,9 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
 - `/workflow:session:start` - Phase 1: Create independent test workflow session
 - `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
 - `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
-- `/workflow:tools:test-task-generate` - Phase 4: Generate test generation and execution task JSONs
-- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes (when `--use-codex` flag used)
-- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode (when `--cli-execute` flag used)
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
 
 **Follow-up Commands**:
 - `/workflow:status` - Review generated test tasks

.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md

@@ -24,6 +24,7 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
 | **Generate Strategies** | Provide 2-4 resolution options per conflict |
 | **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
 | **User Decision** | Present options, never auto-apply |
+| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
 | **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
 
 ## Conflict Categories
@@ -462,10 +463,3 @@ If Edit tool fails mid-application:
 ✓ Error handling robust (validate/retry/degrade)
 ```
 
-## Related Commands
-| Command | Relationship |
-|---------|--------------|
-| `/workflow:tools:context-gather` | Generates input conflict_detection data |
-| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
-| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
-| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md

@@ -163,155 +163,50 @@ If conflict_risk was medium/high, modifications have been applied to:
 
 ## Phase 2: Document Generation Task
 
-### 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
+**Agent Configuration Reference**: All task generation rules, quantification requirements, quality standards, and execution details are defined in action-planning-agent.
 
-**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)
+Refer to: @.claude/agents/action-planning-agent.md for:
+- Task Decomposition Standards
+- Quantification Requirements (MANDATORY)
+- 5-Field Task JSON Schema
+- IMPL_PLAN.md Structure
+- TODO_LIST.md Format
+- Execution Flow & Quality Validation
 
-### Required Outputs
+### Required Outputs Summary
 
 #### 1. Task JSON Files (.task/IMPL-*.json)
-**Location**: .workflow/{session-id}/.task/
-**Template**: Read from the template path provided above
-
-**Task JSON Template Loading**:
-\`\`\`
-Read({template_path})
-\`\`\`
-
-**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)
+- **Location**: `.workflow/{session-id}/.task/`
+- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
+- **Schema**: 5-field structure (id, title, status, meta, context, flow_control) with artifacts integration
+- **Details**: See action-planning-agent.md § Task JSON Generation
 
 #### 2. IMPL_PLAN.md
-**Location**: .workflow/{session-id}/IMPL_PLAN.md
-
-**IMPL_PLAN Template**:
-\`\`\`
-$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
-\`\`\`
-
-**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 role analyses and context-package.json
-- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
-- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
+- **Location**: `.workflow/{session-id}/IMPL_PLAN.md`
+- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
+- **Details**: See action-planning-agent.md § Implementation Plan Creation
 
 #### 3. TODO_LIST.md
-**Location**: .workflow/{session-id}/TODO_LIST.md
-**Structure**:
-\`\`\`markdown
-# Tasks: {Session Topic}
+- **Location**: `.workflow/{session-id}/TODO_LIST.md`
+- **Format**: Hierarchical task list with status indicators (▸, [ ], [x]) and JSON links
+- **Details**: See action-planning-agent.md § TODO List Generation
 
-## Task Progress
-▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
-  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
-  - [ ] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json)
+### Agent Execution Summary
 
-- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
+**Key Steps** (Detailed instructions in action-planning-agent.md):
+1. Load task JSON template from provided path
+2. Extract and decompose tasks with quantification
+3. Generate task JSON files enforcing quantification requirements
+4. Create IMPL_PLAN.md using template
+5. Generate TODO_LIST.md matching task JSONs
+6. Update session state
 
-## Status Legend
-- \`▸\` = Container task (has subtasks)
-- \`- [ ]\` = Pending leaf task
-- \`- [x]\` = Completed leaf task
-\`\`\`
-
-### Execution Instructions for Agent
-
-**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
-
-**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 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 2: Extract and Decompose Tasks**
-- Parse role analysis.md files for requirements, design specs, and task recommendations
-- Review synthesis enhancements and clarifications in role analyses
-- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
-- Apply task merging rules (merge when possible, decompose only when necessary)
-- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
-- 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 6: Update Session State**
-- Update workflow-session.json with task count and artifact inventory
-- Mark session ready for execution
-
-### MCP Enhancement Examples
-
-**Code Index Usage**:
-\`\`\`javascript
-// Discover authentication-related files
-bash(find . -name "*auth*" -type f)
-
-// Search for OAuth patterns
-bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
-
-// Get file summary for key components
-bash(rg "^(class|function|export|interface)" src/auth/index.ts)
-\`\`\`
-
-**Exa Research Usage**:
-\`\`\`javascript
-// Get best practices for task implementation
-mcp__exa__get_code_context_exa(
-  query="TypeScript OAuth2 implementation patterns",
-  tokensNum="dynamic"
-)
-
-// Research specific API usage
-mcp__exa__get_code_context_exa(
-  query="Express.js JWT middleware examples",
-  tokensNum=5000
-)
-\`\`\`
-
-### Quality Validation
-
-Before completion, verify:
-- [ ] All task JSON files created in .task/ directory
-- [ ] Each task JSON has 5 required fields
-- [ ] Artifact references correctly mapped
-- [ ] Flow control includes artifact loading steps
-- [ ] MCP tool integration added where appropriate
-- [ ] IMPL_PLAN.md follows required structure
-- [ ] TODO_LIST.md matches task JSONs
-- [ ] Dependency graph is acyclic
-- [ ] Task count within limits (≤10)
-- [ ] Session state updated
+**Quality Gates** (Full checklist in action-planning-agent.md):
+- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
+- ✓ Task count ≤10 (hard limit)
+- ✓ Artifact references mapped correctly
+- ✓ MCP tool integration added
+- ✓ Documents follow template structure
 
 ## Output
 

.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md

@@ -1,14 +1,28 @@
 ---
 name: task-generate-tdd
-description: Generate TDD task chains with Red-Green-Refactor dependencies, test-first structure, and cycle validation
-argument-hint: "--session WFS-session-id [--agent]"
-allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
+description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
+argument-hint: "--session WFS-session-id [--cli-execute]"
+examples:
+  - /workflow:tools:task-generate-tdd --session WFS-auth
+  - /workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
 ---
 
-# TDD Task Generation Command
+# Autonomous TDD Task Generation Command
 
 ## Overview
-Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
+Autonomous TDD 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. Generates complete Red-Green-Refactor cycles contained within each task.
+
+## 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 TDD template based on `--cli-execute` flag **before** invoking agent
+- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
+- **TDD-First**: Every feature starts with a failing test (Red phase)
+- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
+- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations
 
 ## Task Strategy & Philosophy
 
@@ -44,359 +58,329 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
 - **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
-- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
-- **Artifact-Aware**: Integrates brainstorming outputs
-- **Memory-First**: Reuse loaded documents from memory
-- **Context-Aware**: Analyzes existing codebase and test patterns
-- **Iterative Green Phase**: Auto-diagnose and fix test failures with Gemini + optional Codex
-- **Safety-First**: Auto-revert on max iterations to prevent broken state
-
-## Core Responsibilities
-- Parse analysis results and identify testable features
-- 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
+### Phase 1: Discovery & Context Loading
+**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
 
-1. **Session Validation**
-   - If session metadata in memory → Skip loading
-   - Else: Load `.workflow/{session_id}/workflow-session.json`
-
-2. **Conflict Resolution Check** (NEW - Priority Input)
-   - If CONFLICT_RESOLUTION.md exists → Load selected strategies
-   - Else: Skip to brainstorming artifacts
-   - Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md`
-
-3. **Artifact Discovery**
-   - If artifact inventory in memory → Skip scanning
-   - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
-   - Detect: role analysis documents, guidance-specification.md, role analyses
-
-4. **Context Package Loading**
-   - Load `.workflow/{session_id}/.process/context-package.json`
-   - Load `.workflow/{session_id}/.process/test-context-package.json` (if exists)
-
-### Phase 2: TDD Task JSON Generation
-
-**Input Sources** (priority order):
-1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies
-2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.)
-3. **Context Package**: `.process/context-package.json` - Project structure and requirements
-4. **Test Context**: `.process/test-context-package.json` - Existing test patterns
-
-**TDD Task Structure includes**:
-- Feature list with testable requirements
-- Test cases for Red phase
-- Implementation requirements for Green phase (with test-fix cycle)
-- Refactoring opportunities
-- Task dependencies and execution order
-- Conflict resolution decisions (if applicable)
-
-### Phase 3: Task JSON & IMPL_PLAN.md Generation
-
-#### 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)
-
-**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**:
-- **All IMPL tasks** → `@code-developer` (handles full TDD cycle)
-- Agent executes Red, Green, Refactor phases sequentially within task
-
-**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 Structure Reference
-
-**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
-```json
+**Agent Context Package**:
+```javascript
 {
-  "id": "IMPL-N",                                  // Task identifier
-  "title": "Feature description with TDD",         // Human-readable title
-  "status": "pending",                             // pending | in_progress | completed | container
-  "context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
-  "meta": {
-    "type": "feature",                             // Task type
-    "agent": "@code-developer",                    // Assigned agent
-    "tdd_workflow": true,                          // REQUIRED: Enables TDD flow
-    "max_iterations": 3,                           // Green phase test-fix cycle limit
-    "use_codex": false                             // false=manual fixes, true=Codex automated fixes
+  "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
+  "workflow_type": "tdd",
+  "session_metadata": {
+    // If in memory: use cached content
+    // Else: Load from .workflow/{session-id}/workflow-session.json
   },
-  "context": {
-    "requirements": [                              // Feature requirements with TDD phases
-      "Feature description",
-      "Red: Test scenarios to write",
-      "Green: Implementation approach with test-fix cycle",
-      "Refactor: Code quality improvements"
-    ],
-    "tdd_cycles": [                                // OPTIONAL: Detailed test cycles
+  "brainstorm_artifacts": {
+    // Loaded from context-package.json → brainstorm_artifacts section
+    "role_analyses": [
       {
-        "cycle": 1,
-        "feature": "Specific functionality",
-        "test_focus": "What to test",
-        "expected_failure": "Why test should fail initially"
+        "role": "system-architect",
+        "files": [{"path": "...", "type": "primary|supplementary"}]
       }
     ],
-    "focus_paths": ["D:\\project\\src\\path", "./tests/path"],  // Absolute or clear relative paths from project root
-    "acceptance": [                                // Success criteria
-      "All tests pass (Red → Green)",
-      "Code refactored (Refactor complete)",
-      "Test coverage ≥80%"
-    ],
-    "depends_on": []                               // Task dependencies
+    "guidance_specification": {"path": "...", "exists": true},
+    "synthesis_output": {"path": "...", "exists": true},
+    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
   },
-  "flow_control": {
-    "pre_analysis": [                              // OPTIONAL: Pre-execution checks
-      {
-        "step": "check_test_framework",
-        "action": "Verify test framework",
-        "command": "bash(npm list jest)",
-        "output_to": "test_framework_info",
-        "on_error": "warn"
-      }
-    ],
-    "implementation_approach": [                   // REQUIRED: 3 TDD phases
-      {
-        "step": 1,
-        "title": "RED Phase: Write failing tests",
-        "tdd_phase": "red",                        // REQUIRED: Phase identifier
-        "description": "Write comprehensive failing tests",
-        "modification_points": ["Files/changes to make"],
-        "logic_flow": ["Step-by-step process"],
-        "acceptance": ["Phase success criteria"],
-        "depends_on": [],
-        "output": "failing_tests"
-      },
-      {
-        "step": 2,
-        "title": "GREEN Phase: Implement to pass tests",
-        "tdd_phase": "green",                      // REQUIRED: Phase identifier
-        "description": "Minimal implementation with test-fix cycle",
-        "modification_points": ["Implementation files"],
-        "logic_flow": [
-          "Implement minimal code",
-          "Run tests",
-          "If fail → Enter iteration loop (max 3):",
-          "  1. Extract failure messages",
-          "  2. Gemini bug-fix diagnosis",
-          "  3. Apply fixes",
-          "  4. Rerun tests",
-          "If max_iterations → Auto-revert"
-        ],
-        "acceptance": ["All tests pass"],
-        "command": "bash(npm test -- tests/path/)",
-        "depends_on": [1],
-        "output": "passing_implementation"
-      },
-      {
-        "step": 3,
-        "title": "REFACTOR Phase: Improve code quality",
-        "tdd_phase": "refactor",                   // REQUIRED: Phase identifier
-        "description": "Refactor while keeping tests green",
-        "modification_points": ["Quality improvements"],
-        "logic_flow": ["Incremental refactoring with test verification"],
-        "acceptance": ["Tests still pass", "Code quality improved"],
-        "command": "bash(npm run lint && npm test)",
-        "depends_on": [2],
-        "output": "refactored_implementation"
-      }
-    ],
-    "post_completion": [                           // OPTIONAL: Final verification
-      {
-        "step": "verify_full_tdd_cycle",
-        "action": "Confirm complete TDD cycle",
-        "command": "bash(npm test && echo 'TDD complete')",
-        "output_to": "final_validation",
-        "on_error": "fail"
-      }
-    ],
-    "error_handling": {                            // OPTIONAL: Error recovery
-      "green_phase_max_iterations": {
-        "action": "revert_all_changes",
-        "commands": ["bash(git reset --hard HEAD)"],
-        "report": "Generate failure report"
-      }
-    }
+  "context_package_path": ".workflow/{session-id}/.process/context-package.json",
+  "context_package": {
+    // If in memory: use cached content
+    // Else: Load from .workflow/{session-id}/.process/context-package.json
+  },
+  "test_context_package_path": ".workflow/{session-id}/.process/test-context-package.json",
+  "test_context_package": {
+    // Existing test patterns and coverage analysis
+  },
+  "mcp_capabilities": {
+    "code_index": true,
+    "exa_code": true,
+    "exa_web": true
   }
 }
 ```
 
-**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)
+**Discovery Actions**:
+1. **Load Session Context** (if not in memory)
+   ```javascript
+   if (!memory.has("workflow-session.json")) {
+     Read(.workflow/{session-id}/workflow-session.json)
+   }
+   ```
 
-#### IMPL_PLAN.md Structure
+2. **Load Context Package** (if not in memory)
+   ```javascript
+   if (!memory.has("context-package.json")) {
+     Read(.workflow/{session-id}/.process/context-package.json)
+   }
+   ```
 
-Generate IMPL_PLAN.md with 8-section structure:
+3. **Load Test Context Package** (if not in memory)
+   ```javascript
+   if (!memory.has("test-context-package.json")) {
+     Read(.workflow/{session-id}/.process/test-context-package.json)
+   }
+   ```
 
-**Frontmatter** (required fields):
-```yaml
----
-identifier: WFS-{session-id}
-source: "User requirements" | "File: path"
-conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md  # if exists
-context_package: .workflow/{session-id}/.process/context-package.json
-context_package_path: .workflow/{session-id}/.process/context-package.json
-test_context: .workflow/{session-id}/.process/test-context-package.json  # if exists
-workflow_type: "tdd"
-verification_history:
-  conflict_resolution: "executed | skipped" # based on conflict_risk
-  action_plan_verify: "pending"
-phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
-feature_count: N
-task_count: N  # ≤10 total
-task_breakdown:
-  simple_features: K
-  complex_features: L
-  total_subtasks: M
-tdd_workflow: true
----
+4. **Extract & Load Role Analyses** (from context-package.json)
+   ```javascript
+   // Extract role analysis paths from context package
+   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
+     .flatMap(role => role.files.map(f => f.path));
+
+   // Load each role analysis file
+   roleAnalysisPaths.forEach(path => Read(path));
+   ```
+
+5. **Load Conflict Resolution** (from context-package.json, if exists)
+   ```javascript
+   if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
+     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
+   }
+   ```
+
+6. **Code Analysis with Native Tools** (optional - enhance understanding)
+   ```bash
+   # Find relevant test files and patterns
+   find . -name "*test*" -type f
+   rg "describe|it\(|test\(" -g "*.ts"
+   ```
+
+7. **MCP External Research** (optional - gather TDD best practices)
+   ```javascript
+   // Get external TDD examples and patterns
+   mcp__exa__get_code_context_exa(
+     query="TypeScript TDD best practices Red-Green-Refactor",
+     tokensNum="dynamic"
+   )
+   ```
+
+### 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";
 ```
 
-**8 Sections Structure**:
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="action-planning-agent",
+  description="Generate TDD task JSON and implementation plan",
+  prompt=`
+## Execution Context
 
-```markdown
-# Implementation Plan: {Project Title}
+**Session ID**: WFS-{session-id}
+**Workflow Type**: TDD
+**Execution Mode**: {agent-mode | cli-execute-mode}
+**Task JSON Template Path**: {template_path}
 
-## 1. Summary
-- Core requirements and objectives (2-3 paragraphs)
-- TDD-specific technical approach
+## Phase 1: Discovery Results (Provided Context)
 
-## 2. Context Analysis
-- CCW Workflow Context (Phase progression, Quality gates)
-- Context Package Summary (Focus paths, Test context)
-- Project Profile (Type, Scale, Tech Stack, Timeline)
-- Module Structure (Directory tree)
-- Dependencies (Primary, Testing, Development)
-- Patterns & Conventions
+### Session Metadata
+{session_metadata_content}
 
-## 3. Brainstorming Artifacts Reference
-- Artifact Usage Strategy
-  - CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
-  - role analysis documents (primary reference)
-  - test-context-package.json (test patterns)
-  - context-package.json (smart context)
-- Artifact Priority in Development
+### Role Analyses (Enhanced by Synthesis)
+{role_analyses_content}
+- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
 
-## 4. Implementation Strategy
-- Execution Strategy (TDD Cycles: Red-Green-Refactor)
-- Architectural Approach
-- Key Dependencies (Task dependency graph)
-- Testing Strategy (Coverage targets, Quality gates)
+### Artifacts Inventory
+- **Guidance Specification**: {guidance_spec_path}
+- **Role Analyses**: {role_analyses_list}
 
-## 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
+### Context Package
+{context_package_summary}
+- Includes conflict_risk assessment
 
-## 6. Implementation Plan (Detailed Phased Breakdown)
-- Execution Strategy (feature-by-feature sequential)
-- Phase breakdown (Phase 1, Phase 2, etc.)
-- Resource Requirements (Team, Dependencies, Infrastructure)
+### Test Context Package
+{test_context_package_summary}
+- Existing test patterns, framework config, coverage analysis
 
-## 7. Risk Assessment & Mitigation
-- Risk table (Risk, Impact, Probability, Mitigation, Owner)
-- Critical Risks (TDD-specific)
-- Monitoring Strategy
+### Conflict Resolution (Conditional)
+If conflict_risk was medium/high, modifications have been applied to:
+- **guidance-specification.md**: Design decisions updated to resolve conflicts
+- **Role analyses (*.md)**: Recommendations adjusted for compatibility
+- **context-package.json**: Marked as "resolved" with conflict IDs
+- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
 
-## 8. Success Criteria
-- Functional Completeness
-- Technical Quality (Test coverage ≥80%)
-- Operational Readiness
-- TDD Compliance
+### MCP Analysis Results (Optional)
+**Code Structure**: {mcp_code_index_results}
+**External Research**: {mcp_exa_research_results}
+
+## Phase 2: TDD Document Generation Task
+
+**Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent.
+
+Refer to: @.claude/agents/action-planning-agent.md for:
+- TDD Task Decomposition Standards
+- Red-Green-Refactor Cycle Requirements
+- Quantification Requirements (MANDATORY)
+- 5-Field Task JSON Schema
+- IMPL_PLAN.md Structure (TDD variant)
+- TODO_LIST.md Format
+- TDD Execution Flow & Quality Validation
+
+### TDD-Specific Requirements Summary
+
+#### Task Structure Philosophy
+- **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)
+- Subtasks only when complexity >2500 lines or >6 files per cycle
+- **Maximum 10 tasks** (hard limit for TDD workflows)
+
+#### TDD Cycle Mapping
+- **Simple features**: IMPL-N with internal Red-Green-Refactor phases
+- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks)
+- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage
+
+#### Required Outputs Summary
+
+##### 1. TDD Task JSON Files (.task/IMPL-*.json)
+- **Location**: `.workflow/{session-id}/.task/`
+- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
+- **Schema**: 5-field structure with TDD-specific metadata
+  - `meta.tdd_workflow`: true (REQUIRED)
+  - `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
+  - `meta.use_codex`: false (manual fixes by default)
+  - `context.tdd_cycles`: Array with quantified test cases and coverage
+  - `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
+    1. Red Phase (`tdd_phase: "red"`): Write failing tests
+    2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
+    3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
+- **Details**: See action-planning-agent.md § TDD Task JSON Generation
+
+##### 2. IMPL_PLAN.md (TDD Variant)
+- **Location**: `.workflow/{session-id}/IMPL_PLAN.md`
+- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
+- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
+- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
+- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
+
+##### 3. TODO_LIST.md
+- **Location**: `.workflow/{session-id}/TODO_LIST.md`
+- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
+- **Status**: ▸ (container), [ ] (pending), [x] (completed)
+- **Details**: See action-planning-agent.md § TODO List Generation
+
+### Quantification Requirements (MANDATORY)
+
+**Core Rules**:
+1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list
+2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%")
+3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts
+4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts
+
+**TDD Phase Formats**:
+- **Red Phase**: "Write N test cases: [test1, test2, ...]"
+- **Green Phase**: "Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"
+- **Refactor Phase**: "Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"
+- **Acceptance**: "All N tests pass with >=X% coverage: verify by [test command]"
+
+**Validation Checklist**:
+- [ ] Every Red phase specifies exact test case count with enumerated list
+- [ ] Every Green phase enumerates files, functions, and estimated line counts
+- [ ] Every Refactor phase lists specific improvements with counts
+- [ ] Every acceptance criterion includes measurable coverage percentage
+- [ ] tdd_cycles array contains test_count and test_cases for each cycle
+- [ ] No vague language ("comprehensive", "complete", "thorough")
+
+### Agent Execution Summary
+
+**Key Steps** (Detailed instructions in action-planning-agent.md):
+1. Load task JSON template from provided path
+2. Extract and decompose features with TDD cycles
+3. Generate TDD task JSON files enforcing quantification requirements
+4. Create IMPL_PLAN.md using TDD template variant
+5. Generate TODO_LIST.md with TDD phase indicators
+6. Update session state with TDD metadata
+
+**Quality Gates** (Full checklist in action-planning-agent.md):
+- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
+- ✓ Task count ≤10 (hard limit)
+- ✓ Each task has meta.tdd_workflow: true
+- ✓ Each task has exactly 3 implementation steps with tdd_phase field
+- ✓ Green phase includes test-fix cycle logic
+- ✓ Artifact references mapped correctly
+- ✓ MCP tool integration added
+- ✓ Documents follow TDD template structure
+
+## Output
+
+Generate all three documents and report completion status:
+- TDD task JSON files created: N files (IMPL-*.json)
+- TDD cycles configured: N cycles with quantified test cases
+- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
+- Test context integrated: existing patterns and coverage
+- MCP enhancements: code-index, exa-research
+- Session ready for TDD execution: /workflow:execute
+`
+)
 ```
 
-### Phase 4: TODO_LIST.md Generation
+### Agent Context Passing
 
-Generate task list with internal TDD phase indicators:
+**Memory-Aware Context Assembly**:
+```javascript
+// Assemble context package for agent
+const agentContext = {
+  session_id: "WFS-[id]",
+  workflow_type: "tdd",
 
-**For Simple Features (1 task per feature)**:
-```markdown
-## TDD Implementation Tasks
+  // 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),
 
-### Feature 1: {Feature Name}
-- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
-  - Internal phases: Red → Green → Refactor
-  - Dependencies: None
+  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
 
-### Feature 2: {Feature Name}
-- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
-  - Internal phases: Red → Green → Refactor
-  - Dependencies: IMPL-1
-```
+  context_package: memory.has("context-package.json")
+    ? memory.get("context-package.json")
+    : Read(".workflow/WFS-[id]/.process/context-package.json"),
 
-**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
-```
+  test_context_package_path: ".workflow/WFS-[id]/.process/test-context-package.json",
 
-**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
-```
+  test_context_package: memory.has("test-context-package.json")
+    ? memory.get("test-context-package.json")
+    : Read(".workflow/WFS-[id]/.process/test-context-package.json"),
 
-### Phase 5: Session State Update
+  // Extract brainstorm artifacts from context package
+  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
 
-Update workflow-session.json with TDD metadata:
-```json
-{
-  "workflow_type": "tdd",
-  "feature_count": 5,
-  "task_count": 5,
-  "task_breakdown": {
-    "simple_features": 4,
-    "complex_features": 1,
-    "total_subtasks": 2
-  },
-  "tdd_workflow": true,
-  "task_limit_compliance": true
+  // Load role analyses using paths from context package
+  role_analyses: brainstorm_artifacts.role_analyses
+    .flatMap(role => role.files)
+    .map(file => Read(file.path)),
+
+  // Load conflict resolution if exists (from context package)
+  conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
+    ? Read(brainstorm_artifacts.conflict_resolution.path)
+    : null,
+
+  // Optional MCP enhancements
+  mcp_analysis: executeMcpDiscovery()
 }
 ```
 
-**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)
+## TDD Task Structure Reference
+
+This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
+
+**Quick Reference**:
+- Each TDD task contains complete Red-Green-Refactor cycle
+- Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks)
+- Required metadata: `meta.tdd_workflow: true`, `meta.max_iterations: 3`
+- Flow control: Exactly 3 steps with `tdd_phase` field (red, green, refactor)
+- Context: `tdd_cycles` array with quantified test cases and coverage
+- See Phase 2 agent prompt for full schema and requirements
 
 ## Output Files Structure
 ```
@@ -465,52 +449,30 @@ Update workflow-session.json with TDD metadata:
 
 ## Integration & Usage
 
-### Command Chain
-- **Called By**: `/workflow:tdd-plan` (Phase 4)
-- **Calls**: Gemini CLI for TDD breakdown
-- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
+**Command Chain**:
+- Called by: `/workflow:tdd-plan` (Phase 4)
+- Invokes: `action-planning-agent` for autonomous task generation
+- Followed by: `/workflow:execute`, `/workflow:tdd-verify`
 
-### Basic Usage
+**Basic Usage**:
 ```bash
-# Manual mode (default)
+# Agent mode (default, autonomous execution)
 /workflow:tools:task-generate-tdd --session WFS-auth
 
-# Agent mode (autonomous task generation)
-/workflow:tools:task-generate-tdd --session WFS-auth --agent
+# CLI tool mode (use Gemini/Qwen for generation)
+/workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
 ```
 
-### Expected Output
-```
-TDD task generation complete for session: WFS-auth
+**Execution Modes**:
+- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
+- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen with cli-mode task template
 
-Features analyzed: 5
-Total tasks: 5 (1 task per feature with internal TDD cycles)
-
-Task breakdown:
-- Simple features: 4 tasks (IMPL-1 to IMPL-4)
-- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
-- Total task count: 6 (within 10-task limit)
-
-Structure:
-- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
-- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
-- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
-- IMPL-4: Role Management (Internal: Red → Green → Refactor)
-- IMPL-5: Payment System (Container)
-  - IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
-  - IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
-
-Plans generated:
-- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
-- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
-
-TDD Configuration:
-- Each task contains complete Red-Green-Refactor cycle
-- Green phase includes test-fix cycle (max 3 iterations)
-- Auto-revert on max iterations reached
-
-Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
-```
+**Output**:
+- TDD task JSON files in `.task/` directory (IMPL-N.json format)
+- IMPL_PLAN.md with TDD Implementation Tasks section
+- TODO_LIST.md with internal TDD phase indicators
+- Session state updated with task count and TDD metadata
+- MCP enhancements integrated (if available)
 
 ## Test Coverage Analysis Integration
 
@@ -547,9 +509,3 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
 - **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
 - **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
 
-## Related Commands
-- `/workflow:tdd-plan` - Orchestrates TDD workflow planning (6 phases)
-- `/workflow:tools:test-context-gather` - Analyzes test coverage
-- `/workflow:execute` - Executes TDD tasks in order
-- `/workflow:tdd-verify` - Verifies TDD compliance
-- `/workflow:test-gen` - Post-implementation test generation

.claude/skills/command-guide/reference/commands/workflow/tools/task-generate.md

@@ -45,8 +45,33 @@ This command is built on a set of core principles to ensure efficient and reliab
 - **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
 - **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
 - **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
+- **Quantification-Enforced**: **NEW** - All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations to prevent ambiguity (e.g., "17 commands: [list]" not "implement commands")
 - **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
 
+## 3.5. Quantification Requirements (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
+
+**Core Rules**:
+1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
+2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
+3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
+4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
+5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
+
+**Standard Formats**:
+
+- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
+- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
+- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
+
+**Validation Checklist**:
+- [ ] Every requirement contains explicit count or enumerated list
+- [ ] Every acceptance criterion is measurable with verification command
+- [ ] Every modification_point specifies exact targets (files/functions/lines)
+- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
+- [ ] Each implementation step has its own acceptance criteria
+
 ## 4. Execution Flow
 The command follows a streamlined, three-step process to convert analysis into executable tasks.
 
@@ -59,13 +84,39 @@ The process begins by gathering all necessary inputs. It follows a **Memory-Firs
 
 ### Step 2: Task Decomposition & Grouping
 Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
-1.  **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies.
-2.  **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`.
+
+**Phase 2.1: Quantification Extraction (NEW - CRITICAL)**
+1. **Count Extraction**: Scan analysis documents for quantifiable information:
+   - Search for numbers + nouns (e.g., "5 files", "17 commands", "3 features")
+   - Identify enumerated lists (bullet points, numbered lists, comma-separated items)
+   - Extract explicit counts from tables, diagrams, or structured data
+   - Store extracted counts with their context (what is being counted)
+
+2. **List Enumeration**: Build explicit lists for each deliverable:
+   - If analysis says "implement session commands", enumerate ALL commands: [start, resume, list, complete, archive]
+   - If analysis mentions "create categories", list ALL categories: [literature, experiment, data-analysis, visualization, context]
+   - If analysis describes "modify functions", list ALL functions with line numbers
+   - Maintain full enumerations (no "..." unless list exceeds 20 items)
+
+3. **Verification Method Assignment**: For each deliverable, determine verification approach:
+   - File count: `ls {path}/*.{ext} | wc -l = {count}`
+   - Directory existence: `ls {parent}/ | grep -E '(name1|name2|...)' | wc -l = {count}`
+   - Test coverage: `pytest --cov={module} --cov-report=term | grep TOTAL | awk '{print $4}' >= {percentage}`
+   - Function existence: `grep -E '(func1|func2|...)' {file} | wc -l = {count}`
+
+4. **Ambiguity Detection**: Flag vague language for replacement:
+   - Detect words: "complete", "comprehensive", "reorganize", "refactor", "implement", "create" without counts
+   - Require quantification: "implement" → "implement {N} {items}: [{list}]"
+   - Reject unquantified deliverables
+
+**Phase 2.2: Task Definition & Grouping**
+1.  **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies from quantified analysis
+2.  **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`
 3.  **Task Grouping**:
-    *   Tasks with the **same signature** are candidates for merging, as they operate on the same context.
-    *   Tasks with **different signatures** and no dependencies are grouped for parallel execution.
-    *   Tasks with `depends_on` relationships are marked for sequential execution.
-4.  **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field.
+    *   Tasks with the **same signature** are candidates for merging, as they operate on the same context
+    *   Tasks with **different signatures** and no dependencies are grouped for parallel execution
+    *   Tasks with `depends_on` relationships are marked for sequential execution
+4.  **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field
 
 ### Step 3: Output Generation
 Finally, the command generates all the necessary output files.
@@ -167,38 +218,82 @@ function assignExecutionGroups(tasks) {
 The command produces three key documents and a directory of task files.
 
 ### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
-This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
+Each task JSON embeds all necessary context, artifacts, and execution steps using this schema:
 
+**Top-Level Fields**:
+- `id`: Task identifier (format: `IMPL-N` or `IMPL-N.M` for subtasks)
+- `title`: Descriptive task name
+- `status`: Task state (`pending|active|completed|blocked|container`)
+- `context_package_path`: Path to context package (`.workflow/WFS-[session]/.process/context-package.json`)
+- `meta`: Task metadata
+- `context`: Task-specific context and requirements
+- `flow_control`: Execution steps and workflow
+
+**Meta Object**:
+- `type`: Task category (`feature|bugfix|refactor|test-gen|test-fix|docs`)
+- `agent`: Assigned agent (`@code-developer|@test-fix-agent|@universal-executor`)
+- `execution_group`: Parallelization group ID or null
+- `context_signature`: Hash for context-based grouping
+
+**Context Object**:
+- `requirements`: Quantified implementation requirements (with counts and explicit lists)
+- `focus_paths`: Target directories/files (absolute or relative paths)
+- `acceptance`: Measurable acceptance criteria (with verification commands)
+- `parent`: Parent task ID for subtasks
+- `depends_on`: Prerequisite task IDs
+- `inherited`: Shared patterns and dependencies from parent
+- `shared_context`: Tech stack and conventions
+- `artifacts`: Referenced brainstorm artifacts with paths, priority, and usage
+
+**Flow Control Object**:
+- `pre_analysis`: Context loading and preparation steps
+  - `load_context_package`: Load smart context and artifact catalog
+  - `load_role_analysis_artifacts`: Load role analyses dynamically from context package
+  - `load_planning_context`: Load finalized decisions with resolved conflicts
+  - `codebase_exploration`: Discover existing patterns
+  - `analyze_task_patterns`: Identify modification targets
+- `implementation_approach`: Execution steps
+  - **Agent Mode**: Steps contain `modification_points` and `logic_flow` (agent executes autonomously)
+  - **CLI Mode**: Steps include `command` field with CLI tool invocation
+- `target_files`: Specific files/functions/lines to modify
+
+**Key Characteristics**:
+- **Quantification**: All requirements/acceptance use explicit counts and enumerations
+- **Mode Flexibility**: Supports both agent execution (default) and CLI tool execution (`--cli-execute`)
+- **Context Intelligence**: References context-package.json for smart context and artifact paths
+- **Artifact Integration**: Dynamically loads role analyses and brainstorm artifacts
+
+**Example Task JSON**:
 ```json
 {
-  "id": "IMPL-N[.M]",
-  "title": "Descriptive task name",
-  "status": "pending|active|completed|blocked|container",
-  "context_package_path": ".workflow/WFS-[session]/.process/context-package.json",
+  "id": "IMPL-1",
+  "title": "Implement feature X with Y components",
+  "status": "pending",
+  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
   "meta": {
-    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@universal-executor",
-    "execution_group": "group-id|null",
-    "context_signature": "hash-of-focus_paths-and-artifacts"
+    "type": "feature",
+    "agent": "@code-developer",
+    "execution_group": "parallel-abc123",
+    "context_signature": "hash-value"
   },
   "context": {
-    "requirements": ["Clear requirement from analysis"],
-    "focus_paths": ["D:\\project\\src\\module\\path", "./tests/module/path"],
-    "acceptance": ["Measurable acceptance criterion"],
-    "parent": "IMPL-N",
-    "depends_on": ["IMPL-N.M"],
-    "inherited": {"shared_patterns": [], "common_dependencies": []},
-    "shared_context": {"tech_stack": [], "conventions": []},
+    "requirements": [
+      "Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]",
+      "Create 3 directories: [dir1/, dir2/, dir3/]",
+      "Modify 2 functions: [funcA() in file1.ts lines 10-25, funcB() in file2.ts lines 40-60]"
+    ],
+    "focus_paths": ["D:\\project\\src\\module", "./tests/module"],
+    "acceptance": [
+      "5 command files created: verify by ls .claude/commands/*/*.md | wc -l = 5",
+      "3 directories exist: verify by ls -d dir*/ | wc -l = 3",
+      "All tests pass: pytest tests/ --cov=src/module (>=80% coverage)"
+    ],
+    "depends_on": [],
     "artifacts": [
       {
-        "path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
+        "path": ".workflow/WFS-session/.brainstorming/system-architect/analysis.md",
         "priority": "highest",
-        "usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
-      },
-      {
-        "path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
-        "priority": "high",
-        "usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place"
+        "usage": "Architecture decisions and API specifications"
       }
     ]
   },
@@ -206,18 +301,14 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
     "pre_analysis": [
       {
         "step": "load_context_package",
-        "action": "Load context package for artifact paths",
-        "note": "Context package path is now at top-level field: context_package_path",
-        "commands": [
-          "Read({{context_package_path}})"
-        ],
+        "action": "Load context package for artifact paths and smart context",
+        "commands": ["Read({{context_package_path}})"],
         "output_to": "context_package",
         "on_error": "fail"
       },
       {
         "step": "load_role_analysis_artifacts",
-        "action": "Load role analyses from context-package.json (supports multiple files per role)",
-        "note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
+        "action": "Load role analyses from context-package.json",
         "commands": [
           "Read({{context_package_path}})",
           "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
@@ -225,73 +316,36 @@ This enhanced 5-field schema embeds all necessary context, artifacts, and execut
         ],
         "output_to": "role_analysis_artifacts",
         "on_error": "skip_optional"
-      },
-      {
-        "step": "load_planning_context",
-        "action": "Load plan-generated context intelligence with resolved conflicts",
-        "note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.",
-        "commands": [
-          "Read({{context_package_path}})",
-          "Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)"
-        ],
-        "output_to": "planning_context",
-        "on_error": "fail",
-        "usage_guidance": {
-          "context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)",
-          "guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)"
-        }
-      },
-      {
-        "step": "codebase_exploration",
-        "action": "Explore codebase using native tools",
-        "command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")",
-        "output_to": "codebase_structure"
-      },
-      {
-        "step": "analyze_task_patterns",
-        "action": "Analyze existing code patterns and identify modification targets",
-        "commands": [
-          "bash(cd \"[focus_paths]\")",
-          "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
-        ],
-        "output_to": "task_context_with_targets",
-        "on_error": "fail"
       }
     ],
     "implementation_approach": [
       {
         "step": 1,
-        "title": "Implement task following role analyses and context",
-        "description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.",
+        "title": "Implement feature following role analyses",
+        "description": "Implement feature X using requirements from role analyses and context package",
         "modification_points": [
-          "Apply requirements and design specs from role analysis documents",
-          "Use enhancements and clarifications from synthesis phase",
-          "Use finalized decisions from guidance-specification.md (includes resolved conflicts)",
-          "Use context-package.json for focus paths and dependency resolution",
-          "Consult specific role artifacts for implementation details when needed",
-          "Integrate with existing patterns"
+          "Create 5 command files: [cmd1.md, cmd2.md, cmd3.md, cmd4.md, cmd5.md]",
+          "Modify funcA() in file1.ts lines 10-25: add validation logic",
+          "Modify funcB() in file2.ts lines 40-60: integrate with new API"
         ],
         "logic_flow": [
-          "Load role analyses (requirements, design, enhancements from synthesis)",
-          "Load guidance-specification.md (finalized decisions with resolved conflicts if any)",
-          "Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)",
-          "Extract requirements and design decisions from role documents",
-          "Review synthesis enhancements and clarifications",
-          "Use finalized decisions (conflicts already resolved if applicable)",
-          "Identify modification targets using context package",
-          "Implement following role requirements and design specs",
-          "Consult role artifacts for detailed specifications when needed",
+          "Load role analyses and context package",
+          "Extract requirements and design decisions",
+          "Implement commands following existing patterns",
+          "Update functions with new logic",
           "Validate against acceptance criteria"
         ],
         "depends_on": [],
         "output": "implementation"
       }
     ],
-    "target_files": ["file:function:lines"]
+    "target_files": ["file1.ts:funcA:10-25", "file2.ts:funcB:40-60"]
   }
 }
 ```
 
+**Note**: In CLI Execute Mode (`--cli-execute`), `implementation_approach` steps include a `command` field with the CLI tool invocation (e.g., `bash(codex ...)`).
+
 ### 6.2. IMPL_PLAN.md Structure
 This document provides a high-level overview of the entire implementation plan.
 
@@ -585,194 +639,7 @@ Artifacts are mapped to tasks based on their relevance to the task's domain.
 
 This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
 
-## 8. CLI Execute Mode Details
-When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
-
-**Key Points**:
-- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
-    - **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **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_package_path": ".workflow/WFS-session/.process/context-package.json",
-  "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_role_analyses",
-        "action": "Load role analyses from context-package.json",
-        "commands": [
-          "Read({{context_package_path}})",
-          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
-          "Read(each extracted path)"
-        ],
-        "output_to": "role_analyses",
-        "on_error": "fail"
-      },
-      {
-        "step": "load_context",
-        "action": "Load context package for project structure",
-        "commands": ["Read({{context_package_path}})"],
-        "output_to": "context_pkg",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement JWT-based authentication",
-        "description": "Create authentication module using JWT following [role_analyses] 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_package_path": ".workflow/WFS-session/.process/context-package.json",
-  "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_role_analyses",
-        "action": "Load role analyses from context-package.json",
-        "commands": [
-          "Read({{context_package_path}})",
-          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
-          "Read(each extracted path)"
-        ],
-        "output_to": "role_analyses",
-        "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: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --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_package_path": ".workflow/WFS-session/.process/context-package.json",
-  "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 role analyses from context-package.json",
-        "commands": [
-          "Read({{context_package_path}})",
-          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
-          "Read(each extracted path)"
-        ],
-        "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: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Define role model", "Define permission model", "Create migrations"],
-        "logic_flow": ["Design schema", "Implement models", "Generate migrations"],
-        "depends_on": [],
-        "output": "rbac_models"
-      },
-      {
-        "step": 2,
-        "title": "Implement RBAC middleware",
-        "description": "Create route protection middleware using models from step 1",
-        "command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
-        "logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
-        "depends_on": [1],
-        "output": "rbac_middleware"
-      },
-      {
-        "step": 3,
-        "title": "Add role management API",
-        "description": "Create CRUD endpoints for roles and permissions",
-        "command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
-        "modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
-        "logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
-        "depends_on": [2],
-        "output": "role_management_api"
-      }
-    ],
-    "target_files": [
-      "src/models/Role.ts",
-      "src/models/Permission.ts",
-      "src/middleware/rbac.ts",
-      "src/routes/roles.ts"
-    ]
-  }
-}
-```
-
-**Pattern Summary**:
-- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
-- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
-- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
-- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
-
-## 9. Error Handling
+## 8. Error Handling
 
 ### Input Validation Errors
 | Error | Cause | Resolution |
@@ -795,21 +662,19 @@ When using `--cli-execute`, each step in `implementation_approach` includes a `c
 | Invalid format | Corrupted file | Skip artifact loading |
 | Path invalid | Moved/deleted | Update references |
 
-## 10. Integration & Usage
+## 10. Usage & Related Commands
 
-### Command Chain
-- **Called By**: `/workflow:plan` (Phase 4)
-- **Calls**: None (terminal command)
-- **Followed By**: `/workflow:execute`, `/workflow:status`
-
-### Basic Usage
+**Basic Usage**:
 ```bash
-/workflow:tools:task-generate --session WFS-auth
+/workflow:tools:task-generate --session WFS-auth [--cli-execute]
 ```
 
-## 11. Related Commands
-- `/workflow:plan` - Orchestrates entire planning
-- `/workflow:plan --cli-execute` - Planning with CLI execution mode
-- `/workflow:tools:context-gather` - Provides context package
-- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional)
+**Workflow Integration**:
+- Called by: `/workflow:plan` (task generation phase)
+- Followed by: `/workflow:execute`, `/workflow:status`
+
+**Related Commands**:
+- `/workflow:plan` - Orchestrates entire planning workflow
+- `/workflow:tools:context-gather` - Provides context package input
+- `/workflow:tools:conflict-resolution` - Provides conflict resolution (if needed)
 - `/workflow:execute` - Executes generated tasks

.claude/skills/command-guide/reference/commands/workflow/tools/tdd-coverage-analysis.md

@@ -275,7 +275,3 @@ Overall Compliance: 93/100
 Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
 ```
 
-## Related Commands
-- `/workflow:tdd-verify` - Uses this tool for verification
-- `/workflow:tools:task-generate-tdd` - Generates tasks this tool analyzes
-- `/workflow:execute` - Executes tasks before analysis

.claude/skills/command-guide/reference/commands/workflow/tools/test-concept-enhanced.md

@@ -460,8 +460,3 @@ Synthesize Gemini analysis into standardized format:
 - ✅ Execution time < 20 minutes
 - ✅ Output follows existing test conventions
 
-## Related Commands
-
-- `/workflow:tools:test-context-gather` - Provides input context
-- `/workflow:tools:test-task-generate` - Consumes analysis results
-- `/workflow:test-gen` - Main test generation workflow

.claude/skills/command-guide/reference/commands/workflow/tools/test-context-gather.md

@@ -203,8 +203,3 @@ Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-pac
 - **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
 - **Coverage focus**: Primary goal is identifying implementation files without tests
 
-## Related Commands
-
-- `/workflow:test-gen` - Main test generation workflow
-- `/workflow:tools:test-concept-enhanced` - Test generation analysis
-- `/workflow:tools:test-task-generate` - Test task JSON generation

.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md

@@ -1,6 +1,6 @@
 ---
 name: test-task-generate
-description: Generate test-fix task JSON with iterative test-fix-retest cycle specification using Gemini/Qwen/Codex
+description: Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase
 argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
 examples:
   - /workflow:tools:test-task-generate --session WFS-test-auth
@@ -9,10 +9,23 @@ examples:
   - /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ---
 
-# Test Task Generation Command
+# Autonomous Test Task Generation Command
 
 ## Overview
-Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle specification, including Gemini diagnosis (using bug-fix template) and manual fix workflow (Codex automation only when explicitly requested).
+Autonomous test-fix task JSON generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes. Generates specialized test-fix tasks with comprehensive test-fix-retest cycle specification.
+
+## 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 test research
+- **Pre-Selected Templates**: Command selects correct test template based on `--cli-execute` flag **before** invoking agent
+- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root
+- **Test-First**: Generate comprehensive test coverage before execution
+- **Iterative Refinement**: Test-fix-retest cycle until all tests pass
+- **Surgical Fixes**: Minimal code changes, no refactoring during test fixes
+- **Auto-Revert**: Rollback all changes if max iterations reached
 
 ## Execution Modes
 
@@ -24,583 +37,278 @@ Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle
 - **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
 - **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
 
-## Core Philosophy
-- **Analysis-Driven Test Generation**: Use TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
-- **Agent-Based Test Creation**: Call @code-developer agent for comprehensive test generation
-- **Coverage-First**: Generate all missing tests before execution
-- **Test Execution**: Execute complete test suite after generation
-- **Gemini Diagnosis**: Use Gemini for root cause analysis and fix suggestions (references bug-fix template)
-- **Manual Fixes First**: Apply fixes manually by default, codex only when explicitly needed
-- **Iterative Refinement**: Repeat test-analyze-fix-retest cycle until all tests pass
-- **Surgical Fixes**: Minimal code changes, no refactoring during test fixes
-- **Auto-Revert**: Rollback all changes if max iterations reached
-
-## Core Responsibilities
-- Parse TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
-- Extract test requirements and generation strategy
-- Parse `--use-codex` flag to determine fix mode (manual vs automated)
-- Generate test generation subtask calling @code-developer
-- Generate test execution and fix cycle task JSON with appropriate fix mode
-- Configure Gemini diagnosis workflow (bug-fix template) and manual/Codex fix application
-- Create test-oriented IMPL_PLAN.md and TODO_LIST.md with test generation phase
-
 ## Execution Lifecycle
 
-### Phase 1: Input Validation & Discovery
+### Phase 1: Discovery & Context Loading
+**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
 
-1. **Parameter Parsing**
-   - Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
-   - Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
-   - Store flag values for task JSON generation
-
-2. **Test Session Validation**
-   - Load `.workflow/{test-session-id}/workflow-session.json`
-   - Verify `workflow_type: "test_session"`
-   - Extract `source_session_id` from metadata
-
-3. **Test Analysis Results Loading**
-   - **REQUIRED**: Load `.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md`
-   - Parse test requirements by file
-   - Extract test generation strategy
-   - Identify test files to create with specifications
-
-4. **Test Context Package Loading**
-   - Load `.workflow/{test-session-id}/.process/test-context-package.json`
-   - Extract test framework configuration
-   - Extract coverage gaps and priorities
-   - Load source session implementation summaries
-
-### Phase 2: Task JSON Generation
-
-Generate **TWO task JSON files**:
-1. **IMPL-001.json** - Test Generation (calls @code-developer)
-2. **IMPL-002.json** - Test Execution and Fix Cycle (calls @test-fix-agent)
-
-#### IMPL-001.json - Test Generation Task
-
-```json
+**Agent Context Package**:
+```javascript
 {
-  "id": "IMPL-001",
-  "title": "Generate comprehensive tests for [sourceSessionId]",
-  "status": "pending",
-  "meta": {
-    "type": "test-gen",
-    "agent": "@code-developer",
-    "source_session": "[sourceSessionId]",
-    "test_framework": "jest|pytest|cargo|detected"
+  "session_id": "WFS-test-[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
+  "workflow_type": "test_session",
+  "use_codex": true | false,  // Determined by --use-codex flag
+  "session_metadata": {
+    // If in memory: use cached content
+    // Else: Load from .workflow/{test-session-id}/workflow-session.json
   },
-  "context": {
-    "requirements": [
-      "Generate comprehensive test files based on TEST_ANALYSIS_RESULTS.md",
-      "Follow existing test patterns and conventions from test framework",
-      "Create tests for all missing coverage identified in analysis",
-      "Include happy path, error handling, edge cases, and integration tests",
-      "Use test data and mocks as specified in analysis",
-      "Ensure tests follow project coding standards"
-    ],
-    "focus_paths": [
-      "tests/**/*",
-      "src/**/*.test.*",
-      "{paths_from_analysis}"
-    ],
-    "acceptance": [
-      "All test files from TEST_ANALYSIS_RESULTS.md section 5 are created",
-      "Tests follow existing test patterns and conventions",
-      "Test scenarios cover happy path, errors, edge cases, integration",
-      "All dependencies are properly mocked",
-      "Test files are syntactically valid and can be executed",
-      "Test coverage meets analysis requirements"
-    ],
-    "depends_on": [],
-    "source_context": {
-      "session_id": "[sourceSessionId]",
-      "test_analysis": ".workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md",
-      "test_context": ".workflow/[testSessionId]/.process/test-context-package.json",
-      "implementation_summaries": [
-        ".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
-      ]
-    }
+  "test_analysis_results_path": ".workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md",
+  "test_analysis_results": {
+    // If in memory: use cached content
+    // Else: Load from TEST_ANALYSIS_RESULTS.md
   },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_test_analysis",
-        "action": "Load test generation requirements and strategy",
-        "commands": [
-          "Read(.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md)",
-          "Read(.workflow/[testSessionId]/.process/test-context-package.json)"
-        ],
-        "output_to": "test_generation_requirements",
-        "on_error": "fail"
-      },
-      {
-        "step": "load_implementation_context",
-        "action": "Load source implementation for test generation context",
-        "commands": [
-          "bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
-        ],
-        "output_to": "implementation_context",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "load_existing_test_patterns",
-        "action": "Study existing tests for pattern reference",
-        "commands": [
-          "bash(find . -name \"*.test.*\" -type f)",
-          "bash(# Read first 2 existing test files as examples)",
-          "bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
-          "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
-        ],
-        "output_to": "existing_test_patterns",
-        "on_error": "skip_optional"
-      }
-    ],
-    // Agent Mode (Default): Agent implements tests
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate comprehensive test suite",
-        "description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
-        "modification_points": [
-          "Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
-          "Study existing test patterns",
-          "Create test files with all required scenarios",
-          "Implement happy path, error handling, edge case, and integration tests",
-          "Add required mocks and fixtures"
-        ],
-        "logic_flow": [
-          "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
-          "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
-          "Study existing test patterns from test_context.test_framework.conventions",
-          "For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
-          "Follow test framework conventions and project standards",
-          "Ensure all tests are executable and syntactically valid"
-        ],
-        "depends_on": [],
-        "output": "test_suite"
-      }
-    ],
-
-    // CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
-    "implementation_approach": [{
-      "step": 1,
-      "title": "Generate tests using Codex",
-      "description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
-      "modification_points": [
-        "Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
-        "Codex generates all test files listed in analysis section 5",
-        "Codex ensures tests follow framework conventions"
-      ],
-      "logic_flow": [
-        "Start new Codex session",
-        "Pass TEST_ANALYSIS_RESULTS.md to Codex",
-        "Codex studies existing test patterns",
-        "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)",
-      "depends_on": [],
-      "output": "test_generation"
-    }],
-    "target_files": [
-      "{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
-      "{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
-      "{test_file_N from TEST_ANALYSIS_RESULTS.md section 5}"
-    ]
+  "test_context_package_path": ".workflow/{test-session-id}/.process/test-context-package.json",
+  "test_context_package": {
+    // Existing test patterns and coverage analysis
+  },
+  "source_session_id": "[source-session-id]",  // if exists
+  "source_session_summaries": {
+    // Implementation context from source session
+  },
+  "mcp_capabilities": {
+    "code_index": true,
+    "exa_code": true,
+    "exa_web": true
   }
 }
 ```
 
-#### IMPL-002.json - Test Execution & Fix Cycle Task
+**Discovery Actions**:
+1. **Load Test Session Context** (if not in memory)
+   ```javascript
+   if (!memory.has("workflow-session.json")) {
+     Read(.workflow/{test-session-id}/workflow-session.json)
+   }
+   ```
 
-```json
-{
-  "id": "IMPL-002",
-  "title": "Execute and fix tests for [sourceSessionId]",
-  "status": "pending",
-  "meta": {
-    "type": "test-fix",
-    "agent": "@test-fix-agent",
-    "source_session": "[sourceSessionId]",
-    "test_framework": "jest|pytest|cargo|detected",
-    "max_iterations": 5,
-    "use_codex": false  // Set to true if --use-codex flag present
-  },
-  "context": {
-    "requirements": [
-      "Execute complete test suite (generated in IMPL-001)",
-      "Diagnose test failures using Gemini analysis with bug-fix template",
-      "Present fixes to user for manual application (default)",
-      "Use Codex ONLY if user explicitly requests automation",
-      "Iterate until all tests pass or max iterations reached",
-      "Revert changes if unable to fix within iteration limit"
-    ],
-    "focus_paths": [
-      "tests/**/*",
-      "src/**/*.test.*",
-      "{implementation_files_from_source_session}"
-    ],
-    "acceptance": [
-      "All tests pass successfully (100% pass rate)",
-      "No test failures or errors in final run",
-      "Code changes are minimal and surgical",
-      "All fixes are verified through retest",
-      "Iteration logs document fix progression"
-    ],
-    "depends_on": ["IMPL-001"],
-    "source_context": {
-      "session_id": "[sourceSessionId]",
-      "test_generation_summary": ".workflow/[testSessionId]/.summaries/IMPL-001-summary.md",
-      "implementation_summaries": [
-        ".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
-      ]
-    }
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_source_session_summaries",
-        "action": "Load implementation context from source session",
-        "commands": [
-          "bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
-          "bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
-        ],
-        "output_to": "implementation_context",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "discover_test_framework",
-        "action": "Identify test framework and test command",
-        "commands": [
-          "bash(jq -r '.scripts.test // \"npm test\"' package.json 2>/dev/null || echo 'pytest' || echo 'cargo test')",
-          "bash([ -f 'package.json' ] && echo 'jest/npm' || [ -f 'pytest.ini' ] && echo 'pytest' || [ -f 'Cargo.toml' ] && echo 'cargo' || echo 'unknown')"
-        ],
-        "output_to": "test_command",
-        "on_error": "fail"
-      },
-      {
-        "step": "analyze_test_coverage",
-        "action": "Analyze test coverage and identify missing tests",
-        "commands": [
-          "bash(find . -name \"*.test.*\" -type f)",
-          "bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
-          "bash(# Count implementation files vs test files)",
-          "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
-          "bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))",
-          "bash(echo \"Implementation files: $impl_count, Test files: $test_count\")"
-        ],
-        "output_to": "test_coverage_analysis",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "identify_files_without_tests",
-        "action": "List implementation files that lack corresponding test files",
-        "commands": [
-          "bash(# For each changed file from source session, check if test exists)",
-          "bash(for file in [changed_files]; do test_file=$(echo $file | sed 's/\\(.*\\)\\.\\(ts\\|js\\|py\\)$/\\1.test.\\2/'); [ ! -f \"$test_file\" ] && echo \"$file\"; done)"
-        ],
-        "output_to": "files_without_tests",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "prepare_test_environment",
-        "action": "Ensure test environment is ready",
-        "commands": [
-          "bash([ -f 'package.json' ] && npm install 2>/dev/null || true)",
-          "bash([ -f 'requirements.txt' ] && pip install -q -r requirements.txt 2>/dev/null || true)"
-        ],
-        "output_to": "environment_status",
-        "on_error": "skip_optional"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Execute iterative test-fix-retest cycle",
-        "description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
-        "test_fix_cycle": {
-          "max_iterations": 5,
-          "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
-          "tools": {
-            "test_execution": "bash(test_command)",
-            "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"
-          },
-          "exit_conditions": {
-            "success": "all_tests_pass",
-            "failure": "max_iterations_reached",
-            "error": "test_command_not_found"
-          }
-        },
-        "modification_points": [
-        "PHASE 1: Initial Test Execution",
-        "  1.1. Discover test command from framework detection",
-        "  1.2. Execute initial test run: bash([test_command])",
-        "  1.3. Parse test output and count failures",
-        "  1.4. If all pass → Skip to PHASE 3 (success)",
-        "  1.5. If failures → Store failure output, proceed to PHASE 2",
-        "",
-        "PHASE 2: Iterative Test-Fix-Retest Cycle (max 5 iterations)",
-        "  Note: This phase handles test failures, NOT test generation failures",
-        "  Initialize: max_iterations=5, current_iteration=0",
-        "  ",
-        "  WHILE (tests failing AND current_iteration < max_iterations):",
-        "    current_iteration++",
-        "    ",
-        "    STEP 2.1: Gemini Diagnosis (using bug-fix template)",
-        "    - Prepare diagnosis context:",
-        "      * Test failure output from previous run",
-        "      * Source files from focus_paths",
-        "      * Implementation summaries from source session",
-        "    - Execute Gemini analysis with bug-fix template:",
-        "      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",
-        "               Test output: [test_failures]",
-        "               Source files: [focus_paths]",
-        "               Implementation: [implementation_context]",
-        "      EXPECTED: Root cause analysis, code path tracing, targeted fixes",
-        "      RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Bug: [test_failure_description]",
-        "             Minimal surgical fixes only - no refactoring",
-        "      \" > fix-iteration-[N]-diagnosis.md)",
-        "    - Parse diagnosis → extract fix_suggestion and target_files",
-        "    - Present fix to user for manual application (default)",
-        "    ",
-        "    STEP 2.2: Apply Fix (Based on meta.use_codex Flag)",
-        "    ",
-        "    IF meta.use_codex = false (DEFAULT):",
-        "    - Present Gemini diagnosis to user for manual fix",
-        "    - User applies fix based on diagnosis recommendations",
-        "    - Stage changes: bash(git add -A)",
-        "    - Store fix log: .process/fix-iteration-[N]-changes.log",
-        "    ",
-        "    IF meta.use_codex = true (--use-codex flag present):",
-        "    - Stage current changes (if valid git repo): bash(git add -A)",
-        "    - First iteration: Start new Codex session",
-        "      codex -C [project_root] --full-auto exec \"",
-        "      PURPOSE: Fix test failure iteration 1",
-        "      TASK: [fix_suggestion from Gemini]",
-        "      MODE: write",
-        "      CONTEXT: Diagnosis: .workflow/.process/fix-iteration-1-diagnosis.md",
-        "               Target files: [target_files]",
-        "               Implementation context: [implementation_context]",
-        "      EXPECTED: Minimal code changes to resolve test failure",
-        "      RULES: Apply ONLY suggested changes, no refactoring",
-        "             Preserve existing code style",
-        "      \" --skip-git-repo-check -s danger-full-access",
-        "    - Subsequent iterations: Resume session for context continuity",
-        "      codex exec \"",
-        "      CONTINUE TO NEXT FIX:",
-        "      Iteration [N] of 5: Fix test failure",
-        "      ",
-        "      PURPOSE: Fix remaining test failures",
-        "      TASK: [fix_suggestion from Gemini iteration N]",
-        "      CONTEXT: Previous fixes applied, diagnosis: .process/fix-iteration-[N]-diagnosis.md",
-        "      EXPECTED: Surgical fix for current failure",
-        "      RULES: Build on previous fixes, maintain consistency",
-        "      \" resume --last --skip-git-repo-check -s danger-full-access",
-        "    - Store fix log: .process/fix-iteration-[N]-changes.log",
-        "    ",
-        "    STEP 2.3: Retest and Verification",
-        "    - Re-execute test suite: bash([test_command])",
-        "    - Capture output: .process/fix-iteration-[N]-retest.log",
-        "    - Count failures: bash(grep -c 'FAIL\\|ERROR' .process/fix-iteration-[N]-retest.log)",
-        "    - Check for regression:",
-        "      IF new_failures > previous_failures:",
-        "        WARN: Regression detected",
-        "        Include in next Gemini diagnosis context",
-        "    - Analyze results:",
-        "      IF all_tests_pass:",
-        "        BREAK loop → Proceed to PHASE 3",
-        "      ELSE:",
-        "        Update test_failures context",
-        "        CONTINUE loop",
-        "  ",
-        "  IF max_iterations reached AND tests still failing:",
-        "    EXECUTE: git reset --hard HEAD (revert all changes)",
-        "    MARK: Task status = blocked",
-        "    GENERATE: Detailed failure report with iteration logs",
-        "    EXIT: Require manual intervention",
-        "",
-        "PHASE 3: Final Validation and Certification",
-        "  3.1. Execute final confirmation test run",
-        "  3.2. Generate success summary:",
-        "       - Iterations required: [current_iteration]",
-        "       - Fixes applied: [summary from iteration logs]",
-        "       - Test results: All passing ✅",
-        "  3.3. Mark task status: completed",
-        "  3.4. Update TODO_LIST.md: Mark as ✅",
-        "  3.5. Certify code: APPROVED for deployment"
-      ],
-      "logic_flow": [
-        "Load source session implementation context",
-        "Discover test framework and command",
-        "PHASE 0: Test Coverage Check",
-        "  Analyze existing test files",
-        "  Identify files without tests",
-        "  IF tests missing:",
-        "    Report to user (no automatic generation)",
-        "    Wait for user to generate tests or request automation",
-        "  ELSE:",
-        "    Skip to Phase 1",
-        "PHASE 1: Initial Test Execution",
-        "  Execute test suite",
-        "  IF all pass → Success (Phase 3)",
-        "  ELSE → Store failures, proceed to Phase 2",
-        "PHASE 2: Iterative Fix Cycle (max 5 iterations)",
-        "  LOOP (max 5 times):",
-        "    1. Gemini diagnoses failure with bug-fix template → fix suggestion",
-        "    2. Check meta.use_codex flag:",
-        "       - IF false (default): Present fix to user for manual application",
-        "       - IF true (--use-codex): Codex applies fix with resume for continuity",
-        "    3. Retest and check results",
-        "    4. IF pass → Exit loop to Phase 3",
-        "    5. ELSE → Continue with updated context",
-        "  IF max iterations → Revert + report failure",
-        "PHASE 3: Final Validation",
-        "  Confirm all tests pass",
-        "  Generate summary (include test generation info)",
-        "  Certify code APPROVED"
-      ],
-        "error_handling": {
-          "max_iterations_reached": {
-            "action": "revert_all_changes",
-            "commands": [
-              "bash(git reset --hard HEAD)",
-              "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
-            ],
-            "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
-          },
-          "test_command_fails": {
-            "action": "treat_as_test_failure",
-            "context": "Use stderr as failure context for Gemini diagnosis"
-          },
-          "codex_apply_fails": {
-            "action": "retry_once_then_skip",
-            "fallback": "Mark iteration as skipped, continue to next"
-          },
-          "gemini_diagnosis_fails": {
-            "action": "retry_with_simplified_context",
-            "fallback": "Use previous diagnosis, continue"
-          },
-          "regression_detected": {
-            "action": "log_warning_continue",
-            "context": "Include regression info in next Gemini diagnosis"
-          }
-        },
-        "depends_on": [],
-        "output": "test_fix_results"
-      }
-    ],
-    "target_files": [
-      "Auto-discovered from test failures",
-      "Extracted from Gemini diagnosis each iteration",
-      "Format: file:function:lines or file (for new files)"
-    ],
-    "codex_session": {
-      "strategy": "resume_for_continuity",
-      "first_iteration": "codex exec \"fix iteration 1\" --full-auto",
-      "subsequent_iterations": "codex exec \"fix iteration N\" resume --last",
-      "benefits": [
-        "Maintains conversation context across fixes",
-        "Remembers previous decisions and patterns",
-        "Ensures consistency in fix approach",
-        "Reduces redundant context injection"
-      ]
-    }
-  }
+2. **Load TEST_ANALYSIS_RESULTS.md** (if not in memory, REQUIRED)
+   ```javascript
+   if (!memory.has("TEST_ANALYSIS_RESULTS.md")) {
+     Read(.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md)
+   }
+   ```
+
+3. **Load Test Context Package** (if not in memory)
+   ```javascript
+   if (!memory.has("test-context-package.json")) {
+     Read(.workflow/{test-session-id}/.process/test-context-package.json)
+   }
+   ```
+
+4. **Load Source Session Summaries** (if source_session_id exists)
+   ```javascript
+   if (sessionMetadata.source_session_id) {
+     const summaryFiles = Bash("find .workflow/{source-session-id}/.summaries/ -name 'IMPL-*-summary.md'")
+     summaryFiles.forEach(file => Read(file))
+   }
+   ```
+
+5. **Code Analysis with Native Tools** (optional - enhance understanding)
+   ```bash
+   # Find test files and patterns
+   find . -name "*test*" -type f
+   rg "describe|it\(|test\(" -g "*.ts"
+   ```
+
+6. **MCP External Research** (optional - gather test best practices)
+   ```javascript
+   // Get external test examples and patterns
+   mcp__exa__get_code_context_exa(
+     query="TypeScript test generation best practices jest",
+     tokensNum="dynamic"
+   )
+   ```
+
+### 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(
+  subagent_type="action-planning-agent",
+  description="Generate test-fix task JSON and implementation plan",
+  prompt=`
+## Execution Context
+
+**Session ID**: WFS-test-{session-id}
+**Workflow Type**: Test Session
+**Execution Mode**: {agent-mode | cli-execute-mode}
+**Task JSON Template Path**: {template_path}
+**Use Codex**: {true | false}
+
+## Phase 1: Discovery Results (Provided Context)
+
+### Test Session Metadata
+{session_metadata_content}
+- source_session_id: {source_session_id} (if exists)
+- workflow_type: "test_session"
+
+### TEST_ANALYSIS_RESULTS.md (REQUIRED)
+{test_analysis_results_content}
+- Coverage Assessment
+- Test Framework & Conventions
+- Test Requirements by File
+- Test Generation Strategy
+- Implementation Targets
+- Success Criteria
+
+### Test Context Package
+{test_context_package_summary}
+- Existing test patterns, framework config, coverage analysis
+
+### Source Session Implementation Context (Optional)
+{source_session_summaries}
+- Implementation context from completed session
+
+### MCP Analysis Results (Optional)
+**Code Structure**: {mcp_code_index_results}
+**External Research**: {mcp_exa_research_results}
+
+## Phase 2: Test Task Document Generation
+
+**Agent Configuration Reference**: All test task generation rules, test-fix cycle structure, quality standards, and execution details are defined in action-planning-agent.
+
+Refer to: @.claude/agents/action-planning-agent.md for:
+- Test Task Decomposition Standards
+- Test-Fix-Retest Cycle Requirements
+- 5-Field Task JSON Schema
+- IMPL_PLAN.md Structure (Test variant)
+- TODO_LIST.md Format
+- Test Execution Flow & Quality Validation
+
+### Test-Specific Requirements Summary
+
+#### Task Structure Philosophy
+- **Minimum 2 tasks**: IMPL-001 (test generation) + IMPL-002 (test execution & fix)
+- **Expandable**: Add IMPL-003+ for complex projects (per-module, integration, etc.)
+- IMPL-001: Uses @code-developer or CLI execution
+- IMPL-002: Uses @test-fix-agent with iterative fix cycle
+
+#### Test-Fix Cycle Configuration
+- **Max Iterations**: 5 (for IMPL-002)
+- **Diagnosis Tool**: Gemini with bug-fix template
+- **Fix Application**: Manual (default) or Codex (if --use-codex flag)
+- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
+- **Exit Conditions**: All tests pass OR max iterations reached (auto-revert)
+
+#### Required Outputs Summary
+
+##### 1. Test Task JSON Files (.task/IMPL-*.json)
+- **Location**: `.workflow/{test-session-id}/.task/`
+- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
+- **Schema**: 5-field structure with test-specific metadata
+  - IMPL-001: `meta.type: "test-gen"`, `meta.agent: "@code-developer"`
+  - IMPL-002: `meta.type: "test-fix"`, `meta.agent: "@test-fix-agent"`, `meta.use_codex: {use_codex}`
+  - `flow_control`: Test generation approach (IMPL-001) or test-fix cycle (IMPL-002)
+- **Details**: See action-planning-agent.md § Test Task JSON Generation
+
+##### 2. IMPL_PLAN.md (Test Variant)
+- **Location**: `.workflow/{test-session-id}/IMPL_PLAN.md`
+- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
+- **Test-Specific Frontmatter**: workflow_type="test_session", test_framework, source_session_id
+- **Test-Fix-Retest Cycle Section**: Iterative fix cycle with Gemini diagnosis
+- **Details**: See action-planning-agent.md § Test Implementation Plan Creation
+
+##### 3. TODO_LIST.md
+- **Location**: `.workflow/{test-session-id}/TODO_LIST.md`
+- **Format**: Task list with test generation and execution phases
+- **Status**: [ ] (pending), [x] (completed)
+- **Details**: See action-planning-agent.md § TODO List Generation
+
+### Agent Execution Summary
+
+**Key Steps** (Detailed instructions in action-planning-agent.md):
+1. Load task JSON template from provided path
+2. Parse TEST_ANALYSIS_RESULTS.md for test requirements
+3. Generate IMPL-001 (test generation) task JSON
+4. Generate IMPL-002 (test execution & fix) task JSON with use_codex flag
+5. Generate additional IMPL-*.json if project complexity requires
+6. Create IMPL_PLAN.md using test template variant
+7. Generate TODO_LIST.md with test task indicators
+8. Update session state with test metadata
+
+**Quality Gates** (Full checklist in action-planning-agent.md):
+- ✓ Minimum 2 tasks created (IMPL-001 + IMPL-002)
+- ✓ IMPL-001 has test generation approach from TEST_ANALYSIS_RESULTS.md
+- ✓ IMPL-002 has test-fix cycle with correct use_codex flag
+- ✓ Test framework configuration integrated
+- ✓ Source session context referenced (if exists)
+- ✓ MCP tool integration added
+- ✓ Documents follow test template structure
+
+## Output
+
+Generate all three documents and report completion status:
+- Test task JSON files created: N files (minimum 2)
+- Test requirements integrated: TEST_ANALYSIS_RESULTS.md
+- Test context integrated: existing patterns and coverage
+- Source session context: {source_session_id} summaries (if exists)
+- MCP enhancements: code-index, exa-research
+- Session ready for test execution: /workflow:execute or /workflow:test-cycle-execute
+`
+)
+```
+
+### Agent Context Passing
+
+**Memory-Aware Context Assembly**:
+```javascript
+// Assemble context package for agent
+const agentContext = {
+  session_id: "WFS-test-[id]",
+  workflow_type: "test_session",
+  use_codex: hasUseCodexFlag,
+
+  // Use memory if available, else load
+  session_metadata: memory.has("workflow-session.json")
+    ? memory.get("workflow-session.json")
+    : Read(.workflow/WFS-test-[id]/workflow-session.json),
+
+  test_analysis_results_path: ".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",
+
+  test_analysis_results: memory.has("TEST_ANALYSIS_RESULTS.md")
+    ? memory.get("TEST_ANALYSIS_RESULTS.md")
+    : Read(".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),
+
+  test_context_package_path: ".workflow/WFS-test-[id]/.process/test-context-package.json",
+
+  test_context_package: memory.has("test-context-package.json")
+    ? memory.get("test-context-package.json")
+    : Read(".workflow/WFS-test-[id]/.process/test-context-package.json"),
+
+  // Load source session summaries if exists
+  source_session_id: session_metadata.source_session_id || null,
+
+  source_session_summaries: session_metadata.source_session_id
+    ? loadSourceSummaries(session_metadata.source_session_id)
+    : null,
+
+  // Optional MCP enhancements
+  mcp_analysis: executeMcpDiscovery()
 }
 ```
 
-### Phase 3: IMPL_PLAN.md Generation
+## Test Task Structure Reference
 
-#### Document Structure
-```markdown
----
-identifier: WFS-test-[session-id]
-source_session: WFS-[source-session-id]
-workflow_type: test_session
-test_framework: jest|pytest|cargo|detected
----
+This section provides quick reference for test task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
 
-# Test Validation Plan: [Source Session Topic]
-
-## Summary
-Execute comprehensive test suite for implementation from session WFS-[source-session-id].
-Diagnose and fix all test failures using iterative Gemini analysis and Codex execution.
-
-## Source Session Context
-- **Implementation Session**: WFS-[source-session-id]
-- **Completed Tasks**: IMPL-001, IMPL-002, ...
-- **Changed Files**: [list from git log]
-- **Implementation Summaries**: [references to source session summaries]
-
-## Test Framework
-- **Detected Framework**: jest|pytest|cargo|other
-- **Test Command**: npm test|pytest|cargo test
-- **Test Files**: [discovered test files]
-- **Coverage**: [estimated test coverage]
-
-## Test-Fix-Retest Cycle
-- **Max Iterations**: 5
-- **Diagnosis Tool**: Gemini (analysis mode with bug-fix template from bug-index.md)
-- **Fix Tool**: Manual (default, meta.use_codex=false) or Codex (if --use-codex flag, meta.use_codex=true)
-- **Verification**: Bash test execution + regression check
-
-### Cycle Workflow
-1. **Initial Test**: Execute full suite, capture failures
-2. **Iterative Fix Loop** (max 5 times):
-   - Gemini diagnoses failure using bug-fix template → surgical fix suggestion
-   - Check meta.use_codex flag:
-     - If false (default): Present fix to user for manual application
-     - If true (--use-codex): Codex applies fix with resume for context continuity
-   - Retest and verify (check for regressions)
-   - Continue until all pass or max iterations reached
-3. **Final Validation**: Confirm all tests pass, certify code
-
-### Error Recovery
-- **Max iterations reached**: Revert all changes, report failure
-- **Test command fails**: Treat as test failure, diagnose with Gemini
-- **Codex fails**: Retry once, skip iteration if still failing
-- **Regression detected**: Log warning, include in next diagnosis
-
-## Task Breakdown
-- **IMPL-001**: Execute and validate tests with iterative fix cycle
-
-## Implementation Strategy
-- **Phase 1**: Initial test execution and failure capture
-- **Phase 2**: Iterative Gemini diagnosis + Codex fix + retest
-- **Phase 3**: Final validation and code certification
-
-## Success Criteria
-- All tests pass (100% pass rate)
-- No test failures or errors in final run
-- Minimal, surgical code changes
-- Iteration logs document fix progression
-- Code certified APPROVED for deployment
-```
-
-### Phase 4: TODO_LIST.md Generation
-
-```markdown
-# Tasks: Test Validation for [Source Session]
-
-## Task Progress
-- [ ] **IMPL-001**: Execute and validate tests with iterative fix cycle → [📋](./.task/IMPL-001.json)
-
-## Execution Details
-- **Source Session**: WFS-[source-session-id]
-- **Test Framework**: jest|pytest|cargo
-- **Max Iterations**: 5
-- **Tools**: Gemini diagnosis + Codex resume fixes
-
-## Status Legend
-- `- [ ]` = Pending
-- `- [x]` = Completed
-```
+**Quick Reference**:
+- Minimum 2 tasks: IMPL-001 (test-gen) + IMPL-002 (test-fix)
+- Expandable for complex projects (IMPL-003+)
+- IMPL-001: `meta.agent: "@code-developer"`, test generation approach
+- IMPL-002: `meta.agent: "@test-fix-agent"`, `meta.use_codex: {flag}`, test-fix cycle
+- See Phase 2 agent prompt for full schema and requirements
 
 ## Output Files Structure
 ```
@@ -648,29 +356,42 @@ Diagnose and fix all test failures using iterative Gemini analysis and Codex exe
 ## Integration & Usage
 
 ### Command Chain
-- **Called By**: `/workflow:test-gen` (Phase 4)
-- **Calls**: None (terminal command)
-- **Followed By**: `/workflow:execute` (user-triggered)
+- **Called By**: `/workflow:test-gen` (Phase 4), `/workflow:test-fix-gen` (Phase 4)
+- **Invokes**: `action-planning-agent` for autonomous task generation
+- **Followed By**: `/workflow:execute` or `/workflow:test-cycle-execute` (user-triggered)
 
 ### Basic Usage
 ```bash
-# Manual fix mode (default)
+# Agent mode (default, autonomous execution)
 /workflow:tools:test-task-generate --session WFS-test-auth
 
-# Automated Codex fix mode
+# With automated Codex fixes for IMPL-002
 /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+
+# CLI execution mode for IMPL-001 test generation
+/workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
+
+# Both flags combined
+/workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ```
 
-### Flag Behavior
-- **No flag**: `meta.use_codex=false`, manual fixes presented to user
-- **--use-codex**: `meta.use_codex=true`, Codex automatically applies fixes with resume mechanism
+### Execution Modes
+- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
+- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen/Codex with cli-mode task template for IMPL-001
+- **Codex fixes** (`--use-codex`): Enables automated fixes in IMPL-002 task
 
-## Related Commands
-- `/workflow:test-gen` - Creates test session and calls this tool
-- `/workflow:tools:context-gather` - Provides cross-session context
-- `/workflow:tools:concept-enhanced` - Provides test strategy analysis
-- `/workflow:execute` - Executes the generated test-fix task
-- `@test-fix-agent` - Agent that executes the iterative test-fix cycle
+### Flag Behavior
+- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode generation
+- **--use-codex**: `meta.use_codex=true` (Codex automated fixes with resume mechanism in IMPL-002)
+- **--cli-execute**: Uses CLI tool execution mode for IMPL-001 test generation
+- **Both flags**: CLI generation + automated Codex fixes
+
+### Output
+- Test task JSON files in `.task/` directory (minimum 2: IMPL-001.json + IMPL-002.json)
+- IMPL_PLAN.md with test generation and fix cycle strategy
+- TODO_LIST.md with test task indicators
+- Session state updated with test metadata
+- MCP enhancements integrated (if available)
 
 ## Agent Execution Notes
 

.claude/skills/command-guide/reference/commands/workflow/ui-design/batch-generate.md

@@ -1,480 +0,0 @@
----
-name: batch-generate
-description: Prompt-driven batch UI generation using target-style-centric parallel execution with design token application
-argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
-allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
----
-
-# Batch Generate UI Prototypes (/workflow:ui-design:batch-generate)
-
-## Overview
-Prompt-driven UI generation with intelligent target extraction and **target-style-centric batch execution**. Each agent handles all layouts for one target × style combination.
-
-**Strategy**: Prompt → Targets → Batched Generation
-- **Prompt-driven**: Describe what to build, command extracts targets
-- **Agent scope**: Each of `T × S` agents generates `L` layouts
-- **Parallel batching**: Max 6 concurrent agents for optimal throughput
-- **Component isolation**: Complete task independence
-- **Style-aware**: HTML adapts to design_attributes
-- **Self-contained CSS**: Direct token values (no var() refs)
-
-**Supports**: Pages (full layouts) and components (isolated elements)
-
-## Phase 1: Setup & Validation
-
-### Step 1: Parse Prompt & Resolve Configuration
-```bash
-# Parse required parameters
-prompt_text = --prompt
-device_type = --device-type OR "responsive"
-
-# Extract targets from prompt
-IF --targets:
-    target_list = split_and_clean(--targets)
-ELSE:
-    target_list = extract_targets_from_prompt(prompt_text)  # See helpers
-    IF NOT target_list: target_list = ["home"]  # Fallback
-
-# Detect target type
-target_type = --target-type OR detect_target_type(target_list)
-
-# Resolve base path
-IF --base-path:
-    base_path = --base-path
-ELSE IF --session:
-    bash(find .workflow/WFS-{session} -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
-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-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: Validate Design Tokens
-```bash
-# Check design tokens exist
-bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
-
-# 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**: `design_tokens_valid`, `design_space_analysis`
-
-### Step 3: Gather Layout Inspiration (Reuse or Create)
-```bash
-# Check if layout inspirations already exist from layout-extract phase
-inspiration_source = "{base_path}/.intermediates/layout-analysis/inspirations"
-
-FOR target IN target_list:
-    # 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)
-
-        # 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 (reused or created in `.intermediates/layout-analysis/inspirations/`)
-
-## Phase 2: Target-Style-Centric Batch Generation (Agent)
-
-**Executor**: `Task(ui-design-agent)` × `T × S` tasks in **batched parallel** (max 6 concurrent)
-
-### Step 1: Calculate Batch Execution Plan
-```bash
-bash(mkdir -p {base_path}/prototypes)
-
-# Build task list: T × S combinations
-MAX_PARALLEL = 6
-total_tasks = T × S
-total_batches = ceil(total_tasks / MAX_PARALLEL)
-
-# Initialize batch tracking
-TodoWrite({todos: [
-  {content: "Batch 1/{batches}: Generate 6 tasks", status: "in_progress"},
-  {content: "Batch 2/{batches}: Generate 6 tasks", status: "pending"},
-  ...
-]})
-```
-
-### Step 2: Launch Batched Agent Tasks
-For each batch (up to 6 parallel tasks):
-```javascript
-Task(ui-design-agent): `
-  [TARGET_STYLE_UI_GENERATION_FROM_PROMPT]
-  🎯 ONE component: {target} × Style-{style_id} ({philosophy_name})
-  Generate: {layout_variants} × 2 files (HTML + CSS per layout)
-
-  PROMPT CONTEXT: {target_requirements}  # Extracted from original prompt
-  TARGET: {target} | TYPE: {target_type} | STYLE: {style_id}/{style_variants}
-  BASE_PATH: {base_path}
-  DEVICE: {device_type}
-  ${design_attributes ? "DESIGN_ATTRIBUTES: " + JSON.stringify(design_attributes) : ""}
-
-  ## Reference
-  - Layout inspiration: Read("{base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt")
-  - Design tokens: Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-    Parse ALL token values including:
-    * colors, typography (with combinations), spacing, opacity
-    * border_radius, shadows, breakpoints
-    * component_styles (button, card, input variants)
-  ${design_attributes ? "- Adapt DOM to: density, visual_weight, formality, organic_vs_geometric" : ""}
-
-  ## Generation
-  For EACH layout (1 to {layout_variants}):
-
-  1. HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
-     - Complete HTML5: <!DOCTYPE>, <head>, <body>
-     - CSS ref: <link href="{target}-style-{style_id}-layout-N.css">
-     - Semantic: <header>, <nav>, <main>, <footer>
-     - A11y: ARIA labels, landmarks, responsive meta
-     - Viewport: <meta name="viewport" content="width=device-width, initial-scale=1.0">
-     - Follow user requirements from prompt
-     ${design_attributes ? `
-     - DOM adaptation:
-       * density='spacious' → flatter hierarchy
-       * density='compact' → deeper nesting
-       * visual_weight='heavy' → extra wrappers
-       * visual_weight='minimal' → direct structure` : ""}
-     - Device-specific: Optimize for {device_type}
-
-  2. CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
-     - Self-contained: Direct token VALUES (no var())
-     - Use tokens: colors, fonts, spacing, opacity, borders, shadows
-     - IF tokens.component_styles exists: Use component presets for buttons, cards, inputs
-     - IF tokens.typography.combinations exists: Use typography presets for headings and body text
-     - Device-optimized: {device_type} styles
-     ${device_type === 'responsive' ? '- Responsive: Mobile-first @media' : '- Fixed: ' + device_type}
-     ${design_attributes ? `
-     - Token selection: density → spacing, visual_weight → shadows` : ""}
-
-  ## Notes
-  - ✅ Token VALUES directly from design-tokens.json (with typography.combinations, opacity, component_styles support)
-  - ✅ Follow prompt requirements for {target}
-  - ✅ Optimize for {device_type}
-  - ❌ NO var() refs, NO external deps
-  - Layouts structurally DISTINCT
-  - Write files IMMEDIATELY (per layout)
-  - CSS filename MUST match HTML <link href>
-`
-
-# After each batch completes
-TodoWrite: Mark batch completed, next batch in_progress
-```
-
-## Phase 3: Verify & Generate Previews
-
-### Step 1: Verify Generated Files
-```bash
-# Count expected vs found
-bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
-# Expected: S × L × T × 2
-
-# Validate samples
-Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
-# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
-```
-
-**Output**: `S × L × T × 2` files verified
-
-### Step 2: Run Preview Generation Script
-```bash
-bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
-```
-
-**Script generates**:
-- `compare.html` (interactive matrix)
-- `index.html` (navigation)
-- `PREVIEW.md` (instructions)
-
-### Step 3: Verify Preview Files
-```bash
-bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
-```
-
-**Output**: 3 preview files
-
-## Completion
-
-### Todo Update
-```javascript
-TodoWrite({todos: [
-  {content: "Setup and parse prompt", status: "completed", activeForm: "Parsing prompt"},
-  {content: "Detect token sources", status: "completed", activeForm: "Loading design systems"},
-  {content: "Gather layout inspiration", status: "completed", activeForm: "Researching layouts"},
-  {content: "Batch 1/{batches}: Generate 6 tasks", status: "completed", activeForm: "Generating batch 1"},
-  ... (all batches completed)
-  {content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
-]});
-```
-
-### Output Message
-```
-✅ Prompt-driven batch UI generation complete!
-
-Prompt: {prompt_text}
-
-Configuration:
-- Style Variants: {style_variants}
-- Layout Variants: {layout_variants}
-- Target Type: {target_type}
-- Device Type: {device_type}
-- Targets: {target_list} ({T} targets)
-- Total Prototypes: {S × L × T}
-
-Batch Execution:
-- Total tasks: {T × S} (targets × styles)
-- Batches: {batches} (max 6 parallel per batch)
-- Agent scope: {L} layouts per target×style
-- Component isolation: Complete task independence
-- Device-specific: All layouts optimized for {device_type}
-
-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: Production-ready (WCAG AA compliant)
-
-Generated Files:
-{base_path}/prototypes/
-├── {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
-3. Read PREVIEW.md
-
-Next: /workflow:ui-design:update
-```
-
-## Simple Bash Commands
-
-### Path Operations
-```bash
-# Find design directory
-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-extraction/style-* -d | wc -l)
-
-# Check design tokens exist
-bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
-```
-
-### Validation Commands
-```bash
-# Count generated files
-bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
-
-# Verify preview
-bash(test -f {base_path}/prototypes/compare.html && echo "exists")
-```
-
-### File Operations
-```bash
-# 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")
-```
-
-## Output Structure
-
-```
-{base_path}/
-├── .intermediates/
-│   └── layout-analysis/
-│       └── inspirations/
-│           └── {target}-layout-ideas.txt  # Layout inspiration (reused or created)
-├── prototypes/
-│   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
-│   ├── {target}-style-{s}-layout-{l}.css
-│   ├── compare.html
-│   ├── index.html
-│   └── PREVIEW.md
-└── style-extraction/
-    └── style-{s}/
-        ├── design-tokens.json
-        └── style-guide.md
-```
-
-## Error Handling
-
-### Common Errors
-```
-ERROR: No design tokens found
-→ Run /workflow:ui-design:style-extract first
-
-ERROR: No targets extracted from prompt
-→ Use --targets explicitly or rephrase prompt
-
-ERROR: MCP search failed
-→ Check network, retry
-
-ERROR: Batch {N} agent tasks failed
-→ Check agent output, retry specific target×style combinations
-
-ERROR: Script permission denied
-→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
-```
-
-### Recovery Strategies
-- **Partial success**: Keep successful target×style combinations
-- **Missing design_attributes**: Works without (less style-aware)
-- **Invalid tokens**: Validate design-tokens.json structure
-- **Failed batch**: Re-run command, only failed combinations will retry
-
-## Quality Checklist
-
-- [ ] Prompt clearly describes targets
-- [ ] CSS uses direct token values (no var())
-- [ ] HTML adapts to design_attributes (if available)
-- [ ] Semantic HTML5 structure
-- [ ] ARIA attributes present
-- [ ] Device-optimized layouts
-- [ ] Layouts structurally distinct
-- [ ] compare.html works
-
-## Key Features
-
-- **Prompt-Driven**: Describe what to build, command extracts targets
-- **Target-Style-Centric**: `T×S` agents, each handles `L` layouts
-- **Parallel Batching**: Max 6 concurrent agents with progress tracking
-- **Component Isolation**: Complete task independence
-- **Style-Aware**: HTML adapts to design_attributes
-- **Self-Contained CSS**: Direct token values (no var())
-- **Device-Specific**: Optimized for desktop/mobile/tablet/responsive
-- **Inspiration-Based**: MCP-powered layout research
-- **Production-Ready**: Semantic, accessible, responsive
-
-## Integration
-
-**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**: style-extract, explore-auto, imitate-auto outputs
-**Optimization**: Reuses layout inspirations from layout-extract phase, avoiding duplicate MCP searches
-
-## Usage Examples
-
-### Basic: Auto-detection
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "Dashboard with metric cards and charts"
-
-# Auto: latest design run, extracts "dashboard" target
-# Output: S × L × 1 prototypes
-```
-
-### With Session
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "Auth pages: login, signup, password reset" \
-  --session WFS-auth
-
-# Uses WFS-auth's design run
-# Extracts: ["login", "signup", "password-reset"]
-# Batches: 2 (if S=3: 9 tasks = 6+3)
-# Output: S × L × 3 prototypes
-```
-
-### Components with Device Type
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "Mobile UI components: navbar, card, footer" \
-  --target-type component \
-  --device-type mobile
-
-# Mobile-optimized component generation
-# Output: S × L × 3 prototypes
-```
-
-### Large Scale (Multi-batch)
-```bash
-/workflow:ui-design:batch-generate \
-  --prompt "E-commerce site" \
-  --targets "home,shop,product,cart,checkout" \
-  --style-variants 4 \
-  --layout-variants 2
-
-# Tasks: 5 × 4 = 20 (4 batches: 6+6+6+2)
-# Output: 4 × 2 × 5 = 40 prototypes
-```
-
-## Helper Functions Reference
-
-### Target Extraction
-```python
-# extract_targets_from_prompt(prompt_text)
-# Patterns: "Create X and Y", "Generate X, Y, Z pages", "Build X"
-# Returns: ["x", "y", "z"] (normalized lowercase with hyphens)
-
-# detect_target_type(target_list)
-# Keywords: page (home, dashboard, login) vs component (navbar, card, button)
-# Returns: "page" or "component"
-
-# extract_relevant_context_from_prompt(prompt_text, target)
-# Extracts sentences mentioning specific target
-# Returns: Relevant context string
-```
-
-## Batch Execution Details
-
-### Parallel Control
-- **Max concurrent**: 6 agents per batch
-- **Task distribution**: T × S tasks = ceil(T×S/6) batches
-- **Progress tracking**: TodoWrite per-batch status
-- **Examples**:
-  - 3 tasks → 1 batch
-  - 9 tasks → 2 batches (6+3)
-  - 20 tasks → 4 batches (6+6+6+2)
-
-### Performance
-| Tasks | Batches | Est. Time | Efficiency |
-|-------|---------|-----------|------------|
-| 1-6   | 1       | 3-5 min   | 100%       |
-| 7-12  | 2       | 6-10 min  | ~85%       |
-| 13-18 | 3       | 9-15 min  | ~80%       |
-| 19-30 | 4-5     | 12-25 min | ~75%       |
-
-### Optimization Tips
-1. **Reduce tasks**: Fewer targets or styles
-2. **Adjust layouts**: L=2 instead of L=3 for faster iteration
-3. **Stage generation**: Core pages first, secondary pages later
-
-## Notes
-
-- **Prompt quality**: Clear descriptions improve target extraction
-- **Token sources**: Consolidated (production) or proposed (fast-track)
-- **Batch parallelism**: Max 6 concurrent for stability
-- **Scalability**: Tested up to 30+ tasks (5+ batches)
-- **Dependencies**: MCP web search, ui-generate-preview.sh script

.claude/skills/command-guide/reference/commands/workflow/ui-design/capture.md

@@ -1,7 +1,7 @@
 ---
 name: capture
 description: Batch screenshot capture for UI design workflows using MCP puppeteer or local fallback with URL mapping
-argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
+argument-hint: --url-map "target:url,..." [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
 ---
 
@@ -15,19 +15,38 @@ Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes
 
 ## Phase 1: Initialize & Parse
 
-### Step 1: Determine Base Path
+### Step 1: Determine Base Path & Generate Design ID
 ```bash
-# Priority: --base-path > session > standalone
-bash(if [ -n "$BASE_PATH" ]; then
-  echo "$BASE_PATH"
+# Priority: --design-id > session (latest) > standalone (create new)
+if [ -n "$DESIGN_ID" ]; then
+  # Use provided design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+  if [ -z "$relative_path" ]; then
+    echo "ERROR: Design run not found: $DESIGN_ID"
+    echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
+    exit 1
+  fi
 elif [ -n "$SESSION_ID" ]; then
-  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
-  echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d-%H%M%S)"
+  # Find latest in session or create new
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  if [ -z "$relative_path" ]; then
+    design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+    relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
+  fi
 else
-  echo ".workflow/.design/run-$(date +%Y%m%d-%H%M%S)"
-fi)
+  # Create new standalone design run
+  design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+  relative_path=".workflow/${design_id}"
+fi
 
-bash(mkdir -p $BASE_PATH/screenshots)
+# Create directory and convert to absolute path
+bash(mkdir -p "$relative_path"/screenshots)
+base_path=$(cd "$relative_path" && pwd)
+
+# Extract and display design_id
+design_id=$(basename "$base_path")
+echo "✓ Design ID: $design_id"
+echo "✓ Base path: $base_path"
 ```
 
 ### Step 2: Parse URL Map
@@ -187,7 +206,7 @@ bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$ur
 
 Failed URLs:
   home: https://linear.app
-  Save to: .workflow/.design/run-20250110/screenshots/home.png
+  Save to: .workflow/design-run-20250110/screenshots/home.png
 
 Steps:
   1. Visit URL in browser
@@ -270,7 +289,7 @@ Next: /workflow:ui-design:extract --images "screenshots/*.png"
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Create screenshot directory
 bash(mkdir -p $BASE_PATH/screenshots)

.claude/skills/command-guide/reference/commands/workflow/ui-design/codify-style.md

@@ -0,0 +1,666 @@
+---
+name: workflow:ui-design:codify-style
+description: Orchestrator to extract styles from code and generate shareable reference package with preview (automatic file discovery)
+argument-hint: "<path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+allowed-tools: SlashCommand,Bash,Read,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Codify Style (Orchestrator)
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Coordinates style extraction from codebase and generates shareable reference packages.
+
+**Pure Orchestrator Pattern**: Does NOT directly execute agent tasks. Delegates to specialized commands:
+1. `/workflow:ui-design:import-from-code` - Extract styles from source code
+2. `/workflow:ui-design:reference-page-generator` - Generate versioned reference package with interactive preview
+
+**Output**: Shareable, versioned style reference package at `.workflow/reference_style/{package-name}/`
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:codify-style <path> --package-name <name>`
+2. Phase 0: Parameter validation & preparation → **IMMEDIATELY triggers Phase 1**
+3. Phase 1 (import-from-code) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 2
+4. Phase 2 (reference-page-generator) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 3
+5. Phase 3 (cleanup & verification) → **Execute orchestrator task** → Reports completion
+
+**Phase Transition Mechanism**:
+- **Phase 0 (Validation)**: Validate parameters, prepare workspace → IMMEDIATELY triggers Phase 1
+- **Phase 1-2 (Task Attachment)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these tasks itself.
+- **Task Execution**: Orchestrator runs attached tasks sequentially, updating TodoWrite as each completes
+- **Task Collapse**: After all attached tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing completed tasks
+- No user interaction required after initial command
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 3.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 0 validation → Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - pure orchestrator pattern
+3. **Parse & Pass**: Extract required data from each command output (design run path, metadata)
+4. **Intelligent Validation**: Smart parameter validation with user-friendly error messages
+5. **Safety First**: Package overwrite protection, existence checks, fallback error handling
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+7. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+8. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 3.
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:codify-style <path> [OPTIONS]
+
+# Required
+<path>                  Source code directory to analyze
+
+# Optional
+--package-name <name>   Custom name for the style reference package
+                        (default: auto-generated from directory name)
+--output-dir <path>     Output directory (default: .workflow/reference_style)
+--overwrite             Overwrite existing package without prompting
+```
+
+**Note**: File discovery is fully automatic. The command will scan the source directory and find all style-related files (CSS, SCSS, JS, HTML) automatically.
+
+---
+
+## 4-Phase Execution
+
+### Phase 0: Intelligent Parameter Validation & Session Preparation
+
+**Goal**: Validate parameters, check safety constraints, prepare session, and get user confirmation
+
+**TodoWrite** (First Action):
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Orchestrator tracks only high-level phases. Sub-command details shown when executed.
+
+**Step 0a: Parse and Validate Required Parameters**
+
+```bash
+# Parse positional path parameter (first non-flag argument)
+source_path = FIRST_POSITIONAL_ARG
+
+# Validate source path
+IF NOT source_path:
+    REPORT: "❌ ERROR: Missing required parameter: <path>"
+    REPORT: "USAGE: /workflow:ui-design:codify-style <path> [OPTIONS]"
+    REPORT: "EXAMPLE: /workflow:ui-design:codify-style ./src"
+    REPORT: "EXAMPLE: /workflow:ui-design:codify-style ./app --package-name design-system-v2"
+    EXIT 1
+
+# Validate source path existence
+TRY:
+    source_exists = Bash(test -d "${source_path}" && echo "exists" || echo "not_exists")
+    IF source_exists != "exists":
+        REPORT: "❌ ERROR: Source directory not found: ${source_path}"
+        REPORT: "Please provide a valid directory path."
+        EXIT 1
+CATCH error:
+    REPORT: "❌ ERROR: Cannot validate source path: ${error}"
+    EXIT 1
+
+source = source_path
+STORE: source
+
+# Auto-generate package name if not provided
+IF NOT --package-name:
+    # Extract directory name from path
+    dir_name = Bash(basename "${source}")
+    # Normalize to package name format (lowercase, replace special chars with hyphens)
+    normalized_name = dir_name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+    # Add version suffix
+    package_name = "${normalized_name}-style-v1"
+
+    ELSE:
+    package_name = --package-name
+
+    # Validate custom package name format (lowercase, alphanumeric, hyphens only)
+    IF NOT package_name MATCHES /^[a-z0-9][a-z0-9-]*$/:
+        REPORT: "❌ ERROR: Invalid package name format: ${package_name}"
+        REPORT: "Requirements:"
+        REPORT: "  • Must start with lowercase letter or number"
+        REPORT: "  • Only lowercase letters, numbers, and hyphens allowed"
+        REPORT: "  • No spaces or special characters"
+        REPORT: "EXAMPLES: main-app-style-v1, design-system-v2, component-lib-v1"
+        EXIT 1
+
+STORE: package_name, output_dir (default: ".workflow/reference_style"), overwrite_flag
+```
+
+**Step 0b: Intelligent Package Safety Check**
+
+```bash
+# Set default output directory
+output_dir = --output-dir OR ".workflow/reference_style"
+package_path = "${output_dir}/${package_name}"
+
+TRY:
+    package_exists = Bash(test -d "${package_path}" && echo "exists" || echo "not_exists")
+
+    IF package_exists == "exists":
+        IF NOT --overwrite:
+            REPORT: "❌ ERROR: Package '${package_name}' already exists at ${package_path}/"
+            REPORT: "Use --overwrite flag to replace, or choose a different package name"
+            EXIT 1
+        ELSE:
+            REPORT: "⚠️  Overwriting existing package: ${package_name}"
+
+CATCH error:
+    REPORT: "⚠️  Warning: Cannot check package existence: ${error}"
+    REPORT: "Continuing with package creation..."
+```
+
+**Step 0c: Session Preparation**
+
+```bash
+# Create temporary workspace for processing
+TRY:
+    # Step 1: Ensure .workflow directory exists and generate unique ID
+    Bash(mkdir -p .workflow)
+    temp_id = Bash(echo "codify-temp-$(date +%Y%m%d-%H%M%S)")
+
+    # Step 2: Create temporary directory
+    Bash(mkdir -p ".workflow/${temp_id}")
+
+    # Step 3: Get absolute path using bash
+    design_run_path = Bash(cd ".workflow/${temp_id}" && pwd)
+
+CATCH error:
+    REPORT: "❌ ERROR: Failed to create temporary workspace: ${error}"
+    EXIT 1
+
+STORE: temp_id, design_run_path
+```
+
+**Summary Variables**:
+- `SOURCE`: Validated source directory path
+- `PACKAGE_NAME`: Validated package name (lowercase, alphanumeric, hyphens)
+- `PACKAGE_PATH`: Full output path `${output_dir}/${package_name}`
+- `OUTPUT_DIR`: `.workflow/reference_style` (default) or user-specified
+- `OVERWRITE`: `true` if --overwrite flag present
+- `CSS/SCSS/JS/HTML/STYLE_FILES`: Optional glob patterns
+- `TEMP_ID`: `codify-temp-{timestamp}` (temporary workspace identifier)
+- `DESIGN_RUN_PATH`: Absolute path to temporary workspace
+
+<!-- TodoWrite: Update Phase 0 → completed, Phase 1 → in_progress, INSERT import-from-code tasks -->
+
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1.0: Discover and categorize code files (import-from-code)", "status": "in_progress", "activeForm": "Discovering code files"},
+  {"content": "Phase 1.1: Style Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting style tokens"},
+  {"content": "Phase 1.2: Animation Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting animation tokens"},
+  {"content": "Phase 1.3: Layout Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting layout patterns"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** import-from-code's 4 tasks to current workflow. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 1.0-1.3** sequentially
+
+---
+
+### Phase 1: Style Extraction from Source Code
+
+**Goal**: Extract design tokens, style patterns, and component styles from codebase
+
+**Command Construction**:
+
+```bash
+# Build command with required parameters only
+# Use temp_id as design-id since it's the workspace directory name
+command = "/workflow:ui-design:import-from-code" +
+          " --design-id \"${temp_id}\"" +
+          " --source \"${source}\""
+```
+
+**Execute Command (Task Attachment Pattern)**:
+
+```bash
+TRY:
+    # SlashCommand invocation ATTACHES import-from-code's 4 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 1.0: Discover and categorize code files
+    #   2. Phase 1.1: Style Agent extraction
+    #   3. Phase 1.2: Animation Agent extraction
+    #   4. Phase 1.3: Layout Agent extraction
+    SlashCommand(command)
+
+    # After executing all attached tasks, verify extraction outputs
+    tokens_path = "${design_run_path}/style-extraction/style-1/design-tokens.json"
+    guide_path = "${design_run_path}/style-extraction/style-1/style-guide.md"
+
+    tokens_exists = Bash(test -f "${tokens_path}" && echo "exists" || echo "missing")
+    guide_exists = Bash(test -f "${guide_path}" && echo "exists" || echo "missing")
+
+    IF tokens_exists != "exists" OR guide_exists != "exists":
+        REPORT: "⚠️  WARNING: Expected extraction files not found"
+        REPORT: "Continuing with available outputs..."
+
+CATCH error:
+    REPORT: "❌ ERROR: Style extraction failed"
+    REPORT: "Error: ${error}"
+    REPORT: "Possible cause: Source directory contains no style files"
+    Bash(rm -rf .workflow/${temp_id})
+    EXIT 1
+```
+
+**Example Command**:
+```bash
+# Automatic file discovery
+/workflow:ui-design:import-from-code --design-id codify-temp-20250111-123456 --source ./src
+```
+
+**Completion Criteria**:
+- ✅ `import-from-code` command executed successfully
+- ✅ Design run created at `${design_run_path}`
+- ✅ Required files exist:
+  - `design-tokens.json` - Complete design token system
+  - `style-guide.md` - Style documentation
+- ⭕ Optional files:
+  - `animation-tokens.json` - Animation specifications
+  - `component-patterns.json` - Component catalog
+
+<!-- TodoWrite: REMOVE Phase 1.0-1.3 tasks, INSERT reference-page-generator tasks -->
+
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2.0: Setup and validation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 2.1: Prepare component data (reference-page-generator)", "status": "pending", "activeForm": "Copying layout templates"},
+  {"content": "Phase 2.2: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 3 tasks. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 2.0-2.2** sequentially
+
+---
+
+### Phase 2: Reference Package Generation
+
+**Goal**: Generate shareable reference package with interactive preview and documentation
+
+**Command Construction**:
+
+```bash
+command = "/workflow:ui-design:reference-page-generator " +
+          "--design-run \"${design_run_path}\" " +
+          "--package-name \"${package_name}\" " +
+          "--output-dir \"${output_dir}\""
+```
+
+**Execute Command (Task Attachment Pattern)**:
+
+```bash
+TRY:
+    # SlashCommand invocation ATTACHES reference-page-generator's 3 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 2.0: Setup and validation
+    #   2. Phase 2.1: Prepare component data
+    #   3. Phase 2.2: Generate preview pages
+    SlashCommand(command)
+
+    # After executing all attached tasks, verify package outputs
+    required_files = [
+        "layout-templates.json",
+        "design-tokens.json",
+        "preview.html",
+        "preview.css"
+    ]
+
+    missing_files = []
+    FOR file IN required_files:
+        file_path = "${package_path}/${file}"
+        exists = Bash(test -f "${file_path}" && echo "exists" || echo "missing")
+        IF exists != "exists":
+            missing_files.append(file)
+
+    IF missing_files.length > 0:
+        REPORT: "⚠️  WARNING: Some expected files are missing"
+        REPORT: "Package may be incomplete. Continuing with cleanup..."
+
+CATCH error:
+    REPORT: "❌ ERROR: Reference package generation failed"
+    REPORT: "Error: ${error}"
+    Bash(rm -rf .workflow/${temp_id})
+    EXIT 1
+```
+
+**Example Command**:
+```bash
+/workflow:ui-design:reference-page-generator \
+  --design-run .workflow/codify-temp-20250111-123456 \
+  --package-name main-app-style-v1 \
+  --output-dir .workflow/reference_style
+```
+
+**Completion Criteria**:
+- ✅ `reference-page-generator` executed successfully
+- ✅ Reference package created at `${package_path}/`
+- ✅ All required files present:
+  - `layout-templates.json` - Layout templates from design run
+  - `design-tokens.json` - Complete design token system
+  - `preview.html` - Interactive multi-component showcase
+  - `preview.css` - Showcase styling
+- ⭕ Optional files:
+  - `animation-tokens.json` - Animation specifications (if available from extraction)
+
+<!-- TodoWrite: REMOVE Phase 2.0-2.2 tasks, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "completed", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "in_progress", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**Next Action**: TodoWrite restored → **Execute Phase 3** (orchestrator's own task)
+
+---
+
+### Phase 3: Cleanup & Verification
+
+**Goal**: Clean up temporary workspace and report completion
+
+**Operations**:
+
+```bash
+# Cleanup temporary workspace
+TRY:
+    Bash(rm -rf .workflow/${temp_id})
+CATCH error:
+    # Silent failure - not critical
+
+# Quick verification
+package_exists = Bash(test -d "${package_path}" && echo "exists" || echo "missing")
+
+IF package_exists != "exists":
+    REPORT: "❌ ERROR: Package generation failed - directory not found"
+    EXIT 1
+
+# Get absolute path and component count for final report
+absolute_package_path = Bash(cd "${package_path}" && pwd 2>/dev/null || echo "${package_path}")
+component_count = Bash(jq -r '.layout_templates | length // "unknown"' "${package_path}/layout-templates.json" 2>/dev/null || echo "unknown")
+anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓" || echo "○")
+```
+
+<!-- TodoWrite: Update Phase 3 → completed -->
+
+**Final Action**: Display completion summary to user
+
+---
+
+## Completion Message
+
+```
+✅ Style reference package generated successfully
+
+📦 Package: {package_name}
+📂 Location: {absolute_package_path}/
+📄 Source: {source}
+📊 Components: {component_count}
+
+Files: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
+
+Preview: file://{absolute_package_path}/preview.html
+
+Next: /memory:style-skill-memory {package_name}
+```
+
+---
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize IMMEDIATELY at the start to track orchestrator workflow (4 high-level tasks)
+TodoWrite({todos: [
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]})
+
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// 1. INITIAL STATE: 4 orchestrator-level tasks only
+//
+// 2. PHASE 1 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+//    - TodoWrite expands to: Phase 0 (completed) + 4 import-from-code tasks + Phase 2 + Phase 3
+//    - Orchestrator EXECUTES these 4 tasks sequentially (Phase 1.0 → 1.1 → 1.2 → 1.3)
+//    - First attached task marked as in_progress
+//
+// 3. PHASE 1 TASKS COMPLETED:
+//    - All 4 import-from-code tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 1 summary
+//    - TodoWrite becomes: Phase 0-1 (completed) + Phase 2 + Phase 3
+//
+// 4. PHASE 2 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
+//    - TodoWrite expands to: Phase 0-1 (completed) + 3 reference-page-generator tasks + Phase 3
+//    - Orchestrator EXECUTES these 3 tasks sequentially (Phase 2.0 → 2.1 → 2.2)
+//
+// 5. PHASE 2 TASKS COMPLETED:
+//    - All 3 reference-page-generator tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 2 summary
+//    - TodoWrite returns to: Phase 0-2 (completed) + Phase 3 (in_progress)
+//
+// 6. PHASE 3 EXECUTION:
+//    - Orchestrator's own task (no SlashCommand attachment)
+//    - Mark Phase 3 as completed
+//    - Final state: All 4 orchestrator tasks completed
+//
+// Benefits:
+// ✓ Real-time visibility into attached tasks during execution
+// ✓ Clean orchestrator-level summary after tasks complete
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Dynamic attachment/collapse maintains clarity
+```
+
+---
+
+## Execution Flow Diagram
+
+```
+User triggers: /workflow:ui-design:codify-style ./src --package-name my-style-v1
+  ↓
+[TodoWrite Init] 4 orchestrator-level tasks
+  ├─ Phase 0: Validate parameters and prepare session (in_progress)
+  ├─ Phase 1: Style extraction from source code (pending)
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Phase 0] Parameter validation & preparation
+  ├─ Parse positional path parameter
+  ├─ Validate source directory exists
+  ├─ Auto-generate or validate package name
+  ├─ Check package overwrite protection
+  ├─ Create temporary workspace
+  └─ Display configuration summary
+  ↓
+[Phase 0 Complete] → TodoWrite: Phase 0 → completed
+  ↓
+[Phase 1 Invoke] → SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1.0: Discover and categorize code files (in_progress)  ← ATTACHED
+  ├─ Phase 1.1: Style Agent extraction (pending)                   ← ATTACHED
+  ├─ Phase 1.2: Animation Agent extraction (pending)               ← ATTACHED
+  ├─ Phase 1.3: Layout Agent extraction (pending)                  ← ATTACHED
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 1.0] → Discover files (orchestrator executes this)
+  ↓
+[Execute Phase 1.1-1.3] → Run 3 agents in parallel (orchestrator executes these)
+  └─ Outputs: design-tokens.json, style-guide.md, animation-tokens.json, layout-templates.json
+  ↓
+[Phase 1 Complete] → TodoWrite: COLLAPSE Phase 1.0-1.3 into Phase 1 summary
+  ↓
+[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)        ← COLLAPSED
+  ├─ Phase 2.0: Setup and validation (in_progress)                 ← ATTACHED
+  ├─ Phase 2.1: Prepare component data (pending)                   ← ATTACHED
+  ├─ Phase 2.2: Generate preview pages (pending)                   ← ATTACHED
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 2.0] → Setup and validation (orchestrator executes this)
+  ↓
+[Execute Phase 2.1] → Prepare component data (orchestrator executes this)
+  ↓
+[Execute Phase 2.2] → Generate preview pages (orchestrator executes this)
+  └─ Outputs: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
+  ↓
+[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.0-2.2 into Phase 2 summary
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)
+  ├─ Phase 2: Reference package generation (completed)             ← COLLAPSED
+  └─ Phase 3: Cleanup and verify package (in_progress)
+  ↓
+[Execute Phase 3] → Orchestrator's own task (no attachment needed)
+  ├─ Remove temporary workspace (.workflow/codify-temp-{timestamp}/)
+  ├─ Verify package directory
+  ├─ Extract component count
+  └─ Display completion summary
+  ↓
+[Phase 3 Complete] → TodoWrite: Phase 3 → completed
+  ├─ Phase 0 (completed)
+  ├─ Phase 1 (completed)
+  ├─ Phase 2 (completed)
+  └─ Phase 3 (completed)
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing --source or --package-name | Required parameters not provided | Provide both flags |
+| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
+| import-from-code failed | Source path invalid or no files found | Verify source path, check glob patterns |
+| reference-page-generator failed | Design run incomplete | Check import-from-code output, verify extraction files |
+| Package verification failed | Output directory creation failed | Check file permissions |
+
+### Error Recovery
+
+- If Phase 2 fails: Cleanup temporary session and report error
+- If Phase 3 fails: Keep design run for debugging, report error
+- User can manually inspect `${design_run_path}` if needed
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
+2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
+3. **Status-Driven Execution**: Check TodoList status after each phase
+4. **Phase Completion Pattern**:
+   ```
+   Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
+   ```
+
+### Parameter Pass-Through
+
+Only essential parameters are passed to `import-from-code`:
+- `--design-id` → temporary design run ID (auto-generated)
+- `--source` → user-specified source directory
+
+File discovery is fully automatic - no glob patterns needed.
+
+### Output Directory Structure
+
+```
+.workflow/
+├── reference_style/              # Default output directory
+│   └── {package-name}/
+│       ├── layout-templates.json
+│       ├── design-tokens.json
+│       ├── animation-tokens.json (optional)
+│       ├── preview.html
+│       └── preview.css
+│
+└── codify-temp-{timestamp}/      # Temporary workspace (cleaned up after completion)
+    ├── style-extraction/
+    ├── animation-extraction/
+    └── layout-extraction/
+```
+
+---
+
+## Benefits
+
+- **Simplified Interface**: Single path parameter with intelligent defaults
+- **Auto-Generation**: Package names auto-generated from directory names
+- **Automatic Discovery**: No need to specify file patterns - finds all style files automatically
+- **Pure Orchestrator**: No direct agent execution, delegates to specialized commands
+- **Auto-Continue**: Autonomous 4-phase execution without user interaction
+- **Safety First**: Overwrite protection, validation checks, error handling
+- **Code Reuse**: Leverages existing `import-from-code` and `reference-page-generator` commands
+- **Clean Separation**: Each command has single responsibility
+- **Easy Maintenance**: Changes to sub-commands automatically apply
+
+## Architecture
+
+```
+codify-style (orchestrator - simplified interface)
+  ├─ Phase 0: Intelligent Validation
+  │   ├─ Parse positional path parameter
+  │   ├─ Auto-generate package name (if not provided)
+  │   ├─ Safety checks (overwrite protection)
+  │   └─ User confirmation
+  ├─ Phase 1: /workflow:ui-design:import-from-code (style extraction)
+  │   ├─ Extract design tokens from source code
+  │   ├─ Generate style guide
+  │   └─ Extract component patterns
+  ├─ Phase 2: /workflow:ui-design:reference-page-generator (reference package)
+  │   ├─ Generate shareable package
+  │   ├─ Create interactive preview
+  │   └─ Generate documentation
+  └─ Phase 3: Cleanup & Verification
+      ├─ Remove temporary workspace
+      ├─ Verify package integrity
+      └─ Report completion
+
+Design Principles:
+✓ No task JSON created by this command
+✓ All extraction delegated to import-from-code
+✓ All packaging delegated to reference-page-generator
+✓ Pure orchestration with intelligent defaults
+✓ Single path parameter for maximum simplicity
+```

.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-auto.md

@@ -1,7 +1,7 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution
-argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
+description: Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection
+argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 
@@ -18,35 +18,60 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 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.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
-8. Phase 5 (batch-plan, optional) → Reports completion
+2. Phase 5: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 7**
+3. Phase 7 (style-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 8
+4. Phase 8 (animation-extract, conditional):
+   - **IF should_extract_animation**: **Attach tasks → Execute → Collapse** → Auto-continues to Phase 9
+   - **ELSE**: Skip (use code import) → Auto-continues to Phase 9
+5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
+6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 11
+7. **Phase 11 (preview-generation)** → **Execute script → Generate preview files** → Reports completion
 
 **Phase Transition Mechanism**:
-- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
-- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
-- Upon each phase completion: Automatically process output and execute next phase
-- No additional user interaction after Phase 0c confirmation
+- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
+- **Phase 7-10 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
+- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
+- **Task Collapse**: After tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing
+- **Phase 11 (Script Execution)**: Execute preview generation script
+- No additional user interaction after Phase 5 confirmation
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 11 (preview generation).
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
 
 **Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
 
 ## Core Rules
 
-1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+1. **Start Immediately**: TodoWrite initialization → Phase 7 execution
 2. **No Preliminary Validation**: Sub-commands handle their own validation
 3. **Parse & Pass**: Extract data from each output for next phase
 4. **Default to All**: When selecting variants/prototypes, use ALL generated items
-5. **Track Progress**: Update TodoWrite after each phase
-6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 11 (preview generation).
 
 ## Parameter Requirements
 
+**Recommended Parameter**:
+- `--input "<value>"`: Unified input source (auto-detects type)
+  - **Glob pattern** (images): `"design-refs/*"`, `"screenshots/*.png"`
+  - **File/directory path** (code): `"./src/components"`, `"/path/to/styles"`
+  - **Text description** (prompt): `"modern dashboard with 3 styles"`, `"minimalist design"`
+  - **Combination**: `"design-refs/* modern dashboard"` (glob + description)
+  - Multiple inputs: Separate with `|` → `"design-refs/*|modern style"`
+
+**Detection Logic**:
+- Contains `*` or matches existing files → **glob pattern** (images)
+- Existing file/directory path → **code import**
+- Pure text without paths → **design prompt**
+- Contains `|` separator → **multiple inputs** (glob|prompt or path|prompt)
+
+**Legacy Parameters** (deprecated, use `--input` instead):
+- `--images "<glob>"`: Reference image paths (shows deprecation warning)
+- `--prompt "<description>"`: Design description (shows deprecation warning)
+
 **Optional Parameters** (all have smart defaults):
 - `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
 - `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
@@ -56,19 +81,16 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
   - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
   - **Responsive**: 1920×1080px base with mobile-first breakpoints
 - `--session <id>`: Workflow session ID (standalone mode if omitted)
-- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
-- `--prompt "<description>"`: Design style and target description
 - `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
 - `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
-- `--batch-plan`: Auto-generate implementation tasks after design-update
 
-**Legacy Parameters** (maintained for backward compatibility):
+**Legacy Target Parameters** (maintained for backward compatibility):
 - `--pages "<list>"`: Alias for `--targets` with `--target-type page`
 - `--components "<list>"`: Alias for `--targets` with `--target-type component`
 
 **Input Rules**:
-- Must provide at least one: `--images` or `--prompt` or `--targets`
-- Multiple parameters can be combined for guided analysis
+- Must provide: `--input` OR (legacy: `--images`/`--prompt`) OR `--targets`
+- `--input` can combine multiple input types
 - If `--targets` not provided, intelligently inferred from prompt/session
 
 **Supported Target Types**:
@@ -105,27 +127,63 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
 
-## 6-Phase Execution
+## 11-Phase Execution
 
-### Phase 0a: Intelligent Path Detection & Source Selection
+### Phase 1: Parameter Parsing & Input Detection
 ```bash
-# Step 1: Detect if prompt/images contain existing file paths
+# Step 0: Parse and normalize parameters
+images_input = null
+prompt_text = null
+
+# Handle legacy parameters with deprecation warning
+IF --images OR --prompt:
+    WARN: "⚠️  DEPRECATION: --images and --prompt are deprecated. Use --input instead."
+    WARN: "   Example: --input \"design-refs/*\" or --input \"modern dashboard\""
+    images_input = --images
+    prompt_text = --prompt
+
+# Parse unified --input parameter
+IF --input:
+    # Split by | separator for multiple inputs
+    input_parts = split(--input, "|")
+
+    FOR part IN input_parts:
+        part = trim(part)
+
+        # Detection logic
+        IF contains(part, "*") OR glob_matches_files(part):
+            # Glob pattern detected → images
+            images_input = part
+        ELSE IF file_or_directory_exists(part):
+            # File/directory path → will be handled in code detection
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+        ELSE:
+            # Pure text → prompt
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+
+# Step 1: Detect design source from parsed inputs
 code_files_detected = false
 code_base_path = null
 has_visual_input = false
 
-IF --prompt:
+IF prompt_text:
     # Extract potential file paths from prompt
-    potential_paths = extract_paths_from_text(--prompt)
+    potential_paths = extract_paths_from_text(prompt_text)
     FOR path IN potential_paths:
         IF file_or_directory_exists(path):
             code_files_detected = true
             code_base_path = path
             BREAK
 
-IF --images:
+IF images_input:
     # Check if images parameter points to existing files
-    IF glob_matches_files(--images):
+    IF glob_matches_files(images_input):
         has_visual_input = true
 
 # Step 2: Determine design source strategy
@@ -143,20 +201,23 @@ ELSE:
 STORE: design_source, code_base_path, has_visual_input
 ```
 
-### Phase 0a-2: Intelligent Prompt Parsing
+### Phase 2: Intelligent Prompt Parsing
 ```bash
 # Parse variant counts from prompt or use explicit/default values
-IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
-    style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
-    layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
+IF prompt_text AND (NOT --style-variants OR NOT --layout-variants):
+    style_variants = regex_extract(prompt_text, r"(\d+)\s*style") OR --style-variants OR 3
+    layout_variants = regex_extract(prompt_text, r"(\d+)\s*layout") OR --layout-variants OR 3
 ELSE:
     style_variants = --style-variants OR 3
     layout_variants = --layout-variants OR 3
 
 VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+
+# Interactive mode (always enabled)
+interactive_mode = true  # Always use interactive mode
 ```
 
-### Phase 0a-2: Device Type Inference
+### Phase 3: Device Type Inference
 ```bash
 # Device type inference
 device_type = "auto"
@@ -167,14 +228,14 @@ IF --device-type AND --device-type != "auto":
     device_source = "explicit"
 ELSE:
     # Step 2: Prompt analysis
-    IF --prompt:
+    IF prompt_text:
         device_keywords = {
             "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
             "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
             "tablet": ["tablet", "ipad", "medium screen"],
             "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
         }
-        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        detected_device = detect_device_from_prompt(prompt_text, device_keywords)
         IF detected_device:
             device_type = detected_device
             device_source = "prompt_inference"
@@ -201,27 +262,36 @@ STORE: device_type, device_source
 - Prompt contains "responsive", "adaptive" → responsive
 - Otherwise: Inferred from target type (components→desktop, pages→responsive)
 
-### Phase 0b: Run Initialization & Directory Setup
+### Phase 4: Run Initialization & Directory Setup
 ```bash
-run_id = "run-$(date +%Y%m%d-%H%M%S)"
-base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
+relative_base_path = --session ? ".workflow/WFS-{session}/${design_id}" : ".workflow/${design_id}"
 
-Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+# Create directory and convert to absolute path
+Bash(mkdir -p "${relative_base_path}/style-extraction")
+Bash(mkdir -p "${relative_base_path}/prototypes")
+base_path=$(cd "${relative_base_path}" && pwd)
 
 Write({base_path}/.run-metadata.json): {
-  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "design_id": "${design_id}", "session_id": "${session_id}", "timestamp": "...",
   "workflow": "ui-design:auto",
   "architecture": "style-centric-batch-generation",
   "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
                   "targets": "${inferred_target_list}", "target_type": "${target_type}",
-                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "prompt": "${prompt_text}", "images": "${images_input}",
+                  "input": "${--input}",
                   "device_type": "${device_type}", "device_source": "${device_source}" },
   "status": "in_progress",
   "performance_mode": "optimized"
 }
+
+# Initialize default flags for animation extraction logic
+animation_complete = false  # Default: always extract animations unless code import proves complete
+needs_visual_supplement = false  # Will be set to true in hybrid mode
+skip_animation_extraction = false  # User preference for code import scenario
 ```
 
-### Phase 0c: Unified Target Inference with Intelligent Type Detection
+### Phase 5: Unified Target Inference with Intelligent Type Detection
 ```bash
 # Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
 target_list = []; target_type = "auto"; target_source = "none"
@@ -234,8 +304,8 @@ ELSE IF --targets:
     target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
 
 # Step 3: Prompt analysis (Claude internal analysis)
-ELSE IF --prompt:
-    analysis_result = analyze_prompt("{prompt_text}")  # Extract targets, types, purpose
+ELSE IF prompt_text:
+    analysis_result = analyze_prompt(prompt_text)  # Extract targets, types, purpose
     target_list = analysis_result.targets
     target_type = analysis_result.primary_type OR detect_target_type(target_list)
     target_source = "prompt_analysis"
@@ -286,7 +356,7 @@ MATCH user_input:
 
 STORE: inferred_target_list, target_type, target_inference_source
 
-# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 7
 # This is the only user interaction point in the workflow
 # After this point, all subsequent phases execute automatically without user intervention
 ```
@@ -303,17 +373,35 @@ detect_target_type(target_list):
     RETURN "component" IF component_matches > page_matches ELSE "page"
 ```
 
-### Phase 0d: Code Import & Completeness Assessment (Conditional)
+### Phase 6: Code Import & Completeness Assessment (Conditional)
 ```bash
 IF design_source IN ["code_only", "hybrid"]:
-    REPORT: "🔍 Phase 0d: Code Import ({design_source})"
-    command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" --base-path \"{code_base_path}\""
-    SlashCommand(command)
+    REPORT: "🔍 Phase 6: Code Import ({design_source})"
+    command = "/workflow:ui-design:import-from-code --design-id \"{design_id}\" --source \"{code_base_path}\""
+
+    TRY:
+        # SlashCommand invocation ATTACHES import-from-code's tasks to current workflow
+        # Orchestrator will EXECUTE these attached tasks itself:
+        #   - Phase 0: Discover and categorize code files
+        #   - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
+        SlashCommand(command)
+    CATCH error:
+        WARN: "⚠️ Code import failed: {error}"
+        WARN: "Cleaning up incomplete import directories"
+        Bash(rm -rf "{base_path}/style-extraction" "{base_path}/animation-extraction" "{base_path}/layout-extraction" 2>/dev/null)
+
+        IF design_source == "code_only":
+            REPORT: "Cannot proceed with code-only mode after import failure"
+            EXIT 1
+        ELSE:  # hybrid mode
+            WARN: "Continuing with visual-only mode"
+            design_source = "visual_only"
 
     # Check file existence and assess completeness
     style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
     animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
-    layout_exists = exists("{base_path}/layout-extraction/layout-templates.json")
+    layout_count = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
+    layout_exists = (layout_count > 0)
 
     style_complete = false
     animation_complete = false
@@ -349,14 +437,16 @@ IF design_source IN ["code_only", "hybrid"]:
 
     # Layout completeness check
     IF layout_exists:
-        layouts = Read("{base_path}/layout-extraction/layout-templates.json")
+        # Read first layout file to verify structure
+        first_layout = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | head -1)
+        layout_data = Read(first_layout)
         layout_complete = (
-            layouts.layout_templates?.length >= 3 &&
-            layouts.extraction_metadata?.layout_system?.type &&
-            layouts.extraction_metadata?.responsive?.breakpoints
+            layout_count >= 1 &&
+            layout_data.template?.dom_structure &&
+            layout_data.template?.css_layout_rules
         )
-        IF NOT layout_complete AND layouts.extraction_metadata?.completeness?.missing_items:
-            missing_categories.extend(layouts.extraction_metadata.completeness.missing_items)
+        IF NOT layout_complete:
+            missing_categories.push("complete layout structure")
     ELSE:
         missing_categories.push("layout templates")
 
@@ -374,169 +464,206 @@ IF design_source IN ["code_only", "hybrid"]:
     ELSE IF design_source == "hybrid":
         needs_visual_supplement = true
 
-    STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete
+    # Animation reuse confirmation (code import with complete animations)
+    IF design_source == "code_only" AND animation_complete:
+        REPORT: "✅ 检测到完整的动画系统（来自代码导入）"
+        REPORT: "   Duration scales: {duration_count} | Easing functions: {easing_count}"
+        REPORT: ""
+        REPORT: "Options:"
+        REPORT: "  • 'reuse' (默认) - 复用已有动画系统"
+        REPORT: "  • 'regenerate' - 重新生成动画系统（交互式）"
+        REPORT: "  • 'cancel' - 取消工作流"
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+            "reuse" → skip_animation_extraction = true
+            "regenerate" → skip_animation_extraction = false
+            "cancel" → EXIT 0
+            default → skip_animation_extraction = true  # Default: reuse
+
+    STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete, skip_animation_extraction
 ```
 
-### Phase 1: Style Extraction
+### Phase 7: Style Extraction
 ```bash
 IF design_source == "visual_only" OR needs_visual_supplement:
-    REPORT: "🎨 Phase 1: Style Extraction (variants: {style_variants})"
-    command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
-              (--images ? "--images \"{images}\" " : "") +
-              (--prompt ? "--prompt \"{prompt}\" " : "") +
-              "--mode explore --variants {style_variants}"
+    REPORT: "🎨 Phase 7: Style Extraction (variants: {style_variants})"
+    command = "/workflow:ui-design:style-extract --design-id \"{design_id}\" " +
+              (images_input ? "--images \"{images_input}\" " : "") +
+              (prompt_text ? "--prompt \"{prompt_text}\" " : "") +
+              "--variants {style_variants} --interactive"
+
+    # SlashCommand invocation ATTACHES style-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
 ELSE:
-    REPORT: "✅ Phase 1: Style (Using Code Import)"
+    REPORT: "✅ Phase 7: Style (Using Code Import)"
 ```
 
-### Phase 2.3: Animation Extraction
+### Phase 8: Animation Extraction
 ```bash
-IF design_source == "visual_only" OR NOT animation_complete:
-    REPORT: "🚀 Phase 2.3: Animation Extraction"
-    command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
+# Determine if animation extraction is needed
+should_extract_animation = false
+
+IF (design_source == "visual_only" OR needs_visual_supplement):
+    # Pure visual input or hybrid mode requiring visual supplement
+    should_extract_animation = true
+ELSE IF NOT animation_complete:
+    # Code import but animations are incomplete
+    should_extract_animation = true
+ELSE IF design_source == "code_only" AND animation_complete AND NOT skip_animation_extraction:
+    # Code import with complete animations, but user chose to regenerate
+    should_extract_animation = true
+
+IF should_extract_animation:
+    REPORT: "🚀 Phase 8: Animation Extraction"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:animation-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    command_parts.append("--interactive")
+
+    command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES animation-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
 ELSE:
-    REPORT: "✅ Phase 2.3: Animation (Using Code Import)"
+    REPORT: "✅ Phase 8: Animation (Using Code Import)"
 
 # Output: animation-tokens.json + animation-guide.md
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
+# When phase finishes, IMMEDIATELY execute Phase 9 (auto-continue)
 ```
 
-### Phase 2.5: Layout Extraction
+### Phase 9: Layout Extraction
 ```bash
 targets_string = ",".join(inferred_target_list)
 
 IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_complete):
-    REPORT: "🚀 Phase 2.5: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})"
-    command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
-              (--images ? "--images \"{images}\" " : "") +
-              (--prompt ? "--prompt \"{prompt}\" " : "") +
-              "--targets \"{targets_string}\" --mode explore --variants {layout_variants} --device-type \"{device_type}\""
+    REPORT: "🚀 Phase 9: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})"
+    command = "/workflow:ui-design:layout-extract --design-id \"{design_id}\" " +
+              (images_input ? "--images \"{images_input}\" " : "") +
+              (prompt_text ? "--prompt \"{prompt_text}\" " : "") +
+              "--targets \"{targets_string}\" --variants {layout_variants} --device-type \"{device_type}\" --interactive"
+
+    # SlashCommand invocation ATTACHES layout-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
 ELSE:
-    REPORT: "✅ Phase 2.5: Layout (Using Code Import)"
+    REPORT: "✅ Phase 9: Layout (Using Code Import)"
 ```
 
-### Phase 3: UI Assembly
+### Phase 10: UI Assembly
 ```bash
-command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
-          "--style-variants {style_variants} --layout-variants {layout_variants}"
+command = "/workflow:ui-design:generate --design-id \"{design_id}\"" + (--session ? " --session {session_id}" : "")
 
 total = style_variants × layout_variants × len(inferred_target_list)
 
-REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "🚀 Phase 10: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
 REPORT: "   → Pure assembly: Combining layout templates + design tokens"
 REPORT: "   → Device: {device_type} (from layout templates)"
 REPORT: "   → Assembly tasks: {total} combinations"
 
+# SlashCommand invocation ATTACHES generate's tasks to current workflow
+# Orchestrator will EXECUTE these attached tasks itself
 SlashCommand(command)
 
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
+# After executing all attached tasks, collapse them into phase summary
+# When phase finishes, IMMEDIATELY execute Phase 11 (auto-continue)
 # Output:
 # - {target}-style-{s}-layout-{l}.html (assembled prototypes)
 # - {target}-style-{s}-layout-{l}.css
-# - compare.html (interactive matrix view)
-# - PREVIEW.md (usage instructions)
+# Note: compare.html and PREVIEW.md will be generated in Phase 11
 ```
 
-### Phase 4: Design System Integration
+### Phase 11: Generate Preview Files
 ```bash
-command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
-SlashCommand(command)
+REPORT: "🚀 Phase 11: Generate Preview Files"
 
-# SlashCommand blocks until phase complete
-# Upon completion:
-#   - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
-#   - If no --batch-plan: Workflow complete, display final report
-```
+# Update TodoWrite to reflect preview generation phase
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
+  {"content": "Generate preview files", "status": "in_progress", "activeForm": "Generating preview files"}
+]})
 
-### Phase 5: Batch Task Generation (Optional)
-```bash
-IF --batch-plan:
-    FOR target IN inferred_target_list:
-        task_desc = "Implement {target} {target_type} based on design system"
-        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
+# Execute preview generation script
+Bash(~/.claude/scripts/ui-generate-preview.sh "${base_path}/prototypes")
+
+# Verify output files
+IF NOT exists("${base_path}/prototypes/compare.html"):
+    ERROR: "Preview generation failed: compare.html not found"
+    EXIT 1
+
+IF NOT exists("${base_path}/prototypes/PREVIEW.md"):
+    ERROR: "Preview generation failed: PREVIEW.md not found"
+    EXIT 1
+
+# Mark preview generation as complete
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "completed", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "completed", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "completed", "activeForm": "Executing UI assembly"},
+  {"content": "Generate preview files", "status": "completed", "activeForm": "Generating preview files"}
+]})
+
+REPORT: "✅ Preview files generated successfully"
+REPORT: "   → compare.html (interactive matrix view)"
+REPORT: "   → PREVIEW.md (usage instructions)"
+
+# Workflow complete, display final report
 ```
 
 ## TodoWrite Pattern
 ```javascript
-// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
+// Initialize IMMEDIATELY after Phase 5 user confirmation to track multi-phase execution (5 orchestrator-level tasks)
 TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "in_progress", "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..."}
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "pending", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"},
+  {"content": "Generate preview files", "status": "pending", "activeForm": "Generating preview files"}
 ]})
 
-// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
-// 1. SlashCommand blocks and returns when phase is complete
-// 2. Update current phase: status → "completed"
-// 3. Update next phase: status → "in_progress"
-// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
-// This ensures continuous workflow tracking and prevents premature stopping
-```
-
-## Key Features
-
-- **🚀 Performance**: Style-centric batch generation with S agent calls
-- **🎨 Style-Aware**: HTML structure adapts to design_attributes
-- **✅ Perfect Consistency**: Each style by single agent
-- **📦 Autonomous**: No user intervention required between phases
-- **🧠 Intelligent**: Parses natural language, infers targets/types
-- **🔄 Reproducible**: Deterministic flow with isolated run directories
-- **🎯 Flexible**: Supports pages, components, or mixed targets
-
-## Examples
-
-### 1. Page Mode (Prompt Inference)
-```bash
-/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
-# Result: 27 prototypes (3×3×3) - responsive layouts (default)
-```
-
-### 2. Mobile-First Design
-```bash
-/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
-# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
-```
-
-### 3. Desktop Application
-```bash
-/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
-# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
-```
-
-### 4. Tablet Interface
-```bash
-/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
-# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
-```
-
-### 5. Custom Matrix with Session
-```bash
-/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
-# Result: 2×2×N prototypes - device type inferred from session
-```
-
-### 6. Component Mode (Desktop)
-```bash
-/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
-# Result: 12 prototypes (3×2×2) - desktop components
-```
-
-### 7. Intelligent Parsing + Batch Planning
-```bash
-/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
-# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
-```
-
-### 8. Large Scale Responsive
-```bash
-/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
-# Result: 36 prototypes (3×3×4) - responsive layouts
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// Phase 7-10 SlashCommand Invocation Pattern:
+// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
+// 2. TodoWrite expands to include attached tasks
+// 3. Orchestrator EXECUTES attached tasks sequentially
+// 4. After all attached tasks complete, COLLAPSE them into phase summary
+// 5. Update next phase to in_progress
+// 6. IMMEDIATELY execute next phase (auto-continue)
+//
+// Phase 11 Script Execution Pattern:
+// 1. Mark "Generate preview files" as in_progress
+// 2. Execute preview generation script via Bash tool
+// 3. Verify output files (compare.html, PREVIEW.md)
+// 4. Mark "Generate preview files" as completed
+//
+// Benefits:
+// ✓ Real-time visibility into sub-command task progress
+// ✓ Clean orchestrator-level summary after each phase
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Script execution for preview generation (no delegation)
+// ✓ Dynamic attachment/collapse maintains clarity
 ```
 
 ## Completion Output
@@ -547,34 +674,37 @@ 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} complete design systems (style-extract)
-Phase 2: {n×l} layout templates (layout-extract explore mode)
+Phase 7: {s} complete design systems (style-extract with multi-select)
+Phase 9: {n×l} layout templates (layout-extract with multi-select)
   - Device: {device_type} layouts
   - {n} targets × {l} layout variants = {n×l} structural templates
-Phase 3: UI Assembly (generate)
+  - User-selected concepts generated in parallel
+Phase 10: UI Assembly (generate)
   - Pure assembly: layout templates + design tokens
   - {s}×{l}×{n} = {total} final prototypes
-Phase 4: Brainstorming artifacts updated
-[Phase 5: {n} implementation tasks created]  # if --batch-plan
+Phase 11: Preview files generated (compare.html, PREVIEW.md)
 
 Assembly Process:
 ✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
 ✅ Layout Extraction: {n×l} reusable structural templates
+✅ Multi-Selection Workflow: User selects multiple variants from generated options
 ✅ Pure Assembly: No design decisions in generate phase
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 Design Quality:
 ✅ Token-Driven Styling: 100% var() usage
-✅ Structural Variety: {l} distinct layouts per target
-✅ Style Variety: {s} independent design systems
+✅ Structural Variety: {l} distinct layouts per target (user-selected)
+✅ Style Variety: {s} independent design systems (user-selected)
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 📂 {base_path}/
   ├── .intermediates/          (Intermediate analysis files)
-  │   ├── style-analysis/      (computed-styles.json, design-space-analysis.json)
-  │   └── layout-analysis/     (dom-structure-*.json, inspirations/*.txt)
+  │   ├── style-analysis/      (analysis-options.json with embedded user_selection, computed-styles.json if URL mode)
+  │   ├── animation-analysis/  (analysis-options.json with embedded user_selection, animations-*.json if URL mode)
+  │   └── layout-analysis/     (analysis-options.json with embedded user_selection, dom-structure-*.json if URL mode)
   ├── style-extraction/        ({s} complete design systems)
-  ├── layout-extraction/       ({n×l} layout templates + layout-space-analysis.json)
+  ├── animation-extraction/    (animation-tokens.json, animation-guide.md)
+  ├── layout-extraction/       ({n×l} layout template files: layout-{target}-{variant}.json)
   ├── prototypes/              ({total} assembled prototypes)
   └── .run-metadata.json       (includes device type)
 
@@ -590,6 +720,6 @@ Design Quality:
   - Layout plans stored as structured JSON
   - Optimized for {device_type} viewing
 
-Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+Next: Open compare.html to preview all design variants
 ```
 

.claude/skills/command-guide/reference/commands/workflow/ui-design/explore-layers.md

@@ -1,7 +1,7 @@
 ---
 name: explore-layers
 description: Interactive deep UI capture with depth-controlled layer exploration using MCP puppeteer
-argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
+argument-hint: --url <url> --depth <1-5> [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
 ---
 
@@ -38,17 +38,39 @@ IF depth NOT IN [1, 2, 3, 4, 5]:
 
 ### Step 2: Determine Base Path
 ```bash
-bash(if [ -n "$BASE_PATH" ]; then
-  echo "$BASE_PATH"
+# Priority: --design-id > --session > create new
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+  if [ -z "$relative_path" ]; then
+    echo "ERROR: Design run not found: $DESIGN_ID"
+    echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
+    exit 1
+  fi
 elif [ -n "$SESSION_ID" ]; then
-  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
-  echo ".workflow/WFS-$SESSION_ID/design-layers-$(date +%Y%m%d-%H%M%S)"
+  # Find latest in session or create new
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  if [ -z "$relative_path" ]; then
+    design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+    relative_path=".workflow/WFS-$SESSION_ID/${design_id}"
+  fi
 else
-  echo ".workflow/.design/layers-$(date +%Y%m%d-%H%M%S)"
-fi)
+  # Create new standalone design run
+  design_id="design-run-$(date +%Y%m%d)-$RANDOM"
+  relative_path=".workflow/${design_id}"
+fi
+
+# Create directory structure and convert to absolute path
+bash(mkdir -p "$relative_path")
+base_path=$(cd "$relative_path" && pwd)
+
+# Extract and display design_id
+design_id=$(basename "$base_path")
+echo "✓ Design ID: $design_id"
+echo "✓ Base path: $base_path"
 
 # Create depth directories
-bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
+bash(for i in $(seq 1 $depth); do mkdir -p "$base_path"/screenshots/depth-$i; done)
 ```
 
 **Output**: `url`, `depth`, `base_path`

.claude/skills/command-guide/reference/commands/workflow/ui-design/generate.md

@@ -1,7 +1,7 @@
 ---
 name: generate
-description: Assemble UI prototypes by combining layout templates with design tokens, pure assembler without new content generation
-argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+description: Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation
+argument-hint: [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---
 
@@ -11,7 +11,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
 
 **Strategy**: Pure Assembly
-- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available)
+- **Input**: `layout-*.json` files + `design-tokens.json` (+ reference images if available)
 - **Process**: Combine structure (DOM) with style (tokens)
 - **Output**: Complete HTML/CSS prototypes
 - **No Design Logic**: All layout and style decisions already made
@@ -25,23 +25,48 @@ Pure assembler that combines pre-extracted layout templates with design tokens t
 
 ### Step 1: Resolve Base Path & Parse Configuration
 ```bash
-# Determine working directory
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 
 # Get style count
-bash(ls {base_path}/style-extraction/style-* -d | wc -l)
+bash(ls "$base_path"/style-extraction/style-* -d | wc -l)
 
 # Image reference auto-detected from layout template source_image_path
 ```
 
 ### Step 2: Load Layout Templates
 ```bash
-# Check layout templates exist
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# Check layout templates exist (multi-file pattern)
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 
-# Load layout templates
-Read({base_path}/layout-extraction/layout-templates.json)
-# Extract: targets, layout_variants count, device_type, template structures
+# Get list of all layout files
+bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null)
+
+# Load each layout template file
+FOR each layout_file in layout_files:
+    template_data = Read(layout_file)
+    # Extract: target, variant_id, device_type, dom_structure, css_layout_rules
+
+# Aggregate: targets[], layout_variants count, device_type, all template structures
 ```
 
 **Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
@@ -74,30 +99,97 @@ ELSE:
 
 ## Phase 2: Assembly (Agent)
 
-**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
+**Executor**: `Task(ui-design-agent)` grouped by `target × style` (max 10 layouts per agent, max 6 concurrent agents)
 
-### Step 1: Launch Assembly Tasks
-```bash
-bash(mkdir -p {base_path}/prototypes)
+**⚠️ Core Principle**: **Each agent processes ONLY ONE style** (but can process multiple layouts for that style)
+
+### Agent Grouping Strategy
+
+**Grouping Rules**:
+1. **Style Isolation**: Each agent processes ONLY ONE style (never mixed)
+2. **Balanced Distribution**: Layouts evenly split (e.g., 12→6+6, not 10+2)
+3. **Target Separation**: Different targets use different agents
+
+**Distribution Formula**:
+```
+agents_needed = ceil(layout_count / MAX_LAYOUTS_PER_AGENT)
+base_count = floor(layout_count / agents_needed)
+remainder = layout_count % agents_needed
+# First 'remainder' agents get (base_count + 1), others get base_count
 ```
 
-For each `target × style_id × layout_id`:
+**Examples** (MAX=10):
+
+| Scenario | Result | Explanation |
+|----------|--------|-------------|
+| 3 styles × 3 layouts | 3 agents | Each style: 1 agent (3 layouts) |
+| 3 styles × 12 layouts | 6 agents | Each style: 2 agents (6+6 layouts) |
+| 2 styles × 5 layouts × 2 targets | 4 agents | Each (target, style): 1 agent (5 layouts) |
+
+### Step 1: Calculate Agent Grouping Plan
+```bash
+bash(mkdir -p {base_path}/prototypes)
+
+MAX_LAYOUTS_PER_AGENT = 10
+MAX_PARALLEL = 6
+
+agent_groups = []
+FOR each target in targets:
+  FOR each style_id in [1..S]:
+    layouts_for_this_target_style = filter layouts by current target
+    layout_count = len(layouts_for_this_target_style)
+
+    # Balanced distribution (e.g., 12 layouts → 6+6)
+    agents_needed = ceil(layout_count / MAX_LAYOUTS_PER_AGENT)
+    base_count = floor(layout_count / agents_needed)
+    remainder = layout_count % agents_needed
+
+    layout_chunks = []
+    start_idx = 0
+    FOR i in range(agents_needed):
+      chunk_size = base_count + 1 if i < remainder else base_count
+      layout_chunks.append(layouts[start_idx : start_idx + chunk_size])
+      start_idx += chunk_size
+
+    FOR each chunk in layout_chunks:
+      agent_groups.append({
+        target: target,           # Single target
+        style_id: style_id,       # Single style
+        layout_ids: chunk         # Balanced layouts (≤10)
+      })
+
+total_agents = len(agent_groups)
+total_batches = ceil(total_agents / MAX_PARALLEL)
+
+TodoWrite({todos: [
+  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
+  {content: "Batch 1/{total_batches}: Assemble up to 6 agent groups", status: "in_progress", activeForm: "Assembling batch 1"},
+  {content: "Batch 2/{total_batches}: Assemble up to 6 agent groups", status: "pending", activeForm: "Assembling batch 2"},
+  ... (continue for all batches)
+]})
+```
+
+### Step 2: Launch Batched Assembly Tasks
+
+For each batch (up to 6 parallel agents per batch):
+For each agent group `{target, style_id, layout_ids[]}` in current batch:
 ```javascript
 Task(ui-design-agent): `
   [LAYOUT_STYLE_ASSEMBLY]
-  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
-  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
+  🎯 {target} × Style-{style_id} × Layouts-{layout_ids}
+  ⚠️ CONSTRAINT: Use ONLY style-{style_id}/design-tokens.json (never mix styles)
 
-  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
+  TARGET: {target} | STYLE: {style_id} | LAYOUTS: {layout_ids} (max 10)
   BASE_PATH: {base_path}
 
   ## Inputs (READ ONLY - NO DESIGN DECISIONS)
-  1. Layout Template:
-     Read("{base_path}/layout-extraction/layout-templates.json")
-     Find template where: target={target} AND variant_id="layout-{layout_id}"
-     Extract: dom_structure, css_layout_rules, device_type, source_image_path
+  1. Layout Templates (LOOP THROUGH):
+     FOR each layout_id in layout_ids:
+       Read("{base_path}/layout-extraction/layout-{target}-{layout_id}.json")
+       This file contains the specific layout template for this target and variant.
+       Extract: dom_structure, css_layout_rules, device_type, source_image_path (from template field)
 
-  2. Design Tokens:
+  2. Design Tokens (SHARED - READ ONCE):
      Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
      Extract: ALL token values including:
        * colors, typography (with combinations), spacing, opacity
@@ -121,61 +213,70 @@ Task(ui-design-agent): `
      ELSE:
        Use generic placeholder content
 
-  ## Assembly Process
-  1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
-     - Recursively build from template.dom_structure
-     - Add: <!DOCTYPE html>, <head>, <meta viewport>
-     - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
-     - Inject placeholder content:
-       * Default: Use Lorem ipsum, generic sample data
-       * If reference image available: Generate more contextually appropriate placeholders
-         (e.g., realistic headings, meaningful text snippets that match the visual context)
-     - Preserve all attributes from dom_structure
+  ## Assembly Process (LOOP FOR EACH LAYOUT)
+  FOR each layout_id in layout_ids:
 
-  2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
-     - Start with template.css_layout_rules
-     - Replace ALL var(--*) with actual token values from design-tokens.json
-       Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
-       Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
-       Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
-     - Add visual styling using design tokens:
-       * Colors: tokens.colors.*
-       * Typography: tokens.typography.* (including combinations)
-       * Opacity: tokens.opacity.*
-       * Shadows: tokens.shadows.*
-       * Border radius: tokens.border_radius.*
-     - IF tokens.component_styles exists: Add component style classes
-       * Generate classes for button variants (.btn-primary, .btn-secondary)
-       * Generate classes for card variants (.card-default, .card-interactive)
-       * Generate classes for input variants (.input-default, .input-focus, .input-error)
-       * Use var() references that resolve to actual token values
-     - IF tokens.typography.combinations exists: Add typography preset classes
-       * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
-       * Use var() references for family, size, weight, line-height, letter-spacing
-     - IF has_animations == true: Inject animation tokens
-       * Add CSS Custom Properties for animations at :root level:
-         --duration-instant, --duration-fast, --duration-normal, etc.
-         --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
+    1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
+       - Recursively build from template.dom_structure
+       - Add: <!DOCTYPE html>, <head>, <meta viewport>
+       - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
+       - Inject placeholder content:
+         * Default: Use Lorem ipsum, generic sample data
+         * If reference image available: Generate more contextually appropriate placeholders
+           (e.g., realistic headings, meaningful text snippets that match the visual context)
+       - Preserve all attributes from dom_structure
+
+    2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
+       - Start with template.css_layout_rules
+       - Replace ALL var(--*) with actual token values from design-tokens.json
+         Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
+         Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+         Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
+       - Add visual styling using design tokens:
+         * Colors: tokens.colors.*
+         * Typography: tokens.typography.* (including combinations)
+         * Opacity: tokens.opacity.*
+         * Shadows: tokens.shadows.*
+         * Border radius: tokens.border_radius.*
+       - IF tokens.component_styles exists: Add component style classes
+         * Generate classes for button variants (.btn-primary, .btn-secondary)
+         * Generate classes for card variants (.card-default, .card-interactive)
+         * Generate classes for input variants (.input-default, .input-focus, .input-error)
+         * Use var() references that resolve to actual token values
+       - IF tokens.typography.combinations exists: Add typography preset classes
+         * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
+         * Use var() references for family, size, weight, line-height, letter-spacing
+       - IF has_animations == true: Inject animation tokens (ONCE, shared across layouts)
+         * 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
+
+    3. Write files IMMEDIATELY after each layout completes
 
   ## Assembly Rules
-  - ✅ Pure assembly: Combine existing structure + existing style
-  - ❌ NO layout design decisions (structure pre-defined)
-  - ❌ NO style design decisions (tokens pre-defined)
+  - ✅ Pure assembly: Combine pre-extracted structure + tokens
+  - ❌ NO design decisions (layout/style pre-defined)
+  - ✅ Read tokens ONCE, apply to all layouts in this batch
   - ✅ Replace var() with actual values
-  - ✅ Add placeholder content only
-  - Write files IMMEDIATELY
-  - CSS filename MUST match HTML <link href="...">
+  - ✅ CSS filename MUST match HTML <link href="...">
+
+  ## Output
+  - Files: {len(layout_ids) × 2} (HTML + CSS pairs)
+  - Each layout generates 2 files independently
 `
+
+# After each batch completes
+TodoWrite: Mark current batch completed, next batch in_progress
 ```
 
-### Step 2: Verify Generated Files
+### Step 3: Verify Generated Files
 ```bash
-# Count expected vs found
+# Count expected vs found (should equal S × L × T)
 bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
 
 # Validate samples
@@ -183,7 +284,7 @@ Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
 # Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
 ```
 
-**Output**: `S × L × T × 2` files verified
+**Output**: `total_files = S × L × T × 2` files verified (HTML + CSS pairs)
 
 ## Phase 3: Generate Preview Files
 
@@ -210,10 +311,10 @@ bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {b
 ```javascript
 TodoWrite({todos: [
   {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
-  {content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
-  {content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
-  {content: "Verify files", status: "completed", activeForm: "Validating output"},
-  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
+  {content: "Batch 1/{total_batches}: Assemble 6 tasks", status: "completed", activeForm: "Assembling batch 1"},
+  {content: "Batch 2/{total_batches}: Assemble 6 tasks", status: "completed", activeForm: "Assembling batch 2"},
+  ... (all batches completed)
+  {content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
 ]});
 ```
 
@@ -223,33 +324,41 @@ TodoWrite({todos: [
 
 Configuration:
 - Style Variants: {style_variants}
-- Layout Variants: {layout_variants} (from layout-templates.json)
+- Layout Variants: {layout_variants} (from layout-*.json files)
 - Device Type: {device_type}
 - Targets: {targets}
 - Total Prototypes: {S × L × T}
 - Image Reference: Auto-detected (uses source images when available in layout templates)
+- Animation Support: {has_animations ? 'Enabled (animation-tokens.json loaded)' : 'Not available'}
 
 Assembly Process:
 - Pure assembly: Combined pre-extracted layouts + design tokens
-- No design decisions: All structure and style pre-defined
-- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations
+- Agent grouping: target × style (max 10 layouts per agent)
+- Balanced distribution: Layouts evenly split (e.g., 12 → 6+6, not 10+2)
+
+Batch Execution:
+- Total agents: {total_agents} (each processes ONE style only)
+- Batches: {total_batches} (max 6 agents parallel)
+- Token efficiency: Read once per agent, apply to all layouts
 
 Quality:
 - Structure: From layout-extract (DOM, CSS layout rules)
 - Style: From style-extract (design tokens)
 - CSS: Token values directly applied (var() replaced)
 - Device-optimized: Layouts match device_type from templates
+- Animations: {has_animations ? 'CSS custom properties and @keyframes injected' : 'Static styles only'}
 
 Generated Files:
 {base_path}/prototypes/
-├── _templates/
-│   └── layout-templates.json (input, pre-extracted)
 ├── {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)
 
+Input Files (from layout-extraction/):
+├── layout-{target}-{variant}.json (multiple files, one per target-variant combination)
+
 Preview:
 1. Open compare.html (recommended)
 2. Open index.html
@@ -263,7 +372,7 @@ Next: /workflow:ui-design:update
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Count style variants
 bash(ls {base_path}/style-extraction/style-* -d | wc -l)
@@ -271,8 +380,11 @@ bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 
 ### Validation Commands
 ```bash
-# Check layout templates exist
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# Check layout templates exist (multi-file pattern)
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
+
+# Count layout files
+bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
 
 # Check design tokens exist
 bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
@@ -298,10 +410,10 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 ```
 {base_path}/
 ├── layout-extraction/
-│   └── layout-templates.json      # Input (from layout-extract)
+│   └── layout-{target}-{variant}.json  # Input (multiple files from layout-extract)
 ├── style-extraction/
 │   └── style-{s}/
-│       ├── design-tokens.json     # Input (from style-extract)
+│       ├── design-tokens.json          # Input (from style-extract)
 │       └── style-guide.md
 └── prototypes/
     ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
@@ -330,7 +442,7 @@ ERROR: Script permission denied
 
 ### Recovery Strategies
 - **Partial success**: Keep successful assembly combinations
-- **Invalid template structure**: Validate layout-templates.json
+- **Invalid template structure**: Validate layout-*.json files
 - **Invalid tokens**: Validate design-tokens.json structure
 
 ## Quality Checklist
@@ -346,18 +458,17 @@ ERROR: Script permission denied
 ## Key Features
 
 - **Pure Assembly**: No design decisions, only combination
-- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
-- **Token Resolution**: var() placeholders replaced with actual values
-- **Pre-validated**: Inputs already validated by extract/consolidate
-- **Efficient**: Simple assembly vs complex generation
+- **Token Resolution**: var() → actual values
+- **Efficient Grouping**: target × style (max 10 layouts/agent, balanced split)
+- **Style Isolation**: Each agent processes ONE style only
 - **Production-Ready**: Semantic, accessible, token-driven
 
 ## Integration
 
 **Prerequisites**:
 - `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
-- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+- `/workflow:ui-design:layout-extract` → `layout-{target}-{variant}.json` files
 
-**Input**: `layout-templates.json` + `design-tokens.json`
+**Input**: `layout-*.json` files + `design-tokens.json`
 **Output**: S×L×T prototypes for `/workflow:ui-design:update`
 **Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`

.claude/skills/command-guide/reference/commands/workflow/ui-design/imitate-auto.md

@@ -1,7 +1,7 @@
 ---
 name: imitate-auto
-description: High-speed multi-page UI replication with batch screenshot capture and design token extraction
-argument-hint: --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--prompt "<desc>"]
+description: UI design workflow with direct code/image input for design token extraction and prototype generation
+argument-hint: "[--input "<value>"] [--session <id>]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 ---
 
@@ -9,79 +9,85 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 
 ## Overview & Execution Model
 
-**Fully autonomous replication orchestrator**: Efficiently replicate multiple web pages through sequential execution from screenshot capture to design integration.
+**Fully autonomous design orchestrator**: Efficiently create UI prototypes through sequential execution from design token extraction to system integration.
 
-**Dual Capture Strategy**: Supports two capture modes for different use cases:
-- **Batch Mode** (default): Fast multi-URL screenshot capture via `/workflow:ui-design:capture`
-- **Deep Mode**: Interactive layer exploration for single URL via `/workflow:ui-design:explore-layers`
+**Direct Input Strategy**: Accepts local code files and images:
+- **Code Files**: Detect file paths in `--prompt` parameter
+- **Images**: Reference images via `--images` glob pattern
+- **Hybrid**: Combine both code and visual inputs
 
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
-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 (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
+1. User triggers: `/workflow:ui-design:imitate-auto [--input "..."]`
+2. Phase 0: Initialize and detect input sources
+3. Phase 2: Style extraction → **Attach tasks → Execute → Collapse** → Auto-continues
+4. Phase 2.3: Animation extraction → **Attach tasks → Execute → Collapse** → Auto-continues
+5. Phase 2.5: Layout extraction → **Attach tasks → Execute → Collapse** → Auto-continues
+6. Phase 3: Batch UI assembly → **Attach tasks → Execute → Collapse** → Auto-continues
+7. Phase 4: Design system integration → **Execute orchestrator task** → Reports completion
 
 **Phase Transition Mechanism**:
-- `SlashCommand` is BLOCKING - execution pauses until completion
-- Upon each phase completion: Automatically process output and execute next phase
+- **Task Attachment**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
+- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
+- **Task Collapse**: After tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing
 - No user interaction required after initial parameter parsing
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 5.
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 4.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
 
 ## Core Rules
 
-1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+1. **Start Immediately**: TodoWrite initialization → Phase 2 execution
 2. **No Preliminary Validation**: Sub-commands handle their own validation
 3. **Parse & Pass**: Extract data from each output for next phase
-4. **Track Progress**: Update TodoWrite after each phase
-5. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 5.
+4. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+5. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 4.
 
 ## Parameter Requirements
 
-**Required Parameters**:
-- `--url-map "<map>"`: Target page mapping
-  - Format: `"target1:url1, target2:url2, ..."`
-  - Example: `"home:https://linear.app, pricing:https://linear.app/pricing"`
-  - First target serves as primary style source
+**Recommended Parameter**:
+- `--input "<value>"`: Unified input source (auto-detects type)
+  - **Glob pattern** (images): `"design-refs/*"`, `"screenshots/*.png"`
+  - **File/directory path** (code): `"./src/components"`, `"/path/to/styles"`
+  - **Text description** (prompt): `"Focus on dark mode"`, `"Emphasize minimalist design"`
+  - **Combination**: `"design-refs/* modern dashboard style"` (glob + description)
+  - Multiple inputs: Separate with `|` → `"design-refs/*|modern style"`
+
+**Detection Logic**:
+- Contains `*` or matches existing files → **glob pattern** (images)
+- Existing file/directory path → **code import**
+- Pure text without paths → **design prompt**
+- Contains `|` separator → **multiple inputs** (glob|prompt or path|prompt)
+
+**Legacy Parameters** (deprecated, use `--input` instead):
+- `--images "<glob>"`: Reference image paths (shows deprecation warning)
+- `--prompt "<desc>"`: Design description (shows deprecation warning)
 
 **Optional Parameters**:
-- `--capture-mode <batch|deep>` (Optional, default: batch): Screenshot capture strategy
-  - `batch` (default): Multi-URL fast batch capture via `/workflow:ui-design:capture`
-  - `deep`: Single-URL interactive depth exploration via `/workflow:ui-design:explore-layers`
-  - **Note**: `deep` mode only uses first URL from url-map
-
-- `--depth <1-5>` (Optional, default: 3): Capture depth for deep mode
-  - `1`: Page level (full-page screenshot)
-  - `2`: Element level (+ key components)
-  - `3`: Interaction level (+ modals, dropdowns)
-  - `4`: Embedded level (+ iframes)
-  - `5`: Shadow DOM (+ web components)
-  - **Only applies when** `--capture-mode deep`
-
-- `--session <id>` (Optional): Workflow session ID
+- `--session <id>`: Workflow session ID
   - Integrate into existing session (`.workflow/WFS-{session}/`)
-  - Enable automatic design system integration (Phase 5)
-  - If not provided: standalone mode (`.workflow/.design/`)
+  - Enable automatic design system integration (Phase 4)
+  - If not provided: standalone mode (`.workflow/`)
 
-- `--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)
+**Input Rules**:
+- Must provide: `--input` OR (legacy: `--images`/`--prompt`)
+- `--input` can combine multiple input types
+- File paths are automatically detected and trigger code import
 
 ## Execution Modes
 
-**Capture Modes**:
-- **Batch Mode** (default): Multi-URL screenshot capture for fast replication
-  - Uses `/workflow:ui-design:capture` for parallel screenshot capture
-  - Optimized for replicating multiple pages efficiently
-- **Deep Mode**: Single-URL layer exploration for detailed analysis
-  - Uses `/workflow:ui-design:explore-layers` for interactive depth traversal
-  - Captures page layers at different depths (1-5)
-  - Only processes first URL from url-map
+**Input Sources**:
+- **Code Files**: Automatically detected from `--prompt` file paths
+  - Triggers `/workflow:ui-design:import-from-code` for token extraction
+  - Analyzes existing CSS/JS/HTML files
+- **Visual Input**: Images via `--images` glob pattern
+  - Reference images for style extraction
+  - Screenshots or design mockups
+- **Hybrid Mode**: Combines code import with visual supplements
+  - Code provides base tokens
+  - Images supplement missing design elements
 
 **Token Processing**:
 - **Direct Generation**: Complete design systems generated in style-extract phase
@@ -92,123 +98,134 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
 **Session Integration**:
 - `--session` flag determines session integration or standalone execution
 - Integrated: Design system automatically added to session artifacts
-- Standalone: Output in `.workflow/.design/{run_id}/`
+- Standalone: Output in `.workflow/{run_id}/`
 
-## 6-Phase Execution
+## 5-Phase Execution
 
-### Phase 0: Initialization and Target Parsing
+### Phase 0: Parameter Parsing & Input Detection
 
 ```bash
-# Generate run ID
-run_id = "run-$(date +%Y%m%d-%H%M%S)"
+# Step 0: Parse and normalize parameters
+images_input = null
+prompt_text = null
 
-# Determine base path and session mode
-IF --session:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/design-{run_id}"
-    session_mode = "integrated"
-ELSE:
-    session_id = null
-    base_path = ".workflow/.design/{run_id}"
-    session_mode = "standalone"
+# Handle legacy parameters with deprecation warning
+IF --images OR --prompt:
+    WARN: "⚠️  DEPRECATION: --images and --prompt are deprecated. Use --input instead."
+    WARN: "   Example: --input \"design-refs/*\" or --input \"modern dashboard\""
+    images_input = --images
+    prompt_text = --prompt
 
-# Create base directory
-Bash(mkdir -p "{base_path}")
+# Parse unified --input parameter
+IF --input:
+    # Split by | separator for multiple inputs
+    input_parts = split(--input, "|")
 
-# Step 0.1: Intelligent Path Detection
+    FOR part IN input_parts:
+        part = trim(part)
+
+        # Detection logic
+        IF contains(part, "*") OR glob_matches_files(part):
+            # Glob pattern detected → images
+            images_input = part
+        ELSE IF file_or_directory_exists(part):
+            # File/directory path → will be handled in code detection
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+        ELSE:
+            # Pure text → prompt
+            IF NOT prompt_text:
+                prompt_text = part
+            ELSE:
+                prompt_text = prompt_text + " " + part
+
+# Validation
+IF NOT images_input AND NOT prompt_text:
+    ERROR: "No input provided. Use --input with glob pattern, file path, or text description"
+    EXIT 1
+
+# Step 1: Detect design source from parsed inputs
 code_files_detected = false
 code_base_path = null
-design_source = "web"  # Default for imitate-auto
+has_visual_input = false
 
-IF --prompt:
+IF prompt_text:
     # Extract potential file paths from prompt
-    potential_paths = extract_paths_from_text(--prompt)
+    potential_paths = extract_paths_from_text(prompt_text)
     FOR path IN potential_paths:
         IF file_or_directory_exists(path):
             code_files_detected = true
             code_base_path = path
-            design_source = "hybrid"  # Web + Code
             BREAK
 
-STORE: design_source, code_base_path
+IF images_input:
+    # Check if images parameter points to existing files
+    IF glob_matches_files(images_input):
+        has_visual_input = true
 
-# Parse url-map
-url_map_string = {--url-map}
-VALIDATE: url_map_string is not empty, "--url-map parameter is required"
-
-# Parse target:url pairs
-url_map = {}  # {target_name: url}
-target_names = []
-
-FOR pair IN split(url_map_string, ","):
-    pair = pair.strip()
-
-    IF ":" NOT IN pair:
-        ERROR: "Invalid url-map format: '{pair}'"
-        ERROR: "Expected format: 'target:url'"
-        ERROR: "Example: 'home:https://example.com, pricing:https://example.com/pricing'"
-        EXIT 1
-
-    target, url = pair.split(":", 1)
-    target = target.strip().lower().replace(" ", "-")
-    url = url.strip()
-
-    url_map[target] = url
-    target_names.append(target)
-
-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
-
-# Parse capture mode
-capture_mode = --capture-mode OR "batch"
-depth = int(--depth OR 3)
-
-# Validate capture mode
-IF capture_mode NOT IN ["batch", "deep"]:
-    ERROR: "Invalid --capture-mode: {capture_mode}"
-    ERROR: "Valid options: batch, deep"
+# Step 2: Determine design source strategy
+design_source = "unknown"
+IF code_files_detected AND has_visual_input:
+    design_source = "hybrid"  # Both code and visual
+ELSE IF code_files_detected:
+    design_source = "code_only"  # Only code files
+ELSE IF has_visual_input OR --prompt:
+    design_source = "visual_only"  # Only visual/prompt
+ELSE:
+    ERROR: "No design source provided (code files, images, or prompt required)"
     EXIT 1
 
-# Validate depth (only for deep mode)
-IF capture_mode == "deep":
-    IF depth NOT IN [1, 2, 3, 4, 5]:
-        ERROR: "Invalid --depth: {depth}"
-        ERROR: "Valid range: 1-5"
-        EXIT 1
+STORE: design_source, code_base_path, has_visual_input
 
-    # Warn if multiple URLs in deep mode
-    IF len(target_names) > 1:
-        WARN: "⚠️ Deep mode only uses first URL: '{primary_target}'"
-        WARN: "   Other URLs will be ignored: {', '.join(target_names[1:])}"
-        WARN: "   For multi-URL, use --capture-mode batch"
+# Step 3: Initialize directories
+design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
+
+IF --session:
+    session_id = {provided_session}
+    relative_base_path = ".workflow/WFS-{session_id}/{design_id}"
+    session_mode = "integrated"
+ELSE:
+    session_id = null
+    relative_base_path = ".workflow/{design_id}"
+    session_mode = "standalone"
+
+# Create base directory and convert to absolute path
+Bash(mkdir -p "{relative_base_path}")
+base_path=$(cd "{relative_base_path}" && pwd)
 
 # Write metadata
 metadata = {
     "workflow": "imitate-auto",
-    "run_id": run_id,
+    "run_id": design_id,
     "session_id": session_id,
     "timestamp": current_timestamp(),
     "parameters": {
-        "url_map": url_map,
-        "capture_mode": capture_mode,
-        "depth": depth IF capture_mode == "deep" ELSE null,
-        "prompt": --prompt OR null
+        "design_source": design_source,
+        "code_base_path": code_base_path,
+        "images": images_input OR null,
+        "prompt": prompt_text OR null,
+        "input": --input OR null  # Store original --input for reference
     },
-    "targets": target_names,
     "status": "in_progress"
 }
 
 Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
 
+# Initialize default flags
+animation_complete = false
+needs_visual_supplement = false
+style_complete = false
+layout_complete = false
+
 # 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: "Initialize and detect design source", status: "completed", activeForm: "Initializing"},
   {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: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
+  {content: "Assemble UI prototypes", status: "pending", activeForm: "Assembling UI"},
   {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
 ]})
 ```
@@ -224,10 +241,14 @@ IF design_source == "hybrid":
     REPORT: "   → Source: {code_base_path}"
     REPORT: "   → Mode: Hybrid (Web + Code)"
 
-    command = "/workflow:ui-design:import-from-code --base-path \"{base_path}\" " +
-              "--base-path \"{code_base_path}\""
+    command = "/workflow:ui-design:import-from-code --design-id \"{design_id}\" " +
+              "--source \"{code_base_path}\""
 
     TRY:
+        # SlashCommand invocation ATTACHES import-from-code's tasks to current workflow
+        # Orchestrator will EXECUTE these attached tasks itself:
+        #   - Phase 0: Discover and categorize code files
+        #   - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
         SlashCommand(command)
     CATCH error:
         WARN: "Code import failed: {error}"
@@ -238,7 +259,8 @@ IF design_source == "hybrid":
         # Check file existence and assess completeness
         style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
         animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
-        layout_exists = exists("{base_path}/layout-extraction/layout-templates.json")
+        layout_count = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
+        layout_exists = (layout_count > 0)
 
         style_complete = false
         animation_complete = false
@@ -274,14 +296,16 @@ IF design_source == "hybrid":
 
         # Layout completeness check
         IF layout_exists:
-            layouts = Read("{base_path}/layout-extraction/layout-templates.json")
+            # Read first layout file to verify structure
+            first_layout = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | head -1)
+            layout_data = Read(first_layout)
             layout_complete = (
-                layouts.layout_templates?.length >= 3 &&
-                layouts.extraction_metadata?.layout_system?.type &&
-                layouts.extraction_metadata?.responsive?.breakpoints
+                layout_count >= 1 &&
+                layout_data.template?.dom_structure &&
+                layout_data.template?.css_layout_rules
             )
-            IF NOT layout_complete AND layouts.extraction_metadata?.completeness?.missing_items:
-                missing_categories.extend(layouts.extraction_metadata.completeness.missing_items)
+            IF NOT layout_complete:
+                missing_categories.push("complete layout structure")
         ELSE:
             missing_categories.push("layout templates")
 
@@ -306,148 +330,120 @@ IF design_source == "hybrid":
 
         STORE: style_complete, animation_complete, layout_complete
 
-TodoWrite(mark_completed: "Initialize and parse url-map",
-          mark_in_progress: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})")
-```
-
-### Phase 1: Screenshot Capture (Dual Mode)
-
-```bash
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "🚀 Phase 1: Screenshot Capture"
-IF design_source == "hybrid":
-    REPORT: "   → Purpose: Verify and supplement code analysis"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-
-IF capture_mode == "batch":
-    # Mode A: Batch Multi-URL Capture
-    url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
-    capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
-
-    TRY:
-        SlashCommand(capture_command)
-    CATCH error:
-        ERROR: "Batch capture failed: {error}"
-        ERROR: "Cannot proceed without screenshots"
-        EXIT 1
-
-    # Verify batch capture results
-    screenshot_metadata_path = "{base_path}/screenshots/capture-metadata.json"
-
-    IF NOT exists(screenshot_metadata_path):
-        ERROR: "capture command did not generate metadata file"
-        ERROR: "Expected: {screenshot_metadata_path}"
-        EXIT 1
-
-    screenshot_metadata = Read(screenshot_metadata_path)
-    captured_count = screenshot_metadata.total_captured
-    total_requested = screenshot_metadata.total_requested
-    missing_count = total_requested - captured_count
-
-    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)}"
-
-    IF captured_count == 0:
-        ERROR: "No screenshots captured - cannot proceed"
-        EXIT 1
-
-ELSE:  # capture_mode == "deep"
-    # Mode B: Deep Interactive Layer Exploration
-    primary_url = url_map[primary_target]
-    explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
-
-    TRY:
-        SlashCommand(explore_command)
-    CATCH error:
-        ERROR: "Deep exploration failed: {error}"
-        ERROR: "Cannot proceed without screenshots"
-        EXIT 1
-
-    # Verify deep exploration results
-    layer_map_path = "{base_path}/screenshots/layer-map.json"
-
-    IF NOT exists(layer_map_path):
-        ERROR: "explore-layers did not generate layer-map.json"
-        ERROR: "Expected: {layer_map_path}"
-        EXIT 1
-
-    layer_map = Read(layer_map_path)
-    captured_count = layer_map.summary.total_captures
-    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})",
-          mark_in_progress: "Extract style (visual tokens)")
+TodoWrite(mark_completed: "Initialize and detect design source",
+          mark_in_progress: "Extract style (complete design systems)")
 ```
 
 ### Phase 2: Style Extraction
 
 ```bash
 # Determine if style extraction needed
-skip_style = (design_source == "hybrid" AND style_complete)
+skip_style = (design_source == "code_only" AND style_complete)
 
 IF skip_style:
     REPORT: "✅ Phase 2: Style (Using Code Import)"
 ELSE:
     REPORT: "🚀 Phase 2: Style Extraction"
-    IF capture_mode == "batch":
-        images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
-    ELSE:
-        images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"
 
-    IF --prompt:
-        extraction_prompt = f"Extract visual style tokens from '{primary_target}'. {--prompt}"
-    ELSE:
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:style-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        extraction_prompt = prompt_text
         IF design_source == "hybrid":
-            extraction_prompt = f"Extract visual style tokens from '{primary_target}' to supplement code-imported design tokens."
-        ELSE:
-            extraction_prompt = f"Extract visual style tokens from '{primary_target}' with consistency across all pages."
+            extraction_prompt = f"{prompt_text} (supplement code-imported tokens)"
+        command_parts.append(f"--prompt \"{extraction_prompt}\"")
 
-    url_map_for_extract = ",".join([f"{name}:{url}" for name, url in url_map.items()])
-    extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_extract}\" --prompt \"{extraction_prompt}\" --mode imitate"
+    command_parts.extend(["--variants 1", "--refine", "--interactive"])
+
+    extract_command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES style-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(extract_command)
 
-TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation")
+    # After executing all attached tasks, collapse them into phase summary
+    TodoWrite(mark_completed: "Extract style", mark_in_progress: "Extract animation")
 ```
 
 ### Phase 2.3: Animation Extraction
 
 ```bash
-skip_animation = (design_source == "hybrid" AND animation_complete)
+skip_animation = (design_source == "code_only" AND animation_complete)
 
 IF skip_animation:
     REPORT: "✅ Phase 2.3: Animation (Using Code Import)"
 ELSE:
     REPORT: "🚀 Phase 2.3: Animation Extraction"
-    url_map_for_animation = ",".join([f"{target}:{url}" for target, url in url_map.items()])
-    animation_extract_command = f"/workflow:ui-design:animation-extract --base-path \"{base_path}\" --urls \"{url_map_for_animation}\" --mode auto"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:animation-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    command_parts.extend(["--refine", "--interactive"])
+
+    animation_extract_command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES animation-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(animation_extract_command)
 
+    # After executing all attached tasks, collapse them into phase summary
+    TodoWrite(mark_completed: "Extract animation", mark_in_progress: "Extract layout")
 ```
 
 ### Phase 2.5: Layout Extraction
 
 ```bash
-skip_layout = (design_source == "hybrid" AND layout_complete)
+skip_layout = (design_source == "code_only" AND layout_complete)
 
 IF skip_layout:
     REPORT: "✅ Phase 2.5: Layout (Using Code Import)"
 ELSE:
     REPORT: "🚀 Phase 2.5: Layout Extraction"
-    url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
-    layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --urls \"{url_map_for_layout}\" --targets \"{','.join(target_names)}\" --mode imitate"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:layout-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    # Default target if not specified
+    command_parts.append("--targets \"home\"")
+    command_parts.extend(["--variants 1", "--refine", "--interactive"])
+
+    layout_extract_command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES layout-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(layout_extract_command)
 
-TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI")
+    # After executing all attached tasks, collapse them into phase summary
+    TodoWrite(mark_completed: "Extract layout", mark_in_progress: "Assemble UI")
 ```
 
 ### Phase 3: UI Assembly
 
 ```bash
 REPORT: "🚀 Phase 3: UI Assembly"
-generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"
+generate_command = f"/workflow:ui-design:generate --design-id \"{design_id}\""
+
+# SlashCommand invocation ATTACHES generate's tasks to current workflow
+# Orchestrator will EXECUTE these attached tasks itself
 SlashCommand(generate_command)
 
+# After executing all attached tasks, collapse them into phase summary
 TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integrate design system" : "Completion")
 ```
 
@@ -457,6 +453,9 @@ TodoWrite(mark_completed: "Assemble UI", mark_in_progress: session_id ? "Integra
 IF session_id:
     REPORT: "🚀 Phase 4: Design System Integration"
     update_command = f"/workflow:ui-design:update --session {session_id}"
+
+    # SlashCommand invocation ATTACHES update's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
     SlashCommand(update_command)
 
 # Update metadata
@@ -486,7 +485,7 @@ TodoWrite({todos: [
 ]})
 ```
 
-### Phase 6: Completion Report
+### Phase 4: Completion Report
 
 **Completion Message**:
 ```
@@ -496,26 +495,24 @@ TodoWrite({todos: [
 
 ━━━ 📊 Workflow Summary ━━━
 
-Mode: {capture_mode == "batch" ? "Batch Multi-Page Replication" : f"Deep Interactive Exploration (depth {depth})"}
+Mode: Direct Input ({design_source})
 Session: {session_id or "standalone"}
 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 0 - Input Detection: ✅ {design_source} mode
+  {IF design_source == "code_only": "Code files imported" ELSE IF design_source == "hybrid": "Code + visual inputs" ELSE: "Visual inputs"}
 
 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 2.3 - Animation Extraction: ✅ CSS animations and transitions
+Phase 2.3 - Animation Extraction: ✅ Animation tokens
   Output: animation-extraction/ (animation-tokens.json + animation-guide.md)
-  Method: Auto-extracted from live URLs via Chrome DevTools
 
 Phase 2.5 - Layout Extraction: ✅ Structure templates
   Templates: {template_count} layout structures
 
-Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
-  Targets: {', '.join(target_names)}
+Phase 3 - UI Assembly: ✅ {generated_count} prototypes assembled
   Configuration: 1 style × 1 layout × {generated_count} pages
 
 Phase 4 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
@@ -523,20 +520,6 @@ Phase 4 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭
 ━━━ 📂 Output Structure ━━━
 
 {base_path}/
-├── screenshots/                    # {captured_count} screenshots
-{IF capture_mode == "batch":
-│   ├── {target1}.png
-│   ├── {target2}.png
-│   └── capture-metadata.json
-ELSE:
-│   ├── depth-1/
-│   │   └── full-page.png
-│   ├── depth-2/
-│   │   └── {elements}.png
-│   ├── depth-{depth}/
-│   │   └── {layers}.png
-│   └── layer-map.json
-}
 ├── style-extraction/               # Production-ready design systems
 │   └── style-1/
 │       ├── design-tokens.json
@@ -545,19 +528,18 @@ ELSE:
 │   ├── animation-tokens.json
 │   └── animation-guide.md
 ├── layout-extraction/              # Structure templates
-│   └── layout-templates.json
+│   └── layout-home-1.json          # Layout templates
 └── prototypes/                     # {generated_count} HTML/CSS files
-    ├── {target1}-style-1-layout-1.html + .css
-    ├── {target2}-style-1-layout-1.html + .css
+    ├── home-style-1-layout-1.html + .css
     ├── compare.html                # Interactive preview
     └── index.html                  # Quick navigation
 
 ━━━ ⚡ Performance ━━━
 
 Total workflow time: ~{estimate_total_time()} minutes
-  Screenshot capture: ~{capture_time}
   Style extraction: ~{extract_time}
-  Token processing: ~{token_processing_time}
+  Animation extraction: ~{animation_time}
+  Layout extraction: ~{layout_time}
   UI generation: ~{generate_time}
 
 ━━━ 🌐 Next Steps ━━━
@@ -586,103 +568,81 @@ ELSE:
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution
+// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution (6 orchestrator-level tasks)
 TodoWrite({todos: [
-  {content: "Initialize and parse url-map", status: "in_progress", activeForm: "Initializing"},
-  {content: "Batch screenshot capture", status: "pending", activeForm: "Capturing screenshots"},
+  {content: "Initialize and detect design source", status: "in_progress", activeForm: "Initializing"},
   {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: "Assemble UI for all targets", status: "pending", activeForm: "Assembling UI"},
+  {content: "Assemble UI prototypes", status: "pending", activeForm: "Assembling UI"},
   {content: "Integrate design system", status: "pending", activeForm: "Integrating"}
 ]})
 
-// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
-// 1. SlashCommand blocks and returns when phase is complete
-// 2. Update current phase: status → "completed"
-// 3. Update next phase: status → "in_progress"
-// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
-// This ensures continuous workflow tracking and prevents premature stopping
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// Phase 2-4 SlashCommand Invocation Pattern:
+// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
+// 2. TodoWrite expands to include attached tasks
+// 3. Orchestrator EXECUTES attached tasks sequentially
+// 4. After all attached tasks complete, COLLAPSE them into phase summary
+// 5. Update next phase to in_progress
+// 6. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+//
+// Benefits:
+// ✓ Real-time visibility into sub-command task progress
+// ✓ Clean orchestrator-level summary after each phase
+// ✓ Clear mental model: SlashCommand = attach tasks, not delegate work
+// ✓ Dynamic attachment/collapse maintains clarity
 ```
 
 ## Error Handling
 
 ### Pre-execution Checks
-- **url-map format validation**: Clear error message with format example
-- **Empty url-map**: Error and exit
-- **Invalid target names**: Regex validation with suggestions
+- **Input validation**: Must provide at least one of --images or --prompt
+- **Design source detection**: Error if no valid inputs found
+- **Code import failure**: Fallback to visual-only mode in hybrid, error in code-only mode
 
 ### Phase-Specific Errors
-- **Screenshot capture failure (Phase 1)**:
-  - If total_captured == 0: Terminate workflow
-  - If partial failure: Warn but continue with available screenshots
+- **Code import failure (Phase 0.5)**:
+  - code_only mode: Terminate with clear error
+  - hybrid mode: Warn and fallback to visual-only mode
 
 - **Style extraction failure (Phase 2)**:
   - If extract fails: Terminate with clear error
-  - If style-cards.json missing: Terminate with debugging info
+  - If design-tokens.json missing: Terminate with debugging info
 
-- **Token processing failure (Phase 3)**:
-  - Consolidate mode: Terminate if consolidate fails
-  - Fast mode: Validate proposed_tokens exist before copying
+- **Animation extraction failure (Phase 2.3)**:
+  - Non-critical: Warn but continue
+  - Can proceed without animation tokens
 
-- **UI generation failure (Phase 4)**:
+- **Layout extraction failure (Phase 2.5)**:
+  - If extract fails: Terminate with error
+  - Need layout templates for assembly
+
+- **UI generation failure (Phase 3)**:
   - If generate fails: Terminate with error
-  - If generated_count < target_count: Warn but proceed
+  - If generated_count < expected: Warn but proceed
 
-- **Integration failure (Phase 5)**:
+- **Integration failure (Phase 4)**:
   - Non-blocking: Warn but don't terminate
   - Prototypes already available
 
 ### Recovery Strategies
-- **Partial screenshot failure**: Continue with available screenshots, list missing in warning
-- **Generate failure**: Report specific target failures, user can re-generate individually
+- **Code import failure**: Automatic fallback to visual-only in hybrid mode
+- **Generate failure**: Report specific failures, user can re-generate individually
 - **Integration failure**: Prototypes still usable, can integrate manually
 
-
-## Key Features
-
-- **🚀 Dual Capture**: Batch mode for speed, deep mode for detail
-- **⚡ 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
-- **🎯 Flexible**: Standalone or session-integrated modes
-
-## Examples
-
-### 1. Basic Multi-Page Replication
-```bash
-/workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
-# Result: 2 prototypes with fast-track tokens
-```
-
-### 2. Session Integration
-```bash
-/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
-```bash
-/workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
-# Result: Interactive layer capture + prototype
-```
-
-### 4. Guided Style Extraction
-```bash
-/workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
-# Result: 2 prototypes with minimalist style focus
-```
-
 ## Integration Points
 
-- **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)
+- **Input**: `--images` (glob pattern) and/or `--prompt` (text/file paths) + optional `--session`
+- **Output**: Complete design system in `{base_path}/` (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)
+  1. `/workflow:ui-design:import-from-code` (Phase 0.5, conditional - if code files detected)
   2. `/workflow:ui-design:style-extract` (Phase 2 - complete design systems)
-  3. `/workflow:ui-design:animation-extract` (Phase 2.3 - CSS animations and transitions)
+  3. `/workflow:ui-design:animation-extract` (Phase 2.3 - animation tokens)
   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)
@@ -692,30 +652,31 @@ TodoWrite({todos: [
 ```
 ✅ UI Design Imitate-Auto Workflow Complete!
 
-Mode: {capture_mode} | Session: {session_id or "standalone"}
+Mode: Direct Input ({design_source}) | Session: {session_id or "standalone"}
 Run ID: {run_id}
 
-Phase 1 - Screenshot Capture: ✅ {captured_count} screenshots
+Phase 0 - Input Detection: ✅ {design_source} mode
 Phase 2 - Style Extraction: ✅ Production-ready design systems
+Phase 2.3 - Animation Extraction: ✅ Animation tokens
 Phase 2.5 - Layout Extraction: ✅ Structure templates
-Phase 3 - UI Assembly: ✅ {generated_count} pages assembled
+Phase 3 - UI Assembly: ✅ {generated_count} prototypes 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
 ✅ Production-Ready: WCAG AA compliant, OKLCH colors
+✅ Multi-Source: Code import + visual extraction
 
 📂 {base_path}/
-  ├── screenshots/                  # {captured_count} screenshots
   ├── style-extraction/style-1/     # Production-ready design system
+  ├── animation-extraction/         # Animation tokens
   ├── layout-extraction/            # Structure templates
   └── prototypes/                   # {generated_count} HTML/CSS files
 
 🌐 Preview: {base_path}/prototypes/compare.html
   - Interactive preview
-  - Side-by-side comparison
-  - {generated_count} replicated pages
+  - Design token driven
+  - {generated_count} assembled prototypes
 
 Next: [/workflow:execute] OR [Open compare.html → /workflow:plan]
 ```

.claude/skills/command-guide/reference/commands/workflow/ui-design/layout-extract.md

@@ -1,23 +1,25 @@
 ---
 name: layout-extract
-description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis
-argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
+description: Extract structural layout information from reference images, URLs, or text prompts using Claude analysis with variant generation or refinement mode
+argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
 ---
 
 # 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`).
+Extract structural layout information from reference images, URLs, or text prompts using AI analysis. Supports two modes:
+1. **Exploration Mode** (default): Generate multiple contrasting layout variants
+2. **Refinement Mode** (`--refine`): Refine a single existing layout through detailed adjustments
+
+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
-  - `explore`: Multiple structurally distinct layout variations
-- **Single Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
+- **Dual Mode**: Exploration (multiple contrasting variants) or Refinement (single layout fine-tuning)
+- **Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
 - **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
 - **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
 
@@ -45,15 +47,19 @@ ELSE:
     has_urls = false
     url_list = []
 
-# Determine extraction mode
-extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+# Detect refinement mode
+refine_mode = --refine OR false
 
-# Set variants count based on mode
-IF extraction_mode == "imitate":
-    variants_count = 1  # Force single variant (ignore --variants)
-ELSE IF extraction_mode == "explore":
-    variants_count = --variants OR 3  # Default to 3
+# Set variants count
+# Refinement mode: Force variants_count = 1 (ignore user-provided --variants)
+# Exploration mode: Use --variants or default to 3 (range: 1-5)
+IF refine_mode:
+    variants_count = 1
+    REPORT: "🔧 Refinement mode enabled: Will generate 1 refined layout per target"
+ELSE:
+    variants_count = --variants OR 3
     VALIDATE: 1 <= variants_count <= 5
+    REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting layout concepts per target"
 
 # Resolve targets
 # Priority: --targets → url_list targets → prompt analysis → default ["page"]
@@ -62,6 +68,9 @@ IF --targets:
 ELSE IF has_urls:
     targets = [url_info.target for url_info in url_list]
 ELSE IF --prompt:
+    # Extract targets from prompt using pattern matching
+    # Looks for keywords: "page names", target descriptors (login, dashboard, etc.)
+    # Returns lowercase, hyphenated strings (e.g., ["login", "dashboard"])
     targets = extract_from_prompt(--prompt)
 ELSE:
     targets = ["page"]
@@ -69,9 +78,27 @@ ELSE:
 # Resolve device type
 device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
 
-# Determine base path
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
-# OR use --base-path / --session parameters
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 ```
 
 ### Step 2: Load Inputs & Create Directories
@@ -188,58 +215,54 @@ IF result.exploration?.triggered:
 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")
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 IF exists: SKIP to completion
 ```
 
 ---
 
-**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+**Phase 0 Output**: `input_mode`, `base_path`, `variants_count`, `targets[]`, `device_type`, loaded inputs
 
-## Phase 1: Layout Concept Generation (Explore Mode Only)
+## Phase 1: Layout Concept or Refinement Options Generation
 
-### Step 1: Check Extraction Mode
+### Step 0.5: Load Existing Layout (Refinement Mode)
 ```bash
-# extraction_mode == "imitate" → skip this phase
-# extraction_mode == "explore" → execute this phase
+IF refine_mode:
+    # Load existing layout for refinement
+    existing_layouts = {}
+    FOR target IN targets:
+        layout_files = bash(find {base_path}/layout-extraction -name "layout-{target}-*.json" -print)
+        IF layout_files:
+            # Use first/latest layout file for this target
+            existing_layouts[target] = Read(first_layout_file)
 ```
 
-**If imitate mode**: Skip to Phase 2
-
-### Step 2: Gather Layout Inspiration (Explore Mode)
-```bash
-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}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, inspiration_content)
-```
-
-### Step 3: Generate Layout Concept Options (Agent Task 1)
+### Step 1: Generate Options (Agent Task 1 - Mode-Specific)
 **Executor**: `Task(ui-design-agent)`
 
-Launch agent to generate `variants_count` layout concept options for each target:
+**Exploration Mode** (default): Generate contrasting layout concepts
+**Refinement Mode** (`--refine`): Generate refinement options for existing layouts
 
 ```javascript
-Task(ui-design-agent): `
-  [LAYOUT_CONCEPT_GENERATION_TASK]
-  Generate {variants_count} structurally distinct layout concepts for each target
+// Conditional agent task based on refine_mode
+IF NOT refine_mode:
+    // EXPLORATION MODE
+    Task(ui-design-agent): `
+      [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}
+      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" : ""}
+      ## Input Analysis
+      - Targets: {targets.join(", ")}
+      - Device type: {device_type}
+      - 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
+      ## 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
@@ -267,10 +290,74 @@ Task(ui-design-agent): `
   Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)
 
   CRITICAL: Use Write() tool immediately after generating complete JSON
-`
+    `
+ELSE:
+    // REFINEMENT MODE
+    Task(ui-design-agent): `
+      [LAYOUT_REFINEMENT_OPTIONS_TASK]
+      Generate refinement options for existing layout(s)
+
+      SESSION: {session_id} | MODE: refine | BASE_PATH: {base_path}
+      TARGETS: {targets} | DEVICE_TYPE: {device_type}
+
+      ## Existing Layouts
+      ${FOR target IN targets: "- {target}: {existing_layouts[target]}"}
+
+      ## Input Guidance
+      - User prompt: {prompt_guidance if available}
+      - Visual references: {loaded_images if available}
+
+      ## Refinement Categories
+      Generate 8-12 refinement options per target across these categories:
+
+      1. **Density Adjustments** (2-3 options per target):
+         - More compact: Tighter spacing, reduced whitespace
+         - More spacious: Increased margins, breathing room
+         - Balanced: Moderate adjustments
+
+      2. **Responsiveness Tuning** (2-3 options per target):
+         - Breakpoint behavior: Earlier/later column stacking
+         - Mobile layout: Different navigation/content priority
+         - Tablet optimization: Hybrid desktop/mobile approach
+
+      3. **Grid/Flex Specifics** (2-3 options per target):
+         - Column counts: 2-col ↔ 3-col ↔ 4-col
+         - Gap sizes: Tighter ↔ wider gutters
+         - Alignment: Different flex/grid justification
+
+      4. **Component Arrangement** (1-2 options per target):
+         - Navigation placement: Top ↔ side ↔ bottom
+         - Sidebar position: Left ↔ right ↔ none
+         - Content hierarchy: Different section ordering
+
+      ## Output Format
+      Each option (per target):
+      - target: Which target this refinement applies to
+      - category: "density|responsiveness|grid|arrangement"
+      - option_id: unique identifier
+      - label: Short descriptive name (e.g., "More Compact Spacing")
+      - description: What changes (2-3 sentences)
+      - preview_changes: Key structural adjustments
+      - impact_scope: Which layout regions affected
+
+      ## Output
+      Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json
+
+      Use refinement schema:
+      {
+        "mode": "refinement",
+        "device_type": "{device_type}",
+        "refinement_options": {
+          "{target1}": [array of refinement options],
+          "{target2}": [array of refinement options]
+        }
+      }
+
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
 ```
 
-### Step 4: Verify Options File Created
+### Step 2: Verify Options File Created
 ```bash
 bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")
 
@@ -282,17 +369,40 @@ bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep
 
 ---
 
-## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+## Phase 1.5: User Confirmation (Optional - Triggered by --interactive)
 
-**Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates
+**Purpose**:
+- **Exploration Mode**: Allow user to select preferred layout concept(s) per target
+- **Refinement Mode**: Allow user to select refinement options to apply per target
 
-### Step 1: Load and Present Options
+**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present
+
+### Step 1: Check Interactive Flag
+```bash
+# Skip this entire phase if --interactive flag is not present
+IF NOT --interactive:
+    SKIP to Phase 2
+    IF refine_mode:
+        REPORT: "ℹ️ Non-interactive refinement mode: Will apply all suggested refinements"
+    ELSE:
+        REPORT: "ℹ️ Non-interactive mode: Will generate all {variants_count} variants per target"
+
+# Interactive mode enabled
+REPORT: "🎯 Interactive mode: User selection required for {targets.length} target(s)"
+```
+
+### Step 2: Load and Present Options (Mode-Specific)
 ```bash
 # Read options file
 options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
 
-# Parse layout concepts
-layout_concepts = options.layout_concepts
+# Branch based on mode
+IF NOT refine_mode:
+    # EXPLORATION MODE
+    layout_concepts = options.layout_concepts
+ELSE:
+    # REFINEMENT MODE
+    refinement_options = options.refinement_options
 ```
 
 ### Step 2: Present Options to User (Per Target)
@@ -329,15 +439,34 @@ Please select your preferred concept for this target.
 }
 ```
 
-### Step 3: Capture User Selection (Per Target)
+### Step 3: Capture User Selection and Update Options File (Per Target)
+
+**Interaction Strategy**: If total concepts > 4 OR any target has > 3 concepts, use batch text format:
+
+```
+【目标[N] - [target]】选择布局方案
+[key]) Concept [index]: [concept_name]
+   [design_philosophy]
+[key]) Concept [index]: [concept_name]
+   [design_philosophy]
+...
+请回答 (格式: 1a 2b 或 1a,b 2c 多选)：
+
+User input:
+  "[N][key] [N][key] ..." → Single selection per target
+  "[N][key1,key2] [N][key3] ..." → Multi-selection per target
+```
+
+Otherwise, use `AskUserQuestion` below.
+
 ```javascript
-// Use AskUserQuestion tool for each target
+// Use AskUserQuestion tool for each target (multi-select enabled)
 FOR each target:
   AskUserQuestion({
     questions: [{
-      question: "Which layout concept do you prefer for '{target}'?",
+      question: "Which layout concept(s) do you prefer for '{target}'?",
       header: "Layout for " + target,
-      multiSelect: false,
+      multiSelect: true,  // Multi-selection enabled (default behavior)
       options: [
         {FOR each concept in layout_concepts[target]:
           label: "Concept {concept.index}: {concept.concept_name}",
@@ -347,193 +476,218 @@ FOR each target:
     }]
   })
 
-  // Parse user response
-  selected_option_text = user_answer
+  // Parse user response (array of selections)
+  selected_options = user_answer
 
   // Check for user cancellation
-  IF selected_option_text == null OR selected_option_text == "":
+  IF selected_options == null OR selected_options.length == 0:
       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
+  // Extract concept indices from array
+  selected_indices = []
+  FOR each selected_option_text IN selected_options:
+      match = selected_option_text.match(/Concept (\d+):/)
+      IF match:
+          selected_indices.push(parseInt(match[1]))
+      ELSE:
+          ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
+          EXIT workflow
 
-  // Store selection for this target
+  // Store selections for this target (array of indices)
   selections[target] = {
-    selected_index: selected_index,
-    concept_name: layout_concepts[target][selected_index-1].concept_name
+    selected_indices: selected_indices,  // Array of selected indices
+    concept_names: selected_indices.map(i => layout_concepts[target][i-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}}
+  REPORT: "✅ Selected {selected_indices.length} layout(s) for {target}"
+
+// Calculate total selections across all targets
+total_selections = sum([len(selections[t].selected_indices) for t in targets])
+
+// Update analysis-options.json with user selection (embedded in same file)
+options_file = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": "{current_timestamp}",
+  "selection_type": "per_target_multi",
+  "session_id": "{session_id}",
+  "total_selections": total_selections,
+  "selected_variants": selections  // {target: {selected_indices: [...], concept_names: [...]}}
 }
 
-# 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")
+// Write updated file back
+Write({base_path}/.intermediates/layout-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
 ```
 
-### Step 5: Confirmation Message
+### Step 4: Confirmation Message
 ```
-✅ Selections recorded!
+✅ Selections recorded! Total: {total_selections} layout(s)
 
 {FOR each target, selection in selections:
-  • {target}: Concept {selection.selected_index} - {selection.concept_name}
+  • {target}: {selection.selected_indices.length} layout(s) selected
+    {FOR each index IN selection.selected_indices:
+      - Concept {index}: {layout_concepts[target][index-1].concept_name}
+    }
 }
 
-Proceeding to generate detailed layout templates based on your selections...
+Proceeding to generate {total_selections} detailed layout template(s)...
 ```
 
-**Output**: `user-selection.json` with user's choices for all targets
+**Output**: `analysis-options.json` updated with embedded `user_selection` field
 
 ## Phase 2: Layout Template Generation (Agent Task 2)
 
-**Executor**: `Task(ui-design-agent)` for selected concept(s)
+**Executor**: `Task(ui-design-agent)` × `Total_Selected_Templates` in **parallel**
 
-### Step 1: Load User Selection (Explore Mode)
+### Step 1: Load User Selections or Default to All
 ```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
+# Read analysis-options.json which may contain user_selection
+options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+layout_concepts = options.layout_concepts
 
-    # 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
+# Check if user_selection field exists (interactive mode)
+IF options.user_selection AND options.user_selection.selected_variants:
+    # Interactive mode: Use user-selected variants
+    selections_per_target = options.user_selection.selected_variants
+    total_selections = options.user_selection.total_selections
 ELSE:
-    # Imitate mode - no selection needed
-    selected_concepts = null
+    # Non-interactive mode: Generate ALL variants for ALL targets (default behavior)
+    selections_per_target = {}
+    total_selections = 0
+
+    FOR each target in targets:
+        selections_per_target[target] = {
+            "selected_indices": [1, 2, ..., variants_count],  # All indices
+            "concept_names": []  # Will be filled from options
+        }
+        total_selections += variants_count
+
+# Build task list for all selected concepts across all targets
+task_list = []
+FOR each target in targets:
+    selected_indices = selections_per_target[target].selected_indices  # Array
+    concept_names = selections_per_target[target].concept_names        # Array
+
+    FOR i in range(len(selected_indices)):
+        idx = selected_indices[i]
+        concept = layout_concepts[target][idx - 1]  # 0-indexed array
+        variant_id = i + 1  # 1-based variant numbering
+
+        task_list.push({
+            target: target,
+            variant_id: variant_id,
+            concept: concept,
+            output_file: "{base_path}/layout-extraction/layout-{target}-{variant_id}.json"
+        })
+
+total_tasks = task_list.length
+REPORT: "Generating {total_tasks} layout templates across {targets.length} targets"
 ```
 
-### Step 2: Launch Agent Task
-Generate layout templates for selected concepts:
+### Step 2: Launch Parallel Agent Tasks
+Generate layout templates for ALL selected concepts in parallel:
 ```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.).
+FOR each task in task_list:
+    Task(ui-design-agent): `
+      [LAYOUT_TEMPLATE_GENERATION_TASK #{task.variant_id} for {task.target}]
+      Generate detailed layout template based on user-selected concept.
+      Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
 
-  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
-  DEVICE_TYPE: {device_type}
+      SESSION: {session_id} | BASE_PATH: {base_path}
+      TARGET: {task.target} | VARIANT: {task.variant_id}
+      DEVICE_TYPE: {device_type}
 
-  ${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(", ")}
-  `}
+      USER SELECTION:
+      - Selected Concept: {task.concept.concept_name}
+      - Philosophy: {task.concept.design_philosophy}
+      - Pattern: {task.concept.layout_pattern}
+      - Key Components: {task.concept.key_components.join(", ")}
+      - Structural Features: {task.concept.structural_features.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" : ""}
+      ## Input Analysis
+      - Target: {task.target}
+      - Device type: {device_type}
+      - Visual references: {loaded_images if available}
+      ${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-{task.target}.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
-  ` : ""}
+      ## Generation Rules
+      - Develop the 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
+      ${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:"}
+      ## Template Generation
 
-    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}
+      1. **DOM Structure**:
+         - Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+         - ARIA roles and accessibility attributes
+         - 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" : ""}
+      2. **Component Hierarchy**:
+         - Array of main layout regions
+         - 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
+      3. **CSS Layout Rules**:
+         - 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
-  Write complete layout-templates.json with layout_templates array.
-  Each template must include:
-  - target (string)
-  - 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 ${extraction_mode == "explore" ? "- from selected concept" : ""})
-  - dom_structure (JSON object)
-  - component_hierarchy (array of strings)
-  - css_layout_rules (string)
+      ## Output Files
 
-  ## 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" : ""}
-`
+      Generate 2 files:
+
+      1. **layout-templates.json** - {task.output_file}
+         Write single-template JSON object with:
+         - target: "{task.target}"
+         - variant_id: "layout-{task.variant_id}"
+         - source_image_path (string): Reference image path
+         - device_type: "{device_type}"
+         - design_philosophy (string from selected concept)
+         - dom_structure (JSON object)
+         - component_hierarchy (array of strings)
+         - css_layout_rules (string)
+
+      ## Critical Requirements
+      - ✅ Use Write() tool to generate JSON file
+      - ✅ Single template for {task.target} variant {task.variant_id}
+      - ✅ Structure only, no visual styling
+      - ✅ Token-based CSS (var())
+      - ✅ Can use Exa MCP to research modern layout patterns and obtain code examples (Explore/Text mode)
+      - ✅ Maintain consistency with selected concept
+    `
 ```
 
-**Output**: Agent generates `layout-templates.json` with one template per target
+**Output**: Agent generates multiple layout template files (one per selected concept)
 
-### Step 2: Write Output File
+### Step 3: Verify Output Files
 ```bash
-# Take JSON output from agent
-bash(echo '{agent_json_output}' > {base_path}/layout-extraction/layout-templates.json)
+# Count generated files
+expected_count = total_tasks
+actual_count = bash(ls {base_path}/layout-extraction/layout-*.json | wc -l)
 
-# Verify output
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
-bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_templates" && echo "valid")
+# Verify all files were created
+IF actual_count == expected_count:
+    REPORT: "✓ All {expected_count} layout template files generated"
+ELSE:
+    ERROR: "Expected {expected_count} files, found {actual_count}"
+
+# Verify file structure (sample check)
+bash(cat {base_path}/layout-extraction/layout-{first_target}-1.json | grep -q "variant_id" && echo "valid structure")
 ```
 
-**Output**: `layout-templates.json` created and verified
+**Output**: All layout template files created and verified (one file per selected concept)
 
 ## Completion
 
@@ -541,9 +695,10 @@ bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_t
 ```javascript
 TodoWrite({todos: [
   {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
-  {content: "Layout research (explore mode)", status: "completed", activeForm: "Researching layout patterns"},
-  {content: "Layout analysis and synthesis (agent)", status: "completed", activeForm: "Generating layout templates"},
-  {content: "Write layout-templates.json", status: "completed", activeForm: "Saving templates"}
+  {content: "Layout concept analysis (agent)", status: "completed", activeForm: "Analyzing layout patterns"},
+  {content: "User selection confirmation", status: "completed", activeForm: "Confirming selections"},
+  {content: "Generate layout templates (parallel)", status: "completed", activeForm: "Generating templates"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
 ]});
 ```
 
@@ -553,11 +708,9 @@ TodoWrite({todos: [
 
 Configuration:
 - Session: {session_id}
-- Extraction Mode: {extraction_mode} (imitate/explore)
 - Device Type: {device_type}
-- Targets: {targets}
-- Variants per Target: {variants_count}
-- Total Templates: {targets.length × variants_count}
+- Targets: {targets.join(", ")}
+- Total Templates: {total_tasks} ({targets.length} targets with multi-selection)
 {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
@@ -566,22 +719,27 @@ Configuration:
 - ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
 }
 
-{IF extraction_mode == "explore":
-Layout Research:
-- {targets.length} inspiration files generated
-- Pattern search focused on {device_type} layouts
+User Selections:
+{FOR each target in targets:
+- {target}: {selections_per_target[target].concept_names.join(", ")} ({selections_per_target[target].selected_indices.length} variants)
 }
 
 Generated Templates:
-{FOR each template: - Target: {template.target} | Variant: {template.variant_id} | Philosophy: {template.design_philosophy}}
-
-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)
+{base_path}/layout-extraction/
+{FOR each target in targets:
+  {FOR each variant_id in range(1, selections_per_target[target].selected_indices.length + 1):
+    └── layout-{target}-{variant_id}.json
+  }
 }
 
-Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
+Intermediate Files:
+- {base_path}/.intermediates/layout-analysis/
+  ├── analysis-options.json (concept proposals + user selections embedded)
+  {IF dom_structure_available:
+  ├── dom-structure-*.json ({len(url_list)} DOM extracts)
+  }
+
+Next: /workflow:ui-design:generate will combine these structural templates with design systems to produce final prototypes.
 ```
 
 ## Simple Bash Commands
@@ -589,23 +747,22 @@ Next: /workflow:ui-design:generate will combine these structural templates with
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Create output directories
 bash(mkdir -p {base_path}/layout-extraction)
-bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)  # explore mode only
 ```
 
 ### Validation Commands
 ```bash
 # Check if already extracted
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 
-# Validate JSON structure
-bash(cat layout-templates.json | grep -q "layout_templates" && echo "valid")
+# Count generated files
+bash(ls {base_path}/layout-extraction/layout-*.json | wc -l)
 
-# Count templates
-bash(cat layout-templates.json | grep -c "\"target\":")
+# Validate JSON structure (sample check)
+bash(cat {base_path}/layout-extraction/layout-{first_target}-1.json | grep -q "variant_id" && echo "valid")
 ```
 
 ### File Operations
@@ -614,9 +771,6 @@ bash(cat layout-templates.json | grep -c "\"target\":")
 bash(ls {images_pattern})
 Read({image_path})
 
-# Write inspiration files (explore mode)
-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)
 ```
@@ -627,28 +781,27 @@ bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
 {base_path}/
 ├── .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
+│       ├── analysis-options.json      # Generated layout concepts + user selections (embedded)
+│       └── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
 └── layout-extraction/                 # Final layout templates
-    ├── layout-templates.json          # Structural layout templates
-    └── layout-space-analysis.json     # Layout directions (explore mode only)
+    └── layout-{target}-{variant}.json # Structural layout template JSON
 ```
 
-## layout-templates.json Format
+## Layout Template File Format
+
+Each `layout-{target}-{variant}.json` file contains a single template:
 
 ```json
 {
   "extraction_metadata": {
     "session_id": "...",
     "input_mode": "image|url|prompt|hybrid",
-    "extraction_mode": "imitate|explore",
     "device_type": "desktop|mobile|tablet|responsive",
     "timestamp": "...",
-    "variants_count": 3,
-    "targets": ["home", "dashboard"]
+    "target": "home",
+    "variant_id": "layout-1"
   },
-  "layout_templates": [
+  "template":
     {
       "target": "home",
       "variant_id": "layout-1",
@@ -703,8 +856,8 @@ ERROR: Invalid target name
 ERROR: Agent task failed
 → Check agent output, retry with simplified prompt
 
-ERROR: MCP search failed (explore mode)
-→ Check network, retry
+ERROR: MCP search failed
+→ Check network connection, retry command
 ```
 
 ### Recovery Strategies
@@ -718,29 +871,12 @@ ERROR: MCP search failed (explore mode)
 - **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
+- **Multi-Selection Workflow** - Generate N concepts → User selects multiple → Parallel template generation
+- **Structural Exploration** - Enables A/B testing of different layouts through multi-selection
 - **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
+- **Foundation for Assembly** - Provides structural blueprint for prototype generation
 - **Agent-Powered** - Deep structural analysis with AI
 
-## Integration
 
-**Workflow Position**: Between style extraction and prototype generation
-
-**New Workflow**:
-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`
-     2. Create layout CSS from `css_layout_rules`
-     3. Link design tokens CSS
-     4. Inject placeholder content
-   - **Output**: Complete token-driven HTML/CSS prototypes
-
-**Input**: Reference images, URLs, or text prompts
-**Output**: `layout-templates.json` for `/workflow:ui-design:generate`
-**Next**: `/workflow:ui-design:generate --session {session_id}`

.claude/skills/command-guide/reference/commands/workflow/ui-design/list.md

@@ -0,0 +1,174 @@
+---
+name: list
+description: List all available design runs with metadata (session, created time, prototype count)
+argument-hint: [--session <id>]
+allowed-tools: Bash(*), Read(*)
+---
+
+# List Design Runs (/workflow:ui-design:list)
+
+## Overview
+List all available UI design runs across sessions or within a specific session. Displays design IDs with metadata for easy reference.
+
+**Output**: Formatted list with design-id, session, created time, and prototype count
+
+## Implementation
+
+### Step 1: Determine Search Scope
+```bash
+# Priority: --session > all sessions
+search_path=$(if [ -n "$SESSION_ID" ]; then
+  echo ".workflow/WFS-$SESSION_ID"
+else
+  echo ".workflow"
+fi)
+```
+
+### Step 2: Find and Display Design Runs
+```bash
+echo "Available design runs:"
+echo ""
+
+# Find all design-run directories
+found_count=0
+while IFS= read -r line; do
+  timestamp=$(echo "$line" | cut -d' ' -f1)
+  path=$(echo "$line" | cut -d' ' -f2-)
+
+  # Extract design_id from path
+  design_id=$(basename "$path")
+
+  # Extract session from path
+  session_id=$(echo "$path" | grep -oP 'WFS-\K[^/]+' || echo "standalone")
+
+  # Format created date
+  created_at=$(date -d "@${timestamp%.*}" '+%Y-%m-%d %H:%M' 2>/dev/null || echo "unknown")
+
+  # Count prototypes
+  prototype_count=$(find "$path/prototypes" -name "*.html" 2>/dev/null | wc -l)
+
+  # Display formatted output
+  echo "  - $design_id"
+  echo "      Session: $session_id"
+  echo "      Created: $created_at"
+  echo "      Prototypes: $prototype_count"
+  echo ""
+
+  found_count=$((found_count + 1))
+done < <(find "$search_path" -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr)
+
+# Summary
+if [ $found_count -eq 0 ]; then
+  echo "  No design runs found."
+  echo ""
+  if [ -n "$SESSION_ID" ]; then
+    echo "💡 HINT: Try running '/workflow:ui-design:explore-auto' to create a design run"
+  else
+    echo "💡 HINT: Try running '/workflow:ui-design:explore-auto --session <id>' to create a design run"
+  fi
+else
+  echo "Total: $found_count design run(s)"
+  echo ""
+  echo "💡 USE: /workflow:ui-design:generate --design-id \"<id>\""
+  echo "      OR: /workflow:ui-design:generate --session \"<session>\""
+fi
+```
+
+### Step 3: Execute List Command
+```bash
+Bash(
+  description: "List all UI design runs with metadata",
+  command: "
+    search_path=\"${search_path}\"
+    SESSION_ID=\"${SESSION_ID:-}\"
+
+    echo 'Available design runs:'
+    echo ''
+
+    found_count=0
+    while IFS= read -r line; do
+      timestamp=\$(echo \"\$line\" | cut -d' ' -f1)
+      path=\$(echo \"\$line\" | cut -d' ' -f2-)
+
+      design_id=\$(basename \"\$path\")
+      session_id=\$(echo \"\$path\" | grep -oP 'WFS-\\K[^/]+' || echo 'standalone')
+      created_at=\$(date -d \"@\${timestamp%.*}\" '+%Y-%m-%d %H:%M' 2>/dev/null || echo 'unknown')
+      prototype_count=\$(find \"\$path/prototypes\" -name '*.html' 2>/dev/null | wc -l)
+
+      echo \"  - \$design_id\"
+      echo \"      Session: \$session_id\"
+      echo \"      Created: \$created_at\"
+      echo \"      Prototypes: \$prototype_count\"
+      echo ''
+
+      found_count=\$((found_count + 1))
+    done < <(find \"\$search_path\" -name 'design-run-*' -type d -printf '%T@ %p\\n' 2>/dev/null | sort -nr)
+
+    if [ \$found_count -eq 0 ]; then
+      echo '  No design runs found.'
+      echo ''
+      if [ -n \"\$SESSION_ID\" ]; then
+        echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto\\' to create a design run'
+      else
+        echo '💡 HINT: Try running \\'/workflow:ui-design:explore-auto --session <id>\\' to create a design run'
+      fi
+    else
+      echo \"Total: \$found_count design run(s)\"
+      echo ''
+      echo '💡 USE: /workflow:ui-design:generate --design-id \"<id>\"'
+      echo '      OR: /workflow:ui-design:generate --session \"<session>\"'
+    fi
+  "
+)
+```
+
+## Example Output
+
+### With Session Filter
+```
+$ /workflow:ui-design:list --session ui-redesign
+
+Available design runs:
+
+  - design-run-20250109-143052
+      Session: ui-redesign
+      Created: 2025-01-09 14:30
+      Prototypes: 12
+
+  - design-run-20250109-101534
+      Session: ui-redesign
+      Created: 2025-01-09 10:15
+      Prototypes: 6
+
+Total: 2 design run(s)
+
+💡 USE: /workflow:ui-design:generate --design-id "<id>"
+      OR: /workflow:ui-design:generate --session "<session>"
+```
+
+### All Sessions
+```
+$ /workflow:ui-design:list
+
+Available design runs:
+
+  - design-run-20250109-143052
+      Session: ui-redesign
+      Created: 2025-01-09 14:30
+      Prototypes: 12
+
+  - design-run-20250108-092314
+      Session: landing-page
+      Created: 2025-01-08 09:23
+      Prototypes: 3
+
+  - design-run-20250107-155623
+      Session: standalone
+      Created: 2025-01-07 15:56
+      Prototypes: 8
+
+Total: 3 design run(s)
+
+💡 USE: /workflow:ui-design:generate --design-id "<id>"
+      OR: /workflow:ui-design:generate --session "<session>"
+```

.claude/skills/command-guide/reference/commands/workflow/ui-design/reference-page-generator.md

@@ -0,0 +1,333 @@
+---
+name: workflow:ui-design:reference-page-generator
+description: Generate multi-component reference pages and documentation from design run extraction
+argument-hint: "[--design-run <path>] [--package-name <name>] [--output-dir <path>]"
+allowed-tools: Read,Write,Bash,Task,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Reference Page Generator
+
+## Overview
+
+Converts design run extraction results into shareable reference package with:
+- Interactive multi-component preview (preview.html + preview.css)
+- Component layout templates (layout-templates.json)
+
+**Role**: Takes existing design run (from `import-from-code` or other extraction commands) and generates preview pages for easy reference.
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:reference-page-generator [FLAGS]
+
+# Flags
+--design-run <path>      Design run directory path (required)
+--package-name <name>    Package name for reference (required)
+--output-dir <path>      Output directory (default: .workflow/reference_style)
+```
+
+---
+
+## Execution Process
+
+### Phase 0: Setup & Validation
+
+**Purpose**: Validate inputs, prepare output directory
+
+**Operations**:
+
+```bash
+# 1. Validate required parameters
+if [ -z "$design_run" ] || [ -z "$package_name" ]; then
+  echo "ERROR: --design-run and --package-name are required"
+  echo "USAGE: /workflow:ui-design:reference-page-generator --design-run <path> --package-name <name>"
+  exit 1
+fi
+
+# 2. Validate package name format (lowercase, alphanumeric, hyphens only)
+if ! [[ "$package_name" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+  echo "ERROR: Invalid package name. Use lowercase, alphanumeric, and hyphens only."
+  echo "EXAMPLE: main-app-style-v1"
+  exit 1
+fi
+
+# 3. Validate design run exists
+if [ ! -d "$design_run" ]; then
+  echo "ERROR: Design run not found: $design_run"
+  echo "HINT: Run '/workflow:ui-design:import-from-code' first to create design run"
+  exit 1
+fi
+
+# 4. Check required extraction files exist
+required_files=(
+  "$design_run/style-extraction/style-1/design-tokens.json"
+  "$design_run/layout-extraction/layout-templates.json"
+)
+
+for file in "${required_files[@]}"; do
+  if [ ! -f "$file" ]; then
+    echo "ERROR: Required file not found: $file"
+    echo "HINT: Ensure design run has style and layout extraction results"
+    exit 1
+  fi
+done
+
+# 5. Setup output directory and validate
+output_dir="${output_dir:-.workflow/reference_style}"
+package_dir="${output_dir}/${package_name}"
+
+# Check if package directory exists and is not empty
+if [ -d "$package_dir" ] && [ "$(ls -A $package_dir 2>/dev/null)" ]; then
+  # Directory exists - check if it's a valid package or just a directory
+  if [ -f "$package_dir/metadata.json" ]; then
+    # Valid package - safe to overwrite
+    existing_version=$(jq -r '.version // "unknown"' "$package_dir/metadata.json" 2>/dev/null || echo "unknown")
+    echo "INFO: Overwriting existing package '$package_name' (version: $existing_version)"
+  else
+    # Directory exists but not a valid package
+    echo "ERROR: Directory '$package_dir' exists but is not a valid package"
+    echo "Use a different package name or remove the directory manually"
+    exit 1
+  fi
+fi
+
+mkdir -p "$package_dir"
+
+echo "[Phase 0] Setup Complete"
+echo "  Design Run: $design_run"
+echo "  Package: $package_name"
+echo "  Output: $package_dir"
+```
+
+<!-- TodoWrite: Initialize todo list -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
+  {"content": "Phase 1: 准备组件数据", "status": "in_progress", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "pending", "activeForm": "生成预览"}
+]
+```
+
+---
+
+### Phase 1: Prepare Component Data
+
+**Purpose**: Copy required files from design run to package directory
+
+**Operations**:
+
+```bash
+echo "[Phase 1] Preparing component data from design run"
+
+# 1. Copy layout templates as component patterns
+cp "${design_run}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json"
+
+if [ ! -f "${package_dir}/layout-templates.json" ]; then
+  echo "ERROR: Failed to copy layout templates"
+  exit 1
+fi
+
+# Count components from layout templates
+component_count=$(jq -r '.layout_templates | length // 0' "${package_dir}/layout-templates.json" 2>/dev/null || echo 0)
+echo "  ✓ Layout templates copied (${component_count} components)"
+
+# 2. Copy design tokens (required for preview generation)
+cp "${design_run}/style-extraction/style-1/design-tokens.json" "${package_dir}/design-tokens.json"
+
+if [ ! -f "${package_dir}/design-tokens.json" ]; then
+  echo "ERROR: Failed to copy design tokens"
+  exit 1
+fi
+echo "  ✓ Design tokens copied"
+
+# 3. Copy animation tokens if exists (optional)
+if [ -f "${design_run}/animation-extraction/animation-tokens.json" ]; then
+  cp "${design_run}/animation-extraction/animation-tokens.json" "${package_dir}/animation-tokens.json"
+  echo "  ✓ Animation tokens copied"
+else
+  echo "  ○ Animation tokens not found (optional)"
+fi
+
+echo "[Phase 1] Component data preparation complete"
+```
+
+<!-- TodoWrite: Mark Phase 1 complete, start Phase 2 -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "in_progress", "activeForm": "生成预览"}
+]
+```
+
+---
+
+### Phase 2: Preview Generation (Final Phase)
+
+**Purpose**: Generate interactive multi-component preview (preview.html + preview.css)
+
+**Agent Task**:
+
+```javascript
+Task(ui-design-agent): `
+  [PREVIEW_SHOWCASE_GENERATION]
+  Generate interactive multi-component showcase panel for reference package
+
+  PACKAGE_DIR: ${package_dir} | PACKAGE_NAME: ${package_name}
+
+  ## Input Files (MUST READ ALL)
+
+  1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED)
+  2. ${package_dir}/design-tokens.json (design tokens - REQUIRED)
+  3. ${package_dir}/animation-tokens.json (optional, if exists)
+
+  ## Generation Task
+
+  Create interactive showcase with these sections:
+
+  ### Section 1: Colors
+  - Display all color categories as color swatches
+  - Show hex/rgb values
+  - Group by: brand, semantic, surface, text, border
+
+  ### Section 2: Typography
+  - Display typography scale (font sizes, weights)
+  - Show typography combinations if available
+  - Include font family examples
+  - **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
+    * Common sizes table (small_text, body_text, heading)
+    * Common combinations with use cases
+
+  ### Section 3: Components
+  - Render all components from layout-templates.json (use layout_templates field)
+  - **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
+    * **Display usage_guide** (from layout-templates.json):
+      - Common sizes table with dimensions and use cases
+      - Variant recommendations (when to use primary/secondary/etc)
+      - Usage context list (typical scenarios)
+      - Accessibility tips checklist
+  - **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
+  - Display all variants side-by-side
+  - Show DOM structure with proper styling
+  - Include usage code snippets in <details> tags
+  - Clearly label component types (universal vs specialized)
+
+  ### Section 4: Spacing & Layout
+  - Visual spacing scale
+  - Border radius examples
+  - Shadow depth examples
+  - **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
+    * Size guide table (tight/normal/loose categories)
+    * Common patterns with use cases and pixel values
+
+  ### Section 5: Animations (if available)
+  - Animation duration examples
+  - Easing function demonstrations
+
+  ## Output Requirements
+
+  Generate 2 files:
+  1. ${package_dir}/preview.html
+  2. ${package_dir}/preview.css
+
+  ### preview.html Structure:
+  - Complete standalone HTML file
+  - Responsive design with mobile-first approach
+  - Sticky navigation for sections
+  - Interactive component demonstrations
+  - Code snippets in collapsible <details> elements
+  - Footer with package metadata
+
+  ### preview.css Structure:
+  - CSS Custom Properties from design-tokens.json
+  - Typography combination classes
+  - Component classes from layout-templates.json
+  - Preview page layout styles
+  - Interactive demo styles
+
+  ## Critical Requirements
+  - ✅ Read ALL input files (layout-templates.json, design-tokens.json, animation-tokens.json if exists)
+  - ✅ Generate complete, interactive showcase HTML
+  - ✅ All CSS uses var() references to design tokens
+  - ✅ Display ALL components from layout-templates.json
+  - ✅ **Separate universal components from specialized components** in the showcase
+  - ✅ Display component DOM structures with proper styling
+  - ✅ Include usage code snippets
+  - ✅ Label each component type clearly (Universal / Specialized)
+  - ✅ **Display usage recommendations** when available:
+    - Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
+    - Components: usage_guide for universal components (from layout-templates)
+    - Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
+  - ✅ Gracefully handle missing usage data (display sections only if data exists)
+  - ✅ Use Write() to save both files:
+    - ${package_dir}/preview.html
+    - ${package_dir}/preview.css
+  - ❌ NO external research or MCP calls
+`
+```
+
+<!-- TodoWrite: Mark all complete -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
+  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"}
+]
+```
+
+---
+
+## Output Structure
+
+```
+${output_dir}/
+└── ${package_name}/
+    ├── layout-templates.json    # Layout templates (copied from design run)
+    ├── design-tokens.json       # Design tokens (copied from design run)
+    ├── animation-tokens.json    # Animation tokens (copied from design run, optional)
+    ├── preview.html             # Interactive showcase (NEW)
+    └── preview.css              # Showcase styling (NEW)
+```
+
+## Completion Message
+
+```
+✅ Preview package generated!
+
+Package: {package_name}
+Location: {package_dir}
+
+Files:
+✓ layout-templates.json    {component_count} components
+✓ design-tokens.json       Design tokens
+✓ animation-tokens.json    Animation tokens {if exists: "✓" else: "○ (not found)"}
+✓ preview.html             Interactive showcase
+✓ preview.css              Showcase styling
+
+Open preview:
+  file://{absolute_path_to_package_dir}/preview.html
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing --design-run or --package-name | Required parameters not provided | Provide both flags |
+| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
+| Design run not found | Incorrect path or design run doesn't exist | Verify design run path, run import-from-code first |
+| Missing extraction files | Design run incomplete | Ensure design run has style-extraction and layout-extraction results |
+| Layout templates copy failed | layout-templates.json not found | Run import-from-code with Layout Agent first |
+| Preview generation failed | Invalid design tokens | Check design-tokens.json format |
+
+---
+

.claude/skills/command-guide/reference/commands/workflow/ui-design/style-extract.md

@@ -1,20 +1,22 @@
 ---
 name: style-extract
-description: Extract design style from reference images or text prompts using Claude analysis with variant generation
-argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+description: Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode
+argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*), 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. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
+Extract design style from reference images or text prompts using Claude's built-in analysis. Supports two modes:
+1. **Exploration Mode** (default): Generate multiple contrasting design variants
+2. **Refinement Mode** (`--refine`): Refine a single existing design through detailed adjustments
 
 **Strategy**: AI-Driven Design Space Exploration
 - **Claude-Native**: 100% Claude analysis, no external tools
-- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
+- **Direct Output**: Complete design systems (design-tokens.json)
 - **Flexible Input**: Images, text prompts, or both (hybrid mode)
-- **Maximum Contrast**: AI generates maximally divergent design directions
+- **Dual Mode**: Exploration (multiple contrasting variants) or Refinement (single design fine-tuning)
 - **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
 
 ## Phase 0: Setup & Input Validation
@@ -40,20 +42,41 @@ IF --urls:
 ELSE:
     has_urls = false
 
-# Determine extraction mode
-# Priority: --mode parameter → default "imitate"
-extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+# Detect refinement mode
+refine_mode = --refine OR false
 
-# Set variants count based on mode
-IF extraction_mode == "imitate":
-    variants_count = 1  # Force single variant for imitate mode (ignore --variants)
-ELSE IF extraction_mode == "explore":
-    variants_count = --variants OR 3  # Default to 3 for explore mode
+# Set variants count
+# Refinement mode: Force variants_count = 1 (ignore user-provided --variants)
+# Exploration mode: Use --variants or default to 3 (range: 1-5)
+IF refine_mode:
+    variants_count = 1
+    REPORT: "🔧 Refinement mode enabled: Will generate 1 refined design system"
+ELSE:
+    variants_count = --variants OR 3
     VALIDATE: 1 <= variants_count <= 5
+    REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting design directions"
 
-# Determine base path
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
-# OR use --base-path / --session parameters
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 ```
 
 ### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
@@ -140,72 +163,131 @@ IF exists: SKIP to completion
 
 **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 Direction Generation (Explore Mode Only)
+## Phase 1: Design Direction or Refinement Options Generation
 
-### Step 1: Check Extraction Mode
-```bash
-# Check extraction mode
-# extraction_mode == "imitate" → skip this phase
-# extraction_mode == "explore" → execute this phase
-```
-
-**If imitate mode**: Skip to Phase 2
-
-### Step 2: Load Project Context (Explore Mode)
+### Step 1: Load Project Context
 ```bash
 # Load brainstorming context if available
 bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
+
+# Load existing design system if refinement mode
+IF refine_mode:
+    existing_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
 ```
 
-### Step 3: Generate Design Direction Options (Agent Task 1)
+### Step 2: Generate Options (Agent Task 1 - Mode-Specific)
 **Executor**: `Task(ui-design-agent)`
 
-Launch agent to generate `variants_count` design direction options with previews:
+**Exploration Mode** (default): Generate contrasting design directions
+**Refinement Mode** (`--refine`): Generate refinement options for existing design
 
 ```javascript
-Task(ui-design-agent): `
-  [DESIGN_DIRECTION_GENERATION_TASK]
-  Generate {variants_count} maximally contrasting design directions with visual previews
+// Conditional agent task based on refine_mode
+IF NOT refine_mode:
+    // EXPLORATION MODE
+    Task(ui-design-agent): `
+      [DESIGN_DIRECTION_GENERATION_TASK]
+      Generate {variants_count} maximally contrasting design directions with visual previews
 
-  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+      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}
+      ## 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)
+      ## 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)
+      ## 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)
+      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
+      ## 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)
+      Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
 
-  CRITICAL: Use Write() tool immediately after generating complete JSON
-`
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
+ELSE:
+    // REFINEMENT MODE
+    Task(ui-design-agent): `
+      [DESIGN_REFINEMENT_OPTIONS_TASK]
+      Generate refinement options for existing design system
+
+      SESSION: {session_id} | MODE: refine | BASE_PATH: {base_path}
+
+      ## Existing Design System
+      - design-tokens.json: {existing_tokens}
+
+      ## Input Guidance
+      - User prompt: {prompt_guidance}
+      - Visual references: {loaded_images if available}
+
+      ## Refinement Categories
+      Generate 8-12 refinement options across these categories:
+
+      1. **Intensity/Degree Adjustments** (2-3 options):
+         - Color intensity: more vibrant ↔ more muted
+         - Visual weight: bolder ↔ lighter
+         - Density: more compact ↔ more spacious
+
+      2. **Specific Attribute Tuning** (3-4 options):
+         - Border radius: sharper corners ↔ rounder edges
+         - Shadow depth: subtler shadows ↔ deeper elevation
+         - Typography scale: tighter scale ↔ more contrast
+         - Spacing scale: tighter rhythm ↔ more breathing room
+
+      3. **Context-Specific Variations** (2-3 options):
+         - Dark mode optimization
+         - Mobile-specific adjustments
+         - High-contrast accessibility mode
+
+      4. **Component-Level Customization** (1-2 options):
+         - Button styling emphasis
+         - Card/container treatment
+         - Form input refinements
+
+      ## Output Format
+      Each option:
+      - category: "intensity|attribute|context|component"
+      - option_id: unique identifier
+      - label: Short descriptive name (e.g., "More Vibrant Colors")
+      - description: What changes (2-3 sentences)
+      - preview_changes: Key token adjustments preview
+      - impact_scope: Which tokens affected
+
+      ## Output
+      Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+
+      Use refinement schema:
+      {
+        "mode": "refinement",
+        "base_design": "style-1",
+        "refinement_options": [array of refinement options]
+      }
+
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
 ```
 
-### Step 4: Verify Options File Created
+### Step 3: Verify Options File Created
 ```bash
 bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
 
@@ -217,20 +299,44 @@ bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep
 
 ---
 
-## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+## Phase 1.5: User Confirmation (Optional - Triggered by --interactive)
 
-**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
+**Purpose**:
+- **Exploration Mode**: Allow user to select preferred design direction(s)
+- **Refinement Mode**: Allow user to select refinement options to apply
 
-### Step 1: Load and Present Options
+**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present
+
+### Step 1: Check Interactive Flag
+```bash
+# Skip this entire phase if --interactive flag is not present
+IF NOT --interactive:
+    SKIP to Phase 2
+    IF refine_mode:
+        REPORT: "ℹ️ Non-interactive refinement mode: Will apply all suggested refinements"
+    ELSE:
+        REPORT: "ℹ️ Non-interactive mode: Will generate all {variants_count} variants"
+
+REPORT: "🎯 Interactive mode enabled: User selection required"
+```
+
+### Step 2: Load and Present Options (Mode-Specific)
 ```bash
 # Read options file
 options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
 
-# Parse design directions
-design_directions = options.design_directions
+# Branch based on mode
+IF NOT refine_mode:
+    # EXPLORATION MODE
+    design_directions = options.design_directions
+ELSE:
+    # REFINEMENT MODE
+    refinement_options = options.refinement_options
 ```
 
-### Step 2: Present Options to User
+### Step 3: Present Options to User (Mode-Specific)
+
+**Exploration Mode**:
 ```
 📋 Design Direction Options
 
@@ -263,14 +369,39 @@ Please select the direction(s) you'd like to develop into complete design system
 ═══════════════════════════════════════════════════
 ```
 
-### Step 3: Capture User Selection
+**Refinement Mode**:
+```
+📋 Design Refinement Options
+
+We've analyzed your existing design system and generated refinement options.
+Please select the refinement(s) you'd like to apply.
+
+Base Design: style-1
+
+{FOR each option in refinement_options grouped by category:
+  ━━━ {category_name} ━━━
+
+  {FOR each refinement in category_options:
+    [{refinement.option_id}] {refinement.label}
+    {refinement.description}
+    Preview: {refinement.preview_changes}
+    Affects: {refinement.impact_scope}
+  }
+}
+
+═══════════════════════════════════════════════════
+```
+
+### Step 4: Capture User Selection and Update Analysis JSON
+
+**Exploration Mode Interaction**:
 ```javascript
-// Use AskUserQuestion tool for selection
+// Use AskUserQuestion tool for multi-selection
 AskUserQuestion({
   questions: [{
-    question: "Which design direction would you like to develop into a complete design system?",
+    question: "Which design direction(s) would you like to develop into complete design systems?",
     header: "Style Choice",
-    multiSelect: false,  // Single selection for Phase 1
+    multiSelect: true,  // Multi-selection enabled
     options: [
       {FOR each direction:
         label: "Option {direction.index}: {direction.philosophy_name}",
@@ -280,142 +411,187 @@ AskUserQuestion({
   }]
 })
 
-// Parse user response (e.g., "Option 1: Minimalist & Airy")
-selected_option_text = user_answer
+// Parse user response (array of selections)
+selected_options = user_answer
 
 // Check for user cancellation
-IF selected_option_text == null OR selected_option_text == "":
+IF selected_options == null OR selected_options.length == 0:
     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
-```
+// Extract option indices
+selected_indices = []
+FOR each selected_option_text IN selected_options:
+    match = selected_option_text.match(/Option (\d+):/)
+    IF match:
+        selected_indices.push(parseInt(match[1]))
 
-### 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
-  }
+REPORT: "✅ Selected {selected_indices.length} design direction(s)"
+
+// Update analysis-options.json
+options_file = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": NOW(),
+  "selected_indices": selected_indices,
+  "selection_count": selected_indices.length
 }
-
-# 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")
+Write({base_path}/.intermediates/style-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
 ```
 
-### Step 5: Confirmation Message
+**Refinement Mode Interaction**:
+```javascript
+// Use AskUserQuestion tool for multi-selection of refinements
+AskUserQuestion({
+  questions: [{
+    question: "Which refinement(s) would you like to apply to your design system?",
+    header: "Refinements",
+    multiSelect: true,  // Multi-selection enabled
+    options: [
+      {FOR each refinement:
+        label: "{refinement.label}",
+        description: "{refinement.description} (Affects: {refinement.impact_scope})"
+      }
+    ]
+  }]
+})
+
+// Parse user response
+selected_refinements = user_answer
+
+// Check for user cancellation
+IF selected_refinements == null OR selected_refinements.length == 0:
+    REPORT: "⚠️ User canceled selection. Workflow terminated."
+    EXIT workflow
+
+// Extract refinement option_ids
+selected_option_ids = []
+FOR each selected_text IN selected_refinements:
+    # Match against refinement labels to find option_ids
+    FOR each refinement IN refinement_options:
+        IF refinement.label IN selected_text:
+            selected_option_ids.push(refinement.option_id)
+
+REPORT: "✅ Selected {selected_option_ids.length} refinement(s)"
+
+// Update analysis-options.json
+options_file = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": NOW(),
+  "selected_option_ids": selected_option_ids,
+  "selection_count": selected_option_ids.length
+}
+Write({base_path}/.intermediates/style-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
+```
+
+### Step 5: Confirmation Message (Mode-Specific)
+
+**Exploration Mode**:
 ```
 ✅ Selection recorded!
 
-You selected: Option {selected_index} - {selected_direction.philosophy_name}
+You selected {selected_indices.length} design direction(s):
+{FOR each index IN selected_indices:
+  • Option {index} - {design_directions[index-1].philosophy_name}
+}
 
-Proceeding to generate complete design system based on your selection...
+Proceeding to generate {selected_indices.length} complete design system(s)...
 ```
 
-**Output**: `user-selection.json` with user's choice
+**Refinement Mode**:
+```
+✅ Selection recorded!
+
+You selected {selected_option_ids.length} refinement(s):
+{FOR each id IN selected_option_ids:
+  • {refinement_by_id[id].label} ({refinement_by_id[id].category})
+}
+
+Proceeding to apply refinements and generate updated design system...
+```
+
+**Output**: Updated `analysis-options.json` with user's selection embedded
 
 ## Phase 2: Design System Generation (Agent Task 2)
 
 **Executor**: `Task(ui-design-agent)` for selected variant(s)
 
-### Step 1: Load User Selection (Explore Mode)
+### Step 1: Load User Selection or Default to All
 ```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
+# Read analysis-options.json which may contain user_selection
+options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
 
-    # 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
+# Check if user_selection field exists (interactive mode)
+IF options.user_selection AND options.user_selection.selected_indices:
+    # Interactive mode: Use user-selected variants
+    selected_indices = options.user_selection.selected_indices  # Array of selected indices (e.g., [1, 3])
 
-    # For Phase 1, we only allow single selection
-    selected_direction = selected_directions[0]
-    actual_variants_count = 1
+    REPORT: "🎯 Interactive mode: Using {selected_indices.length} user-selected variant(s)"
 ELSE:
-    # Imitate mode - generate single variant without selection
-    selected_direction = null
-    actual_variants_count = 1
+    # Non-interactive mode: Generate ALL variants (default behavior)
+    selected_indices = [1, 2, ..., variants_count]  # All indices from 1 to variants_count
+
+    REPORT: "ℹ️ Non-interactive mode: Generating all {variants_count} variant(s)"
+
+# Extract the selected direction details from options
+selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed array
+
+actual_variants_count = selected_indices.length
+REPORT: "📦 Generating {actual_variants_count} design system(s)..."
 ```
 
-### Step 2: Create Output Directory
+### Step 2: Create Output Directories
 ```bash
-# Create directory for selected variant only
-bash(mkdir -p {base_path}/style-extraction/style-1)
+# Create directories for each selected variant
+FOR index IN 1..actual_variants_count:
+    bash(mkdir -p {base_path}/style-extraction/style-{index})
 ```
 
-### Step 3: Launch Agent Task
-Generate design system for selected direction:
+### Step 3: Launch Agent Tasks (Parallel)
+Generate design systems for ALL selected directions in parallel (max 5 concurrent):
+
 ```javascript
-Task(ui-design-agent): `
-  [DESIGN_SYSTEM_GENERATION_TASK]
-  Generate production-ready design system based on user-selected direction
+// Launch parallel tasks, one for each selected direction
+FOR variant_index IN 1..actual_variants_count:
+    selected_direction = selected_directions[variant_index - 1]  // 0-indexed
 
-  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+    Task(ui-design-agent): `
+      [DESIGN_SYSTEM_GENERATION_TASK #{variant_index}/{actual_variants_count}]
+      Generate production-ready design system based on user-selected direction
 
-  ${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}
+      SESSION: {session_id} | VARIANT: {variant_index}/{actual_variants_count} | BASE_PATH: {base_path}
 
-  ${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 : ""}
-  ` : ""}
-  ` : ""}
+      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}
 
-  ## 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)" : ""}
+      ## 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
+      ## Generation Rules
+      - 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
+      - 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/
+      ## Generate
+      Create complete design system in {base_path}/style-extraction/style-{variant_index}/
 
   1. **design-tokens.json**:
      - Complete token structure with ALL fields:
@@ -433,29 +609,15 @@ Task(ui-design-agent): `
      ${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
      - Common Tailwind CSS usage patterns in project (if extracting from existing project)
 
-  2. **style-guide.md**:
-     - Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
-     - Complete color system documentation with accessibility notes
-     - Typography scale and usage guidelines
-     - Typography Combinations section: Document each preset (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) with usage context and code examples
-     - Spacing system explanation
-     - Opacity & Transparency section: Opacity scale usage, common use cases (disabled states, overlays, hover effects), accessibility considerations
-     - Shadows & Elevation section: Shadow hierarchy and semantic usage
-     - Component Styles section: Document button, card, and input variants with code examples and visual descriptions
-     - Border Radius system and semantic usage
-     - Component examples and usage patterns
-     - Common Tailwind CSS patterns (if applicable)
-
   ## Critical Requirements
   - ✅ Use Write() tool immediately for each file
-  - ✅ Write to style-1/ directory (single output)
-  - ❌ NO external research or MCP calls (pure AI generation)
+  - ✅ Write to style-{variant_index}/ directory
+  - ✅ Can use Exa MCP to research modern design patterns and obtain code examples (Explore/Text mode)
   - ✅ 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
+**Output**: {actual_variants_count} parallel agent tasks generate design-tokens.json for each variant
 
 ## Phase 3: Verify Output
 
@@ -513,15 +675,14 @@ Design Direction Selection:
 
 Generated Files:
 {base_path}/style-extraction/
-└── style-1/ (design-tokens.json, style-guide.md)
+└── style-1/design-tokens.json
 
 {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)
+{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options + user selection)
 }
 
 Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
@@ -533,7 +694,7 @@ Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Expand image pattern
 bash(ls {images_pattern})
@@ -559,8 +720,10 @@ bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colo
 # Load brainstorming context
 bash(test -f .brainstorming/role analysis documents && cat it)
 
-# Create directories
-bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
+# Create directories (example for multiple variants)
+bash(mkdir -p {base_path}/style-extraction/style-1)
+bash(mkdir -p {base_path}/style-extraction/style-2)
+bash(mkdir -p {base_path}/style-extraction/style-3)
 
 # Verify output
 bash(ls {base_path}/style-extraction/style-1/)
@@ -574,12 +737,10 @@ bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json &&
 ├── .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)
+│       └── analysis-options.json    # Design direction options + user selection (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
+        └── design-tokens.json       # Production-ready design tokens
 ```
 
 ## design-tokens.json Format
@@ -662,10 +823,4 @@ ERROR: Claude JSON parsing error
 - **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-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 extracts visual style (colors, typography, spacing) and generates production-ready design systems. For layout structure extraction, use `/workflow:ui-design:layout-extract`.

.claude/skills/command-guide/reference/commands/workflow/ui-design/update.md

@@ -28,7 +28,7 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
 
 # Verify design artifacts in latest design run
-latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-run-*")
 
 # Detect design system structure
 IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
@@ -89,8 +89,8 @@ Update `.brainstorming/role analysis documents` with design system references.
 ## UI/UX Guidelines
 
 ### Design System Reference
-**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../design-{run_id}/{style_guide_path}
+**Finalized Design Tokens**: @../{design_id}/{design_tokens_path}
+**Style Guide**: @../{design_id}/{style_guide_path}
 **Design System Mode**: {design_system_mode}
 
 ### Implementation Requirements
@@ -101,12 +101,12 @@ Update `.brainstorming/role analysis documents` with design system references.
 
 ### Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
+- **{page_name}**: @../{design_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
 }
 
 ### Design System Assets
 ```json
-{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
+{"design_tokens": "{design_id}/{design_tokens_path}", "style_guide": "{design_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "{design_id}/prototypes/{prototype}.html"}]}
 ```
 ```
 
@@ -145,9 +145,9 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Design System Implementation Reference
 
-**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../../design-{run_id}/{style_guide_path}
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Design Tokens**: @../../{design_id}/{design_tokens_path}
+**Style Guide**: @../../{design_id}/{style_guide_path}
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -156,8 +156,8 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Animation & Interaction Reference
 
-**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Animations**: @../../{design_id}/animation-extraction/animation-tokens.json
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -166,7 +166,7 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Layout Structure Reference
 
-**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
+**Layout Templates**: @../../{design_id}/layout-extraction/layout-templates.json
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -175,7 +175,7 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Prototype Validation Reference
 
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -197,8 +197,8 @@ Create or update `.brainstorming/ui-designer/design-system-reference.md`:
 ## Design System Integration
 This style guide references the finalized design system from the design refinement phase.
 
-**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Design Tokens**: @../../{design_id}/{design_tokens_path}
+**Style Guide**: @../../{design_id}/{style_guide_path}
 **Design System Mode**: {design_system_mode}
 
 ## Implementation Guidelines
@@ -209,13 +209,13 @@ This style guide references the finalized design system from the design refineme
 
 ## Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
+- **{page_name}**: @../../{design_id}/prototypes/{prototype}.html
 }
 
 ## Token System
 For complete token definitions and usage examples, see:
-- Design Tokens: @../../design-{run_id}/{design_tokens_path}
-- Style Guide: @../../design-{run_id}/{style_guide_path}
+- Design Tokens: @../../{design_id}/{design_tokens_path}
+- Style Guide: @../../{design_id}/{style_guide_path}
 
 ---
 *Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
@@ -271,24 +271,24 @@ Next: /workflow:plan [--agent] "<task description>"
 
 **@ Reference Format** (role analysis documents):
 ```
-@../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../design-{run_id}/style-extraction/style-1/style-guide.md
-@../design-{run_id}/prototypes/{prototype}.html
+@../{design_id}/style-extraction/style-1/design-tokens.json
+@../{design_id}/style-extraction/style-1/style-guide.md
+@../{design_id}/prototypes/{prototype}.html
 ```
 
 **@ Reference Format** (ui-designer/design-system-reference.md):
 ```
-@../../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../../design-{run_id}/style-extraction/style-1/style-guide.md
-@../../design-{run_id}/prototypes/{prototype}.html
+@../../{design_id}/style-extraction/style-1/design-tokens.json
+@../../{design_id}/style-extraction/style-1/style-guide.md
+@../../{design_id}/prototypes/{prototype}.html
 ```
 
 **@ Reference Format** (role analysis.md files):
 ```
-@../../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../../design-{run_id}/animation-extraction/animation-tokens.json
-@../../design-{run_id}/layout-extraction/layout-templates.json
-@../../design-{run_id}/prototypes/{prototype}.html
+@../../{design_id}/style-extraction/style-1/design-tokens.json
+@../../{design_id}/animation-extraction/animation-tokens.json
+@../../{design_id}/layout-extraction/layout-templates.json
+@../../{design_id}/prototypes/{prototype}.html
 ```
 
 ## Integration with /workflow:plan
@@ -307,9 +307,9 @@ After this update, `/workflow:plan` will discover design assets through:
   "task_id": "IMPL-001",
   "context": {
     "design_system": {
-      "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"]
+      "tokens": "{design_id}/style-extraction/style-1/design-tokens.json",
+      "style_guide": "{design_id}/style-extraction/style-1/style-guide.md",
+      "prototypes": ["{design_id}/prototypes/dashboard-variant-1.html"]
     }
   }
 }

.claude/workflows/intelligent-tools-strategy.md

@@ -42,12 +42,9 @@ codex -C [dir] --full-auto exec "[prompt]" [-m model] [--skip-git-repo-check -s
 ### Model Selection
 
 **Gemini**:
-- `gemini-3-pro-preview-11-2025` - Analysis (default, preferred)
-- `gemini-2.5-pro` - Analysis (alternative)
+- `gemini-2.5-pro` - Analysis (default)
 - `gemini-2.5-flash` - Documentation updates
 
-**Error Handling**: If `gemini-3-pro-preview-11-2025` returns 404 error, fallback to `gemini-2.5-pro`
-
 **Qwen**:
 - `coder-model` - Code analysis (default)
 - `vision-model` - Image analysis (rare)
@@ -128,7 +125,6 @@ codex -C [dir] --full-auto exec "[prompt]" [-m model] [--skip-git-repo-check -s
 
 **Error Handling**:
 - **HTTP 429**: May show error but still return results - check if results exist (results present = success, no results = retry/fallback to Qwen)
-- **HTTP 404**: If `gemini-3-pro-preview-11-2025` returns 404, fallback to `gemini-2.5-pro`
 
 ### Codex
 
@@ -244,14 +240,14 @@ Use the **[Standard Prompt Template](#standard-prompt-template)** for all tools.
 - **Tool**: `gemini` (primary) | `qwen` (fallback)
 - **Prompt**: `-p "[Standard Prompt Template]"` (prompt BEFORE options)
 - **Model**: `-m [model-name]` (optional, placed AFTER prompt)
-  - Gemini: `gemini-3-pro-preview-11-2025` (default) | `gemini-2.5-pro` | `gemini-2.5-flash`
+  - Gemini: `gemini-2.5-pro` (default) | `gemini-2.5-flash`
   - Qwen: `coder-model` (default) | `vision-model`
 - **Write Permission**: `--approval-mode yolo` (ONLY for MODE=write, placed AFTER prompt)
 
 **Command Examples**:
 ```bash
 # Analysis Mode (default, read-only)
-cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-3-pro-preview-11-2025
+cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-2.5-pro
 
 # Write Mode (requires MODE=write in template + --approval-mode yolo)
 cd [directory] && gemini -p "[Standard Prompt Template with MODE: write]" -m gemini-2.5-flash --approval-mode yolo
@@ -260,7 +256,7 @@ cd [directory] && gemini -p "[Standard Prompt Template with MODE: write]" -m gem
 cd [directory] && qwen -p "[Standard Prompt Template]" -m coder-model
 
 # Multi-directory support
-cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-3-pro-preview-11-2025 --include-directories ../shared,../types
+cd [directory] && gemini -p "[Standard Prompt Template]" -m gemini-2.5-pro --include-directories ../shared,../types
 ```
 
 #### Codex
@@ -333,7 +329,7 @@ codex --full-auto exec "Add JWT refresh token validation" resume --last --skip-g
 2. Explicitly reference external files in CONTEXT field with @ patterns
 3. ⚠️ BOTH steps are MANDATORY
 
-Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-3-pro-preview-11-2025 --include-directories ../shared`
+Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-2.5-pro --include-directories ../shared`
 
 **Rule**: If CONTEXT contains `@../dir/**/*`, command MUST include `--include-directories ../dir`
 
@@ -348,10 +344,10 @@ Example: `cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" -m gemini-3-
 **Syntax**:
 ```bash
 # Comma-separated format
-gemini -p "prompt" -m gemini-3-pro-preview-11-2025 --include-directories /path/to/project1,/path/to/project2
+gemini -p "prompt" -m gemini-2.5-pro --include-directories /path/to/project1,/path/to/project2
 
 # Multiple flags format
-gemini -p "prompt" -m gemini-3-pro-preview-11-2025 --include-directories /path/to/project1 --include-directories /path/to/project2
+gemini -p "prompt" -m gemini-2.5-pro --include-directories /path/to/project1 --include-directories /path/to/project2
 
 # Recommended: cd + --include-directories
 cd src/auth && gemini -p "
@@ -361,7 +357,7 @@ MODE: analysis
 CONTEXT: @**/* @../shared/**/* @../types/**/*
 EXPECTED: Complete analysis with cross-directory dependencies
 RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on integration patterns | analysis=READ-ONLY
-" -m gemini-3-pro-preview-11-2025 --include-directories ../shared,../types
+" -m gemini-2.5-pro --include-directories ../shared,../types
 ```
 
 **Best Practices**:
@@ -449,7 +445,7 @@ MODE: analysis
 CONTEXT: @components/Auth.tsx @types/auth.d.ts @hooks/useAuth.ts | Memory: Previous refactoring identified type inconsistencies, following React hooks patterns, related implementation in @hooks/useAuth.ts (commit abc123)
 EXPECTED: Comprehensive analysis report with type safety recommendations, code examples, and references to previous findings
 RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on type safety and component composition | analysis=READ-ONLY
-" -m gemini-3-pro-preview-11-2025
+" -m gemini-2.5-pro
 ```
 
 ### RULES Field Configuration

.claude/workflows/workflow-architecture.md

@@ -686,8 +686,8 @@ All workflows use the same file structure definition regardless of complexity. *
 │   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
 │   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
 │
-├── [.design/]                  # Standalone UI design outputs (created when needed)
-│   └── run-[timestamp]/        # Timestamped design runs without session
+├── [design-run-*/]             # Standalone UI design outputs (created when needed)
+│   └── (timestamped)/          # Timestamped design runs without session
 │       ├── .intermediates/     # Intermediate analysis files
 │       │   ├── style-analysis/ # Style analysis data
 │       │   │   ├── computed-styles.json        # Extracted CSS values
@@ -749,7 +749,7 @@ All workflows use the same file structure definition regardless of complexity. *
 - **On-Demand Creation**: Other directories created when first needed
 - **Dynamic Files**: Subtask JSON files created during task decomposition
 - **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
-- **Design Usage**: `design-{timestamp}/` created by UI design workflows, `.design/` for standalone design runs
+- **Design Usage**: `design-{timestamp}/` created by UI design workflows in `.workflow/` directly for standalone design runs
 - **Intermediate Files**: `.intermediates/` contains analysis data (style/layout) separate from final deliverables
 - **Layout Templates**: `layout-extraction/layout-templates.json` contains structural templates for UI assembly
 

COMMAND_REFERENCE.md

@@ -87,7 +87,6 @@ These commands orchestrate complex, multi-phase development processes, from plan
 |---|---|
 | `/workflow:ui-design:explore-auto` | Exploratory UI design workflow with style-centric batch generation. |
 | `/workflow:ui-design:imitate-auto` | High-speed multi-page UI replication with batch screenshot capture. |
-| `/workflow:ui-design:batch-generate` | Prompt-driven batch UI generation using target-style-centric parallel execution. |
 | `/workflow:ui-design:capture` | Batch screenshot capture for UI design workflows using MCP or local fallback. |
 | `/workflow:ui-design:explore-layers` | Interactive deep UI capture with depth-controlled layer exploration. |
 | `/workflow:ui-design:style-extract` | Extract design style from reference images or text prompts using Claude's analysis. |

COMMAND_SPEC.md

@@ -375,15 +375,6 @@ Specialized workflow for UI/UX design, from style extraction to prototype genera
   /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
   ```
 
-### **/workflow:ui-design:batch-generate**
-- **Syntax**: `/workflow:ui-design:batch-generate [--prompt "..."] [--targets "..."] ...`
-- **Responsibilities**: Prompt-driven batch UI generation with parallel execution for multiple targets and styles.
-- **Agent Calls**: `@ui-design-agent`.
-- **Example**:
-  ```bash
-  /workflow:ui-design:batch-generate --prompt "Dashboard with metric cards and charts"
-  ```
-
 ### **/workflow:ui-design:capture**
 - **Syntax**: `/workflow:ui-design:capture --url-map "target:url,..." ...`
 - **Responsibilities**: Batch screenshot capture tool using MCP Chrome DevTools with multi-tier fallback strategy (MCP → Playwright → Chrome → Manual).

Install-Claude.ps1

@@ -646,6 +646,37 @@ function Backup-AndReplaceDirectory {
     return $true
 }
 
+function Backup-CriticalConfigFiles {
+    param(
+        [string]$TargetDirectory,
+        [string]$BackupFolder,
+        [string[]]$FileNames
+    )
+
+    if (-not $BackupFolder -or $NoBackup) {
+        return
+    }
+
+    if (-not (Test-Path $TargetDirectory)) {
+        return
+    }
+
+    $backedUpCount = 0
+    foreach ($fileName in $FileNames) {
+        $filePath = Join-Path $TargetDirectory $fileName
+        if (Test-Path $filePath) {
+            if (Backup-FileToFolder -FilePath $filePath -BackupFolder $BackupFolder) {
+                Write-ColorOutput "Critical config backed up: $fileName" $ColorSuccess
+                $backedUpCount++
+            }
+        }
+    }
+
+    if ($backedUpCount -gt 0) {
+        Write-ColorOutput "Backed up $backedUpCount critical configuration file(s)" $ColorInfo
+    }
+}
+
 function Merge-DirectoryContents {
     param(
         [string]$Source,
@@ -1227,9 +1258,9 @@ function Install-Global {
         }
     }
 
-    # Replace .claude directory (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .claude directory..." $ColorInfo
-    $claudeInstalled = Backup-AndReplaceDirectory -Source $sourceClaudeDir -Destination $globalClaudeDir -Description ".claude directory" -BackupFolder $backupFolder
+    # Merge .claude directory (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .claude directory (incremental merge)..." $ColorInfo
+    $claudeInstalled = Merge-DirectoryContents -Source $sourceClaudeDir -Destination $globalClaudeDir -Description ".claude directory" -BackupFolder $backupFolder
 
     # Track .claude directory in manifest
     if ($claudeInstalled) {
@@ -1253,9 +1284,12 @@ function Install-Global {
         Add-ManifestEntry -Manifest $manifest -Path $globalClaudeMd -Type "File"
     }
 
-    # Replace .codex directory (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .codex directory..." $ColorInfo
-    $codexInstalled = Backup-AndReplaceDirectory -Source $sourceCodexDir -Destination $globalCodexDir -Description ".codex directory" -BackupFolder $backupFolder
+    # Backup critical config files in .codex directory before installation
+    Backup-CriticalConfigFiles -TargetDirectory $globalCodexDir -BackupFolder $backupFolder -FileNames @("AGENTS.md")
+
+    # Merge .codex directory (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .codex directory (incremental merge)..." $ColorInfo
+    $codexInstalled = Merge-DirectoryContents -Source $sourceCodexDir -Destination $globalCodexDir -Description ".codex directory" -BackupFolder $backupFolder
 
     # Track .codex directory in manifest
     if ($codexInstalled) {
@@ -1268,9 +1302,12 @@ function Install-Global {
         }
     }
 
-    # Replace .gemini directory (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .gemini directory..." $ColorInfo
-    $geminiInstalled = Backup-AndReplaceDirectory -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
+    # Backup critical config files in .gemini directory before installation
+    Backup-CriticalConfigFiles -TargetDirectory $globalGeminiDir -BackupFolder $backupFolder -FileNames @("GEMINI.md", "CLAUDE.md")
+
+    # Merge .gemini directory (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .gemini directory (incremental merge)..." $ColorInfo
+    $geminiInstalled = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
 
     # Track .gemini directory in manifest
     if ($geminiInstalled) {
@@ -1283,9 +1320,12 @@ function Install-Global {
         }
     }
 
-    # Replace .qwen directory (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .qwen directory..." $ColorInfo
-    $qwenInstalled = Backup-AndReplaceDirectory -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
+    # Backup critical config files in .qwen directory before installation
+    Backup-CriticalConfigFiles -TargetDirectory $globalQwenDir -BackupFolder $backupFolder -FileNames @("QWEN.md")
+
+    # Merge .qwen directory (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .qwen directory (incremental merge)..." $ColorInfo
+    $qwenInstalled = Merge-DirectoryContents -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
 
     # Track .qwen directory in manifest
     if ($qwenInstalled) {
@@ -1372,9 +1412,9 @@ function Install-Path {
         $destFolderPath = Join-Path $localClaudeDir $folder
 
         if (Test-Path $sourceFolderPath) {
-            # Use new backup and replace logic for local folders
-            Write-ColorOutput "Installing local folder: $folder..." $ColorInfo
-            $folderInstalled = Backup-AndReplaceDirectory -Source $sourceFolderPath -Destination $destFolderPath -Description "$folder folder" -BackupFolder $backupFolder
+            # Use incremental merge for local folders (preserves user customizations)
+            Write-ColorOutput "Installing local folder: $folder (incremental merge)..." $ColorInfo
+            $folderInstalled = Merge-DirectoryContents -Source $sourceFolderPath -Destination $destFolderPath -Description "$folder folder" -BackupFolder $backupFolder
             Write-ColorOutput "Installed local folder: $folder" $ColorSuccess
 
             # Track local folder in manifest
@@ -1461,9 +1501,12 @@ function Install-Path {
         Add-ManifestEntry -Manifest $manifest -Path $globalClaudeMd -Type "File"
     }
 
-    # Replace .codex directory to local location (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .codex directory to local location..." $ColorInfo
-    $codexInstalled = Backup-AndReplaceDirectory -Source $sourceCodexDir -Destination $localCodexDir -Description ".codex directory" -BackupFolder $backupFolder
+    # Backup critical config files in .codex directory before installation
+    Backup-CriticalConfigFiles -TargetDirectory $localCodexDir -BackupFolder $backupFolder -FileNames @("AGENTS.md")
+
+    # Merge .codex directory to local location (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .codex directory to local location (incremental merge)..." $ColorInfo
+    $codexInstalled = Merge-DirectoryContents -Source $sourceCodexDir -Destination $localCodexDir -Description ".codex directory" -BackupFolder $backupFolder
 
     # Track .codex directory in manifest
     if ($codexInstalled) {
@@ -1476,9 +1519,12 @@ function Install-Path {
         }
     }
 
-    # Replace .gemini directory to local location (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .gemini directory to local location..." $ColorInfo
-    $geminiInstalled = Backup-AndReplaceDirectory -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
+    # Backup critical config files in .gemini directory before installation
+    Backup-CriticalConfigFiles -TargetDirectory $localGeminiDir -BackupFolder $backupFolder -FileNames @("GEMINI.md", "CLAUDE.md")
+
+    # Merge .gemini directory to local location (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .gemini directory to local location (incremental merge)..." $ColorInfo
+    $geminiInstalled = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
 
     # Track .gemini directory in manifest
     if ($geminiInstalled) {
@@ -1491,9 +1537,12 @@ function Install-Path {
         }
     }
 
-    # Replace .qwen directory to local location (backup → clear → copy entire folder)
-    Write-ColorOutput "Installing .qwen directory to local location..." $ColorInfo
-    $qwenInstalled = Backup-AndReplaceDirectory -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
+    # Backup critical config files in .qwen directory before installation
+    Backup-CriticalConfigFiles -TargetDirectory $localQwenDir -BackupFolder $backupFolder -FileNames @("QWEN.md")
+
+    # Merge .qwen directory to local location (incremental overlay - preserves user files)
+    Write-ColorOutput "Installing .qwen directory to local location (incremental merge)..." $ColorInfo
+    $qwenInstalled = Merge-DirectoryContents -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
 
     # Track .qwen directory in manifest
     if ($qwenInstalled) {

Install-Claude.sh

@@ -344,6 +344,36 @@ function copy_file_to_destination() {
     fi
 }
 
+function backup_critical_config_files() {
+    local target_directory="$1"
+    local backup_folder="$2"
+    shift 2
+    local file_names=("$@")
+
+    if [ "$NO_BACKUP" = true ] || [ -z "$backup_folder" ]; then
+        return 0
+    fi
+
+    if [ ! -d "$target_directory" ]; then
+        return 0
+    fi
+
+    local backed_up_count=0
+    for file_name in "${file_names[@]}"; do
+        local file_path="${target_directory}/${file_name}"
+        if [ -f "$file_path" ]; then
+            if backup_file_to_folder "$file_path" "$backup_folder"; then
+                write_color "Critical config backed up: $file_name" "$COLOR_SUCCESS"
+                ((backed_up_count++))
+            fi
+        fi
+    done
+
+    if [ "$backed_up_count" -gt 0 ]; then
+        write_color "Backed up $backed_up_count critical configuration file(s)" "$COLOR_INFO"
+    fi
+}
+
 function backup_and_replace_directory() {
     local source="$1"
     local destination="$2"
@@ -512,9 +542,9 @@ function install_global() {
         fi
     fi
 
-    # Replace .claude directory (backup → clear conflicting → copy)
-    write_color "Installing .claude directory..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_claude_dir" "$global_claude_dir" ".claude directory" "$backup_folder"; then
+    # Merge .claude directory (incremental overlay - preserves user files)
+    write_color "Installing .claude directory (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_claude_dir" "$global_claude_dir" ".claude directory" "$backup_folder"; then
         # Track .claude directory in manifest
         add_manifest_entry "$manifest_file" "$global_claude_dir" "Directory"
 
@@ -533,9 +563,12 @@ function install_global() {
         add_manifest_entry "$manifest_file" "$global_claude_md" "File"
     fi
 
-    # Replace .codex directory (backup → clear conflicting → copy)
-    write_color "Installing .codex directory..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_codex_dir" "$global_codex_dir" ".codex directory" "$backup_folder"; then
+    # Backup critical config files in .codex directory before installation
+    backup_critical_config_files "$global_codex_dir" "$backup_folder" "AGENTS.md"
+
+    # Merge .codex directory (incremental overlay - preserves user files)
+    write_color "Installing .codex directory (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_codex_dir" "$global_codex_dir" ".codex directory" "$backup_folder"; then
         # Track .codex directory in manifest
         add_manifest_entry "$manifest_file" "$global_codex_dir" "Directory"
 
@@ -547,9 +580,12 @@ function install_global() {
         done < <(find "$source_codex_dir" -type f -print0)
     fi
 
-    # Replace .gemini directory (backup → clear conflicting → copy)
-    write_color "Installing .gemini directory..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_gemini_dir" "$global_gemini_dir" ".gemini directory" "$backup_folder"; then
+    # Backup critical config files in .gemini directory before installation
+    backup_critical_config_files "$global_gemini_dir" "$backup_folder" "GEMINI.md" "CLAUDE.md"
+
+    # Merge .gemini directory (incremental overlay - preserves user files)
+    write_color "Installing .gemini directory (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_gemini_dir" "$global_gemini_dir" ".gemini directory" "$backup_folder"; then
         # Track .gemini directory in manifest
         add_manifest_entry "$manifest_file" "$global_gemini_dir" "Directory"
 
@@ -561,9 +597,12 @@ function install_global() {
         done < <(find "$source_gemini_dir" -type f -print0)
     fi
 
-    # Replace .qwen directory (backup → clear conflicting → copy)
-    write_color "Installing .qwen directory..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_qwen_dir" "$global_qwen_dir" ".qwen directory" "$backup_folder"; then
+    # Backup critical config files in .qwen directory before installation
+    backup_critical_config_files "$global_qwen_dir" "$backup_folder" "QWEN.md"
+
+    # Merge .qwen directory (incremental overlay - preserves user files)
+    write_color "Installing .qwen directory (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_qwen_dir" "$global_qwen_dir" ".qwen directory" "$backup_folder"; then
         # Track .qwen directory in manifest
         add_manifest_entry "$manifest_file" "$global_qwen_dir" "Directory"
 
@@ -642,9 +681,9 @@ function install_path() {
         local dest_folder="${local_claude_dir}/${folder}"
 
         if [ -d "$source_folder" ]; then
-            # Use new backup and replace logic for local folders
-            write_color "Installing local folder: $folder..." "$COLOR_INFO"
-            if backup_and_replace_directory "$source_folder" "$dest_folder" "$folder folder" "$backup_folder"; then
+            # Use incremental merge for local folders (preserves user customizations)
+            write_color "Installing local folder: $folder (incremental merge)..." "$COLOR_INFO"
+            if merge_directory_contents "$source_folder" "$dest_folder" "$folder folder" "$backup_folder"; then
                 # Track local folder in manifest
                 add_manifest_entry "$manifest_file" "$dest_folder" "Directory"
 
@@ -715,9 +754,12 @@ function install_path() {
         add_manifest_entry "$manifest_file" "$global_claude_md" "File"
     fi
 
-    # Replace .codex directory to local location (backup → clear conflicting → copy)
-    write_color "Installing .codex directory to local location..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_codex_dir" "$local_codex_dir" ".codex directory" "$backup_folder"; then
+    # Backup critical config files in .codex directory before installation
+    backup_critical_config_files "$local_codex_dir" "$backup_folder" "AGENTS.md"
+
+    # Merge .codex directory to local location (incremental overlay - preserves user files)
+    write_color "Installing .codex directory to local location (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_codex_dir" "$local_codex_dir" ".codex directory" "$backup_folder"; then
         # Track .codex directory in manifest
         add_manifest_entry "$manifest_file" "$local_codex_dir" "Directory"
 
@@ -729,9 +771,12 @@ function install_path() {
         done < <(find "$source_codex_dir" -type f -print0)
     fi
 
-    # Replace .gemini directory to local location (backup → clear conflicting → copy)
-    write_color "Installing .gemini directory to local location..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_gemini_dir" "$local_gemini_dir" ".gemini directory" "$backup_folder"; then
+    # Backup critical config files in .gemini directory before installation
+    backup_critical_config_files "$local_gemini_dir" "$backup_folder" "GEMINI.md" "CLAUDE.md"
+
+    # Merge .gemini directory to local location (incremental overlay - preserves user files)
+    write_color "Installing .gemini directory to local location (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_gemini_dir" "$local_gemini_dir" ".gemini directory" "$backup_folder"; then
         # Track .gemini directory in manifest
         add_manifest_entry "$manifest_file" "$local_gemini_dir" "Directory"
 
@@ -743,9 +788,12 @@ function install_path() {
         done < <(find "$source_gemini_dir" -type f -print0)
     fi
 
-    # Replace .qwen directory to local location (backup → clear conflicting → copy)
-    write_color "Installing .qwen directory to local location..." "$COLOR_INFO"
-    if backup_and_replace_directory "$source_qwen_dir" "$local_qwen_dir" ".qwen directory" "$backup_folder"; then
+    # Backup critical config files in .qwen directory before installation
+    backup_critical_config_files "$local_qwen_dir" "$backup_folder" "QWEN.md"
+
+    # Merge .qwen directory to local location (incremental overlay - preserves user files)
+    write_color "Installing .qwen directory to local location (incremental merge)..." "$COLOR_INFO"
+    if merge_directory_contents "$source_qwen_dir" "$local_qwen_dir" ".qwen directory" "$backup_folder"; then
         # Track .qwen directory in manifest
         add_manifest_entry "$manifest_file" "$local_qwen_dir" "Directory"