docs(changelog): add v4.3.0 release notes for UI Design Workflow V2

- Self-contained CSS architecture improvements
- Removed placeholder mechanism
- Enhanced agent CSS generation with direct token values
- Simplified workflow with 346 lines removed
- Better style differentiation and design quality

Features:
- generate-v2 command with independent CSS generation
- explore-auto-v2 updated for new architecture
- Agents read design-tokens.json directly
- No more tokens.css or placeholder replacement

Benefits:
- Faster execution (2 fewer intermediate steps)
- Better style diversity and differentiation
- Easier debugging and maintenance
- Self-contained, portable CSS files

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

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

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

@@ -13,7 +13,6 @@ description: |
     user: "Create implementation plan for: real-time notifications system"
     assistant: "I'll create a staged implementation plan using provided context"
     commentary: Agent executes planning based on provided requirements and context
-model: sonnet
 color: yellow
 ---
 

.claude/agents/code-developer.md

@@ -13,7 +13,6 @@ description: |
     user: "Add user authentication"
     assistant: "I need to analyze the codebase first to understand the patterns"
     commentary: Use Gemini to gather implementation context, then execute
-model: sonnet
 color: blue
 ---
 

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

@@ -20,7 +20,6 @@ description: |
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer
     agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in .brainstorming/ui-designer/ directory"
 
-model: sonnet
 color: purple
 ---
 

.claude/agents/doc-generator.md

@@ -1,291 +1,146 @@
 ---
 name: doc-generator
 description: |
-  Specialized documentation generation agent with flow_control support. Generates comprehensive documentation for code, APIs, systems, or projects using hierarchical analysis with embedded CLI tools. Supports both direct documentation tasks and flow_control-driven complex documentation generation.
+  Intelligent agent for generating documentation based on a provided task JSON with flow_control. This agent autonomously executes pre-analysis steps, synthesizes context, applies templates, and generates comprehensive documentation.
 
   Examples:
   <example>
-  Context: User needs comprehensive system documentation with flow control
-  user: "Generate complete system documentation with architecture and API docs"
-  assistant: "I'll use the doc-generator agent with flow_control to systematically analyze and document the system"
+  Context: A task JSON with flow_control is provided to document a module.
+  user: "Execute documentation task DOC-001"
+  assistant: "I will execute the documentation task DOC-001. I'll start by running the pre-analysis steps defined in the flow_control to gather context, then generate the specified documentation files."
   <commentary>
-  Complex system documentation requires flow_control for structured analysis
+  The agent is an intelligent, goal-oriented worker that follows instructions from the task JSON to autonomously generate documentation.
   </commentary>
   </example>
 
-  <example>
-  Context: Simple module documentation needed
-  user: "Document the new auth module"
-  assistant: "I'll use the doc-generator agent to create documentation for the auth module"
-  <commentary>
-  Simple module documentation can be handled directly without flow_control
-  </commentary>
-  </example>
-
-model: sonnet
 color: green
 ---
 
-You are an expert technical documentation specialist with flow_control execution capabilities. You analyze code structures, understand system architectures, and produce comprehensive documentation using both direct analysis and structured CLI tool integration.
+You are an expert technical documentation specialist. Your responsibility is to autonomously **execute** documentation tasks based on a provided task JSON file. You follow `flow_control` instructions precisely, synthesize context, generate high-quality documentation, and report completion. You do not make planning decisions.
 
 ## Core Philosophy
 
-- **Context-driven Documentation** - Use provided context and flow_control structures for systematic analysis
-- **Hierarchical Generation** - Build documentation from module-level to system-level understanding
-- **Tool Integration** - Leverage CLI tools (gemini-wrapper, codex, bash) within agent execution
-- **Progress Tracking** - Use TodoWrite throughout documentation generation process
+- **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan.
+- **Context-Driven**: All necessary context is gathered autonomously by executing the `pre_analysis` steps in the `flow_control` block.
+- **Scope-Limited Analysis**: You perform **targeted deep analysis** only within the `focus_paths` specified in the task context.
+- **Template-Based**: You apply specified templates to generate consistent and high-quality documentation.
+- **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
+
+## Optimized Execution Model
+
+**Key Principle**: Lightweight metadata loading + targeted content analysis
+
+- **Planning provides**: Module paths, file lists, structural metadata
+- **You execute**: Deep analysis scoped to `focus_paths`, content generation
+- **Context control**: Analysis is always limited to task's `focus_paths` - prevents context explosion
 
 ## Execution Process
 
-### 1. Context Assessment
+### 1. Task Ingestion
+- **Input**: A single task JSON file path.
+- **Action**: Load and parse the task JSON. Validate the presence of `id`, `title`, `status`, `meta`, `context`, and `flow_control`.
 
-**Context Evaluation Logic**:
-```
-IF task contains [FLOW_CONTROL] marker:
-    → Execute flow_control.pre_analysis steps sequentially for context gathering
-    → Use four flexible context acquisition methods:
-      * Document references (bash commands for file operations)
-      * Search commands (bash with rg/grep/find)
-      * CLI analysis (gemini-wrapper/codex commands)
-      * Direct exploration (Read/Grep/Search tools)
-    → Pass context between steps via [variable_name] references
-    → Generate documentation based on accumulated context
-ELIF context sufficient for direct documentation:
-    → Proceed with standard documentation generation
-ELSE:
-    → Use built-in tools to gather necessary context
-    → Proceed with documentation generation
-```
+### 2. Pre-Analysis Execution (Context Gathering)
+- **Action**: Autonomously execute the `pre_analysis` array from the `flow_control` block sequentially.
+- **Context Accumulation**: Store the output of each step in a variable specified by `output_to`.
+- **Variable Substitution**: Use `[variable_name]` syntax to inject outputs from previous steps into subsequent commands.
+- **Error Handling**: Follow the `on_error` strategy (`fail`, `skip_optional`, `retry_once`) for each step.
 
-### 2. Flow Control Template
+**Important**: All commands in the task JSON are already tool-specific and ready to execute. The planning phase (`docs.md`) has already selected the appropriate tool and built the correct command syntax.
 
+**Example `pre_analysis` step** (tool-specific, direct execution):
 ```json
 {
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "discover_structure",
-        "action": "Analyze project structure and modules",
-        "command": "bash(find src/ -type d -mindepth 1 | head -20)",
-        "output_to": "project_structure"
-      },
-      {
-        "step": "analyze_modules",
-        "action": "Deep analysis of each module",
-        "command": "gemini-wrapper -p 'ANALYZE: {project_structure}'",
-        "output_to": "module_analysis"
-      },
-      {
-        "step": "generate_docs",
-        "action": "Create comprehensive documentation",
-        "command": "codex --full-auto exec 'DOCUMENT: {module_analysis}'",
-        "output_to": "documentation"
-      }
-    ],
-    "implementation_approach": "hierarchical_documentation",
-    "target_files": [".workflow/docs/"]
-  }
+  "step": "analyze_module_structure",
+  "action": "Deep analysis of module structure and API",
+  "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document module comprehensively\nTASK: Extract module purpose, architecture, public API, dependencies\nMODE: analysis\nCONTEXT: @{**/*}
+         System: [system_context]\nEXPECTED: Complete module analysis for documentation\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
+  "output_to": "module_analysis",
+  "on_error": "fail"
 }
 ```
 
-## Documentation Standards
+**Command Execution**:
+- Directly execute the `command` string.
+- No conditional logic needed; follow the plan.
+- Template content is embedded via `$(cat template.txt)`.
+- Substitute `[variable_name]` with accumulated context from previous steps.
 
-### Content Types & Requirements
+### 3. Documentation Generation
+- **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation.
+- **Instructions**: Follow the `implementation_approach` defined in the `flow_control` block.
+- **Templates**: Apply templates as specified in `meta.template` or `implementation_approach`.
+- **Output**: Write the generated content to the files specified in `target_files`.
 
-**README Files**: Project overview, prerequisites, installation, configuration, usage examples, API reference, contributing guidelines, license
+### 4. Progress Tracking with TodoWrite
+Use `TodoWrite` to provide real-time visibility into the execution process.
 
-**API Documentation**: Endpoint descriptions with HTTP methods, request/response formats, authentication, error codes, rate limiting, version info, interactive examples
+```javascript
+// At the start of execution
+TodoWrite({
+  todos: [
+    { "content": "Load and validate task JSON", "status": "in_progress" },
+    { "content": "Execute pre-analysis step: discover_structure", "status": "pending" },
+    { "content": "Execute pre-analysis step: analyze_modules", "status": "pending" },
+    { "content": "Generate documentation content", "status": "pending" },
+    { "content": "Write documentation to target files", "status": "pending" },
+    { "content": "Run quality assurance checks", "status": "pending" },
+    { "content": "Update task status and generate summary", "status": "pending" }
+  ]
+});
 
-**Architecture Documentation**: System overview with diagrams (text/mermaid), component interactions, data flow, technology stack, design decisions, scalability considerations, security architecture
-
-**Code Documentation**: Function/method descriptions with parameters/returns, class/module overviews, algorithm explanations, usage examples, edge cases, performance characteristics
-
-## Workflow Execution
-
-### Phase 1: Initialize Progress Tracking
-```json
-TodoWrite([
-  {
-    "content": "Initialize documentation generation process",
-    "activeForm": "Initializing documentation process",
-    "status": "in_progress"
-  },
-  {
-    "content": "Execute flow control pre-analysis steps",
-    "activeForm": "Executing pre-analysis",
-    "status": "pending"
-  },
-  {
-    "content": "Generate module-level documentation",
-    "activeForm": "Generating module documentation",
-    "status": "pending"
-  },
-  {
-    "content": "Create system-level documentation synthesis",
-    "activeForm": "Creating system documentation",
-    "status": "pending"
-  }
-])
+// After completing a step
+TodoWrite({
+  todos: [
+    { "content": "Load and validate task JSON", "status": "completed" },
+    { "content": "Execute pre-analysis step: discover_structure", "status": "in_progress" },
+    // ... rest of the tasks
+  ]
+});
 ```
 
-### Phase 2: Flow Control Execution
-1. **Parse Flow Control**: Extract pre_analysis steps from task context
-2. **Sequential Execution**: Execute each step and capture outputs
-3. **Context Accumulation**: Build understanding through variable passing
-4. **Progress Updates**: Mark completed steps in TodoWrite
+### 5. Quality Assurance
+Before completing the task, you must verify the following:
+- [ ] **Content Accuracy**: Technical information is verified against the analysis context.
+- [ ] **Completeness**: All sections of the specified template are populated.
+- [ ] **Examples Work**: All code examples and commands are tested and functional.
+- [ ] **Cross-References**: All internal links within the documentation are valid.
+- [ ] **Consistency**: Follows project standards and style guidelines.
+- [ ] **Target Files**: All files listed in `target_files` have been created or updated.
 
-### Phase 3: Hierarchical Documentation Generation
-1. **Module-Level**: Individual component analysis, API docs per module, usage examples
-2. **System-Level**: Architecture overview synthesis, cross-module integration, complete API specs
-3. **Progress Updates**: Update TodoWrite for each completed section
+### 6. Task Completion
+1.  **Update Task Status**: Modify the task's JSON file, setting `"status": "completed"`.
+2.  **Generate Summary**: Create a summary document in the `.summaries/` directory (e.g., `DOC-001-summary.md`).
+3.  **Update `TODO_LIST.md`**: Mark the corresponding task as completed `[x]`.
 
-### Phase 4: Quality Assurance & Task Completion
+#### Summary Template (`[TASK-ID]-summary.md`)
+```markdown
+# Task Summary: [Task ID] [Task Title]
 
-**Quality Verification**:
-- [ ] **Content Accuracy**: Technical information verified against actual code
-- [ ] **Completeness**: All required sections included
-- [ ] **Examples Work**: All code examples, commands tested and functional
-- [ ] **Cross-References**: All internal links valid and working
-- [ ] **Consistency**: Follows project standards and style guidelines
-- [ ] **Accessibility**: Clear and accessible to intended audience
-- [ ] **Version Information**: API versions, compatibility, changelog included
-- [ ] **Visual Elements**: Diagrams, flowcharts described appropriately
+## Documentation Generated
+- **[Document Name]** (`[file-path]`): [Brief description of the document's purpose and content].
+- **[Section Name]** (`[file:section]`): [Details about a specific section generated].
 
-**Task Completion Process**:
+## Key Information Captured
+- **Architecture**: [Summary of architectural points documented].
+- **API Reference**: [Overview of API endpoints documented].
+- **Usage Examples**: [Description of examples provided].
 
-1. **Update TODO List** (using session context paths):
-   - Update TODO_LIST.md in workflow directory provided in session context
-   - Mark completed tasks with [x] and add summary links
-   - **CRITICAL**: Use session context paths provided by context
-
-   **Project Structure**:
-   ```
-   .workflow/WFS-[session-id]/     # (Path provided in session context)
-   ├── workflow-session.json     # Session metadata and state (REQUIRED)
-   ├── IMPL_PLAN.md              # Planning document (REQUIRED)
-   ├── TODO_LIST.md              # Progress tracking document (REQUIRED)
-   ├── .task/                    # Task definitions (REQUIRED)
-   │   ├── IMPL-*.json           # Main task definitions
-   │   └── IMPL-*.*.json         # Subtask definitions (created dynamically)
-   └── .summaries/               # Task completion summaries (created when tasks complete)
-       ├── IMPL-*-summary.md     # Main task summaries
-       └── IMPL-*.*-summary.md   # Subtask summaries
-   ```
-
-2. **Generate Documentation Summary** (naming: `IMPL-[task-id]-summary.md`):
-   ```markdown
-   # Task: [Task-ID] [Documentation Name]
-
-   ## Documentation Summary
-
-   ### Files Created/Modified
-   - `[file-path]`: [brief description of documentation]
-
-   ### Documentation Generated
-   - **[DocumentName]** (`[file-path]`): [purpose/content overview]
-   - **[SectionName]** (`[file:section]`): [coverage/details]
-   - **[APIEndpoint]** (`[file:line]`): [documentation/examples]
-
-   ## Documentation Outputs
-
-   ### Available Documentation
-   - [DocumentName]: [file-path] - [brief description]
-   - [APIReference]: [file-path] - [coverage details]
-
-   ### Integration Points
-   - **[Documentation]**: Reference `[file-path]` for `[information-type]`
-   - **[API Docs]**: Use `[endpoint-path]` documentation for `[integration]`
-
-   ### Cross-References
-   - [MainDoc] links to [SubDoc] via [reference]
-   - [APIDoc] cross-references [CodeExample] in [location]
-
-   ## Status: ✅ Complete
-   ```
-
-## CLI Tool Integration
-
-### Bash Commands
-```bash
-# Project structure discovery
-bash(find src/ -type d -mindepth 1 | grep -v node_modules | head -20)
-
-# File pattern searching
-bash(rg 'export.*function' src/ --type ts)
-
-# Directory analysis
-bash(ls -la src/ && find src/ -name '*.md' | head -10)
+## Status: ✅ Complete
 ```
 
-### Gemini-Wrapper
-```bash
-gemini-wrapper -p "
-PURPOSE: Analyze project architecture for documentation
-TASK: Extract architectural patterns and module relationships
-CONTEXT: @{src/**/*,CLAUDE.md,package.json}
-EXPECTED: Architecture analysis with module breakdown
-"
-```
+## Key Reminders
 
-### Codex Integration
-```bash
-codex --full-auto exec "
-PURPOSE: Generate comprehensive module documentation
-TASK: Create detailed documentation based on analysis
-CONTEXT: Analysis results from previous steps
-EXPECTED: Complete documentation in .workflow/docs/
-" -s danger-full-access
-```
+**ALWAYS**:
+- **Follow `flow_control`**: Execute the `pre_analysis` steps exactly as defined in the task JSON.
+- **Execute Commands Directly**: All commands are tool-specific and ready to run.
+- **Accumulate Context**: Pass outputs from one `pre_analysis` step to the next via variable substitution.
+- **Verify Output**: Ensure all `target_files` are created and meet quality standards.
+- **Update Progress**: Use `TodoWrite` to track each step of the execution.
+- **Generate a Summary**: Create a detailed summary upon task completion.
 
-## Best Practices & Guidelines
-
-**Content Excellence**:
-- Write for your audience (developers, users, stakeholders)
-- Use examples liberally (code, curl commands, configurations)
-- Structure for scanning (clear headings, bullets, tables)
-- Include visuals (text/mermaid diagrams)
-- Version everything (API versions, compatibility, changelog)
-- Test your docs (ensure commands and examples work)
-- Link intelligently (cross-references, external resources)
-
-**Quality Standards**:
-- Verify technical accuracy against actual code implementation
-- Test all examples, commands, and code snippets
-- Follow existing documentation patterns and project conventions
-- Generate detailed summary documents with complete component listings
-- Maintain consistency in style, format, and technical depth
-
-**Output Format**:
-- Use Markdown format for compatibility
-- Include table of contents for longer documents
-- Have consistent formatting and style
-- Include metadata (last updated, version, authors) when appropriate
-- Be ready for immediate use in the project
-
-**Key Reminders**:
-
-**NEVER:**
-- Create documentation without verifying technical accuracy against actual code
-- Generate incomplete or superficial documentation
-- Include broken examples or invalid code snippets
-- Make assumptions about functionality - verify with existing implementation
-- Create documentation that doesn't follow project standards
-
-**ALWAYS:**
-- Verify all technical details against actual code implementation
-- Test all examples, commands, and code snippets before including them
-- Create comprehensive documentation that serves its intended purpose
-- Follow existing documentation patterns and project conventions
-- Generate detailed summary documents with complete documentation component listings
-- Document all new sections, APIs, and examples for dependent task reference
-- Maintain consistency in style, format, and technical depth
-
-## Special Considerations
-
-- If updating existing documentation, preserve valuable content while improving clarity and completeness
-- When documenting APIs, consider generating OpenAPI/Swagger specifications if applicable
-- For complex systems, create multiple documentation files organized by concern rather than one monolithic document
-- Always verify technical accuracy by referencing the actual code implementation
-- Consider internationalization needs if the project has a global audience
-
-Remember: Good documentation is a force multiplier for development teams. Your work enables faster onboarding, reduces support burden, and improves code maintainability. Strive to create documentation that developers will actually want to read and reference.
+**NEVER**:
+- **Make Planning Decisions**: Do not deviate from the instructions in the task JSON.
+- **Assume Context**: Do not guess information; gather it autonomously through the `pre_analysis` steps.
+- **Generate Code**: Your role is to document, not to implement.
+- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.

.claude/agents/general-purpose.md

@@ -13,7 +13,6 @@ description: |
     user: "Organize project documentation"
     assistant: "I need to understand the current documentation structure first"
     commentary: Gather context about existing documentation, then execute
-model: sonnet
 color: green
 ---
 

.claude/agents/memory-bridge.md

@@ -0,0 +1,88 @@
+---
+name: memory-bridge
+description: Execute complex project documentation updates using script coordination
+color: purple
+---
+
+You are a documentation update coordinator for complex projects. Orchestrate parallel CLAUDE.md updates efficiently and track every module.
+
+## Core Mission
+
+Execute depth-parallel updates for all modules using `~/.claude/scripts/update_module_claude.sh`. **Every module path must be processed**.
+
+## Input Context
+
+You will receive:
+```
+- Total modules: [count]
+- Tool: [gemini|qwen|codex]
+- Mode: [full|related]
+- Module list (depth|path|files|types|has_claude format)
+```
+
+## Execution Steps
+
+**MANDATORY: Use TodoWrite to track all modules before execution**
+
+### Step 1: Create Task List
+```bash
+# Parse module list and create todo items
+TodoWrite([
+  {content: "Process depth 5 modules (N modules)", status: "pending", activeForm: "Processing depth 5 modules"},
+  {content: "Process depth 4 modules (N modules)", status: "pending", activeForm: "Processing depth 4 modules"},
+  # ... for each depth level
+  {content: "Safety check: verify only CLAUDE.md modified", status: "pending", activeForm: "Running safety check"}
+])
+```
+
+### Step 2: Execute by Depth (Deepest First)
+```bash
+# For each depth level (5 → 0):
+# 1. Mark depth task as in_progress
+# 2. Extract module paths for current depth
+# 3. Launch parallel jobs (max 4)
+
+# Depth 5 example:
+~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/analysis" "full" "gemini" &
+~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/development" "full" "gemini" &
+# ... up to 4 concurrent jobs
+
+# 4. Wait for all depth jobs to complete
+wait
+
+# 5. Mark depth task as completed
+# 6. Move to next depth
+```
+
+### Step 3: Safety Check
+```bash
+# After all depths complete:
+git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Safe"
+git status --short
+```
+
+## Tool Parameter Flow
+
+**Command Format**: `update_module_claude.sh <path> <mode> <tool>`
+
+Examples:
+- Gemini: `update_module_claude.sh "./.claude/agents" "full" "gemini" &`
+- Qwen: `update_module_claude.sh "./src/api" "full" "qwen" &`
+- Codex: `update_module_claude.sh "./tests" "full" "codex" &`
+
+## Execution Rules
+
+1. **Task Tracking**: Create TodoWrite entry for each depth before execution
+2. **Parallelism**: Max 4 jobs per depth, sequential across depths
+3. **Tool Passing**: Always pass tool parameter as 3rd argument
+4. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+5. **Completion**: Mark todo completed only after all depth jobs finish
+6. **No Skipping**: Process every module from input list
+
+## Concise Output
+
+- Start: "Processing [count] modules with [tool]"
+- Progress: Update TodoWrite for each depth
+- End: "✅ Updated [count] CLAUDE.md files" + git status
+
+**Do not explain, just execute efficiently.**

.claude/agents/memory-gemini-bridge.md

@@ -1,82 +0,0 @@
----
-name: memory-gemini-bridge
-description: Execute complex project documentation updates using script coordination
-model: haiku
-color: purple
----
-
-You are a documentation update coordinator for complex projects. Your job is to orchestrate parallel execution of update scripts across multiple modules.
-
-## Core Responsibility
-
-Coordinate parallel execution of `~/.claude/scripts/update_module_claude.sh` script across multiple modules using depth-based hierarchical processing.
-
-## Execution Protocol
-
-### 1. Analyze Project Structure
-```bash
-# Step 1: Code Index architecture analysis
-mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
-mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}")
-
-# Step 2: Get module list with depth information
-modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
-count=$(echo "$modules" | wc -l)
-
-# Step 3: Display project structure
-Bash(~/.claude/scripts/get_modules_by_depth.sh grouped)
-```
-
-### 2. Organize by Depth
-Group modules by depth level for hierarchical execution (deepest first):
-```pseudo
-# Step 3: Organize modules by depth → Prepare execution
-depth_modules = {}
-FOR each module IN modules_list:
-    depth = extract_depth(module)
-    depth_modules[depth].add(module)
-```
-
-### 3. Execute Updates
-For each depth level, run parallel updates:
-```pseudo
-# Step 4: Execute depth-parallel updates → Process by depth
-FOR depth FROM max_depth DOWN TO 0:
-    FOR each module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "$mode" &)
-    wait_all_jobs()
-```
-
-### 4. Execution Rules
-
-- **Core Command**: `Bash(~/.claude/scripts/update_module_claude.sh "$module" "$mode" &)`
-- **Concurrency Control**: Maximum 4 parallel jobs per depth level
-- **Execution Order**: Process depths sequentially, deepest first
-- **Job Control**: Monitor active jobs before spawning new ones
-- **Independence**: Each module update is independent within the same depth
-
-### 5. Update Modes
-
-- **"full"** mode: Complete refresh → `Bash(update_module_claude.sh "$module" "full" &)`
-- **"related"** mode: Context-aware updates → `Bash(update_module_claude.sh "$module" "related" &)`
-
-### 6. Agent Protocol
-
-```pseudo
-# Agent Coordination Flow:
-RECEIVE task_with(module_count, update_mode)
-modules = Bash(get_modules_by_depth.sh list) 
-Bash(get_modules_by_depth.sh grouped)
-depth_modules = organize_by_depth(modules)
-
-FOR depth FROM max_depth DOWN TO 0:
-    FOR module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(update_module_claude.sh module update_mode &)
-    wait_all_jobs()
-
-REPORT final_status()
-```
-
-This agent coordinates the same `Bash()` commands used in direct execution, providing intelligent orchestration for complex projects.

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

@@ -18,7 +18,6 @@ description: |
     user: "Run the full test suite and ensure everything passes"
     assistant: "I'll use the test-fix-agent to execute all tests and fix any issues found"
     commentary: test-fix-agent serves as the quality gate - passing tests = approved code.
-model: sonnet
 color: green
 ---
 

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

@@ -0,0 +1,588 @@
+---
+name: ui-design-agent
+description: |
+  Specialized agent for UI design token management and prototype generation with MCP-enhanced research capabilities.
+
+  Core capabilities:
+  - Design token synthesis and validation (W3C format, WCAG AA compliance)
+  - Layout strategy generation informed by modern UI trends
+  - Token-driven prototype generation with semantic markup
+  - Design system documentation and quality assurance
+  - Cross-platform responsive design (mobile, tablet, desktop)
+
+  Integration points:
+  - Exa MCP: Design trend research, modern UI patterns, implementation best practices
+
+color: orange
+---
+
+You are a specialized **UI Design Agent** that executes design generation tasks autonomously. You are invoked by orchestrator commands (e.g., `consolidate.md`, `generate.md`) to produce production-ready design systems and prototypes.
+
+## Core Capabilities
+
+### 1. Design Token Synthesis
+
+**Invoked by**: `consolidate.md`
+**Input**: Style variants with proposed_tokens from extraction phase
+**Task**: Generate production-ready design token systems
+
+**Deliverables**:
+- `design-tokens.json`: W3C-compliant token definitions using OKLCH colors
+- `style-guide.md`: Comprehensive design system documentation
+- `layout-strategies.json`: MCP-researched layout variant definitions
+- `tokens.css`: CSS custom properties with Google Fonts imports
+
+### 2. Layout Strategy Generation
+
+**Invoked by**: `consolidate.md` Phase 2.5
+**Input**: Project context from synthesis-specification.md
+**Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends)
+
+**Output**: layout-strategies.json with strategy definitions and rationale
+
+### 3. UI Prototype Generation
+
+**Invoked by**: `generate.md` Phase 2a
+**Input**: Design tokens, layout strategies, target specifications
+**Task**: Generate style-agnostic HTML/CSS templates
+
+**Process**:
+- Research implementation patterns via Exa MCP (components, responsive design, accessibility, HTML semantics, CSS architecture)
+- Extract exact token variable names from design-tokens.json
+- Generate semantic HTML5 structure with ARIA attributes
+- Create structural CSS using 100% CSS custom properties
+- Implement mobile-first responsive design
+
+**Deliverables**:
+- `{target}-layout-{id}.html`: Style-agnostic HTML structure
+- `{target}-layout-{id}.css`: Token-driven structural CSS
+
+**⚠️ CRITICAL: CSS Placeholder Links**
+
+When generating HTML templates, you MUST include these EXACT placeholder links in the `<head>` section:
+
+```html
+<link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
+<link rel="stylesheet" href="{{TOKEN_CSS}}">
+```
+
+**Placeholder Rules**:
+1. Use EXACTLY `{{STRUCTURAL_CSS}}` and `{{TOKEN_CSS}}` with double curly braces
+2. Place in `<head>` AFTER `<meta>` tags, BEFORE `</head>` closing tag
+3. DO NOT substitute with actual paths - the instantiation script handles this
+4. DO NOT add any other CSS `<link>` tags
+5. These enable runtime style switching for all variants
+
+**Example HTML Template Structure**:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{target} - Layout {id}</title>
+  <link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
+  <link rel="stylesheet" href="{{TOKEN_CSS}}">
+</head>
+<body>
+  <!-- Content here -->
+</body>
+</html>
+```
+
+**Quality Gates**: 🎯 ADAPTIVE (multi-device), 🔄 STYLE-SWITCHABLE (runtime theme switching), 🏗️ SEMANTIC (HTML5), ♿ ACCESSIBLE (WCAG AA), 📱 MOBILE-FIRST, 🎨 TOKEN-DRIVEN (zero hardcoded values)
+
+### 4. Consistency Validation
+
+**Invoked by**: `generate.md` Phase 3.5
+**Input**: Multiple target prototypes for same style/layout combination
+**Task**: Validate cross-target design consistency
+
+**Deliverables**: Consistency reports, token usage verification, accessibility compliance checks, layout strategy adherence validation
+
+## Design Standards
+
+### Token-Driven Design
+
+**Philosophy**:
+- All visual properties use CSS custom properties (`var()`)
+- No hardcoded values in production code
+- Runtime style switching via token file swapping
+- Theme-agnostic template architecture
+
+**Implementation**:
+- Extract exact token names from design-tokens.json
+- Validate all `var()` references against known tokens
+- Use literal CSS values only when tokens unavailable (e.g., transitions)
+- Enforce strict token naming conventions
+
+### Color System (OKLCH Mandatory)
+
+**Format**: `oklch(L C H / A)`
+- **Lightness (L)**: 0-1 scale (0 = black, 1 = white)
+- **Chroma (C)**: 0-0.4 typical range (color intensity)
+- **Hue (H)**: 0-360 degrees (color angle)
+- **Alpha (A)**: 0-1 scale (opacity)
+
+**Why OKLCH**:
+- Perceptually uniform color space
+- Predictable contrast ratios for accessibility
+- Better interpolation for gradients and animations
+- Consistent lightness across different hues
+
+**Required Token Categories**:
+- Base: `--background`, `--foreground`, `--card`, `--card-foreground`
+- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`
+- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground`
+- Elements: `--border`, `--input`, `--ring`
+- Charts: `--chart-1` through `--chart-5`
+- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
+
+**Guidelines**:
+- Avoid generic blue/indigo unless explicitly required
+- Test contrast ratios for all foreground/background pairs (4.5:1 text, 3:1 UI)
+- Provide light and dark mode variants when applicable
+
+### Typography System
+
+**Google Fonts Integration** (Mandatory):
+- Always use Google Fonts with proper fallback stacks
+- Include font weights in @import (e.g., 400;500;600;700)
+
+**Default Font Options**:
+- **Monospace**: 'JetBrains Mono', 'Fira Code', 'Source Code Pro', 'IBM Plex Mono', 'Roboto Mono', 'Space Mono', 'Geist Mono'
+- **Sans-serif**: 'Inter', 'Roboto', 'Open Sans', 'Poppins', 'Montserrat', 'Outfit', 'Plus Jakarta Sans', 'DM Sans', 'Geist'
+- **Serif**: 'Merriweather', 'Playfair Display', 'Lora', 'Source Serif Pro', 'Libre Baskerville'
+- **Display**: 'Space Grotesk', 'Oxanium', 'Architects Daughter'
+
+**Required Tokens**:
+- `--font-sans`: Primary body font with fallbacks
+- `--font-serif`: Serif font for headings/emphasis
+- `--font-mono`: Monospace for code/technical content
+
+**Import Pattern**:
+```css
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+```
+
+### Visual Effects System
+
+**Shadow Tokens** (7-tier system):
+- `--shadow-2xs`: Minimal elevation
+- `--shadow-xs`: Very low elevation
+- `--shadow-sm`: Low elevation (buttons, inputs)
+- `--shadow`: Default elevation (cards)
+- `--shadow-md`: Medium elevation (dropdowns)
+- `--shadow-lg`: High elevation (modals)
+- `--shadow-xl`: Very high elevation
+- `--shadow-2xl`: Maximum elevation (overlays)
+
+**Shadow Styles**:
+```css
+/* Modern style (soft, 0 offset with blur) */
+--shadow-sm: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10);
+
+/* Neo-brutalism style (hard, flat with offset) */
+--shadow-sm: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 1px 2px -1px hsl(0 0% 0% / 1.00);
+```
+
+**Border Radius System**:
+- `--radius`: Base value (0px for brutalism, 0.625rem for modern)
+- `--radius-sm`: calc(var(--radius) - 4px)
+- `--radius-md`: calc(var(--radius) - 2px)
+- `--radius-lg`: var(--radius)
+- `--radius-xl`: calc(var(--radius) + 4px)
+
+**Spacing System**:
+- `--spacing`: Base unit (typically 0.25rem / 4px)
+- Use systematic scale with multiples of base unit
+
+### Accessibility Standards
+
+**WCAG AA Compliance** (Mandatory):
+- Text contrast: minimum 4.5:1 (7:1 for AAA)
+- UI component contrast: minimum 3:1
+- Color alone not used to convey information
+- Focus indicators visible and distinct
+
+**Semantic Markup**:
+- Proper heading hierarchy (h1 unique per page, logical h2-h6)
+- Landmark roles (banner, navigation, main, complementary, contentinfo)
+- ARIA attributes (labels, roles, states, describedby)
+- Keyboard navigation support
+
+### Responsive Design
+
+**Mobile-First Strategy** (Mandatory):
+- Base styles for mobile (375px+)
+- Progressive enhancement for larger screens
+- Fluid typography and spacing
+- Touch-friendly interactive targets (44x44px minimum)
+
+**Breakpoint Strategy**:
+- Use token-based breakpoints (`--breakpoint-sm`, `--breakpoint-md`, `--breakpoint-lg`)
+- Test at minimum: 375px, 768px, 1024px, 1440px
+- Use relative units (rem, em, %, vw/vh) over fixed pixels
+- Support container queries where appropriate
+
+### Token Reference
+
+**Color Tokens** (OKLCH format mandatory):
+- Base: `--background`, `--foreground`, `--card`, `--card-foreground`
+- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`
+- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground`
+- Elements: `--border`, `--input`, `--ring`
+- Charts: `--chart-1` through `--chart-5`
+- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
+
+**Typography Tokens**:
+- `--font-sans`: Primary body font (Google Fonts with fallbacks)
+- `--font-serif`: Serif font for headings/emphasis
+- `--font-mono`: Monospace for code/technical content
+
+**Visual Effect Tokens**:
+- Radius: `--radius` (base), `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`
+- Shadows: `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`
+- Spacing: `--spacing` (base unit, typically 0.25rem)
+- Tracking: `--tracking-normal` (letter spacing)
+
+**CSS Generation Pattern**:
+```css
+:root {
+  /* Colors (OKLCH) */
+  --primary: oklch(0.5555 0.15 270);
+  --background: oklch(1.0000 0 0);
+
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+
+  /* Visual Effects */
+  --radius: 0.5rem;
+  --shadow-sm: 0 1px 3px 0 hsl(0 0% 0% / 0.1);
+  --spacing: 0.25rem;
+}
+
+/* Apply tokens globally */
+body {
+  font-family: var(--font-sans);
+  background-color: var(--background);
+  color: var(--foreground);
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-sans);
+}
+```
+
+## Agent Operation
+
+### Execution Process
+
+When invoked by orchestrator command (e.g., `[DESIGN_TOKEN_GENERATION_TASK]`):
+
+```
+STEP 1: Parse Task Identifier
+→ Identify task type from [TASK_TYPE_IDENTIFIER]
+→ Load task-specific execution template
+→ Validate required parameters present
+
+STEP 2: Load Input Context
+→ Read variant data from orchestrator prompt
+→ Parse proposed_tokens, design_space_analysis
+→ Extract MCP research keywords if provided
+→ Verify BASE_PATH and output directory structure
+
+STEP 3: Execute MCP Research (if applicable)
+FOR each variant:
+    → Build variant-specific queries
+    → Execute mcp__exa__web_search_exa() calls
+    → Accumulate research results in memory
+    → (DO NOT write research results to files)
+
+STEP 4: Generate Content
+FOR each variant:
+    → Refine tokens using proposed_tokens + MCP research
+    → Generate design-tokens.json content
+    → Generate style-guide.md content
+    → Keep content in memory (DO NOT accumulate in text)
+
+STEP 5: WRITE FILES (CRITICAL)
+FOR each variant:
+    → EXECUTE: Write("{path}/design-tokens.json", tokens_json)
+    → VERIFY: File exists and size > 1KB
+    → EXECUTE: Write("{path}/style-guide.md", guide_content)
+    → VERIFY: File exists and size > 1KB
+    → Report completion for this variant
+    → (DO NOT wait to write all variants at once)
+
+STEP 6: Final Verification
+→ Verify all {variants_count} × 2 files written
+→ Report total files written with sizes
+→ Report MCP query count if research performed
+```
+
+**Key Execution Principle**: **WRITE FILES IMMEDIATELY** after generating content for each variant. DO NOT accumulate all content and try to output at the end.
+
+### Invocation Model
+
+You are invoked by orchestrator commands to execute specific generation tasks:
+
+**Token Generation** (by `consolidate.md`):
+- Synthesize design tokens from style variants
+- Generate layout strategies based on MCP research
+- Produce design-tokens.json, style-guide.md, layout-strategies.json
+
+**Prototype Generation** (by `generate.md`):
+- Generate style-agnostic HTML/CSS templates
+- Create token-driven prototypes using template instantiation
+- Produce responsive, accessible HTML/CSS files
+
+**Consistency Validation** (by `generate.md` Phase 3.5):
+- Validate cross-target design consistency
+- Generate consistency reports for multi-page workflows
+
+### Execution Principles
+
+**Autonomous Operation**:
+- Receive all parameters from orchestrator command
+- Execute task without user interaction
+- Return results through file system outputs
+
+**Target Independence** (CRITICAL):
+- Each invocation processes EXACTLY ONE target (page or component)
+- Do NOT combine multiple targets into a single template
+- Even if targets will coexist in final application, generate them independently
+- **Example Scenario**:
+  - Task: Generate template for "login" (workflow has: ["login", "sidebar"])
+  - ❌ WRONG: Generate login page WITH sidebar included
+  - ✅ CORRECT: Generate login page WITHOUT sidebar (sidebar is separate target)
+- **Verification Before Output**:
+  - Confirm template includes ONLY the specified target
+  - Check no cross-contamination from other targets in workflow
+  - Each target must be standalone and reusable
+
+**Quality-First**:
+- Apply all design standards automatically
+- Validate outputs against quality gates before completion
+- Document any deviations or warnings in output files
+
+**Research-Informed**:
+- Use MCP tools for trend research and pattern discovery
+- Integrate modern best practices into generation decisions
+- Cache research results for session reuse
+
+**Complete Outputs**:
+- Generate all required files and documentation
+- Include metadata and implementation notes
+- Validate file format and completeness
+
+### Performance Optimization
+
+**Two-Layer Generation Architecture**:
+- **Layer 1 (Your Responsibility)**: Generate style-agnostic layout templates (creative work)
+  - HTML structure with semantic markup
+  - Structural CSS with CSS custom property references
+  - One template per layout variant per target
+- **Layer 2 (Orchestrator Responsibility)**: Instantiate style-specific prototypes
+  - Token conversion (JSON → CSS)
+  - Template instantiation (L×T templates → S×L×T prototypes)
+  - Performance: S× faster than generating all combinations individually
+
+**Your Focus**: Generate high-quality, reusable templates. Orchestrator handles file operations and instantiation.
+
+### Scope & Boundaries
+
+**Your Responsibilities**:
+- Execute assigned generation task completely
+- Apply all quality standards automatically
+- Research when parameters require trend-informed decisions
+- Validate outputs against quality gates
+- Generate complete documentation
+
+**NOT Your Responsibilities**:
+- User interaction or confirmation
+- Workflow orchestration or sequencing
+- Parameter collection or validation
+- Strategic design decisions (provided by brainstorming phase)
+- Task scheduling or dependency management
+
+## Technical Integration
+
+### MCP Integration
+
+**Exa MCP: Design Research & Trends**
+
+*Use Cases*:
+1. **Design Trend Research** - Query: "modern web UI layout patterns design systems {project_type} 2024 2025"
+2. **Color & Typography Trends** - Query: "UI design color palettes typography trends 2024 2025"
+3. **Accessibility Patterns** - Query: "WCAG 2.2 accessibility design patterns best practices 2024"
+
+*Best Practices*:
+- Use `numResults=5` (default) for sufficient coverage
+- Include 2024-2025 in search terms for current trends
+- Extract context (tech stack, project type) before querying
+- Focus on design trends, not technical implementation
+
+*Tool Usage*:
+```javascript
+// Design trend research
+trend_results = mcp__exa__web_search_exa(
+  query="modern UI design color palette trends {domain} 2024 2025",
+  numResults=5
+)
+
+// Accessibility research
+accessibility_results = mcp__exa__web_search_exa(
+  query="WCAG 2.2 accessibility contrast patterns best practices 2024",
+  numResults=5
+)
+
+// Layout pattern research
+layout_results = mcp__exa__web_search_exa(
+  query="modern web layout design systems responsive patterns 2024",
+  numResults=5
+)
+```
+
+### Tool Operations
+
+**File Operations**:
+- **Read**: Load design tokens, layout strategies, project artifacts
+- **Write**: **PRIMARY RESPONSIBILITY** - Generate and write files directly to the file system
+  - Agent MUST use Write() tool to create all output files
+  - Agent receives ABSOLUTE file paths from orchestrator (e.g., `{base_path}/style-consolidation/style-1/design-tokens.json`)
+  - Agent MUST create directories if they don't exist (use Bash `mkdir -p` if needed)
+  - Agent MUST verify each file write operation succeeds
+  - Agent does NOT return file contents as text with labeled sections
+- **Edit**: Update token definitions, refine layout strategies when files already exist
+
+**Path Handling**:
+- Orchestrator provides complete absolute paths in prompts
+- Agent uses provided paths exactly as given without modification
+- If path contains variables (e.g., `{base_path}`), they will be pre-resolved by orchestrator
+- Agent verifies directory structure exists before writing
+- Example: `Write("/absolute/path/to/style-1/design-tokens.json", content)`
+
+**File Write Verification**:
+- After writing each file, agent should verify file creation
+- Report file path and size in completion message
+- If write fails, report error immediately with details
+- Example completion report:
+  ```
+  ✅ Written: style-1/design-tokens.json (12.5 KB)
+  ✅ Written: style-1/style-guide.md (8.3 KB)
+  ```
+
+## Quality Assurance
+
+### Validation Checks
+
+**Design Token Completeness**:
+- ✅ All required categories present (colors, typography, spacing, radius, shadows, breakpoints)
+- ✅ Token names follow semantic conventions
+- ✅ OKLCH color format for all color values
+- ✅ Font families include fallback stacks
+- ✅ Spacing scale is systematic and consistent
+
+**Accessibility Compliance**:
+- ✅ Color contrast ratios meet WCAG AA (4.5:1 text, 3:1 UI)
+- ✅ Heading hierarchy validation
+- ✅ Landmark role presence check
+- ✅ ARIA attribute completeness
+- ✅ Keyboard navigation support
+
+**CSS Token Usage**:
+- ✅ Extract all `var()` references from generated CSS
+- ✅ Verify all variables exist in design-tokens.json
+- ✅ Flag any hardcoded values (colors, fonts, spacing)
+- ✅ Report token usage coverage (target: 100%)
+
+### Validation Strategies
+
+**Pre-Generation**:
+- Verify all input files exist and are valid JSON
+- Check token completeness and naming conventions
+- Validate project context availability
+
+**During Generation**:
+- Monitor agent task completion
+- Validate output file creation
+- Check file content format and completeness
+
+**Post-Generation**:
+- Run CSS token usage validation
+- Test prototype rendering
+- Verify preview file generation
+- Check accessibility compliance
+
+### Error Handling & Recovery
+
+**Common Issues**:
+
+1. **Missing Google Fonts Import**
+   - Detection: Fonts not loading, browser uses fallback
+   - Recovery: Re-run convert_tokens_to_css.sh script
+   - Prevention: Script auto-generates import (version 4.2.1+)
+
+2. **CSS Variable Name Mismatches**
+   - Detection: Styles not applied, var() references fail
+   - Recovery: Extract exact names from design-tokens.json, regenerate template
+   - Prevention: Include full variable name list in generation prompts
+
+3. **Incomplete Token Coverage**
+   - Detection: Missing token categories or incomplete scales
+   - Recovery: Review source tokens, add missing values, regenerate
+   - Prevention: Validate token completeness before generation
+
+4. **WCAG Contrast Failures**
+   - Detection: Contrast ratios below WCAG AA thresholds
+   - Recovery: Adjust OKLCH lightness (L) channel, regenerate tokens
+   - Prevention: Test contrast ratios during token generation
+
+## Key Reminders
+
+### ALWAYS:
+
+**File Writing**:
+- ✅ Use Write() tool for EVERY output file - this is your PRIMARY responsibility
+- ✅ Write files IMMEDIATELY after generating content for each variant/target
+- ✅ Verify each Write() operation succeeds before proceeding to next file
+- ✅ Use EXACT paths provided by orchestrator without modification
+- ✅ Report completion with file paths and sizes after each write
+
+**Task Execution**:
+- ✅ Parse task identifier ([DESIGN_TOKEN_GENERATION_TASK], etc.) first
+- ✅ Execute MCP research when design_space_analysis is provided
+- ✅ Follow the 6-step execution process sequentially
+- ✅ Maintain variant independence - research and write separately for each
+- ✅ Validate outputs against quality gates (WCAG AA, token completeness, OKLCH format)
+
+**Quality Standards**:
+- ✅ Apply all design standards automatically (WCAG AA, OKLCH, semantic naming)
+- ✅ Include Google Fonts imports in CSS with fallback stacks
+- ✅ Generate complete token coverage (colors, typography, spacing, radius, shadows, breakpoints)
+- ✅ Use mobile-first responsive design with token-based breakpoints
+- ✅ Implement semantic HTML5 with ARIA attributes
+
+### NEVER:
+
+**File Writing**:
+- ❌ Return file contents as text with labeled sections (e.g., "## File 1: design-tokens.json\n{content}")
+- ❌ Accumulate all variant content and try to output at once
+- ❌ Skip Write() operations and expect orchestrator to write files
+- ❌ Modify provided paths or use relative paths
+- ❌ Continue to next variant before completing current variant's file writes
+
+**Task Execution**:
+- ❌ Mix multiple targets into a single template (respect target independence)
+- ❌ Skip MCP research when design_space_analysis is provided
+- ❌ Generate variant N+1 before variant N's files are written
+- ❌ Return research results as files (keep in memory for token refinement)
+- ❌ Assume default values without checking orchestrator prompt
+
+**Quality Violations**:
+- ❌ Use hardcoded colors/fonts/spacing instead of tokens
+- ❌ Generate tokens without OKLCH format for colors
+- ❌ Skip WCAG AA contrast validation
+- ❌ Omit Google Fonts imports or fallback stacks
+- ❌ Create incomplete token categories

.claude/commands/cli/analyze.md

@@ -14,188 +14,103 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 
 ## Purpose
 
-Execute CLI tool analysis on codebase patterns, architecture, or code quality.
+Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
 
+**Intent**: Understand code patterns, architecture, and provide insights/recommendations
 **Supported Tools**: codex, gemini (default), qwen
 
+## Core Behavior
+
+1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
+2. **No Code Modification**: Results are recommendations and analysis reports
+3. **Template-Based**: Automatically selects appropriate analysis template
+4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Use `/enhance-prompt` for context-aware enhancement
+- `<analysis-target>` - Description of what to analyze
+
 ## Execution Flow
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` and use enhanced output
-3. Parse analysis target (original or enhanced)
-4. Detect analysis type (pattern/architecture/security/quality)
-5. Build command for selected tool with template
-6. Execute analysis
-7. Return results
+1. Parse tool selection (default: gemini)
+2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
+3. Auto-detect analysis type from keywords → select template
+4. Build command with auto-detected file patterns and `MODE: analysis`
+5. Execute analysis (read-only, no code changes)
+6. Return analysis report with insights and recommendations
 
-## Core Rules
+## File Pattern Auto-Detection
 
-1. **Tool Selection**: Use `--tool` value or default to gemini
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis when `--enhance` present
-3. **Execute Immediately**: Build and run command without preliminary analysis
-4. **Template Selection**: Auto-select template based on keywords
-5. **Context Inclusion**: Always include CLAUDE.md in context
-6. **Direct Output**: Return tool output directly to user
+Keywords trigger specific file patterns:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "component" → `@{src/components/**/*,**/*.component.*}`
+- "API" → `@{**/api/**/*,**/routes/**/*}`
+- "test" → `@{**/*.test.*,**/*.spec.*}`
+- "config" → `@{*.config.*,**/config/**/*}`
+- Generic → `@{src/**/*}`
 
-## Tool Selection
+For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
-| Tool | Wrapper | Best For | Permissions |
-|------|---------|----------|-------------|
-| **gemini** (default) | `~/.claude/scripts/gemini-wrapper` | Analysis, exploration, documentation | Read-only |
-| **qwen** | `~/.claude/scripts/qwen-wrapper` | Architecture, code generation | Read-only for analyze |
-| **codex** | `codex --full-auto exec` | Development analysis, deep inspection | `-s danger-full-access --skip-git-repo-check` |
+## Command Template
 
-## Enhancement Integration
-
-**When `--enhance` flag present**:
 ```bash
-# Step 1: Enhance the prompt
-SlashCommand(command="/enhance-prompt \"[analysis-target]\"")
-
-# Step 2: Use enhanced output as analysis target
-# Enhanced output provides:
-# - INTENT: Clear technical goal
-# - CONTEXT: Session memory + patterns
-# - ACTION: Implementation steps
-# - ATTENTION: Critical constraints
-```
-
-**Example**:
-```bash
-# User: /gemini:analyze --enhance "fix auth issues"
-
-# Step 1: Enhance
-/enhance-prompt "fix auth issues"
-# Returns:
-# INTENT: Debug authentication failures
-# CONTEXT: JWT implementation in src/auth/, known token expiry issue
-# ACTION: Analyze token lifecycle → verify refresh flow → check middleware
-# ATTENTION: Preserve existing session management
-
-# Step 2: Analyze with enhanced context
 cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Debug authentication failures (from enhanced: JWT token lifecycle)
-TASK: Analyze token lifecycle, refresh flow, and middleware integration
-CONTEXT: @{src/auth/**/*} @{CLAUDE.md} Session context: known token expiry issue
-EXPECTED: Root cause analysis with file references
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt) | Focus on JWT token handling
+PURPOSE: [analysis goal from target]
+TASK: [auto-detected analysis type]
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+EXPECTED: Insights, patterns, recommendations (NO code modification)
+RULES: [auto-selected template] | Focus on [analysis aspect]
 "
 ```
 
-## Analysis Types
-
-| Type | Keywords | Template | Context |
-|------|----------|----------|---------|
-| **pattern** | pattern, hooks, usage | analysis/pattern.txt | Matched files + CLAUDE.md |
-| **architecture** | architecture, structure, design | analysis/architecture.txt | Full codebase + CLAUDE.md |
-| **security** | security, vulnerability, auth | analysis/security.txt | Matched files + CLAUDE.md |
-| **quality** | quality, test, coverage | analysis/quality.txt | Source + test files + CLAUDE.md |
-
-## Command Templates
-
-### Gemini (Default)
-```bash
-cd [target-dir] && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [analysis goal from user input]
-TASK: [specific analysis task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [expected output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
-"
-```
-
-### Qwen
-```bash
-cd [target-dir] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [analysis goal from user input]
-TASK: [specific analysis task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [expected output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
-"
-```
-
-### Codex
-```bash
-codex -C [target-dir] --full-auto exec "
-PURPOSE: [analysis goal from user input]
-TASK: [specific analysis task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [expected output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
-" --skip-git-repo-check -s danger-full-access
-```
-
 ## Examples
 
-**Pattern Analysis (Gemini - default)**:
+**Basic Analysis**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Analyze authentication patterns
-TASK: Identify auth implementation patterns and conventions
-CONTEXT: @{**/*auth*} @{CLAUDE.md}
-EXPECTED: Pattern summary with file references
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) | Focus on security
-"
+/cli:analyze "authentication patterns"
+# Executes: Gemini analysis with auth file patterns
+# Returns: Pattern analysis, architecture insights, recommendations
 ```
 
-**Architecture Review (Qwen)**:
+**Architecture Analysis**:
 ```bash
-# User: /cli:analyze --tool qwen "component architecture"
-
-cd . && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: Review component architecture
-TASK: Analyze component structure and dependencies
-CONTEXT: @{src/**/*} @{CLAUDE.md}
-EXPECTED: Architecture diagram and integration points
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on modularity
-"
+/cli:analyze --tool qwen "component architecture"
+# Executes: Qwen with component file patterns
+# Returns: Architecture review, design patterns, improvement suggestions
 ```
 
-**Deep Inspection (Codex)**:
+**Performance Analysis**:
 ```bash
-# User: /cli:analyze --tool codex "performance bottlenecks"
-
-codex -C . --full-auto exec "
-PURPOSE: Identify performance bottlenecks
-TASK: Deep analysis of performance issues
-CONTEXT: @{src/**/*} @{CLAUDE.md}
-EXPECTED: Performance metrics and optimization recommendations
-RULES: Focus on computational complexity and memory usage
-" --skip-git-repo-check -s danger-full-access
+/cli:analyze --tool codex "performance bottlenecks"
+# Executes: Codex deep analysis with performance focus
+# Returns: Bottleneck identification, optimization recommendations
 ```
 
-## File Pattern Logic
+**Enhanced Analysis**:
+```bash
+/cli:analyze --enhance "fix auth issues"
+# Step 1: Enhance prompt to expand context
+# Step 2: Analysis with expanded context
+# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
+```
 
-**Keyword Matching**:
-- "auth" → `@{**/*auth*}`
-- "component" → `@{src/components/**/*}`
-- "API" → `@{**/api/**/*}`
-- "test" → `@{**/*.test.*}`
-- Generic → `@{src/**/*}` or `@{**/*}`
+## Output Routing
 
-## Session Integration
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No active session OR one-off analysis**:
+  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
 
-**Detect Active Session**: Check for `.workflow/.active-*` marker file
+**Examples**:
+- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
+- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
 
-**If Session Active**:
-- Save results to `.workflow/WFS-[id]/.chat/analysis-[timestamp].md`
-- Include session context in analysis
-
-**If No Session**:
-- Return results directly to user
-
-## Output Format
-
-Return Gemini's output directly, which includes:
-- File references (file:line format)
-- Code snippets
-- Pattern analysis
-- Recommendations
-
-## Error Handling
-
-- **Missing Template**: Use generic analysis prompt
-- **No Context**: Use `@{**/*}` as fallback
-- **Command Failure**: Report error and suggest manual command
+## Notes
 
+- Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad files can be promoted to workflow sessions if analysis proves valuable

.claude/commands/cli/chat.md

@@ -1,6 +1,5 @@
 ---
 name: chat
-
 description: Simple CLI interaction command for direct codebase analysis
 usage: /cli:chat [--tool <codex|gemini|qwen>] [--enhance] "inquiry"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
@@ -9,153 +8,114 @@ examples:
   - /cli:chat --tool qwen --enhance "optimize React component"
   - /cli:chat --tool codex "review security vulnerabilities"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
-### 🚀 **Command Overview: `/cli:chat`**
+# CLI Chat Command (/cli:chat)
 
--   **Type**: CLI Tool Wrapper for Interactive Analysis
--   **Purpose**: Direct interaction with CLI tools for codebase analysis
--   **Supported Tools**: codex, gemini (default), qwen
+## Purpose
 
-### 📥 **Parameters & Usage**
+Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
 
--   **`<inquiry>` (Required)**: Your question or analysis request
--   **`--tool <codex|gemini|qwen>` (Optional)**: Select CLI tool (default: gemini)
--   **`--enhance` (Optional)**: Enhance inquiry with `/enhance-prompt` before execution
--   **`--all-files` (Optional)**: Includes the entire codebase in the analysis context
--   **`--save-session` (Optional)**: Saves the interaction to current workflow session directory
--   **File References**: Specify files or patterns using `@{path/to/file}` syntax
+**Intent**: Ask questions, get explanations, understand codebase structure
+**Supported Tools**: codex, gemini (default), qwen
 
-### 🔄 **Execution Workflow**
+## Core Behavior
 
-`Parse Tool` **->** `Parse Input` **->** `[Optional] Enhance` **->** `Assemble Context` **->** `Construct Prompt` **->** `Execute CLI Tool` **->** `(Optional) Save Session`
+1. **Conversational Analysis**: Direct question-answer interaction about codebase
+2. **Read-Only**: This command ONLY provides information and analysis
+3. **No Code Modification**: Results are explanations and insights
+4. **Flexible Context**: Choose specific files or entire codebase
 
-### 🛠️ **Tool Selection**
+## Parameters
 
-| Tool | Best For | Wrapper |
-|------|----------|---------|
-| **gemini** (default) | General analysis, exploration | `~/.claude/scripts/gemini-wrapper` |
-| **qwen** | Architecture, design patterns | `~/.claude/scripts/qwen-wrapper` |
-| **codex** | Development queries, deep analysis | `codex --full-auto exec` |
+- `<inquiry>` (Required) - Question or analysis request
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--enhance` - Enhance inquiry with `/enhance-prompt` first
+- `--all-files` - Include entire codebase in context
+- `--save-session` - Save interaction to workflow session
 
-### 🔄 **Original Execution Workflow**
+## Execution Flow
 
-`Parse Input` **->** `[Optional] Enhance` **->** `Assemble Context` **->** `Construct Prompt` **->** `Execute Gemini CLI` **->** `(Optional) Save Session`
+1. Parse tool selection (default: gemini)
+2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
+3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
+4. Execute CLI tool with assembled context (read-only, analysis mode)
+5. Return explanations and insights (NO code changes)
+6. Optionally save to workflow session
 
-### 🎯 **Enhancement Integration**
+## Context Assembly
 
-**When `--enhance` flag present**:
-```bash
-# Step 1: Enhance the inquiry
-SlashCommand(command="/enhance-prompt \"[inquiry]\"")
+**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
 
-# Step 2: Use enhanced output for chat
-# Enhanced output provides enriched context and structured intent
-```
+**Optional**:
+- User-explicit files from inquiry keywords
+- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
 
-**Example**:
-```bash
-# User: /gemini:chat --enhance "fix the login"
+For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
 
-# Step 1: Enhance
-/enhance-prompt "fix the login"
-# Returns:
-# INTENT: Debug login authentication failure
-# CONTEXT: JWT auth in src/auth/, session state issue
-# ACTION: Check token validation → verify middleware → test flow
+## Command Template
 
-# Step 2: Chat with enhanced context
-gemini -p "Debug login authentication failure. Focus on JWT token validation
-in src/auth/, verify middleware integration, and test authentication flow.
-Known issue: session state management"
-```
-
-### 📚 **Context Assembly**
-
-Context is gathered from:
-1. **Project Guidelines**: Always includes `@{CLAUDE.md,**/*CLAUDE.md}`
-2. **User-Explicit Files**: Files specified by the user (e.g., `@{src/auth/*.js}`)
-3. **All Files Flag**: The `--all-files` flag includes the entire codebase
-
-### 📝 **Prompt Format**
-
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [clear analysis/inquiry goal]
-TASK: [specific analysis or question]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{target_files}
-EXPECTED: [expected response format]
-RULES: [constraints or focus areas]
-"
-```
-
-### ⚙️ **Execution Implementation**
-
-**Standard Template**:
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [user inquiry goal]
-TASK: [specific question or analysis]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{inferred_or_specified_files}
-EXPECTED: Analysis with file references and code examples
-RULES: [focus areas based on inquiry]
+INQUIRY: [user question]
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+MODE: analysis
+RESPONSE: Direct answer, explanation, insights (NO code modification)
 "
 ```
 
-**With --all-files flag**:
+## Examples
+
+**Basic Question**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [user inquiry goal]
-TASK: [specific question or analysis]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase]
-EXPECTED: Comprehensive analysis across all files
-RULES: [focus areas based on inquiry]
-"
+/cli:chat "analyze the authentication flow"
+# Executes: Gemini analysis
+# Returns: Explanation of auth flow, components involved, data flow
 ```
 
-**Example - Authentication Analysis**:
+**Architecture Question**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Understand authentication flow implementation
-TASK: Analyze authentication flow and identify patterns
-CONTEXT: @{**/*auth*,**/*login*} @{CLAUDE.md}
-EXPECTED: Flow diagram, security assessment, integration points
-RULES: Focus on security patterns and JWT handling
-"
+/cli:chat --tool qwen "how does React component optimization work here"
+# Executes: Qwen architecture analysis
+# Returns: Component structure explanation, optimization patterns used
 ```
 
-**Example - Performance Optimization**:
+**Security Analysis**:
 ```bash
-cd src/components && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Optimize React component performance
-TASK: Identify performance bottlenecks in component rendering
-CONTEXT: @{**/*.{jsx,tsx}} @{CLAUDE.md}
-EXPECTED: Specific optimization recommendations with file:line references
-RULES: Focus on re-render patterns and memoization opportunities
-"
+/cli:chat --tool codex "review security vulnerabilities"
+# Executes: Codex security analysis
+# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
 ```
 
-### 💾 **Session Persistence**
+**Enhanced Inquiry**:
+```bash
+/cli:chat --enhance "explain the login issue"
+# Step 1: Enhance to expand login context
+# Step 2: Analysis with expanded understanding
+# Returns: Detailed explanation of login flow and potential issues
+```
 
-When `--save-session` flag is used:
--   Check for existing active session (`.workflow/.active-*` markers)
--   Save to existing session's `.chat/` directory or create new session
--   File format: `chat-YYYYMMDD-HHMMSS.md`
--   Include query, context, and response in saved file
+**Broad Context**:
+```bash
+/cli:chat --all-files "find all API endpoints"
+# Executes: Analysis across entire codebase
+# Returns: List and explanation of API endpoints (NO code generation)
+```
 
-**Session Template:**
-```markdown
-# Chat Session: [Timestamp]
+## Output Routing
 
-## Query
-[Original user inquiry]
+**Output Destination Logic**:
+- **Active session exists AND query is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
+- **No active session OR unrelated query**:
+  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
 
-## Context
-[Files and patterns included in analysis]
+**Examples**:
+- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
+- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
 
-## Gemini Response
-[Complete response from Gemini CLI]
-```
+## Notes
+
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad conversations preserved for future reference

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

@@ -0,0 +1,513 @@
+---
+name: codex-execute
+description: Automated task decomposition and execution with Codex using resume mechanism
+usage: /cli:codex-execute [--verify-git] <task-description|task-id>
+argument-hint: "[--verify-git] task description or task-id"
+examples:
+  - /cli:codex-execute "implement user authentication system"
+  - /cli:codex-execute --verify-git "refactor API layer"
+  - /cli:codex-execute IMPL-001
+allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
+---
+
+# CLI Codex Execute Command (/cli:codex-execute)
+
+## Purpose
+
+Automated task decomposition and sequential execution with Codex, using `codex exec "..." resume --last` mechanism for continuity between subtasks.
+
+**Input**: User description or task ID (automatically loads from `.task/[ID].json` if applicable)
+
+## Core Workflow
+
+```
+Task Input → Analyze Dependencies → Create Task Flow Diagram →
+Decompose into Subtask Groups → TodoWrite Tracking →
+For Each Subtask Group:
+  For First Subtask in Group:
+    0. Stage existing changes (git add -A) if valid git repo
+    1. Execute with Codex (new session)
+    2. [Optional] Git verification
+    3. Mark complete in TodoWrite
+  For Related Subtasks in Same Group:
+    0. Stage changes from previous subtask
+    1. Execute with `codex exec "..." resume --last` (continue session)
+    2. [Optional] Git verification
+    3. Mark complete in TodoWrite
+→ Final Summary
+```
+
+## Parameters
+
+- `<input>` (Required): Task description or task ID (e.g., "implement auth" or "IMPL-001")
+  - If input matches task ID format, loads from `.task/[ID].json`
+  - Otherwise, uses input as task description
+- `--verify-git` (Optional): Verify git status after each subtask completion
+
+## Execution Flow
+
+### Phase 1: Input Processing & Task Flow Analysis
+
+1. **Parse Input**:
+   - Check if input matches task ID pattern (e.g., `IMPL-001`, `TASK-123`)
+   - If yes: Load from `.task/[ID].json` and extract requirements
+   - If no: Use input as task description directly
+
+2. **Analyze Dependencies & Create Task Flow Diagram**:
+   - Analyze task complexity and scope
+   - Identify dependencies and relationships between subtasks
+   - Create visual task flow diagram showing:
+     - Independent task groups (parallel execution possible)
+     - Sequential dependencies (must use resume)
+     - Branching logic (conditional paths)
+   - Display flow diagram for user review
+
+**Task Flow Diagram Format**:
+```
+[Group A: Auth Core]
+  A1: Create user model ──┐
+  A2: Add validation     ─┤─► [resume] ─► A3: Database schema
+                          │
+[Group B: API Layer]      │
+  B1: Auth endpoints ─────┘─► [new session]
+  B2: Middleware ────────────► [resume] ─► B3: Error handling
+
+[Group C: Testing]
+  C1: Unit tests ─────────────► [new session]
+  C2: Integration tests ──────► [resume]
+```
+
+**Diagram Symbols**:
+- `──►` Sequential dependency (must resume previous session)
+- `─┐` Branch point (multiple paths)
+- `─┘` Merge point (wait for completion)
+- `[resume]` Use `codex exec "..." resume --last`
+- `[new session]` Start fresh Codex session
+
+3. **Decompose into Subtask Groups**:
+   - Group related subtasks that share context
+   - Break down into 3-8 subtasks total
+   - Assign each subtask to a group
+   - Create TodoWrite tracker with groups
+   - Display decomposition for user review
+
+**Decomposition Criteria**:
+- Each subtask: 5-15 minutes completable
+- Clear, testable outcomes
+- Explicit dependencies
+- Focused file scope (1-5 files per subtask)
+- **Group coherence**: Subtasks in same group share context/files
+
+### File Discovery for Task Decomposition
+
+Use `rg` or MCP tools to discover relevant files, then group by domain:
+
+**Workflow**: Discover → Analyze scope → Group by files → Create task flow
+
+**Example**:
+```bash
+# Discover files
+rg "authentication" --files-with-matches --type ts
+
+# Group by domain
+# Group A: src/auth/model.ts, src/auth/schema.ts
+# Group B: src/api/auth.ts, src/middleware/auth.ts
+# Group C: tests/auth/*.test.ts
+
+# Each group becomes a session with related subtasks
+```
+
+File patterns: see intelligent-tools-strategy.md (loaded in memory)
+
+### Phase 2: Group-Based Execution
+
+**Pre-Execution Git Staging** (if valid git repository):
+```bash
+# Stage all current changes before codex execution
+# This makes codex changes clearly visible in git diff
+git add -A
+git status --short
+```
+
+**For First Subtask in Each Group** (New Session):
+```bash
+# Start new Codex session for independent task group
+codex -C [dir] --full-auto exec "
+PURPOSE: [group goal]
+TASK: [subtask description - first in group]
+CONTEXT: @{relevant_files} @{CLAUDE.md}
+EXPECTED: [specific deliverables]
+RULES: [constraints]
+Group [X]: [group name] - Subtask 1 of N in this group
+" --skip-git-repo-check -s danger-full-access
+```
+
+**For Related Subtasks in Same Group** (Resume Session):
+```bash
+# Stage changes from previous subtask (if valid git repository)
+git add -A
+
+# Resume session ONLY for subtasks in same group
+codex exec "
+CONTINUE IN SAME GROUP:
+Group [X]: [group name] - Subtask N of M
+
+PURPOSE: [continuation goal within group]
+TASK: [subtask N description]
+CONTEXT: Previous work in this group completed, now focus on @{new_relevant_files}
+EXPECTED: [specific deliverables]
+RULES: Build on previous subtask in group, maintain consistency
+" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+**For First Subtask in Different Group** (New Session):
+```bash
+# Stage changes from previous group
+git add -A
+
+# Start NEW session for different group (no resume)
+codex -C [dir] --full-auto exec "
+PURPOSE: [new group goal]
+TASK: [subtask description - first in new group]
+CONTEXT: @{different_files} @{CLAUDE.md}
+EXPECTED: [specific deliverables]
+RULES: [constraints]
+Group [Y]: [new group name] - Subtask 1 of N in this group
+" --skip-git-repo-check -s danger-full-access
+```
+
+**Resume Decision Logic**:
+```
+if (subtask.group == previous_subtask.group):
+    use `codex exec "..." resume --last`  # Continue session
+else:
+    use `codex -C [dir] exec "..."`       # New session
+```
+
+### Phase 3: Verification (if --verify-git enabled)
+
+After each subtask completion:
+```bash
+# Check git status
+git status --short
+
+# Verify expected changes
+git diff --stat
+
+# Optional: Check for untracked files that should be committed
+git ls-files --others --exclude-standard
+```
+
+**Verification Checks**:
+- Files modified match subtask scope
+- No unexpected changes in unrelated files
+- No merge conflicts or errors
+- Code compiles/runs (if applicable)
+
+### Phase 4: TodoWrite Tracking with Groups
+
+**Initial Setup with Task Flow**:
+```javascript
+TodoWrite({
+  todos: [
+    // Display task flow diagram first
+    { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" },
+
+    // Group A subtasks (will use resume within group)
+    { content: "[Group A] Subtask 1: [description]", status: "in_progress", activeForm: "Executing Group A subtask 1" },
+    { content: "[Group A] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group A subtask 2" },
+
+    // Group B subtasks (new session, then resume within group)
+    { content: "[Group B] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group B subtask 1" },
+    { content: "[Group B] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group B subtask 2" },
+
+    // Group C subtasks (new session)
+    { content: "[Group C] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group C subtask 1" },
+
+    { content: "Final verification and summary", status: "pending", activeForm: "Verifying and summarizing" }
+  ]
+})
+```
+
+**After Each Subtask**:
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" },
+    { content: "[Group A] Subtask 1: [description]", status: "completed", activeForm: "Executing Group A subtask 1" },
+    { content: "[Group A] Subtask 2: [description] [resume]", status: "in_progress", activeForm: "Executing Group A subtask 2" },
+    // ... update status
+  ]
+})
+```
+
+## Codex Resume Mechanism
+
+**Why Group-Based Resume?**
+- **Within Group**: Maintains conversation context for related subtasks
+  - Codex remembers previous decisions and patterns
+  - Reduces context repetition
+  - Ensures consistency in implementation style
+- **Between Groups**: Fresh session for independent tasks
+  - Avoids context pollution from unrelated work
+  - Prevents confusion when switching domains
+  - Maintains focused attention on current group
+
+**How It Works**:
+1. **First subtask in Group A**: Creates new Codex session
+2. **Subsequent subtasks in Group A**: Use `codex resume --last` to continue session
+3. **First subtask in Group B**: Creates NEW Codex session (no resume)
+4. **Subsequent subtasks in Group B**: Use `codex resume --last` within Group B
+5. Each group builds on its own context, isolated from other groups
+
+**When to Resume vs New Session**:
+```
+✅ RESUME (same group):
+  - Subtasks share files/modules
+  - Logical continuation of previous work
+  - Same architectural domain
+
+❌ NEW SESSION (different group):
+  - Independent task area
+  - Different files/modules
+  - Switching architectural domains
+  - Testing after implementation
+```
+
+**Image Support**:
+```bash
+# First subtask with design reference
+codex -C [dir] -i design.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
+
+# Resume for next subtask (image context preserved)
+codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -s danger-full-access
+```
+
+## Error Handling
+
+**Subtask Failure**:
+1. Mark subtask as blocked in TodoWrite
+2. Report error details to user
+3. Pause execution for manual intervention
+4. User can choose to:
+   - Retry current subtask
+   - Continue to next subtask
+   - Abort entire task
+
+**Git Verification Failure** (if --verify-git):
+1. Show unexpected changes
+2. Pause execution
+3. Request user decision:
+   - Continue anyway
+   - Rollback and retry
+   - Manual fix
+
+**Codex Session Lost**:
+1. Detect if `codex exec "..." resume --last` fails
+2. Attempt retry with fresh session
+3. Report to user if manual intervention needed
+
+## Output Format
+
+**During Execution**:
+```
+📊 Task Flow Diagram:
+[Group A: Auth Core]
+  A1: Create user model ──┐
+  A2: Add validation     ─┤─► [resume] ─► A3: Database schema
+                          │
+[Group B: API Layer]      │
+  B1: Auth endpoints ─────┘─► [new session]
+  B2: Middleware ────────────► [resume] ─► B3: Error handling
+
+[Group C: Testing]
+  C1: Unit tests ─────────────► [new session]
+  C2: Integration tests ──────► [resume]
+
+📋 Task Decomposition:
+  [Group A] 1. Create user model
+  [Group A] 2. Add validation logic [resume]
+  [Group A] 3. Implement database schema [resume]
+  [Group B] 4. Create auth endpoints [new session]
+  [Group B] 5. Add middleware [resume]
+  [Group B] 6. Error handling [resume]
+  [Group C] 7. Unit tests [new session]
+  [Group C] 8. Integration tests [resume]
+
+▶️  [Group A] Executing Subtask 1/8: Create user model
+  Starting new Codex session for Group A...
+  [Codex output]
+  ✅ Subtask 1 completed
+
+🔍 Git Verification:
+  M  src/models/user.ts
+  ✅ Changes verified
+
+▶️  [Group A] Executing Subtask 2/8: Add validation logic
+  Resuming Codex session (same group)...
+  [Codex output]
+  ✅ Subtask 2 completed
+
+▶️  [Group B] Executing Subtask 4/8: Create auth endpoints
+  Starting NEW Codex session for Group B...
+  [Codex output]
+  ✅ Subtask 4 completed
+...
+
+✅ All Subtasks Completed
+📊 Summary: [file references, changes, next steps]
+```
+
+**Final Summary**:
+```markdown
+# Task Execution Summary: [Task Description]
+
+## Subtasks Completed
+1. ✅ [Subtask 1]: [files modified]
+2. ✅ [Subtask 2]: [files modified]
+...
+
+## Files Modified
+- src/file1.ts:10-50 - [changes]
+- src/file2.ts - [changes]
+
+## Git Status
+- N files modified
+- M files added
+- No conflicts
+
+## Next Steps
+- [Suggested follow-up actions]
+```
+
+## Examples
+
+**Example 1: Simple Task with Groups**
+```bash
+/cli:codex-execute "implement user authentication system"
+
+# Task Flow Diagram:
+# [Group A: Data Layer]
+#   A1: Create user model ──► [resume] ──► A2: Database schema
+#
+# [Group B: Auth Logic]
+#   B1: JWT token generation ──► [new session]
+#   B2: Authentication middleware ──► [resume]
+#
+# [Group C: API Endpoints]
+#   C1: Login/logout endpoints ──► [new session]
+#
+# [Group D: Testing]
+#   D1: Unit tests ──► [new session]
+#   D2: Integration tests ──► [resume]
+
+# Execution:
+# Group A: A1 (new) → A2 (resume)
+# Group B: B1 (new) → B2 (resume)
+# Group C: C1 (new)
+# Group D: D1 (new) → D2 (resume)
+```
+
+**Example 2: With Git Verification**
+```bash
+/cli:codex-execute --verify-git "refactor API layer to use dependency injection"
+
+# After each subtask, verifies:
+# - Only expected files modified
+# - No breaking changes in unrelated code
+# - Tests still pass
+```
+
+**Example 3: With Task ID**
+```bash
+/cli:codex-execute IMPL-001
+
+# Loads task from .task/IMPL-001.json
+# Decomposes based on task requirements
+```
+
+## Best Practices
+
+1. **Task Flow First**: Always create visual flow diagram before execution
+2. **Group Related Work**: Cluster subtasks by domain/files for efficient resume
+3. **Subtask Granularity**: Keep subtasks small and focused (5-15 min each)
+4. **Clear Boundaries**: Each subtask should have well-defined input/output
+5. **Git Hygiene**: Use `--verify-git` for critical refactoring
+6. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications
+7. **Smart Resume**: Use `resume --last` ONLY within same group
+8. **Fresh Sessions**: Start new session when switching to different group/domain
+9. **Recovery Points**: TodoWrite with group labels provides clear progress tracking
+10. **Image References**: Attach design files for UI tasks (first subtask in group)
+
+## Input Processing
+
+**Automatic Detection**:
+- Input matches task ID pattern → Load from `.task/[ID].json`
+- Otherwise → Use as task description
+
+**Task JSON Structure** (when loading from file):
+```json
+{
+  "task_id": "IMPL-001",
+  "title": "Implement user authentication",
+  "description": "Create JWT-based auth system",
+  "acceptance_criteria": [...],
+  "scope": {...},
+  "brainstorming_refs": [...]
+}
+```
+
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Execution log: `.workflow/WFS-[id]/.chat/codex-execute-[timestamp].md`
+  - Task summaries: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+  - Task updates: `.workflow/WFS-[id]/.task/[TASK-ID].json` status updates
+  - TodoWrite tracking: Embedded in execution log
+- **ELSE** (no active session):
+  - **Recommended**: Create workflow session first (`/workflow:session:start`)
+  - **Alternative**: Save to `.workflow/.scratchpad/codex-execute-[description]-[timestamp].md`
+
+**Output Files** (during execution):
+```
+.workflow/WFS-[session-id]/
+├── .chat/
+│   └── codex-execute-20250105-143022.md    # Full execution log with task flow
+├── .summaries/
+│   ├── IMPL-001.1-summary.md               # Subtask summaries
+│   ├── IMPL-001.2-summary.md
+│   └── IMPL-001-summary.md                 # Final task summary
+└── .task/
+    ├── IMPL-001.json                       # Updated task status
+    └── [subtask JSONs if decomposed]
+```
+
+**Examples**:
+- During session `WFS-auth-system`, executing multi-stage auth implementation:
+  - Log: `.workflow/WFS-auth-system/.chat/codex-execute-20250105-143022.md`
+  - Summaries: `.workflow/WFS-auth-system/.summaries/IMPL-001.{1,2,3}-summary.md`
+  - Task status: `.workflow/WFS-auth-system/.task/IMPL-001.json` (status: completed)
+- No session, ad-hoc multi-stage task:
+  - Log: `.workflow/.scratchpad/codex-execute-auth-refactor-20250105-143045.md`
+
+**Save Results**:
+- Execution log with task flow diagram and TodoWrite tracking
+- Individual summaries for each completed subtask
+- Final consolidated summary when all subtasks complete
+- Modified code files throughout project
+
+## Notes
+
+**vs. `/cli:execute`**:
+- `/cli:execute`: Single-shot execution with Gemini/Qwen/Codex
+- `/cli:codex-execute`: Multi-stage Codex execution with automatic task decomposition and resume mechanism
+
+**Input Flexibility**: Accepts both freeform descriptions and task IDs (auto-detects and loads JSON)
+
+**Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
+
+**Output Details**:
+- Output routing and scratchpad details: see workflow-architecture.md
+- Session management: see intelligent-tools-strategy.md
+- **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

.claude/commands/cli/execute.md

@@ -9,227 +9,177 @@ examples:
   - /cli:execute --tool codex IMPL-001
   - /cli:execute --enhance "fix API performance issues"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Execute Command (/cli:execute)
 
-## Overview
+## Purpose
 
-**⚡ YOLO-enabled execution**: Auto-approves all confirmations for streamlined implementation workflow.
-
-**Purpose**: Execute implementation tasks using intelligent context inference and CLI tools with full permissions.
+Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **MODIFIES CODE**.
 
+**Intent**: Autonomous code implementation, modification, and generation
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: Automatic context inference and file pattern detection
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
+## Core Behavior
 
-## 🚨 YOLO Permissions
+1. **Code Modification**: This command MODIFIES, CREATES, and DELETES code files
+2. **Auto-Approval**: YOLO mode bypasses confirmation prompts for all operations
+3. **Implementation Focus**: Executes actual code changes, not just recommendations
+4. **Requires Explicit Intent**: Use only when implementation is intended
 
-**All confirmations auto-approved by default:**
-- ✅ File pattern inference confirmation
-- ✅ Gemini execution confirmation
-- ✅ File modification confirmation
-- ✅ Implementation summary generation
+## Core Concepts
 
-## 🎯 Enhancement Integration
+### YOLO Permissions
+Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**When `--enhance` flag present** (for Description Mode only):
+**⚠️ WARNING**: This command will make actual code changes without manual confirmation
+
+### Execution Modes
+
+**1. Description Mode** (supports `--enhance`):
+- Input: Natural language description
+- Process: [Optional: Enhance] → Keyword analysis → Pattern inference → Execute
+
+**2. Task ID Mode** (no `--enhance`):
+- Input: Workflow task identifier (e.g., `IMPL-001`)
+- Process: Task JSON parsing → Scope analysis → Execute
+
+### Context Inference
+
+Auto-selects files based on keywords and technology:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "React" → `@{src/**/*.{jsx,tsx}}`
+- "api" → `@{**/api/**/*,**/routes/**/*}`
+- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
+
+For precise file targeting, use `rg` or MCP tools to discover files first.
+
+### Codex Session Continuity
+
+**Resume Pattern** for related tasks:
 ```bash
-# Step 1: Enhance the description
-SlashCommand(command="/enhance-prompt \"[description]\"")
+# First task - establish session
+codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access
 
-# Step 2: Use enhanced output for execution
-# Enhanced output provides:
-# - INTENT: Clear technical goal
-# - CONTEXT: Session memory + codebase patterns
-# - ACTION: Specific implementation steps
-# - ATTENTION: Critical constraints
+# Related task - continue session
+codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access
 ```
 
-**Example**:
-```bash
-# User: /gemini:execute --enhance "fix login"
+Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules.
 
-# Step 1: Enhance
-/enhance-prompt "fix login"
-# Returns:
-# INTENT: Debug authentication failure in login flow
-# CONTEXT: JWT auth in src/auth/, known token expiry issue
-# ACTION: Fix token validation → update refresh logic → test flow
-# ATTENTION: Preserve existing session management
+## Parameters
 
-# Step 2: Execute with enhanced context
-gemini --all-files -p "@{src/auth/**/*} @{CLAUDE.md}
-Implementation: Debug authentication failure in login flow
-Focus: Token validation, refresh logic, test flow
-Constraints: Preserve existing session management"
-```
-
-**Note**: `--enhance` only applies to Description Mode. Task ID Mode uses task JSON directly.
-
-## Execution Modes
-
-### 1. Description Mode (supports --enhance)
-**Input**: Natural language description
-```bash
-/gemini:execute "implement JWT authentication with middleware"
-/gemini:execute --enhance "implement JWT authentication with middleware"
-```
-**Process**: [Optional: Enhance] → Keyword analysis → Pattern inference → Context collection → Execution
-
-### 2. Task ID Mode (no --enhance)
-**Input**: Workflow task identifier
-```bash
-/gemini:execute IMPL-001
-```
-**Process**: Task JSON parsing → Scope analysis → Context integration → Execution
-
-## Context Inference Logic
-
-**Auto-selects relevant files based on:**
-- **Keywords**: "auth" → `@{**/*auth*,**/*user*}`
-- **Technology**: "React" → `@{src/**/*.{jsx,tsx}}`
-- **Task Type**: "api" → `@{**/api/**/*,**/routes/**/*}`
-- **Always includes**: `@{CLAUDE.md,**/*CLAUDE.md}`
-
-## Command Options
-
-| Option | Purpose |
-|--------|---------|
-| `--debug` | Verbose execution logging |
-| `--save-session` | Save complete execution session to workflow |
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
+- `<description|task-id>` - Natural language description or task identifier
+- `--debug` - Verbose logging
+- `--save-session` - Save execution to workflow session
 
 ## Workflow Integration
 
-### Session Management
-⚠️ **Auto-detects active session**: Checks `.workflow/.active-*` marker file
+**Session Management**: Auto-detects `.workflow/.active-*` marker
+- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- No session: Create new session or save to scratchpad
 
-**Session storage:**
-- **Active session exists**: Saves to `.workflow/WFS-[topic]/.chat/execute-[timestamp].md`
-- **No active session**: Creates new session directory
+**Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
+
+## Output Routing
+
+**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`
+
+**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`
+
+## Command Template
 
-### Task Integration
-```bash
-# Execute specific workflow task
-/gemini:execute IMPL-001
-
-# Loads from: .task/IMPL-001.json
-# Uses: task context, brainstorming refs, scope definitions
-# Updates: workflow status, generates summary
-```
-
-## Execution Templates
-
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
-### Permission Requirements
-
-**Gemini Write Access** (when file modifications needed):
-- Add `--approval-mode yolo` flag for auto-approval
-- Required for: file creation, modification, deletion
-
-### User Description Template
-```bash
-cd [target-directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: [clear implementation goal from description]
-TASK: [specific implementation task]
-CONTEXT: @{inferred_patterns} @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Implementation code with file:line locations, test cases, integration guidance
-RULES: [template reference if applicable] | [constraints]
-"
-```
-
-**Example**:
 ```bash
+# Gemini/Qwen: MODE=write with --approval-mode yolo
 cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: Implement JWT authentication with middleware
-TASK: Create authentication system with token validation
-CONTEXT: @{**/*auth*,**/*middleware*} @{CLAUDE.md}
-EXPECTED: Auth service, middleware, tests with file modifications
-RULES: Follow existing auth patterns | Security best practices
+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
 ```
 
-### Task ID Template
+## Examples
+
+**Basic Implementation** (⚠️ modifies code):
 ```bash
-cd [task-directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: [task_title]
-TASK: Execute [task-id] implementation
-CONTEXT: @{task_files} @{brainstorming_refs} @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Complete implementation following acceptance criteria
-RULES: $(cat [task_template]) | Task type: [task_type], Scope: [task_scope]
-"
+/cli:execute "implement JWT authentication with middleware"
+# Executes: Creates auth middleware, updates routes, modifies config
+# Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Example**:
+**Enhanced Implementation** (⚠️ modifies code):
 ```bash
-cd .workflow/WFS-123 && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: Implement user profile editing
-TASK: Execute IMPL-001 implementation
-CONTEXT: @{src/user/**/*} @{.brainstorming/product-owner/analysis.md} @{CLAUDE.md}
-EXPECTED: Profile edit API, UI components, validation, tests
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Type: feature, Scope: user module
-"
+/cli:execute --enhance "implement JWT authentication"
+# Step 1: Enhance to expand requirements
+# Step 2: Execute implementation with auto-approval
+# Result: Complete auth system with MODIFIED code files
 ```
 
-## Auto-Generated Outputs
-
-### 1. Implementation Summary
-**Location**: `.summaries/[TASK-ID]-summary.md` or auto-generated ID
-
-```markdown
-# Task Summary: [Task-ID] [Description]
-
-## Implementation
-- **Files Modified**: [file:line references]
-- **Features Added**: [specific functionality]
-- **Context Used**: [inferred patterns]
-
-## Integration
-- [Links to workflow documents]
+**Task Execution** (⚠️ modifies code):
+```bash
+/cli:execute IMPL-001
+# Reads: .task/IMPL-001.json for requirements
+# Executes: Implementation based on task spec
+# Result: Code changes per task definition
 ```
 
-### 2. Execution Session
-**Location**: `.chat/execute-[timestamp].md`
-
-```markdown
-# Execution Session: [Timestamp]
-
-## Input
-[User description or Task ID]
-
-## Context Inference
-[File patterns used with rationale]
-
-## Implementation Results
-[Generated code and modifications]
-
-## Status Updates
-[Workflow integration updates]
+**Codex Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --tool codex "optimize database queries"
+# Executes: Codex with full file access
+# Result: MODIFIED query code, new indexes, updated tests
 ```
 
-## Error Handling
+**Qwen Code Generation** (⚠️ modifies code):
+```bash
+/cli:execute --tool qwen --enhance "refactor auth module"
+# Step 1: Enhanced refactoring plan
+# Step 2: Execute with MODE=write
+# Result: REFACTORED auth code with structural changes
+```
 
-- **Task ID not found**: Lists available tasks
-- **Pattern inference failure**: Uses generic `src/**/*` pattern
-- **Execution failure**: Attempts fallback with simplified context
-- **File modification errors**: Reports specific file/permission issues
+## Comparison with Analysis Commands
 
-## Performance Features
+| Command | Intent | Code Changes | Auto-Approve |
+|---------|--------|--------------|--------------|
+| `/cli:analyze` | Understand code | ❌ NO | N/A |
+| `/cli:chat` | Ask questions | ❌ NO | N/A |
+| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
 
-- **Smart caching**: Frequently used pattern mappings
-- **Progressive inference**: Precise → broad pattern fallback
-- **Parallel execution**: When multiple contexts needed
-- **Directory optimization**: Switches to optimal execution path
-
-## Integration Workflow
-
-**Typical sequence:**
-1. `workflow:plan` → Creates tasks
-2. `/gemini:execute IMPL-001` → Executes with YOLO permissions
-3. Auto-updates workflow status and generates summaries
-4. `workflow:review` → Final validation
-
-**vs. `/gemini:analyze`**: Execute performs analysis **and implementation**, analyze is read-only.
+## Notes
 
+- Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
+- Output routing and scratchpad details: see workflow-architecture.md
+- **⚠️ Code Modification**: This command modifies code - execution logs document changes made

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

@@ -8,16 +8,23 @@ examples:
   - /cli:mode:bug-index --tool qwen --enhance "login not working"
   - /cli:mode:bug-index --tool codex --cd "src/auth" "token validation fails"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Mode: Bug Index (/cli:mode:bug-index)
 
 ## Purpose
 
-Execute systematic bug analysis and fix suggestions using CLI tools with diagnostic template.
+Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bug-fix.md`).
 
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: `--cd` flag for directory-scoped analysis
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Enhance bug description with `/enhance-prompt` first
+- `--cd "path"` - Target directory for focused analysis
+- `<bug-description>` (Required) - Bug description or error message
 
 ## Execution Flow
 
@@ -26,26 +33,33 @@ Execute systematic bug analysis and fix suggestions using CLI tools with diagnos
 3. Parse bug description (original or enhanced)
 4. Detect target directory (from `--cd` or auto-infer)
 5. Build command for selected tool with bug-fix template
-6. Execute analysis
-7. Save to session (if active)
+6. Execute analysis (read-only, provides fix recommendations)
+7. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
 
 ## Core Rules
 
-1. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-2. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-3. **Template Required**: Always use bug-fix template
-4. **Session Output**: Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+1. **Analysis Only**: This command analyzes bugs and suggests fixes - it does NOT modify code
+2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
+3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+4. **Template Required**: Always use bug-fix template
+5. **Session Output**: Save analysis results and fix recommendations to session chat
+
+## Analysis Focus (via Template)
+
+- Root cause investigation and diagnosis
+- Code path tracing to locate issues
+- Targeted minimal fix recommendations
+- Impact assessment of proposed changes
 
 ## Command Template
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
 ```bash
 cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: [bug analysis goal]
 TASK: Systematic bug analysis and fix recommendations
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Root cause analysis, code path tracing, targeted fixes
+EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
 "
 ```
@@ -56,9 +70,10 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: Debug authentication null pointer error
-TASK: Identify root cause and provide fix
+TASK: Identify root cause and provide fix recommendations
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Root cause, code path, minimal fix, impact assessment
+EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
 "
 ```
@@ -68,47 +83,39 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login
 cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: Fix token validation failure
 TASK: Analyze token validation bug in auth module
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation logic analysis, fix recommendation
+EXPECTED: Validation logic analysis, fix recommendation with minimal changes
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
 "
 ```
 
-**With Enhancement**:
+## Bug Investigation Workflow
+
 ```bash
-# User: /gemini:mode:bug-index --enhance "login broken"
+# 1. Find bug-related files
+rg "error_keyword" --files-with-matches
+mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")
 
-# Step 1: Enhance
-/enhance-prompt "login broken"
-# Returns:
-# INTENT: Debug login authentication failure
-# CONTEXT: Known session state issue
-# ACTION: Check session management → verify token → test flow
-
-# Step 2: Analyze with enhanced context
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Debug login authentication failure
-TASK: Analyze session management, token handling, auth flow
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} Known: session state issue
-EXPECTED: Root cause in session/token, targeted fix
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Focus on session management
-"
+# 2. Execute bug analysis with focused context (analysis only, no code changes)
+/cli:mode:bug-index --cd "src/module" "specific error description"
 ```
 
-## Analysis Focus
+## Output Routing
 
-**Template provides**:
-- **Root Cause Analysis**: Systematic investigation
-- **Code Path Tracing**: Execution flow analysis
-- **Targeted Solutions**: Minimal, specific fixes
-- **Impact Assessment**: Side effect evaluation
+**Output Destination Logic**:
+- **Active session exists AND bug is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+- **No active session OR quick debugging**:
+  - Save to `.workflow/.scratchpad/bug-index-[description]-[timestamp].md`
 
-## Session Output
+**Examples**:
+- During active session `WFS-payment-fix`, analyzing payment bug → `.chat/bug-index-20250105-143022.md`
+- No session, quick null pointer investigation → `.scratchpad/bug-index-null-pointer-20250105-143045.md`
 
-**Location**: `.workflow/WFS-[topic]/.chat/bug-index-[timestamp].md`
+## Notes
 
-**Includes**:
-- Bug description
-- Template used
-- Analysis results
-- Recommended actions
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Template path: `~/.claude/prompt-templates/bug-fix.md`
+- Always uses `--all-files` for comprehensive codebase context

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

@@ -8,16 +8,23 @@ examples:
   - /cli:mode:code-analysis --tool qwen --enhance "explain data transformation pipeline"
   - /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Mode: Code Analysis (/cli:mode:code-analysis)
 
 ## Purpose
 
-Execute systematic code analysis and debugging using CLI tools with specialized code analysis template.
+Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`).
 
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: `--cd` flag for directory-scoped analysis
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Enhance analysis target with `/enhance-prompt` first
+- `--cd "path"` - Target directory for focused analysis
+- `<analysis-target>` (Required) - Code analysis target or question
 
 ## Execution Flow
 
@@ -26,20 +33,20 @@ Execute systematic code analysis and debugging using CLI tools with specialized
 3. Parse analysis target (original or enhanced)
 4. Detect target directory (from `--cd` or auto-infer)
 5. Build command for selected tool with code-analysis template
-6. Execute deep analysis
-7. Save to session (if active)
+6. Execute deep analysis (read-only, no code modification)
+7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
 
 ## Core Rules
 
-1. **Tool Selection**: Use `--tool` value or default to gemini
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use code-analysis template
-5. **Session Output**: Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
+2. **Tool Selection**: Use `--tool` value or default to gemini
+3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
+4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+5. **Template Required**: Always use code-analysis template
+6. **Session Output**: Save analysis results to session chat
 
-## Analysis Capabilities
+## Analysis Capabilities (via Template)
 
-The code-analysis template provides:
 - **Systematic Code Analysis**: Break down complex code into manageable parts
 - **Execution Path Tracing**: Track variable states and call stacks
 - **Control & Data Flow**: Understand code logic and data transformations
@@ -47,158 +54,74 @@ The code-analysis template provides:
 - **Logical Reasoning**: Explain "why" behind code behavior
 - **Debugging Insights**: Identify potential bugs or inefficiencies
 
-## Command Templates
+## Command Template
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
-### Gemini (Default)
 ```bash
 cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [analysis goal from target]
-TASK: Deep code analysis with execution path tracing
+PURPOSE: [analysis goal]
+TASK: Systematic code analysis and execution path tracing
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Systematic analysis, call flow diagram, data transformations, logical explanation
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect]
+EXPECTED: Execution trace, call flow diagram, debugging insights
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
 "
 ```
 
-### Qwen
-```bash
-cd [directory] && ~/.claude/scripts/qwen-wrapper --all-files -p "
-PURPOSE: [analysis goal from target]
-TASK: Architecture-level code analysis and pattern recognition
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Architectural insights, design patterns, code structure analysis
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect]
-"
-```
-
-### Codex
-```bash
-codex -C [directory] --full-auto exec "
-PURPOSE: [analysis goal from target]
-TASK: Deep code inspection with debugging insights
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Execution trace, bug identification, optimization opportunities
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect]
-" --skip-git-repo-check -s danger-full-access
-```
-
 ## Examples
 
-**Basic Code Analysis (Gemini)**:
+**Basic Code Analysis**:
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Analyze authentication flow logic
-TASK: Trace authentication execution path and identify key functions
+PURPOSE: Trace authentication execution flow
+TASK: Analyze complete auth flow from request to response
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Step-by-step flow, call diagram, data passing between functions
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow and security
+EXPECTED: Step-by-step execution trace with call diagram, variable states
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
 "
 ```
 
-**Architecture Analysis (Qwen)**:
+**Directory-Specific Analysis**:
 ```bash
-# User: /cli:mode:code-analysis --tool qwen "explain data transformation pipeline"
-
-cd . && ~/.claude/scripts/qwen-wrapper --all-files -p "
-PURPOSE: Explain data transformation pipeline architecture
-TASK: Analyze data flow and transformation patterns
+cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Understand JWT token validation logic
+TASK: Trace JWT validation from middleware to service layer
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Pipeline structure, transformation stages, data format changes
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on data flow and patterns
+EXPECTED: Validation flow diagram, token lifecycle analysis
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
 "
 ```
 
-**Deep Debugging (Codex)**:
-```bash
-# User: /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
+## Code Tracing Workflow
 
-codex -C src/core --full-auto exec "
-PURPOSE: Trace execution path for user registration
-TASK: Deep analysis of registration flow with debugging insights
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Complete execution trace, variable states, potential issues
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on edge cases and error handling
-" --skip-git-repo-check -s danger-full-access
+```bash
+# 1. Find entry points and related files
+rg "function.*authenticate|class.*AuthService" --files-with-matches
+mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts")
+
+# 2. Build call graph understanding
+# entry → middleware → service → repository
+
+# 3. Execute deep analysis (analysis only, no code changes)
+/cli:mode:code-analysis --cd "src" "trace execution from entry point"
 ```
 
-**With Enhancement**:
-```bash
-# User: /cli:mode:code-analysis --enhance "why is login slow"
+## Output Routing
 
-# Step 1: Enhance
-/enhance-prompt "why is login slow"
-# Returns:
-# INTENT: Identify performance bottlenecks in login flow
-# CONTEXT: Authentication module, database queries
-# ACTION: Trace execution path → identify slow operations → suggest optimizations
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+- **No active session OR standalone analysis**:
+  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
 
-# Step 2: Analyze with enhanced context
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Identify performance bottlenecks in login flow
-TASK: Trace login execution path and measure operation costs
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{**/*auth*,**/*login*}
-EXPECTED: Performance analysis, bottleneck identification, optimization recommendations
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on performance and database queries
-"
-```
+**Examples**:
+- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
+- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
 
-## Analysis Output Structure
+## Notes
 
-Based on code-analysis.md template, output includes:
-
-### 1. 思考过程 (Thinking Process)
-- Analysis strategy and approach
-- Key assumptions about code behavior
-
-### 2. 对问题的理解 (Understanding)
-- Restate analysis target
-- Confirm understanding of requirements
-
-### 3. 核心解答 (Core Answer)
-- Direct, concise answer to analysis question
-
-### 4. 详细分析与调用逻辑 (Detailed Analysis)
-- **代码段识别**: Relevant code sections
-- **执行流程**: Step-by-step execution flow
-- **调用图**: Visual call flow diagram with symbols:
-  - `───►` Function call
-  - `◄───` Return
-  - `│` Continuation
-  - `├─` Intermediate step
-  - `└─` Last step in block
-- **数据传递**: Data passing and state changes
-- **逻辑解释**: Why code behaves this way
-
-### 5. 总结 (Summary)
-- Key findings and recommendations
-
-## Session Output
-
-**Location**: `.workflow/WFS-[topic]/.chat/code-analysis-[timestamp].md`
-
-**Includes**:
-- Analysis target
-- Template used
-- Complete structured analysis
-- Call flow diagrams
-- Debugging insights
-- Recommendations
-
-## Use Cases
-
-| Use Case | Best Tool | Focus |
-|----------|-----------|-------|
-| **Understand execution flow** | gemini | Call sequences, data flow |
-| **Architectural patterns** | qwen | Design patterns, structure |
-| **Performance debugging** | codex | Bottlenecks, optimizations |
-| **Bug investigation** | codex | Error paths, edge cases |
-| **Code review** | gemini | Logic correctness, clarity |
-| **Refactoring planning** | qwen | Structure improvements |
-
-## Tool Selection Guide
-
-- **Gemini**: Best for general code understanding and tracing
-- **Qwen**: Best for architectural analysis and pattern recognition
-- **Codex**: Best for deep debugging and performance analysis
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Template path: `~/.claude/prompt-templates/code-analysis.md`
+- Always uses `--all-files` for comprehensive code context

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

@@ -8,16 +8,23 @@ examples:
   - /cli:mode:plan --tool qwen --enhance "plan microservices migration"
   - /cli:mode:plan --tool codex --cd "src/auth" "authentication system"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Mode: Plan (/cli:mode:plan)
 
 ## Purpose
 
-Execute planning and architecture analysis using CLI tools with specialized template.
+Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`).
 
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: `--cd` flag for directory-scoped planning
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Enhance topic with `/enhance-prompt` first
+- `--cd "path"` - Target directory for focused planning
+- `<topic>` (Required) - Planning topic or architectural question
 
 ## Execution Flow
 
@@ -26,79 +33,93 @@ Execute planning and architecture analysis using CLI tools with specialized temp
 3. Parse topic (original or enhanced)
 4. Detect target directory (from `--cd` or auto-infer)
 5. Build command for selected tool with planning template
-6. Execute analysis
-7. Save to session (if active)
+6. Execute analysis (read-only, no code modification)
+7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
 
 ## Core Rules
 
-1. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
-2. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-3. **Template Required**: Always use planning template
-4. **Session Output**: Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
+2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
+3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+4. **Template Required**: Always use planning template
+5. **Session Output**: Save analysis results to session chat
+
+## Planning Capabilities (via Template)
+
+- Strategic architecture insights and recommendations
+- Implementation roadmaps and suggestions
+- Key technical decisions analysis
+- Risk assessment
+- Resource planning
 
 ## Command Template
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
 ```bash
 cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: [planning goal from topic]
 TASK: Comprehensive planning and architecture analysis
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Strategic insights, implementation roadmap, key decisions
+EXPECTED: Strategic insights, implementation recommendations, key decisions
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
 "
 ```
 
 ## Examples
 
-**Basic Planning**:
+**Basic Planning Analysis**:
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Design user dashboard feature architecture
-TASK: Comprehensive architecture planning for dashboard
+PURPOSE: Design user dashboard architecture
+TASK: Plan dashboard component structure and data flow
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Architecture design, component structure, implementation roadmap
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability and UX
+EXPECTED: Architecture recommendations, component design, data flow diagram
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
 "
 ```
 
-**Directory-Specific**:
+**Directory-Specific Planning**:
 ```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Plan authentication system redesign
-TASK: Analyze current auth and plan improvements
+cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Plan API refactoring strategy
+TASK: Analyze current API structure and recommend improvements
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Migration strategy, security improvements, timeline
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on security and backward compatibility
+EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
 "
 ```
 
-**With Enhancement**:
+## Planning Workflow
+
 ```bash
-# User: /gemini:mode:plan --enhance "fix auth issues"
+# 1. Discover project structure
+~/.claude/scripts/get_modules_by_depth.sh
+mcp__code-index__find_files(pattern="*.ts")
 
-# Step 1: Enhance
-/enhance-prompt "fix auth issues"
-# Returns structured planning context
+# 2. Gather existing architecture info
+rg "architecture|design" --files-with-matches
 
-# Step 2: Plan with enhanced input
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [enhanced goal]
-TASK: [enhanced task description]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [enhanced context]
-EXPECTED: Strategic plan with enhanced requirements
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | [enhanced constraints]
-"
+# 3. Execute planning analysis (analysis only, no code changes)
+/cli:mode:plan "topic for strategic planning"
 ```
 
-## Session Output
+## Output Routing
 
-**Location**: `.workflow/WFS-[topic]/.chat/plan-[timestamp].md`
+**Output Destination Logic**:
+- **Active session exists AND planning is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+- **No active session OR exploratory planning**:
+  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
 
-**Includes**:
-- Planning topic
-- Template used
-- Analysis results
-- Implementation roadmap
-- Key decisions
+**Examples**:
+- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
+- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
+
+## Notes
+
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Template path: `~/.claude/prompt-templates/plan.md`
+- Always uses `--all-files` for comprehensive project context

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

@@ -1,40 +1,55 @@
 ---
 name: update-memory-full
 description: Complete project-wide CLAUDE.md documentation update
-usage: /update-memory-full
+usage: /update-memory-full [--tool <gemini|qwen|codex>]
+argument-hint: "[--tool gemini|qwen|codex]"
 examples:
-  - /update-memory-full                      # Full project documentation update
+  - /update-memory-full                      # Full project documentation update (gemini default)
+  - /update-memory-full --tool qwen          # Use Qwen for architecture analysis
+  - /update-memory-full --tool codex         # Use Codex for implementation validation
 ---
 
 ### 🚀 Command Overview: `/update-memory-full`
 
 Complete project-wide documentation update using depth-parallel execution.
 
+**Tool Selection**:
+- **Gemini (default)**: Documentation generation, pattern recognition, architecture review
+- **Qwen**: Architecture analysis, system design documentation
+- **Codex**: Implementation validation, code quality analysis
+
 ### 📝 Execution Template
 
 ```bash
 #!/bin/bash
 # Complete project-wide CLAUDE.md documentation update
 
-# Step 1: Code Index architecture analysis
+# Step 1: Parse tool selection (default: gemini)
+tool="gemini"
+[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
+[[ "$*" == *"--tool codex"* ]] && tool="codex"
+
+# Step 2: Code Index architecture analysis
 mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
 mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}")
 
-# Step 2: Cache git changes
+# Step 3: Cache git changes
 Bash(git add -A 2>/dev/null || true)
 
-# Step 3: Get and display project structure
+# Step 4: Get and display project structure
 modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
 count=$(echo "$modules" | wc -l)
 
-# Step 3: Analysis handover → Model takes control
+# Step 5: Analysis handover → Model takes control
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 
 # Pseudocode flow:
 # IF (module_count > 20 OR complex_project_detected):
-#     → Task "Complex project full update" subagent_type: "memory-gemini-bridge"
+#     → Task "Complex project full update" subagent_type: "memory-bridge"
 # ELSE:
 #     → Present plan and WAIT FOR USER APPROVAL before execution
+#
+# Pass tool parameter to update_module_claude.sh: "$tool"
 ```
 
 ### 🧠 Model Analysis Phase
@@ -43,9 +58,9 @@ After the bash script completes the initial analysis, the model takes control to
 
 1. **Analyze Complexity**: Review module count and project context
 2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files
-3. **Choose Strategy**: 
+3. **Choose Strategy**:
    - Simple projects: Present execution plan with CLAUDE.md paths to user
-   - Complex projects: Delegate to memory-gemini-bridge agent
+   - Complex projects: Delegate to memory-bridge agent
 4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated
 5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
 
@@ -56,17 +71,19 @@ After the bash script completes the initial analysis, the model takes control to
 Model will present detailed plan:
 ```
 📋 Update Plan:
+  Tool: [gemini|qwen|codex] (from --tool parameter)
+
   NEW CLAUDE.md files (X):
     - ./src/components/CLAUDE.md
     - ./src/services/CLAUDE.md
-  
+
   UPDATE existing CLAUDE.md files (Y):
     - ./CLAUDE.md
     - ./src/CLAUDE.md
     - ./tests/CLAUDE.md
 
   Total: N CLAUDE.md files will be processed
-  
+
   ⚠️ Confirm execution? (y/n)
 ```
 
@@ -84,7 +101,7 @@ depth_modules = organize_by_depth(modules)
 FOR depth FROM max_depth DOWN TO 0:
     FOR each module IN depth_modules[depth]:
         WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" &)
+        Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" "$tool" &)
     wait_all_jobs()
 
 # Step 6: Safety check and restore staging state
@@ -102,13 +119,43 @@ Bash(git status --short)
 ```
 
 **For Complex Projects (>20 modules):**
-The model will delegate to the memory-gemini-bridge agent using the Task tool:
-```
+
+The model will delegate to the memory-bridge agent with structured context:
+
+```javascript
 Task "Complex project full update"
-prompt: "Execute full documentation update for [count] modules using depth-parallel execution"
-subagent_type: "memory-gemini-bridge"
+subagent_type: "memory-bridge"
+prompt: `
+CONTEXT:
+- Total modules: ${module_count}
+- Tool: ${tool}  // from --tool parameter, default: gemini
+- Mode: full
+- Existing CLAUDE.md: ${existing_count}
+- New CLAUDE.md needed: ${new_count}
+
+MODULE LIST:
+${modules_output}  // Full output from get_modules_by_depth.sh list
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level before execution
+2. Process depths 5→0 sequentially, max 4 parallel jobs per depth
+3. Command format: update_module_claude.sh "<path>" "full" "${tool}" &
+4. Extract exact path from "depth:N|path:<PATH>|..." format
+5. Verify all ${module_count} modules are processed
+6. Run safety check after completion
+7. Display git status
+
+Execute depth-parallel updates for all modules.
+`
 ```
 
+**Agent receives complete context:**
+- Module count and tool selection
+- Full structured module list
+- Clear execution requirements
+- Path extraction format
+- Success criteria
+
 
 ### 📚 Usage Examples
 

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

@@ -1,15 +1,23 @@
 ---
 name: update-memory-related
 description: Context-aware CLAUDE.md documentation updates based on recent changes
-usage: /update-memory-related
+usage: /update-memory-related [--tool <gemini|qwen|codex>]
+argument-hint: "[--tool gemini|qwen|codex]"
 examples:
-  - /update-memory-related                    # Update documentation based on recent changes
+  - /update-memory-related                    # Update documentation based on recent changes (gemini default)
+  - /update-memory-related --tool qwen        # Use Qwen for architecture analysis
+  - /update-memory-related --tool codex       # Use Codex for implementation validation
 ---
 
 ### 🚀 Command Overview: `/update-memory-related`
 
 Context-aware documentation update for modules affected by recent changes.
 
+**Tool Selection**:
+- **Gemini (default)**: Documentation generation, pattern recognition, architecture review
+- **Qwen**: Architecture analysis, system design documentation
+- **Codex**: Implementation validation, code quality analysis
+
 
 ### 📝 Execution Template
 
@@ -17,30 +25,37 @@ Context-aware documentation update for modules affected by recent changes.
 #!/bin/bash
 # Context-aware CLAUDE.md documentation update
 
-# Step 1: Code Index refresh and architecture analysis
+# Step 1: Parse tool selection (default: gemini)
+tool="gemini"
+[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
+[[ "$*" == *"--tool codex"* ]] && tool="codex"
+
+# Step 2: Code Index refresh and architecture analysis
 mcp__code-index__refresh_index()
 mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
 
-# Step 2: Detect changed modules (before staging)
+# Step 3: Detect changed modules (before staging)
 changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list))
 
-# Step 3: Cache git changes (protect current state)
+# Step 4: Cache git changes (protect current state)
 Bash(git add -A 2>/dev/null || true)
 
-# Step 3: Use detected changes or fallback
+# Step 5: Use detected changes or fallback
 if [ -z "$changed" ]; then
     changed=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list | head -10))
 fi
 count=$(echo "$changed" | wc -l)
 
-# Step 4: Analysis handover → Model takes control  
+# Step 6: Analysis handover → Model takes control
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 
 # Pseudocode flow:
 # IF (change_count > 15 OR complex_changes_detected):
-#     → Task "Complex project related update" subagent_type: "memory-gemini-bridge"
+#     → Task "Complex project related update" subagent_type: "memory-bridge"
 # ELSE:
 #     → Present plan and WAIT FOR USER APPROVAL before execution
+#
+# Pass tool parameter to update_module_claude.sh: "$tool"
 ```
 
 ### 🧠 Model Analysis Phase
@@ -51,7 +66,7 @@ After the bash script completes change detection, the model takes control to:
 2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files
 3. **Choose Strategy**: 
    - Simple changes: Present execution plan with CLAUDE.md paths to user
-   - Complex changes: Delegate to memory-gemini-bridge agent
+   - Complex changes: Delegate to memory-bridge agent
 4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules
 5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
 
@@ -62,18 +77,20 @@ After the bash script completes change detection, the model takes control to:
 Model will present detailed plan for affected modules:
 ```
 📋 Related Update Plan:
+  Tool: [gemini|qwen|codex] (from --tool parameter)
+
   CHANGED modules affecting CLAUDE.md:
-  
+
   NEW CLAUDE.md files (X):
     - ./src/api/auth/CLAUDE.md  [new module]
     - ./src/utils/helpers/CLAUDE.md  [new module]
-  
+
   UPDATE existing CLAUDE.md files (Y):
     - ./src/api/CLAUDE.md  [parent of changed auth/]
     - ./src/CLAUDE.md  [root level]
 
   Total: N CLAUDE.md files will be processed for recent changes
-  
+
   ⚠️ Confirm execution? (y/n)
 ```
 
@@ -91,7 +108,7 @@ depth_modules = organize_by_depth(changed_modules)
 FOR depth FROM max_depth DOWN TO 0:
     FOR each module IN depth_modules[depth]:
         WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" &)
+        Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" "$tool" &)
     wait_all_jobs()
 
 # Step 6: Safety check and restore staging state
@@ -109,13 +126,44 @@ Bash(git diff --stat)
 ```
 
 **For Complex Changes (>15 modules):**
-The model will delegate to the memory-gemini-bridge agent using the Task tool:
-```
+
+The model will delegate to the memory-bridge agent with structured context:
+
+```javascript
 Task "Complex project related update"
-prompt: "Execute context-aware update for [count] changed modules using depth-parallel execution"
-subagent_type: "memory-gemini-bridge"
+subagent_type: "memory-bridge"
+prompt: `
+CONTEXT:
+- Total modules: ${change_count}
+- Tool: ${tool}  // from --tool parameter, default: gemini
+- Mode: related
+- Changed modules detected via: detect_changed_modules.sh
+- Existing CLAUDE.md: ${existing_count}
+- New CLAUDE.md needed: ${new_count}
+
+MODULE LIST:
+${changed_modules_output}  // Full output from detect_changed_modules.sh list
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level before execution
+2. Process depths sequentially (deepest→shallowest), max 4 parallel jobs per depth
+3. Command format: update_module_claude.sh "<path>" "related" "${tool}" &
+4. Extract exact path from "depth:N|path:<PATH>|..." format
+5. Verify all ${change_count} modules are processed
+6. Run safety check after completion
+7. Display git diff --stat
+
+Execute depth-parallel updates for changed modules only.
+`
 ```
 
+**Agent receives complete context:**
+- Changed module count and tool selection
+- Full structured module list (changed only)
+- Clear execution requirements with "related" mode
+- Path extraction format
+- Success criteria
+
 
 ### 📚 Usage Examples
 

.claude/commands/version.md

@@ -170,8 +170,8 @@ Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-W
 
 **Scenario 3: Development version**
 ```
-✨ You are running a development version (3.3.0-dev)
-This is newer than the latest stable release (v3.2.2)
+✨ You are running a development version (3.4.0-dev)
+This is newer than the latest stable release (v3.3.0)
 ```
 
 ## Simple Bash Commands

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

@@ -0,0 +1,421 @@
+---
+name: action-plan-verify
+description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
+usage: /workflow:action-plan-verify [--session <session-id>]
+argument-hint: "optional: --session <session-id>"
+examples:
+  - /workflow:action-plan-verify
+  - /workflow:action-plan-verify --session WFS-auth
+allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`synthesis-specification.md`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
+
+**Synthesis Authority**: The `synthesis-specification.md` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+```bash
+# Detect active workflow session
+IF --session parameter provided:
+    session_id = provided session
+ELSE:
+    CHECK: .workflow/.active-* marker files
+    IF active_session EXISTS:
+        session_id = get_active_session()
+    ELSE:
+        ERROR: "No active workflow session found. Use --session <session-id>"
+        EXIT
+
+# Derive absolute paths
+session_dir = .workflow/WFS-{session}
+brainstorm_dir = session_dir/.brainstorming
+task_dir = session_dir/.task
+
+# Validate required artifacts
+SYNTHESIS = brainstorm_dir/synthesis-specification.md
+IMPL_PLAN = session_dir/IMPL_PLAN.md
+TASK_FILES = Glob(task_dir/*.json)
+
+# Abort if missing
+IF NOT EXISTS(SYNTHESIS):
+    ERROR: "synthesis-specification.md not found. Run /workflow:brainstorm:synthesis first"
+    EXIT
+
+IF NOT EXISTS(IMPL_PLAN):
+    ERROR: "IMPL_PLAN.md not found. Run /workflow:plan first"
+    EXIT
+
+IF TASK_FILES.count == 0:
+    ERROR: "No task JSON files found. Run /workflow:plan first"
+    EXIT
+```
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only minimal necessary context from each artifact:
+
+**From synthesis-specification.md**:
+- Functional Requirements (IDs, descriptions, acceptance criteria)
+- Non-Functional Requirements (IDs, targets)
+- Business Requirements (IDs, success metrics)
+- Key Architecture Decisions
+- Risk factors and mitigation strategies
+- Implementation Roadmap (high-level phases)
+
+**From IMPL_PLAN.md**:
+- Summary and objectives
+- Context Analysis
+- Implementation Strategy
+- Task Breakdown Summary
+- Success Criteria
+- Brainstorming Artifacts References (if present)
+
+**From task.json files**:
+- Task IDs
+- Titles and descriptions
+- Status
+- Dependencies (depends_on, blocks)
+- Context (requirements, focus_paths, acceptance, artifacts)
+- Flow control (pre_analysis, implementation_approach)
+- Meta (complexity, priority, use_codex)
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+**Requirements inventory**:
+- Each functional/non-functional/business requirement with stable ID
+- Requirement text, acceptance criteria, priority
+
+**Architecture decisions inventory**:
+- ADRs from synthesis
+- Technology choices
+- Data model references
+
+**Task coverage mapping**:
+- Map each task to one or more requirements (by ID reference or keyword inference)
+- Map each requirement to covering tasks
+
+**Dependency graph**:
+- Task-to-task dependencies (depends_on, blocks)
+- Requirement-level dependencies (from synthesis)
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Requirements Coverage Analysis
+
+- **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
+- **Unmapped Tasks**: Tasks with no clear requirement linkage
+- **NFR Coverage Gaps**: Non-functional requirements (performance, security, scalability) not reflected in tasks
+
+#### B. Consistency Validation
+
+- **Requirement Conflicts**: Tasks contradicting synthesis requirements
+- **Architecture Drift**: IMPL_PLAN architecture not matching synthesis ADRs
+- **Terminology Drift**: Same concept named differently across IMPL_PLAN and tasks
+- **Data Model Inconsistency**: Tasks referencing entities/fields not in synthesis data model
+
+#### C. Dependency Integrity
+
+- **Circular Dependencies**: Task A depends on B, B depends on C, C depends on A
+- **Missing Dependencies**: Task requires outputs from another task but no explicit dependency
+- **Broken Dependencies**: Task depends on non-existent task ID
+- **Logical Ordering Issues**: Implementation tasks before foundational setup without dependency note
+
+#### D. Synthesis Alignment
+
+- **Priority Conflicts**: High-priority synthesis requirements mapped to low-priority tasks
+- **Success Criteria Mismatch**: IMPL_PLAN success criteria not covering synthesis acceptance criteria
+- **Risk Mitigation Gaps**: Critical risks in synthesis without corresponding mitigation tasks
+
+#### E. Task Specification Quality
+
+- **Ambiguous Focus Paths**: Tasks with vague or missing focus_paths
+- **Underspecified Acceptance**: Tasks without clear acceptance criteria
+- **Missing Artifacts References**: Tasks not referencing relevant brainstorming artifacts in context.artifacts
+- **Weak Flow Control**: Tasks without clear implementation_approach or pre_analysis steps
+- **Missing Target Files**: Tasks without flow_control.target_files specification
+
+#### F. Duplication Detection
+
+- **Overlapping Task Scope**: Multiple tasks with nearly identical descriptions
+- **Redundant Requirements Coverage**: Same requirement covered by multiple tasks without clear partitioning
+
+#### G. Feasibility Assessment
+
+- **Complexity Misalignment**: Task marked "simple" but requires multiple file modifications
+- **Resource Conflicts**: Parallel tasks requiring same resources/files
+- **Skill Gap Risks**: Tasks requiring skills not in team capability assessment (from synthesis)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**:
+  - Violates synthesis authority (requirement conflict)
+  - Core requirement with zero coverage
+  - Circular dependencies
+  - Broken dependencies
+
+- **HIGH**:
+  - NFR coverage gaps
+  - Priority conflicts
+  - Missing risk mitigation tasks
+  - Ambiguous acceptance criteria
+
+- **MEDIUM**:
+  - Terminology drift
+  - Missing artifacts references
+  - Weak flow control
+  - Logical ordering issues
+
+- **LOW**:
+  - Style/wording improvements
+  - Minor redundancy not affecting execution
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+```markdown
+## Action Plan Verification Report
+
+**Session**: WFS-{session-id}
+**Generated**: {timestamp}
+**Artifacts Analyzed**: synthesis-specification.md, IMPL_PLAN.md, {N} task files
+
+---
+
+### Executive Summary
+
+- **Overall Risk Level**: CRITICAL | HIGH | MEDIUM | LOW
+- **Recommendation**: BLOCK_EXECUTION | PROCEED_WITH_FIXES | PROCEED_WITH_CAUTION | PROCEED
+- **Critical Issues**: {count}
+- **High Issues**: {count}
+- **Medium Issues**: {count}
+- **Low Issues**: {count}
+
+---
+
+### Findings Summary
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| C1 | Coverage | CRITICAL | synthesis:FR-03 | Requirement "User auth" has zero task coverage | Add authentication implementation task |
+| H1 | Consistency | HIGH | IMPL-1.2 vs synthesis:ADR-02 | Task uses REST while synthesis specifies GraphQL | Align task with ADR-02 decision |
+| M1 | Specification | MEDIUM | IMPL-2.1 | Missing context.artifacts reference | Add @synthesis reference |
+| L1 | Duplication | LOW | IMPL-3.1, IMPL-3.2 | Similar scope | Consider merging |
+
+(Add one row per finding; generate stable IDs prefixed by severity initial.)
+
+---
+
+### Requirements Coverage Analysis
+
+| Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
+|----------------|---------------------|-----------|----------|----------------|-------|
+| FR-01 | User authentication | ✅ Yes | IMPL-1.1, IMPL-1.2 | ✅ Match | Complete |
+| FR-02 | Data export | ✅ Yes | IMPL-2.3 | ⚠️ Mismatch | High req → Med priority task |
+| FR-03 | Profile management | ❌ No | - | - | **CRITICAL: Zero coverage** |
+| NFR-01 | Response time <200ms | ❌ No | - | - | **HIGH: No performance tasks** |
+
+**Coverage Metrics**:
+- Functional Requirements: 85% (17/20 covered)
+- Non-Functional Requirements: 40% (2/5 covered)
+- Business Requirements: 100% (5/5 covered)
+
+---
+
+### Unmapped Tasks
+
+| Task ID | Title | Issue | Recommendation |
+|---------|-------|-------|----------------|
+| IMPL-4.5 | Refactor utils | No requirement linkage | Link to technical debt or remove |
+
+---
+
+### Dependency Graph Issues
+
+**Circular Dependencies**: None detected ✅
+
+**Broken Dependencies**:
+- IMPL-2.3 depends on "IMPL-2.4" (non-existent)
+
+**Logical Ordering Issues**:
+- IMPL-5.1 (integration test) has no dependency on IMPL-1.* (implementation tasks)
+
+---
+
+### Synthesis Alignment Issues
+
+| Issue Type | Synthesis Reference | IMPL_PLAN/Task | Impact | Recommendation |
+|------------|---------------------|----------------|--------|----------------|
+| Architecture Conflict | synthesis:ADR-01 (JWT auth) | IMPL_PLAN uses session cookies | HIGH | Update IMPL_PLAN to use JWT |
+| Priority Mismatch | synthesis:FR-02 (High) | IMPL-2.3 (Medium) | MEDIUM | Elevate task priority |
+| Missing Risk Mitigation | synthesis:Risk-03 (API rate limits) | No mitigation tasks | HIGH | Add rate limiting implementation task |
+
+---
+
+### Task Specification Quality Issues
+
+**Missing Artifacts References**: 12 tasks lack context.artifacts
+**Weak Flow Control**: 5 tasks lack implementation_approach
+**Missing Target Files**: 8 tasks lack flow_control.target_files
+
+**Sample Issues**:
+- IMPL-1.2: No context.artifacts reference to synthesis
+- IMPL-3.1: Missing flow_control.target_files specification
+- IMPL-4.2: Vague focus_paths ["src/"] - needs refinement
+
+---
+
+### Feasibility Concerns
+
+| Concern | Tasks Affected | Issue | Recommendation |
+|---------|----------------|-------|----------------|
+| Skill Gap | IMPL-6.1, IMPL-6.2 | Requires Kubernetes expertise not in team | Add training task or external consultant |
+| Resource Conflict | IMPL-3.1, IMPL-3.2 | Both modify src/auth/service.ts in parallel | Add dependency or serialize |
+
+---
+
+### Metrics
+
+- **Total Requirements**: 30 (20 functional, 5 non-functional, 5 business)
+- **Total Tasks**: 25
+- **Overall Coverage**: 77% (23/30 requirements with ≥1 task)
+- **Critical Issues**: 2
+- **High Issues**: 5
+- **Medium Issues**: 8
+- **Low Issues**: 3
+
+---
+
+### Next Actions
+
+#### If CRITICAL Issues Exist (Current Status: 2 CRITICAL)
+**Recommendation**: ❌ **BLOCK EXECUTION** - Resolve CRITICAL issues before proceeding
+
+**Required Actions**:
+1. **CRITICAL**: Add authentication implementation tasks to cover FR-03
+2. **CRITICAL**: Add performance optimization tasks to cover NFR-01
+
+#### If Only HIGH/MEDIUM/LOW Issues
+**Recommendation**: ⚠️ **PROCEED WITH CAUTION** - Issues are non-blocking but should be addressed
+
+**Suggested Improvements**:
+1. Add context.artifacts references to all tasks (use /task:replan)
+2. Fix broken dependency IMPL-2.3 → IMPL-2.4
+3. Add flow_control.target_files to underspecified tasks
+
+#### Command Suggestions
+```bash
+# Fix critical coverage gaps
+/task:create "Implement user authentication (FR-03)"
+/task:create "Add performance optimization (NFR-01)"
+
+# Refine existing tasks
+/task:replan IMPL-1.2 "Add context.artifacts and target_files"
+
+# Update IMPL_PLAN if architecture drift detected
+# (Manual edit required)
+```
+```
+
+### 7. Provide Remediation Options
+
+At end of report, ask the user:
+
+```markdown
+### 🔧 Remediation Options
+
+Would you like me to:
+1. **Generate task suggestions** for unmapped requirements (no auto-creation)
+2. **Provide specific edit commands** for top N issues (you execute manually)
+3. **Create remediation checklist** for systematic fixing
+
+(Do NOT apply fixes automatically - this is read-only analysis)
+```
+
+### 8. Update Session Metadata
+
+```json
+{
+  "phases": {
+    "PLAN": {
+      "status": "completed",
+      "action_plan_verification": {
+        "completed": true,
+        "completed_at": "timestamp",
+        "overall_risk_level": "HIGH",
+        "recommendation": "PROCEED_WITH_FIXES",
+        "issues": {
+          "critical": 2,
+          "high": 5,
+          "medium": 8,
+          "low": 3
+        },
+        "coverage": {
+          "functional_requirements": 0.85,
+          "non_functional_requirements": 0.40,
+          "business_requirements": 1.00
+        },
+        "report_path": ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
+      }
+    }
+  }
+}
+```
+
+## Operating Principles
+
+### Context Efficiency
+- **Minimal high-signal tokens**: Focus on actionable findings
+- **Progressive disclosure**: Load artifacts incrementally
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes produces consistent IDs and counts
+
+### Analysis Guidelines
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize synthesis violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+### Verification Taxonomy
+- **Coverage**: Requirements → Tasks mapping
+- **Consistency**: Cross-artifact alignment
+- **Dependencies**: Task ordering and relationships
+- **Synthesis Alignment**: Adherence to authoritative requirements
+- **Task Quality**: Specification completeness
+- **Feasibility**: Implementation risks
+
+## Behavior Rules
+
+- **If no issues found**: Report "✅ Action plan verification passed. No issues detected." and suggest proceeding to `/workflow:execute`.
+- **If CRITICAL issues exist**: Recommend blocking execution until resolved.
+- **If only HIGH/MEDIUM issues**: User may proceed with caution, but provide improvement suggestions.
+- **If IMPL_PLAN.md or task files missing**: Instruct user to run `/workflow:plan` first.
+- **Always provide actionable remediation suggestions**: Don't just identify problems—suggest solutions.
+
+## Context
+
+{ARGS}

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

@@ -1,6 +1,6 @@
 ---
 name: synthesis
-description: Generate synthesis-report.md from topic-framework and role analyses with @ references
+description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
 usage: /workflow:brainstorm:synthesis
 argument-hint: "no arguments required - synthesizes existing framework and role analyses"
 examples:
@@ -11,25 +11,36 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
 ## 🧩 **Synthesis Document Generator**
 
 ### Core Function
-**Specialized command for generating synthesis-report.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive strategic analysis with cross-role insights.
+**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights.
+
+**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
 
 ### Primary Capabilities
-- **Framework Integration**: Reference topic-framework.md discussion points across all roles
-- **Role Analysis Integration**: Consolidate all role/analysis.md files using @ references
-- **Cross-Framework Comparison**: Compare how each role addressed framework discussion points
+- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime
+- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles
+- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references
+- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points
 - **@ Reference System**: Create structured references to source documents
 - **Update Detection**: Smart updates when new role analyses are added
+- **Flexible Participation**: Supports any subset of available roles (1 to 9+)
 
 ### Document Integration Model
 **Three-Document Reference System**:
 1. **topic-framework.md** → Structured discussion framework (input)
 2. **[role]/analysis.md** → Role-specific analyses addressing framework (input)
-3. **synthesis-report.md** → Integrated synthesis with @ references (output)
+3. **synthesis-specification.md** → Complete integrated specification (output)
 
 ## ⚙️ **Execution Protocol**
 
-### ⚠️ Direct Execution Only
-**DO NOT use Task tool or delegate to any agent** - This is a document synthesis task using only Read/Write/Glob tools for aggregating existing analyses.
+### ⚠️ Direct Execution by Main Claude
+**Execution Model**: Main Claude directly executes this command without delegating to sub-agents.
+
+**Rationale**:
+- **Full Context Access**: Avoids context transmission loss that occurs with Task tool delegation
+- **Complex Cognitive Analysis**: Leverages main Claude's complete reasoning capabilities for cross-role synthesis
+- **Tool Usage**: Combines Read/Write/Glob tools with main Claude's analytical intelligence
+
+**DO NOT use Task tool** - Main Claude performs intelligent analysis directly while reading/writing files, ensuring no information loss from context passing.
 
 ### Phase 1: Document Discovery & Validation
 ```bash
@@ -51,22 +62,39 @@ IF NOT EXISTS:
 
 ### Phase 2: Role Analysis Discovery
 ```bash
-# Discover available role analyses
+# Dynamically discover available role analyses
 SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/
 FIND_ANALYSES: [
-    */analysis.md files in role directories
+    Scan all subdirectories for */analysis.md files
+    Extract role names from directory names
 ]
+
+# Available roles (for reference, actual participation is dynamic):
+# - product-manager
+# - product-owner
+# - scrum-master
+# - system-architect
+# - ui-designer
+# - ux-expert
+# - data-architect
+# - subject-matter-expert
+# - test-strategist
+
 LOAD_DOCUMENTS: {
     "topic_framework": topic-framework.md,
-    "role_analyses": [discovered analysis.md files],
-    "existing_synthesis": synthesis-report.md (if exists)
+    "role_analyses": [dynamically discovered analysis.md files],
+    "participating_roles": [extract role names from discovered directories],
+    "existing_synthesis": synthesis-specification.md (if exists)
 }
+
+# Note: Not all roles participate in every brainstorming session
+# Only synthesize roles that actually produced analysis.md files
 ```
 
 ### Phase 3: Update Mechanism Check
 ```bash
 # Check for existing synthesis
-IF synthesis-report.md EXISTS:
+IF synthesis-specification.md EXISTS:
     SHOW current synthesis summary to user
     ASK: "Synthesis exists. Do you want to:"
     OPTIONS:
@@ -84,42 +112,60 @@ Initialize synthesis task tracking:
   {"content": "Validate topic-framework.md and role analyses availability", "status": "in_progress", "activeForm": "Validating source documents"},
   {"content": "Load topic framework discussion points structure", "status": "pending", "activeForm": "Loading framework structure"},
   {"content": "Cross-analyze role responses to each framework point", "status": "pending", "activeForm": "Cross-analyzing framework responses"},
-  {"content": "Generate synthesis-report.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"},
+  {"content": "Generate synthesis-specification.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"},
   {"content": "Update session metadata with synthesis completion", "status": "pending", "activeForm": "Updating session metadata"}
 ]
 ```
 
-### Phase 4: Cross-Role Analysis Execution
+### Phase 5: Cross-Role Analysis Execution
 
-#### 4.1 Data Collection and Preprocessing
+**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2.
+
+#### 5.1 Data Collection and Preprocessing
 ```pseudo
-FOR each role_directory in brainstorming_roles:
-    IF role_directory exists:
-        role_analysis = Read(role_directory + "/analysis.md")
-        role_recommendations = Read(role_directory + "/recommendations.md") IF EXISTS
-        role_insights[role] = extract_key_insights(role_analysis)
-        role_recommendations[role] = extract_recommendations(role_analysis)
-        role_concerns[role] = extract_concerns_risks(role_analysis)
+# Iterate over dynamically discovered role analyses
+FOR each discovered_role IN participating_roles:
+    role_directory = brainstorm_dir + "/" + discovered_role
+
+    # Load role analysis (required)
+    role_analysis = Read(role_directory + "/analysis.md")
+
+    # Load optional artifacts if present
+    IF EXISTS(role_directory + "/recommendations.md"):
+        role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md")
     END IF
+
+    # Extract insights from analysis
+    role_insights[discovered_role] = extract_key_insights(role_analysis)
+    role_recommendations[discovered_role] = extract_recommendations(role_analysis)
+    role_concerns[discovered_role] = extract_concerns_risks(role_analysis)
+    role_diagrams[discovered_role] = identify_diagrams_and_visuals(role_analysis)
 END FOR
+
+# Log participating roles for metadata
+participating_role_count = COUNT(participating_roles)
+participating_role_names = participating_roles
 ```
 
-#### 4.2 Cross-Role Insight Analysis
+#### 5.2 Cross-Role Insight Analysis
 ```pseudo
-# Consensus identification
+# Consensus identification (across all participating roles)
 consensus_areas = identify_common_themes(role_insights)
 agreement_matrix = create_agreement_matrix(role_recommendations)
 
-# Disagreement analysis
+# Disagreement analysis (track which specific roles disagree)
 disagreement_areas = identify_conflicting_views(role_insights)
 tension_points = analyze_role_conflicts(role_recommendations)
+FOR each conflict IN disagreement_areas:
+    conflict.dissenting_roles = identify_dissenting_roles(conflict)
+END FOR
 
 # Innovation opportunity extraction
 innovation_opportunities = extract_breakthrough_ideas(role_insights)
 synergy_opportunities = identify_cross_role_synergies(role_insights)
 ```
 
-#### 4.3 Priority and Decision Matrix Generation
+#### 5.3 Priority and Decision Matrix Generation
 ```pseudo
 # Create comprehensive evaluation matrix
 FOR each recommendation:
@@ -137,16 +183,6 @@ SORT recommendations BY priority_score DESC
 ## 📊 **Output Specification**
 
 ### Output Location
-```
-.workflow/WFS-{topic-slug}/.brainstorming/
-├── topic-framework.md          # Input: Framework structure
-├── [role]/analysis.md          # Input: Role analyses (multiple)
-└── synthesis-report.md         # ★ OUTPUT: Integrated synthesis with @ references
-```
-
-### Streamlined Single-Document Output ⚠️ SIMPLIFIED STRUCTURE
-
-#### Output Document - Single Comprehensive Synthesis
 The synthesis process creates **one consolidated document** that integrates all role perspectives:
 
 ```
@@ -157,30 +193,74 @@ The synthesis process creates **one consolidated document** that integrates all
 ```
 
 #### synthesis-specification.md Structure (Complete Specification)
+
+**Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint.
+**Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
+
 ```markdown
 # [Topic] - Integrated Implementation Specification
 
 **Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
 **Source Integration**: All brainstorming role perspectives consolidated
+**Document Type**: Requirements & Design Specification (WHAT to build)
 
 ## Executive Summary
 Strategic overview with key insights, breakthrough opportunities, and implementation priorities.
 
+## Key Designs & Decisions
+### Core Architecture Diagram
+```mermaid
+graph TD
+    A[Component A] --> B[Component B]
+    B --> C[Component C]
+```
+*Reference: @system-architect/analysis.md#architecture-diagram*
+
+### User Journey Map
+![User Journey](./assets/user-journey.png)
+*Reference: @ux-expert/analysis.md#user-journey*
+
+### Data Model Overview
+```mermaid
+erDiagram
+    USER ||--o{ ORDER : places
+    ORDER ||--|{ LINE-ITEM : contains
+```
+*Reference: @data-architect/analysis.md#data-model*
+
+### Architecture Decision Records (ADRs)
+**ADR-01: [Decision Title]**
+- **Context**: Background and problem statement
+- **Decision**: Chosen approach
+- **Rationale**: Why this approach was selected
+- **Reference**: @system-architect/analysis.md#adr-01
+
+## Controversial Points & Alternatives
+| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
+|-------|------------------|-------------------------|--------------------| -----------------|
+| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
+| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
+
+*This section preserves decision context and rejected alternatives for future reference.*
+
 ## Requirements & Acceptance Criteria
 ### Functional Requirements
-| ID | Description | Source | Priority | Acceptance | Dependencies |
-|----|-------------|--------|----------|------------|--------------|
-| FR-01 | Core feature | @role/analysis.md | High | Criteria | None |
+| ID | Description | Rationale Summary | Source | Priority | Acceptance | Dependencies |
+|----|-------------|-------------------|--------|----------|------------|--------------|
+| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password | None |
+| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON | FR-01 |
 
 ### Non-Functional Requirements
-| ID | Description | Target | Validation |
-|----|-------------|--------|------------|
-| NFR-01 | Performance | <200ms | Testing |
+| ID | Description | Rationale Summary | Target | Validation | Source |
+|----|-------------|-------------------|--------|------------|--------|
+| NFR-01 | Response time | UX research shows <200ms critical | <200ms | Load testing | @ux-expert/analysis.md |
+| NFR-02 | Data encryption | Compliance requirement | AES-256 | Security audit | @security-expert/analysis.md |
 
 ### Business Requirements
-| ID | Description | Value | Success Metric |
-|----|-------------|-------|----------------|
-| BR-01 | User engagement | High | 80% retention |
+| ID | Description | Rationale Summary | Value | Success Metric | Source |
+|----|-------------|-------------------|-------|----------------|--------|
+| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
+| BR-02 | Revenue growth | Business case justification | High | 25% MRR increase | @product-owner/analysis.md |
 
 ## Design Specifications
 ### UI/UX Guidelines
@@ -201,7 +281,34 @@ Strategic overview with key insights, breakthrough opportunities, and implementa
 - Compliance requirements and regulations
 - Technical quality and domain-specific patterns
 
-## Implementation Roadmap
+## Process & Collaboration Concerns
+**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
+
+### Team Capability Assessment
+| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
+|----------------|---------------|--------------|---------------------|-----------|
+| Kubernetes | Intermediate | Need advanced knowledge | Training + external consultant | @scrum-master/analysis.md |
+| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
+
+### Process Risks
+| Risk | Impact | Probability | Mitigation | Owner |
+|------|--------|-------------|------------|-------|
+| Cross-team API dependency | High | Medium | Early API contract definition | @scrum-master/analysis.md |
+| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | @ux-expert/analysis.md |
+
+### Collaboration Patterns
+- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
+- **Architecture Reviews**: Weekly arch review for system-level decisions
+- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
+- **Reference**: @scrum-master/analysis.md#collaboration
+
+### Timeline Constraints
+- **Blocking Dependencies**: Project-X API must complete before Phase 2
+- **Resource Constraints**: Only 2 backend developers available in Q1
+- **External Dependencies**: Third-party OAuth provider integration timeline
+- **Reference**: @scrum-master/analysis.md#constraints
+
+## Implementation Roadmap (High-Level)
 ### Development Phases
 **Phase 1** (0-3 months): Foundation and core features
 **Phase 2** (3-6 months): Advanced features and integrations
@@ -212,10 +319,12 @@ Strategic overview with key insights, breakthrough opportunities, and implementa
 - Testing strategy and quality assurance
 - Deployment and monitoring approach
 
-### Task Breakdown
-- Epic and feature mapping aligned with requirements
-- Sprint planning guidance with dependency management
-- Resource allocation and timeline recommendations
+### Feature Grouping (Epic-Level)
+- High-level feature grouping and prioritization
+- Epic-level dependencies and sequencing
+- Strategic milestones and release planning
+
+**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
 
 ## Risk Assessment & Mitigation
 ### Critical Risks Identified
@@ -235,6 +344,9 @@ Strategic overview with key insights, breakthrough opportunities, and implementa
 
 ### Streamlined Status Synchronization
 Upon completion, update `workflow-session.json`:
+
+**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
+
 ```json
 {
   "phases": {
@@ -242,22 +354,47 @@ Upon completion, update `workflow-session.json`:
       "status": "completed",
       "synthesis_completed": true,
       "completed_at": "timestamp",
-      "participating_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
+      "participating_roles": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
+      "available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
       "consolidated_output": {
         "synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md"
       },
       "synthesis_quality": {
         "role_integration": "complete",
         "requirement_coverage": "comprehensive",
+        "decision_transparency": "alternatives_documented",
+        "process_risks_identified": true,
         "implementation_readiness": "ready"
       },
       "content_metrics": {
-        "roles_synthesized": 9,
-        "functional_requirements": 25,
-        "non_functional_requirements": 12,
-        "business_requirements": 8,
-        "implementation_phases": 3,
-        "risk_factors_identified": 8
+        "roles_synthesized": "<COUNT(participating_roles)>",
+        "functional_requirements": "<dynamic-count>",
+        "non_functional_requirements": "<dynamic-count>",
+        "business_requirements": "<dynamic-count>",
+        "architecture_decisions": "<dynamic-count>",
+        "controversial_points": "<dynamic-count>",
+        "diagrams_included": "<dynamic-count>",
+        "process_risks": "<dynamic-count>",
+        "team_skill_gaps": "<dynamic-count>",
+        "implementation_phases": "<dynamic-count>",
+        "risk_factors_identified": "<dynamic-count>"
+      }
+    }
+  }
+}
+```
+
+**Example with actual values**:
+```json
+{
+  "phases": {
+    "BRAINSTORM": {
+      "status": "completed",
+      "participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"],
+      "content_metrics": {
+        "roles_synthesized": 5,
+        "functional_requirements": 18,
+        "controversial_points": 2
       }
     }
   }
@@ -268,28 +405,96 @@ Upon completion, update `workflow-session.json`:
 
 ### Required Synthesis Elements
 - [ ] Integration of all available role analyses with comprehensive coverage
-- [ ] Clear identification of consensus areas and disagreement points
+- [ ] **Key Designs & Decisions**: Architecture diagrams, user journey maps, ADRs documented
+- [ ] **Controversial Points**: Disagreement points, alternatives, and decision rationale captured
+- [ ] **Process Concerns**: Team capability gaps, process risks, collaboration patterns identified
 - [ ] Quantified priority recommendation matrix with evaluation criteria
 - [ ] Actionable implementation plan with phased approach
 - [ ] Comprehensive risk assessment with mitigation strategies
 
 ### Synthesis Analysis Quality Standards
 - [ ] **Completeness**: Integrates all available role analyses without gaps
+- [ ] **Visual Clarity**: Key diagrams (architecture, data model, user journey) included via Mermaid or images
+- [ ] **Decision Transparency**: Documents not just decisions, but alternatives and why they were rejected
 - [ ] **Insight Generation**: Identifies cross-role patterns and deep insights
-- [ ] **Actionability**: Provides specific, executable recommendations and next steps
-- [ ] **Balance**: Considers all role perspectives and addresses concerns
+- [ ] **Actionability**: Provides specific, executable recommendations with rationale
+- [ ] **Balance**: Considers all role perspectives, including process-oriented roles (Scrum Master)
 - [ ] **Forward-Looking**: Includes long-term strategic and innovation considerations
 
 ### Output Validation Criteria
 - [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation
-- [ ] **Resource-Aware**: Implementation plans consider resource and time constraints
-- [ ] **Risk-Managed**: Comprehensive risk assessment with mitigation strategies
+- [ ] **Context-Rich**: Each requirement includes rationale summary for immediate understanding
+- [ ] **Resource-Aware**: Team skill gaps and constraints explicitly documented
+- [ ] **Risk-Managed**: Both technical and process risks captured with mitigation strategies
 - [ ] **Measurable Success**: Clear success metrics and monitoring frameworks
 - [ ] **Clear Actions**: Specific next steps with assigned responsibilities and timelines
 
 ### Integration Excellence Standards
-- [ ] **Cross-Role Synthesis**: Successfully identifies and resolves role perspective conflicts
+- [ ] **Cross-Role Synthesis**: Successfully identifies and documents role perspective conflicts
+- [ ] **No Role Marginalization**: Process, UX, and compliance concerns equally visible as functional requirements
 - [ ] **Strategic Coherence**: Recommendations form coherent strategic direction
-- [ ] **Implementation Readiness**: Plans are detailed enough for immediate execution
+- [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
 - [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+- [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
+- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+
+## 🚀 **Recommended Next Steps**
+
+After synthesis completion, follow this recommended workflow:
+
+### Option 1: Standard Planning Workflow (Recommended)
+```bash
+# Step 1: Verify conceptual clarity (Quality Gate)
+/workflow:concept-verify --session WFS-{session-id}
+# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
+
+# Step 2: Proceed to action planning (after concept verification)
+/workflow:plan --session WFS-{session-id}
+# → Generates IMPL_PLAN.md and task.json files
+
+# Step 3: Verify action plan quality (Quality Gate)
+/workflow:action-plan-verify --session WFS-{session-id}
+# → Read-only analysis to catch issues before execution
+
+# Step 4: Start implementation
+/workflow:execute --session WFS-{session-id}
+```
+
+### Option 2: TDD Workflow
+```bash
+# Step 1: Verify conceptual clarity
+/workflow:concept-verify --session WFS-{session-id}
+
+# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
+/workflow:tdd-plan --session WFS-{session-id} "Feature description"
+
+# Step 3: Verify TDD plan quality
+/workflow:action-plan-verify --session WFS-{session-id}
+
+# Step 4: Execute TDD workflow
+/workflow:execute --session WFS-{session-id}
+```
+
+### Quality Gates Explained
+
+**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
+- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
+- **Time**: 10-20 minutes (interactive)
+- **Value**: Reduces downstream rework by 40-60%
+- **Output**: Updated synthesis-specification.md with clarifications
+
+**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
+- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
+- **Time**: 5-10 minutes (read-only analysis)
+- **Value**: Prevents execution of flawed plans, saves 2-5 days
+- **Output**: Verification report with actionable recommendations
+
+### Skip Verification? (Not Recommended)
+
+If you want to skip verification and proceed directly:
+```bash
+/workflow:plan --session WFS-{session-id}
+/workflow:execute --session WFS-{session-id}
+```
+
+⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

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

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

.claude/commands/workflow/plan.md

@@ -15,13 +15,23 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 4 slash commands in sequence, parse their outputs, pass context between them, and ensure complete execution.
+**This command is a pure orchestrator**: Execute 4 slash commands in sequence, parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
 
-**Execution Flow**:
-1. Initialize TodoWrite → Execute Phase 1 → Parse output → Update TodoWrite
-2. Execute Phase 2 with Phase 1 data → Parse output → Update TodoWrite
-3. Execute Phase 3 with Phase 2 data → Parse output → Update TodoWrite
-4. Execute Phase 4 with Phase 3 validation → Update TodoWrite → Return summary
+**Execution Model - Auto-Continue Workflow**:
+
+This workflow runs **fully autonomously** once triggered. Each phase completes, reports its output to you, then **immediately and automatically** proceeds to the next phase without requiring any user intervention.
+
+1. **User triggers**: `/workflow:plan "task"`
+2. **Phase 1 executes** → Reports output to user → Auto-continues
+3. **Phase 2 executes** → Reports output to user → Auto-continues
+4. **Phase 3 executes** → Reports output to user → Auto-continues
+5. **Phase 4 executes** → Reports final summary
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status
+- After each phase completion, automatically executes next pending phase
+- **No user action required** - workflow runs end-to-end autonomously
+- Progress updates shown at each phase for visibility
 
 **Execution Modes**:
 - **Manual Mode** (default): Use `/workflow:tools:task-generate`
@@ -32,9 +42,8 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
 2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1
 3. **Parse Every Output**: Extract required data from each command's output for next phase
-4. **Sequential Execution**: Each phase depends on previous phase's output
-5. **Complete All Phases**: Do not return to user until Phase 4 completes
-6. **Track Progress**: Update TodoWrite after every phase completion
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
 
 ## 4-Phase Execution
 
@@ -64,6 +73,8 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **TodoWrite**: Mark phase 1 completed, phase 2 in_progress
 
+**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
+
 ---
 
 ### Phase 2: Context Gathering
@@ -83,6 +94,8 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **TodoWrite**: Mark phase 2 completed, phase 3 in_progress
 
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+
 ---
 
 ### Phase 3: Intelligent Analysis
@@ -99,9 +112,18 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
+**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 4
+
 ---
 
 ### Phase 4: Task Generation
+
+**Relationship with Brainstorm Phase**:
+- If brainstorm synthesis exists (synthesis-specification.md), Phase 3 analysis incorporates it as input
+- **synthesis-specification.md defines "WHAT"**: Requirements, design specs, high-level features
+- **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
+- Task generation translates high-level specifications into concrete, actionable work items
+
 **Command**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
 - Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
@@ -121,7 +143,12 @@ Planning complete for session: [sessionId]
 Tasks generated: [count]
 Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
-Next: /workflow:execute or /workflow:status
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
+2. /workflow:status  # Review task breakdown
+3. /workflow:execute  # Start implementation (after verification)
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
@@ -227,23 +254,23 @@ Return summary to user
 
 - **Parsing Failure**: If output parsing fails, retry command once, then report error
 - **Validation Failure**: If validation fails, report which file/data is missing
-- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed
+- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed to next phase
 
 ## Coordinator Checklist
 
 ✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
 ✅ Initialize TodoWrite before any command
 ✅ Execute Phase 1 immediately with structured description
-✅ Parse session ID from Phase 1 output
+✅ Parse session ID from Phase 1 output, store in memory
 ✅ Pass session ID and structured description to Phase 2 command
-✅ Parse context path from Phase 2 output
+✅ Parse context path from Phase 2 output, store in memory
 ✅ Pass session ID and context path to Phase 3 command
 ✅ Verify ANALYSIS_RESULTS.md after Phase 3
 ✅ Select correct Phase 4 command based on --agent flag
 ✅ Pass session ID to Phase 4 command
 ✅ Verify all Phase 4 outputs
 ✅ Update TodoWrite after each phase
-✅ Return summary only after Phase 4 completes
+✅ After each phase, automatically continue to next phase based on TodoList status
 
 ## Structure Template Reference
 

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

@@ -26,10 +26,11 @@ 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. **Sequential Execution**: Each phase depends on previous output
-5. **Complete All Phases**: Do not return until Phase 5 completes
+5. **Complete All Phases**: Do not return until Phase 7 completes (with concept verification)
 6. **TDD Context**: All descriptions include "TDD:" prefix
+7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
 
-## 5-Phase Execution
+## 7-Phase Execution (with Concept Verification)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -50,12 +51,51 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Extract contextPath
 
-### Phase 3: TDD Analysis
+### Phase 3: Test Coverage Analysis
+**Command**: `/workflow:tools:test-context-gather --session [sessionId]`
+
+**Purpose**: Analyze existing codebase for:
+- Existing test patterns and conventions
+- Current test coverage
+- Related components and integration points
+- Test framework detection
+
+**Parse**: Extract testContextPath (`.workflow/[sessionId]/.process/test-context-package.json`)
+
+**Benefits**:
+- Makes TDD aware of existing environment
+- Identifies reusable test patterns
+- Prevents duplicate test creation
+- Enables integration with existing tests
+
+### Phase 4: TDD Analysis
 **Command**: `/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]`
 
-**Parse**: Verify ANALYSIS_RESULTS.md
+**Note**: Generates ANALYSIS_RESULTS.md with TDD-specific structure:
+- Feature list with testable requirements
+- Test cases for Red phase
+- Implementation requirements for Green phase
+- Refactoring opportunities
+- Task dependencies and execution order
 
-### Phase 4: TDD Task Generation
+**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
+
+### Phase 5: Concept Verification (NEW QUALITY GATE)
+**Command**: `/workflow:concept-verify --session [sessionId]`
+
+**Purpose**: Verify conceptual clarity before TDD task generation
+- Clarify test requirements and acceptance criteria
+- Resolve ambiguities in expected behavior
+- Validate TDD approach is appropriate
+
+**Behavior**:
+- If no ambiguities found → Auto-proceed to Phase 6
+- If ambiguities exist → Interactive clarification (up to 5 questions)
+- After clarifications → Auto-proceed to Phase 6
+
+**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+
+### Phase 6: TDD Task Generation
 **Command**:
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
@@ -63,19 +103,21 @@ TEST_FOCUS: [Test scenarios]
 **Parse**: Extract feature count, chain count, task count
 
 **Validate**:
-- TDD_PLAN.md exists
-- IMPL_PLAN.md exists
+- IMPL_PLAN.md exists (unified plan with TDD Task Chains section)
 - TEST-*.json, IMPL-*.json, REFACTOR-*.json exist
 - TODO_LIST.md exists
+- IMPL tasks include test-fix-cycle configuration
+- IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 
-### Phase 5: TDD Structure Validation
-**Internal validation (no command)**
+### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
+**Internal validation first, then recommend external verification**
 
-**Validate**:
+**Internal Validation**:
 1. Each feature has TEST → IMPL → REFACTOR chain
 2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
 3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
 4. Agents: TEST uses @code-review-test-agent, IMPL/REFACTOR use @code-developer
+5. IMPL tasks contain test-fix-cycle in flow_control for iterative Green phase
 
 **Return Summary**:
 ```
@@ -89,23 +131,30 @@ Structure:
 - Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
 [...]
 
-Plans:
-- TDD Structure: .workflow/[sessionId]/TDD_PLAN.md
-- Implementation: .workflow/[sessionId]/IMPL_PLAN.md
+Plan:
+- Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
+  (includes TDD Task Chains section with workflow_type: "tdd")
 
-Next: /workflow:execute or /workflow:tdd-verify
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+2. /workflow:execute --session [sessionId]  # Start TDD execution
+3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task dependencies
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize
+// Initialize (7 phases now with concept verification)
 [
-  {content: "Execute session discovery", status: "in_progress", activeForm: "..."},
-  {content: "Execute context gathering", status: "pending", activeForm: "..."},
-  {content: "Execute TDD analysis", status: "pending", activeForm: "..."},
-  {content: "Execute TDD task generation", status: "pending", activeForm: "..."},
-  {content: "Validate TDD structure", status: "pending", activeForm: "..."}
+  {content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
+  {content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
+  {content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
+  {content: "Execute TDD analysis", status: "pending", activeForm": "Executing TDD analysis"},
+  {content: "Execute concept verification", status: "pending", activeForm": "Executing concept verification"},
+  {content: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
+  {content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
 ]
 
 // Update after each phase: mark current "completed", next "in_progress"
@@ -131,3 +180,96 @@ Convert user input to TDD-structured format:
 - `/workflow:execute` - Execute TDD tasks
 - `/workflow:tdd-verify` - Verify TDD compliance
 - `/workflow:status` - View progress
+## TDD Workflow Enhancements
+
+### Overview
+The TDD workflow has been significantly enhanced by integrating best practices from both traditional `plan --agent` and `test-gen` workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.
+
+### Key Improvements
+
+#### 1. Test Coverage Analysis (Phase 3)
+**Adopted from test-gen workflow**
+
+Before planning TDD tasks, the workflow now analyzes the existing codebase:
+- Detects existing test patterns and conventions
+- Identifies current test coverage
+- Discovers related components and integration points
+- Detects test framework automatically
+
+**Benefits**:
+- Context-aware TDD planning
+- Avoids duplicate test creation
+- Enables integration with existing tests
+- No longer assumes greenfield scenarios
+
+#### 2. Iterative Green Phase with Test-Fix Cycle
+**Adopted from test-gen workflow**
+
+IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:
+
+**Enhanced IMPL Task Flow**:
+```
+1. Write minimal implementation code
+2. Execute test suite
+3. IF tests pass → Complete task ✅
+4. IF tests fail → Enter fix cycle:
+   a. Gemini diagnoses with bug-fix template
+   b. Apply fix (manual or Codex)
+   c. Retest
+   d. Repeat (max 3 iterations)
+5. IF max iterations → Auto-revert changes 🔄
+```
+
+**Benefits**:
+- ✅ Faster feedback within Green phase
+- ✅ Autonomous recovery from implementation errors
+- ✅ Systematic debugging with Gemini
+- ✅ Safe rollback prevents broken state
+
+#### 3. Agent-Driven Planning
+**From plan --agent workflow**
+
+Supports action-planning-agent for more autonomous TDD planning with:
+- MCP tool integration (code-index, exa)
+- Memory-first principles
+- Brainstorming artifact integration
+- Task merging over decomposition
+
+### Workflow Comparison
+
+| Aspect | Previous | Current |
+|--------|----------|---------|
+| **Phases** | 5 | 6 (test coverage analysis) |
+| **Context** | Greenfield assumption | Existing codebase aware |
+| **Green Phase** | Single implementation | Iterative with fix cycle |
+| **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
+| **Test Analysis** | None | Deep coverage analysis |
+| **Feedback Loop** | Post-execution | During Green phase |
+
+### Migration Notes
+
+**Backward Compatibility**: ✅ Fully compatible
+- Existing TDD workflows continue to work
+- New features are additive, not breaking
+- Phase 3 can be skipped if test-context-gather not available
+
+**Session Structure**:
+```
+.workflow/WFS-xxx/
+├── IMPL_PLAN.md (unified plan with TDD Task Chains section)
+├── TODO_LIST.md
+├── .process/
+│   ├── context-package.json
+│   ├── test-context-package.json
+│   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
+│   └── green-fix-iteration-*.md (fix logs)
+└── .task/
+    ├── TEST-*.json (Red phase)
+    ├── IMPL-*.json (Green phase with test-fix-cycle)
+    └── REFACTOR-*.json (Refactor phase)
+```
+
+**Configuration Options** (in IMPL tasks):
+- `meta.max_iterations`: Fix attempts (default: 3)
+- `meta.use_codex`: Auto-fix mode (default: false)
+

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

@@ -1,11 +1,11 @@
 ---
 name: test-gen
 description: Create independent test-fix workflow session by analyzing completed implementation
-usage: /workflow:test-gen <source-session-id>
-argument-hint: "<source-session-id>"
+usage: /workflow:test-gen [--use-codex] <source-session-id>
+argument-hint: "[--use-codex] <source-session-id>"
 examples:
   - /workflow:test-gen WFS-user-auth
-  - /workflow:test-gen WFS-api-refactor
+  - /workflow:test-gen --use-codex WFS-api-refactor
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -20,6 +20,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - **Context-First**: Prioritizes gathering code changes and summaries from source session
 - **Format Reuse**: Creates standard `IMPL-*.json` task, using `meta.type: "test-fix"` for agent assignment
 - **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
 
 **Execution Flow**:
 1. Initialize TodoWrite → Create test session → Parse session ID
@@ -36,8 +37,9 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 5. **Complete All Phases**: Do not return to user until Phase 4 completes (execution triggered separately)
 6. **Track Progress**: Update TodoWrite after every phase completion
 7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
+8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
 
-## 4-Phase Execution
+## 5-Phase Execution
 
 ### Phase 1: Create Test Session
 **Command**: `SlashCommand(command="/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
@@ -65,107 +67,117 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ---
 
-### Phase 2: Gather Cross-Session Context
-**Command**: `SlashCommand(command="/workflow:tools:context-gather --session [testSessionId]")`
+### Phase 2: Gather Test Context
+**Command**: `SlashCommand(command="/workflow:tools:test-context-gather --session [testSessionId]")`
 
 **Input**: `testSessionId` from Phase 1 (e.g., `WFS-test-user-auth`)
 
-**Automatic Detection**:
-- context-gather reads `.workflow/[testSessionId]/workflow-session.json`
-- Detects `workflow_type: "test_session"`
-- Automatically uses `source_session_id` to gather source session context
-- No need for manual `--source-session` parameter
-
-**Cross-Session Context Collection** (Automatic):
-- Implementation summaries: `.workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md`
-- Code changes: `git log --since=[source_session_created_at]` for changed files
-- Original plan: `.workflow/[sourceSessionId]/IMPL_PLAN.md`
-- Test files: Discovered via MCP code-index tools
+**Expected Behavior**:
+- Load source session implementation context and summaries
+- Analyze test coverage using MCP tools (find existing tests)
+- Identify files requiring tests (coverage gaps)
+- Detect test framework and conventions
+- Generate `test-context-package.json`
 
 **Parse Output**:
-- Extract: context package path (store as `contextPath`)
-- Pattern: `.workflow/[testSessionId]/.process/context-package.json`
+- Extract: test context package path (store as `testContextPath`)
+- Pattern: `.workflow/[testSessionId]/.process/test-context-package.json`
 
 **Validation**:
-- Context package created in test session directory
-- Contains source session artifacts (summaries, changed files)
-- Includes test file inventory
+- Test context package created
+- Contains source session summaries
+- Includes coverage gap analysis
+- Test framework detected
+- Test conventions documented
 
 **TodoWrite**: Mark phase 2 completed, phase 3 in_progress
 
 ---
 
-### Phase 3: Implementation Analysis
-**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [testSessionId] --context [contextPath]")`
+### Phase 3: Test Generation Analysis
+**Command**: `SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessionId] --context [testContextPath]")`
 
 **Input**:
-- `testSessionId` from Phase 1 (e.g., `WFS-test-user-auth`)
-- `contextPath` from Phase 2 (e.g., `.workflow/WFS-test-user-auth/.process/context-package.json`)
-
-**Analysis Focus**:
-- Review implementation summaries from source session
-- Identify test files and coverage gaps
-- Assess test execution strategy (unit, integration, e2e)
-- Determine failure diagnosis approach
-- Recommend code quality improvements
+- `testSessionId` from Phase 1
+- `testContextPath` from Phase 2
 
 **Expected Behavior**:
-- Reads context-package.json with cross-session artifacts
-- Executes parallel analysis (Gemini for test strategy, optional Codex for validation)
-- Generates comprehensive test execution strategy
-- Identifies code modification targets for test fixes
-- Provides feasibility assessment for test validation
+- Use Gemini to analyze coverage gaps and implementation context
+- Study existing test patterns and conventions
+- Generate test requirements for each missing test file
+- Design test generation strategy
+- Generate `TEST_ANALYSIS_RESULTS.md`
 
 **Parse Output**:
-- Verify `.workflow/[testSessionId]/.process/ANALYSIS_RESULTS.md` created
-- Contains test strategy and execution plan
-- Lists code modification targets (format: `file:function:lines` or `file`)
-- Includes risk assessment and optimization recommendations
+- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
+- Contains test requirements and generation strategy
+- Lists test files to create with specifications
 
 **Validation**:
-- File `.workflow/[testSessionId]/.process/ANALYSIS_RESULTS.md` exists
-- Contains complete analysis sections:
-  - Current State Analysis (test coverage, existing tests)
-  - Proposed Solution Design (test execution strategy)
-  - Implementation Strategy (code targets, feasibility)
-  - Solution Optimization (performance, quality)
-  - Critical Success Factors (acceptance criteria)
+- TEST_ANALYSIS_RESULTS.md exists with complete sections:
+  - Coverage Assessment
+  - Test Framework & Conventions
+  - Test Requirements by File
+  - Test Generation Strategy
+  - Implementation Targets (test files to create)
+  - Success Criteria
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
 ---
 
-### Phase 4: Generate Test Task
-**Command**: `SlashCommand(command="/workflow:tools:task-generate --session [testSessionId]")`
+### Phase 4: Generate Test Tasks
+**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] --session [testSessionId]")`
 
-**Input**: `testSessionId` from Phase 1
+**Input**:
+- `testSessionId` from Phase 1
+- `--use-codex` flag (if present in original command)
 
 **Expected Behavior**:
-- Reads ANALYSIS_RESULTS.md from Phase 3
-- Extracts test strategy and code modification targets
-- Generates `IMPL-001.json` (reusing standard format) with:
-  - `meta.type: "test-fix"` (enables @test-fix-agent assignment)
-  - `meta.agent: "@test-fix-agent"`
-  - `context.requirements`: Test execution requirements from analysis
-  - `context.focus_paths`: Test files and source files from analysis
-  - `context.acceptance`: All tests pass criteria
-  - `flow_control.pre_analysis`: Load source session summaries
-  - `flow_control.implementation_approach`: Test execution strategy from ANALYSIS_RESULTS.md
-  - `flow_control.target_files`: Code modification targets from analysis
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
+- Extract test requirements and generation strategy
+- Generate **TWO task JSON files**:
+  - **IMPL-001.json**: Test Generation task (calls @code-developer)
+  - **IMPL-002.json**: Test Execution and Fix Cycle task (calls @test-fix-agent)
+- Generate IMPL_PLAN.md with test generation and execution strategy
+- Generate TODO_LIST.md with both tasks
 
 **Parse Output**:
-- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists (test generation)
+- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists (test execution & fix)
 - Verify `.workflow/[testSessionId]/IMPL_PLAN.md` created
 - Verify `.workflow/[testSessionId]/TODO_LIST.md` created
 
-**Validation**:
-- Task JSON has `id: "IMPL-001"` and `meta.type: "test-fix"`
-- IMPL_PLAN.md contains test validation strategy from ANALYSIS_RESULTS.md
-- TODO_LIST.md shows IMPL-001 task
-- flow_control includes code targets and test strategy
-- Task is ready for /workflow:execute
+**Validation - IMPL-001.json (Test Generation)**:
+- Task ID: `IMPL-001`
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
+- `flow_control.pre_analysis`: Load TEST_ANALYSIS_RESULTS.md and test context
+- `flow_control.implementation_approach`: Test generation steps
+- `flow_control.target_files`: Test files to create from analysis section 5
 
-**TodoWrite**: Mark phase 4 completed
+**Validation - IMPL-002.json (Test Execution & Fix)**:
+- Task ID: `IMPL-002`
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex: true|false` (based on --use-codex flag)
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Execute and fix tests
+- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
+  - **Cycle pattern**: test → gemini_diagnose → manual_fix (or codex if --use-codex) → retest
+  - **Tools configuration**: Gemini for analysis with bug-fix template, manual or Codex for fixes
+  - **Exit conditions**: Success (all pass) or failure (max iterations)
+- `flow_control.implementation_approach.modification_points`: 3-phase execution flow
+  - Phase 1: Initial test execution
+  - 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
+
+---
+
+### Phase 5: Return Summary to User
 
 **Return to User**:
 ```
@@ -173,315 +185,120 @@ Independent test-fix workflow created successfully!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
-Task Created: IMPL-001 (test-fix)
+
+Tasks Created:
+- IMPL-001: Test Generation (@code-developer)
+- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+
+Test Framework: [detected framework]
+Test Files to Generate: [count]
+Max Fix Iterations: 5
+Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
 Next Steps:
 1. Review test plan: .workflow/[testSessionId]/IMPL_PLAN.md
-2. Execute validation: /workflow:execute
+2. Execute workflow: /workflow:execute
 3. Monitor progress: /workflow:status
-
-The @test-fix-agent will:
-- Execute all tests
-- Diagnose any failures
-- Fix code until tests pass
 ```
 
+**TodoWrite**: Mark phase 5 completed
+
 ---
 
 ## TodoWrite Pattern
 
+Track progress through 5 phases:
+
 ```javascript
-// Initialize (before Phase 1)
 TodoWrite({todos: [
-  {"content": "Create independent test session", "status": "in_progress", "activeForm": "Creating test session"},
-  {"content": "Gather cross-session context", "status": "pending", "activeForm": "Gathering cross-session context"},
-  {"content": "Analyze implementation for test strategy", "status": "pending", "activeForm": "Analyzing implementation"},
-  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
-]})
-
-// After Phase 1
-TodoWrite({todos: [
-  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
-  {"content": "Gather cross-session context", "status": "in_progress", "activeForm": "Gathering cross-session context"},
-  {"content": "Analyze implementation for test strategy", "status": "pending", "activeForm": "Analyzing implementation"},
-  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
-]})
-
-// After Phase 2
-TodoWrite({todos: [
-  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
-  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
-  {"content": "Analyze implementation for test strategy", "status": "in_progress", "activeForm": "Analyzing implementation"},
-  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
-]})
-
-// After Phase 3
-TodoWrite({todos: [
-  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
-  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
-  {"content": "Analyze implementation for test strategy", "status": "completed", "activeForm": "Analyzing implementation"},
-  {"content": "Generate test validation task", "status": "in_progress", "activeForm": "Generating test validation task"}
-]})
-
-// After Phase 4
-TodoWrite({todos: [
-  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
-  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
-  {"content": "Analyze implementation for test strategy", "status": "completed", "activeForm": "Analyzing implementation"},
-  {"content": "Generate test validation task", "status": "completed", "activeForm": "Generating test validation task"}
+  {"content": "Create independent test session", "status": "in_progress|completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "pending|in_progress|completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending|in_progress|completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending|in_progress|completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending|in_progress|completed", "activeForm": "Returning workflow summary"}
 ]})
 ```
 
+Update status to `in_progress` when starting each phase, mark `completed` when done.
+
 ## Data Flow
 
 ```
-User: /workflow:test-gen WFS-user-auth
-    ↓
-Phase 1: session-start --new "Test validation for WFS-user-auth"
-    ↓ Creates: WFS-test-user-auth session
-    ↓ Writes: workflow-session.json with workflow_type="test_session", source_session_id="WFS-user-auth"
-    ↓ Output: testSessionId = "WFS-test-user-auth"
-    ↓
-Phase 2: context-gather --session WFS-test-user-auth
-    ↓ Auto-detects: test session type from workflow-session.json
-    ↓ Auto-reads: source_session_id = "WFS-user-auth"
-    ↓ Gathers: Cross-session context (summaries, code changes, tests)
-    ↓ Output: .workflow/WFS-test-user-auth/.process/context-package.json
-    ↓
-Phase 3: concept-enhanced --session WFS-test-user-auth --context context-package.json
-    ↓ Reads: context-package.json with cross-session artifacts
-    ↓ Executes: Parallel analysis (Gemini test strategy + optional Codex validation)
-    ↓ Analyzes: Test coverage, execution strategy, code targets
-    ↓ Output: .workflow/WFS-test-user-auth/.process/ANALYSIS_RESULTS.md
-    ↓
-Phase 4: task-generate --session WFS-test-user-auth
-    ↓ Reads: ANALYSIS_RESULTS.md with test strategy and code targets
-    ↓ Generates: IMPL-001.json with meta.type="test-fix"
-    ↓ Output: Task, plan, and todo files in test session
-    ↓
-Return: Summary with next steps (user triggers /workflow:execute separately)
+/workflow:test-gen WFS-user-auth
+  ↓
+Phase 1: session-start → WFS-test-user-auth
+  ↓
+Phase 2: test-context-gather → test-context-package.json
+  ↓
+Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md
+  ↓
+Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json
+  ↓
+Phase 5: Return summary
+  ↓
+/workflow:execute → IMPL-001 (@code-developer) → IMPL-002 (@test-fix-agent)
 ```
 
-## Session Metadata Design
+## Session Metadata
 
-**Test Session (`WFS-test-user-auth/workflow-session.json`)**:
-```json
-{
-  "session_id": "WFS-test-user-auth",
-  "project": "Test validation for user authentication implementation",
-  "status": "planning",
-  "created_at": "2025-10-03T12:00:00Z",
-  "workflow_type": "test_session",
-  "source_session_id": "WFS-user-auth"
-}
-```
+Test session includes `workflow_type: "test_session"` and `source_session_id` for automatic context gathering.
 
-## Automatic Cross-Session Context Collection
+## Task Output
 
-When `context-gather` detects `workflow_type: "test_session"`:
+Generates two tasks:
+- **IMPL-001** (@code-developer): Test generation from TEST_ANALYSIS_RESULTS.md
+- **IMPL-002** (@test-fix-agent): Test execution with iterative fix cycle (max 5 iterations)
 
-**Collected from Source Session** (`.workflow/WFS-user-auth/`):
-- Implementation summaries: `.summaries/IMPL-*-summary.md`
-- Code changes: `git log --since=[source_created_at] --name-only`
-- Original plan: `IMPL_PLAN.md`
-- Task definitions: `.task/IMPL-*.json`
-
-**Collected from Current Project**:
-- Test files: `mcp__code-index__find_files(pattern="*.test.*")`
-- Test configuration: `package.json`, `jest.config.js`, etc.
-- Source files: Based on changed files from git log
-
-## Task Generation Output
-
-task-generate creates `IMPL-001.json` (reusing standard format) with:
-
-```json
-{
-  "id": "IMPL-001",
-  "title": "Execute and validate tests for [sourceSessionId]",
-  "status": "pending",
-  "meta": {
-    "type": "test-fix",
-    "agent": "@test-fix-agent"
-  },
-  "context": {
-    "requirements": [
-      "Execute complete test suite for all implemented modules",
-      "Diagnose and fix any test failures",
-      "Ensure all tests pass before completion"
-    ],
-    "focus_paths": ["src/**/*.test.ts", "src/**/implementation.ts"],
-    "acceptance": [
-      "All tests pass successfully",
-      "No test failures or errors",
-      "Code is approved and ready for deployment"
-    ],
-    "depends_on": [],
-    "artifacts": []
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_source_session_summaries",
-        "action": "Load implementation summaries from source session",
-        "commands": [
-          "bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
-          "Read(.workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md)"
-        ],
-        "output_to": "implementation_context",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "analyze_test_files",
-        "action": "Identify test files and coverage",
-        "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
-          "mcp__code-index__search_code_advanced(pattern=\"test|describe|it\", file_pattern=\"*.test.*\")"
-        ],
-        "output_to": "test_inventory",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": {
-      "task_description": "Execute tests and fix failures until all pass",
-      "modification_points": [
-        "Run test suite using detected framework",
-        "Parse test output to identify failures",
-        "Diagnose root cause of failures",
-        "Modify source code to fix issues",
-        "Re-run tests to verify fixes"
-      ],
-      "logic_flow": [
-        "Load implementation context",
-        "Identify test framework and configuration",
-        "Execute complete test suite",
-        "If failures: analyze error messages",
-        "Fix source code based on diagnosis",
-        "Re-run tests",
-        "Repeat until all tests pass"
-      ]
-    },
-    "target_files": ["src/**/*.test.ts", "src/**/implementation.ts"]
-  }
-}
-```
+See `/workflow:tools:test-task-generate` for complete task JSON schemas.
 
 ## Error Handling
 
-### Phase 1 Failures
-- **Source session not found**: Return error "Source session [sourceSessionId] not found in .workflow/"
-- **Invalid source session**: Return error "Source session [sourceSessionId] has no completed IMPL tasks"
-- **Session creation failed**: Return error "Could not create test session. Check /workflow:session:start"
+| Phase | Error | Action |
+|-------|-------|--------|
+| 1 | Source session not found | Return error with source session ID |
+| 1 | No completed IMPL tasks | Return error, source incomplete |
+| 2 | Context gathering failed | Return error, check source artifacts |
+| 3 | Analysis failed | Return error, check context package |
+| 4 | Task generation failed | Retry once, then error with details |
 
-### Phase 2 Failures
-- **Context gathering failed**: Return error "Could not gather cross-session context. Check source session artifacts"
-- **No source artifacts**: Return error "Source session has no implementation summaries or git history"
+## Output Files
 
-### Phase 3 Failures
-- **Analysis failed**: Return error "Implementation analysis failed. Check context package and ANALYSIS_RESULTS.md"
-- **No test strategy**: Return error "Could not determine test execution strategy from analysis"
-- **Missing code targets**: Warning only, proceed with general test task
-
-### Phase 4 Failures
-- **Task generation failed**: Retry once, then return error with details
-- **Invalid task structure**: Return error with JSON validation details
-
-## Workflow Integration
-
-### Complete Flow Example
-```
-1. Implementation Phase (prior to test-gen)
-   /workflow:plan "Build auth system"
-   → Creates WFS-auth session
-   → @code-developer implements + writes tests
-   → Creates IMPL-001-summary.md in WFS-auth
-
-2. Test Generation Phase (test-gen)
-   /workflow:test-gen WFS-auth
-   Phase 1: session-start → Creates WFS-test-auth session
-   Phase 2: context-gather → Gathers from WFS-auth, creates context-package.json
-   Phase 3: concept-enhanced → Analyzes implementation, creates ANALYSIS_RESULTS.md
-   Phase 4: task-generate → Creates IMPL-001.json with meta.type="test-fix"
-   Returns: Summary with next steps
-
-3. Test Execution Phase (user-triggered)
-   /workflow:execute
-   → Detects active session: WFS-test-auth
-   → @test-fix-agent picks up IMPL-001 (test-fix type)
-   → Runs test suite
-   → Diagnoses failures (if any)
-   → Fixes source code
-   → Re-runs tests
-   → All pass → Code approved ✅
-```
-
-### Output Files Created
-
-**In Test Session** (`.workflow/WFS-test-auth/`):
-- `workflow-session.json` - Contains workflow_type and source_session_id
-- `.process/context-package.json` - Cross-session context from WFS-auth
-- `.process/ANALYSIS_RESULTS.md` - Test strategy and code targets from concept-enhanced
-- `.task/IMPL-001.json` - Test-fix task definition
-- `IMPL_PLAN.md` - Test validation plan (from ANALYSIS_RESULTS.md)
+Created in `.workflow/WFS-test-[session]/`:
+- `workflow-session.json` - Session metadata
+- `.process/test-context-package.json` - Coverage analysis
+- `.process/TEST_ANALYSIS_RESULTS.md` - Test requirements
+- `.task/IMPL-001.json` - Test generation task
+- `.task/IMPL-002.json` - Test execution & fix task
+- `IMPL_PLAN.md` - Test plan
 - `TODO_LIST.md` - Task checklist
-- `.summaries/IMPL-001-summary.md` - Created by @test-fix-agent after completion
+
+## Agent Execution
+
+**IMPL-001** (@code-developer):
+- Generates test files based on TEST_ANALYSIS_RESULTS.md
+- Follows existing test patterns and conventions
+
+**IMPL-002** (@test-fix-agent):
+1. Run test suite
+2. Iterative fix cycle (max 5):
+   - Gemini diagnosis with bug-fix template → surgical fix suggestions
+   - Manual fix application (default) OR Codex applies fixes if --use-codex flag (resume mechanism)
+   - Retest and check regressions
+3. Final validation and certification
+
+See `/workflow:tools:test-task-generate` for detailed specifications.
 
 ## Best Practices
 
-1. **Run after implementation complete**: Ensure source session has completed IMPL tasks and summaries
-2. **Check git commits**: Implementation changes should be committed for accurate git log analysis
-3. **Verify test files exist**: Source implementation should include test files
-4. **Independent sessions**: Test session is separate from implementation session for clean separation
-5. **Monitor execution**: Use `/workflow:status` to track test-fix progress after /workflow:execute
-
-## Coordinator Checklist
-
-✅ Initialize TodoWrite before any command (4 phases)
-✅ Phase 1: Create test session with source session ID
-✅ Parse new test session ID from Phase 1 output
-✅ Phase 2: Run context-gather (auto-detects test session, no extra params)
-✅ Verify context-package.json contains cross-session artifacts
-✅ Phase 3: Run concept-enhanced with session and context path
-✅ Verify ANALYSIS_RESULTS.md contains test strategy and code targets
-✅ Phase 4: Run task-generate to create IMPL-001.json
-✅ Verify task has meta.type="test-fix" and meta.agent="@test-fix-agent"
-✅ Verify flow_control includes analysis insights and code targets
-✅ Update TodoWrite after each phase
-✅ Return summary after Phase 4 (execution is separate user action)
-
-## Required Tool Modifications
-
-### `/workflow:session:start`
-- Support `--new` flag for test session creation
-- Auto-detect test session pattern from task description
-- Write `workflow_type: "test_session"` and `source_session_id` to metadata
-
-### `/workflow:tools:context-gather`
-- Read session metadata to detect `workflow_type: "test_session"`
-- Auto-extract `source_session_id` from metadata
-- Gather cross-session context from source session artifacts
-- Include git log analysis from source session creation time
-
-### `/workflow:tools:concept-enhanced`
-- No changes required (already supports cross-session context analysis)
-- Will automatically analyze test strategy based on context-package.json
-- Generates ANALYSIS_RESULTS.md with code targets and test execution plan
-
-### `/workflow:tools:task-generate`
-- Recognize test session context and generate appropriate task
-- Create `IMPL-001.json` with `meta.type: "test-fix"`
-- Extract test strategy from ANALYSIS_RESULTS.md
-- Include code targets and cross-session references in flow_control
-
-### `/workflow:execute`
-- No changes required (already dispatches by meta.agent)
+1. Run after implementation complete (ensure source session has summaries)
+2. Commit implementation changes before test-gen
+3. Monitor execution with `/workflow:status`
+4. Review iteration logs in `.process/fix-iteration-*`
 
 ## Related Commands
-- `/workflow:plan` - Create implementation workflow (run before test-gen)
-- `/workflow:session:start` - Phase 1 tool for test session creation
-- `/workflow:tools:context-gather` - Phase 2 tool for cross-session context collection
-- `/workflow:tools:concept-enhanced` - Phase 3 tool for implementation analysis and test strategy
-- `/workflow:tools:task-generate` - Phase 4 tool for test task creation
-- `/workflow:execute` - Execute test-fix workflow (user-triggered after test-gen)
-- `/workflow:status` - Check workflow progress
-- `@test-fix-agent` - Agent that executes and fixes tests
+
+- `/workflow:tools:test-context-gather` - Phase 2 (coverage analysis)
+- `/workflow:tools:test-concept-enhanced` - Phase 3 (Gemini test analysis)
+- `/workflow:tools:test-task-generate` - Phase 4 (task generation)
+- `/workflow:execute` - Execute workflow
+- `/workflow:status` - Check progress

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

@@ -130,6 +130,15 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
      - Tech stack from tech_stack section
      - Project structure from statistics section
 
+     **ANALYSIS PRIORITY - Use ALL source documents from context-package assets[]**:
+     1. PRIMARY SOURCES (Highest Priority): Individual role analysis.md files (system-architect, ui-designer, product-manager, etc.)
+        - These contain complete technical details, design rationale, ADRs, and decision context
+        - Extract: Technical specs, API schemas, design tokens, caching configs, performance metrics
+     2. SYNTHESIS REFERENCE (Medium Priority): synthesis-specification.md
+        - Use for integrated requirements and cross-role alignment
+        - Validate decisions and identify integration points
+     3. TOPIC FRAMEWORK (Low Priority): topic-framework.md for discussion context
+
      EXPECTED:
      1. CURRENT STATE ANALYSIS: Existing patterns, code structure, integration points, technical debt
      2. SOLUTION DESIGN: Core architecture principles, system design, key design decisions with rationale

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

@@ -1,256 +1,590 @@
 ---
 name: docs
-description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
-usage: /workflow:docs <type> [scope]
-argument-hint: "architecture"|"api"|"all"
+description: Documentation planning and orchestration - creates structured documentation tasks for execution
+usage: /workflow:docs <type> [options]
+argument-hint: "architecture"|"api"|"all" [--tool <gemini|qwen|codex>] [--scope <path>]
 examples:
-  - /workflow:docs all
-  - /workflow:docs architecture src/modules
-  - /workflow:docs api --scope api/
+  - /workflow:docs all                          # Complete documentation (gemini default)
+  - /workflow:docs all --tool qwen              # Use Qwen for architecture focus
+  - /workflow:docs architecture --scope src/modules
+  - /workflow:docs api --tool gemini --scope api/
 ---
 
 # Workflow Documentation Command
 
+## Purpose
+
+**`/workflow:docs` is a lightweight planner/orchestrator** - it analyzes project structure using metadata tools, decomposes documentation work into tasks, and generates execution plans. It does **NOT** generate any documentation content itself.
+
+**Key Principle**: Lightweight Planning + Targeted Execution
+- **docs.md** → Collect metadata (paths, structure), generate task JSONs with path references
+- **doc-generator.md** → Execute targeted analysis on focus_paths, generate content
+
+**Optimization Philosophy**:
+- **Planning phase**: Minimal context - only metadata (module paths, file lists via `get_modules_by_depth.sh` and Code Index MCP)
+- **Task JSON**: Store path references, not content
+- **Execution phase**: Targeted deep analysis within focus_paths scope
+
 ## Usage
+
 ```bash
-/workflow:docs <type> [scope]
+/workflow:docs <type> [--tool <gemini|qwen|codex>] [--scope <path>]
 ```
 
-## Input Detection
-- **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
-- **Scope**: Optional module/directory filtering → Focuses documentation generation
-- **Default**: `all` → Complete documentation suite
+### Parameters
 
-## Core Workflow
+- **type**: `architecture` | `api` | `all` (required)
+  - `architecture`: System design, module interactions, patterns
+  - `api`: Endpoint documentation, API specifications
+  - `all`: Complete documentation suite
 
-### Planning & Task Creation Process
-The command performs structured planning and task creation:
+- **--tool**: `gemini` | `qwen` | `codex` (optional, default: gemini)
+  - `gemini`: Comprehensive documentation, pattern recognition
+  - `qwen`: Architecture analysis, system design focus
+  - `codex`: Implementation validation, code quality
 
-**0. Pre-Planning Architecture Analysis** ⚠️ MANDATORY FIRST STEP
-- **System Structure Analysis**: MUST run `bash(~/.claude/scripts/get_modules_by_depth.sh)` for dynamic task decomposition
-- **Module Boundary Identification**: Understand module organization and dependencies
-- **Architecture Pattern Recognition**: Identify architectural styles and design patterns
-- **Foundation for documentation**: Use structure analysis to guide task decomposition
+- **--scope**: Directory path filter (optional)
 
-**1. Documentation Planning**
-- **Type Analysis**: Determine documentation scope (architecture/api/all)
-- **Module Discovery**: Use architecture analysis results to identify components
-- **Dynamic Task Decomposition**: Analyze project structure to determine optimal task count and module grouping
-- **Session Management**: Create or use existing documentation session
+## Planning Workflow
 
-**2. Task Generation**
-- **Create session**: `.workflow/WFS-docs-[timestamp]/`
-- **Create active marker**: `.workflow/.active-WFS-docs-[timestamp]` (must match session folder name)
-- **Generate IMPL_PLAN.md**: Documentation requirements and task breakdown
-- **Create task.json files**: Individual documentation tasks with flow_control
-- **Setup TODO_LIST.md**: Progress tracking for documentation generation
+### Complete Execution Flow
 
-### Session Management ⚠️ CRITICAL
-- **Check for active sessions**: Look for `.workflow/.active-WFS-docs-*` markers
-- **Marker naming**: Active marker must exactly match session folder name
-- **Session creation**: `WFS-docs-[timestamp]` folder with matching `.active-WFS-docs-[timestamp]` marker
-- **Task execution**: Use `/workflow:execute` to run individual documentation tasks within active session
-- **Session isolation**: Each documentation session maintains independent context and state
+```
+/workflow:docs [type] [--tool] [--scope]
+    ↓
+Phase 1: Init Session → Create session dir & active marker
+    ↓
+Phase 2: Module Analysis → Run get_modules_by_depth.sh
+    ↓
+Phase 3: Quick Assess → Check existing docs
+    ↓
+Phase 4: Decompose → Create task list & TodoWrite
+    ↓
+Phase 5: Generate Tasks → Build IMPL-*.json & plans
+    ↓
+✅ Planning Complete → Show TodoWrite status
+```
 
-## Output Structure
+### Phase Details
+
+#### Phase 1: Session Initialization
+```bash
+# Parse arguments and create session structure
+doc_type="all"  # architecture|api|all
+tool="gemini"   # gemini|qwen|codex (default: gemini)
+scope=""        # optional path filter
+
+timestamp=$(date +%Y%m%d-%H%M%S)
+session_dir=".workflow/WFS-docs-${timestamp}"
+mkdir -p "${session_dir}"/{.task,.process,.summaries}
+touch ".workflow/.active-WFS-docs-${timestamp}"
+```
+
+#### Phase 2: Lightweight Metadata Collection (MANDATORY)
+```bash
+# Step 1: Run get_modules_by_depth.sh for module hierarchy (metadata only)
+module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
+# Format: depth:N|path:<PATH>|files:N|size:N|has_claude:yes/no
+
+# Step 2: Use Code Index MCP for file discovery (optional, for better precision)
+# Example: mcp__code-index__find_files(pattern="src/**/")
+# This finds directories without loading content
+
+# IMPORTANT: Do NOT read file contents in planning phase
+# Only collect: paths, file counts, module structure
+```
+
+#### Phase 3: Quick Documentation Assessment
+```bash
+# Lightweight check - no heavy analysis
+existing_docs=$(find . -maxdepth 2 -name "*.md" -not -path "./.workflow/*" | wc -l)
+
+if [[ $existing_docs -gt 5 ]]; then
+    find . -maxdepth 3 -name "*.md" > "${session_dir}/.process/existing-docs.txt"
+fi
+
+# Record strategy
+cat > "${session_dir}/.process/strategy.md" <<EOF
+**Type**: ${doc_type}
+**Tool**: ${tool}
+**Scope**: ${scope:-"Full project"}
+EOF
+```
+
+#### Phase 4: Task Decomposition & TodoWrite Setup
+
+**Decomposition Strategy**:
+1. **Always create**: System Overview task (IMPL-001)
+2. **If architecture/all**: Architecture Documentation task
+3. **If api/all**: Unified API Documentation task
+4. **For each module**: Module Documentation task (grouped)
+
+**Grouping Rules**:
+- Max 3 modules per task
+- Max 30 files per task
+- Group by dependency depth and functional similarity
+
+**TodoWrite Setup**:
+```
+✅ Session initialization (completed)
+⏳ IMPL-001: Project Overview (pending)
+⏳ IMPL-002: Module 'auth' (pending)
+⏳ IMPL-003: Module 'api' (pending)
+⏳ IMPL-004: Architecture Documentation (pending)
+⏳ IMPL-005: API Documentation (pending)
+```
+
+#### Phase 5: Task JSON Generation
+
+Each task follows the 5-field schema with detailed flow_control.
+
+**Command Generation Logic**:
+```bash
+# Build tool-specific command at planning time
+if [[ "$tool" == "codex" ]]; then
+    cmd="codex -C ${dir} --full-auto exec \"...\""
+else
+    cmd="bash(cd ${dir} && ~/.claude/scripts/${tool}-wrapper -p \"...\")"
+fi
+```
+
+## Task Templates
+
+### 1. System Overview (IMPL-001)
+**Purpose**: Project-level documentation
+**Output**: `.workflow/docs/README.md`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-001",
+  "title": "Generate Project Overview Documentation",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "template": "project-overview"
+  },
+  "context": {
+    "requirements": [
+      "Document project purpose, architecture, and getting started guide",
+      "Create navigation structure for all documentation",
+      "Use Project-Level Documentation Template"
+    ],
+    "focus_paths": ["."],
+    "acceptance": [
+      "Complete .workflow/docs/README.md following template",
+      "All template sections populated with accurate information",
+      "Navigation links to module and API documentation"
+    ],
+    "scope": "Project root and overall structure"
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "discover_project_structure",
+        "action": "Get project module hierarchy metadata",
+        "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
+        "output_to": "system_structure",
+        "on_error": "fail",
+        "note": "Lightweight metadata only - no file content"
+      },
+      {
+        "step": "analyze_tech_stack",
+        "action": "Analyze technology stack from key config files",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack from key config files\\nMODE: analysis\\nCONTEXT: @{package.json,pom.xml,build.gradle,requirements.txt,go.mod,Cargo.toml,CLAUDE.md}\\nEXPECTED: Technology list and architecture style\\nRULES: Be concise, focus on stack only\")",
+        "output_to": "tech_stack_analysis",
+        "on_error": "skip_optional",
+        "note": "Only analyze config files - small, controlled context"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Use system_structure and tech_stack_analysis to populate Project Overview Template",
+      "logic_flow": [
+        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt",
+        "Fill sections using [system_structure] and [tech_stack_analysis]",
+        "Generate navigation links based on module paths",
+        "Format output as Markdown"
+      ]
+    },
+    "target_files": [".workflow/docs/README.md"]
+  }
+}
+```
+
+### 2. Module Documentation (IMPL-002+)
+**Purpose**: Module-level documentation
+**Output**: `.workflow/docs/modules/[name]/README.md`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-002",
+  "title": "Document Module: 'auth'",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "template": "module-documentation"
+  },
+  "context": {
+    "requirements": [
+      "Document module purpose, internal architecture, public API",
+      "Include dependencies and usage examples",
+      "Use Module-Level Documentation Template"
+    ],
+    "focus_paths": ["src/auth"],
+    "acceptance": [
+      "Complete .workflow/docs/modules/auth/README.md",
+      "All exported functions/classes documented",
+      "Working code examples included"
+    ],
+    "scope": "auth module only"
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "analyze_module_content",
+        "action": "Perform deep analysis of the specific module's content",
+        "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document 'auth' module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: Structured analysis of module content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
+        "output_to": "module_analysis",
+        "on_error": "fail",
+        "note": "Analysis strictly limited to focus_paths ('src/auth') - controlled context"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Use the detailed [module_analysis] to populate the Module-Level Documentation Template",
+      "logic_flow": [
+        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt",
+        "Fill sections using [module_analysis]",
+        "Generate code examples from actual usage",
+        "Format output as Markdown"
+      ]
+    },
+    "target_files": [".workflow/docs/modules/auth/README.md"]
+  }
+}
+```
+
+### 3. Architecture Documentation (if requested)
+**Purpose**: System design and patterns
+**Output**: `.workflow/docs/architecture/`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-N-1",
+  "title": "Generate Architecture Documentation",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "qwen",
+    "template": "architecture"
+  },
+  "context": {
+    "requirements": [
+      "Document system design patterns and architectural decisions",
+      "Create module interaction diagrams",
+      "Explain data flow and component relationships"
+    ],
+    "focus_paths": ["."],
+    "acceptance": [
+      "Complete architecture documentation in .workflow/docs/architecture/",
+      "Diagrams explaining system design",
+      "Clear explanation of architectural patterns"
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_all_module_docs",
+        "action": "Aggregate all module documentation",
+        "command": "bash(find .workflow/docs/modules -name 'README.md' -exec cat {} \\;)",
+        "output_to": "module_docs",
+        "on_error": "fail"
+      },
+      {
+        "step": "analyze_architecture",
+        "action": "Synthesize system architecture from modules",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize system architecture\\nTASK: Create architecture documentation from module docs\\nMODE: analysis\\nCONTEXT: [module_docs]\\nEXPECTED: Architecture documentation with patterns\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt) | Focus on design patterns, data flow, component interactions\")",
+        "output_to": "architecture_analysis",
+        "on_error": "fail",
+        "note": "Command varies: gemini-wrapper (default) | qwen-wrapper | codex exec"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Create architecture documentation from synthesis",
+      "logic_flow": [
+        "Parse architecture_analysis for patterns and design decisions",
+        "Create text-based diagrams (mermaid/ASCII) for module interactions",
+        "Document data flow between components",
+        "Explain architectural decisions and trade-offs",
+        "Format as structured documentation"
+      ]
+    },
+    "target_files": [
+      ".workflow/docs/architecture/system-design.md",
+      ".workflow/docs/architecture/module-map.md",
+      ".workflow/docs/architecture/data-flow.md"
+    ]
+  }
+}
+```
+
+### 4. API Documentation (if requested)
+**Purpose**: API reference and specifications
+**Output**: `.workflow/docs/api/README.md`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-N",
+  "title": "Generate Unified API Documentation",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "template": "api-reference"
+  },
+  "context": {
+    "requirements": [
+      "Document all API endpoints with request/response formats",
+      "Include authentication and error handling",
+      "Generate OpenAPI specification if applicable",
+      "Use API-Level Documentation Template"
+    ],
+    "focus_paths": ["src/api", "src/routes", "src/controllers"],
+    "acceptance": [
+      "Complete .workflow/docs/api/README.md following template",
+      "All endpoints documented with examples",
+      "OpenAPI spec generated if REST API detected"
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "discover_api_endpoints",
+        "action": "Find all API routes and endpoints using MCP",
+        "command": "mcp__code-index__search_code_advanced(pattern='router\\.|app\\.|@(Get|Post|Put|Delete|Patch)', file_pattern='*.{ts,js}', output_mode='content', head_limit=100)",
+        "output_to": "endpoint_discovery",
+        "on_error": "skip_optional",
+        "note": "Use MCP instead of rg for better structure"
+      },
+      {
+        "step": "analyze_api_structure",
+        "action": "Analyze API structure and patterns",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")",
+        "output_to": "api_analysis",
+        "on_error": "fail",
+        "note": "Analysis limited to API-related paths - controlled context"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Use api_analysis to populate API-Level Documentation Template",
+      "logic_flow": [
+        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt",
+        "Parse api_analysis for: endpoints, auth, request/response",
+        "Fill template sections with extracted information",
+        "Generate OpenAPI spec if REST API detected",
+        "Format output as Markdown"
+      ]
+    },
+    "target_files": [
+      ".workflow/docs/api/README.md",
+      ".workflow/docs/api/openapi.yaml"
+    ]
+  }
+}
+```
+
+## Planning Outputs
+
+### File Structure
+```
+.workflow/
+├── .active-WFS-docs-20240120-143022
+└── WFS-docs-20240120-143022/
+    ├── IMPL_PLAN.md              # Implementation plan
+    ├── TODO_LIST.md              # Progress tracker
+    ├── .process/
+    │   ├── strategy.md           # Doc strategy
+    │   └── existing-docs.txt     # Existing docs list
+    └── .task/
+        ├── IMPL-001.json         # System overview
+        ├── IMPL-002.json         # Module: auth
+        ├── IMPL-003.json         # Module: api
+        ├── IMPL-004.json         # Architecture
+        └── IMPL-005.json         # API docs
+```
+
+### IMPL_PLAN.md
+```markdown
+# Documentation Implementation Plan
+
+**Session**: WFS-docs-[timestamp]
+**Type**: [architecture|api|all]
+**Tool**: [gemini|qwen|codex]
+
+## Task Breakdown
+
+### IMPL-001: System Overview
+- **Output**: .workflow/docs/README.md
+- **Template**: project-overview.txt
+
+### IMPL-002+: Module Documentation
+- **Modules**: [list]
+- **Template**: module-documentation.txt
+
+### IMPL-N: Architecture/API (if requested)
+- **Template**: architecture.txt / api-reference.txt
+
+## Execution Order
+1. IMPL-001 (Foundation)
+2. IMPL-002 to IMPL-[M] (Modules - can parallelize)
+3. IMPL-[M+1] (Architecture - needs modules)
+4. IMPL-[N] (API - can run after IMPL-001)
+```
+
+### TODO_LIST.md
+```markdown
+# Documentation Progress Tracker
+
+- [ ] **IMPL-001**: Generate Project Overview
+- [ ] **IMPL-002**: Document Module: 'auth'
+- [ ] **IMPL-003**: Document Module: 'api'
+- [ ] **IMPL-004**: Generate Architecture Documentation
+- [ ] **IMPL-005**: Generate Unified API Documentation
+
+## Execution
+```bash
+/workflow:execute IMPL-001
+/workflow:execute IMPL-002
+# ...
+```
+```
+
+## Execution Phase
+
+### Via /workflow:execute
+
+```
+For Each Task (IMPL-001, IMPL-002, ...):
+
+/workflow:execute IMPL-NNN
+    ↓
+TodoWrite: pending → in_progress
+    ↓
+Execute flow_control (pre_analysis steps)
+    ↓
+Generate Documentation (apply template)
+    ↓
+TodoWrite: in_progress → completed
+    ↓
+✅ Task Complete
+```
+
+### TodoWrite Status Tracking
+
+**Planning Phase**:
+```
+✅ Session initialization (completed)
+⏳ IMPL-001: Project Overview (pending)
+⏳ IMPL-002: Module 'auth' (pending)
+```
+
+**Execution Phase**:
+```
+Executing IMPL-001:
+✅ Session initialization
+🔄 IMPL-001: Project Overview (in_progress)
+⏳ IMPL-002: Module 'auth'
+
+After IMPL-001:
+✅ Session initialization
+✅ IMPL-001: Project Overview (completed)
+🔄 IMPL-002: Module 'auth' (in_progress)
+```
+
+## Documentation Output
+
+### Final Structure
 ```
 .workflow/docs/
-├── README.md              # System navigation
-├── modules/               # Level 1: Module documentation
-│   ├── [module-1]/
-│   │   ├── overview.md
-│   │   ├── api.md
-│   │   ├── dependencies.md
-│   │   └── examples.md
-│   └── [module-n]/...
-├── architecture/          # Level 2: System architecture
+├── README.md                     # IMPL-001: Project overview
+├── modules/
+│   ├── auth/README.md           # IMPL-002: Auth module
+│   └── api/README.md            # IMPL-003: API module
+├── architecture/                # IMPL-004: Architecture
 │   ├── system-design.md
 │   ├── module-map.md
-│   ├── data-flow.md
-│   └── tech-stack.md
-└── api/                   # Level 2: Unified API docs
-    ├── unified-api.md
+│   └── data-flow.md
+└── api/                         # IMPL-005: API docs
+    ├── README.md
     └── openapi.yaml
 ```
 
-## Task Decomposition Standards
+## Next Steps
 
-### Dynamic Task Planning Rules
-**Module Grouping**: Max 3 modules per task, max 30 files per task
-**Task Count**: Calculate based on `total_modules ÷ 3 (rounded up) + base_tasks`
-**File Limits**: Split tasks when file count exceeds 30 in any module group
-**Base Tasks**: System overview (1) + Architecture (1) + API consolidation (1)
-**Module Tasks**: Group related modules by dependency depth and functional similarity
-
-### Documentation Task Types
-**IMPL-001**: System Overview Documentation
-- Project structure analysis
-- Technology stack documentation
-- Main navigation creation
-
-**IMPL-002**: Module Documentation (per module)
-- Individual module analysis
-- API surface documentation
-- Dependencies and relationships
-- Usage examples
-
-**IMPL-003**: Architecture Documentation
-- System design patterns
-- Module interaction mapping
-- Data flow documentation
-- Design principles
-
-**IMPL-004**: API Documentation
-- Endpoint discovery and analysis
-- OpenAPI specification generation
-- Authentication documentation
-- Integration examples
-
-### Task JSON Schema (5-Field Architecture)
-Each documentation task uses the workflow-architecture.md 5-field schema:
-- **id**: IMPL-N format
-- **title**: Documentation task name
-- **status**: pending|active|completed|blocked
-- **meta**: { type: "documentation", agent: "@doc-generator" }
-- **context**: { requirements, focus_paths, acceptance, scope }
-- **flow_control**: { pre_analysis[], implementation_approach, target_files[] }
-
-## Document Generation
-
-### Workflow Process
-**Input Analysis** → **Session Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md** → **Execute Tasks**
-
-**Always Created**:
-- **IMPL_PLAN.md**: Documentation requirements and task breakdown
-- **Session state**: Task references and documentation paths
-
-**Auto-Created (based on scope)**:
-- **TODO_LIST.md**: Progress tracking for documentation tasks
-- **.task/IMPL-*.json**: Individual documentation tasks with flow_control
-- **.process/ANALYSIS_RESULTS.md**: Documentation analysis artifacts
-
-**Document Structure**:
-```
-.workflow/
-├── .active-WFS-docs-20231201-143022  # Active session marker (matches folder name)
-└── WFS-docs-20231201-143022/         # Documentation session folder
-    ├── IMPL_PLAN.md                  # Main documentation plan
-    ├── TODO_LIST.md                  # Progress tracking
-    ├── .process/
-    │   └── ANALYSIS_RESULTS.md       # Documentation analysis
-    └── .task/
-        ├── IMPL-001.json             # System overview task
-        ├── IMPL-002.json             # Module documentation task
-        ├── IMPL-003.json             # Architecture documentation task
-        └── IMPL-004.json             # API documentation task
+### 1. Review Planning Output
+```bash
+cat .workflow/WFS-docs-*/IMPL_PLAN.md
+cat .workflow/WFS-docs-*/TODO_LIST.md
 ```
 
-### Task Flow Control Templates
+### 2. Execute Documentation Tasks
+```bash
+# Sequential (recommended)
+/workflow:execute IMPL-001  # System overview first
+/workflow:execute IMPL-002  # Module docs
+/workflow:execute IMPL-003
+/workflow:execute IMPL-004  # Architecture
+/workflow:execute IMPL-005  # API docs
 
-**System Overview Task (IMPL-001)**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "system_architecture_analysis",
-      "action": "Discover system architecture and module hierarchy",
-      "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
-      "output_to": "system_structure"
-    },
-    {
-      "step": "project_discovery",
-      "action": "Discover project structure and entry points",
-      "command": "bash(find . -type f -name '*.json' -o -name '*.md' -o -name 'package.json' | head -20)",
-      "output_to": "project_structure"
-    },
-    {
-      "step": "analyze_tech_stack",
-      "action": "Analyze technology stack and dependencies using structure analysis",
-      "command": "~/.claude/scripts/gemini-wrapper -p \"Analyze project technology stack and dependencies based on: [system_structure]\"",
-      "output_to": "tech_analysis"
-    }
-  ],
-  "target_files": [".workflow/docs/README.md"]
-}
+# Parallel (module docs only)
+/workflow:execute IMPL-002 &
+/workflow:execute IMPL-003 &
+wait
 ```
 
-**Module Documentation Task (IMPL-002)**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "load_system_structure",
-      "action": "Load system architecture analysis from previous task",
-      "command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)",
-      "output_to": "system_context"
-    },
-    {
-      "step": "module_analysis",
-      "action": "Analyze specific module structure and API within system context",
-      "command": "~/.claude/scripts/gemini-wrapper -p \"Analyze module [MODULE_NAME] structure and exported API within system: [system_context]\"",
-      "output_to": "module_context"
-    }
-  ],
-  "target_files": [".workflow/docs/modules/[MODULE_NAME]/overview.md"]
-}
+### 3. Review Generated Documentation
+```bash
+ls -lah .workflow/docs/
+cat .workflow/docs/README.md
 ```
 
-## Analysis Templates
-
-### Project Structure Analysis Rules
-- Identify main modules and purposes
-- Map directory organization patterns
-- Extract entry points and configuration files
-- Recognize architectural styles and design patterns
-- Analyze module relationships and dependencies
-- Document technology stack and requirements
-
-### Module Analysis Rules
-- Identify module boundaries and entry points
-- Extract exported functions, classes, interfaces
-- Document internal organization and structure
-- Analyze API surfaces with types and parameters
-- Map dependencies within and between modules
-- Extract usage patterns and examples
-
-### API Analysis Rules
-- Classify endpoint types (REST, GraphQL, WebSocket, RPC)
-- Extract request/response parameters and schemas
-- Document authentication and authorization requirements
-- Generate OpenAPI 3.0 specification structure
-- Create comprehensive endpoint documentation
-- Provide usage examples and integration guides
+### 4. TodoWrite Progress
+- Planning: All tasks `pending`
+- Execution: `pending` → `in_progress` → `completed`
+- Real-time status updates via TodoWrite
 
 ## Error Handling
-- **Invalid document type**: Clear error message with valid options
-- **Module not found**: Skip missing modules with warning
-- **Analysis failures**: Fall back to file-based analysis
-- **Permission issues**: Clear guidance on directory access
+
+- **No modules found**: Create only IMPL-001 (system overview)
+- **Scope path invalid**: Show error and exit
+- **Active session exists**: Prompt to complete or pause
+- **Tool unavailable**: Fall back to gemini
 
 ## Key Benefits
 
-### Structured Documentation Process
-- **Task-based approach**: Documentation broken into manageable, trackable tasks
-- **Flow control integration**: Systematic analysis ensures completeness
-- **Progress visibility**: TODO_LIST.md provides clear completion status
-- **Quality assurance**: Each task has defined acceptance criteria
+### Clear Separation of Concerns
+- **Planning**: Session creation, task decomposition (this command)
+- **Execution**: Content generation, quality assurance (doc-generator agent)
 
-### Workflow Integration
-- **Planning foundation**: Documentation provides context for implementation planning
-- **Execution consistency**: Same task execution model as implementation
-- **Context accumulation**: Documentation builds comprehensive project understanding
+### Scalable Task Management
+- Independent, self-contained tasks
+- Parallelizable module documentation
+- Clear dependencies (architecture needs modules)
 
-## Usage Examples
+### Template-Driven Consistency
+- All documentation follows standard templates
+- Reusable and maintainable
+- Easy to update standards
 
-### Complete Documentation Workflow
-```bash
-# Step 1: Create documentation plan and tasks
-/workflow:docs all
-
-# Step 2: Execute documentation tasks (after planning)
-/workflow:execute IMPL-001  # System overview
-/workflow:execute IMPL-002  # Module documentation
-/workflow:execute IMPL-003  # Architecture documentation
-/workflow:execute IMPL-004  # API documentation
-```
-The system creates structured documentation tasks with proper session management, task.json files, and integration with the broader workflow system for systematic and trackable documentation generation.
+### Full Context for Execution
+- Each task JSON contains complete instructions
+- flow_control defines exact analysis steps
+- Tool selection for flexibility

.claude/commands/workflow/tools/status.md

@@ -1,258 +0,0 @@
----
-name: workflow:status
-description: Generate on-demand views from JSON task data
-usage: /workflow:status [task-id] [--format=<format>] [--validate]
-argument-hint: [optional: task-id, format, validation]
-examples:
-  - /workflow:status
-  - /workflow:status impl-1
-  - /workflow:status --format=hierarchy
-  - /workflow:status --validate
----
-
-# Workflow Status Command (/workflow:status)
-
-## Overview
-Generates on-demand views from JSON task data. No synchronization needed - all views are calculated from the current state of JSON files.
-
-## Core Principles
-**Data Source:** @~/.claude/workflows/workflow-architecture.md
-
-## Key Features
-
-### Pure View Generation
-- **No Sync**: Views are generated, not synchronized
-- **Always Current**: Reads latest JSON data every time
-- **No Persistence**: Views are temporary, not saved
-- **Single Source**: All data comes from JSON files only
-
-### Multiple View Formats
-- **Overview** (default): Current tasks and status
-- **Hierarchy**: Task relationships and structure
-- **Details**: Specific task information
-
-## Usage
-
-### Default Overview
-```bash
-/workflow:status
-```
-
-Generates current workflow overview:
-```markdown
-# Workflow Overview
-**Session**: WFS-user-auth
-**Phase**: IMPLEMENT
-**Type**: medium
-
-## Active Tasks
-- [⚠️] impl-1: Build authentication module (code-developer)
-- [⚠️] impl-2: Setup user management (code-developer)
-
-## Completed Tasks
-- [✅] impl-0: Project setup
-
-## Stats
-- **Total**: 8 tasks
-- **Completed**: 3
-- **Active**: 2
-- **Remaining**: 3
-```
-
-### Specific Task View
-```bash
-/workflow:status impl-1
-```
-
-Shows detailed task information:
-```markdown
-# Task: impl-1
-
-**Title**: Build authentication module
-**Status**: active
-**Agent**: @code-developer
-**Type**: feature
-
-## Context
-- **Requirements**: JWT authentication, OAuth2 support
-- **Scope**: src/auth/*, tests/auth/*
-- **Acceptance**: Module handles JWT tokens, OAuth2 flow implemented
-- **Inherited From**: WFS-user-auth
-
-## Relations
-- **Parent**: none
-- **Subtasks**: impl-1.1, impl-1.2
-- **Dependencies**: impl-0
-
-## Execution
-- **Attempts**: 0
-- **Last Attempt**: never
-
-## Metadata
-- **Created**: 2025-09-05T10:30:00Z
-- **Updated**: 2025-09-05T10:35:00Z
-```
-
-### Hierarchy View
-```bash
-/workflow:status --format=hierarchy
-```
-
-Shows task relationships:
-```markdown
-# Task Hierarchy
-
-## Main Tasks
-- impl-0: Project setup ✅
-- impl-1: Build authentication module ⚠️
-  - impl-1.1: Design auth schema
-  - impl-1.2: Implement auth logic
-- impl-2: Setup user management ⚠️
-
-## Dependencies
-- impl-1 → depends on → impl-0
-- impl-2 → depends on → impl-1
-```
-
-## View Generation Process
-
-### Data Loading
-```pseudo
-function generate_workflow_status(task_id, format):
-  // Load all current data
-  session = load_workflow_session()
-  all_tasks = load_all_task_json_files()
-
-  // Filter if specific task requested
-  if task_id:
-    target_task = find_task(all_tasks, task_id)
-    return generate_task_detail_view(target_task)
-
-  // Generate requested format
-  switch format:
-    case 'hierarchy':
-      return generate_hierarchy_view(all_tasks)
-    default:
-      return generate_overview(session, all_tasks)
-```
-
-### Real-Time Calculation
-- **Task Counts**: Calculated from JSON file status fields
-- **Relationships**: Built from JSON relations fields
-- **Status**: Read directly from current JSON state
-
-## Validation Mode
-
-### Basic Validation
-```bash
-/workflow:status --validate
-```
-
-Performs integrity checks:
-```markdown
-# Validation Results
-
-## JSON File Validation
-✅ All task JSON files are valid
-✅ Session file is valid and readable
-
-## Relationship Validation
-✅ All parent-child relationships are valid
-✅ All dependencies reference existing tasks
-✅ No circular dependencies detected
-
-## Hierarchy Validation
-✅ Task hierarchy within depth limits (max 3 levels)
-✅ All subtask references are bidirectional
-
-## Issues Found
-⚠️ impl-3: No subtasks defined (expected for leaf task)
-
-**Status**: All systems operational
-```
-
-### Validation Checks
-- **JSON Schema**: All files parse correctly
-- **References**: All task IDs exist
-- **Hierarchy**: Parent-child relationships are valid
-- **Dependencies**: No circular dependencies
-- **Depth**: Task hierarchy within limits
-
-## Error Handling
-
-### Missing Files
-```bash
-❌ Session file not found
-→ Initialize new workflow session? (y/n)
-
-❌ Task impl-5 not found
-→ Available tasks: impl-1, impl-2, impl-3, impl-4
-```
-
-### Invalid Data
-```bash
-❌ Invalid JSON in impl-2.json
-→ Cannot generate view for impl-2
-→ Repair file manually or recreate task
-
-⚠️ Circular dependency detected: impl-1 → impl-2 → impl-1
-→ Task relationships may be incorrect
-```
-
-## Performance Benefits
-
-### Fast Generation
-- **No File Writes**: Only reads JSON files
-- **No Sync Logic**: No complex synchronization
-- **Instant Results**: Generate views on demand
-- **No Conflicts**: No state consistency issues
-
-### Scalability
-- **Large Task Sets**: Handles hundreds of tasks efficiently
-- **Complex Hierarchies**: No performance degradation
-- **Concurrent Access**: Multiple views can be generated simultaneously
-
-## Integration
-
-### Workflow Integration
-- Use after task creation to see current state
-- Use for debugging task relationships
-
-### Command Integration
-```bash
-# Common workflow
-/task:create "New feature"
-/workflow:status                    # Check current state
-/task:breakdown impl-1
-/workflow:status --format=hierarchy # View new structure
-/task:execute impl-1.1
-```
-
-## Output Formats
-
-### Supported Formats
-- `overview` (default): General workflow status
-- `hierarchy`: Task relationships
-- `tasks`: Simple task list
-- `details`: Comprehensive information
-
-### Custom Filtering
-```bash
-# Show only active tasks
-/workflow:status --format=tasks --filter=active
-
-# Show completed tasks only
-/workflow:status --format=tasks --filter=completed
-
-# Show tasks for specific agent
-/workflow:status --format=tasks --agent=@code-developer
-```
-
-## Related Commands
-
-- `/task:create` - Create tasks (generates JSON data)
-- `/task:execute` - Execute tasks (updates JSON data)
-- `/task:breakdown` - Create subtasks (generates more JSON data)
-- `/workflow:vibe` - Coordinate agents (uses workflow status for coordination)
-
-This workflow status system provides instant, accurate views of workflow state without any synchronization complexity or performance overhead.

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

@@ -169,7 +169,21 @@ Task(
       {
         "type": "synthesis_specification",
         "path": "{synthesis_spec_path}",
-        "priority": "highest"
+        "priority": "highest",
+        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+      },
+      {
+        "type": "role_analysis",
+        "path": "{role_analysis_path}",
+        "priority": "high",
+        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
+        "note": "Dynamically discovered - multiple role analysis files included based on brainstorming results"
+      },
+      {
+        "type": "topic_framework",
+        "path": "{topic_framework_path}",
+        "priority": "low",
+        "usage": "Discussion context and framework structure"
       }
     ]
   },
@@ -203,12 +217,13 @@ Task(
       }
     ],
     "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification",
+      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
       "modification_points": ["Apply requirements from synthesis"],
       "logic_flow": [
         "Load synthesis specification",
         "Analyze existing patterns",
         "Implement following specification",
+        "Consult artifacts for technical details when needed",
         "Validate against acceptance criteria"
       ]
     },
@@ -223,35 +238,231 @@ Task(
 \`\`\`markdown
 ---
 identifier: WFS-{session-id}
-source: "User requirements"
+source: "User requirements" | "File: path" | "Issue: ISS-001"
 analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+artifacts: .workflow/{session-id}/.brainstorming/
+context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+workflow_type: "standard | tdd | design"  # Indicates execution model
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
 ---
 
 # Implementation Plan: {Project Title}
 
-## Summary
-Core requirements, objectives, and technical approach.
+## 1. Summary
+Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
-## Context Analysis
-- **Project**: Type, patterns, tech stack
-- **Modules**: Components and integration points
-- **Dependencies**: External libraries and constraints
-- **Patterns**: Code conventions and guidelines
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
 
-## Brainstorming Artifacts
-- synthesis-specification.md (Highest priority)
-- topic-framework.md (Medium priority)
-- Role analyses: ui-designer, system-architect, etc.
+**Technical Approach**:
+- [High-level approach]
 
-## Task Breakdown
-- **Task Count**: N tasks, complexity level
-- **Hierarchy**: Flat/Two-level structure
-- **Dependencies**: Task dependency graph
+## 2. Context Analysis
 
-## Implementation Plan
-- **Execution Strategy**: Sequential/Parallel approach
-- **Resource Requirements**: Tools, dependencies, artifacts
-- **Success Criteria**: Metrics and acceptance conditions
+### CCW Workflow Context
+**Phase Progression**:
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
+- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
+- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+
+### Module Structure
+\`\`\`
+[Directory tree showing key modules]
+\`\`\`
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**APIs**: [External services]
+**Development**: [Testing, linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns like DI, Event-Driven]
+- **Component Design**: [Design patterns]
+- **State Management**: [State strategy]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every task references this first for requirements and design decisions
+- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
+- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
+
+**Context Intelligence (context-package.json)**:
+- **What**: Smart context gathered by CCW's context-gather phase
+- **Content**: Focus paths, dependency graph, existing patterns, module structure
+- **Usage**: Tasks load this via \`flow_control.preparatory_steps\` for environment setup
+- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen/Codex parallel analysis results
+- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
+- **Usage**: Referenced in task planning for technical guidance and risk mitigation
+- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Role-specific discussion points and analysis framework
+- **system-architect/analysis.md**: Detailed architecture specifications
+- **ui-designer/analysis.md**: Layout and component specifications
+- **product-manager/analysis.md**: Product vision and user stories
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for all tasks)
+2. context-package.json (smart context for execution environment)
+3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
+4. Role-specific analyses (fallback for detailed specifications)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
+
+**Rationale**: [Why this execution model fits the project]
+
+**Parallelization Opportunities**:
+- [List independent workstreams]
+
+**Serialization Requirements**:
+- [List critical dependencies]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [Justification for architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [State management approach]
+
+### Key Dependencies
+**Task Dependency Graph**:
+\`\`\`
+[High-level dependency visualization]
+\`\`\`
+
+**Critical Path**: [Identify bottleneck tasks]
+
+### Testing Strategy
+**Testing Approach**:
+- Unit testing: [Tools, scope]
+- Integration testing: [Key integration points]
+- E2E testing: [Critical user flows]
+
+**Coverage Targets**:
+- Lines: ≥70%
+- Functions: ≥70%
+- Branches: ≥65%
+
+**Quality Gates**:
+- [CI/CD gates]
+- [Performance budgets]
+
+## 5. Task Breakdown Summary
+
+### Task Count
+**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
+
+### Task Structure
+- **IMPL-1**: [Main task title]
+- **IMPL-2**: [Main task title]
+...
+
+### Complexity Assessment
+- **High**: [List with rationale]
+- **Medium**: [List]
+- **Low**: [List]
+
+### Dependencies
+[Reference Section 4.3 for dependency graph]
+
+**Parallelization Opportunities**:
+- [Specific task groups that can run in parallel]
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**Phase 1 (Weeks 1-2): [Phase Name]**
+- **Tasks**: IMPL-1, IMPL-2
+- **Deliverables**:
+  - [Specific deliverable 1]
+  - [Specific deliverable 2]
+- **Success Criteria**:
+  - [Measurable criterion]
+
+**Phase 2 (Weeks 3-N): [Phase Name]**
+...
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition and skills]
+
+**External Dependencies**:
+- [Third-party services, APIs]
+
+**Infrastructure**:
+- [Development, staging, production environments]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
+
+**Critical Risks** (High impact + High probability):
+- [Risk 1]: [Detailed mitigation plan]
+
+**Monitoring Strategy**:
+- [How risks will be monitored]
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All acceptance criteria from task.json files met
+
+**Technical Quality**:
+- [ ] Test coverage ≥70%
+- [ ] Bundle size within budget
+- [ ] Performance targets met
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline operational
+- [ ] Monitoring and logging configured
+- [ ] Documentation complete
+
+**Business Metrics**:
+- [ ] [Key business metrics from synthesis]
 \`\`\`
 
 #### 3. TODO_LIST.md

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

@@ -20,6 +20,9 @@ Generate TDD-specific task chains from analysis results with enforced Red-Green-
 - **Phase-Explicit**: Each task marked with Red/Green/Refactor phase
 - **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
@@ -47,32 +50,18 @@ Generate TDD-specific task chains from analysis results with enforced Red-Green-
    - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
    - Detect: synthesis-specification.md, topic-framework.md, role analyses
 
-### Phase 2: TDD Task Analysis
+### Phase 2: TDD Task JSON Generation
 
-#### Gemini TDD Breakdown
-```bash
-cd project-root && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Generate TDD task breakdown with Red-Green-Refactor chains
-TASK: Analyze ANALYSIS_RESULTS.md and create TDD-structured task breakdown
-CONTEXT: @{.workflow/{session_id}/ANALYSIS_RESULTS.md,.workflow/{session_id}/.brainstorming/*}
-EXPECTED:
-- Feature list with testable requirements (identify 3-8 features)
-- Test cases for each feature (Red phase) - specific test scenarios
-- Implementation requirements (Green phase) - minimal code to pass
-- Refactoring opportunities (Refactor phase) - quality improvements
+**Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase)
+
+**Note**: The ANALYSIS_RESULTS.md now includes TDD-specific breakdown:
+- Feature list with testable requirements
+- Test cases for Red phase
+- Implementation requirements for Green phase
+- Refactoring opportunities
 - Task dependencies and execution order
-- Focus paths for each phase
-RULES:
-- Each feature must have TEST → IMPL → REFACTOR chain
-- Tests must define clear failure conditions
-- Implementation must be minimal to pass tests
-- Refactoring must maintain green tests
-- Output structured markdown for task generation
-- Maximum 10 features (30 total tasks)
-" > .workflow/{session_id}/.process/TDD_TASK_BREAKDOWN.md
-```
 
-### Phase 3: TDD Task JSON Generation
+### Phase 3: Enhanced IMPL_PLAN.md Generation
 
 #### Task Chain Structure
 For each feature, generate 3 tasks with ID format:
@@ -145,19 +134,23 @@ For each feature, generate 3 tasks with ID format:
   "meta": {
     "type": "feature",
     "agent": "@code-developer",
-    "tdd_phase": "green"
+    "tdd_phase": "green",
+    "max_iterations": 3,
+    "use_codex": false
   },
   "context": {
     "requirements": [
       "Implement minimal AuthService to pass TEST-1.1",
       "Handle valid and invalid credentials",
-      "Return appropriate success/error responses"
+      "Return appropriate success/error responses",
+      "If tests fail after implementation, diagnose and fix iteratively"
     ],
     "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
     "acceptance": [
       "All tests in TEST-1.1 pass",
       "Implementation is minimal and focused",
-      "No over-engineering or premature optimization"
+      "No over-engineering or premature optimization",
+      "Test failures resolved within iteration limit"
     ],
     "depends_on": ["TEST-1.1"]
   },
@@ -172,21 +165,83 @@ For each feature, generate 3 tasks with ID format:
       },
       {
         "step": "verify_tests_failing",
-        "action": "Confirm tests are currently failing",
+        "action": "Confirm tests are currently failing (Red phase validation)",
         "command": "bash(npm test -- tests/auth/login.test.ts || echo 'Tests failing as expected')",
         "output_to": "initial_test_status",
         "on_error": "warn"
+      },
+      {
+        "step": "load_test_context",
+        "action": "Load test patterns and framework info",
+        "command": "bash(cat .workflow/WFS-xxx/.process/test-context-package.json 2>/dev/null || echo '{}')",
+        "output_to": "test_context",
+        "on_error": "skip_optional"
       }
     ],
+    "implementation_approach": {
+      "task_description": "Write minimal code to pass tests, then enter iterative fix cycle if they still fail",
+      "initial_implementation": [
+        "Write minimal code based on test requirements",
+        "Execute test suite: bash(npm test -- tests/auth/login.test.ts)",
+        "If tests pass → Complete task",
+        "If tests fail → Capture failure logs and proceed to test-fix cycle"
+      ],
+      "test_fix_cycle": {
+        "max_iterations": 3,
+        "cycle_pattern": "gemini_diagnose → manual_fix (or codex if meta.use_codex=true) → retest",
+        "tools": {
+          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+          "fix_application": "manual (default) or codex if meta.use_codex=true",
+          "verification": "bash(npm test -- tests/auth/login.test.ts)"
+        },
+        "exit_conditions": {
+          "success": "all_tests_pass",
+          "failure": "max_iterations_reached"
+        },
+        "steps": [
+          "ITERATION LOOP (max 3):",
+          "  1. Gemini Diagnosis:",
+          "     bash(cd .workflow/WFS-xxx/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+          "     PURPOSE: Diagnose TDD Green phase test failure iteration [N]",
+          "     TASK: Systematic bug analysis and fix recommendations",
+          "     MODE: analysis",
+          "     CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
+          "              Test output: [test_failures]",
+          "              Test requirements: [test_requirements]",
+          "              Implementation: [focus_paths]",
+          "     EXPECTED: Root cause analysis, code path tracing, targeted fixes",
+          "     RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
+          "            Minimal surgical fixes only - stay in Green phase",
+          "     \" > green-fix-iteration-[N]-diagnosis.md)",
+          "  2. Apply Fix (check meta.use_codex):",
+          "     IF meta.use_codex=false (default): Present diagnosis to user for manual fix",
+          "     IF meta.use_codex=true: Codex applies fix automatically",
+          "  3. Retest: bash(npm test -- tests/auth/login.test.ts)",
+          "  4. If pass → Exit loop, complete task",
+          "     If fail → Continue to next iteration",
+          "IF max_iterations reached: Revert changes, report failure"
+        ]
+      }
+    },
     "post_completion": [
       {
         "step": "verify_tests_passing",
-        "action": "Confirm all tests now pass",
+        "action": "Confirm all tests now pass (Green phase achieved)",
         "command": "bash(npm test -- tests/auth/login.test.ts)",
         "output_to": "final_test_status",
         "on_error": "fail"
       }
-    ]
+    ],
+    "error_handling": {
+      "max_iterations_reached": {
+        "action": "revert_all_changes",
+        "commands": [
+          "bash(git reset --hard HEAD)",
+          "bash(echo 'TDD Green phase failed: Unable to pass tests within 3 iterations' > .workflow/WFS-xxx/.process/green-phase-failure.md)"
+        ],
+        "report": "Generate failure report in .summaries/IMPL-1.1-failure-report.md"
+      }
+    }
   }
 }
 ```
@@ -248,19 +303,283 @@ For each feature, generate 3 tasks with ID format:
 }
 ```
 
-### Phase 4: TDD_PLAN.md Generation
+### Phase 4: Unified IMPL_PLAN.md Generation
 
-Generate TDD-specific plan with:
-- Feature breakdown
-- Red-Green-Refactor chains
-- Execution order
-- TDD compliance checkpoints
+Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
 
-### Phase 5: Enhanced IMPL_PLAN.md Generation
+**Frontmatter**:
+```yaml
+---
+identifier: WFS-{session-id}
+source: "User requirements" | "File: path" | "Issue: ISS-001"
+analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+artifacts: .workflow/{session-id}/.brainstorming/
+context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+workflow_type: "tdd"  # TDD-specific workflow
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"  # TDD workflow phases
+feature_count: N
+task_count: 3N
+tdd_chains: N
+---
+```
 
-Generate standard IMPL_PLAN.md with TDD context reference.
+**Complete Structure** (8 Sections):
 
-### Phase 6: TODO_LIST.md Generation
+```markdown
+# Implementation Plan: {Project Title}
+
+## 1. Summary
+Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
+
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
+
+**Technical Approach**:
+- TDD-driven development with Red-Green-Refactor cycles
+- [Other high-level approaches]
+
+## 2. Context Analysis
+
+### CCW Workflow Context
+**Phase Progression** (TDD-specific):
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Test Coverage Analysis (test-context-package.json: existing test patterns identified)
+- ✅ Phase 4: TDD Analysis (ANALYSIS_RESULTS.md: test-first requirements with Gemini/Qwen insights)
+- ✅ Phase 5: Concept Verification ({X} clarifications answered, test requirements clarified | skipped)
+- ⏳ Phase 6: TDD Task Generation (current phase - generating IMPL_PLAN.md with TDD chains)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (test requirements clarified, 0 ambiguities) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute for TDD dependency validation)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Test Context**: {existing test patterns, coverage baseline, test framework detected}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {test file count} tests identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+- **TDD Framework**: Testing framework and tools
+
+### Module Structure
+```
+[Directory tree showing key modules and test directories]
+```
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**Testing**: [Test framework, mocking libraries]
+**Development**: [Linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns]
+- **Testing Patterns**: [Unit, integration, E2E patterns]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every TDD task (TEST/IMPL/REFACTOR) references this for requirements and acceptance criteria
+- **How**: Extract testable requirements, architecture decisions, expected behaviors
+- **Priority**: Authoritative - defines what to test and how to implement
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth for TDD
+
+**Context Intelligence (context-package.json & test-context-package.json)**:
+- **What**: Smart context from CCW's context-gather and test-context-gather phases
+- **Content**: Focus paths, dependency graph, existing test patterns, test framework configuration
+- **Usage**: RED phase loads test patterns, GREEN phase loads implementation context
+- **CCW Value**: Automated discovery of existing tests and patterns for TDD consistency
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen parallel analysis with TDD-specific breakdown
+- **Content**: Testable requirements, test scenarios, implementation strategies, risk assessment
+- **Usage**: RED phase references test cases, GREEN phase references implementation approach
+- **CCW Value**: Multi-model analysis providing comprehensive TDD guidance
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, functional/non-functional requirements
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Discussion framework
+- **system-architect/analysis.md**: Architecture specifications
+- **Role-specific analyses**: [Other relevant analyses]
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for test cases and implementation)
+2. test-context-package.json (existing test patterns for TDD consistency)
+3. context-package.json (smart context for execution environment)
+4. ANALYSIS_RESULTS.md (technical analysis with TDD breakdown)
+5. Role-specific analyses (supplementary)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: TDD Cycles (Red-Green-Refactor)
+
+**Rationale**: Test-first approach ensures correctness and reduces bugs
+
+**TDD Cycle Pattern**:
+- RED: Write failing test
+- GREEN: Implement minimal code to pass (with test-fix cycle if needed)
+- REFACTOR: Improve code quality while keeping tests green
+
+**Parallelization Opportunities**:
+- [Independent features that can be developed in parallel]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [TDD-compatible architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [Test isolation strategy]
+
+### Key Dependencies
+**Task Dependency Graph**:
+```
+Feature 1:
+  TEST-1.1 (RED)
+      ↓
+  IMPL-1.1 (GREEN) [with test-fix cycle]
+      ↓
+  REFACTOR-1.1 (REFACTOR)
+
+Feature 2:
+  TEST-2.1 (RED) [depends on REFACTOR-1.1 if related]
+      ↓
+  IMPL-2.1 (GREEN)
+      ↓
+  REFACTOR-2.1 (REFACTOR)
+```
+
+**Critical Path**: [Identify bottleneck features]
+
+### Testing Strategy
+**TDD Testing Approach**:
+- Unit testing: Each feature has comprehensive unit tests
+- Integration testing: Cross-feature integration
+- E2E testing: Critical user flows after all TDD cycles
+
+**Coverage Targets**:
+- Lines: ≥80% (TDD ensures high coverage)
+- Functions: ≥80%
+- Branches: ≥75%
+
+**Quality Gates**:
+- All tests must pass before moving to next phase
+- Refactor phase must maintain test success
+
+## 5. TDD Task Chains (TDD-Specific Section)
+
+### Feature-by-Feature TDD Chains
+
+**Feature 1: {Feature Name}**
+```
+🔴 TEST-1.1: Write failing test for {feature}
+    ↓
+🟢 IMPL-1.1: Implement to pass tests (includes test-fix cycle: max 3 iterations)
+    ↓
+🔵 REFACTOR-1.1: Refactor implementation while keeping tests green
+```
+
+**Feature 2: {Feature Name}**
+```
+🔴 TEST-2.1: Write failing test for {feature}
+    ↓
+🟢 IMPL-2.1: Implement to pass tests (includes test-fix cycle)
+    ↓
+🔵 REFACTOR-2.1: Refactor implementation
+```
+
+[Continue for all N features]
+
+### TDD Task Breakdown Summary
+- **Total Features**: {N}
+- **Total Tasks**: {3N} (N TEST + N IMPL + N REFACTOR)
+- **TDD Chains**: {N}
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**TDD Cycle Execution**: Feature-by-feature sequential TDD cycles
+
+**Phase 1 (Weeks 1-2): Foundation Features**
+- **Features**: Feature 1, Feature 2
+- **Tasks**: TEST-1.1, IMPL-1.1, REFACTOR-1.1, TEST-2.1, IMPL-2.1, REFACTOR-2.1
+- **Deliverables**:
+  - Complete TDD cycles for foundation features
+  - All tests passing
+- **Success Criteria**:
+  - ≥80% test coverage
+  - All RED-GREEN-REFACTOR cycles completed
+
+**Phase 2 (Weeks 3-N): Advanced Features**
+[Continue with remaining features]
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition with TDD experience]
+
+**External Dependencies**:
+- [Testing frameworks, mocking services]
+
+**Infrastructure**:
+- [CI/CD with test automation]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| Tests fail repeatedly in GREEN phase | High | Medium | Test-fix cycle (max 3 iterations) with auto-revert | Dev Team |
+| Complex features hard to test | High | Medium | Break down into smaller testable units | Architect |
+| [Other risks] | Med/Low | Med/Low | [Strategies] | [Owner] |
+
+**Critical Risks** (TDD-Specific):
+- **GREEN phase failures**: Mitigated by test-fix cycle with Gemini diagnosis
+- **Test coverage gaps**: Mitigated by TDD-first approach ensuring tests before code
+
+**Monitoring Strategy**:
+- Track TDD cycle completion rate
+- Monitor test success rate per iteration
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All features implemented through TDD cycles
+- [ ] All RED-GREEN-REFACTOR cycles completed successfully
+
+**Technical Quality**:
+- [ ] Test coverage ≥80% (ensured by TDD)
+- [ ] All tests passing (GREEN state achieved)
+- [ ] Code refactored for quality (REFACTOR phase completed)
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline with automated test execution
+- [ ] Test failure alerting configured
+
+**TDD Compliance**:
+- [ ] Every feature has TEST → IMPL → REFACTOR chain
+- [ ] No implementation without tests (RED-first principle)
+- [ ] Refactoring did not break tests
+```
+
+### Phase 5: TODO_LIST.md Generation
 
 Generate task list with TDD phase indicators:
 ```markdown
@@ -270,7 +589,7 @@ Generate task list with TDD phase indicators:
 - [ ] **REFACTOR-1.1**: Refactor implementation (🔵 REFACTOR) [depends: IMPL-1.1] → [📋](./.task/REFACTOR-1.1.json)
 ```
 
-### Phase 7: Session State Update
+### Phase 6: Session State Update
 
 Update workflow-session.json with TDD metadata:
 ```json
@@ -285,18 +604,18 @@ Update workflow-session.json with TDD metadata:
 ## Output Files Structure
 ```
 .workflow/{session-id}/
-├── IMPL_PLAN.md                     # Standard implementation plan
-├── TDD_PLAN.md                      # TDD-specific plan ⭐ NEW
+├── IMPL_PLAN.md                     # Unified plan with TDD Task Chains section
 ├── TODO_LIST.md                     # Progress tracking with TDD phases
 ├── .task/
 │   ├── TEST-1.1.json                # Red phase task
-│   ├── IMPL-1.1.json                # Green phase task
+│   ├── IMPL-1.1.json                # Green phase task (with test-fix-cycle)
 │   ├── REFACTOR-1.1.json            # Refactor phase task
 │   └── ...
 └── .process/
-    ├── ANALYSIS_RESULTS.md          # Input from concept-enhanced
-    ├── TDD_TASK_BREAKDOWN.md        # Gemini TDD breakdown ⭐ NEW
-    └── context-package.json         # Input from context-gather
+    ├── ANALYSIS_RESULTS.md          # Enhanced with TDD breakdown from concept-enhanced
+    ├── test-context-package.json    # Test coverage analysis
+    ├── context-package.json         # Input from context-gather
+    └── green-fix-iteration-*.md     # Fix logs from Green phase
 ```
 
 ## Validation Rules
@@ -356,13 +675,49 @@ Structure:
 - Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1
 
 Plans generated:
-- TDD Plan: .workflow/WFS-auth/TDD_PLAN.md
-- Implementation Plan: .workflow/WFS-auth/IMPL_PLAN.md
+- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Task Chains section)
 
 Next: /workflow:execute or /workflow:tdd-verify
 ```
 
+## Test Coverage Analysis Integration
+
+The TDD workflow includes test coverage analysis (via `/workflow:tools:test-context-gather`) to:
+- Detect existing test patterns and conventions
+- Identify current test coverage gaps
+- Discover test framework and configuration
+- Enable integration with existing tests
+
+This makes TDD workflow context-aware instead of assuming greenfield scenarios.
+
+## Iterative Green Phase with Test-Fix Cycle
+
+IMPL (Green phase) tasks include automatic test-fix cycle:
+
+**Process Flow**:
+1. **Initial Implementation**: Write minimal code to pass tests
+2. **Test Execution**: Run test suite
+3. **Success Path**: Tests pass → Complete task
+4. **Failure Path**: Tests fail → Enter iterative fix cycle:
+   - **Gemini Diagnosis**: Analyze failures with bug-fix template
+   - **Fix Application**: Manual (default) or Codex (if meta.use_codex=true)
+   - **Retest**: Verify fix resolves failures
+   - **Repeat**: Up to max_iterations (default: 3)
+5. **Safety Net**: Auto-revert all changes if max iterations reached
+
+**Key Benefits**:
+- ✅ Faster feedback loop within Green phase
+- ✅ Autonomous recovery from initial implementation errors
+- ✅ Systematic debugging with Gemini's bug-fix template
+- ✅ Safe rollback prevents broken TDD state
+
+## Configuration Options
+- **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
+- `/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/task-generate.md

@@ -84,21 +84,22 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "source": "brainstorm_synthesis",
         "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
         "priority": "highest",
-        "contains": "complete_integrated_specification"
+        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+      },
+      {
+        "type": "role_analysis",
+        "source": "brainstorm_roles",
+        "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis.md",
+        "priority": "high",
+        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
+        "note": "Dynamically discovered - multiple role analysis files may be included based on brainstorming results"
       },
       {
         "type": "topic_framework",
         "source": "brainstorm_framework",
         "path": ".workflow/WFS-[session]/.brainstorming/topic-framework.md",
-        "priority": "medium",
-        "contains": "discussion_framework_structure"
-      },
-      {
-        "type": "individual_role_analysis",
-        "source": "brainstorm_roles",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md",
         "priority": "low",
-        "contains": "role_specific_analysis_fallback"
+        "usage": "Discussion context and framework structure"
       }
     ]
   },
@@ -115,14 +116,16 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "on_error": "skip_optional"
       },
       {
-        "step": "load_individual_role_artifacts",
-        "action": "Load individual role analyses as fallback",
+        "step": "load_role_analysis_artifacts",
+        "action": "Load role-specific analysis documents for technical details",
+        "note": "These artifacts contain implementation details not in synthesis. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics.",
         "commands": [
           "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis.md' 2>/dev/null | head -8)",
+          "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)",
           "Read(.workflow/WFS-[session]/.brainstorming/ui-designer/analysis.md)",
-          "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)"
+          "Read(.workflow/WFS-[session]/.brainstorming/product-manager/analysis.md)"
         ],
-        "output_to": "individual_artifacts",
+        "output_to": "role_analysis_artifacts",
         "on_error": "skip_optional"
       },
       {
@@ -152,10 +155,11 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
       }
     ],
     "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification",
+      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
       "modification_points": [
         "Apply consolidated requirements from synthesis-specification.md",
         "Follow technical guidelines from synthesis",
+        "Consult artifacts for implementation details when needed",
         "Integrate with existing patterns"
       ],
       "logic_flow": [
@@ -163,6 +167,7 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "Extract requirements and design",
         "Analyze existing patterns",
         "Implement following specification",
+        "Consult artifacts for technical details when needed",
         "Validate against acceptance criteria"
       ]
     },
@@ -235,33 +240,229 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 identifier: WFS-{session-id}
 source: "User requirements" | "File: path" | "Issue: ISS-001"
 analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+artifacts: .workflow/{session-id}/.brainstorming/
+context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+workflow_type: "standard | tdd | design"  # Indicates execution model
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
 ---
 
 # Implementation Plan: {Project Title}
 
-## Summary
-Core requirements, objectives, and technical approach.
+## 1. Summary
+Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
-## Context Analysis
-- **Project**: Type, patterns, tech stack
-- **Modules**: Components and integration points
-- **Dependencies**: External libraries and constraints
-- **Patterns**: Code conventions and guidelines
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
 
-## Brainstorming Artifacts
-- synthesis-specification.md (Highest priority)
-- topic-framework.md (Medium priority)
-- Role analyses: ui-designer, system-architect, etc.
+**Technical Approach**:
+- [High-level approach]
 
-## Task Breakdown
-- **Task Count**: N tasks, complexity level
-- **Hierarchy**: Flat/Two-level structure
-- **Dependencies**: Task dependency graph
+## 2. Context Analysis
 
-## Implementation Plan
-- **Execution Strategy**: Sequential/Parallel approach
-- **Resource Requirements**: Tools, dependencies, artifacts
-- **Success Criteria**: Metrics and acceptance conditions
+### CCW Workflow Context
+**Phase Progression**:
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
+- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
+- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+
+### Module Structure
+```
+[Directory tree showing key modules]
+```
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**APIs**: [External services]
+**Development**: [Testing, linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns like DI, Event-Driven]
+- **Component Design**: [Design patterns]
+- **State Management**: [State strategy]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every task references this first for requirements and design decisions
+- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
+- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
+
+**Context Intelligence (context-package.json)**:
+- **What**: Smart context gathered by CCW's context-gather phase
+- **Content**: Focus paths, dependency graph, existing patterns, module structure
+- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup
+- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen/Codex parallel analysis results
+- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
+- **Usage**: Referenced in task planning for technical guidance and risk mitigation
+- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Role-specific discussion points and analysis framework
+- **system-architect/analysis.md**: Detailed architecture specifications
+- **ui-designer/analysis.md**: Layout and component specifications
+- **product-manager/analysis.md**: Product vision and user stories
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for all tasks)
+2. context-package.json (smart context for execution environment)
+3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
+4. Role-specific analyses (fallback for detailed specifications)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
+
+**Rationale**: [Why this execution model fits the project]
+
+**Parallelization Opportunities**:
+- [List independent workstreams]
+
+**Serialization Requirements**:
+- [List critical dependencies]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [Justification for architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [State management approach]
+
+### Key Dependencies
+**Task Dependency Graph**:
+```
+[High-level dependency visualization]
+```
+
+**Critical Path**: [Identify bottleneck tasks]
+
+### Testing Strategy
+**Testing Approach**:
+- Unit testing: [Tools, scope]
+- Integration testing: [Key integration points]
+- E2E testing: [Critical user flows]
+
+**Coverage Targets**:
+- Lines: ≥70%
+- Functions: ≥70%
+- Branches: ≥65%
+
+**Quality Gates**:
+- [CI/CD gates]
+- [Performance budgets]
+
+## 5. Task Breakdown Summary
+
+### Task Count
+**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
+
+### Task Structure
+- **IMPL-1**: [Main task title]
+- **IMPL-2**: [Main task title]
+...
+
+### Complexity Assessment
+- **High**: [List with rationale]
+- **Medium**: [List]
+- **Low**: [List]
+
+### Dependencies
+[Reference Section 4.3 for dependency graph]
+
+**Parallelization Opportunities**:
+- [Specific task groups that can run in parallel]
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**Phase 1 (Weeks 1-2): [Phase Name]**
+- **Tasks**: IMPL-1, IMPL-2
+- **Deliverables**:
+  - [Specific deliverable 1]
+  - [Specific deliverable 2]
+- **Success Criteria**:
+  - [Measurable criterion]
+
+**Phase 2 (Weeks 3-N): [Phase Name]**
+...
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition and skills]
+
+**External Dependencies**:
+- [Third-party services, APIs]
+
+**Infrastructure**:
+- [Development, staging, production environments]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
+
+**Critical Risks** (High impact + High probability):
+- [Risk 1]: [Detailed mitigation plan]
+
+**Monitoring Strategy**:
+- [How risks will be monitored]
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All acceptance criteria from task.json files met
+
+**Technical Quality**:
+- [ ] Test coverage ≥70%
+- [ ] Bundle size within budget
+- [ ] Performance targets met
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline operational
+- [ ] Monitoring and logging configured
+- [ ] Documentation complete
+
+**Business Metrics**:
+- [ ] [Key business metrics from synthesis]
 ```
 
 ### Phase 5: TODO_LIST.md Generation

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

@@ -0,0 +1,468 @@
+---
+name: test-concept-enhanced
+description: Analyze test requirements and generate test generation strategy using Gemini
+usage: /workflow:tools:test-concept-enhanced --session <test_session_id> --context <test_context_package_path>
+argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
+examples:
+  - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
+---
+
+# Test Concept Enhanced Command
+
+## Overview
+Specialized analysis tool for test generation workflows that uses Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies.
+
+## Core Philosophy
+- **Coverage-Driven**: Focus on identified test gaps from context analysis
+- **Pattern-Based**: Learn from existing tests and project conventions
+- **Gemini-Powered**: Use Gemini for test requirement analysis and strategy design
+- **Single-Round Analysis**: Comprehensive test analysis in one execution
+- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution
+
+## Core Responsibilities
+- Parse test-context-package.json from test-context-gather
+- Analyze implementation summaries and coverage gaps
+- Study existing test patterns and conventions
+- Generate test generation strategy using Gemini
+- Produce TEST_ANALYSIS_RESULTS.md for task generation
+
+## Execution Lifecycle
+
+### Phase 1: Validation & Preparation
+
+1. **Session Validation**
+   - Load `.workflow/{test_session_id}/workflow-session.json`
+   - Verify test session type is "test-gen"
+   - Extract source session reference
+
+2. **Context Package Validation**
+   - Read `test-context-package.json`
+   - Validate required sections: metadata, source_context, test_coverage, test_framework
+   - Extract coverage gaps and framework details
+
+3. **Strategy Determination**
+   - **Simple Test Generation** (1-3 files): Single Gemini analysis
+   - **Medium Test Generation** (4-6 files): Gemini comprehensive analysis
+   - **Complex Test Generation** (>6 files): Gemini analysis with modular approach
+
+### Phase 2: Gemini Test Analysis
+
+**Tool Configuration**:
+```bash
+cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
+TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
+MODE: analysis
+CONTEXT: @{.workflow/{test_session_id}/.process/test-context-package.json}
+
+**MANDATORY FIRST STEP**: Read and analyze test-context-package.json to understand:
+- Test coverage gaps from test_coverage.missing_tests[]
+- Implementation context from source_context.implementation_summaries[]
+- Existing test patterns from test_framework.conventions
+- Changed files requiring tests from source_context.implementation_summaries[].changed_files
+
+**ANALYSIS REQUIREMENTS**:
+
+1. **Implementation Understanding**
+   - Load all implementation summaries from source session
+   - Understand implemented features, APIs, and business logic
+   - Extract key functions, classes, and modules
+   - Identify integration points and dependencies
+
+2. **Existing Test Pattern Analysis**
+   - Study existing test files for patterns and conventions
+   - Identify test structure (describe/it, test suites, fixtures)
+   - Analyze assertion patterns and mocking strategies
+   - Extract test setup/teardown patterns
+
+3. **Coverage Gap Assessment**
+   - For each file in missing_tests[], analyze:
+     - File purpose and functionality
+     - Public APIs requiring test coverage
+     - Critical paths and edge cases
+     - Integration points requiring tests
+   - Prioritize tests: high (core logic), medium (utilities), low (helpers)
+
+4. **Test Requirements Specification**
+   - For each missing test file, specify:
+     - **Test scope**: What needs to be tested
+     - **Test scenarios**: Happy path, error cases, edge cases, integration
+     - **Test data**: Required fixtures, mocks, test data
+     - **Dependencies**: External services, databases, APIs to mock
+     - **Coverage targets**: Functions/methods requiring tests
+
+5. **Test Generation Strategy**
+   - Determine test generation approach for each file
+   - Identify reusable test patterns from existing tests
+   - Plan test data and fixture requirements
+   - Define mocking strategy for dependencies
+   - Specify expected test file structure
+
+EXPECTED OUTPUT - Write to gemini-test-analysis.md:
+
+# Test Generation Analysis
+
+## 1. Implementation Context Summary
+- **Source Session**: {source_session_id}
+- **Implemented Features**: {feature_summary}
+- **Changed Files**: {list_of_implementation_files}
+- **Tech Stack**: {technologies_used}
+
+## 2. Test Coverage Assessment
+- **Existing Tests**: {count} files
+- **Missing Tests**: {count} files
+- **Coverage Percentage**: {percentage}%
+- **Priority Breakdown**:
+  - High Priority: {count} files (core business logic)
+  - Medium Priority: {count} files (utilities, helpers)
+  - Low Priority: {count} files (configuration, constants)
+
+## 3. Existing Test Pattern Analysis
+- **Test Framework**: {framework_name_and_version}
+- **File Naming Convention**: {pattern}
+- **Test Structure**: {describe_it_or_other}
+- **Assertion Style**: {expect_assert_should}
+- **Mocking Strategy**: {mocking_framework_and_patterns}
+- **Setup/Teardown**: {beforeEach_afterEach_patterns}
+- **Test Data**: {fixtures_factories_builders}
+
+## 4. Test Requirements by File
+
+### File: {implementation_file_path}
+**Test File**: {suggested_test_file_path}
+**Priority**: {high|medium|low}
+
+#### Scope
+- {description_of_what_needs_testing}
+
+#### Test Scenarios
+1. **Happy Path Tests**
+   - {scenario_1}
+   - {scenario_2}
+
+2. **Error Handling Tests**
+   - {error_scenario_1}
+   - {error_scenario_2}
+
+3. **Edge Case Tests**
+   - {edge_case_1}
+   - {edge_case_2}
+
+4. **Integration Tests** (if applicable)
+   - {integration_scenario_1}
+   - {integration_scenario_2}
+
+#### Test Data & Fixtures
+- {required_test_data}
+- {required_mocks}
+- {required_fixtures}
+
+#### Dependencies to Mock
+- {external_service_1}
+- {external_service_2}
+
+#### Coverage Targets
+- Function: {function_name} - {test_requirements}
+- Function: {function_name} - {test_requirements}
+
+---
+[Repeat for each missing test file]
+---
+
+## 5. Test Generation Strategy
+
+### Overall Approach
+- {strategy_description}
+
+### Test Generation Order
+1. {file_1} - {rationale}
+2. {file_2} - {rationale}
+3. {file_3} - {rationale}
+
+### Reusable Patterns
+- {pattern_1_from_existing_tests}
+- {pattern_2_from_existing_tests}
+
+### Test Data Strategy
+- {approach_to_test_data_and_fixtures}
+
+### Mocking Strategy
+- {approach_to_mocking_dependencies}
+
+### Quality Criteria
+- Code coverage target: {percentage}%
+- Test scenarios per function: {count}
+- Integration test coverage: {approach}
+
+## 6. Implementation Targets
+
+**Purpose**: Identify new test files to create
+
+**Format**: New test files only (no existing files to modify)
+
+**Test Files to Create**:
+1. **Target**: `tests/auth/TokenValidator.test.ts`
+   - **Type**: Create new test file
+   - **Purpose**: Test TokenValidator class
+   - **Scenarios**: 15 test cases covering validation logic, error handling, edge cases
+   - **Dependencies**: Mock JWT library, test fixtures for tokens
+
+2. **Target**: `tests/middleware/errorHandler.test.ts`
+   - **Type**: Create new test file
+   - **Purpose**: Test error handling middleware
+   - **Scenarios**: 8 test cases for different error types and response formats
+   - **Dependencies**: Mock Express req/res/next, error fixtures
+
+[List all test files to create]
+
+## 7. Success Metrics
+- **Test Coverage Goal**: {target_percentage}%
+- **Test Quality**: All scenarios covered (happy, error, edge, integration)
+- **Convention Compliance**: Follow existing test patterns
+- **Maintainability**: Clear test descriptions, reusable fixtures
+
+RULES:
+- Focus on TEST REQUIREMENTS and GENERATION STRATEGY, NOT code generation
+- Study existing test patterns thoroughly for consistency
+- Prioritize critical business logic tests
+- Specify clear test scenarios and coverage targets
+- Identify all dependencies requiring mocks
+- **MUST write output to .workflow/{test_session_id}/.process/gemini-test-analysis.md**
+- Do NOT generate actual test code or implementation
+- Output ONLY test analysis and generation strategy
+" --approval-mode yolo
+```
+
+**Output Location**: `.workflow/{test_session_id}/.process/gemini-test-analysis.md`
+
+### Phase 3: Results Synthesis
+
+1. **Output Validation**
+   - Verify `gemini-test-analysis.md` exists and is complete
+   - Validate all required sections present
+   - Check test requirements are actionable
+
+2. **Quality Assessment**
+   - Test scenarios cover happy path, errors, edge cases
+   - Dependencies and mocks clearly identified
+   - Test generation strategy is practical
+   - Coverage targets are reasonable
+
+### Phase 4: TEST_ANALYSIS_RESULTS.md Generation
+
+Synthesize Gemini analysis into standardized format:
+
+```markdown
+# Test Generation Analysis Results
+
+## Executive Summary
+- **Test Session**: {test_session_id}
+- **Source Session**: {source_session_id}
+- **Analysis Timestamp**: {timestamp}
+- **Coverage Gap**: {missing_test_count} files require tests
+- **Test Framework**: {framework}
+- **Overall Strategy**: {high_level_approach}
+
+---
+
+## 1. Coverage Assessment
+
+### Current Coverage
+- **Existing Tests**: {count} files
+- **Implementation Files**: {count} files
+- **Coverage Percentage**: {percentage}%
+
+### Missing Tests (Priority Order)
+1. **High Priority** ({count} files)
+   - {file_1} - {reason}
+   - {file_2} - {reason}
+
+2. **Medium Priority** ({count} files)
+   - {file_1} - {reason}
+
+3. **Low Priority** ({count} files)
+   - {file_1} - {reason}
+
+---
+
+## 2. Test Framework & Conventions
+
+### Framework Configuration
+- **Framework**: {framework_name}
+- **Version**: {version}
+- **Test Pattern**: {file_pattern}
+- **Test Directory**: {directory_structure}
+
+### Conventions
+- **File Naming**: {convention}
+- **Test Structure**: {describe_it_blocks}
+- **Assertions**: {assertion_library}
+- **Mocking**: {mocking_framework}
+- **Setup/Teardown**: {beforeEach_afterEach}
+
+### Example Pattern (from existing tests)
+```
+{example_test_structure_from_analysis}
+```
+
+---
+
+## 3. Test Requirements by File
+
+[For each missing test, include:]
+
+### Test File: {test_file_path}
+**Implementation**: {implementation_file}
+**Priority**: {high|medium|low}
+**Estimated Test Count**: {count}
+
+#### Test Scenarios
+1. **Happy Path**: {scenarios}
+2. **Error Handling**: {scenarios}
+3. **Edge Cases**: {scenarios}
+4. **Integration**: {scenarios}
+
+#### Dependencies & Mocks
+- {dependency_1_to_mock}
+- {dependency_2_to_mock}
+
+#### Test Data Requirements
+- {fixture_1}
+- {fixture_2}
+
+---
+
+## 4. Test Generation Strategy
+
+### Generation Approach
+{overall_strategy_description}
+
+### Generation Order
+1. {test_file_1} - {rationale}
+2. {test_file_2} - {rationale}
+3. {test_file_3} - {rationale}
+
+### Reusable Components
+- **Test Fixtures**: {common_fixtures}
+- **Mock Patterns**: {common_mocks}
+- **Helper Functions**: {test_helpers}
+
+### Quality Targets
+- **Coverage Goal**: {percentage}%
+- **Scenarios per Function**: {min_count}
+- **Integration Coverage**: {approach}
+
+---
+
+## 5. Implementation Targets
+
+**Purpose**: New test files to create (code-developer will generate these)
+
+**Test Files to Create**:
+
+1. **Target**: `tests/auth/TokenValidator.test.ts`
+   - **Implementation Source**: `src/auth/TokenValidator.ts`
+   - **Test Scenarios**: 15 (validation, error handling, edge cases)
+   - **Dependencies**: Mock JWT library, token fixtures
+   - **Priority**: High
+
+2. **Target**: `tests/middleware/errorHandler.test.ts`
+   - **Implementation Source**: `src/middleware/errorHandler.ts`
+   - **Test Scenarios**: 8 (error types, response formats)
+   - **Dependencies**: Mock Express, error fixtures
+   - **Priority**: High
+
+[List all test files with full specifications]
+
+---
+
+## 6. Success Criteria
+
+### Coverage Metrics
+- Achieve {target_percentage}% code coverage
+- All public APIs have tests
+- Critical paths fully covered
+
+### Quality Standards
+- All test scenarios covered (happy, error, edge, integration)
+- Follow existing test conventions
+- Clear test descriptions and assertions
+- Maintainable test structure
+
+### Validation Approach
+- Run full test suite after generation
+- Verify coverage with coverage tool
+- Manual review of test quality
+- Integration test validation
+
+---
+
+## 7. Reference Information
+
+### Source Context
+- **Implementation Summaries**: {paths}
+- **Existing Tests**: {example_tests}
+- **Documentation**: {relevant_docs}
+
+### Analysis Tools
+- **Gemini Analysis**: gemini-test-analysis.md
+- **Coverage Tools**: {coverage_tool_if_detected}
+```
+
+**Output Location**: `.workflow/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
+
+## Error Handling
+
+### Validation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing context package | test-context-gather not run | Run test-context-gather first |
+| No coverage gaps | All files have tests | Skip test generation, proceed to test execution |
+| No test framework detected | Missing test dependencies | Request user to configure test framework |
+| Invalid source session | Source session incomplete | Complete implementation first |
+
+### Gemini Execution Errors
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| Timeout | Large project analysis | Reduce scope, analyze by module |
+| Output incomplete | Token limit exceeded | Retry with focused analysis |
+| No output file | Write permission error | Check directory permissions |
+
+### Fallback Strategy
+- If Gemini fails, generate basic TEST_ANALYSIS_RESULTS.md from context package
+- Use coverage gaps and framework info to create minimal requirements
+- Provide guidance for manual test planning
+
+## Performance Optimization
+
+- **Focused Analysis**: Only analyze files with missing tests
+- **Pattern Reuse**: Study existing tests for quick pattern extraction
+- **Parallel Operations**: Load implementation summaries in parallel
+- **Timeout Management**: 20-minute limit for Gemini analysis
+
+## Integration
+
+### Called By
+- `/workflow:test-gen` (Phase 4: Analysis)
+
+### Requires
+- `/workflow:tools:test-context-gather` output (test-context-package.json)
+
+### Followed By
+- `/workflow:tools:test-task-generate` - Generates test task JSON with code-developer invocation
+
+## Success Criteria
+
+- ✅ Valid TEST_ANALYSIS_RESULTS.md generated
+- ✅ All missing tests documented with requirements
+- ✅ Test scenarios cover happy path, errors, edge cases
+- ✅ Dependencies and mocks identified
+- ✅ Test generation strategy is actionable
+- ✅ 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

@@ -0,0 +1,310 @@
+---
+name: test-context-gather
+description: Collect test coverage context and identify files requiring test generation
+usage: /workflow:tools:test-context-gather --session <test_session_id>
+argument-hint: "--session WFS-test-session-id"
+examples:
+  - /workflow:tools:test-context-gather --session WFS-test-auth
+  - /workflow:tools:test-context-gather --session WFS-test-payment
+---
+
+# Test Context Gather Command
+
+## Overview
+Specialized context collector for test generation workflows that analyzes test coverage, identifies missing tests, and packages implementation context from source sessions.
+
+## Core Philosophy
+- **Coverage-First**: Analyze existing test coverage before planning
+- **Gap Identification**: Locate implementation files without corresponding tests
+- **Source Context Loading**: Import implementation summaries from source session
+- **Framework Detection**: Auto-detect test framework and patterns
+- **MCP-Powered**: Leverage code-index tools for precise analysis
+
+## Core Responsibilities
+- Load source session implementation context
+- Analyze current test coverage using MCP tools
+- Identify files requiring test generation
+- Detect test framework and conventions
+- Package test context for analysis phase
+
+## Execution Lifecycle
+
+### Phase 1: Session Validation & Source Loading
+
+1. **Test Session Validation**
+   - Load `.workflow/{test_session_id}/workflow-session.json`
+   - Extract `meta.source_session` reference
+   - Validate test session type is "test-gen"
+
+2. **Source Session Context Loading**
+   - Read `.workflow/{source_session_id}/workflow-session.json`
+   - Load implementation summaries from `.workflow/{source_session_id}/.summaries/`
+   - Extract changed files and implementation scope
+   - Identify implementation patterns and tech stack
+
+### Phase 2: Test Coverage Analysis (MCP Tools)
+
+1. **Existing Test Discovery**
+   ```bash
+   # Find all test files
+   mcp__code-index__find_files(pattern="*.test.*")
+   mcp__code-index__find_files(pattern="*.spec.*")
+   mcp__code-index__find_files(pattern="*test_*.py")
+
+   # Search for test patterns
+   mcp__code-index__search_code_advanced(
+     pattern="describe|it|test|@Test",
+     file_pattern="*.test.*",
+     context_lines=0
+   )
+   ```
+
+2. **Coverage Gap Analysis**
+   ```bash
+   # For each implementation file from source session
+   # Check if corresponding test file exists
+
+   # Example: src/auth/AuthService.ts -> tests/auth/AuthService.test.ts
+   #          src/utils/validator.py -> tests/test_validator.py
+
+   # Output: List of files without tests
+   ```
+
+3. **Test Statistics**
+   - Count total test files
+   - Count implementation files from source session
+   - Calculate coverage percentage
+   - Identify coverage gaps by module
+
+### Phase 3: Test Framework Detection
+
+1. **Framework Identification**
+   ```bash
+   # Check package.json or requirements.txt
+   mcp__code-index__search_code_advanced(
+     pattern="jest|mocha|jasmine|pytest|unittest|rspec",
+     file_pattern="package.json|requirements.txt|Gemfile",
+     context_lines=2
+   )
+
+   # Analyze existing test patterns
+   mcp__code-index__search_code_advanced(
+     pattern="describe\\(|it\\(|test\\(|def test_",
+     file_pattern="*.test.*",
+     context_lines=3
+   )
+   ```
+
+2. **Convention Analysis**
+   - Test file naming patterns (*.test.ts vs *.spec.ts)
+   - Test directory structure (tests/ vs __tests__ vs src/**/*.test.*)
+   - Assertion library (expect, assert, should)
+   - Mocking framework (jest.fn, sinon, unittest.mock)
+
+### Phase 4: Context Packaging
+
+Generate `test-context-package.json`:
+
+```json
+{
+  "metadata": {
+    "test_session_id": "WFS-test-auth",
+    "source_session_id": "WFS-auth",
+    "timestamp": "2025-10-04T10:30:00Z",
+    "task_type": "test-generation",
+    "complexity": "medium"
+  },
+  "source_context": {
+    "implementation_summaries": [
+      {
+        "task_id": "IMPL-001",
+        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+        "changed_files": [
+          "src/auth/AuthService.ts",
+          "src/auth/TokenValidator.ts",
+          "src/middleware/auth.ts"
+        ],
+        "implementation_type": "feature"
+      }
+    ],
+    "tech_stack": ["typescript", "express", "jsonwebtoken"],
+    "project_patterns": {
+      "architecture": "layered",
+      "error_handling": "try-catch with custom errors",
+      "async_pattern": "async/await"
+    }
+  },
+  "test_coverage": {
+    "existing_tests": [
+      "tests/auth/AuthService.test.ts",
+      "tests/middleware/auth.test.ts"
+    ],
+    "missing_tests": [
+      {
+        "implementation_file": "src/auth/TokenValidator.ts",
+        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
+        "priority": "high",
+        "reason": "New implementation without tests"
+      }
+    ],
+    "coverage_stats": {
+      "total_implementation_files": 3,
+      "files_with_tests": 2,
+      "files_without_tests": 1,
+      "coverage_percentage": 66.7
+    }
+  },
+  "test_framework": {
+    "framework": "jest",
+    "version": "^29.0.0",
+    "test_pattern": "**/*.test.ts",
+    "test_directory": "tests/",
+    "assertion_library": "expect",
+    "mocking_framework": "jest",
+    "conventions": {
+      "file_naming": "*.test.ts",
+      "test_structure": "describe/it blocks",
+      "setup_teardown": "beforeEach/afterEach"
+    }
+  },
+  "assets": [
+    {
+      "type": "implementation_summary",
+      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+      "relevance": "Source implementation context",
+      "priority": "highest"
+    },
+    {
+      "type": "existing_test",
+      "path": "tests/auth/AuthService.test.ts",
+      "relevance": "Test pattern reference",
+      "priority": "high"
+    },
+    {
+      "type": "source_code",
+      "path": "src/auth/TokenValidator.ts",
+      "relevance": "Implementation requiring tests",
+      "priority": "high"
+    },
+    {
+      "type": "documentation",
+      "path": "CLAUDE.md",
+      "relevance": "Project conventions",
+      "priority": "medium"
+    }
+  ],
+  "focus_areas": [
+    "Generate comprehensive tests for TokenValidator",
+    "Follow existing Jest patterns from AuthService tests",
+    "Cover happy path, error cases, and edge cases",
+    "Include integration tests for middleware"
+  ]
+}
+```
+
+## Output Location
+
+```
+.workflow/{test_session_id}/.process/test-context-package.json
+```
+
+## MCP Tools Usage
+
+### File Discovery
+```bash
+# Test files
+mcp__code-index__find_files(pattern="*.test.*")
+mcp__code-index__find_files(pattern="*.spec.*")
+
+# Implementation files
+mcp__code-index__find_files(pattern="*.ts")
+mcp__code-index__find_files(pattern="*.js")
+```
+
+### Content Search
+```bash
+# Test framework detection
+mcp__code-index__search_code_advanced(
+  pattern="jest|mocha|pytest",
+  file_pattern="package.json|requirements.txt"
+)
+
+# Test pattern analysis
+mcp__code-index__search_code_advanced(
+  pattern="describe|it|test",
+  file_pattern="*.test.*",
+  context_lines=2
+)
+```
+
+### Coverage Analysis
+```bash
+# For each implementation file
+# Check if test exists
+implementation_file="src/auth/AuthService.ts"
+test_file_patterns=(
+  "tests/auth/AuthService.test.ts"
+  "src/auth/AuthService.test.ts"
+  "src/auth/__tests__/AuthService.test.ts"
+)
+
+# Search for test file
+for pattern in "${test_file_patterns[@]}"; do
+  if mcp__code-index__find_files(pattern="$pattern") | grep -q .; then
+    echo "✅ Test exists: $pattern"
+    break
+  fi
+done
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Source session not found | Invalid source_session reference | Verify test session metadata |
+| No implementation summaries | Source session incomplete | Complete source session first |
+| MCP tools unavailable | MCP not configured | Fallback to bash find/grep |
+| No test framework detected | Missing test dependencies | Request user to specify framework |
+
+## Fallback Strategy (No MCP)
+
+```bash
+# File discovery
+find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
+
+# Framework detection
+grep -r "jest\|mocha\|pytest" package.json requirements.txt 2>/dev/null
+
+# Coverage analysis
+for impl_file in $(cat changed_files.txt); do
+  test_file=$(echo $impl_file | sed 's/src/tests/' | sed 's/\(.*\)\.\(ts\|js\|py\)$/\1.test.\2/')
+  [ ! -f "$test_file" ] && echo "$impl_file → MISSING TEST"
+done
+```
+
+## Integration
+
+### Called By
+- `/workflow:test-gen` (Phase 3: Context Gathering)
+
+### Calls
+- MCP code-index tools for analysis
+- Bash file operations for fallback
+
+### Followed By
+- `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation
+
+## Success Criteria
+
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified with MCP tools
+- ✅ Test framework detected and documented
+- ✅ Valid test-context-package.json generated
+- ✅ All missing tests catalogued with priority
+- ✅ Execution time < 20 seconds
+
+## 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

@@ -0,0 +1,655 @@
+---
+name: test-task-generate
+description: Generate test-fix task JSON with iterative test-fix-retest cycle specification
+usage: /workflow:tools:test-task-generate [--use-codex] --session <test-session-id>
+argument-hint: "[--use-codex] --session WFS-test-session-id"
+examples:
+  - /workflow:tools:test-task-generate --session WFS-test-auth
+  - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+---
+
+# 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).
+
+## 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
+
+1. **Parameter Parsing**
+   - Parse `--use-codex` flag from command arguments
+   - Store flag value for IMPL-002.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
+{
+  "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"
+  },
+  "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"
+      ]
+    }
+  },
+  "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": [
+          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "bash(# Read first 2 existing test files as examples)",
+          "bash(test_files=$(mcp__code-index__find_files(pattern=\"*.test.*\") | head -2))",
+          "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
+        ],
+        "output_to": "existing_test_patterns",
+        "on_error": "skip_optional"
+      }
+    ],
+    "implementation_approach": {
+      "task_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).",
+      "generation_steps": [
+        "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"
+      ],
+      "quality_criteria": [
+        "All test scenarios from analysis are implemented",
+        "Test structure matches existing patterns",
+        "Clear test descriptions and assertions",
+        "Proper setup/teardown and fixtures",
+        "Dependencies properly mocked",
+        "Tests follow project coding standards"
+      ]
+    },
+    "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}"
+    ]
+  }
+}
+```
+
+#### IMPL-002.json - Test Execution & Fix Cycle Task
+
+```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": [
+          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "mcp__code-index__search_code_advanced(pattern=\"test|describe|it|def test_\", file_pattern=\"*.test.*\")",
+          "bash(# Count implementation files vs test files)",
+          "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
+          "bash(test_count=$(mcp__code-index__find_files(pattern=\"*.test.*\") | wc -l))",
+          "bash(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": {
+      "task_description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if explicitly needed)",
+      "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-wrapper (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 && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+        "      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/prompt-templates/bug-fix.md) | 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"
+        }
+      }
+    },
+    "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"
+      ]
+    }
+  }
+}
+```
+
+### Phase 3: IMPL_PLAN.md Generation
+
+#### Document Structure
+```markdown
+---
+identifier: WFS-test-[session-id]
+source_session: WFS-[source-session-id]
+workflow_type: test_session
+test_framework: jest|pytest|cargo|detected
+---
+
+# 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
+```
+
+## Output Files Structure
+```
+.workflow/WFS-test-[session]/
+├── workflow-session.json           # Test session metadata
+├── IMPL_PLAN.md                    # Test validation plan
+├── TODO_LIST.md                    # Progress tracking
+├── .task/
+│   └── IMPL-001.json               # Test-fix task with cycle spec
+├── .process/
+│   ├── ANALYSIS_RESULTS.md         # From concept-enhanced (optional)
+│   ├── context-package.json        # From context-gather
+│   ├── initial-test.log            # Phase 1: Initial test results
+│   ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
+│   ├── fix-iteration-1-changes.log  # Codex changes iteration 1
+│   ├── fix-iteration-1-retest.log   # Retest results iteration 1
+│   ├── fix-iteration-N-*.md/log    # Subsequent iterations
+│   └── final-test.log              # Phase 3: Final validation
+└── .summaries/
+    └── IMPL-001-summary.md         # Success report OR failure report
+```
+
+## Error Handling
+
+### Input Validation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Not a test session | Missing workflow_type: "test_session" | Verify session created by test-gen |
+| Source session not found | Invalid source_session_id | Check source session exists |
+| No implementation summaries | Source session incomplete | Ensure source session has completed tasks |
+
+### Test Framework Discovery Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No test command found | Unknown framework | Manual test command specification |
+| No test files found | Tests not written | Request user to write tests first |
+| Test dependencies missing | Incomplete setup | Run dependency installation |
+
+### Generation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Invalid JSON structure | Template error | Fix task generation logic |
+| Missing required fields | Incomplete metadata | Validate session metadata |
+
+## Integration & Usage
+
+### Command Chain
+- **Called By**: `/workflow:test-gen` (Phase 4)
+- **Calls**: None (terminal command)
+- **Followed By**: `/workflow:execute` (user-triggered)
+
+### Basic Usage
+```bash
+# Manual fix mode (default)
+/workflow:tools:test-task-generate --session WFS-test-auth
+
+# Automated Codex fix mode
+/workflow:tools:test-task-generate --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
+
+## 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
+
+## Agent Execution Notes
+
+The `@test-fix-agent` will execute the task by following the `flow_control.implementation_approach` specification:
+
+1. **Load task JSON**: Read complete test-fix task from `.task/IMPL-002.json`
+2. **Check meta.use_codex**: Determine fix mode (manual or automated)
+3. **Execute pre_analysis**: Load source context, discover framework, analyze tests
+4. **Phase 1**: Run initial test suite
+5. **Phase 2**: If failures, enter iterative loop:
+   - Use Gemini for diagnosis (analysis mode with bug-fix template)
+   - Check meta.use_codex flag:
+     - If false (default): Present fix suggestions to user for manual application
+     - If true (--use-codex): Use Codex resume for automated fixes (maintains context)
+   - Retest and check for regressions
+   - Repeat max 5 times
+6. **Phase 3**: Generate summary and certify code
+7. **Error Recovery**: Revert changes if max iterations reached
+
+**Bug Diagnosis Template**: Uses bug-fix.md template as referenced in bug-index.md for systematic root cause analysis, code path tracing, and targeted fix recommendations.
+
+**Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.

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

@@ -0,0 +1,450 @@
+---
+name: consolidate
+description: Consolidate style variants into independent design systems and plan layout strategies
+usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
+examples:
+  - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --variants 3
+  - /workflow:ui-design:consolidate --session WFS-auth --variants 2
+  - /workflow:ui-design:consolidate --base-path "./.workflow/.design/run-20250109-150533"  # Uses all variants
+  - /workflow:ui-design:consolidate --session WFS-auth  # Process all variants from extraction
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
+---
+
+# Design System Consolidation Command
+
+## Overview
+Consolidate user-selected style variants into **independent production-ready design systems**. This command serves as the **Style Planning Phase**, focusing exclusively on design tokens and style guides for the subsequent generation phase.
+
+## Core Philosophy
+- **Style System Focus**: Exclusively handles design system consolidation
+- **Agent-Driven**: Uses ui-design-agent for multi-file generation efficiency
+- **Separate Design Systems**: Generates N independent design systems (one per variant)
+- **Token Refinement**: Refines `proposed_tokens` from each variant into complete systems
+- **Intelligent Synthesis**: Ensures completeness and consistency
+- **Production-Ready**: Complete design system(s) with documentation
+- **Matrix-Ready**: Provides style variants for style × layout matrix exploration in generate phase
+
+## Execution Protocol
+
+### Phase 1: Path Resolution & Variant Loading
+
+```bash
+# Determine base path
+IF --base-path: base_path = {provided_base_path}
+ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
+
+# Verify extraction output exists
+style_cards_path = "{base_path}/style-extraction/style-cards.json"
+VERIFY: exists(style_cards_path)
+
+# Load style cards
+style_cards = Read(style_cards_path)
+total_variants = len(style_cards.style_cards)
+```
+
+### Phase 2: Variant Selection
+
+```bash
+# Determine how many variants to consolidate
+IF --variants:
+    variants_count = {provided_count}
+    VALIDATE: 1 <= variants_count <= total_variants
+ELSE:
+    variants_count = total_variants
+
+# Select first N variants
+selected_variants = style_cards.style_cards[0:variants_count]
+VERIFY: selected_variants.length > 0
+
+REPORT: "📦 Generating {variants_count} independent design systems"
+```
+
+### Phase 3: Load Design Context (Optional)
+
+```bash
+# Load brainstorming context if available
+design_context = ""
+IF exists({base_path}/.brainstorming/synthesis-specification.md):
+    design_context = Read(synthesis-specification.md)
+ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
+    design_context = Read(ui-designer/analysis.md)
+
+# Load design space analysis from extraction phase
+design_space_analysis = {}
+design_space_path = "{base_path}/style-extraction/design-space-analysis.json"
+IF exists(design_space_path):
+    design_space_analysis = Read(design_space_path)
+    REPORT: "📊 Loaded design space analysis with {len(design_space_analysis.divergent_directions)} variant directions"
+ELSE:
+    REPORT: "⚠️ No design space analysis found - will refine tokens from proposed_tokens only"
+```
+
+### Phase 4: Design System Synthesis (Agent Execution)
+
+```bash
+REPORT: "🤖 Using agent for separate design system generation..."
+
+# Create output directories
+Bash(mkdir -p "{base_path}/style-consolidation/style-{{1..{variants_count}}}")
+
+# Prepare agent task prompt with clear task identifier
+agent_task_prompt = """
+[DESIGN_TOKEN_GENERATION_TASK]
+
+CRITICAL: You MUST use Write() tool to create files. DO NOT return file contents as text.
+
+## Task Summary
+Generate {variants_count} independent design systems using philosophy-driven refinement and WRITE files directly (NO MCP calls).
+
+## Context
+SESSION: {session_id}
+MODE: Separate design system generation with philosophy-driven refinement (NO MCP)
+BASE_PATH: {base_path}
+VARIANTS TO PROCESS: {variants_count}
+
+## Variant Data
+
+CRITICAL PATH MAPPING:
+- Variant 1 (id: {variant.id}) → Output directory: style-1/
+- Variant 2 (id: {variant.id}) → Output directory: style-2/
+- Variant N (id: {variant.id}) → Output directory: style-N/
+
+Use loop index (1-based) for directory names, NOT variant.id.
+
+{FOR each variant IN selected_variants with index N (1-based):
+  ---
+  VARIANT INDEX: {N} (use this for directory: style-{N}/)
+  Variant ID: {variant.id} (metadata only, DO NOT use in paths)
+  Name: {variant.name}
+  Description: {variant.description}
+  Design Philosophy: {variant.design_philosophy}
+  Proposed Tokens: {JSON.stringify(variant.proposed_tokens, null, 2)}
+  ---
+}
+
+{IF design_context: DESIGN CONTEXT (from brainstorming): {design_context}}
+
+{IF design_space_analysis:
+## Design Space Analysis (for Philosophy-Driven Refinement)
+{JSON.stringify(design_space_analysis, null, 2)}
+
+Note: Each variant has design_attributes and anti_keywords for token refinement.
+Use philosophy_name and design_attributes to guide token generation WITHOUT external research.
+}
+
+## Task
+For EACH variant (1 to {variants_count}):
+1. **Load variant's design philosophy and attributes** (from design_space_analysis)
+2. **Refine design tokens** using philosophy-driven strategy (NO external research)
+3. **Generate and WRITE 2 files** to the file system
+
+## Step 1: Load Design Philosophy (No MCP Calls)
+
+IF design_space_analysis is provided:
+  FOR EACH variant:
+    1. **Extract Design Direction**: Load philosophy_name, design_attributes, search_keywords, anti_keywords
+    2. **Use as Refinement Guide**: Apply philosophy and attributes to token generation
+    3. **Enforce Constraints**: Avoid characteristics listed in anti_keywords
+    4. **Maintain Divergence**: Ensure tokens differ from other variants based on attributes
+
+ELSE:
+  Refine tokens based solely on variant's proposed_tokens and design_philosophy from style-cards.json
+
+## Philosophy-Driven Refinement Strategy
+
+**Core Principles**:
+- Use variant's design_attributes as primary guide (color saturation, visual weight, formality, organic/geometric, innovation, density)
+- Apply anti_keywords as explicit constraints during token selection
+- Ensure WCAG AA accessibility using built-in AI knowledge (4.5:1 text, 3:1 UI)
+- Preserve maximum contrast between variants from extraction phase
+
+**Refinement Process** (Apply to each variant):
+1. **Colors**: Generate palette based on saturation attribute
+   - "monochrome" → low chroma values (oklch L 0.00-0.02 H)
+   - "vibrant" → high chroma values (oklch L 0.20-0.30 H)
+2. **Typography**: Select font families matching formality level
+   - "playful" → rounded, friendly fonts
+   - "luxury" → serif, elegant fonts
+3. **Spacing**: Apply density attribute
+   - "spacious" → larger spacing scale (e.g., "4": "1.5rem")
+   - "compact" → smaller spacing scale (e.g., "4": "0.75rem")
+4. **Shadows**: Match visual weight
+   - "minimal" → subtle shadows with low opacity
+   - "bold" → strong shadows with higher spread
+5. **Border Radius**: Align with organic/geometric attribute
+   - "organic" → larger radius values (xl: "1.5rem")
+   - "brutalist" → minimal radius (xl: "0.125rem")
+6. **Innovation**: Influence overall token adventurousness
+   - "timeless" → conservative, proven values
+   - "experimental" → unconventional token combinations
+
+## Step 2: Refinement Rules (apply to each variant)
+1. **Complete Token Coverage**: Ensure all categories present (colors, typography, spacing, etc.)
+2. **Fill Gaps**: Generate missing tokens based on variant's philosophy and design_attributes
+3. **Maintain Style Identity**: Preserve unique characteristics from proposed tokens
+4. **Semantic Naming**: Use clear names (e.g., "brand-primary" not "color-1")
+5. **Accessibility**: Validate WCAG AA contrast using built-in AI knowledge (4.5:1 text, 3:1 UI)
+6. **OKLCH Format**: All colors use oklch(L C H / A) format
+7. **Design Philosophy**: Expand variant's design philosophy based on its attributes
+8. **Divergence Preservation**: Apply anti_keywords to prevent convergence with other variants
+
+## Step 3: FILE WRITE OPERATIONS (CRITICAL)
+
+**EXECUTION MODEL**: For EACH variant (1 to {variants_count}):
+1. Load design philosophy and attributes
+2. Refine tokens using philosophy-driven strategy
+3. **IMMEDIATELY Write() files - DO NOT accumulate, DO NOT return as text**
+
+### Required Write Operations Per Variant
+
+For variant with loop index {N} (e.g., 1st variant = N=1, 2nd variant = N=2), execute these Write() operations:
+
+#### Write Operation 1: Design Tokens
+**Path**: `{base_path}/style-consolidation/style-{N}/design-tokens.json`
+**Method**: `Write(path, JSON.stringify(tokens, null, 2))`
+**Example**: For 1st variant → `{base_path}/style-consolidation/style-1/design-tokens.json`
+**Content Structure**:
+```json
+{
+  "colors": {
+    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+    "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
+    "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
+  },
+  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
+}
+```
+
+#### Write Operation 2: Style Guide
+**Path**: `{base_path}/style-consolidation/style-{N}/style-guide.md`
+**Method**: `Write(path, guide_markdown_content)`
+**Example**: For 2nd variant → `{base_path}/style-consolidation/style-2/style-guide.md`
+**Content Structure**:
+```markdown
+# Design System Style Guide - {variant.name}
+
+## Design Philosophy
+{Expanded variant philosophy}
+
+## Color System
+### Brand Colors, Surface Colors, Semantic Colors, Text Colors, Border Colors
+{List all with usage and accessibility notes}
+
+## Typography
+### Font Families, Type Scale, Usage Examples
+{Complete typography documentation}
+
+## Spacing System, Component Guidelines
+{Spacing patterns and component token examples}
+
+## Accessibility
+- All text meets WCAG AA (4.5:1 minimum)
+- UI components meet WCAG AA (3:1 minimum)
+- Focus indicators are clearly visible
+```
+
+### Execution Checklist (Per Variant)
+
+For each variant from 1 to {variants_count} (use loop index N):
+- [ ] Extract variant's philosophy, design_attributes, and anti_keywords
+- [ ] Apply philosophy-driven refinement strategy to proposed_tokens
+- [ ] Generate complete token set following refinement rules
+- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{N}/design-tokens.json", tokens_json)`
+  - Example: 1st variant → `style-1/design-tokens.json`
+- [ ] **EXECUTE**: `Write("{base_path}/style-consolidation/style-{N}/style-guide.md", guide_content)`
+  - Example: 1st variant → `style-1/style-guide.md`
+- [ ] Verify both files written successfully
+
+### Verification After Each Write
+```javascript
+// Immediately after Write() for each file (use loop index N):
+Bash(`ls -lh "{base_path}/style-consolidation/style-{N}/"`)
+// Example: For 1st variant → ls -lh ".../style-1/"
+// Confirm file exists and has reasonable size (>1KB)
+
+## Expected Final Report
+
+After completing all {variants_count} variants, report:
+```
+✅ Variant 1 ({variant_name}):
+   - design-tokens.json: 12.5 KB | {token_count} tokens
+   - style-guide.md: 8.3 KB
+✅ Variant 2 ({variant_name}):
+   - design-tokens.json: 11.8 KB | {token_count} tokens
+   - style-guide.md: 7.9 KB
+... (for all variants)
+
+Summary: {variants_count} design systems generated with philosophy-driven refinement (zero MCP calls)
+```
+
+## KEY REMINDERS (CRITICAL)
+
+**ALWAYS:**
+- Use Write() tool for EVERY file - this is your PRIMARY responsibility
+- Write files immediately after generating content for each variant
+- Verify each Write() operation succeeds before proceeding
+- Use loop index (N) for directory names: `{base_path}/style-consolidation/style-{N}/...`
+  - 1st variant → `style-1/`, 2nd variant → `style-2/`, etc.
+  - DO NOT use variant.id in paths (metadata only)
+- Apply philosophy-driven refinement strategy for each variant
+- Maintain variant divergence using design_attributes and anti_keywords
+- Report completion with file paths and sizes
+
+**NEVER:**
+- Return file contents as text with labeled sections
+- Accumulate all content and try to output at once
+- Skip Write() operations and expect orchestrator to write files
+- Use relative paths or modify provided paths
+- Use external research or MCP calls (pure AI refinement only)
+- Generate variant N+1 before completing variant N writes
+"""
+
+# Dispatch to ui-design-agent with task prompt
+Task(subagent_type="ui-design-agent", description="Generate {variants_count} separate design systems", prompt=agent_task_prompt)
+
+REPORT: "✅ Agent task dispatched for {variants_count} design systems"
+```
+
+### Phase 5: Verify Agent File Creation
+```bash
+REPORT: "📝 Verifying agent file creation for {variants_count} design systems..."
+
+# Verify each variant's files were created by agent (use numeric index)
+FOR N IN range(1, variants_count + 1):
+    tokens_path = "{base_path}/style-consolidation/style-{N}/design-tokens.json"
+    guide_path = "{base_path}/style-consolidation/style-{N}/style-guide.md"
+
+    # Verify files exist
+    VERIFY: exists(tokens_path), "Design tokens not created by agent for style-{N}"
+    VERIFY: exists(guide_path), "Style guide not created by agent for style-{N}"
+
+    # Optional: Validate JSON structure
+    TRY:
+        tokens = Read(tokens_path)
+        tokens_json = parse_json(tokens)
+        VALIDATE: tokens_json.colors exists, "Missing colors in design-tokens.json"
+        VALIDATE: tokens_json.typography exists, "Missing typography in design-tokens.json"
+        VALIDATE: tokens_json.spacing exists, "Missing spacing in design-tokens.json"
+
+        tokens_size = get_file_size(tokens_path)
+        guide_size = get_file_size(guide_path)
+        REPORT: "  ✅ style-{N}/ verified ({tokens_size} KB tokens, {guide_size} KB guide)"
+    CATCH error:
+        ERROR: "Validation failed for style-{N}: {error}"
+        REPORT: "  ⚠️ Files exist but validation failed - review agent output"
+
+REPORT: "✅ All {variants_count} design systems verified"
+```
+
+**Output Structure**:
+```
+{base_path}/style-consolidation/
+├── style-1/ (design-tokens.json, style-guide.md)
+├── style-2/ (same structure)
+└── style-N/ (same structure)
+```
+
+### Phase 6: Completion & Reporting
+
+```javascript
+TodoWrite({todos: [
+  {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
+  {content: "Select variants for consolidation", status: "completed", activeForm: "Selecting variants"},
+  {content: "Load design context and space analysis", status: "completed", activeForm: "Loading context"},
+  {content: "Apply philosophy-driven refinement", status: "completed", activeForm: "Refining design tokens"},
+  {content: "Generate design systems via agent", status: "completed", activeForm: "Generating design systems"},
+  {content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Design system consolidation complete for session: {session_id}
+
+{IF design_space_analysis:
+🎨 Philosophy-Driven Refinement:
+- {variants_count} design systems generated from AI-analyzed philosophies
+- Zero MCP calls (pure AI token refinement)
+- Divergence preserved from extraction phase design_attributes
+- Each variant maintains unique style identity via anti_keywords
+}
+
+Generated {variants_count} independent design systems:
+{FOR each variant: - {variant.name} ({variant.id})}
+
+📂 Output: {base_path}/style-consolidation/
+├── style-1/ (design-tokens.json, style-guide.md)
+├── style-2/ (same structure)
+└── style-{variants_count}/ (same structure)
+
+Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --targets "dashboard,auth" --layout-variants N
+
+Note: When called from /workflow:ui-design:explore-auto, UI generation is triggered automatically.
+Layout planning is now handled in the generate phase for each specific target.
+```
+
+## design-tokens.json Format
+
+**Token structure** (all variants follow identical structure with different values):
+
+```json
+{
+  "colors": {
+    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+    "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
+    "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
+  },
+  "typography": {
+    "font_family": {"heading": "...", "body": "...", "mono": "..."},
+    "font_size": {"xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."},
+    "font_weight": {"normal": "400", "medium": "500", "semibold": "600", "bold": "700"},
+    "line_height": {"tight": "1.25", "normal": "1.5", "relaxed": "1.75"},
+    "letter_spacing": {"tight": "-0.025em", "normal": "0", "wide": "0.025em"}
+  },
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px"}
+}
+```
+
+**Requirements**: All colors in OKLCH format, complete token coverage, semantic naming
+
+## Error Handling
+
+- **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first
+- **Invalid variant count**: List available count, auto-select all if called from auto workflow
+- **Parsing errors**: Retry with stricter format instructions
+- **Validation warnings**: Report but continue (non-blocking)
+- **Missing categories**: Claude will fill gaps based on design philosophy
+
+## Key Features
+
+1. **Philosophy-Driven Refinement** - Pure AI token refinement based on design_space_analysis from extraction phase; Uses variant-specific philosophies and design_attributes as refinement rules; Preserves maximum contrast without external trend pollution; Zero MCP calls = faster execution + better divergence preservation
+2. **Agent-Driven Architecture** - Uses ui-design-agent for multi-file generation; Processes N variants with philosophy-guided synthesis; Structured output with deterministic token generation; Agent applies design attributes directly to token values
+3. **Separate Design Systems (Matrix-Ready)** - Generates N independent design systems (one per variant); Each variant maintains unique style identity from extraction phase; Provides style foundation for style × layout matrix exploration in generate phase
+4. **Token Refinement with AI Guidance** - Reads `proposed_tokens` from style cards; Loads design_space_analysis for philosophy and attributes; Applies attributes to token generation (saturation → chroma, density → spacing, etc.); Refines tokens while maintaining variant divergence through anti_keywords
+5. **Complete Design System Output** - design-tokens.json (CSS tokens per variant); style-guide.md (documentation per variant with philosophy explanation)
+6. **Production-Ready Quality** - WCAG AA accessibility validation using built-in AI knowledge (4.5:1 text, 3:1 UI); OKLCH color format for perceptual uniformity; Semantic token naming; Complete token coverage
+7. **Streamlined Workflow** - Sequential phases with clear responsibilities; Agent handles philosophy-driven token refinement and file generation; Reproducible with deterministic structure; Context-aware (integrates brainstorming and design space analysis); ~30-60s faster without MCP overhead
+8. **Divergence Preservation** - Strictly follows design_space_analysis constraints from extraction; Applies anti_keywords to prevent variant convergence; Maintains maximum variant contrast through attribute-driven generation; No external research = pure philosophical consistency
+
+## Integration Points
+
+- **Input**:
+  - `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
+  - `design-space-analysis.json` from extraction phase (with philosophy and design_attributes)
+  - `--variants` parameter (default: all variants)
+- **Output**: Style Systems: `style-consolidation/style-{N}/design-tokens.json` and `style-guide.md` for each variant (refined with philosophy-driven approach), where N is the variant index (1, 2, 3...)
+- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow
+- **Next Command**: `/workflow:ui-design:generate --style-variants N --targets "..." --layout-variants M` performs target-specific layout planning

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

@@ -0,0 +1,390 @@
+---
+name: explore-auto-v2
+description: Exploratory UI design workflow with style-centric batch generation
+usage: /workflow:ui-design:explore-auto-v2 [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
+examples:
+  - /workflow:ui-design:explore-auto-v2 --prompt "Generate 3 style variants for modern blog: home, article, author"
+  - /workflow:ui-design:explore-auto-v2 --prompt "SaaS dashboard and settings with 2 layout options"
+  - /workflow:ui-design:explore-auto-v2 --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
+  - /workflow:ui-design:explore-auto-v2 --session WFS-auth --images "refs/*.png"
+  - /workflow:ui-design:explore-auto-v2 --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
+---
+
+# UI Design Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning.
+
+**Unified Target System**: Generates `style_variants × layout_variants × targets` prototypes, where targets can be:
+- **Pages** (full-page layouts): home, dashboard, settings, etc.
+- **Components** (isolated UI elements): navbar, card, hero, form, etc.
+- **Mixed**: Can combine both in a single workflow
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:explore-auto-v2 [params]`
+2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
+3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
+4. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
+5. **Phase 3 (ui-generate-v2)** → **WAIT for completion** → Auto-continues
+6. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+7. Phase 5 (batch-plan, optional) → 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
+
+**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).
+
+**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 1 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).
+
+## Parameter Requirements
+
+**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)
+- `--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):
+- `--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
+- If `--targets` not provided, intelligently inferred from prompt/session
+
+**Supported Target Types**:
+- **Pages** (full layouts): home, dashboard, settings, profile, login, etc.
+- **Components** (UI elements):
+  - Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
+  - Content: hero, card, list, table, grid, timeline
+  - Input: form, search, filter, input-group
+  - Feedback: modal, alert, toast, badge, progress
+  - Media: gallery, carousel, video-player, image-card
+  - Other: footer, pagination, dropdown, tooltip, avatar
+
+**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
+- "Generate **3 style variants**" → `--style-variants 3`
+- "**2 layout options**" → `--layout-variants 2`
+- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
+- Explicit flags override prompt inference
+
+## Execution Modes
+
+**Matrix Mode** (style-centric):
+- Generates `style_variants × layout_variants × targets` prototypes
+- **Phase 1**: `style_variants` style options with design_attributes (extract)
+- **Phase 2**: `style_variants` independent design systems (consolidate)
+- **Phase 3**: Style-centric batch generation (generate-v2)
+  - Sub-phase 1: `targets × layout_variants` target-specific layout plans
+  - **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
+  - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - Performance: Efficient parallel execution with S agents
+  - Quality: HTML structure adapts to design_attributes
+  - Pages: Full-page layouts with complete structure
+  - Components: Isolated elements with minimal wrapper
+
+**Integrated vs. Standalone**:
+- `--session` flag determines session integration or standalone execution
+
+## 6-Phase Execution
+
+### Phase 0a: 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
+ELSE:
+    style_variants = --style-variants OR 3
+    layout_variants = --layout-variants OR 3
+
+VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+```
+
+### Phase 0b: 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}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "workflow": "ui-design:auto-v2",
+  "version": "2.0",
+  "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}" },
+  "status": "in_progress",
+  "performance_mode": "optimized"
+}
+```
+
+### Phase 0c: 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"
+
+# Step 1-2: Explicit parameters (legacy or unified)
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets); target_source = "explicit"
+    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
+    target_list = analysis_result.targets
+    target_type = analysis_result.primary_type OR detect_target_type(target_list)
+    target_source = "prompt_analysis"
+
+# Step 4: Session synthesis
+ELSE IF --session AND exists(synthesis-specification.md):
+    target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
+
+# Step 5: Fallback
+IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [normalize(t) for t in target_list if is_valid(t)]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+IF --target-type != "auto": target_type = --target-type
+
+# Interactive confirmation
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION (v2.0 Style-Centric)"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Performance: {style_variants} agent calls (vs {layout_variants * len(validated_targets)} in v1.0)"
+  "Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+user_input = WAIT_FOR_USER_INPUT()
+
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  default → proceed with current list
+
+STORE: inferred_target_list, target_type, target_inference_source
+
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# This is the only user interaction point in the workflow
+# After this point, all subsequent phases execute automatically without user intervention
+```
+
+**Helper Function: detect_target_type()**
+```bash
+detect_target_type(target_list):
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
+
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
+
+    RETURN "component" IF component_matches > page_matches ELSE "page"
+```
+
+### Phase 1: Style Extraction
+```bash
+command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--variants {style_variants} --mode explore"
+SlashCommand(command)
+
+# Output: {style_variants} style cards with design_attributes
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2 (auto-continue)
+```
+
+### Phase 2: Style Consolidation
+```bash
+command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
+          "--variants {style_variants}"
+SlashCommand(command)
+
+# Output: {style_variants} independent design systems with tokens.css
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
+```
+
+### Phase 3: Style-Centric Matrix UI Generation
+```bash
+targets_string = ",".join(inferred_target_list)
+command = "/workflow:ui-design:generate-v2 --base-path \"{base_path}\" " +
+          "--targets \"{targets_string}\" --target-type \"{target_type}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
+
+total = style_variants × layout_variants × len(inferred_target_list)
+agent_calls = style_variants
+
+REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "   → Agent calls: {agent_calls} style-centric agents"
+REPORT: "   → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
+REPORT: "   → Style-centric generation: Each of {style_variants} agents handles {layout_variants}×{len(inferred_target_list)} combinations"
+
+SlashCommand(command)
+
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
+# Output:
+# - {target}-layout-{l}.json (target-specific layout plans)
+# - {target}-style-{s}-layout-{l}.html (final prototypes with style-aware structure)
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
+```
+
+### Phase 4: Design System Integration
+```bash
+command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
+SlashCommand(command)
+
+# 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
+```
+
+### 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}\"")
+```
+
+## TodoWrite Pattern
+```javascript
+// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
+  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute style-centric UI generation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
+]})
+
+// ⚠️ 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-v2 --prompt "Modern blog: home, article, author"
+# Result: 27 prototypes (3×3×3)
+```
+
+### 2. Custom Matrix with Session
+```bash
+/workflow:ui-design:explore-auto-v2 --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
+# Result: 2×2×N prototypes
+```
+
+### 3. Component Mode
+```bash
+/workflow:ui-design:explore-auto-v2 --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2) - components with minimal wrapper
+```
+
+### 4. Intelligent Parsing + Batch Planning
+```bash
+/workflow:ui-design:explore-auto-v2 --prompt "Create 4 styles with 2 layouts for dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated tasks
+```
+
+### 5. Large Scale
+```bash
+/workflow:ui-design:explore-auto-v2 --targets "home,dashboard,settings,profile" --style-variants 3 --layout-variants 3
+# Result: 36 prototypes (3×3×4)
+```
+
+## Completion Output
+```
+✅ UI Design Explore-Auto Workflow Complete!
+
+Architecture: Style-Centric Batch Generation
+Run ID: {run_id} | Session: {session_id or "standalone"}
+Type: {icon} {target_type} | Matrix: {s}×{l}×{n} = {total} prototypes
+
+Phase 1: {s} style variants with design_attributes (extract)
+Phase 2: {s} design systems with tokens.css (consolidate)
+Phase 3: Style-centric batch generation (generate-v2)
+  - {n}×{l} target-specific layout plans
+  - {s} style-centric agents (each handled {l}×{n} combinations)
+  - {s}×{l}×{n} = {total} final prototypes with style-aware structure
+Phase 4: Brainstorming artifacts updated
+[Phase 5: {n} implementation tasks created]  # if --batch-plan
+
+Agent Execution:
+✅ Style-centric agents: {s} agents total
+✅ Each agent handles: {l}×{n} combinations
+
+Design Quality:
+✅ Style-Aware Structure: HTML adapts to design_attributes
+✅ Style Consistency: PERFECT (each style by single agent)
+✅ Token-Driven Styling: 100% var() usage
+
+📂 {base_path}/
+  ├── style-extraction/       ({s} style cards + design-space-analysis.json)
+  ├── style-consolidation/    ({s} design systems with tokens.css)
+  ├── prototypes/
+  │   ├── _templates/         ({n}×{l} layout JSON files)
+  │   └── ...                 ({total} final prototypes)
+  └── .run-metadata.json
+
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive {s}×{l} matrix view
+  - Side-by-side comparison
+  - Target-specific layouts with style-aware structure
+  - Toggle between {n} targets
+
+{icon} Targets: {', '.join(targets)} (type: {target_type})
+  - Each target has {l} custom-designed layouts
+  - Each style × target × layout has unique HTML structure (not just CSS!)
+  - Layout plans stored as structured JSON
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+```
+

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

@@ -0,0 +1,350 @@
+---
+name: explore-auto
+description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations (3×3 matrix exploration)
+usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
+examples:
+  - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
+  - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
+  - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
+  - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
+  - /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --prompt "Compare 3 navigation bar designs" --style-variants 3 --layout-variants 2
+  - /workflow:ui-design:explore-auto --targets "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
+  - /workflow:ui-design:explore-auto --targets "home,dashboard" --target-type "page"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
+---
+
+# UI Design Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning.
+
+**Unified Target System**: Generates `style_variants × layout_variants × targets` prototypes, where targets can be:
+- **Pages** (full-page layouts): home, dashboard, settings, etc.
+- **Components** (isolated UI elements): navbar, card, hero, form, etc.
+- **Mixed**: Can combine both in a single workflow
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:explore-auto [params]`
+2. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
+3. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
+4. Phase 3 (ui-generate) → **WAIT for completion** → Auto-continues with unified target list
+5. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+6. Phase 5 (batch-plan, optional) → Reports completion
+
+**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).
+
+**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 1 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).
+
+## Parameter Requirements
+
+**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)
+- `--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):
+- `--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
+- If `--targets` not provided, intelligently inferred from prompt/session
+
+**Supported Target Types**:
+- **Pages** (full layouts): home, dashboard, settings, profile, login, etc.
+- **Components** (UI elements):
+  - Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
+  - Content: hero, card, list, table, grid, timeline
+  - Input: form, search, filter, input-group
+  - Feedback: modal, alert, toast, badge, progress
+  - Media: gallery, carousel, video-player, image-card
+  - Other: footer, pagination, dropdown, tooltip, avatar
+
+**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
+- "Generate **3 style variants**" → `--style-variants 3`
+- "**2 layout options**" → `--layout-variants 2`
+- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
+- Explicit flags override prompt inference
+
+## Execution Modes
+
+**Matrix Mode** (unified):
+- Generates `style_variants × layout_variants × targets` prototypes
+- **Phase 1**: `style_variants` style options (extract)
+- **Phase 2**: `style_variants` independent design systems (consolidate)
+- **Phase 3**: Layout planning + UI generation (generate)
+  - Sub-phase 1: `targets × layout_variants` target-specific layout plans
+  - Sub-phase 2: `layout_variants × targets` HTML/CSS templates
+  - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - Pages: Full-page layouts with complete structure
+  - Components: Isolated elements with minimal wrapper
+  - Mixed: Combination based on intelligent detection
+
+**Integrated vs. Standalone**:
+- `--session` flag determines session integration or standalone execution
+
+## 6-Phase Execution
+
+### Phase 0a: 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
+ELSE:
+    style_variants = --style-variants OR 3
+    layout_variants = --layout-variants OR 3
+
+VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+```
+
+### Phase 0b: 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}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "workflow": "ui-design:auto",
+  "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
+                  "targets": "${inferred_target_list}", "target_type": "${target_type}",
+                  "prompt": "${prompt_text}", "images": "${images_pattern}" },
+  "status": "in_progress"
+}
+```
+
+### Phase 0c: 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"
+
+# Step 1-2: Explicit parameters (legacy or unified)
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets); target_source = "explicit"
+    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
+    target_list = analysis_result.targets
+    target_type = analysis_result.primary_type OR detect_target_type(target_list)
+    target_source = "prompt_analysis"
+
+# Step 4: Session synthesis
+ELSE IF --session AND exists(synthesis-specification.md):
+    target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
+
+# Step 5: Fallback
+IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [normalize(t) for t in target_list if is_valid(t)]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+IF --target-type != "auto": target_type = --target-type
+
+# Interactive confirmation
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+user_input = WAIT_FOR_USER_INPUT()
+
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  default → proceed with current list
+
+STORE: inferred_target_list, target_type, target_inference_source
+```
+
+**Helper Function: detect_target_type()**
+```bash
+detect_target_type(target_list):
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
+
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
+
+    RETURN "component" IF component_matches > page_matches ELSE "page"
+```
+
+### Phase 1: Style Extraction
+```bash
+command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--variants {style_variants} --mode explore"
+SlashCommand(command)
+
+# WAIT for extract command to complete, then IMMEDIATELY continue to Phase 2
+# DO NOT STOP - Phase 2 must execute automatically
+```
+
+### Phase 2: Style Consolidation
+```bash
+command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
+          "--variants {style_variants}"
+SlashCommand(command)
+
+# WAIT for consolidate command to complete, then IMMEDIATELY continue to Phase 3
+# DO NOT STOP - Phase 3 must execute automatically
+# Output: style_variants independent design systems (design tokens and style guides)
+```
+
+### Phase 3: Matrix UI Generation (with Layout Planning)
+```bash
+targets_string = ",".join(inferred_target_list)
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
+          "--targets \"{targets_string}\" --target-type \"{target_type}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
+
+total = style_variants × layout_variants × len(inferred_target_list)
+REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "   → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
+
+SlashCommand(command)
+
+# WAIT for generate command to complete, then IMMEDIATELY continue to Phase 4
+# DO NOT STOP - Phase 4 must execute automatically
+# Output:
+# - {target}-layout-{l}.json (target-specific layout plans)
+# - {target}-style-{s}-layout-{l}.html (final prototypes)
+# - compare.html (matrix view)
+```
+
+### Phase 4: Design System Integration
+```bash
+command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
+SlashCommand(command)
+
+# WAIT for update command to complete
+# If --batch-plan flag present: IMMEDIATELY continue to Phase 5
+# If no --batch-plan: Workflow complete, display final report
+```
+
+### 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}\"")
+```
+
+## TodoWrite Pattern
+```javascript
+// Initialize at workflow start to track multi-phase execution
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
+  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI generation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
+]})
+
+// ⚠️ CRITICAL: After EACH phase completion, you MUST:
+// 1. Update current phase: status → "completed"
+// 2. Update next phase: status → "in_progress"
+// 3. Continue to execute next phase immediately
+// This ensures continuous workflow tracking and prevents premature stopping
+```
+
+## Key Features
+- **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 - inferred defaults)
+```
+
+### 2. 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 (targets from synthesis)
+```
+
+### 3. Component Mode
+```bash
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2 components with minimal wrapper)
+```
+
+### 4. Intelligent Parsing + Batch Planning
+```bash
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated implementation tasks
+```
+
+### 5. Legacy Support
+```bash
+/workflow:ui-design:explore-auto --pages "home,dashboard,settings"
+# Equivalent to: --targets "home,dashboard,settings" --target-type "page"
+```
+
+## Completion Output
+```
+✅ UI Design Explore-Auto Workflow Complete!
+
+Run ID: {run_id} | Session: {session_id or "standalone"}
+Type: {icon} {target_type} | Matrix: {s}×{l}×{n} = {total} prototypes
+
+Phase 1: {s} style variants (extract)
+Phase 2: {s} design systems (consolidate)
+Phase 3: Layout planning + generation (generate)
+  - {n}×{l} target-specific layout plans
+  - {l}×{n} HTML/CSS templates
+  - {s}×{l}×{n} = {total} final prototypes
+Phase 4: Brainstorming artifacts updated
+[Phase 5: {n} implementation tasks created]  # if --batch-plan
+
+📂 {base_path}/
+  ├── style-consolidation/  ({s} design systems)
+  ├── prototypes/
+  │   ├── _templates/       ({n}×{l} layout JSON + {l}×{n} HTML/CSS)
+  │   └── ...               ({total} final prototypes)
+  └── .run-metadata.json
+
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive {s}×{l} matrix view
+  - Side-by-side comparison
+  - Target-specific layouts per prototype
+
+{icon} Targets: {', '.join(targets)} (type: {target_type})
+  - Each target has {l} custom-designed layouts
+  - Layout plans stored as structured JSON
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+```

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

@@ -0,0 +1,425 @@
+---
+name: extract
+description: Extract design style from reference images or text prompts using Claude's analysis
+usage: /workflow:ui-design:extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>]
+examples:
+  - /workflow:ui-design:extract --images "design-refs/*.png" --variants 3
+  - /workflow:ui-design:extract --prompt "Modern minimalist blog, dark theme" --variants 3
+  - /workflow:ui-design:extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --variants 2
+  - /workflow:ui-design:extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --variants 3
+  - /workflow:ui-design:extract --prompt "Bold vibrant" --variants 1  # Single variant (default)
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
+---
+
+# Style Extraction Command
+
+## Overview
+Extract design style elements from reference images or text prompts using Claude's built-in analysis capabilities. Generates a single, comprehensive `style-cards.json` file containing multiple design variants with complete token proposals.
+
+## Core Philosophy
+- **Claude-Native**: 100% Claude-driven analysis, no external tools
+- **Single Output**: Only `style-cards.json` with embedded token proposals
+- **Sequential Execution**: Generate multiple style variants in one pass
+- **Flexible Input**: Images, text prompts, or both (hybrid mode)
+- **Reproducible**: Deterministic output structure
+
+## Execution Protocol
+
+### Phase 0: Parameter Detection & Validation
+
+```bash
+# Detect input source
+IF --images AND --prompt: input_mode = "hybrid"  # Text guides image analysis
+ELSE IF --images: input_mode = "image"
+ELSE IF --prompt: input_mode = "text"
+ELSE: ERROR: "Must provide --images or --prompt"
+
+# Determine base path (PRIORITY: --base-path > --session > standalone)
+IF --base-path:
+    base_path = {provided_base_path}; session_mode = "integrated"
+    session_id = base_path matches ".workflow/WFS-*/design-*" ? extract_session_id(base_path) : "standalone"
+ELSE:
+    run_id = "run-" + timestamp()
+    IF --session:
+        session_mode = "integrated"; session_id = {provided_session}
+        base_path = ".workflow/WFS-{session_id}/design-{run_id}/"
+    ELSE:
+        session_mode = "standalone"; base_path = ".workflow/.design/{run_id}/"
+
+# Set variant count
+variants_count = --variants OR 1; VALIDATE: 1 <= variants_count <= 5
+```
+
+### Phase 1: Input Loading & Validation
+
+```bash
+# Expand and validate inputs
+IF input_mode IN ["image", "hybrid"]:
+    expanded_images = Glob({--images pattern}); VERIFY: expanded_images.length > 0
+    FOR each image: image_data[i] = Read({image_path})
+
+IF input_mode IN ["text", "hybrid"]:
+    VALIDATE: --prompt is non-empty; prompt_guidance = {--prompt value}
+
+CREATE: {base_path}/style-extraction/
+```
+
+### Phase 0.5: AI-Driven Design Space Divergence
+
+```bash
+# Determine extraction mode
+extraction_mode = --mode OR "auto"
+IF extraction_mode == "auto":
+    extraction_mode = (variants_count == 1) ? "imitate" : "explore"
+    REPORT: "🔍 Auto-detected mode: {extraction_mode} (variants_count={variants_count})"
+
+# Branch: Skip or Execute divergence analysis
+IF extraction_mode == "imitate":
+    REPORT: "🎯 IMITATE MODE: High-fidelity single style extraction"
+    REPORT: "   → Skipping design space divergence analysis"
+    REPORT: "   → Proceeding to Phase 2 for direct style synthesis"
+    design_space_analysis = null
+    # Skip to Phase 2
+    GOTO Phase 2
+
+# ELSE: REQUIRED execution path for explore mode
+# ⚠️ CRITICAL: The following steps (Step 1-3) MUST be executed when extraction_mode == "explore"
+# Step 1: Load project context (explore mode only)
+project_context = ""
+IF exists({base_path}/.brainstorming/synthesis-specification.md):
+    project_context = Read(synthesis-specification.md)
+ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
+    project_context = Read(ui-designer/analysis.md)
+
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🎨 EXPLORE MODE: Analyzing design space (REQUIRED)"
+REPORT: "   → Generating {variants_count} maximally contrasting directions"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Step 2: AI-driven divergent direction generation (REQUIRED)
+divergence_prompt = """
+Analyze user requirements and generate {variants_count} MAXIMALLY CONTRASTING design directions.
+
+USER INPUT:
+{IF prompt_guidance: Prompt: "{prompt_guidance}"}
+{IF project_context: Project Context Summary: {extract_key_points(project_context, max_lines=10)}}
+{IF images: Reference Images: {image_count} images will be analyzed in next phase}
+
+DESIGN ATTRIBUTE SPACE (maximize contrast):
+- Color Saturation: [monochrome, muted, moderate, vibrant, hypersaturated]
+- Visual Weight: [minimal, light, balanced, bold, heavy]
+- Formality: [playful, casual, professional, formal, luxury]
+- Organic vs Geometric: [organic/fluid, soft, balanced, geometric, brutalist]
+- Innovation: [timeless, modern, contemporary, trendy, experimental]
+- Density: [spacious, airy, balanced, compact, dense]
+
+TASK:
+1. Identify design space center point from user requirements
+2. Generate {variants_count} directions that:
+   - Are MAXIMALLY DISTANT from each other in attribute space
+   - Each occupies a distinct region/quadrant of the design spectrum
+   - Together provide diverse aesthetic options
+   - Are contextually appropriate for project type
+   - Have clear, memorable philosophical differences
+3. For each direction, generate:
+   - Specific search keywords for MCP research (3-5 keywords)
+   - Anti-keywords to avoid (2-3 keywords)
+   - Clear rationale explaining contrast with other variants
+
+OUTPUT FORMAT: Valid JSON only, no markdown:
+{"design_space_center": {attributes}, "divergent_directions": [
+  {"id": "variant-1", "philosophy_name": "Brief name 2-3 words",
+   "design_attributes": {attribute_scores}, "search_keywords": [...],
+   "anti_keywords": [...], "rationale": "..."}
+], "contrast_verification": {"min_pairwise_distance": "0.75", "strategy": "..."}}
+
+RULES: Output ONLY valid JSON, maximize inter-variant distance, ensure each variant
+occupies distinct aesthetic region, avoid overlapping attributes
+"""
+
+# Execute AI analysis (REQUIRED in explore mode)
+divergent_directions = parse_json(Claude_Native_Analysis(divergence_prompt))
+
+REPORT: "✅ Generated {variants_count} contrasting design directions:"
+FOR direction IN divergent_directions.divergent_directions:
+    REPORT: "  - {direction.philosophy_name}: {direction.rationale}"
+
+design_space_analysis = divergent_directions
+
+# Step 3: Save design space analysis for consolidation phase (REQUIRED)
+# ⚠️ CRITICAL: This file MUST be generated in explore mode for downstream consolidation
+output_file_path = "{base_path}/style-extraction/design-space-analysis.json"
+Write({file_path: output_file_path,
+       content: JSON.stringify(design_space_analysis, null, 2)})
+
+REPORT: "💾 Saved design space analysis to design-space-analysis.json"
+
+# Verification step (REQUIRED)
+VERIFY: file_exists(output_file_path) == true
+REPORT: "✅ Verified: design-space-analysis.json exists ({file_size(output_file_path)} bytes)"
+```
+
+### Phase 2: Variant-Specific Style Synthesis & Direct File Write
+
+**Analysis Prompt Template**:
+```
+Generate {variants_count} design style proposals{IF extraction_mode == "explore": , each guided by its pre-analyzed design direction}.
+
+INPUT MODE: {input_mode}
+{IF input_mode IN ["image", "hybrid"]: VISUAL REFERENCES: {list of loaded images}}
+{IF input_mode IN ["text", "hybrid"]: TEXT GUIDANCE: "{prompt_guidance}"}
+
+{IF extraction_mode == "explore":
+DESIGN SPACE ANALYSIS: {design_space_analysis summary}
+
+VARIANT-SPECIFIC DESIGN DIRECTIONS:
+{FOR each direction IN design_space_analysis.divergent_directions:
+---
+VARIANT: {direction.id} | PHILOSOPHY: {direction.philosophy_name}
+DESIGN ATTRIBUTES: {direction.design_attributes}
+SEARCH KEYWORDS: {direction.search_keywords}
+ANTI-PATTERNS (avoid): {direction.anti_keywords}
+RATIONALE: {direction.rationale}
+---}
+}
+
+TASK: Generate {variants_count} design style variant{IF variants_count > 1: s} where {IF extraction_mode == "explore": EACH variant}:
+{IF extraction_mode == "explore":
+1. Strictly follows its pre-defined design philosophy and attributes
+2. Maintains maximum contrast with other variants' attributes
+3. Incorporates its design direction and avoids its anti-patterns
+}
+{IF extraction_mode == "imitate":
+1. Provides high-fidelity replication of reference design
+2. Focuses on accurate extraction of visual characteristics
+}
+4. Uses OKLCH color space for all color values
+5. Includes complete, production-ready design token proposals
+6. Applies WCAG AA accessibility guidelines (4.5:1 text, 3:1 UI)
+
+{IF extraction_mode == "explore":
+CRITICAL RULES FOR CONTRAST:
+- Variant-1 should feel completely different from Variant-2/3
+- Use each variant's specific attribute scores (e.g., "monochrome" vs "vibrant")
+- Each variant should embody its unique design direction
+- If Variant-1 is "minimal/geometric", Variant-2 must be "bold/organic" or similar contrast
+}
+
+OUTPUT FORMAT: JSON matching this structure:
+{"extraction_metadata": {"session_id": "...", "input_mode": "...", "timestamp": "...", "variants_count": N},
+ "style_cards": [
+   {"id": "variant-1", "name": "Concise Style Name (2-3 words)", "description": "2-3 sentences",
+    "design_philosophy": "Core design principles",
+    "preview": {"primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..."},
+    "proposed_tokens": {
+      "colors": {"brand": {...}, "surface": {...}, "semantic": {...}, "text": {...}, "border": {...}},
+      "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+      "spacing": {"0": "0", ..., "24": "6rem"},
+      "border_radius": {"none": "0", ..., "full": "9999px"},
+      "shadows": {"sm": "...", ..., "xl": "..."},
+      "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
+    }}
+   // Repeat for ALL {variants_count} variants
+ ]}
+
+RULES: {IF extraction_mode == "explore": Each variant must strictly adhere to pre-defined attributes; maximize visual contrast;}
+{IF extraction_mode == "imitate": Focus on high-fidelity replication;}
+all colors in OKLCH format; complete token structures; semantic naming;
+WCAG AA accessibility (4.5:1 text, 3:1 UI)
+```
+
+**Execution & File Write**:
+```bash
+# Execute Claude Native Analysis (internal processing, no context output)
+style_cards_json = Claude_Native_Analysis(synthesis_prompt)
+
+# Write directly to file
+Write({file_path: "{base_path}/style-extraction/style-cards.json", content: style_cards_json})
+REPORT: "💾 Saved {variants_count} style variants to style-cards.json"
+```
+
+### Phase 3: Completion
+
+```javascript
+TodoWrite({todos: [
+  {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
+  {content: extraction_mode == "explore" ? "Analyze design space for maximum contrast" : "Skip design space analysis (imitate mode)", status: "completed", activeForm: extraction_mode == "explore" ? "Analyzing design space" : "Skipping analysis"},
+  {content: extraction_mode == "explore" ? `Generate ${variants_count} divergent design directions (REQUIRED)` : "Prepare for high-fidelity extraction", status: "completed", activeForm: extraction_mode == "explore" ? "Generating directions" : "Preparing extraction"},
+  {content: extraction_mode == "explore" ? `Write and verify design-space-analysis.json (REQUIRED)` : "Skip design space output", status: "completed", activeForm: extraction_mode == "explore" ? "Writing and verifying file" : "Skipping output"},
+  {content: `Generate and write ${variants_count} ${extraction_mode == "explore" ? "contrasting" : "high-fidelity"} style variant${variants_count > 1 ? "s" : ""} to file`, status: "completed", activeForm: "Generating and writing variants"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Style extraction complete for session: {session_id}
+
+Mode: {extraction_mode == "imitate" ? "🎯 IMITATE (high-fidelity)" : "🎨 EXPLORE (contrast analysis)"}
+Input mode: {input_mode}
+{IF image mode: Images analyzed: {count}}
+{IF prompt mode: Prompt: "{truncated_prompt}"}
+
+{IF extraction_mode == "explore":
+🎨 Design Space Analysis:
+- Generated {variants_count} MAXIMALLY CONTRASTING design directions
+- Min pairwise contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
+- Strategy: {design_space_analysis.contrast_verification.strategy}
+}
+{IF extraction_mode == "imitate":
+🎯 Imitation Mode:
+- High-fidelity single style extraction
+- Design space divergence skipped for faster execution
+}
+
+Generated {variants_count} style variant{variants_count > 1 ? "s" : ""}:
+{FOR each card: - {card.name} ({card.id}) - {card.design_philosophy}}
+
+📂 Outputs:
+- {base_path}/style-extraction/style-cards.json
+{IF extraction_mode == "explore": - {base_path}/style-extraction/design-space-analysis.json}
+
+Next: /workflow:ui-design:consolidate --session {session_id} --variants {variants_count} [--layout-variants <count>]
+
+Note: When called from /workflow:ui-design:{extraction_mode == "imitate" ? "imitate" : "explore"}-auto, consolidation is triggered automatically.
+```
+
+## Output Structure
+
+```
+.workflow/WFS-{session}/design-{run_id}/style-extraction/
+├── style-cards.json              # Complete style variants with token proposals
+└── design-space-analysis.json    # Design directions (explore mode only)
+
+OR (standalone mode):
+
+.workflow/.design/{run_id}/style-extraction/
+├── style-cards.json
+└── design-space-analysis.json    # Only in explore mode
+```
+
+### style-cards.json Format
+
+**Schema Structure**:
+
+```json
+{
+  "extraction_metadata": {"session_id": "string", "input_mode": "image|text|hybrid",
+                           "timestamp": "ISO 8601", "variants_count": "number"},
+  "style_cards": [
+    {
+      "id": "variant-{n}", "name": "Concise Style Name (2-3 words)",
+      "description": "2-3 sentence description of visual language and UX",
+      "design_philosophy": "Core design principles for this variant",
+      "preview": {"primary": "oklch(...)", "background": "oklch(...)",
+                  "font_heading": "Font family, fallbacks", "border_radius": "value"},
+      "proposed_tokens": {
+        "colors": {
+          "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+          "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+          "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+          "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
+          "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
+        },
+        "typography": {
+          "font_family": {"heading": "...", "body": "...", "mono": "..."},
+          "font_size": {"xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."},
+          "font_weight": {"normal": "400", "medium": "500", "semibold": "600", "bold": "700"},
+          "line_height": {"tight": "1.25", "normal": "1.5", "relaxed": "1.75"},
+          "letter_spacing": {"tight": "-0.025em", "normal": "0", "wide": "0.025em"}
+        },
+        "spacing": {"0": "0", "1": "0.25rem", "2": "0.5rem", "3": "0.75rem", "4": "1rem",
+                    "5": "1.25rem", "6": "1.5rem", "8": "2rem", "10": "2.5rem", "12": "3rem",
+                    "16": "4rem", "20": "5rem", "24": "6rem"},
+        "border_radius": {"none": "0", "sm": "0.25rem", "md": "0.5rem", "lg": "0.75rem",
+                          "xl": "1rem", "full": "9999px"},
+        "shadows": {"sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
+                    "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07)",
+                    "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.10)",
+                    "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15)"},
+        "breakpoints": {"sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px"}
+      }
+    }
+    // Repeat structure for variants_count total (variant-1, variant-2, ..., variant-n)
+  ]
+}
+```
+
+**Key Structural Requirements**:
+- Each variant MUST have complete, independent token proposals (all categories present)
+- All colors MUST use OKLCH format: `oklch(L C H / A)`
+- Token keys MUST match exactly across all variants for consistency
+- Variants differ in VALUES, not structure
+- Production-ready: no placeholders or incomplete sections
+
+## Error Handling
+
+- **No images found**: Report glob pattern and suggest corrections
+- **Invalid prompt**: Require non-empty string for text mode
+- **Claude JSON parsing error**: Retry with stricter format instructions
+- **Invalid session**: Create standalone session automatically in `.workflow/.scratchpad/`
+- **Invalid variant count**: Clamp to 1-5 range and warn user
+
+## Key Features
+
+1. **🚀 AI-Driven Design Space Exploration** 🆕
+   - Phase 0.5: AI analyzes requirements and generates MAXIMALLY CONTRASTING design directions
+   - Uses 6-dimensional design attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density)
+   - Ensures each variant occupies a distinct region of the design spectrum
+   - Generates search keywords and anti-patterns for each variant
+   - Provides contrast verification with minimum pairwise distance metrics
+
+2. **🎯 Variant-Specific Design Directions** 🆕
+   - AI generates search keywords and anti-patterns for each variant
+   - Each variant has distinct design philosophy (e.g., "minimal brutalist" vs "bold vibrant")
+   - Philosophy-specific keywords guide synthesis
+   - Design space analysis saved for consolidation phase
+   - Trend research deferred to consolidation for better integration
+
+3. **🔒 Maximum Contrast Guarantee**
+   - AI-driven divergence ensures variants are maximally distant in attribute space
+   - Each variant has distinct: philosophy, color saturation, visual weight, formality, etc.
+   - Explicit anti-patterns prevent variants from borrowing each other's characteristics
+   - Contrast verification built into design space analysis
+
+4. **100% Claude-Native Analysis**
+   - No external tools (gemini-wrapper, codex, or MCP) - pure Claude
+   - Single-pass comprehensive analysis guided by design space analysis
+   - Fast, deterministic style synthesis without external dependencies
+
+5. **Streamlined Output**
+   - Single file (`style-cards.json`) vs. multiple scattered files
+   - Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter
+   - Each variant contains complete token proposals embedded
+
+6. **Flexible Input Modes**
+   - Image-only: Analyze visual references through each variant's philosophical lens
+   - Text-only: Generate from descriptions with maximum divergence
+   - Hybrid: Text guides image analysis while maintaining variant independence
+   - All modes enhanced with AI-driven design space analysis
+
+7. **Context-Aware & Dynamic**
+   - Extracts design keywords from user prompts (e.g., "minimalist", "Linear.app")
+   - Considers project type from brainstorming artifacts
+   - Dynamically generates design directions based on project context
+   - No hardcoded design philosophies - fully adaptive
+
+8. **Production-Ready Token Proposals**
+   - Complete design system proposals per variant
+   - OKLCH color format for perceptual uniformity and accessibility
+   - Semantic naming conventions
+   - WCAG AA accessibility considerations built-in
+   - Variant-specific token sets (not generic)
+
+9. **Workflow Integration**
+   - Integrated mode: Works within existing workflow sessions
+   - Standalone mode: Auto-creates session in scratchpad
+   - Context-aware: Can reference synthesis-specification.md or ui-designer/analysis.md
+   - Contrast metrics included in completion report
+
+## Integration Points
+
+- **Input**: Reference images (PNG, JPG, WebP) via glob patterns, or text prompts
+- **Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
+- **Context**: Optional brainstorming artifacts (`synthesis-specification.md`, `ui-designer/analysis.md`)
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
+- **Next Step**: `/workflow:ui-design:consolidate --session {session_id} --variants {count} [--layout-variants <count>]` (add `--keep-separate` for matrix mode)

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

@@ -0,0 +1,546 @@
+---
+name: generate-v2
+description: Generate UI prototypes using target-style-centric batch generation
+usage: /workflow:ui-design:generate-v2 [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+examples:
+  - /workflow:ui-design:generate-v2 --session WFS-auth --targets "dashboard,settings" --style-variants 3 --layout-variants 3
+  - /workflow:ui-design:generate-v2 --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "home,pricing"
+  - /workflow:ui-design:generate-v2 --targets "navbar,hero,card" --target-type "component" --style-variants 2 --layout-variants 2
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
+---
+
+# UI Generation Command (Target-Style-Centric Architecture)
+
+**Executor**: → @ui-design-agent
+**Parallel Generation**: Phase 2 → @ui-design-agent (T×S tasks, each handling L layouts)
+
+## Overview
+Generate production-ready UI prototypes (HTML/CSS) using **target-style-centric batch generation**. Each agent handles all layout variants for one target × one style combination, ensuring component isolation and focused generation.
+
+## Core Philosophy
+- **Target-Style-Centric**: Each of T×S agents generates L layouts for one target × one style
+- **Component Isolation**: Tasks completely independent, preventing cross-component interference
+- **Style-Aware Structure**: HTML DOM adapts based on design_attributes (density, visual_weight, etc.)
+- **Performance Optimized**: T×S agent calls with highly focused scope per agent
+- **Layout Inspiration**: Simple text-based research replaces complex JSON planning
+- **Self-Contained CSS**: Agent reads design-tokens.json and creates independent CSS (no token.css reference)
+- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
+
+## Execution Protocol
+
+### Phase 1: Path Resolution & Context Loading
+```bash
+# 1. Determine base path
+IF --base-path: base_path = {provided_base_path}
+ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
+
+# 2. Determine style variant count and layout variant count
+style_variants = --style-variants OR auto_detect_from_consolidation()
+layout_variants = --layout-variants OR 3
+VALIDATE: 1 <= style_variants <= 5
+VALIDATE: 1 <= layout_variants <= 5
+
+# Validate against actual style directories
+actual_style_count = count_directories({base_path}/style-consolidation/style-*)
+
+IF actual_style_count == 0:
+    ERROR: "No style directories found"; SUGGEST: "Run /workflow:ui-design:consolidate first"; EXIT 1
+
+IF style_variants > actual_style_count:
+    WARN: "⚠️ Requested {style_variants}, but only {actual_style_count} exist"
+    REPORT: "   Available styles: {list_directories}"; style_variants = actual_style_count
+
+REPORT: "✅ Validated style variants: {style_variants}"
+
+# 3. Enhanced target list parsing with type detection
+target_list = []; target_type = "page"  # Default
+
+# Priority 1: Unified --targets parameter
+IF --targets:
+    raw_targets = {--targets value}
+    target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
+    target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
+
+    target_type = --target-type provided ? {--target-type} : detect_target_type(target_list)
+    REPORT: "🎯 Using provided targets ({target_type}): {', '.join(target_list)}"
+
+# Priority 2: Legacy --pages parameter
+ELSE IF --pages:
+    raw_targets = {--pages value}
+    target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
+    target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
+    target_type = "page"
+    REPORT: "📋 Using provided pages (legacy): {', '.join(target_list)}"
+
+# Priority 3: Extract from synthesis-specification.md
+ELSE IF --session:
+    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+    target_list = extract_targets_from_synthesis(synthesis_spec); target_type = "page"
+    REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
+
+# Priority 4: Detect from existing prototypes or default
+ELSE:
+    target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]; target_type = "page"
+    REPORT: "📋 Detected/default targets: {', '.join(target_list)}"
+
+# 4. Validate target names
+validated_targets = [t for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
+invalid_targets = [t for t in target_list if t not in validated_targets]
+
+IF invalid_targets: REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}"
+VALIDATE: validated_targets not empty, "No valid targets found"
+target_list = validated_targets
+
+STORE: target_list, target_type
+
+# 5. Verify design systems exist
+FOR style_id IN range(1, style_variants + 1):
+    VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
+
+# 6. Load design space analysis (for style-aware generation)
+design_space_path = "{base_path}/style-extraction/design-space-analysis.json"
+IF exists(design_space_path):
+    design_space_analysis = Read(design_space_path)
+    REPORT: "📊 Loaded design space analysis with style attributes"
+ELSE:
+    WARN: "⚠️ No design space analysis found - will use basic style generation"
+    design_space_analysis = null
+
+# 7. Load requirements (if integrated mode)
+IF --session:
+    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+ELSE:
+    synthesis_spec = null
+```
+
+### Phase 1.5: Target Layout Inspiration
+```bash
+REPORT: "💡 Gathering layout inspiration for {len(target_list)} targets..."
+
+CREATE: {base_path}/prototypes/_inspirations/
+
+# For each target, gather layout inspiration via MCP search
+FOR target IN target_list:
+    REPORT: "  Researching '{target}' ({target_type}) layout patterns..."
+
+    # MCP search for layout patterns
+    search_query = f"common {target} {target_type} layout patterns variations best practices"
+    search_results = mcp__exa__web_search_exa(
+        query=search_query,
+        numResults=5
+    )
+
+    # Extract key layout patterns from search results
+    inspiration_content = f"""Layout Inspiration for '{target}' ({target_type})
+Generated: {current_timestamp()}
+Search Query: {search_query}
+
+## Layout Patterns Identified
+
+From web research, {layout_variants} distinct layout approaches:
+
+Layout 1: [First structural pattern identified from search]
+- Key characteristics: ...
+- Structure approach: ...
+
+Layout 2: [Second structural pattern]
+- Key characteristics: ...
+- Structure approach: ...
+
+Layout 3: [Third structural pattern]
+- Key characteristics: ...
+- Structure approach: ...
+
+## Reference Links
+{format_search_results_urls(search_results)}
+
+## Implementation Notes
+- Each layout should be STRUCTURALLY DIFFERENT (not just CSS variations)
+- Consider {target_type}-specific patterns (navigation, content areas, interactions)
+- Adapt structure based on design_attributes in Phase 2
+"""
+
+    # Write simple inspiration file
+    inspiration_file = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt"
+    Write(inspiration_file, inspiration_content)
+
+    REPORT: f"   ✓ Created: {target}-layout-ideas.txt"
+
+REPORT: f"✅ Phase 1.5 complete: Gathered inspiration for {len(target_list)} targets"
+```
+
+### Phase 2: Target-Style-Centric Batch Generation
+
+**Strategy**: T×S target-style-centric agents, each generating L layouts for one target × one style.
+**Performance**: T×S agent calls with component isolation
+
+```bash
+REPORT: "🎨 Phase 2: Launching {len(target_list)}×{style_variants}={len(target_list) * style_variants} target-style agents..."
+REPORT: "   Each agent generates {layout_variants} layouts for one component"
+
+CREATE: {base_path}/prototypes/
+
+# Launch ONE agent task PER TARGET × STYLE combination (parallel execution)
+FOR target IN target_list:
+    # Load layout inspiration for this target
+    inspiration_path = f"{base_path}/prototypes/_inspirations/{target}-layout-ideas.txt"
+
+    FOR style_id IN range(1, style_variants + 1):
+        # Load style-specific context
+        style_tokens_path = f"{base_path}/style-consolidation/style-{style_id}/design-tokens.json"
+        style_guide_path = f"{base_path}/style-consolidation/style-{style_id}/style-guide.md"
+
+        # Extract design attributes for this style (if available)
+        IF design_space_analysis AND style_id <= len(design_space_analysis.divergent_directions):
+            design_attributes = design_space_analysis.divergent_directions[style_id - 1]
+            philosophy_name = design_attributes.philosophy_name
+            attributes_summary = JSON.stringify({
+                density: design_attributes.design_attributes.density,
+                visual_weight: design_attributes.design_attributes.visual_weight,
+                formality: design_attributes.design_attributes.formality,
+                organic_vs_geometric: design_attributes.design_attributes.organic_vs_geometric,
+                innovation: design_attributes.design_attributes.innovation
+            })
+        ELSE:
+            design_attributes = null
+            philosophy_name = f"Style {style_id}"
+            attributes_summary = "No design attributes available"
+
+        Task(ui-design-agent): """
+          [TARGET_STYLE_UI_GENERATION]
+
+          ## 🎯 Mission
+          Generate {layout_variants} layout variants for: {target} × Style-{style_id} ({philosophy_name})
+          Output: {layout_variants × 2} files ({layout_variants} HTML + {layout_variants} CSS)
+
+          ## 🎨 Style Context
+          PHILOSOPHY: {philosophy_name}
+          {IF design_attributes:
+          DESIGN_ATTRIBUTES: {attributes_summary}
+          Key impacts:
+          - density → DOM nesting depth, whitespace scale
+          - visual_weight → wrapper layers, border/shadow strength
+          - formality → semantic structure choices
+          - organic_vs_geometric → alignment, edge treatment
+          - innovation → layout adventurousness
+          }
+
+          ## 📂 Input Resources
+          **Design System**:
+          - Design Tokens (JSON): {style_tokens_path}
+          - Style Guide: {style_guide_path}
+
+          **Layout Inspiration**: {inspiration_path}
+          Contains {layout_variants} distinct structural patterns
+
+          **Target**: {target} ({target_type})
+
+          ## 🔄 Generation Steps (for each layout 1..{layout_variants})
+
+          **1. Read Inspiration**
+          - Load: {inspiration_path}
+          - Apply layout N pattern
+
+          **2. Read Design Tokens**
+          - Load: {style_tokens_path}
+          - Parse JSON structure and extract all design token values
+          - Understand token categories: colors, typography, spacing, shadows, borders, etc.
+
+          **3. Generate HTML Structure**
+          - Complete HTML5 document (<!DOCTYPE>, <html>, <head>, <body>)
+          - Semantic elements: <header>, <nav>, <main>, <section>, <article>, <footer>
+          - ARIA attributes: aria-label, role, aria-labelledby
+          - Responsive meta: <meta name="viewport" content="width=device-width, initial-scale=1">
+          - Include CSS reference: <link rel="stylesheet" href="{target}-style-{style_id}-layout-N.css">
+          - Example: For dashboard-style-1-layout-2.html, use <link rel="stylesheet" href="dashboard-style-1-layout-2.css">
+
+          {IF design_attributes:
+          **⚠️ Adapt DOM based on design_attributes:**
+          - density='spacious' → Flatter hierarchy
+            Example: <main><section class="card"></section></main>
+          - density='compact' → Deeper nesting
+            Example: <main><div class="grid"><div class="card-wrapper"><section></section></div></div></main>
+          - visual_weight='heavy' → Extra wrapper divs for layered effects
+            Example: <div class="border-container"><div class="content-wrapper">...</div></div>
+          - visual_weight='minimal' → Direct structure, minimal wrappers
+            Example: <section class="card">...</section>
+          - organic_vs_geometric → Affects alignment patterns and edge structure
+          }
+
+          **4. Generate Self-Contained CSS**
+          ⚠️ Use design token values DIRECTLY from step 2 - create complete, independent CSS
+
+          **Required Token Usage** (from design-tokens.json):
+          - Colors: Use color values for backgrounds, text, borders
+          - Typography: Use font-family, font-size, font-weight, line-height values
+          - Spacing: Use spacing scale for margins, padding, gaps
+          - Borders: Use border-radius, border-width values
+          - Shadows: Use box-shadow values
+          - Breakpoints: Use breakpoint values for @media queries
+
+          {IF design_attributes:
+          **Apply design_attributes to token selection:**
+          - density='spacious' → Select larger spacing tokens
+          - density='compact' → Select smaller spacing tokens
+          - visual_weight='heavy' → Use stronger shadows, add borders
+          - visual_weight='minimal' → Use subtle/no shadows
+          - formality → Affects typography choices and structure
+          - organic_vs_geometric → Affects border-radius and alignment
+          }
+
+          **CSS Structure**:
+          - Complete styling: colors, typography, layout, spacing, effects
+          - Responsive design: Mobile-first with breakpoint-based @media
+          - Self-contained: No external dependencies or var() references
+
+          **5. Write Files IMMEDIATELY**
+          - Output paths:
+            - HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-N.html
+            - CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-N.css
+          - Write after generating each layout (do NOT accumulate)
+          - Do NOT return content as text
+
+          ## ✅ Success Criteria
+          - [ ] Generated exactly {layout_variants × 2} files
+          - [ ] All HTML includes correct CSS file reference (matching filename pattern)
+          - [ ] All CSS uses design token values directly (self-contained, no var() references)
+          - [ ] CSS fully embodies the style's design tokens (colors, typography, spacing, effects)
+          - [ ] {IF design_attributes: 'HTML structure adapts to design_attributes' ELSE: 'HTML follows layout inspiration'}
+          - [ ] Layouts are structurally distinct (different grids/regions, not just CSS tweaks)
+          - [ ] Files written to filesystem (not returned as text)
+
+          ## 📋 Completion
+          Report: "✅ {target} × Style-{style_id} ({philosophy_name}): {layout_variants × 2} files created"
+        """
+
+REPORT: "⏳ Phase 2: Waiting for {len(target_list) * style_variants} target-style agents to complete..."
+REPORT: "   Expected total files: {style_variants × layout_variants × len(target_list) × 2}"
+```
+
+### Phase 2.5: Verify Agent File Creation
+```bash
+REPORT: "📝 Phase 2.5: Verifying target-style generation..."
+
+total_expected = style_variants × layout_variants × len(target_list) × 2
+total_found = 0
+
+FOR target IN target_list:
+    FOR style_id IN range(1, style_variants + 1):
+        agent_files_found = 0
+
+        FOR layout_id IN range(1, layout_variants + 1):
+            html_file = f"{target}-style-{style_id}-layout-{layout_id}.html"
+            css_file = f"{target}-style-{style_id}-layout-{layout_id}.css"
+
+            html_path = f"{base_path}/prototypes/{html_file}"
+            css_path = f"{base_path}/prototypes/{css_file}"
+
+            # Verify files exist
+            IF exists(html_path) AND exists(css_path):
+                # Validate content
+                html_content = Read(html_path)
+                css_content = Read(css_path)
+
+                # Basic validation
+                VALIDATE: "<!DOCTYPE html>" in html_content, f"Invalid HTML: {html_file}"
+                VALIDATE: f'href="{css_file}"' in html_content, f"Missing or incorrect CSS reference in: {html_file}"
+                VALIDATE: len(css_content) > 100, f"CSS file too small (likely incomplete): {css_file}"
+
+                html_size = get_file_size(html_path)
+                css_size = get_file_size(css_path)
+
+                agent_files_found += 2
+                total_found += 2
+
+                REPORT: f"   ✓ {html_file} ({html_size} KB) + {css_file} ({css_size} KB)"
+            ELSE:
+                ERROR: f"   ✗ Missing files: {target}-style-{style_id}-layout-{layout_id}.*"
+
+        REPORT: f"  {target} × style-{style_id}: {agent_files_found}/{layout_variants * 2} files verified"
+
+IF total_found == total_expected:
+    REPORT: f"✅ Phase 2.5 complete: Verified all {total_expected} files"
+ELSE:
+    ERROR: f"⚠️ Only {total_found}/{total_expected} files found - some agents may have failed"
+```
+
+### Phase 3: Generate Preview Files
+
+```bash
+REPORT: "🌐 Phase 3: Generating preview files..."
+
+prototypes_dir = f"{base_path}/prototypes"
+
+# Template-based preview generation script
+# - Uses: ~/.claude/workflows/_template-compare-matrix.html
+# - Auto-detects: S, L, T from file patterns
+# - Generates: compare.html, index.html, PREVIEW.md
+Bash(~/.claude/scripts/ui-generate-preview-v2.sh "{prototypes_dir}")
+
+# Verify preview files generated
+preview_files = [
+    f"{base_path}/prototypes/compare.html",
+    f"{base_path}/prototypes/index.html",
+    f"{base_path}/prototypes/PREVIEW.md"
+]
+
+all_present = True
+FOR file_path IN preview_files:
+    IF exists(file_path):
+        REPORT: f"   ✓ Generated: {basename(file_path)}"
+    ELSE:
+        WARN: f"   ✗ Missing: {basename(file_path)}"
+        all_present = False
+
+IF all_present:
+    REPORT: "✅ Phase 3 complete: All preview files generated"
+ELSE:
+    WARN: "⚠️ Some preview files missing - script may need attention"
+```
+
+### Phase 4: Completion
+
+```javascript
+TodoWrite({todos: [
+  {content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
+  {content: `Gather layout inspiration for ${target_list.length} targets`, status: "completed", activeForm: "Gathering inspiration"},
+  {content: `Launch ${target_list.length}×${style_variants}=${target_list.length * style_variants} target-style agents (each handling ${layout_variants} layouts)`, status: "completed", activeForm: "Running target-style generation"},
+  {content: `Verify ${style_variants * layout_variants * target_list.length * 2} generated files`, status: "completed", activeForm: "Verifying files"},
+  {content: "Generate preview files (compare.html, index.html)", status: "completed", activeForm: "Generating previews"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Target-Style-Centric UI Generation Complete!
+
+Architecture: Target-Style-Centric Batch Generation
+
+Configuration:
+- Style Variants: {style_variants}
+- Layout Variants: {layout_variants} (inspiration-based)
+- Target Type: {target_type_icon} {target_type}
+- Targets: {target_list}
+- Total Prototypes: {style_variants * layout_variants * len(target_list)}
+
+Agent Execution:
+✅ Target-style agents: T×S = {len(target_list)}×{style_variants} = {len(target_list) * style_variants} agents
+✅ Each agent handles: L = {layout_variants} layouts for one component
+✅ Component isolation: Tasks completely independent
+
+Design Quality:
+✅ Style-Aware Structure: {IF design_space_analysis: 'YES - HTML adapts to design_attributes' ELSE: 'Standard semantic structure'}
+✅ Focused generation: Each agent handles single target × single style
+✅ Self-Contained CSS: Direct design token usage (no var() dependencies)
+
+Output Files:
+- Layout Inspirations: {len(target_list)} simple text files
+- HTML Prototypes: {style_variants * layout_variants * len(target_list)} files
+- CSS Files: {style_variants * layout_variants * len(target_list)} files
+- Preview Files: compare.html, index.html, PREVIEW.md
+
+Generated Structure:
+📂 {base_path}/prototypes/
+├── _inspirations/
+│   └── {target}-layout-ideas.txt ({len(target_list)} inspiration files)
+├── {target}-style-{s}-layout-{l}.html ({style_variants * layout_variants * len(target_list)} prototypes)
+├── {target}-style-{s}-layout-{l}.css
+├── compare.html (interactive S×L×T matrix)
+├── index.html (quick navigation)
+└── PREVIEW.md (usage instructions)
+
+🌐 Interactive Preview:
+1. Matrix View: Open compare.html (recommended)
+2. Quick Index: Open index.html
+3. Instructions: See PREVIEW.md
+
+{IF design_space_analysis:
+🎨 Style-Aware Generation Active:
+Each style's prototypes use structure adapted to design_attributes:
+- Density affects container nesting and whitespace
+- Visual weight affects wrapper layers and border structure
+- Same layout × same target × different style = DIFFERENT HTML trees!
+}
+
+Next: /workflow:ui-design:update {--session flag if applicable}
+
+Note: When called from /workflow:ui-design:explore-auto, design-update is triggered automatically.
+
+**Dynamic Values**: target_type_icon: "📄" for page, "🧩" for component
+```
+
+## Output Structure
+
+```
+{base_path}/prototypes/
+├── _inspirations/                                 # Layout inspiration only
+│   └── {target}-layout-ideas.txt                 # Simple inspiration text
+├── {target}-style-{s}-layout-{l}.html            # Final prototypes (S×L×T)
+├── {target}-style-{s}-layout-{l}.css
+├── compare.html                                   # Interactive matrix
+├── index.html                                     # Navigation page
+└── PREVIEW.md                                     # Instructions
+
+{base_path}/style-consolidation/
+├── style-1/ (design-tokens.json, style-guide.md)
+├── style-2/ (same structure)
+└── style-{S}/ (same structure)
+```
+
+## Error Handling
+
+### Pre-execution Checks
+- **No design systems found**: Error - Run `/workflow:ui-design:consolidate` first
+- **Invalid target names**: Extract from synthesis-specification.md or error with validation message
+- **Missing design-space-analysis.json**: WARN only - generation continues with basic structure
+- **Unsupported target type**: Error if target_type not in ["page", "component"]
+
+### Phase-Specific Errors
+- **Agent execution errors (Phase 2)**: Report details, identify which target × style agent failed
+- **Invalid design-tokens.json**: Check JSON format and structure
+- **Missing files (Phase 2.5)**: Indicates agent failed to write - review agent output logs
+- **MCP search errors (Phase 1.5)**: Check network connectivity, retry search
+- **Preview generation errors (Phase 3)**: Check script exists, permissions
+
+### Recovery Strategies
+- **Partial generation**: If some target-style agents succeed, you still have those prototypes
+- **Retry single combination**: Can re-run targeting failed target × style combination
+- **Missing design_attributes**: Generation works without them - just less style-aware
+- **Permission errors**: Run `chmod +x ~/.claude/scripts/ui-generate-preview-v2.sh`
+
+## Key Features
+
+1. **🚀 Target-Style-Centric Batch Generation**
+   Each agent handles L layouts for one target × one style with component isolation
+
+2. **🎯 Component Isolation**
+   Tasks completely independent, preventing cross-component interference
+
+3. **🎨 Style-Aware Structure Adaptation**
+   HTML DOM adapts based on design_attributes (density, visual_weight, organic_vs_geometric)
+
+4. **⚡ Performance Optimized**
+   Parallel execution of T×S agents with highly focused scope per agent
+
+5. **💡 Simplified Layout Inspiration**
+   Simple text-based research replaces complex JSON planning
+
+6. **🔧 Focused Agent Scope**
+   Each agent generates only L layouts, reducing complexity and improving quality
+
+7. **🎯 Self-Contained CSS Generation**
+   Agents read design-tokens.json and create independent CSS with direct token values (no var() references)
+
+8. **🌐 Interactive Visualization**
+   Full-featured compare.html with matrix grid
+
+9. **✅ Production-Ready Output**
+   Semantic HTML5, ARIA attributes, WCAG 2.2 compliant
+
+## Integration Points
+
+- **Input**: Per-style design-tokens.json; design-space-analysis.json (optional); targets + layout-variants
+- **Output**: S×L×T HTML/CSS prototypes with self-contained styling for `/workflow:ui-design:update`
+- **Auto Integration**: Triggered by `/workflow:ui-design:explore-auto`
+- **Backward Compatibility**: Works without design-space-analysis.json

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

@@ -0,0 +1,617 @@
+---
+name: generate
+description: Generate UI prototypes in matrix mode (style × layout combinations) for pages or components
+usage: /workflow:ui-design:generate [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+examples:
+  - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "dashboard,settings" --target-type "page" --style-variants 3 --layout-variants 3
+  - /workflow:ui-design:generate --session WFS-auth --targets "home,pricing" --target-type "page" --style-variants 2 --layout-variants 2
+  - /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533"  # ✅ Recommended: auto-detect variants
+  - /workflow:ui-design:generate --targets "navbar,hero,card" --target-type "component" --style-variants 3 --layout-variants 2
+  - /workflow:ui-design:generate --pages "home,dashboard" --style-variants 2 --layout-variants 2  # Legacy syntax
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
+---
+
+# UI Generation Command (Matrix Mode)
+
+**Executor**: → @ui-design-agent
+**Parallel Generation**: Phase 2a → @ui-design-agent (L×T tasks)
+
+## Overview
+Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix mode, strictly adhering to consolidated design tokens from separate style design systems. Supports both full-page layouts and isolated component generation.
+
+## Core Philosophy
+- **Unified Generation**: Single mode generating `style_variants × layout_variants × targets` prototypes
+- **Target Types**: Supports pages (full layouts) and components (isolated UI elements)
+- **Agent-Driven**: Uses `Task(ui-design-agent)` for parallel generation
+- **Token-Driven**: All styles reference per-style design-tokens.json; no hardcoded values
+- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
+- **Template-Based**: Decouples HTML structure from CSS styling for optimal performance
+- **Adaptive Wrapper**: All templates use complete HTML5 documents; body content adapts (full page structure for pages, isolated component for components)
+
+## Execution Protocol
+
+### Phase 1: Path Resolution & Context Loading
+
+```bash
+# 1. Determine base path
+IF --base-path: base_path = {provided_base_path}
+ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
+
+# 2. Determine style variant count and layout variant count
+style_variants = --style-variants OR 3; VALIDATE: 1 <= style_variants <= 5
+layout_variants = --layout-variants OR 3; VALIDATE: 1 <= layout_variants <= 5
+
+# Validate against actual style directories
+actual_style_count = count_directories({base_path}/style-consolidation/style-*)
+
+IF actual_style_count == 0:
+    ERROR: "No style directories found"; SUGGEST: "Run /workflow:ui-design:consolidate first"; EXIT 1
+
+IF style_variants > actual_style_count:
+    WARN: "⚠️ Requested {style_variants}, but only {actual_style_count} exist"
+    REPORT: "   Available styles: {list_directories}"; style_variants = actual_style_count
+
+REPORT: "✅ Validated style variants: {style_variants}"
+
+# 3. Enhanced target list parsing with type detection
+target_list = []; target_type = "page"  # Default
+
+# Priority 1: Unified --targets parameter
+IF --targets:
+    raw_targets = {--targets value}
+    target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
+    target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
+
+    target_type = --target-type provided ? {--target-type} : detect_target_type(target_list)
+    REPORT: "🎯 Using provided targets ({target_type}): {', '.join(target_list)}"
+
+# Priority 2: Legacy --pages parameter
+ELSE IF --pages:
+    raw_targets = {--pages value}
+    target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
+    target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
+    target_type = "page"
+    REPORT: "📋 Using provided pages (legacy): {', '.join(target_list)}"
+
+# Priority 3: Extract from synthesis-specification.md
+ELSE IF --session:
+    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+    target_list = extract_targets_from_synthesis(synthesis_spec); target_type = "page"
+    REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
+
+# Priority 4: Detect from existing prototypes or default
+ELSE:
+    target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]; target_type = "page"
+    REPORT: "📋 Detected/default targets: {', '.join(target_list)}"
+
+# 4. Validate target names
+validated_targets = [t for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
+invalid_targets = [t for t in target_list if t not in validated_targets]
+
+IF invalid_targets: REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}"
+VALIDATE: validated_targets not empty, "No valid targets found"
+target_list = validated_targets
+
+STORE: target_list, target_type
+
+# 5. Verify design systems exist
+FOR style_id IN range(1, style_variants + 1):
+    VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
+    VERIFY: exists({base_path}/style-consolidation/style-{style_id}/style-guide.md)
+
+# 6. Load requirements (if integrated mode)
+IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+```
+
+### Phase 1.5: Target-Specific Layout Planning
+
+```bash
+REPORT: "📐 Planning {layout_variants} layout strategies for each target..."
+
+CREATE: {base_path}/prototypes/_templates/
+
+# For each target, plan its specific layouts
+FOR target IN target_list:
+    REPORT: "  Planning layouts for '{target}' ({target_type})..."
+
+    FOR layout_id IN range(1, layout_variants + 1):
+        Task(ui-design-agent): "
+          [TARGET_LAYOUT_PLANNING]
+
+          TARGET: {target} | TARGET_TYPE: {target_type} | LAYOUT_ID: {layout_id}/{layout_variants}
+          BASE_PATH: {base_path}
+          {IF --session: PROJECT_REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
+
+          ## Task
+          Research {target} {target_type} layout variations → Select approach #{layout_id} → Generate layout plan JSON
+
+          ## Research
+          mcp__exa__web_search_exa(
+            query=\"common {target} {target_type} layout patterns variations best practices 2024\",
+            numResults=5
+          )
+          Identify multiple structural patterns → Select DISTINCT approach #{layout_id}
+
+          ## Output
+          Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json\", layout_plan_json)
+
+          ## JSON Structure
+          ```json
+          {
+            "id": "layout-{layout_id}",
+            "target": "{target}",
+            "target_type": "{target_type}",
+            "name": "Descriptive name (2-4 words)",
+            "description": "2-3 sentences",
+            "structure": {
+              // IF page: type, regions, grid, sidebar, responsive
+              // IF component: arrangement, alignment, spacing, element_order
+            },
+            "semantic_hints": [...],
+            "accessibility_features": [...],
+            "research_references": [...]
+          }
+          ```
+
+          ## Requirements
+          - Research-informed, structurally DIFFERENT from other layout IDs
+          - Write file directly (not text output)
+        "
+
+# Wait for all agent tasks to complete
+REPORT: "⏳ Waiting for layout planning agents to complete..."
+
+# Verify agent created layout JSON files
+REPORT: "📝 Verifying agent file creation..."
+
+FOR target IN target_list:
+    FOR layout_id IN range(1, layout_variants + 1):
+        layout_json_label = f"{target}-layout-{layout_id}.json"
+        json_path = f"{base_path}/prototypes/_templates/{layout_json_label}"
+
+        # Verify file exists
+        VERIFY: exists(json_path), f"Layout JSON not created by agent: {layout_json_label}"
+
+        # Validate JSON structure
+        TRY:
+            layout_json_content = Read(json_path)
+            layout_plan = JSON.parse(layout_json_content)
+
+            # Validate required fields
+            VALIDATE: layout_plan.id == f"layout-{layout_id}", f"Invalid layout ID in {layout_json_label}"
+            VALIDATE: layout_plan.target == target, f"Invalid target in {layout_json_label}"
+            VALIDATE: layout_plan.target_type == target_type, f"Invalid target_type in {layout_json_label}"
+            VALIDATE: layout_plan.name exists, f"Missing 'name' field in {layout_json_label}"
+            VALIDATE: layout_plan.structure exists, f"Missing 'structure' field in {layout_json_label}"
+
+            file_size = get_file_size(json_path)
+            REPORT: f"   ✓ Verified: {layout_json_label} - {layout_plan.name} ({file_size} KB)"
+        CATCH error:
+            ERROR: f"Validation failed for {layout_json_label}: {error}"
+            REPORT: f"   ⚠️ File exists but validation failed - review agent output"
+
+REPORT: f"✅ Phase 1.5 complete: Verified {len(target_list) × layout_variants} target-specific layout files"
+```
+
+### Phase 1.6: Convert Design Tokens to CSS
+
+```bash
+REPORT: "🎨 Converting design tokens to CSS variables..."
+
+# Check for jq dependency
+IF NOT command_exists("jq"):
+    ERROR: "jq is not installed or not in PATH. The conversion script requires jq."
+    REPORT: "Please install jq: macOS: brew install jq | Linux: apt-get install jq | Windows: https://stedolan.github.io/jq/download/"
+    EXIT 1
+
+# Convert design tokens to CSS for each style variant
+FOR style_id IN range(1, style_variants + 1):
+    tokens_json_path = "{base_path}/style-consolidation/style-${style_id}/design-tokens.json"
+    tokens_css_path = "{base_path}/style-consolidation/style-${style_id}/tokens.css"
+    script_path = "~/.claude/scripts/convert_tokens_to_css.sh"
+
+    # Verify input file exists
+    VERIFY: exists(tokens_json_path), f"Design tokens not found for style-{style_id}"
+
+    # Execute conversion: cat input.json | script.sh > output.css
+    Bash(cat "${tokens_json_path}" | "${script_path}" > "${tokens_css_path}")
+
+    # Verify output was generated
+    IF exit_code == 0 AND exists(tokens_css_path):
+        file_size = get_file_size(tokens_css_path)
+        REPORT: f"   ✓ Generated tokens.css for style-{style_id} ({file_size} KB)"
+    ELSE:
+        ERROR: f"Failed to generate tokens.css for style-{style_id}"
+        EXIT 1
+
+REPORT: f"✅ Phase 1.6 complete: Converted {style_variants} design token files to CSS"
+```
+
+### Phase 1.7: Extract Token Variable Names from CSS
+
+```bash
+REPORT: "📋 Extracting actual CSS variable names from tokens.css..."
+tokens_css_path = "{base_path}/style-consolidation/style-1/tokens.css"
+VERIFY: exists(tokens_css_path), "tokens.css not found. Phase 1.6 may have failed."
+
+tokens_css_content = Read(tokens_css_path)
+
+# Extract all CSS variable names from the generated file
+# Pattern: --variable-name: value;
+all_token_vars = extract_css_variables(tokens_css_content)  # Regex: r'--([a-z0-9-_]+):'
+
+# Categorize variables for better Agent understanding
+color_vars = [v for v in all_token_vars if v.startswith('--color-')]
+typography_vars = [v for v in all_token_vars if v.startswith(('--font-', '--line-height-', '--letter-spacing-'))]
+spacing_vars = [v for v in all_token_vars if v.startswith('--spacing-')]
+radius_vars = [v for v in all_token_vars if v.startswith('--border-radius-')]
+shadow_vars = [v for v in all_token_vars if v.startswith('--shadow-')]
+breakpoint_vars = [v for v in all_token_vars if v.startswith('--breakpoint-')]
+
+REPORT: f"✅ Extracted {len(all_token_vars)} actual CSS variables from tokens.css"
+REPORT: f"   Colors: {len(color_vars)} | Typography: {len(typography_vars)} | Spacing: {len(spacing_vars)}"
+```
+
+### Phase 2: Optimized Matrix UI Generation
+
+**Strategy**: Two-layer generation reduces complexity from `O(S×L×T)` to `O(L×T)`, achieving **`S` times faster** performance.
+
+- **Layer 1**: Generate `L × T` layout templates (HTML structure + structural CSS) by agent
+- **Layer 2**: Instantiate `S × L × T` final prototypes via fast file operations
+
+#### Phase 2a: Layout Template Generation
+
+**Parallel Executor**: → @ui-design-agent
+
+```bash
+CREATE: {base_path}/prototypes/_templates/
+CREATE: {base_path}/prototypes/
+
+# Launch parallel template generation tasks → @ui-design-agent
+# Total agent tasks: layout_variants × len(target_list)
+FOR layout_id IN range(1, layout_variants + 1):
+    FOR target IN target_list:
+        # Read the target-specific layout plan
+        layout_json_path = f"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json"
+        layout_plan = Read(layout_json_path)
+
+        Task(ui-design-agent): "
+          [UI_LAYOUT_TEMPLATE_GENERATION]
+
+          🚨 TARGET INDEPENDENCE: Generate template for EXACTLY ONE target: '{target}' (standalone, reusable)
+
+          LAYOUT_ID: {layout_id} | TARGET: {target} | TARGET_TYPE: {target_type}
+          BASE_PATH: {base_path}
+          {IF --session: REQUIREMENTS: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
+
+          ## Layout Plan to Implement
+          **Path**: {layout_json_path}
+          **Plan**: {JSON.stringify(layout_plan, null, 2)}
+
+          ## Task
+          Generate TWO template files implementing the layout plan:
+          - HTML: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.html
+          - CSS: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.css
+
+          ## HTML Requirements
+          - Complete HTML5 document (<!DOCTYPE>, <html>, <head>, <body>)
+          - Semantic elements + ARIA attributes
+          - Body content:
+            * IF page → Full structure (header, nav, main, footer)
+            * IF component → Isolated element in presentation wrapper
+          - ⚠️ CRITICAL CSS placeholders in <head>:
+            <link rel=\"stylesheet\" href=\"{{STRUCTURAL_CSS}}\">
+            <link rel=\"stylesheet\" href=\"{{TOKEN_CSS}}\">
+
+          ## CSS Requirements - Token Reference
+
+          **1. Read tokens.css**
+          Read(\"{base_path}/style-consolidation/style-1/tokens.css\")
+          Extract all CSS variable names (pattern: lines with \"  --\" in \":root {}\")
+
+          **2. Available Tokens**
+          - Colors: {', '.join(color_vars[:5])}... ({len(color_vars)} total)
+          - Typography: {', '.join(typography_vars[:5])}... ({len(typography_vars)} total)
+          - Spacing: {', '.join(spacing_vars[:5])}... ({len(spacing_vars)} total)
+          - Radius: {', '.join(radius_vars[:3])}... ({len(radius_vars)} total)
+          - Shadows: {', '.join(shadow_vars)}
+
+          **3. Variable Usage Rules**
+          - ✅ Use ONLY variables from tokens.css (exact names)
+          - ✅ Format: var(--exact-name-from-file)
+          - ❌ NO invented/guessed variable names
+          - ❌ NO hardcoded values (colors, fonts, spacing)
+
+          **4. Optional Extension**
+          If core tokens insufficient → Create `{target}-layout-{layout_id}-tokens.css` with `--layout-*` prefix
+          Examples: `--layout-spacing-navbar-height`, `--layout-size-sidebar-width`
+
+          **CSS Scope**: Structural layout only (Flexbox, Grid, positioning)
+          **Responsive**: Mobile-first approach
+
+          ## Write Operations
+          Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.html\", html_content)
+          Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.css\", css_content)
+
+          Report completion with file paths. Write files directly (not text output).
+        "
+
+REPORT: "⏳ Phase 2a: Waiting for agents to complete template generation..."
+```
+
+#### Phase 2a.5: Verify Agent Template File Creation
+
+```bash
+REPORT: "📝 Phase 2a.5: Verifying agent template file creation..."
+
+# Verify each agent created template files
+FOR layout_id IN range(1, layout_variants + 1):
+    FOR target IN target_list:
+        html_label = f"{target}-layout-{layout_id}.html"
+        css_label = f"{target}-layout-{layout_id}.css"
+
+        html_path = f"{base_path}/prototypes/_templates/{html_label}"
+        css_path = f"{base_path}/prototypes/_templates/{css_label}"
+
+        # Verify files exist
+        VERIFY: exists(html_path), f"HTML template not created by agent: {html_label}"
+        VERIFY: exists(css_path), f"CSS template not created by agent: {css_label}"
+
+        # Validate content
+        TRY:
+            html_content = Read(html_path)
+            css_content = Read(css_path)
+
+            # Basic validation checks
+            VALIDATE: len(html_content) > 100, f"HTML template too short: {html_label}"
+            VALIDATE: len(css_content) > 50, f"CSS template too short: {css_label}"
+            VALIDATE: "<!DOCTYPE html>" in html_content, f"Invalid HTML structure: {html_label}"
+            VALIDATE: "var(--" in css_content, f"Missing CSS variables: {css_label}"
+
+            html_size = get_file_size(html_path)
+            css_size = get_file_size(css_path)
+            REPORT: f"   ✓ Verified: {html_label} ({html_size} KB) + {css_label} ({css_size} KB)"
+        CATCH error:
+            ERROR: f"Validation failed for {target}-layout-{layout_id}: {error}"
+            REPORT: f"   ⚠️ Files exist but validation failed - review agent output"
+
+REPORT: "✅ Phase 2a.5 complete: Verified {layout_variants * len(target_list) * 2} template files"
+```
+
+#### Phase 2b: Prototype Instantiation
+
+```bash
+REPORT: "🚀 Phase 2b: Instantiating prototypes from templates..."
+
+# Verify tokens.css files exist (should be created in Phase 1.6)
+FOR style_id IN range(1, style_variants + 1):
+    tokens_css_path = "{base_path}/style-consolidation/style-${style_id}/tokens.css"
+    VERIFY: exists(tokens_css_path), f"tokens.css missing for style-{style_id}. Phase 1.6 may have failed."
+
+REPORT: "   ✓ Verified {style_variants} tokens.css files exist"
+
+# Use ui-instantiate-prototypes.sh script for instantiation
+prototypes_dir = "{base_path}/prototypes"
+targets_csv = ','.join(target_list)
+session_id = --session provided ? {session_id} : "standalone"
+
+# Execute instantiation script with target type
+Bash(~/.claude/scripts/ui-instantiate-prototypes.sh "{prototypes_dir}" --session-id "{session_id}" --mode "{target_type}")
+
+# The script auto-detects: Targets, Style variants, Layout variants
+# The script generates:
+# 1. S × L × T HTML prototypes with CSS links
+# 2. Implementation notes for each prototype
+# 3. compare.html (interactive matrix)
+# 4. index.html (navigation page)
+# 5. PREVIEW.md (documentation)
+
+REPORT: "✅ Phase 2b complete: Instantiated {style_variants * layout_variants * len(target_list)} final prototypes"
+REPORT: "   Mode: {target_type} | Performance: {style_variants}× faster than original approach"
+```
+
+### Phase 3: Verify Preview Files
+
+```bash
+REPORT: "🔍 Phase 3: Verifying preview files..."
+
+expected_files = ["{base_path}/prototypes/compare.html", "{base_path}/prototypes/index.html", "{base_path}/prototypes/PREVIEW.md"]
+
+all_present = true
+FOR file_path IN expected_files:
+    IF exists(file_path): REPORT: "   ✓ Found: {basename(file_path)}"
+    ELSE: REPORT: "   ✗ Missing: {basename(file_path)}"; all_present = false
+
+IF all_present: REPORT: "✅ Phase 3 complete: All preview files verified"
+ELSE: WARN: "⚠️ Some preview files missing - script may have failed"
+
+# Optional: Generate fallback design-tokens.css for reference
+fallback_css_path = "{base_path}/prototypes/design-tokens.css"
+IF NOT exists(fallback_css_path):
+    Write(fallback_css_path, "/* Auto-generated fallback CSS custom properties */\n/* See style-consolidation/style-{n}/tokens.css for actual values */")
+    REPORT: "   ✓ Generated fallback design-tokens.css"
+```
+
+### Phase 3.5: Cross-Target Consistency Validation
+
+**Condition**: Only executes if `len(target_list) > 1 AND target_type == "page"`
+
+```bash
+# Skip if single target or component mode
+IF len(target_list) <= 1 OR target_type == "component": SKIP to Phase 4
+
+# For multi-page workflows, validate cross-page consistency → @ui-design-agent
+FOR style_id IN range(1, style_variants + 1):
+    FOR layout_id IN range(1, layout_variants + 1):
+        Task(@ui-design-agent): "
+          [CROSS_PAGE_CONSISTENCY_VALIDATION]
+
+          STYLE: {style_id} | LAYOUT: {layout_id} | TARGETS: {target_list} | TYPE: {target_type}
+          BASE_PATH: {base_path}
+
+          ## Input
+          {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html/css (all targets)
+
+          ## Validate
+          1. Shared components (header/nav/footer)
+          2. Token usage (no hardcoded values)
+          3. Accessibility (ARIA, headings, landmarks)
+          4. Layout strategy consistency
+
+          ## Output
+          Write({base_path}/prototypes/consistency-report-s{style_id}-l{layout_id}.md, validation_report)
+
+          Focus on shared elements. Page-specific variations acceptable.
+        "
+
+# Aggregate consistency reports
+Write({base_path}/prototypes/CONSISTENCY_SUMMARY.md):
+# Multi-{target_type.capitalize()} Consistency Summary
+
+## Validated Combinations
+- Style Variants: {style_variants} | Layout Variants: {layout_variants}
+- Total Reports: {style_variants * layout_variants}
+
+## Report Files
+{FOR s, l: - [Style {s} Layout {l}](./consistency-report-s{s}-l{l}.md)}
+
+Run `/workflow:ui-design:update` once all issues are resolved.
+```
+
+### Phase 4: Completion
+
+```javascript
+TodoWrite({todos: [
+  {content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
+  {content: `Plan ${target_list.length}×${layout_variants} target-specific layouts`, status: "completed", activeForm: "Planning layouts"},
+  {content: `Convert ${style_variants} design token files to CSS`, status: "completed", activeForm: "Converting tokens to CSS"},
+  {content: "Extract CSS variable names from tokens.css", status: "completed", activeForm: "Extracting variable names"},
+  {content: `Generate ${layout_variants}×${target_list.length} layout templates (agent reads tokens.css)`, status: "completed", activeForm: "Generating templates"},
+  {content: `Instantiate ${style_variants}×${layout_variants}×${target_list.length} prototypes using script`, status: "completed", activeForm: "Running script"},
+  {content: "Verify preview files generation", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Optimized Matrix UI generation complete!
+
+Configuration:
+- Style Variants: {style_variants}
+- Layout Variants: {layout_variants} (target-specific planning)
+- Target Type: {target_type_icon} {target_type}
+- Targets: {target_list}
+- Total Prototypes: {style_variants * layout_variants * len(target_list)}
+- Layout Plans: {len(target_list) × layout_variants} target-specific JSON files generated
+
+Performance Metrics:
+- Layout Templates Generated: {layout_variants * len(target_list)} (Agent tasks)
+- Prototypes Instantiated: {style_variants * layout_variants * len(target_list)} (script-based)
+- Preview Files: compare.html, index.html, PREVIEW.md (auto-generated)
+- Speed Improvement: {style_variants}× faster than previous approach
+- Resource Efficiency: {100 * (1 - 1/style_variants)}% reduction in Agent calls
+- Script: ui-instantiate-prototypes.sh v3.0 with auto-detection
+
+Generated Structure:
+📂 {base_path}/prototypes/
+├── _templates/
+│   ├── {target}-layout-{l}.json ({len(target_list) × layout_variants} layout plans)
+│   ├── {target}-layout-{l}.html ({layout_variants * len(target_list)} HTML templates)
+│   └── {target}-layout-{l}.css ({layout_variants * len(target_list)} CSS templates)
+├── {target}-style-{s}-layout-{l}.html ({style_variants * layout_variants * len(target_list)} final prototypes)
+├── {target}-style-{s}-layout-{l}-notes.md
+├── compare.html (interactive matrix visualization)
+└── index.html (quick navigation)
+
+🌐 Interactive Preview:
+1. Matrix View: Open compare.html (recommended)
+2. Quick Index: Open index.html
+3. Instructions: See PREVIEW.md
+
+{IF target_type == "component": Note: Components use complete HTML5 documents with isolated body content for better comparison and styling.}
+
+Next: /workflow:ui-design:update {--session flag if applicable}
+
+Note: When called from /workflow:ui-design:auto, design-update is triggered automatically.
+
+**Dynamic Values**: target_type_icon: "📄" for page, "🧩" for component
+```
+
+## Output Structure
+
+```
+{base_path}/prototypes/
+├── _templates/                            # Target-specific layout plans and templates
+│   ├── {target}-layout-1.json            # Layout plan JSON (target-specific)
+│   ├── {target}-layout-1.html            # Style-agnostic HTML structure
+│   ├── {target}-layout-1.css             # Structural CSS with var() references
+│   └── ... (T × L layout plans + templates)
+├── compare.html                           # Interactive matrix visualization
+├── index.html                             # Simple navigation page
+├── PREVIEW.md                             # Preview instructions
+├── design-tokens.css                      # CSS custom properties fallback
+├── {target}-style-{s}-layout-{l}.html    # Final prototypes (copied from templates)
+├── {target}-style-{s}-layout-{l}-notes.md  # Implementation notes
+└── ... (S × L × T total final files)
+
+{base_path}/style-consolidation/
+├── style-1/ (design-tokens.json, tokens.css, style-guide.md)
+├── style-2/ (same structure)
+└── ...
+```
+
+## Error Handling
+
+### Pre-execution Checks
+- **No design systems found**: Error - Run `/workflow:ui-design:consolidate` first
+- **Invalid target names**: Extract from synthesis-specification.md or error with validation message
+- **Missing templates directory**: Auto-created in Phase 1.5
+- **Unsupported target type**: Error if target_type not in ["page", "component"]
+- **Layout planning failures**: Check Phase 1.5 agent outputs for errors
+
+### Phase-Specific Errors
+- **Agent execution errors (Phase 2a)**: Report details, suggest retry with specific phase
+- **Token conversion errors (Phase 2b)**: Check design-tokens.json format, validate JSON schema
+- **Script execution errors (Phase 2b)**: Check script exists, permissions, output for specific errors
+- **Preview generation errors (Phase 3)**: Check script completed, verify template exists, review Phase 2b output
+
+### Recovery Strategies
+- **Partial failure**: Script reports generated vs failed counts - review logs
+- **Missing templates**: Indicates Phase 2a issue - regenerate templates
+- **Auto-detection failures**: Use manual mode with explicit parameters
+- **Permission errors**: Run `chmod +x ~/.claude/scripts/ui-instantiate-prototypes.sh`
+
+## Quality Checks
+
+After generation, ensure:
+- [ ] All CSS values reference design token custom properties
+- [ ] No hardcoded colors, spacing, or typography
+- [ ] Semantic HTML structure with proper element hierarchy
+- [ ] ARIA attributes present for accessibility
+- [ ] Responsive design implemented with mobile-first approach
+- [ ] File naming follows `{target}-style-{s}-layout-{l}` convention
+- [ ] compare.html loads correctly with all prototypes
+- [ ] Template files are reusable and style-agnostic
+- [ ] All templates use complete HTML5 documents with appropriate body content (full structure for pages, isolated component for components)
+
+## Key Features
+
+1. **Target-Specific Layout Planning** 🆕 - Each target gets custom-designed layouts; Agent researches modern patterns using MCP tools; Layout plans saved as structured JSON
+2. **Unified Target Generation** - Supports both pages (full layouts) and components (isolated elements); Backward compatible with legacy `--pages` parameter
+3. **Optimized Template-Based Architecture** - Generates `L × T` reusable templates plus `L × T` layout plans; **`S` times faster**
+4. **Three-Layer Generation Strategy** - Layer 1: Layout planning (target-specific); Layer 2: Template generation (implements plans); Layer 3: Fast instantiation; Agent autonomously uses MCP tools
+5. **Script-Based Instantiation (v3.0)** - Uses `ui-instantiate-prototypes.sh` for efficient file operations; Auto-detection; Robust error handling; Integrated preview generation; Supports both page and component modes
+6. **Consistent Cross-Style Layouts** - Same layout structure applied uniformly; Easier to compare styles; Simplified maintenance
+7. **Dynamic Style Injection** - CSS custom properties enable runtime style switching; Each style variant has its own `tokens.css` file
+8. **Interactive Visualization** - Full-featured compare.html; Matrix grid view with synchronized scrolling; Enhanced index.html with statistics; Comprehensive PREVIEW.md
+9. **Production-Ready Output** - Semantic HTML5 and ARIA attributes (WCAG 2.2); Mobile-first responsive design; Token-driven styling; Implementation notes
+
+## Integration Points
+
+- **Input**: Per-style `design-tokens.json` from `/workflow:ui-design:consolidate`; `--targets` and `--layout-variants` parameters; Optional: `synthesis-specification.md` for target requirements; Target type specification
+- **Output**: Target-specific `layout-{n}.json` files; Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
+- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow
+- **Key Change**: Layout planning moved from consolidate to generate phase; Each target gets custom-designed layouts
+- **Backward Compatibility**: Legacy `--pages` parameter continues to work

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

@@ -0,0 +1,436 @@
+---
+name: imitate-auto
+description: Imitation-focused UI design workflow - Rapidly replicate a single design style from URL or images (skip exploration, direct to implementation)
+usage: /workflow:ui-design:imitate-auto [--url "<url>"] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>]
+examples:
+  - /workflow:ui-design:imitate-auto --url "https://linear.app" --targets "home,features,pricing"
+  - /workflow:ui-design:imitate-auto --images "refs/design.png" --prompt "Imitate this minimalist design for dashboard and settings"
+  - /workflow:ui-design:imitate-auto --url "https://stripe.com" --session WFS-payment
+  - /workflow:ui-design:imitate-auto --images "refs/*.png" --targets "home"
+  - /workflow:ui-design:imitate-auto --url "https://example.com" --targets "navbar,hero" --target-type "component"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*)
+---
+
+# UI Design Imitate-Auto Workflow Command
+
+## Overview & Philosophy
+
+**Fast-track UI imitation workflow**: Replicates a single design style from reference source (URL or images), bypassing exploration and consolidation phases for maximum speed (~2-3× faster than explore-auto).
+
+**Core Philosophy**:
+- **Imitation over Exploration**: Focus on replicating specific design, not generating variants
+- **Single Mode**: Always 1 style × 1 layout × N targets
+- **Speed Optimized**: Bypasses `consolidate` step via direct token extraction
+- **Reference-Driven**: Requires URL or images as primary input
+- **Auto-Screenshot**: Supports Playwright/Chrome with manual upload fallback
+
+**Streamlined Flow**: Phase 0 (init) → 0.5 (screenshot) → 0.75 (URL analysis if needed) → 1 (extraction) → 2 (token adapt) → 3 (generate) → 4 (integrate)
+
+**Performance**: ~2-3× faster than explore-auto for single-style scenarios
+
+**Ideal For**: MVP development, high-fidelity prototyping, design replication, studying successful patterns
+
+## Key Features
+
+- **Fast-Track Imitation**: ~2-3× faster than explore-auto by bypassing consolidation phase
+- **Reference-Driven**: Requires URL or images as primary design source for accurate replication
+- **Auto-Screenshot Capability**: Intelligent fallback (Playwright → Chrome → Manual upload) for URL-based workflows
+- **Single-Style Focus**: Always generates 1 style × 1 layout × N targets for streamlined execution
+- **Consolidation Bypass**: Direct design token extraction saves 30-60s per workflow
+- **Interactive Confirmation**: User validates inferred targets before execution to prevent mistakes
+- **Flexible Target Types**: Supports both full-page layouts and isolated UI components
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 0 execution
+2. **No Multi-Variant**: Always 1 style × 1 layout × N targets
+3. **Reference Required**: Must provide `--url` OR `--images`
+4. **Auto-Continue**: Automatic phase progression without pausing
+5. **Track Progress**: Update TodoWrite after each phase
+
+## Parameter Requirements
+
+**Required Parameters** (at least one must be provided):
+- `--url "<url>"`: Reference website URL for style imitation (supports auto-screenshot)
+- `--images "<glob>"`: Reference image paths (e.g., `refs/*.png`, `design-refs/*.jpg`)
+
+**Optional Parameters** (all have smart defaults):
+- `--targets "<list>"`: Comma-separated targets (pages/components) to generate
+  - Examples: `"home,dashboard"`, `"navbar,hero,card"`
+  - If omitted: inferred from `--prompt` or defaults to `["home"]`
+- `--target-type "page|component"`: Explicitly set target type
+  - `page`: Full-page layouts with complete structure
+  - `component`: Isolated UI elements with minimal wrapper
+  - Default: intelligent detection based on target names
+- `--session <id>`: Workflow session ID (e.g., `WFS-ecommerce`)
+  - If provided: integrates with session brainstorming artifacts
+  - If omitted: runs in standalone mode
+- `--prompt "<description>"`: Design guidance and target hints
+  - Used for target inference and style extraction refinement
+  - Examples: `"Imitate dark mode for dashboard"`, `"Focus on minimalist design"`
+
+**Legacy Parameters** (maintained for backward compatibility):
+- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
+
+**Not Supported** (use `/workflow:ui-design:explore-auto` instead):
+- `--style-variants`, `--layout-variants`, `--batch-plan`
+
+**Input Rules**:
+- Must provide at least one: `--url` OR `--images`
+- Multiple parameters can be combined for guided imitation
+- If `--targets` not provided, intelligently inferred from prompt or defaults to `["home"]`
+- URL and images can be used together (screenshot + additional references)
+
+**Supported Target Types**:
+- **Pages** (full layouts): home, dashboard, settings, profile, login, pricing, etc.
+- **Components** (UI elements):
+  - Navigation: navbar, header, menu, sidebar, tabs
+  - Content: hero, card, list, table, gallery
+  - Input: form, search, filter, button
+  - Feedback: modal, alert, toast, badge
+  - Other: footer, dropdown, avatar, pagination
+
+## 5-Phase Execution
+
+### Phase 0: Simplified Initialization
+
+```bash
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation/style-1,prototypes}")
+
+# Metadata
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "workflow": "ui-design:imitate-auto", "mode": "single_style_imitation",
+  "parameters": {"url": "${url_value}", "images": "${images_pattern}", "targets": "${target_list}", "prompt": "${prompt_text}"},
+  "status": "in_progress"
+}
+
+# Unified target inference (no interactive confirmation)
+target_list = []; target_type = "page"; target_source = "none"
+
+# Priority: --pages (legacy) → --targets → --prompt → default
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets)
+    target_type = --target-type ? --target-type : detect_target_type(target_list)
+    target_source = "explicit"
+ELSE IF --prompt:
+    target_list = extract_targets_from_prompt(prompt_text) OR ["home"]
+    target_type = --target-type ? --target-type : detect_target_type(target_list)
+    target_source = "prompt_inferred"
+ELSE:
+    target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [t.strip().lower().replace(" ", "-") for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+
+type_emoji = "📄" IF target_type == "page" ELSE "🧩"
+type_label = "pages" IF target_type == "page" ELSE "components"
+
+# Interactive confirmation
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "⚡ IMITATE MODE CONFIRMATION"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Reference: {url_value OR images_pattern}"
+  "Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+user_input = WAIT_FOR_USER_INPUT()
+
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  default → proceed with current list
+
+REPORT: "✅ Confirmed: {len(validated_targets)} {type_label} with single style"
+REPORT: "   {type_emoji} Targets: {', '.join(validated_targets)} | Type: {target_type} | Reference: {url_value OR images_pattern}"
+
+STORE: run_id, base_path, inferred_target_list = validated_targets, target_type
+```
+
+**Helper Function: detect_target_type()**
+```bash
+detect_target_type(target_list):
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", "pricing", "about", "contact", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", "modal", "alert", "dropdown", ...]
+
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget", "element"])
+
+    RETURN "component" IF component_matches > page_matches ELSE "page"
+```
+
+### Phase 0.5: URL Screenshot Capture (Auto-Fallback)
+
+**Condition**: Only if `--url` provided
+
+```bash
+IF --url:
+    screenshot_dir = "{base_path}/screenshots"; Bash(mkdir -p "{screenshot_dir}")
+    screenshot_success = false; screenshot_files = []
+
+    # Try Playwright → Chrome → Manual fallback
+    TRY: Bash(npx playwright screenshot "{url_value}" "{screenshot_dir}/full-page.png" --full-page --timeout 30000)
+         screenshot_files.append("{screenshot_dir}/full-page.png"); screenshot_success = true
+         REPORT: "   ✅ Playwright screenshot captured"
+    CATCH: REPORT: "   ⚠️ Playwright failed"
+
+    IF NOT screenshot_success:
+        TRY: Bash(google-chrome --headless --disable-gpu --screenshot="{screenshot_dir}/full-page.png" --window-size=1920,1080 "{url_value}")
+             screenshot_files.append("{screenshot_dir}/full-page.png"); screenshot_success = true
+             REPORT: "   ✅ Chrome screenshot captured"
+        CATCH: REPORT: "   ⚠️ Chrome failed"
+
+    # Manual upload fallback
+    IF NOT screenshot_success:
+        REPORT: "━━━ ⚠️ AUTOMATED SCREENSHOT FAILED ━━━"
+        REPORT: "Unable to capture: {url_value}"
+        REPORT: "Manual screenshot required:"
+        REPORT: "  1. Visit: {url_value} | 2. Take full-page screenshot | 3. Save to: {screenshot_dir}/"
+        REPORT: "Options: 'ready' (screenshot saved) | 'skip' (URL only) | 'abort' (cancel)"
+        REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+          "ready|done|ok" → screenshot_files = Glob("{screenshot_dir}/*.{png,jpg,jpeg}");
+                            IF screenshot_files: screenshot_success = true; REPORT: "✅ Manual screenshot detected"
+                            ELSE: REPORT: "❌ No screenshot found, using URL analysis only"
+          "skip" → REPORT: "⏭️ Skipping screenshot, using URL analysis"
+          "abort" → ERROR: "Workflow aborted by user"; EXIT
+          _ → REPORT: "⚠️ Invalid input, proceeding with URL analysis"
+
+    # Store results
+    STORE: screenshot_mode = screenshot_success ? "with_screenshots" : "url_only", screenshot_paths = screenshot_files
+    REPORT: screenshot_success ? "✅ Screenshot capture complete: {len(screenshot_files)} image(s)" : "ℹ️ Proceeding with URL analysis only"
+ELSE:
+    STORE: screenshot_mode = "manual_images", screenshot_paths = []
+    REPORT: "ℹ️ Using provided images (--images parameter)"
+```
+
+### Phase 0.75: URL Content Analysis (Fallback Mode)
+
+**Condition**: Only if `screenshot_mode == "url_only"`
+
+```bash
+url_analysis_content = ""
+
+IF screenshot_mode == "url_only":
+    REPORT: "🔍 Analyzing URL content (no screenshot available)"
+
+    # Fetch URL design patterns using MCP web search
+    url_analysis_content = mcp__exa__web_search_exa(
+        query="site:{url_value} design style color scheme layout",
+        numResults=3
+    )
+
+    STORE: url_analysis_data = url_analysis_content
+    REPORT: "✅ URL content analysis complete"
+```
+
+### Phase 1: Single Style Extraction
+
+```bash
+# Determine input based on screenshot capture
+source_desc = screenshot_mode == "with_screenshots" ? "captured screenshots from {url_value}" :
+              screenshot_mode == "url_only" ? "URL analysis of {url_value}" : "user-provided images"
+
+images_flag = screenshot_mode == "with_screenshots" ? "--images \"{base_path}/screenshots/*.{png,jpg,jpeg}\"" :
+              screenshot_mode == "manual_images" AND --images ? "--images \"{image_glob}\"" : ""
+
+url_flag = screenshot_mode == "url_only" ? "--url \"{url_value}\"" : ""
+
+# Construct optimized extraction prompt with URL analysis data
+url_context = screenshot_mode == "url_only" ? "URL analysis data: {url_analysis_data}" : ""
+enhanced_prompt = "Extract a single, high-fidelity design system that accurately imitates the visual style from {source_desc}. {url_context} {prompt_text}"
+
+# Force single variant with imitate mode
+command = "/workflow:ui-design:extract --base-path \"{base_path}\" {url_flag} {images_flag} --prompt \"{enhanced_prompt}\" --mode imitate"
+
+REPORT: "🚀 Phase 1: Style Extraction | Source: {source_desc} | Mode: imitate (high-fidelity)"
+
+SlashCommand(command)  # → Phase 2
+```
+
+### Phase 2: Fast Token Adaptation (Bypass Consolidate)
+
+```bash
+REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate)"
+
+# Note: Orchestrator directly reads and transforms files here (not delegating to agent)
+# This is a performance optimization to bypass the full consolidate phase
+style_cards = Read({base_path}/style-extraction/style-cards.json)
+style_card = style_cards.style_cards[0]
+
+design_tokens = style_card.proposed_tokens
+philosophy = style_card.design_philosophy
+style_name = style_card.name
+
+# Write design-tokens.json directly (orchestrator-level file transformation)
+Write({base_path}/style-consolidation/style-1/design-tokens.json, JSON.stringify(design_tokens, null, 2))
+
+# Create minimal style-guide.md
+Write({base_path}/style-consolidation/style-1/style-guide.md):
+# Design System: {style_name}
+
+## Design Philosophy
+{philosophy}
+
+## Description
+{style_card.description}
+
+## Design Tokens
+All tokens in `design-tokens.json` follow OKLCH color space.
+
+**Key Colors**: Primary: {design_tokens.colors.brand.primary} | Background: {design_tokens.colors.surface.background} | Text: {design_tokens.colors.text.primary}
+
+**Typography**: Heading: {design_tokens.typography.font_family.heading} | Body: {design_tokens.typography.font_family.body}
+
+**Spacing Scale**: {design_tokens.spacing.keys().length} values
+
+*Note: Generated in imitate mode for fast replication.*
+
+REPORT: "✅ Tokens extracted and formatted | Style: {style_name} | Bypassed consolidate for {performance_gain}× speed"
+```
+
+### Phase 3: Single Prototype Generation
+
+```bash
+targets_string = ",".join(inferred_target_list)
+type_emoji = "📄" IF target_type == "page" ELSE "🧩"
+type_label = "page(s)" IF target_type == "page" ELSE "component(s)"
+
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" --targets \"{targets_string}\" --target-type \"{target_type}\" --style-variants 1 --layout-variants 1"
+
+REPORT: "🚀 Phase 3: Generating {len(inferred_target_list)} {type_label}"
+REPORT: "   {type_emoji} Targets: {targets_string} | Mode: 1×1 (imitation-optimized)"
+
+SlashCommand(command)  # → Phase 4
+
+# Output: Prototypes: {target}-style-1-layout-1.html, Total: len(inferred_target_list), Type: {target_type}
+```
+
+### Phase 4: Design System Integration
+
+```bash
+IF --session:
+    SlashCommand("/workflow:ui-design:update --session {session_id}")  # → Complete
+ELSE:
+    REPORT: "ℹ️ Standalone mode: Skipping integration | Prototypes at: {base_path}/prototypes/"
+    # → Complete (standalone)
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize
+TodoWrite({todos: [
+  {"content": "Initialize run directory and infer targets", "status": "in_progress", "activeForm": "Initializing"},
+  {"content": "Capture screenshots from URL (if provided)", "status": "pending", "activeForm": "Capturing screenshots"},
+  {"content": "Analyze URL content (fallback mode)", "status": "pending", "activeForm": "Analyzing URL content"},
+  {"content": "Extract single design style from reference", "status": "pending", "activeForm": "Extracting style"},
+  {"content": "Adapt tokens (bypass consolidate)", "status": "pending", "activeForm": "Adapting tokens"},
+  {"content": "Generate single-style prototypes", "status": "pending", "activeForm": "Generating prototypes"},
+  {"content": "Integrate design system", "status": "pending", "activeForm": "Integrating design"}
+]})
+
+// Update after each phase: Mark current completed, next in_progress
+```
+
+## Error Handling
+
+- **No reference source**: Error if neither `--url` nor `--images` provided
+- **Screenshot capture failure**: Tries Playwright → Chrome → Manual upload (user uploads, skips, or aborts); gracefully handles missing tools
+- **Invalid URL/images**: Report error, suggest alternative input
+- **Token extraction failure**: Fallback to minimal default design system
+
+## Performance Comparison
+
+| Aspect | explore-auto | imitate-auto |
+|--------|--------------|--------------|
+| **Purpose** | Design exploration | Design replication |
+| **Input** | Optional URL/images | **Required** URL or images |
+| **Variants** | 1-5 styles × 1-5 layouts | Always 1 × 1 |
+| **Consolidate** | Full consolidation | **Bypassed** (direct tokens) |
+| **Speed** | Baseline | **~2-3× faster** |
+| **Output** | Matrix (S×L×T) | Direct (1×1×T) |
+
+**Performance Benefits**: Skipped consolidate (~30-60s saved), single variant, direct token mapping, streamlined decisions
+
+## Example Execution Flows
+
+### Example 1: URL with Auto-Screenshot (Pages)
+```bash
+/workflow:ui-design:imitate-auto --url "https://linear.app" --targets "home,features,pricing"
+
+# Flow: 0 (3 pages) → 0.5 (Playwright captures) → 1 (single style) → 2 (direct tokens ~2s vs ~45s) → 3 (3 prototypes) → 4
+# Time: ~2-3 min (vs 5-7 min with explore-auto)
+```
+
+### Example 2: Images with Guidance (Page Mode)
+```bash
+/workflow:ui-design:imitate-auto --images "refs/dark-theme.png" --prompt "Focus on dark mode" --targets "dashboard"
+
+# Flow: 0 → 0.5 (skip) → 1 → 2 → 3 → 4
+# Output: dashboard-style-1-layout-1.html | Type: page (full-page layout)
+```
+
+### Example 3: Component Mode
+```bash
+/workflow:ui-design:imitate-auto --url "https://example.com" --targets "navbar,hero,card" --target-type "component"
+
+# Flow: 0 → 0.5 → 1 → 2 → 3 → 4
+# Output: navbar/hero/card-style-1-layout-1.html | Type: component (minimal wrapper)
+```
+
+### Example 4: URL with Manual Screenshot
+```bash
+/workflow:ui-design:imitate-auto --url "https://stripe.com/pricing" --targets "pricing"
+
+# 0.5: Playwright failed → Chrome failed → User prompted → types 'ready' → ✅ continues OR 'skip' → ⚠️ URL only
+# If skip: 0.75 (MCP URL analysis) → 1 → 2 → 3 → 4
+# If ready: 1 → 2 → 3 → 4
+```
+
+## Completion Output
+
+```
+✅ UI Design Imitation Complete!
+
+Mode: Single Style Replication | Run ID: {run_id} | Session: {session_id or "standalone"} | Reference: {url OR images} | Type: {type_emoji} {type_label}
+
+Phase 0 - Initialization: {target_count} {target_type}(s) prepared
+Phase 0.5 - Screenshot Capture: {screenshot_status}
+  {IF success: ✅ Captured via {method} | ELSE: ⚠️ URL analysis fallback activated}
+Phase 0.75 - URL Content Analysis: {IF url_only: ✅ Design patterns analyzed via MCP | ELSE: ⏭️ Skipped (screenshots available)}
+Phase 1 - Style Extraction: Single style extracted
+Phase 2 - Token Adaptation: Bypassed consolidate (⚡ {time_saved}s saved)
+Phase 3 - Prototype Generation: {target_count} {target_type} prototypes created
+Phase 4 - Design Integration: {integrated OR "Standalone mode"}
+
+📂 Output: {base_path}/
+  ├── style-extraction/style-cards.json (1 style card)
+  ├── style-consolidation/style-1/ (design tokens)
+  └── prototypes/ ({target_count} HTML/CSS files)
+
+🌐 Preview: {base_path}/prototypes/index.html
+
+{type_emoji} Targets: {', '.join(inferred_target_list)} | Type: {target_type}
+  Context: {IF target_type == "page": "Full-page layouts" ELSE: "Isolated components with minimal wrapper"}
+
+Performance:
+- Design system: ~{time}s (vs ~{consolidate_time}s with consolidate)
+- Total workflow: ~{total_time}s
+- Speed improvement: ~{improvement}× faster than explore-auto
+
+{IF session: Next: /workflow:plan to create implementation tasks | ELSE: Prototypes ready: {base_path}/prototypes/}
+```

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

@@ -0,0 +1,272 @@
+---
+name: update
+description: Update brainstorming artifacts with finalized design system references
+usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
+examples:
+  - /workflow:ui-design:update --session WFS-auth
+  - /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
+---
+
+# Design Update Command
+
+## Overview
+
+Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
+
+## Core Philosophy
+
+- **Reference-Only Updates**: Use @ references, no content duplication
+- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
+- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
+- **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
+- **Minimal Reading**: Verify file existence, don't read design content
+
+## Execution Protocol
+
+### Phase 1: Session & Artifact Validation
+
+```bash
+# Validate session
+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-*")
+
+# Detect design system structure (unified vs separate)
+IF exists({latest_design}/style-consolidation/design-tokens.json):
+    design_system_mode = "unified"; design_tokens_path = "style-consolidation/design-tokens.json"; style_guide_path = "style-consolidation/style-guide.md"
+ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
+    design_system_mode = "separate"; design_tokens_path = "style-consolidation/style-1/design-tokens.json"; style_guide_path = "style-consolidation/style-1/style-guide.md"
+ELSE:
+    ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"
+
+VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
+
+REPORT: "📋 Design system mode: {design_system_mode} | Tokens: {design_tokens_path}"
+
+# Prototype selection
+selected_list = --selected-prototypes ? parse_comma_separated(--selected-prototypes) : Glob({latest_design}/prototypes/*.html)
+VALIDATE: Specified prototypes exist IF --selected-prototypes
+
+REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
+```
+
+### Phase 2: Load Target Artifacts Only
+
+**What to Load**: Only the files we need to **update**, not the design files we're referencing.
+
+```bash
+# Load target brainstorming artifacts (files to be updated)
+Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
+
+# Optional: Read prototype notes for descriptions (minimal context)
+FOR each selected_prototype IN selected_list:
+    Read({latest_design}/prototypes/{selected_prototype}-notes.md)  # Extract: layout_strategy, page_name only
+
+# Note: Do NOT read design-tokens.json, style-guide.md, or prototype HTML. Only verify existence and generate @ references.
+```
+
+### Phase 3: Update Synthesis Specification
+
+Update `.brainstorming/synthesis-specification.md` with design system references.
+
+**Target Section**: `## UI/UX Guidelines`
+
+**Content Template**:
+```markdown
+## UI/UX Guidelines
+
+### Design System Reference
+**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../design-{run_id}/{style_guide_path}
+**Design System Mode**: {design_system_mode}
+
+### Implementation Requirements
+**Token Adherence**: All UI implementations MUST use design token CSS custom properties
+**Accessibility**: WCAG AA compliance validated in design-tokens.json
+**Responsive**: Mobile-first design using token-based breakpoints
+**Component Patterns**: Follow patterns documented in style-guide.md
+
+### Reference Prototypes
+{FOR each selected_prototype:
+- **{page_name}**: @../design-{run_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"}]}
+```
+```
+
+**Implementation**:
+```bash
+# Option 1: Edit existing section
+Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
+     old_string="## UI/UX Guidelines\n[existing content]",
+     new_string="## UI/UX Guidelines\n\n[new design reference content]")
+
+# Option 2: Append if section doesn't exist
+IF section not found:
+    Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
+```
+
+### Phase 4: Update UI Designer Style Guide
+
+Create or update `.brainstorming/ui-designer/style-guide.md`:
+
+```markdown
+# UI Designer Style Guide
+
+## 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 System Mode**: {design_system_mode}
+
+## Implementation Guidelines
+1. **Use CSS Custom Properties**: All styles reference design tokens
+2. **Follow Semantic HTML**: Use HTML5 semantic elements
+3. **Maintain Accessibility**: WCAG AA compliance required
+4. **Responsive Design**: Mobile-first with token-based breakpoints
+
+## Reference Prototypes
+{FOR each selected_prototype:
+- **{page_name}**: @../../design-{run_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}
+
+---
+*Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
+```
+
+**Implementation**:
+```bash
+Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
+      content="[generated content with @ references]")
+```
+
+### Phase 5: Completion
+
+```javascript
+TodoWrite({todos: [
+  {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
+  {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
+  {content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
+  {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Design system references updated for session: WFS-{session}
+
+Updated artifacts:
+✓ synthesis-specification.md - UI/UX Guidelines section with @ references
+✓ ui-designer/style-guide.md - Design system reference guide
+
+Design system assets ready for /workflow:plan:
+- design-tokens.json | style-guide.md | {prototype_count} reference prototypes
+
+Next: /workflow:plan [--agent] "<task description>"
+      The plan phase will automatically discover and utilize the design system.
+```
+
+## Output Structure
+
+**Updated Files**:
+```
+.workflow/WFS-{session}/.brainstorming/
+├── synthesis-specification.md       # Updated with UI/UX Guidelines section
+└── ui-designer/
+    └── style-guide.md               # New or updated design reference guide
+```
+
+**@ Reference Format** (synthesis-specification.md):
+```
+@../design-{run_id}/style-consolidation/design-tokens.json
+@../design-{run_id}/style-consolidation/style-guide.md
+@../design-{run_id}/prototypes/{prototype}.html
+```
+
+**@ Reference Format** (ui-designer/style-guide.md):
+```
+@../../design-{run_id}/style-consolidation/design-tokens.json
+@../../design-{run_id}/style-consolidation/style-guide.md
+@../../design-{run_id}/prototypes/{prototype}.html
+```
+
+## Integration with /workflow:plan
+
+After this update, `/workflow:plan` will discover design assets through:
+
+**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
+- Reads synthesis-specification.md → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
+
+**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
+- Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
+
+**Example Task JSON** (generated by task-generate):
+```json
+{
+  "task_id": "IMPL-001",
+  "context": {
+    "design_system": {
+      "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
+      "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
+      "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
+    }
+  }
+}
+```
+
+## Error Handling
+
+- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
+- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
+- **ui-designer/ directory missing**: Create directory and file
+- **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
+- **Invalid prototype names**: Skip invalid entries, continue with valid ones
+
+## Validation Checks
+
+After update, verify:
+- [ ] synthesis-specification.md contains UI/UX Guidelines section
+- [ ] UI/UX Guidelines include @ references (not content duplication)
+- [ ] ui-designer/style-guide.md created or updated
+- [ ] All @ referenced files exist and are accessible
+- [ ] @ reference paths are relative and correct
+
+## Key Features
+
+1. **Reference-Only Updates**: Uses @ notation for file references, no content duplication, lightweight and maintainable
+2. **Main Claude Direct Execution**: No Agent handoff (preserves context), simple reference generation, reliable path resolution
+3. **Plan-Ready Output**: `/workflow:plan` Phase 3 can discover design system, task generation includes design asset paths, clear integration points
+4. **Minimal Reading**: Only reads target files to update, verifies design file existence (no content reading), optional prototype notes for descriptions
+5. **Flexible Prototype Selection**: Auto-select all prototypes (default), manual selection via --selected-prototypes parameter, validates existence
+
+## Integration Points
+
+- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
+- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
+- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
+
+## Why Main Claude Execution?
+
+This command is executed directly by main Claude (not delegated to an Agent) because:
+
+1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
+2. **Context Preservation**: Main Claude has full session and conversation context
+3. **Minimal Transformation**: Primarily updating references, not analyzing content
+4. **Path Resolution**: Requires precise relative path calculation
+5. **Edit Operations**: Better error recovery for Edit conflicts
+6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
+
+This ensures reliable, lightweight integration without Agent handoff overhead.

.claude/prompt-templates/plan.md

@@ -1,10 +1,3 @@
----
-name: plan
-description: 软件架构规划和技术实现计划分析模板
-category: planning
-keywords: [规划, 架构, 实现计划, 技术设计, 修改方案]
----
-
 # 软件架构规划模板
 # AI Persona & Core Mission
 

.claude/scripts/convert_tokens_to_css.sh

@@ -0,0 +1,225 @@
+#!/bin/bash
+# Convert design-tokens.json to tokens.css with Google Fonts import and global font rules
+# Usage: cat design-tokens.json | ./convert_tokens_to_css.sh > tokens.css
+# Or: ./convert_tokens_to_css.sh < design-tokens.json > tokens.css
+
+# Read JSON from stdin
+json_input=$(cat)
+
+# Extract metadata for header comment
+style_name=$(echo "$json_input" | jq -r '.meta.name // "Unknown Style"' 2>/dev/null || echo "Design Tokens")
+
+# Generate header
+cat <<EOF
+/* ========================================
+   Design Tokens: ${style_name}
+   Auto-generated from design-tokens.json
+   ======================================== */
+
+EOF
+
+# ========================================
+# Google Fonts Import Generation
+# ========================================
+# Extract font families and generate Google Fonts import URL
+fonts=$(echo "$json_input" | jq -r '
+  .typography.font_family | to_entries[] | .value
+' 2>/dev/null | sed "s/'//g" | cut -d',' -f1 | sort -u)
+
+# Build Google Fonts URL
+google_fonts_url="https://fonts.googleapis.com/css2?"
+font_params=""
+
+while IFS= read -r font; do
+  # Skip system fonts and empty lines
+  if [[ -z "$font" ]] || [[ "$font" =~ ^(system-ui|sans-serif|serif|monospace|cursive|fantasy)$ ]]; then
+    continue
+  fi
+
+  # Special handling for common web fonts with weights
+  case "$font" in
+    "Comic Neue")
+      font_params+="family=Comic+Neue:wght@300;400;700&"
+      ;;
+    "Patrick Hand"|"Caveat"|"Dancing Script"|"Architects Daughter"|"Indie Flower"|"Shadows Into Light"|"Permanent Marker")
+      # URL-encode font name and add common weights
+      encoded_font=$(echo "$font" | sed 's/ /+/g')
+      font_params+="family=${encoded_font}:wght@400;700&"
+      ;;
+    "Segoe Print"|"Bradley Hand"|"Chilanka")
+      # These are system fonts, skip
+      ;;
+    *)
+      # Generic font: add with default weights
+      encoded_font=$(echo "$font" | sed 's/ /+/g')
+      font_params+="family=${encoded_font}:wght@400;500;600;700&"
+      ;;
+  esac
+done <<< "$fonts"
+
+# Generate @import if we have fonts
+if [[ -n "$font_params" ]]; then
+  # Remove trailing &
+  font_params="${font_params%&}"
+  echo "/* Import Web Fonts */"
+  echo "@import url('${google_fonts_url}${font_params}&display=swap');"
+  echo ""
+fi
+
+# ========================================
+# CSS Custom Properties Generation
+# ========================================
+echo ":root {"
+
+# Colors - Brand
+echo "  /* Colors - Brand */"
+echo "$json_input" | jq -r '
+  .colors.brand | to_entries[] |
+  "  --color-brand-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Surface
+echo "  /* Colors - Surface */"
+echo "$json_input" | jq -r '
+  .colors.surface | to_entries[] |
+  "  --color-surface-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Semantic
+echo "  /* Colors - Semantic */"
+echo "$json_input" | jq -r '
+  .colors.semantic | to_entries[] |
+  "  --color-semantic-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Text
+echo "  /* Colors - Text */"
+echo "$json_input" | jq -r '
+  .colors.text | to_entries[] |
+  "  --color-text-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Colors - Border
+echo "  /* Colors - Border */"
+echo "$json_input" | jq -r '
+  .colors.border | to_entries[] |
+  "  --color-border-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Font Family
+echo "  /* Typography - Font Family */"
+echo "$json_input" | jq -r '
+  .typography.font_family | to_entries[] |
+  "  --font-family-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Font Size
+echo "  /* Typography - Font Size */"
+echo "$json_input" | jq -r '
+  .typography.font_size | to_entries[] |
+  "  --font-size-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Font Weight
+echo "  /* Typography - Font Weight */"
+echo "$json_input" | jq -r '
+  .typography.font_weight | to_entries[] |
+  "  --font-weight-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Line Height
+echo "  /* Typography - Line Height */"
+echo "$json_input" | jq -r '
+  .typography.line_height | to_entries[] |
+  "  --line-height-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Typography - Letter Spacing
+echo "  /* Typography - Letter Spacing */"
+echo "$json_input" | jq -r '
+  .typography.letter_spacing | to_entries[] |
+  "  --letter-spacing-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Spacing
+echo "  /* Spacing */"
+echo "$json_input" | jq -r '
+  .spacing | to_entries[] |
+  "  --spacing-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Border Radius
+echo "  /* Border Radius */"
+echo "$json_input" | jq -r '
+  .border_radius | to_entries[] |
+  "  --border-radius-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Shadows
+echo "  /* Shadows */"
+echo "$json_input" | jq -r '
+  .shadows | to_entries[] |
+  "  --shadow-\(.key): \(.value);"
+' 2>/dev/null
+
+echo ""
+
+# Breakpoints
+echo "  /* Breakpoints */"
+echo "$json_input" | jq -r '
+  .breakpoints | to_entries[] |
+  "  --breakpoint-\(.key): \(.value);"
+' 2>/dev/null
+
+echo "}"
+echo ""
+
+# ========================================
+# Global Font Application
+# ========================================
+echo "/* ========================================"
+echo "   Global Font Application"
+echo "   ======================================== */"
+echo ""
+echo "body {"
+echo "  font-family: var(--font-family-body);"
+echo "  font-size: var(--font-size-base);"
+echo "  line-height: var(--line-height-normal);"
+echo "  color: var(--color-text-primary);"
+echo "  background-color: var(--color-surface-background);"
+echo "}"
+echo ""
+echo "h1, h2, h3, h4, h5, h6, legend {"
+echo "  font-family: var(--font-family-heading);"
+echo "}"
+echo ""
+echo "/* Reset default margins for better control */"
+echo "* {"
+echo "  margin: 0;"
+echo "  padding: 0;"
+echo "  box-sizing: border-box;"
+echo "}"

.claude/scripts/ui-generate-preview-v2.sh

@@ -0,0 +1,391 @@
+#!/bin/bash
+#
+# UI Generate Preview v2.0 - Template-Based Preview Generation
+# Purpose: Generate compare.html and index.html using template substitution
+# Template: ~/.claude/workflows/_template-compare-matrix.html
+#
+# Usage: ui-generate-preview-v2.sh <prototypes_dir> [--template <path>]
+#
+
+set -e
+
+# Color output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Default template path
+TEMPLATE_PATH="$HOME/.claude/workflows/_template-compare-matrix.html"
+
+# Parse arguments
+prototypes_dir="${1:-.}"
+shift || true
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --template)
+            TEMPLATE_PATH="$2"
+            shift 2
+            ;;
+        *)
+            echo -e "${RED}Unknown option: $1${NC}"
+            exit 1
+            ;;
+    esac
+done
+
+if [[ ! -d "$prototypes_dir" ]]; then
+    echo -e "${RED}Error: Directory not found: $prototypes_dir${NC}"
+    exit 1
+fi
+
+cd "$prototypes_dir" || exit 1
+
+echo -e "${GREEN}📊 Auto-detecting matrix dimensions...${NC}"
+
+# Auto-detect styles, layouts, targets from file patterns
+# Pattern: {target}-style-{s}-layout-{l}.html
+styles=$(find . -maxdepth 1 -name "*-style-*-layout-*.html" | \
+         sed 's/.*-style-\([0-9]\+\)-.*/\1/' | sort -un)
+layouts=$(find . -maxdepth 1 -name "*-style-*-layout-*.html" | \
+          sed 's/.*-layout-\([0-9]\+\)\.html/\1/' | sort -un)
+targets=$(find . -maxdepth 1 -name "*-style-*-layout-*.html" | \
+          sed 's/\.\///; s/-style-.*//' | sort -u)
+
+S=$(echo "$styles" | wc -l)
+L=$(echo "$layouts" | wc -l)
+T=$(echo "$targets" | wc -l)
+
+echo -e "   Detected: ${GREEN}${S}${NC} styles × ${GREEN}${L}${NC} layouts × ${GREEN}${T}${NC} targets"
+
+if [[ $S -eq 0 ]] || [[ $L -eq 0 ]] || [[ $T -eq 0 ]]; then
+    echo -e "${RED}Error: No prototype files found matching pattern {target}-style-{s}-layout-{l}.html${NC}"
+    exit 1
+fi
+
+# ============================================================================
+# Generate compare.html from template
+# ============================================================================
+
+echo -e "${YELLOW}🎨 Generating compare.html from template...${NC}"
+
+if [[ ! -f "$TEMPLATE_PATH" ]]; then
+    echo -e "${RED}Error: Template not found: $TEMPLATE_PATH${NC}"
+    exit 1
+fi
+
+# Build pages/targets JSON array
+PAGES_JSON="["
+first=true
+for target in $targets; do
+    if [[ "$first" == true ]]; then
+        first=false
+    else
+        PAGES_JSON+=", "
+    fi
+    PAGES_JSON+="\"$target\""
+done
+PAGES_JSON+="]"
+
+# Generate metadata
+RUN_ID="run-$(date +%Y%m%d-%H%M%S)"
+SESSION_ID="standalone"
+TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +"%Y-%m-%d")
+
+# Replace placeholders in template
+cat "$TEMPLATE_PATH" | \
+    sed "s|{{run_id}}|${RUN_ID}|g" | \
+    sed "s|{{session_id}}|${SESSION_ID}|g" | \
+    sed "s|{{timestamp}}|${TIMESTAMP}|g" | \
+    sed "s|{{style_variants}}|${S}|g" | \
+    sed "s|{{layout_variants}}|${L}|g" | \
+    sed "s|{{pages_json}}|${PAGES_JSON}|g" \
+    > compare.html
+
+echo -e "${GREEN}   ✓ Generated compare.html from template${NC}"
+
+# ============================================================================
+# Generate index.html
+# ============================================================================
+
+echo -e "${YELLOW}📋 Generating index.html...${NC}"
+
+cat > index.html << 'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>UI Prototypes Index</title>
+    <style>
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        body {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            max-width: 1200px;
+            margin: 0 auto;
+            padding: 40px 20px;
+            background: #f5f5f5;
+        }
+        h1 { margin-bottom: 10px; color: #333; }
+        .subtitle { color: #666; margin-bottom: 30px; }
+        .cta {
+            background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+            color: white;
+            padding: 20px;
+            border-radius: 8px;
+            margin-bottom: 30px;
+            box-shadow: 0 4px 6px rgba(0,0,0,0.1);
+        }
+        .cta h2 { margin-bottom: 10px; }
+        .cta a {
+            display: inline-block;
+            background: white;
+            color: #667eea;
+            padding: 10px 20px;
+            border-radius: 6px;
+            text-decoration: none;
+            font-weight: 600;
+            margin-top: 10px;
+        }
+        .cta a:hover { background: #f8f9fa; }
+        .style-section {
+            background: white;
+            padding: 20px;
+            border-radius: 8px;
+            margin-bottom: 20px;
+            box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+        }
+        .style-section h2 {
+            color: #495057;
+            margin-bottom: 15px;
+            padding-bottom: 10px;
+            border-bottom: 2px solid #e9ecef;
+        }
+        .target-group {
+            margin-bottom: 20px;
+        }
+        .target-group h3 {
+            color: #6c757d;
+            font-size: 16px;
+            margin-bottom: 10px;
+        }
+        .link-grid {
+            display: grid;
+            grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+            gap: 10px;
+        }
+        .prototype-link {
+            padding: 12px 16px;
+            background: #f8f9fa;
+            border: 1px solid #dee2e6;
+            border-radius: 6px;
+            text-decoration: none;
+            color: #495057;
+            display: flex;
+            justify-content: space-between;
+            align-items: center;
+            transition: all 0.2s;
+        }
+        .prototype-link:hover {
+            background: #e9ecef;
+            border-color: #667eea;
+            transform: translateX(2px);
+        }
+        .prototype-link .label { font-weight: 500; }
+        .prototype-link .icon { color: #667eea; }
+    </style>
+</head>
+<body>
+    <h1>🎨 UI Prototypes Index</h1>
+    <p class="subtitle">Generated __S__×__L__×__T__ = __TOTAL__ prototypes</p>
+
+    <div class="cta">
+        <h2>📊 Interactive Comparison</h2>
+        <p>View all styles and layouts side-by-side in an interactive matrix</p>
+        <a href="compare.html">Open Matrix View →</a>
+    </div>
+
+    <h2>📂 All Prototypes</h2>
+__CONTENT__
+</body>
+</html>
+EOF
+
+# Build content HTML
+CONTENT=""
+for style in $styles; do
+    CONTENT+="<div class='style-section'>"$'\n'
+    CONTENT+="<h2>Style ${style}</h2>"$'\n'
+
+    for target in $targets; do
+        target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
+        CONTENT+="<div class='target-group'>"$'\n'
+        CONTENT+="<h3>${target_capitalized}</h3>"$'\n'
+        CONTENT+="<div class='link-grid'>"$'\n'
+
+        for layout in $layouts; do
+            html_file="${target}-style-${style}-layout-${layout}.html"
+            if [[ -f "$html_file" ]]; then
+                CONTENT+="<a href='${html_file}' class='prototype-link' target='_blank'>"$'\n'
+                CONTENT+="<span class='label'>Layout ${layout}</span>"$'\n'
+                CONTENT+="<span class='icon'>↗</span>"$'\n'
+                CONTENT+="</a>"$'\n'
+            fi
+        done
+
+        CONTENT+="</div></div>"$'\n'
+    done
+
+    CONTENT+="</div>"$'\n'
+done
+
+# Calculate total
+TOTAL_PROTOTYPES=$((S * L * T))
+
+# Replace placeholders (using a temp file for complex replacement)
+{
+    echo "$CONTENT" > /tmp/content_tmp.txt
+    sed "s|__S__|${S}|g" index.html | \
+        sed "s|__L__|${L}|g" | \
+        sed "s|__T__|${T}|g" | \
+        sed "s|__TOTAL__|${TOTAL_PROTOTYPES}|g" | \
+        sed -e "/__CONTENT__/r /tmp/content_tmp.txt" -e "/__CONTENT__/d" > /tmp/index_tmp.html
+    mv /tmp/index_tmp.html index.html
+    rm -f /tmp/content_tmp.txt
+}
+
+echo -e "${GREEN}   ✓ Generated index.html${NC}"
+
+# ============================================================================
+# Generate PREVIEW.md
+# ============================================================================
+
+echo -e "${YELLOW}📝 Generating PREVIEW.md...${NC}"
+
+cat > PREVIEW.md << EOF
+# UI Prototypes Preview Guide
+
+Generated: $(date +"%Y-%m-%d %H:%M:%S")
+
+## 📊 Matrix Dimensions
+
+- **Styles**: ${S}
+- **Layouts**: ${L}
+- **Targets**: ${T}
+- **Total Prototypes**: $((S*L*T))
+
+## 🌐 How to View
+
+### Option 1: Interactive Matrix (Recommended)
+
+Open \`compare.html\` in your browser to see all prototypes in an interactive matrix view.
+
+**Features**:
+- Side-by-side comparison of all styles and layouts
+- Switch between targets using the dropdown
+- Adjust grid columns for better viewing
+- Direct links to full-page views
+- Selection system with export to JSON
+- Fullscreen mode for detailed inspection
+
+### Option 2: Simple Index
+
+Open \`index.html\` for a simple list of all prototypes with direct links.
+
+### Option 3: Direct File Access
+
+Each prototype can be opened directly:
+- Pattern: \`{target}-style-{s}-layout-{l}.html\`
+- Example: \`dashboard-style-1-layout-1.html\`
+
+## 📁 File Structure
+
+\`\`\`
+prototypes/
+├── compare.html           # Interactive matrix view
+├── index.html             # Simple navigation index
+├── PREVIEW.md             # This file
+EOF
+
+for style in $styles; do
+    for target in $targets; do
+        for layout in $layouts; do
+            echo "├── ${target}-style-${style}-layout-${layout}.html" >> PREVIEW.md
+            echo "├── ${target}-style-${style}-layout-${layout}.css" >> PREVIEW.md
+        done
+    done
+done
+
+cat >> PREVIEW.md << 'EOF2'
+```
+
+## 🎨 Style Variants
+
+EOF2
+
+for style in $styles; do
+    cat >> PREVIEW.md << EOF3
+### Style ${style}
+
+EOF3
+    style_guide="../style-consolidation/style-${style}/style-guide.md"
+    if [[ -f "$style_guide" ]]; then
+        head -n 10 "$style_guide" | tail -n +2 >> PREVIEW.md 2>/dev/null || echo "Design philosophy and tokens" >> PREVIEW.md
+    else
+        echo "Design system ${style}" >> PREVIEW.md
+    fi
+    echo "" >> PREVIEW.md
+done
+
+cat >> PREVIEW.md << 'EOF4'
+
+## 🎯 Targets
+
+EOF4
+
+for target in $targets; do
+    target_capitalized="$(echo ${target:0:1} | tr '[:lower:]' '[:upper:]')${target:1}"
+    echo "- **${target_capitalized}**: ${L} layouts × ${S} styles = $((L*S)) variations" >> PREVIEW.md
+done
+
+cat >> PREVIEW.md << 'EOF5'
+
+## 💡 Tips
+
+1. **Comparison**: Use compare.html to see how different styles affect the same layout
+2. **Navigation**: Use index.html for quick access to specific prototypes
+3. **Selection**: Mark favorites in compare.html using star icons
+4. **Export**: Download selection JSON for implementation planning
+5. **Inspection**: Open browser DevTools to inspect HTML structure and CSS
+6. **Sharing**: All files are standalone - can be shared or deployed directly
+
+## 📝 Next Steps
+
+1. Review prototypes in compare.html
+2. Select preferred style × layout combinations
+3. Export selections as JSON
+4. Provide feedback for refinement
+5. Use selected designs for implementation
+
+---
+
+Generated by /workflow:ui-design:generate-v2 (Style-Centric Architecture)
+EOF5
+
+echo -e "${GREEN}   ✓ Generated PREVIEW.md${NC}"
+
+# ============================================================================
+# Completion Summary
+# ============================================================================
+
+echo ""
+echo -e "${GREEN}✅ Preview generation complete!${NC}"
+echo -e "   Files created: compare.html, index.html, PREVIEW.md"
+echo -e "   Matrix: ${S} styles × ${L} layouts × ${T} targets = $((S*L*T)) prototypes"
+echo ""
+echo -e "${YELLOW}🌐 Next Steps:${NC}"
+echo -e "   1. Open compare.html for interactive matrix view"
+echo -e "   2. Open index.html for simple navigation"
+echo -e "   3. Read PREVIEW.md for detailed usage guide"
+echo ""

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

@@ -0,0 +1,811 @@
+#!/bin/bash
+
+# UI Prototype Instantiation Script with Preview Generation (v3.0 - Auto-detect)
+# Purpose: Generate S × L × P final prototypes from templates + interactive preview files
+# Usage:
+#   Simple: ui-instantiate-prototypes.sh <prototypes_dir>
+#   Full:   ui-instantiate-prototypes.sh <base_path> <pages> <style_variants> <layout_variants> [options]
+
+# Use safer error handling
+set -o pipefail
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+log_info() {
+    echo "$1"
+}
+
+log_success() {
+    echo "✅ $1"
+}
+
+log_error() {
+    echo "❌ $1"
+}
+
+log_warning() {
+    echo "⚠️  $1"
+}
+
+# Auto-detect pages from templates directory
+auto_detect_pages() {
+    local templates_dir="$1/_templates"
+
+    if [ ! -d "$templates_dir" ]; then
+        log_error "Templates directory not found: $templates_dir"
+        return 1
+    fi
+
+    # Find unique page names from template files (e.g., login-layout-1.html -> login)
+    local pages=$(find "$templates_dir" -name "*-layout-*.html" -type f | \
+                  sed 's|.*/||' | \
+                  sed 's|-layout-[0-9]*\.html||' | \
+                  sort -u | \
+                  tr '\n' ',' | \
+                  sed 's/,$//')
+
+    echo "$pages"
+}
+
+# Auto-detect style variants count
+auto_detect_style_variants() {
+    local base_path="$1"
+    local style_dir="$base_path/../style-consolidation"
+
+    if [ ! -d "$style_dir" ]; then
+        log_warning "Style consolidation directory not found: $style_dir"
+        echo "3"  # Default
+        return
+    fi
+
+    # Count style-* directories
+    local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
+
+    if [ "$count" -eq 0 ]; then
+        echo "3"  # Default
+    else
+        echo "$count"
+    fi
+}
+
+# Auto-detect layout variants count
+auto_detect_layout_variants() {
+    local templates_dir="$1/_templates"
+
+    if [ ! -d "$templates_dir" ]; then
+        echo "3"  # Default
+        return
+    fi
+
+    # Find the first page and count its layouts
+    local first_page=$(find "$templates_dir" -name "*-layout-1.html" -type f | head -1 | sed 's|.*/||' | sed 's|-layout-1\.html||')
+
+    if [ -z "$first_page" ]; then
+        echo "3"  # Default
+        return
+    fi
+
+    # Count layout files for this page
+    local count=$(find "$templates_dir" -name "${first_page}-layout-*.html" -type f | wc -l)
+
+    if [ "$count" -eq 0 ]; then
+        echo "3"  # Default
+    else
+        echo "$count"
+    fi
+}
+
+# ============================================================================
+# Parse Arguments
+# ============================================================================
+
+show_usage() {
+    cat <<'EOF'
+Usage:
+  Simple (auto-detect): ui-instantiate-prototypes.sh <prototypes_dir> [options]
+  Full:                 ui-instantiate-prototypes.sh <base_path> <pages> <style_variants> <layout_variants> [options]
+
+Simple Mode (Recommended):
+  prototypes_dir    Path to prototypes directory (auto-detects everything)
+
+Full Mode:
+  base_path         Base path to prototypes directory
+  pages             Comma-separated list of pages/components
+  style_variants    Number of style variants (1-5)
+  layout_variants   Number of layout variants (1-5)
+
+Options:
+  --run-id <id>         Run ID (default: auto-generated)
+  --session-id <id>     Session ID (default: standalone)
+  --mode <page|component>  Exploration mode (default: page)
+  --template <path>     Path to compare.html template (default: ~/.claude/workflows/_template-compare-matrix.html)
+  --no-preview          Skip preview file generation
+  --help                Show this help message
+
+Examples:
+  # Simple usage (auto-detect everything)
+  ui-instantiate-prototypes.sh .design/prototypes
+
+  # With options
+  ui-instantiate-prototypes.sh .design/prototypes --session-id WFS-auth
+
+  # Full manual mode
+  ui-instantiate-prototypes.sh .design/prototypes "login,dashboard" 3 3 --session-id WFS-auth
+EOF
+}
+
+# Default values
+BASE_PATH=""
+PAGES=""
+STYLE_VARIANTS=""
+LAYOUT_VARIANTS=""
+RUN_ID="run-$(date +%Y%m%d-%H%M%S)"
+SESSION_ID="standalone"
+MODE="page"
+TEMPLATE_PATH="$HOME/.claude/workflows/_template-compare-matrix.html"
+GENERATE_PREVIEW=true
+AUTO_DETECT=false
+
+# Parse arguments
+if [ $# -lt 1 ]; then
+    log_error "Missing required arguments"
+    show_usage
+    exit 1
+fi
+
+# Check if using simple mode (only 1 positional arg before options)
+if [ $# -eq 1 ] || [[ "$2" == --* ]]; then
+    # Simple mode - auto-detect
+    AUTO_DETECT=true
+    BASE_PATH="$1"
+    shift 1
+else
+    # Full mode - manual parameters
+    if [ $# -lt 4 ]; then
+        log_error "Full mode requires 4 positional arguments"
+        show_usage
+        exit 1
+    fi
+
+    BASE_PATH="$1"
+    PAGES="$2"
+    STYLE_VARIANTS="$3"
+    LAYOUT_VARIANTS="$4"
+    shift 4
+fi
+
+# Parse optional arguments
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --run-id)
+            RUN_ID="$2"
+            shift 2
+            ;;
+        --session-id)
+            SESSION_ID="$2"
+            shift 2
+            ;;
+        --mode)
+            MODE="$2"
+            shift 2
+            ;;
+        --template)
+            TEMPLATE_PATH="$2"
+            shift 2
+            ;;
+        --no-preview)
+            GENERATE_PREVIEW=false
+            shift
+            ;;
+        --help)
+            show_usage
+            exit 0
+            ;;
+        *)
+            log_error "Unknown option: $1"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# ============================================================================
+# Auto-detection (if enabled)
+# ============================================================================
+
+if [ "$AUTO_DETECT" = true ]; then
+    log_info "🔍 Auto-detecting configuration from directory..."
+
+    # Detect pages
+    PAGES=$(auto_detect_pages "$BASE_PATH")
+    if [ -z "$PAGES" ]; then
+        log_error "Could not auto-detect pages from templates"
+        exit 1
+    fi
+    log_info "   Pages: $PAGES"
+
+    # Detect style variants
+    STYLE_VARIANTS=$(auto_detect_style_variants "$BASE_PATH")
+    log_info "   Style variants: $STYLE_VARIANTS"
+
+    # Detect layout variants
+    LAYOUT_VARIANTS=$(auto_detect_layout_variants "$BASE_PATH")
+    log_info "   Layout variants: $LAYOUT_VARIANTS"
+
+    echo ""
+fi
+
+# ============================================================================
+# Validation
+# ============================================================================
+
+# Validate base path
+if [ ! -d "$BASE_PATH" ]; then
+    log_error "Base path not found: $BASE_PATH"
+    exit 1
+fi
+
+# Validate style and layout variants
+if [ "$STYLE_VARIANTS" -lt 1 ] || [ "$STYLE_VARIANTS" -gt 5 ]; then
+    log_error "Style variants must be between 1 and 5 (got: $STYLE_VARIANTS)"
+    exit 1
+fi
+
+if [ "$LAYOUT_VARIANTS" -lt 1 ] || [ "$LAYOUT_VARIANTS" -gt 5 ]; then
+    log_error "Layout variants must be between 1 and 5 (got: $LAYOUT_VARIANTS)"
+    exit 1
+fi
+
+# Validate STYLE_VARIANTS against actual style directories
+if [ "$STYLE_VARIANTS" -gt 0 ]; then
+    style_dir="$BASE_PATH/../style-consolidation"
+
+    if [ ! -d "$style_dir" ]; then
+        log_error "Style consolidation directory not found: $style_dir"
+        log_info "Run /workflow:ui-design:consolidate first"
+        exit 1
+    fi
+
+    actual_styles=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
+
+    if [ "$actual_styles" -eq 0 ]; then
+        log_error "No style directories found in: $style_dir"
+        log_info "Run /workflow:ui-design:consolidate first to generate style design systems"
+        exit 1
+    fi
+
+    if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+        log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+        log_info "Available style directories:"
+        find "$style_dir" -maxdepth 1 -type d -name "style-*" 2>/dev/null | sed 's|.*/||' | sort
+        log_info "Auto-correcting to $actual_styles style variants"
+        STYLE_VARIANTS=$actual_styles
+    fi
+fi
+
+# Parse pages into array
+IFS=',' read -ra PAGE_ARRAY <<< "$PAGES"
+
+if [ ${#PAGE_ARRAY[@]} -eq 0 ]; then
+    log_error "No pages found"
+    exit 1
+fi
+
+# ============================================================================
+# Header Output
+# ============================================================================
+
+echo "========================================="
+echo "UI Prototype Instantiation & Preview"
+if [ "$AUTO_DETECT" = true ]; then
+    echo "(Auto-detected configuration)"
+fi
+echo "========================================="
+echo "Base Path: $BASE_PATH"
+echo "Mode: $MODE"
+echo "Pages/Components: $PAGES"
+echo "Style Variants: $STYLE_VARIANTS"
+echo "Layout Variants: $LAYOUT_VARIANTS"
+echo "Run ID: $RUN_ID"
+echo "Session ID: $SESSION_ID"
+echo "========================================="
+echo ""
+
+# Change to base path
+cd "$BASE_PATH" || exit 1
+
+# ============================================================================
+# Phase 1: Instantiate Prototypes
+# ============================================================================
+
+log_info "🚀 Phase 1: Instantiating prototypes from templates..."
+echo ""
+
+total_generated=0
+total_failed=0
+
+for page in "${PAGE_ARRAY[@]}"; do
+    # Trim whitespace
+    page=$(echo "$page" | xargs)
+
+    log_info "Processing page/component: $page"
+
+    for s in $(seq 1 "$STYLE_VARIANTS"); do
+        for l in $(seq 1 "$LAYOUT_VARIANTS"); do
+            # Define file paths
+            TEMPLATE_HTML="_templates/${page}-layout-${l}.html"
+            STRUCTURAL_CSS="_templates/${page}-layout-${l}.css"
+            TOKEN_CSS="../style-consolidation/style-${s}/tokens.css"
+            OUTPUT_HTML="${page}-style-${s}-layout-${l}.html"
+
+            # Copy template and replace placeholders
+            if [ -f "$TEMPLATE_HTML" ]; then
+                cp "$TEMPLATE_HTML" "$OUTPUT_HTML" || {
+                    log_error "Failed to copy template: $TEMPLATE_HTML"
+                    ((total_failed++))
+                    continue
+                }
+
+                # Replace CSS placeholders (Windows-compatible sed syntax)
+                sed -i "s|{{STRUCTURAL_CSS}}|${STRUCTURAL_CSS}|g" "$OUTPUT_HTML" || true
+                sed -i "s|{{TOKEN_CSS}}|${TOKEN_CSS}|g" "$OUTPUT_HTML" || true
+
+                log_success "Created: $OUTPUT_HTML"
+                ((total_generated++))
+
+                # Create implementation notes (simplified)
+                NOTES_FILE="${page}-style-${s}-layout-${l}-notes.md"
+
+                # Generate notes with simple heredoc
+                cat > "$NOTES_FILE" <<NOTESEOF
+# Implementation Notes: ${page}-style-${s}-layout-${l}
+
+## Generation Details
+- **Template**: ${TEMPLATE_HTML}
+- **Structural CSS**: ${STRUCTURAL_CSS}
+- **Style Tokens**: ${TOKEN_CSS}
+- **Layout Strategy**: Layout ${l}
+- **Style Variant**: Style ${s}
+- **Mode**: ${MODE}
+
+## Template Reuse
+This prototype was generated from a shared layout template to ensure consistency
+across all style variants. The HTML structure is identical for all ${page}-layout-${l}
+prototypes, with only the design tokens (colors, fonts, spacing) varying.
+
+## Design System Reference
+Refer to \`../style-consolidation/style-${s}/style-guide.md\` for:
+- Design philosophy
+- Token usage guidelines
+- Component patterns
+- Accessibility requirements
+
+## Customization
+To modify this prototype:
+1. Edit the layout template: \`${TEMPLATE_HTML}\` (affects all styles)
+2. Edit the structural CSS: \`${STRUCTURAL_CSS}\` (affects all styles)
+3. Edit design tokens: \`${TOKEN_CSS}\` (affects only this style variant)
+
+## Run Information
+- **Run ID**: ${RUN_ID}
+- **Session ID**: ${SESSION_ID}
+- **Generated**: $(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%d)
+NOTESEOF
+
+            else
+                log_error "Template not found: $TEMPLATE_HTML"
+                ((total_failed++))
+            fi
+        done
+    done
+done
+
+echo ""
+log_success "Phase 1 complete: Generated ${total_generated} prototypes"
+if [ $total_failed -gt 0 ]; then
+    log_warning "Failed: ${total_failed} prototypes"
+fi
+echo ""
+
+# ============================================================================
+# Phase 2: Generate Preview Files (if enabled)
+# ============================================================================
+
+if [ "$GENERATE_PREVIEW" = false ]; then
+    log_info "⏭️  Skipping preview generation (--no-preview flag)"
+    exit 0
+fi
+
+log_info "🎨 Phase 2: Generating preview files..."
+echo ""
+
+# ============================================================================
+# 2a. Generate compare.html from template
+# ============================================================================
+
+if [ ! -f "$TEMPLATE_PATH" ]; then
+    log_warning "Template not found: $TEMPLATE_PATH"
+    log_info "   Skipping compare.html generation"
+else
+    log_info "📄 Generating compare.html from template..."
+
+    # Convert page array to JSON format
+    PAGES_JSON="["
+    for i in "${!PAGE_ARRAY[@]}"; do
+        page=$(echo "${PAGE_ARRAY[$i]}" | xargs)
+        PAGES_JSON+="\"$page\""
+        if [ $i -lt $((${#PAGE_ARRAY[@]} - 1)) ]; then
+            PAGES_JSON+=", "
+        fi
+    done
+    PAGES_JSON+="]"
+
+    TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u +%Y-%m-%d)
+
+    # Read template and replace placeholders
+    cat "$TEMPLATE_PATH" | \
+        sed "s|{{run_id}}|${RUN_ID}|g" | \
+        sed "s|{{session_id}}|${SESSION_ID}|g" | \
+        sed "s|{{timestamp}}|${TIMESTAMP}|g" | \
+        sed "s|{{style_variants}}|${STYLE_VARIANTS}|g" | \
+        sed "s|{{layout_variants}}|${LAYOUT_VARIANTS}|g" | \
+        sed "s|{{pages_json}}|${PAGES_JSON}|g" \
+        > compare.html
+
+    log_success "Generated: compare.html"
+fi
+
+# ============================================================================
+# 2b. Generate index.html
+# ============================================================================
+
+log_info "📄 Generating index.html..."
+
+# Calculate total prototypes
+TOTAL_PROTOTYPES=$((STYLE_VARIANTS * LAYOUT_VARIANTS * ${#PAGE_ARRAY[@]}))
+
+# Generate index.html with simple heredoc
+cat > index.html <<'INDEXEOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>UI Prototypes - __MODE__ Mode - __RUN_ID__</title>
+  <style>
+    body {
+      font-family: system-ui, -apple-system, sans-serif;
+      max-width: 900px;
+      margin: 2rem auto;
+      padding: 0 2rem;
+      background: #f9fafb;
+    }
+    .header {
+      background: white;
+      padding: 2rem;
+      border-radius: 0.75rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+      margin-bottom: 2rem;
+    }
+    h1 {
+      color: #2563eb;
+      margin-bottom: 0.5rem;
+      font-size: 2rem;
+    }
+    .meta {
+      color: #6b7280;
+      font-size: 0.875rem;
+      margin-top: 0.5rem;
+    }
+    .info {
+      background: #f3f4f6;
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      margin: 1.5rem 0;
+      border-left: 4px solid #2563eb;
+    }
+    .cta {
+      display: inline-block;
+      background: #2563eb;
+      color: white;
+      padding: 1rem 2rem;
+      border-radius: 0.5rem;
+      text-decoration: none;
+      font-weight: 600;
+      margin: 1rem 0;
+      transition: background 0.2s;
+    }
+    .cta:hover {
+      background: #1d4ed8;
+    }
+    .stats {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+      gap: 1rem;
+      margin: 1.5rem 0;
+    }
+    .stat {
+      background: white;
+      border: 1px solid #e5e7eb;
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      text-align: center;
+      box-shadow: 0 1px 2px rgba(0,0,0,0.05);
+    }
+    .stat-value {
+      font-size: 2.5rem;
+      font-weight: bold;
+      color: #2563eb;
+      margin-bottom: 0.25rem;
+    }
+    .stat-label {
+      color: #6b7280;
+      font-size: 0.875rem;
+    }
+    .section {
+      background: white;
+      padding: 2rem;
+      border-radius: 0.75rem;
+      margin-bottom: 2rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+    h2 {
+      color: #1f2937;
+      margin-bottom: 1rem;
+      font-size: 1.5rem;
+    }
+    ul {
+      line-height: 1.8;
+      color: #374151;
+    }
+    .pages-list {
+      list-style: none;
+      padding: 0;
+    }
+    .pages-list li {
+      background: #f9fafb;
+      padding: 0.75rem 1rem;
+      margin: 0.5rem 0;
+      border-radius: 0.375rem;
+      border-left: 3px solid #2563eb;
+    }
+    .badge {
+      display: inline-block;
+      background: #dbeafe;
+      color: #1e40af;
+      padding: 0.25rem 0.75rem;
+      border-radius: 0.25rem;
+      font-size: 0.75rem;
+      font-weight: 600;
+      margin-left: 0.5rem;
+    }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>🎨 UI Prototype __MODE__ Mode</h1>
+    <div class="meta">
+      <strong>Run ID:</strong> __RUN_ID__ |
+      <strong>Session:</strong> __SESSION_ID__ |
+      <strong>Generated:</strong> __TIMESTAMP__
+    </div>
+  </div>
+
+  <div class="info">
+    <p><strong>Matrix Configuration:</strong> __STYLE_VARIANTS__ styles × __LAYOUT_VARIANTS__ layouts × __PAGE_COUNT__ __MODE__s</p>
+    <p><strong>Total Prototypes:</strong> __TOTAL_PROTOTYPES__ interactive HTML files</p>
+  </div>
+
+  <a href="compare.html" class="cta">🔍 Open Interactive Matrix Comparison →</a>
+
+  <div class="stats">
+    <div class="stat">
+      <div class="stat-value">__STYLE_VARIANTS__</div>
+      <div class="stat-label">Style Variants</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value">__LAYOUT_VARIANTS__</div>
+      <div class="stat-label">Layout Options</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value">__PAGE_COUNT__</div>
+      <div class="stat-label">__MODE__s</div>
+    </div>
+    <div class="stat">
+      <div class="stat-value">__TOTAL_PROTOTYPES__</div>
+      <div class="stat-label">Total Prototypes</div>
+    </div>
+  </div>
+
+  <div class="section">
+    <h2>🌟 Features</h2>
+    <ul>
+      <li><strong>Interactive Matrix View:</strong> __STYLE_VARIANTS__×__LAYOUT_VARIANTS__ grid with synchronized scrolling</li>
+      <li><strong>Flexible Zoom:</strong> 25%, 50%, 75%, 100% viewport scaling</li>
+      <li><strong>Fullscreen Mode:</strong> Detailed view for individual prototypes</li>
+      <li><strong>Selection System:</strong> Mark favorites with export to JSON</li>
+      <li><strong>__MODE__ Switcher:</strong> Compare different __MODE__s side-by-side</li>
+      <li><strong>Persistent State:</strong> Selections saved in localStorage</li>
+    </ul>
+  </div>
+
+  <div class="section">
+    <h2>📄 Generated __MODE__s</h2>
+    <ul class="pages-list">
+__PAGES_LIST__
+    </ul>
+  </div>
+
+  <div class="section">
+    <h2>📚 Next Steps</h2>
+    <ol>
+      <li>Open <code>compare.html</code> to explore all variants in matrix view</li>
+      <li>Use zoom and sync scroll controls to compare details</li>
+      <li>Select your preferred style×layout combinations</li>
+      <li>Export selections as JSON for implementation planning</li>
+      <li>Review implementation notes in <code>*-notes.md</code> files</li>
+    </ol>
+  </div>
+</body>
+</html>
+INDEXEOF
+
+# Build pages list HTML
+PAGES_LIST_HTML=""
+for page in "${PAGE_ARRAY[@]}"; do
+    page=$(echo "$page" | xargs)
+    VARIANT_COUNT=$((STYLE_VARIANTS * LAYOUT_VARIANTS))
+    PAGES_LIST_HTML+="      <li>\n"
+    PAGES_LIST_HTML+="        <strong>${page}</strong>\n"
+    PAGES_LIST_HTML+="        <span class=\"badge\">${STYLE_VARIANTS}×${LAYOUT_VARIANTS} = ${VARIANT_COUNT} variants</span>\n"
+    PAGES_LIST_HTML+="      </li>\n"
+done
+
+# Replace all placeholders in index.html
+MODE_UPPER=$(echo "$MODE" | awk '{print toupper(substr($0,1,1)) tolower(substr($0,2))}')
+sed -i "s|__RUN_ID__|${RUN_ID}|g" index.html
+sed -i "s|__SESSION_ID__|${SESSION_ID}|g" index.html
+sed -i "s|__TIMESTAMP__|${TIMESTAMP}|g" index.html
+sed -i "s|__MODE__|${MODE_UPPER}|g" index.html
+sed -i "s|__STYLE_VARIANTS__|${STYLE_VARIANTS}|g" index.html
+sed -i "s|__LAYOUT_VARIANTS__|${LAYOUT_VARIANTS}|g" index.html
+sed -i "s|__PAGE_COUNT__|${#PAGE_ARRAY[@]}|g" index.html
+sed -i "s|__TOTAL_PROTOTYPES__|${TOTAL_PROTOTYPES}|g" index.html
+sed -i "s|__PAGES_LIST__|${PAGES_LIST_HTML}|g" index.html
+
+log_success "Generated: index.html"
+
+# ============================================================================
+# 2c. Generate PREVIEW.md
+# ============================================================================
+
+log_info "📄 Generating PREVIEW.md..."
+
+cat > PREVIEW.md <<PREVIEWEOF
+# UI Prototype Preview Guide
+
+## Quick Start
+1. Open \`index.html\` for overview and navigation
+2. Open \`compare.html\` for interactive matrix comparison
+3. Use browser developer tools to inspect responsive behavior
+
+## Configuration
+
+- **Exploration Mode:** ${MODE_UPPER}
+- **Run ID:** ${RUN_ID}
+- **Session ID:** ${SESSION_ID}
+- **Style Variants:** ${STYLE_VARIANTS}
+- **Layout Options:** ${LAYOUT_VARIANTS}
+- **${MODE_UPPER}s:** ${PAGES}
+- **Total Prototypes:** ${TOTAL_PROTOTYPES}
+- **Generated:** ${TIMESTAMP}
+
+## File Naming Convention
+
+\`\`\`
+{${MODE}}-style-{s}-layout-{l}.html
+\`\`\`
+
+**Example:** \`dashboard-style-1-layout-2.html\`
+- ${MODE_UPPER}: dashboard
+- Style: Design system 1
+- Layout: Layout variant 2
+
+## Interactive Features (compare.html)
+
+### Matrix View
+- **Grid Layout:** ${STYLE_VARIANTS}×${LAYOUT_VARIANTS} table with all prototypes visible
+- **Synchronized Scroll:** All iframes scroll together (toggle with button)
+- **Zoom Controls:** Adjust viewport scale (25%, 50%, 75%, 100%)
+- **${MODE_UPPER} Selector:** Switch between different ${MODE}s instantly
+
+### Prototype Actions
+- **⭐ Selection:** Click star icon to mark favorites
+- **⛶ Fullscreen:** View prototype in fullscreen overlay
+- **↗ New Tab:** Open prototype in dedicated browser tab
+
+### Selection Export
+1. Select preferred prototypes using star icons
+2. Click "Export Selection" button
+3. Downloads JSON file: \`selection-${RUN_ID}.json\`
+4. Use exported file for implementation planning
+
+## Design System References
+
+Each prototype references a specific style design system:
+PREVIEWEOF
+
+# Add style references
+for s in $(seq 1 "$STYLE_VARIANTS"); do
+    cat >> PREVIEW.md <<STYLEEOF
+
+### Style ${s}
+- **Tokens:** \`../style-consolidation/style-${s}/design-tokens.json\`
+- **CSS Variables:** \`../style-consolidation/style-${s}/tokens.css\`
+- **Style Guide:** \`../style-consolidation/style-${s}/style-guide.md\`
+STYLEEOF
+done
+
+cat >> PREVIEW.md <<'FOOTEREOF'
+
+## Responsive Testing
+
+All prototypes are mobile-first responsive. Test at these breakpoints:
+
+- **Mobile:** 375px - 767px
+- **Tablet:** 768px - 1023px
+- **Desktop:** 1024px+
+
+Use browser DevTools responsive mode for testing.
+
+## Accessibility Features
+
+- Semantic HTML5 structure
+- ARIA attributes for screen readers
+- Keyboard navigation support
+- Proper heading hierarchy
+- Focus indicators
+
+## Next Steps
+
+1. **Review:** Open `compare.html` and explore all variants
+2. **Select:** Mark preferred prototypes using star icons
+3. **Export:** Download selection JSON for implementation
+4. **Implement:** Use `/workflow:ui-design:update` to integrate selected designs
+5. **Plan:** Run `/workflow:plan` to generate implementation tasks
+
+---
+
+**Generated by:** `ui-instantiate-prototypes.sh`
+**Version:** 3.0 (auto-detect mode)
+FOOTEREOF
+
+log_success "Generated: PREVIEW.md"
+
+# ============================================================================
+# Completion Summary
+# ============================================================================
+
+echo ""
+echo "========================================="
+echo "✅ Generation Complete!"
+echo "========================================="
+echo ""
+echo "📊 Summary:"
+echo "   Prototypes: ${total_generated} generated"
+if [ $total_failed -gt 0 ]; then
+    echo "   Failed: ${total_failed}"
+fi
+echo "   Preview Files: compare.html, index.html, PREVIEW.md"
+echo "   Matrix: ${STYLE_VARIANTS}×${LAYOUT_VARIANTS} (${#PAGE_ARRAY[@]} ${MODE}s)"
+echo "   Total Files: ${TOTAL_PROTOTYPES} prototypes + preview files"
+echo ""
+echo "🌐 Next Steps:"
+echo "   1. Open: ${BASE_PATH}/index.html"
+echo "   2. Explore: ${BASE_PATH}/compare.html"
+echo "   3. Review: ${BASE_PATH}/PREVIEW.md"
+echo ""
+echo "Performance: Template-based approach with ${STYLE_VARIANTS}× speedup"
+echo "========================================="

.claude/scripts/update_module_claude.sh

@@ -1,13 +1,15 @@
 #!/bin/bash
 # Update CLAUDE.md for a specific module with automatic layer detection
-# Usage: update_module_claude.sh <module_path> [update_type]
+# Usage: update_module_claude.sh <module_path> [update_type] [tool]
 #   module_path: Path to the module directory
 #   update_type: full|related (default: full)
+#   tool: gemini|qwen|codex (default: gemini)
 #   Script automatically detects layer depth and selects appropriate template
 
 update_module_claude() {
     local module_path="$1"
     local update_type="${2:-full}"
+    local tool="${3:-gemini}"
     
     # Validate parameters
     if [ -z "$module_path" ]; then
@@ -40,30 +42,30 @@ update_module_claude() {
     if [ "$module_path" = "." ]; then
         # Root directory
         layer="Layer 1 (Root)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer1-root.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer1-root.txt"
         analysis_strategy="--all-files"
     elif [[ "$clean_path" =~ ^[^/]+$ ]]; then
         # Top-level directories (e.g., .claude, src, tests)
         layer="Layer 2 (Domain)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer2-domain.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer2-domain.txt"
         analysis_strategy="@{*/CLAUDE.md}"
     elif [[ "$clean_path" =~ ^[^/]+/[^/]+$ ]]; then
         # Second-level directories (e.g., .claude/scripts, src/components)
         layer="Layer 3 (Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer3-module.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer3-module.txt"
         analysis_strategy="@{*/CLAUDE.md}"
     else
         # Deeper directories (e.g., .claude/workflows/cli-templates/prompts)
         layer="Layer 4 (Sub-Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer4-submodule.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer4-submodule.txt"
         analysis_strategy="--all-files"
     fi
     
     # Prepare logging info
     local module_name=$(basename "$module_path")
-    
+
     echo "⚡ Updating: $module_path"
-    echo "   Layer: $layer | Type: $update_type | Files: $file_count"
+    echo "   Layer: $layer | Type: $update_type | Tool: $tool | Files: $file_count"
     echo "   Template: $(basename "$template_path") | Strategy: $analysis_strategy"
     
     # Generate prompt with template injection
@@ -106,31 +108,50 @@ update_module_claude() {
     # Execute update
     local start_time=$(date +%s)
     echo "   🔄 Starting update..."
-    
+
     if cd "$module_path" 2>/dev/null; then
-        # Execute gemini command with layer-specific analysis strategy
-        local gemini_result=0
-        if [ "$analysis_strategy" = "--all-files" ]; then
-            gemini --all-files --yolo -p "$base_prompt
+        local tool_result=0
+        local final_prompt="$base_prompt
 
         Module Information:
         - Name: $module_name
         - Path: $module_path
         - Layer: $layer
-        - Analysis Strategy: $analysis_strategy" 2>&1
-            gemini_result=$?
-        else
-            gemini --yolo -p "$analysis_strategy $base_prompt
+        - Tool: $tool
+        - Analysis Strategy: $analysis_strategy"
 
-        Module Information:
-        - Name: $module_name
-        - Path: $module_path
-        - Layer: $layer
-        - Analysis Strategy: $analysis_strategy" 2>&1
-            gemini_result=$?
-        fi
-        
-        if [ $gemini_result -eq 0 ]; then
+        # Execute with selected tool
+        case "$tool" in
+            qwen)
+                if [ "$analysis_strategy" = "--all-files" ]; then
+                    qwen --all-files --yolo -p "$final_prompt" 2>&1
+                    tool_result=$?
+                else
+                    qwen --yolo -p "$analysis_strategy $final_prompt" 2>&1
+                    tool_result=$?
+                fi
+                ;;
+            codex)
+                if [ "$analysis_strategy" = "--all-files" ]; then
+                    codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
+                    tool_result=$?
+                else
+                    codex --full-auto exec "$final_prompt CONTEXT: $analysis_strategy" --skip-git-repo-check -s danger-full-access 2>&1
+                    tool_result=$?
+                fi
+                ;;
+            gemini|*)
+                if [ "$analysis_strategy" = "--all-files" ]; then
+                    gemini --all-files --yolo -p "$final_prompt" 2>&1
+                    tool_result=$?
+                else
+                    gemini --yolo -p "$analysis_strategy $final_prompt" 2>&1
+                    tool_result=$?
+                fi
+                ;;
+        esac
+
+        if [ $tool_result -eq 0 ]; then
             local end_time=$(date +%s)
             local duration=$((end_time - start_time))
             echo "   ✅ Completed in ${duration}s"

.claude/workflows/_template-compare-matrix.html

@@ -0,0 +1,692 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>UI Design Matrix Comparison - {{run_id}}</title>
+  <style>
+    :root {
+      --color-primary: #2563eb;
+      --color-bg: #f9fafb;
+      --color-surface: #ffffff;
+      --color-border: #e5e7eb;
+      --color-text: #1f2937;
+      --color-text-secondary: #6b7280;
+    }
+
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+      background: var(--color-bg);
+      color: var(--color-text);
+      line-height: 1.6;
+    }
+
+    .container {
+      max-width: 1600px;
+      margin: 0 auto;
+      padding: 2rem;
+    }
+
+    header {
+      background: var(--color-surface);
+      padding: 1.5rem 2rem;
+      border-radius: 0.5rem;
+      margin-bottom: 2rem;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+
+    h1 {
+      color: var(--color-primary);
+      font-size: 1.875rem;
+      margin-bottom: 0.5rem;
+    }
+
+    .meta {
+      color: var(--color-text-secondary);
+      font-size: 0.875rem;
+    }
+
+    .controls {
+      background: var(--color-surface);
+      padding: 1.5rem;
+      border-radius: 0.5rem;
+      margin-bottom: 2rem;
+      display: flex;
+      gap: 1.5rem;
+      align-items: center;
+      flex-wrap: wrap;
+    }
+
+    .control-group {
+      display: flex;
+      flex-direction: column;
+      gap: 0.5rem;
+    }
+
+    label {
+      font-size: 0.875rem;
+      font-weight: 500;
+      color: var(--color-text-secondary);
+    }
+
+    select, button {
+      padding: 0.5rem 1rem;
+      border: 1px solid var(--color-border);
+      border-radius: 0.375rem;
+      font-size: 0.875rem;
+      background: white;
+      cursor: pointer;
+    }
+
+    select:focus, button:focus {
+      outline: 2px solid var(--color-primary);
+      outline-offset: 2px;
+    }
+
+    button {
+      background: var(--color-primary);
+      color: white;
+      border: none;
+      font-weight: 500;
+      transition: background 0.2s;
+    }
+
+    button:hover {
+      background: #1d4ed8;
+    }
+
+    .matrix-container {
+      background: var(--color-surface);
+      border-radius: 0.5rem;
+      overflow: hidden;
+      box-shadow: 0 1px 3px rgba(0,0,0,0.1);
+    }
+
+    .matrix-table {
+      width: 100%;
+      border-collapse: collapse;
+    }
+
+    .matrix-table th,
+    .matrix-table td {
+      border: 1px solid var(--color-border);
+      padding: 0.75rem;
+      text-align: center;
+    }
+
+    .matrix-table th {
+      background: #f3f4f6;
+      font-weight: 600;
+      color: var(--color-text);
+    }
+
+    .matrix-table thead th {
+      background: var(--color-primary);
+      color: white;
+    }
+
+    .matrix-table tbody th {
+      background: #f9fafb;
+      font-weight: 600;
+    }
+
+    .prototype-cell {
+      position: relative;
+      padding: 0;
+      height: 400px;
+      vertical-align: top;
+    }
+
+    .prototype-wrapper {
+      height: 100%;
+      display: flex;
+      flex-direction: column;
+    }
+
+    .prototype-header {
+      padding: 0.5rem;
+      background: #f9fafb;
+      border-bottom: 1px solid var(--color-border);
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      flex-shrink: 0;
+    }
+
+    .prototype-title {
+      font-size: 0.75rem;
+      font-weight: 500;
+      color: var(--color-text-secondary);
+    }
+
+    .prototype-actions {
+      display: flex;
+      gap: 0.25rem;
+    }
+
+    .icon-btn {
+      width: 24px;
+      height: 24px;
+      padding: 0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      background: transparent;
+      border: none;
+      color: var(--color-text-secondary);
+      cursor: pointer;
+      border-radius: 0.25rem;
+    }
+
+    .icon-btn:hover {
+      background: #e5e7eb;
+      color: var(--color-text);
+    }
+
+    .icon-btn.selected {
+      background: var(--color-primary);
+      color: white;
+    }
+
+    .prototype-iframe-container {
+      flex: 1;
+      position: relative;
+      overflow: hidden;
+    }
+
+    .prototype-iframe {
+      width: 100%;
+      height: 100%;
+      border: none;
+      transform-origin: top left;
+    }
+
+    .zoom-info {
+      position: absolute;
+      bottom: 0.5rem;
+      right: 0.5rem;
+      background: rgba(0,0,0,0.7);
+      color: white;
+      padding: 0.25rem 0.5rem;
+      border-radius: 0.25rem;
+      font-size: 0.75rem;
+      pointer-events: none;
+    }
+
+    .tabs {
+      display: flex;
+      gap: 0.5rem;
+      margin-bottom: 1rem;
+      border-bottom: 2px solid var(--color-border);
+    }
+
+    .tab {
+      padding: 0.75rem 1.5rem;
+      background: transparent;
+      border: none;
+      border-bottom: 2px solid transparent;
+      cursor: pointer;
+      font-weight: 500;
+      color: var(--color-text-secondary);
+      margin-bottom: -2px;
+    }
+
+    .tab.active {
+      color: var(--color-primary);
+      border-bottom-color: var(--color-primary);
+    }
+
+    .tab-content {
+      display: none;
+    }
+
+    .tab-content.active {
+      display: block;
+    }
+
+    .fullscreen-overlay {
+      display: none;
+      position: fixed;
+      top: 0;
+      left: 0;
+      right: 0;
+      bottom: 0;
+      background: rgba(0,0,0,0.95);
+      z-index: 1000;
+      padding: 2rem;
+    }
+
+    .fullscreen-overlay.active {
+      display: flex;
+      flex-direction: column;
+    }
+
+    .fullscreen-header {
+      color: white;
+      margin-bottom: 1rem;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+    }
+
+    .fullscreen-iframe {
+      flex: 1;
+      border: none;
+      background: white;
+      border-radius: 0.5rem;
+    }
+
+    .close-btn {
+      background: rgba(255,255,255,0.2);
+      color: white;
+      border: none;
+      padding: 0.5rem 1rem;
+      border-radius: 0.375rem;
+      cursor: pointer;
+    }
+
+    .close-btn:hover {
+      background: rgba(255,255,255,0.3);
+    }
+
+    .selection-summary {
+      background: #fef3c7;
+      border-left: 4px solid #f59e0b;
+      padding: 1rem;
+      margin-bottom: 2rem;
+      border-radius: 0.375rem;
+    }
+
+    .selection-summary h3 {
+      color: #92400e;
+      margin-bottom: 0.5rem;
+      font-size: 1rem;
+    }
+
+    .selection-list {
+      list-style: none;
+      color: #78350f;
+      font-size: 0.875rem;
+    }
+
+    .selection-list li {
+      padding: 0.25rem 0;
+    }
+
+    @media (max-width: 1200px) {
+      .prototype-cell {
+        height: 300px;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>🎨 UI Design Matrix Comparison</h1>
+      <div class="meta">
+        <strong>Run ID:</strong> {{run_id}} |
+        <strong>Session:</strong> {{session_id}} |
+        <strong>Generated:</strong> {{timestamp}}
+      </div>
+    </header>
+
+    <div class="controls">
+      <div class="control-group">
+        <label for="page-select">Page:</label>
+        <select id="page-select">
+          <!-- Populated by JavaScript -->
+        </select>
+      </div>
+
+      <div class="control-group">
+        <label for="zoom-level">Zoom:</label>
+        <select id="zoom-level">
+          <option value="0.25">25%</option>
+          <option value="0.5">50%</option>
+          <option value="0.75">75%</option>
+          <option value="1" selected>100%</option>
+        </select>
+      </div>
+
+      <div class="control-group">
+        <label>&nbsp;</label>
+        <button id="sync-scroll-toggle">🔗 Sync Scroll: ON</button>
+      </div>
+
+      <div class="control-group">
+        <label>&nbsp;</label>
+        <button id="export-selection">📥 Export Selection</button>
+      </div>
+    </div>
+
+    <div id="selection-summary" class="selection-summary" style="display:none">
+      <h3>Selected Prototypes (<span id="selection-count">0</span>)</h3>
+      <ul id="selection-list" class="selection-list"></ul>
+    </div>
+
+    <div class="tabs">
+      <button class="tab active" data-tab="matrix">Matrix View</button>
+      <button class="tab" data-tab="comparison">Side-by-Side</button>
+      <button class="tab" data-tab="runs">Compare Runs</button>
+    </div>
+
+    <div class="tab-content active" data-content="matrix">
+      <div class="matrix-container">
+        <table class="matrix-table">
+          <thead>
+            <tr>
+              <th>Style ↓ / Layout →</th>
+              <th>Layout 1</th>
+              <th>Layout 2</th>
+              <th>Layout 3</th>
+            </tr>
+          </thead>
+          <tbody id="matrix-body">
+            <!-- Populated by JavaScript -->
+          </tbody>
+        </table>
+      </div>
+    </div>
+
+    <div class="tab-content" data-content="comparison">
+      <p>Select two prototypes from the matrix to compare side-by-side.</p>
+      <div id="comparison-view"></div>
+    </div>
+
+    <div class="tab-content" data-content="runs">
+      <p>Compare the same prototype across different runs.</p>
+      <div id="runs-comparison"></div>
+    </div>
+  </div>
+
+  <div id="fullscreen-overlay" class="fullscreen-overlay">
+    <div class="fullscreen-header">
+      <h2 id="fullscreen-title"></h2>
+      <button class="close-btn" onclick="closeFullscreen()">✕ Close</button>
+    </div>
+    <iframe id="fullscreen-iframe" class="fullscreen-iframe"></iframe>
+  </div>
+
+  <script>
+    // Configuration - Replace with actual values during generation
+    const CONFIG = {
+      runId: "{{run_id}}",
+      sessionId: "{{session_id}}",
+      styleVariants: {{style_variants}},  // e.g., 3
+      layoutVariants: {{layout_variants}},  // e.g., 3
+      pages: {{pages_json}},  // e.g., ["dashboard", "auth"]
+      basePath: "."  // Relative path to prototypes
+    };
+
+    // State
+    let state = {
+      currentPage: CONFIG.pages[0],
+      zoomLevel: 1,
+      syncScroll: true,
+      selected: new Set(),
+      fullscreenSrc: null
+    };
+
+    // Initialize
+    document.addEventListener('DOMContentLoaded', () => {
+      populatePageSelect();
+      renderMatrix();
+      setupEventListeners();
+      loadSelectionFromStorage();
+    });
+
+    function populatePageSelect() {
+      const select = document.getElementById('page-select');
+      CONFIG.pages.forEach(page => {
+        const option = document.createElement('option');
+        option.value = page;
+        option.textContent = capitalize(page);
+        select.appendChild(option);
+      });
+    }
+
+    function renderMatrix() {
+      const tbody = document.getElementById('matrix-body');
+      tbody.innerHTML = '';
+
+      for (let s = 1; s <= CONFIG.styleVariants; s++) {
+        const row = document.createElement('tr');
+
+        // Style header cell
+        const headerCell = document.createElement('th');
+        headerCell.textContent = `Style ${s}`;
+        row.appendChild(headerCell);
+
+        // Prototype cells for each layout
+        for (let l = 1; l <= CONFIG.layoutVariants; l++) {
+          const cell = document.createElement('td');
+          cell.className = 'prototype-cell';
+
+          const filename = `${state.currentPage}-style-${s}-layout-${l}.html`;
+          const id = `${state.currentPage}-s${s}-l${l}`;
+
+          cell.innerHTML = `
+            <div class="prototype-wrapper">
+              <div class="prototype-header">
+                <span class="prototype-title">S${s}L${l}</span>
+                <div class="prototype-actions">
+                  <button class="icon-btn select-btn" data-id="${id}" title="Select">
+                    ${state.selected.has(id) ? '★' : '☆'}
+                  </button>
+                  <button class="icon-btn" onclick="openFullscreen('${filename}', 'Style ${s} Layout ${l}')" title="Fullscreen">
+                    ⛶
+                  </button>
+                  <button class="icon-btn" onclick="openInNewTab('${filename}')" title="Open in new tab">
+                    ↗
+                  </button>
+                </div>
+              </div>
+              <div class="prototype-iframe-container">
+                <iframe
+                  class="prototype-iframe"
+                  src="${filename}"
+                  data-cell="s${s}-l${l}"
+                  style="transform: scale(${state.zoomLevel});"
+                ></iframe>
+                <div class="zoom-info">${Math.round(state.zoomLevel * 100)}%</div>
+              </div>
+            </div>
+          `;
+
+          row.appendChild(cell);
+        }
+
+        tbody.appendChild(row);
+      }
+
+      // Re-attach selection event listeners
+      document.querySelectorAll('.select-btn').forEach(btn => {
+        btn.addEventListener('click', (e) => toggleSelection(e.target.dataset.id, e.target));
+      });
+
+      // Setup scroll sync
+      if (state.syncScroll) {
+        setupScrollSync();
+      }
+    }
+
+    function setupScrollSync() {
+      const iframes = document.querySelectorAll('.prototype-iframe');
+      let isScrolling = false;
+
+      iframes.forEach(iframe => {
+        iframe.addEventListener('load', () => {
+          const iframeWindow = iframe.contentWindow;
+
+          iframe.contentDocument.addEventListener('scroll', (e) => {
+            if (!state.syncScroll || isScrolling) return;
+
+            isScrolling = true;
+            const scrollTop = iframe.contentDocument.documentElement.scrollTop;
+            const scrollLeft = iframe.contentDocument.documentElement.scrollLeft;
+
+            iframes.forEach(otherIframe => {
+              if (otherIframe !== iframe && otherIframe.contentDocument) {
+                otherIframe.contentDocument.documentElement.scrollTop = scrollTop;
+                otherIframe.contentDocument.documentElement.scrollLeft = scrollLeft;
+              }
+            });
+
+            setTimeout(() => { isScrolling = false; }, 50);
+          });
+        });
+      });
+    }
+
+    function setupEventListeners() {
+      // Page selector
+      document.getElementById('page-select').addEventListener('change', (e) => {
+        state.currentPage = e.target.value;
+        renderMatrix();
+      });
+
+      // Zoom level
+      document.getElementById('zoom-level').addEventListener('change', (e) => {
+        state.zoomLevel = parseFloat(e.target.value);
+        renderMatrix();
+      });
+
+      // Sync scroll toggle
+      document.getElementById('sync-scroll-toggle').addEventListener('click', (e) => {
+        state.syncScroll = !state.syncScroll;
+        e.target.textContent = `🔗 Sync Scroll: ${state.syncScroll ? 'ON' : 'OFF'}`;
+        if (state.syncScroll) setupScrollSync();
+      });
+
+      // Export selection
+      document.getElementById('export-selection').addEventListener('click', exportSelection);
+
+      // Tab switching
+      document.querySelectorAll('.tab').forEach(tab => {
+        tab.addEventListener('click', (e) => {
+          const tabName = e.target.dataset.tab;
+          switchTab(tabName);
+        });
+      });
+    }
+
+    function toggleSelection(id, btn) {
+      if (state.selected.has(id)) {
+        state.selected.delete(id);
+        btn.textContent = '☆';
+        btn.classList.remove('selected');
+      } else {
+        state.selected.add(id);
+        btn.textContent = '★';
+        btn.classList.add('selected');
+      }
+
+      updateSelectionSummary();
+      saveSelectionToStorage();
+    }
+
+    function updateSelectionSummary() {
+      const summary = document.getElementById('selection-summary');
+      const count = document.getElementById('selection-count');
+      const list = document.getElementById('selection-list');
+
+      count.textContent = state.selected.size;
+
+      if (state.selected.size > 0) {
+        summary.style.display = 'block';
+        list.innerHTML = Array.from(state.selected)
+          .map(id => `<li>${id}</li>`)
+          .join('');
+      } else {
+        summary.style.display = 'none';
+      }
+    }
+
+    function saveSelectionToStorage() {
+      localStorage.setItem(`selection-${CONFIG.runId}`, JSON.stringify(Array.from(state.selected)));
+    }
+
+    function loadSelectionFromStorage() {
+      const stored = localStorage.getItem(`selection-${CONFIG.runId}`);
+      if (stored) {
+        state.selected = new Set(JSON.parse(stored));
+        updateSelectionSummary();
+      }
+    }
+
+    function exportSelection() {
+      const report = {
+        runId: CONFIG.runId,
+        sessionId: CONFIG.sessionId,
+        timestamp: new Date().toISOString(),
+        selections: Array.from(state.selected).map(id => ({
+          id,
+          file: `${id.replace(/-s(\d+)-l(\d+)/, '-style-$1-layout-$2')}.html`
+        }))
+      };
+
+      const blob = new Blob([JSON.stringify(report, null, 2)], { type: 'application/json' });
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `selection-${CONFIG.runId}.json`;
+      a.click();
+      URL.revokeObjectURL(url);
+
+      alert(`Exported ${state.selected.size} selections to selection-${CONFIG.runId}.json`);
+    }
+
+    function openFullscreen(src, title) {
+      const overlay = document.getElementById('fullscreen-overlay');
+      const iframe = document.getElementById('fullscreen-iframe');
+      const titleEl = document.getElementById('fullscreen-title');
+
+      iframe.src = src;
+      titleEl.textContent = title;
+      overlay.classList.add('active');
+      state.fullscreenSrc = src;
+    }
+
+    function closeFullscreen() {
+      const overlay = document.getElementById('fullscreen-overlay');
+      const iframe = document.getElementById('fullscreen-iframe');
+
+      overlay.classList.remove('active');
+      iframe.src = '';
+      state.fullscreenSrc = null;
+    }
+
+    function openInNewTab(src) {
+      window.open(src, '_blank');
+    }
+
+    function switchTab(tabName) {
+      document.querySelectorAll('.tab').forEach(tab => {
+        tab.classList.toggle('active', tab.dataset.tab === tabName);
+      });
+
+      document.querySelectorAll('.tab-content').forEach(content => {
+        content.classList.toggle('active', content.dataset.content === tabName);
+      });
+    }
+
+    function capitalize(str) {
+      return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+
+    // Close fullscreen on ESC key
+    document.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && state.fullscreenSrc) {
+        closeFullscreen();
+      }
+    });
+  </script>
+</body>
+</html>

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

@@ -0,0 +1,240 @@
+# API-Level Documentation Template
+
+Generate comprehensive API documentation following this structure:
+
+## Overview
+[Brief description of the API's purpose and capabilities]
+
+## Authentication
+### Authentication Method
+[e.g., JWT, OAuth2, API Keys]
+
+### Obtaining Credentials
+```bash
+# Example authentication flow
+```
+
+### Using Credentials
+```http
+GET /api/resource HTTP/1.1
+Authorization: Bearer <token>
+```
+
+---
+
+## Base URL
+```
+Production: https://api.example.com/v1
+Staging: https://staging.api.example.com/v1
+```
+
+## Common Response Codes
+| Code | Description |
+|------|-------------|
+| 200  | Success |
+| 201  | Created |
+| 400  | Bad Request |
+| 401  | Unauthorized |
+| 403  | Forbidden |
+| 404  | Not Found |
+| 500  | Internal Server Error |
+
+---
+
+## Endpoints
+
+### Resource: Users
+
+#### GET /users
+**Description**: Retrieves a paginated list of users.
+
+**Query Parameters**:
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `limit` | number | No | Number of results (default: 20, max: 100) |
+| `offset` | number | No | Pagination offset (default: 0) |
+| `sort` | string | No | Sort field (e.g., `name`, `-created_at`) |
+
+**Example Request**:
+```http
+GET /users?limit=10&offset=0&sort=-created_at HTTP/1.1
+Authorization: Bearer <token>
+```
+
+**Response (200 OK)**:
+```json
+{
+  "data": [
+    {
+      "id": 1,
+      "name": "John Doe",
+      "email": "john@example.com",
+      "created_at": "2024-01-01T00:00:00Z"
+    }
+  ],
+  "pagination": {
+    "total": 100,
+    "limit": 10,
+    "offset": 0
+  }
+}
+```
+
+**Error Response (401 Unauthorized)**:
+```json
+{
+  "error": {
+    "code": "UNAUTHORIZED",
+    "message": "Invalid or expired token"
+  }
+}
+```
+
+---
+
+#### GET /users/:id
+**Description**: Retrieves a single user by ID.
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | User ID |
+
+**Example Request**:
+```http
+GET /users/123 HTTP/1.1
+Authorization: Bearer <token>
+```
+
+**Response (200 OK)**:
+```json
+{
+  "id": 123,
+  "name": "John Doe",
+  "email": "john@example.com",
+  "created_at": "2024-01-01T00:00:00Z",
+  "updated_at": "2024-01-15T10:30:00Z"
+}
+```
+
+---
+
+#### POST /users
+**Description**: Creates a new user.
+
+**Request Body**:
+```json
+{
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "password": "securePassword123"
+}
+```
+
+**Validation Rules**:
+- `name`: Required, 2-100 characters
+- `email`: Required, valid email format, must be unique
+- `password`: Required, minimum 8 characters
+
+**Response (201 Created)**:
+```json
+{
+  "id": 124,
+  "name": "Jane Smith",
+  "email": "jane@example.com",
+  "created_at": "2024-01-20T12:00:00Z"
+}
+```
+
+**Error Response (400 Bad Request)**:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Email already exists"
+      }
+    ]
+  }
+}
+```
+
+---
+
+#### PUT /users/:id
+**Description**: Updates an existing user.
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | User ID |
+
+**Request Body** (all fields optional):
+```json
+{
+  "name": "Jane Doe",
+  "email": "jane.doe@example.com"
+}
+```
+
+**Response (200 OK)**:
+```json
+{
+  "id": 124,
+  "name": "Jane Doe",
+  "email": "jane.doe@example.com",
+  "updated_at": "2024-01-21T09:15:00Z"
+}
+```
+
+---
+
+#### DELETE /users/:id
+**Description**: Deletes a user.
+
+**Path Parameters**:
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `id` | number | User ID |
+
+**Response (204 No Content)**:
+[Empty response body]
+
+---
+
+## Rate Limiting
+- **Limit**: 1000 requests per hour per API key
+- **Headers**:
+  - `X-RateLimit-Limit`: Total requests allowed
+  - `X-RateLimit-Remaining`: Requests remaining
+  - `X-RateLimit-Reset`: Unix timestamp when limit resets
+
+---
+
+## SDKs and Client Libraries
+- [JavaScript/TypeScript SDK](./sdks/javascript.md)
+- [Python SDK](./sdks/python.md)
+
+---
+
+## Webhooks
+[Description of webhook system if applicable]
+
+---
+
+## Changelog
+### v1.1.0 (2024-01-20)
+- Added user sorting functionality
+- Improved error messages
+
+### v1.0.0 (2024-01-01)
+- Initial API release
+
+---
+
+**API Version**: 1.1.0
+**Last Updated**: [Auto-generated timestamp]
+**Support**: api-support@example.com

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

@@ -0,0 +1,91 @@
+# Module-Level Documentation Template
+
+Generate detailed module documentation following this structure:
+
+## 1. Purpose and Responsibilities
+[What this module does, its boundaries, and its role in the larger system]
+
+## 2. Internal Architecture
+- **Key Components**:
+  - [Component 1]: [Description and responsibility]
+  - [Component 2]: [Description and responsibility]
+- **Data Flow**: [How data moves through the module, with diagrams if applicable]
+- **Core Logic**: [Explanation of the main business logic and algorithms]
+- **State Management**: [How state is managed within the module]
+
+## 3. Public API / Interface
+### Exported Functions
+```typescript
+/**
+ * Function description
+ * @param param1 - Parameter description
+ * @returns Return value description
+ */
+export function exampleFunction(param1: Type): ReturnType;
+```
+
+### Exported Classes
+```typescript
+/**
+ * Class description
+ */
+export class ExampleClass {
+  // Public methods and properties
+}
+```
+
+### Usage Examples
+```typescript
+import { exampleFunction } from './module';
+
+// Example 1: Basic usage
+const result = exampleFunction(input);
+
+// Example 2: Advanced usage
+// ...
+```
+
+## 4. Dependencies
+### Internal Dependencies
+- **[Module A]**: [Why this dependency exists, what it provides]
+- **[Module B]**: [Purpose of dependency]
+
+### External Dependencies
+- **[Library 1]** (`version`): [Purpose and usage]
+- **[Library 2]** (`version`): [Purpose and usage]
+
+## 5. Configuration
+### Environment Variables
+- `ENV_VAR_NAME`: [Description, default value]
+
+### Configuration Options
+```typescript
+interface ModuleConfig {
+  option1: Type; // Description
+  option2: Type; // Description
+}
+```
+
+## 6. Testing
+### Running Tests
+```bash
+npm test -- module-name
+```
+
+### Test Coverage
+- Unit tests: [Coverage percentage or key test files]
+- Integration tests: [Coverage or test scenarios]
+
+## 7. Common Use Cases
+1. **Use Case 1**: [Description and code example]
+2. **Use Case 2**: [Description and code example]
+
+## 8. Troubleshooting
+### Common Issues
+- **Issue 1**: [Description and solution]
+- **Issue 2**: [Description and solution]
+
+---
+**Module Path**: [File path]
+**Last Updated**: [Auto-generated timestamp]
+**Owner/Maintainer**: [Team or individual]

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

@@ -0,0 +1,58 @@
+# Project-Level Documentation Template
+
+Generate comprehensive project documentation following this structure:
+
+## 1. Overview
+- **Purpose**: [High-level mission and goals of the project]
+- **Target Audience**: [Primary users, developers, stakeholders]
+- **Key Features**: [List of major functionalities and capabilities]
+
+## 2. System Architecture
+- **Architectural Style**: [e.g., Monolith, Microservices, Layered, Event-Driven]
+- **Core Components**: [Diagram or list of major system parts and their interactions]
+- **Technology Stack**:
+  - Languages: [Programming languages used]
+  - Frameworks: [Key frameworks and libraries]
+  - Databases: [Data storage solutions]
+  - Infrastructure: [Deployment and hosting]
+- **Design Principles**: [Guiding principles like SOLID, DRY, separation of concerns]
+
+## 3. Getting Started
+- **Prerequisites**: [Required software, tools, versions]
+- **Installation**:
+  ```bash
+  # Installation commands
+  ```
+- **Configuration**: [Environment setup, config files]
+- **Running the Project**:
+  ```bash
+  # Startup commands
+  ```
+
+## 4. Development Workflow
+- **Branching Strategy**: [e.g., GitFlow, trunk-based]
+- **Coding Standards**: [Style guide, linting rules]
+- **Testing**:
+  ```bash
+  # Test commands
+  ```
+- **Build & Deployment**: [CI/CD pipeline overview]
+
+## 5. Project Structure
+```
+project-root/
+├── src/           # [Description]
+├── tests/         # [Description]
+├── docs/          # [Description]
+└── config/        # [Description]
+```
+
+## 6. Navigation
+- [Module Documentation](./modules/)
+- [API Reference](./api/)
+- [Architecture Details](./architecture/)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+
+---
+**Last Updated**: [Auto-generated timestamp]
+**Documentation Version**: [Project version]

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

@@ -1,4 +1,4 @@
-Analyze project structure for DMS hierarchy optimization:
+Analyze project structure for memory hierarchy optimization:
 
 ## Required Analysis:
 1. Assess project complexity and file organization patterns

.claude/workflows/design-tokens-schema.md

@@ -0,0 +1,534 @@
+---
+name: design-tokens-schema
+description: Design tokens JSON schema specification for UI design workflow
+type: specification
+---
+
+# Design Tokens Schema Specification
+
+## Overview
+Standardized JSON schema for design tokens used in `/workflow:design/*` commands. Ensures consistency across style extraction, consolidation, and UI generation phases.
+
+## Core Principles
+
+1. **OKLCH Color Format**: All colors use OKLCH color space for perceptual uniformity
+2. **Semantic Naming**: User-centric token names (brand-primary, surface-elevated, not color-1, bg-2)
+3. **rem-Based Sizing**: All spacing and typography use rem units for scalability
+4. **Comprehensive Coverage**: Complete token set for production-ready design systems
+5. **Accessibility First**: WCAG AA compliance validated and documented
+
+## Full Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Design Tokens",
+  "description": "Design token definitions for UI design workflow",
+  "type": "object",
+  "required": ["colors", "typography", "spacing", "border_radius", "shadow"],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "properties": {
+        "version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
+        "generated_at": {"type": "string", "format": "date-time"},
+        "session_id": {"type": "string", "pattern": "^WFS-"},
+        "description": {"type": "string"}
+      }
+    },
+    "colors": {
+      "type": "object",
+      "required": ["brand", "surface", "semantic", "text"],
+      "properties": {
+        "brand": {
+          "type": "object",
+          "description": "Brand identity colors",
+          "required": ["primary", "secondary"],
+          "properties": {
+            "primary": {"$ref": "#/definitions/color"},
+            "secondary": {"$ref": "#/definitions/color"},
+            "accent": {"$ref": "#/definitions/color"}
+          }
+        },
+        "surface": {
+          "type": "object",
+          "description": "Surface and background colors",
+          "required": ["background", "elevated"],
+          "properties": {
+            "background": {"$ref": "#/definitions/color"},
+            "elevated": {"$ref": "#/definitions/color"},
+            "sunken": {"$ref": "#/definitions/color"},
+            "overlay": {"$ref": "#/definitions/color"}
+          }
+        },
+        "semantic": {
+          "type": "object",
+          "description": "Semantic state colors",
+          "required": ["success", "warning", "error", "info"],
+          "properties": {
+            "success": {"$ref": "#/definitions/color"},
+            "warning": {"$ref": "#/definitions/color"},
+            "error": {"$ref": "#/definitions/color"},
+            "info": {"$ref": "#/definitions/color"}
+          }
+        },
+        "text": {
+          "type": "object",
+          "description": "Text colors with WCAG AA validated contrast",
+          "required": ["primary", "secondary"],
+          "properties": {
+            "primary": {"$ref": "#/definitions/color"},
+            "secondary": {"$ref": "#/definitions/color"},
+            "tertiary": {"$ref": "#/definitions/color"},
+            "inverse": {"$ref": "#/definitions/color"},
+            "disabled": {"$ref": "#/definitions/color"}
+          }
+        },
+        "border": {
+          "type": "object",
+          "description": "Border and divider colors",
+          "properties": {
+            "subtle": {"$ref": "#/definitions/color"},
+            "default": {"$ref": "#/definitions/color"},
+            "strong": {"$ref": "#/definitions/color"}
+          }
+        }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "required": ["font_family", "font_size", "line_height", "font_weight"],
+      "properties": {
+        "font_family": {
+          "type": "object",
+          "required": ["heading", "body"],
+          "properties": {
+            "heading": {"type": "string"},
+            "body": {"type": "string"},
+            "mono": {"type": "string"}
+          }
+        },
+        "font_size": {
+          "type": "object",
+          "required": ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"],
+          "properties": {
+            "xs": {"$ref": "#/definitions/size_rem"},
+            "sm": {"$ref": "#/definitions/size_rem"},
+            "base": {"$ref": "#/definitions/size_rem"},
+            "lg": {"$ref": "#/definitions/size_rem"},
+            "xl": {"$ref": "#/definitions/size_rem"},
+            "2xl": {"$ref": "#/definitions/size_rem"},
+            "3xl": {"$ref": "#/definitions/size_rem"},
+            "4xl": {"$ref": "#/definitions/size_rem"},
+            "5xl": {"$ref": "#/definitions/size_rem"}
+          }
+        },
+        "line_height": {
+          "type": "object",
+          "required": ["tight", "normal", "relaxed"],
+          "properties": {
+            "tight": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"},
+            "normal": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"},
+            "relaxed": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"}
+          }
+        },
+        "font_weight": {
+          "type": "object",
+          "properties": {
+            "light": {"type": "integer", "enum": [300]},
+            "normal": {"type": "integer", "enum": [400]},
+            "medium": {"type": "integer", "enum": [500]},
+            "semibold": {"type": "integer", "enum": [600]},
+            "bold": {"type": "integer", "enum": [700]}
+          }
+        }
+      }
+    },
+    "spacing": {
+      "type": "object",
+      "description": "Spacing scale (rem-based)",
+      "required": ["0", "1", "2", "3", "4", "6", "8"],
+      "patternProperties": {
+        "^\\d+$": {"$ref": "#/definitions/size_rem"}
+      }
+    },
+    "border_radius": {
+      "type": "object",
+      "required": ["none", "sm", "md", "lg", "full"],
+      "properties": {
+        "none": {"type": "string", "const": "0"},
+        "sm": {"$ref": "#/definitions/size_rem"},
+        "md": {"$ref": "#/definitions/size_rem"},
+        "lg": {"$ref": "#/definitions/size_rem"},
+        "xl": {"$ref": "#/definitions/size_rem"},
+        "2xl": {"$ref": "#/definitions/size_rem"},
+        "full": {"type": "string", "const": "9999px"}
+      }
+    },
+    "shadow": {
+      "type": "object",
+      "required": ["sm", "md", "lg"],
+      "properties": {
+        "none": {"type": "string", "const": "none"},
+        "sm": {"type": "string"},
+        "md": {"type": "string"},
+        "lg": {"type": "string"},
+        "xl": {"type": "string"},
+        "2xl": {"type": "string"}
+      }
+    },
+    "breakpoint": {
+      "type": "object",
+      "description": "Responsive breakpoints",
+      "properties": {
+        "sm": {"type": "string", "pattern": "^\\d+px$"},
+        "md": {"type": "string", "pattern": "^\\d+px$"},
+        "lg": {"type": "string", "pattern": "^\\d+px$"},
+        "xl": {"type": "string", "pattern": "^\\d+px$"},
+        "2xl": {"type": "string", "pattern": "^\\d+px$"}
+      }
+    },
+    "accessibility": {
+      "type": "object",
+      "description": "WCAG AA compliance data",
+      "properties": {
+        "contrast_ratios": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {
+              "type": "object",
+              "properties": {
+                "background": {"type": "string"},
+                "foreground": {"type": "string"},
+                "ratio": {"type": "number"},
+                "wcag_aa_pass": {"type": "boolean"},
+                "wcag_aaa_pass": {"type": "boolean"}
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "color": {
+      "type": "string",
+      "pattern": "^oklch\\(\\s*\\d+(\\.\\d+)?\\s+\\d+(\\.\\d+)?\\s+\\d+(\\.\\d+)?\\s*(\\/\\s*\\d+(\\.\\d+)?)?\\s*\\)$",
+      "description": "OKLCH color format: oklch(L C H / A)"
+    },
+    "size_rem": {
+      "type": "string",
+      "pattern": "^\\d+(\\.\\d+)?rem$",
+      "description": "rem-based size value"
+    }
+  }
+}
+```
+
+## Example: Complete Design Tokens
+
+```json
+{
+  "meta": {
+    "version": "1.0.0",
+    "generated_at": "2025-10-05T15:30:00Z",
+    "session_id": "WFS-auth-dashboard",
+    "description": "Modern minimalist design system with high contrast"
+  },
+  "colors": {
+    "brand": {
+      "primary": "oklch(0.45 0.20 270 / 1)",
+      "secondary": "oklch(0.60 0.15 200 / 1)",
+      "accent": "oklch(0.65 0.18 30 / 1)"
+    },
+    "surface": {
+      "background": "oklch(0.98 0.01 270 / 1)",
+      "elevated": "oklch(1.00 0.00 0 / 1)",
+      "sunken": "oklch(0.95 0.02 270 / 1)",
+      "overlay": "oklch(0.00 0.00 0 / 0.5)"
+    },
+    "semantic": {
+      "success": "oklch(0.55 0.15 150 / 1)",
+      "warning": "oklch(0.70 0.18 60 / 1)",
+      "error": "oklch(0.50 0.20 20 / 1)",
+      "info": "oklch(0.60 0.15 240 / 1)"
+    },
+    "text": {
+      "primary": "oklch(0.20 0.02 270 / 1)",
+      "secondary": "oklch(0.45 0.02 270 / 1)",
+      "tertiary": "oklch(0.60 0.02 270 / 1)",
+      "inverse": "oklch(0.98 0.01 270 / 1)",
+      "disabled": "oklch(0.70 0.01 270 / 0.5)"
+    },
+    "border": {
+      "subtle": "oklch(0.90 0.01 270 / 1)",
+      "default": "oklch(0.80 0.02 270 / 1)",
+      "strong": "oklch(0.60 0.05 270 / 1)"
+    }
+  },
+  "typography": {
+    "font_family": {
+      "heading": "Inter, system-ui, -apple-system, sans-serif",
+      "body": "Inter, system-ui, -apple-system, sans-serif",
+      "mono": "Fira Code, Consolas, monospace"
+    },
+    "font_size": {
+      "xs": "0.75rem",
+      "sm": "0.875rem",
+      "base": "1rem",
+      "lg": "1.125rem",
+      "xl": "1.25rem",
+      "2xl": "1.5rem",
+      "3xl": "1.875rem",
+      "4xl": "2.25rem",
+      "5xl": "3rem"
+    },
+    "line_height": {
+      "tight": "1.25",
+      "normal": "1.5",
+      "relaxed": "1.75"
+    },
+    "font_weight": {
+      "light": 300,
+      "normal": 400,
+      "medium": 500,
+      "semibold": 600,
+      "bold": 700
+    }
+  },
+  "spacing": {
+    "0": "0",
+    "1": "0.25rem",
+    "2": "0.5rem",
+    "3": "0.75rem",
+    "4": "1rem",
+    "5": "1.25rem",
+    "6": "1.5rem",
+    "8": "2rem",
+    "10": "2.5rem",
+    "12": "3rem",
+    "16": "4rem",
+    "20": "5rem",
+    "24": "6rem"
+  },
+  "border_radius": {
+    "none": "0",
+    "sm": "0.25rem",
+    "md": "0.5rem",
+    "lg": "0.75rem",
+    "xl": "1rem",
+    "2xl": "1.5rem",
+    "full": "9999px"
+  },
+  "shadow": {
+    "none": "none",
+    "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
+    "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)",
+    "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)",
+    "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15), 0 10px 10px oklch(0.00 0.00 0 / 0.04)",
+    "2xl": "0 25px 50px oklch(0.00 0.00 0 / 0.25)"
+  },
+  "breakpoint": {
+    "sm": "640px",
+    "md": "768px",
+    "lg": "1024px",
+    "xl": "1280px",
+    "2xl": "1536px"
+  },
+  "accessibility": {
+    "contrast_ratios": {
+      "text_primary_on_background": {
+        "background": "oklch(0.98 0.01 270 / 1)",
+        "foreground": "oklch(0.20 0.02 270 / 1)",
+        "ratio": 14.2,
+        "wcag_aa_pass": true,
+        "wcag_aaa_pass": true
+      },
+      "brand_primary_on_background": {
+        "background": "oklch(0.98 0.01 270 / 1)",
+        "foreground": "oklch(0.45 0.20 270 / 1)",
+        "ratio": 6.8,
+        "wcag_aa_pass": true,
+        "wcag_aaa_pass": false
+      }
+    }
+  }
+}
+```
+
+## CSS Custom Properties Generation
+
+Design tokens should be converted to CSS custom properties for use in generated UI:
+
+```css
+:root {
+  /* Brand Colors */
+  --color-brand-primary: oklch(0.45 0.20 270 / 1);
+  --color-brand-secondary: oklch(0.60 0.15 200 / 1);
+  --color-brand-accent: oklch(0.65 0.18 30 / 1);
+
+  /* Surface Colors */
+  --color-surface-background: oklch(0.98 0.01 270 / 1);
+  --color-surface-elevated: oklch(1.00 0.00 0 / 1);
+  --color-surface-sunken: oklch(0.95 0.02 270 / 1);
+
+  /* Semantic Colors */
+  --color-semantic-success: oklch(0.55 0.15 150 / 1);
+  --color-semantic-warning: oklch(0.70 0.18 60 / 1);
+  --color-semantic-error: oklch(0.50 0.20 20 / 1);
+  --color-semantic-info: oklch(0.60 0.15 240 / 1);
+
+  /* Text Colors */
+  --color-text-primary: oklch(0.20 0.02 270 / 1);
+  --color-text-secondary: oklch(0.45 0.02 270 / 1);
+  --color-text-tertiary: oklch(0.60 0.02 270 / 1);
+
+  /* Typography */
+  --font-family-heading: Inter, system-ui, sans-serif;
+  --font-family-body: Inter, system-ui, sans-serif;
+  --font-family-mono: Fira Code, Consolas, monospace;
+
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+  --font-size-xl: 1.25rem;
+  --font-size-2xl: 1.5rem;
+  --font-size-3xl: 1.875rem;
+  --font-size-4xl: 2.25rem;
+
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+
+  /* Spacing */
+  --spacing-0: 0;
+  --spacing-1: 0.25rem;
+  --spacing-2: 0.5rem;
+  --spacing-3: 0.75rem;
+  --spacing-4: 1rem;
+  --spacing-6: 1.5rem;
+  --spacing-8: 2rem;
+  --spacing-12: 3rem;
+  --spacing-16: 4rem;
+
+  /* Border Radius */
+  --border-radius-none: 0;
+  --border-radius-sm: 0.25rem;
+  --border-radius-md: 0.5rem;
+  --border-radius-lg: 0.75rem;
+  --border-radius-xl: 1rem;
+  --border-radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px oklch(0.00 0.00 0 / 0.05);
+  --shadow-md: 0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06);
+  --shadow-lg: 0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05);
+}
+```
+
+## Tailwind Configuration Generation
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          primary: 'oklch(0.45 0.20 270 / <alpha-value>)',
+          secondary: 'oklch(0.60 0.15 200 / <alpha-value>)',
+          accent: 'oklch(0.65 0.18 30 / <alpha-value>)'
+        },
+        surface: {
+          background: 'oklch(0.98 0.01 270 / <alpha-value>)',
+          elevated: 'oklch(1.00 0.00 0 / <alpha-value>)',
+          sunken: 'oklch(0.95 0.02 270 / <alpha-value>)'
+        },
+        semantic: {
+          success: 'oklch(0.55 0.15 150 / <alpha-value>)',
+          warning: 'oklch(0.70 0.18 60 / <alpha-value>)',
+          error: 'oklch(0.50 0.20 20 / <alpha-value>)',
+          info: 'oklch(0.60 0.15 240 / <alpha-value>)'
+        }
+      },
+      fontFamily: {
+        heading: ['Inter', 'system-ui', 'sans-serif'],
+        body: ['Inter', 'system-ui', 'sans-serif'],
+        mono: ['Fira Code', 'Consolas', 'monospace']
+      },
+      fontSize: {
+        'xs': '0.75rem',
+        'sm': '0.875rem',
+        'base': '1rem',
+        'lg': '1.125rem',
+        'xl': '1.25rem',
+        '2xl': '1.5rem',
+        '3xl': '1.875rem',
+        '4xl': '2.25rem'
+      },
+      spacing: {
+        '1': '0.25rem',
+        '2': '0.5rem',
+        '3': '0.75rem',
+        '4': '1rem',
+        '6': '1.5rem',
+        '8': '2rem',
+        '12': '3rem',
+        '16': '4rem'
+      },
+      borderRadius: {
+        'sm': '0.25rem',
+        'md': '0.5rem',
+        'lg': '0.75rem',
+        'xl': '1rem',
+        '2xl': '1.5rem'
+      },
+      boxShadow: {
+        'sm': '0 1px 2px oklch(0.00 0.00 0 / 0.05)',
+        'md': '0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)',
+        'lg': '0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)'
+      }
+    }
+  }
+}
+```
+
+## Validation Requirements
+
+### Color Validation
+- All colors MUST use OKLCH format
+- Alpha channel optional (defaults to 1)
+- Lightness: 0-1 (0% to 100%)
+- Chroma: 0-0.4 (typical range, can exceed for vibrant colors)
+- Hue: 0-360 (degrees)
+
+### Accessibility Validation
+- Text on background: minimum 4.5:1 contrast (WCAG AA)
+- Large text (18pt+ or 14pt+ bold): minimum 3:1 contrast
+- UI components: minimum 3:1 contrast
+- Non-text focus indicators: minimum 3:1 contrast
+
+### Consistency Validation
+- Spacing scale maintains consistent ratio (e.g., 1.5x or 2x progression)
+- Typography scale follows modular scale principles
+- Border radius values progress logically
+- Shadow layers increase in offset and blur systematically
+
+## Usage in Commands
+
+### style-extract Output
+Generates initial `design-tokens.json` from visual analysis
+
+### style-consolidate Output
+Finalizes validated `design-tokens.json` with accessibility data
+
+### ui-generate Input
+Reads `design-tokens.json` to generate CSS custom properties
+
+### design-update Integration
+References `design-tokens.json` path in synthesis-specification.md
+
+## Version History
+
+- **1.0.0**: Initial schema with OKLCH colors, semantic naming, WCAG AA validation

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

@@ -6,11 +6,22 @@ type: strategic-guideline
 
 # Intelligent Tools Selection Strategy
 
+## 📋 Table of Contents
+1. [Core Framework](#-core-framework)
+2. [Tool Specifications](#-tool-specifications)
+3. [Command Templates](#-command-templates)
+4. [Tool Selection Guide](#-tool-selection-guide)
+5. [Usage Patterns](#-usage-patterns)
+6. [Best Practices](#-best-practices)
+
+---
+
 ## ⚡ Core Framework
 
-**Gemini**: Analysis, understanding, exploration & documentation
-**Qwen**: Architecture analysis, code generation & implementation
-**Codex**: Development, implementation & automation
+### Tool Overview
+- **Gemini**: Analysis, understanding, exploration & documentation
+- **Qwen**: Architecture analysis, code generation & implementation
+- **Codex**: Development, implementation & automation
 
 ### Decision Principles
 - **Use tools early and often** - Tools are faster, more thorough, and reliable than manual approaches
@@ -18,6 +29,7 @@ type: strategic-guideline
 - **Default to tools** - Use specialized tools for most coding tasks, no matter how small
 - **Lower barriers** - Engage tools immediately when encountering any complexity
 - **Context optimization** - Based on user intent, determine whether to use `-C [directory]` parameter for focused analysis to reduce irrelevant context import
+- **⚠️ Write operation protection** - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto
 
 ### Quick Decision Rules
 1. **Exploring/Understanding?** → Start with Gemini
@@ -26,32 +38,118 @@ type: strategic-guideline
 4. **Not sure?** → Use multiple tools in parallel
 5. **Small task?** → Still use tools - they're faster than manual work
 
-### Core Execution Rules
-- **Default Timeout**: Bash commands default execution time = 20 minutes (1200000ms)
-- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions use this timeout
-- **Command Examples**: `bash(cd target/directory && ~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(cd target/directory && ~/.claude/scripts/qwen-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
-- **Override When Needed**: Specify custom timeout for longer operations
+---
 
-### Permission Framework
-- **Gemini/Qwen Write Access**: Use `--approval-mode yolo` when tools need to create/modify files
-- **Codex Write Access**: Always use `-s danger-full-access` and `--skip-git-repo-check` for development and file operations
-- **Auto-approval Protocol**: Enable automatic tool approvals for autonomous workflow execution
+## 🎯 Tool Specifications
 
-## 🎯 Universal Command Template
+### Gemini
+- **Command**: `~/.claude/scripts/gemini-wrapper`
+- **Strengths**: Large context window, pattern recognition
+- **Best For**: Analysis, documentation generation, code exploration
+- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
+- **Default MODE**: `analysis` (read-only)
+- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
 
-### Standard Format (REQUIRED)
+#### MODE Options
+- `analysis` (default) - Read-only analysis and documentation generation
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
+
+### Qwen
+- **Command**: `~/.claude/scripts/qwen-wrapper`
+- **Strengths**: Architecture analysis, pattern recognition
+- **Best For**: System design analysis, architectural review
+- **Permissions**: Architecture analysis only, no automatic code generation
+- **Default MODE**: `analysis` (read-only)
+- **⚠️ Write Trigger**: Explicitly prohibited from auto-calling write mode
+
+#### MODE Options
+- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
+- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
+
+### Codex
+- **Command**: `codex --full-auto exec`
+- **Strengths**: Autonomous development, mathematical reasoning
+- **Best For**: Implementation, testing, automation
+- **Permissions**: Requires explicit MODE=auto or MODE=write specification
+- **Default MODE**: No default, must be explicitly specified
+- **⚠️ Write Trigger**: Only when user explicitly requests "implement", "modify", "generate code" AND specifies MODE
+
+#### MODE Options
+- `auto` - ⚠️ Autonomous development with full file operations (requires explicit specification, enables -s danger-full-access)
+- `write` - ⚠️ Test generation and file modification (requires explicit specification)
+- **Default**: No default mode, MODE must be explicitly specified
+
+#### Session Management
+- `codex resume` - Resume previous interactive session (picker by default)
+- `codex exec "task" resume --last` - Continue most recent session with new task (maintains context)
+- `codex -i <image_file>` - Attach image(s) to initial prompt (useful for UI/design references)
+- **Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
+  - **Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END
+  - **Example**:
+    ```bash
+    # First task - establish session
+    codex -C project --full-auto exec "Implement auth module" --skip-git-repo-check -s danger-full-access
+
+    # Subsequent tasks - continue same session
+    codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
+    codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access
+    ```
+
+#### Auto-Resume Decision Rules
+**When to use `resume --last`**:
+- Current task is related to/extends previous Codex task in conversation memory
+- Current task requires context from previous implementation
+- Current task is part of multi-step workflow (e.g., implement → enhance → test)
+- Session memory indicates recent Codex execution on same module/feature
+
+**When NOT to use `resume --last`**:
+- First Codex task in conversation
+- New independent task unrelated to previous work
+- Switching to different module/feature area
+- No recent Codex task in conversation memory
+
+---
+
+## 🎯 Command Templates
+
+### Universal Template Structure
+Every command MUST follow this structure:
+- [ ] **PURPOSE** - Clear goal and intent
+- [ ] **TASK** - Specific execution task
+- [ ] **MODE** - Execution mode and permission level
+- [ ] **CONTEXT** - File references and memory context from previous sessions
+- [ ] **EXPECTED** - Clear expected results
+- [ ] **RULES** - Template reference and constraints
+
+### Standard Command Formats
+
+#### Gemini Commands
 ```bash
-# Gemini Analysis (全权限)
+# Gemini Analysis (read-only, default)
 cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: [clear analysis goal]
 TASK: [specific analysis task]
-MODE: [analysis|write]
+MODE: analysis
 CONTEXT: [file references and memory context]
 EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 
-# Qwen Architecture Analysis (仅分析)
+# Gemini Write Mode (requires explicit MODE=write)
+# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
+cd [directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+PURPOSE: [clear goal]
+TASK: [specific task]
+MODE: write
+CONTEXT: [file references and memory context]
+EXPECTED: [expected output]
+RULES: [template reference and constraints]
+"
+```
+
+#### Qwen Commands
+```bash
+# Qwen Architecture Analysis (read-only, default)
 cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: [clear architecture goal]
 TASK: [specific analysis task]
@@ -61,41 +159,44 @@ EXPECTED: [expected deliverables]
 RULES: [template reference and constraints]
 "
 
-# Codex Development
+# Qwen Write Mode (requires explicit MODE=write)
+# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
+cd [directory] && ~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "
+PURPOSE: [clear goal]
+TASK: [specific task]
+MODE: write
+CONTEXT: [file references and memory context]
+EXPECTED: [expected deliverables]
+RULES: [template reference and constraints]
+"
+```
+
+#### Codex Commands
+```bash
+# Codex Development (requires explicit MODE=auto)
+# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
 codex -C [directory] --full-auto exec "
 PURPOSE: [clear development goal]
 TASK: [specific development task]
-MODE: [auto|write]
+MODE: auto
+CONTEXT: [file references and memory context]
+EXPECTED: [expected deliverables]
+RULES: [template reference and constraints]
+" --skip-git-repo-check -s danger-full-access
+
+# Codex Test/Write Mode (requires explicit MODE=write)
+# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
+codex -C [directory] --full-auto exec "
+PURPOSE: [clear goal]
+TASK: [specific task]
+MODE: write
 CONTEXT: [file references and memory context]
 EXPECTED: [expected deliverables]
 RULES: [template reference and constraints]
 " --skip-git-repo-check -s danger-full-access
 ```
 
-### Template Structure
-- [ ] **PURPOSE** - Clear goal and intent
-- [ ] **TASK** - Specific execution task
-- [ ] **MODE** - Execution mode and permission level
-- [ ] **CONTEXT** - File references and memory context from previous sessions
-- [ ] **EXPECTED** - Clear expected results
-- [ ] **RULES** - Template reference and constraints
-
-### MODE Field Definition
-
-The MODE field controls execution behavior and file permissions:
-
-**For Gemini** (全权限，可读写):
-- `analysis` (default) - 分析 + 可生成文档
-- `write` - 创建/修改文件（自动启用 --approval-mode yolo）
-
-**For Qwen** (仅分析):
-- `analysis` (default) - 仅架构分析，不生成代码
-
-**For Codex**:
-- `auto` (default) - 自主开发，全文件操作
-- `write` - 测试生成和文件修改
-
-### Directory Context
+### Directory Context Configuration
 Tools execute in current working directory:
 - **Gemini**: `cd path/to/project && ~/.claude/scripts/gemini-wrapper -p "prompt"`
 - **Qwen**: `cd path/to/project && ~/.claude/scripts/qwen-wrapper -p "prompt"`
@@ -103,7 +204,7 @@ Tools execute in current working directory:
 - **Path types**: Supports both relative (`../project`) and absolute (`/full/path`) paths
 - **Token analysis**: For gemini-wrapper and qwen-wrapper, token counting happens in current directory
 
-### Rules Field Format
+### RULES Field Format
 ```bash
 RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].txt") | [constraints]
 ```
@@ -114,7 +215,44 @@ RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].tx
 - No template: `Focus on security patterns, include dependency analysis`
 - File patterns: `@{src/**/*.ts,CLAUDE.md} - Stay within scope`
 
-## 📊 Tool Selection Matrix
+### File Pattern Reference
+- All files: `@{**/*}`
+- Source files: `@{src/**/*}`
+- TypeScript: `@{*.ts,*.tsx}`
+- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
+- Tests: `@{src/**/*.test.*}`
+
+**Complex Pattern Discovery**:
+For complex file pattern requirements, use semantic discovery tools BEFORE CLI execution:
+- **rg (ripgrep)**: Content-based file discovery with regex patterns
+- **Code Index MCP**: Semantic file search based on task requirements
+- **Workflow**: Discover → Extract precise paths → Build CONTEXT field
+
+**Example**:
+```bash
+# Step 1: Discover files semantically
+rg "export.*Component" --files-with-matches --type ts  # Find component files
+mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")  # Find interface files
+
+# Step 2: Build precise CONTEXT from discovery results
+CONTEXT: @{src/components/Auth.tsx,src/types/auth.d.ts,src/hooks/useAuth.ts}
+
+# Step 3: Execute CLI with precise file references
+cd src && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze authentication components
+TASK: Review auth component patterns and props interfaces
+MODE: analysis
+CONTEXT: @{components/Auth.tsx,types/auth.d.ts,hooks/useAuth.ts}
+EXPECTED: Pattern analysis and improvement suggestions
+RULES: Focus on type safety and component composition
+"
+```
+
+---
+
+## 📊 Tool Selection Guide
+
+### Selection Matrix
 
 | Task Type | Tool | Use Case | Template |
 |-----------|------|----------|-----------|
@@ -127,11 +265,11 @@ RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].tx
 | **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
 | **Refactoring** | Multiple | Gemini for analysis, Qwen/Codex for execution | `development/refactor.txt` |
 
-## 📁 Template System
+### Template System
 
 **Base Structure**: `~/.claude/workflows/cli-templates/`
 
-### Available Templates
+#### Available Templates
 ```
 prompts/
 ├── analysis/
@@ -157,6 +295,8 @@ tech-stacks/
 └── react-dev.md         - React architecture
 ```
 
+---
+
 ## 🚀 Usage Patterns
 
 ### Workflow Integration (REQUIRED)
@@ -168,8 +308,9 @@ When planning any coding task, **ALWAYS** integrate CLI tools:
 4. **Quality Phase**: Use Codex for testing and validation
 
 ### Common Scenarios
+
+#### Code Analysis
 ```bash
-# Gemini - Code Analysis
 ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: Understand codebase architecture
 TASK: Analyze project structure and identify patterns
@@ -178,8 +319,10 @@ CONTEXT: @{src/**/*.ts,CLAUDE.md} Previous analysis of auth system
 EXPECTED: Architecture overview and integration points
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on integration points
 "
+```
 
-# Gemini - Generate Documentation
+#### Documentation Generation
+```bash
 ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: Generate API documentation
 TASK: Create comprehensive API reference from code
@@ -188,8 +331,10 @@ CONTEXT: @{src/api/**/*}
 EXPECTED: API.md with all endpoints documented
 RULES: Follow project documentation standards
 "
+```
 
-# Qwen - Architecture Analysis
+#### Architecture Analysis
+```bash
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze authentication system architecture
 TASK: Review JWT-based auth system design
@@ -198,8 +343,11 @@ CONTEXT: @{src/auth/**/*} Existing patterns and requirements
 EXPECTED: Architecture analysis report with recommendations
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on security
 "
+```
 
-# Codex - Feature Development
+#### Feature Development (Multi-task with Resume)
+```bash
+# First task - establish session
 codex -C path/to/project --full-auto exec "
 PURPOSE: Implement user authentication
 TASK: Create JWT-based authentication system
@@ -209,66 +357,46 @@ EXPECTED: Complete auth module with tests
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/development/feature.txt') | Follow security best practices
 " --skip-git-repo-check -s danger-full-access
 
-# Codex - Test Generation
-codex -C src/auth --full-auto exec "
+# Continue in same session - Add JWT validation
+codex --full-auto exec "
+PURPOSE: Enhance authentication security
+TASK: Add JWT token validation and refresh logic
+MODE: auto
+CONTEXT: Previous auth implementation from current session
+EXPECTED: JWT validation middleware and token refresh endpoints
+RULES: Follow JWT best practices, maintain session context
+" resume --last --skip-git-repo-check -s danger-full-access
+
+# Continue in same session - Add tests
+codex --full-auto exec "
 PURPOSE: Increase test coverage
 TASK: Generate comprehensive tests for auth module
 MODE: write
-CONTEXT: @{**/*.ts} Exclude existing tests
+CONTEXT: Auth implementation from current session
 EXPECTED: Complete test suite with 80%+ coverage
 RULES: Use Jest, follow existing patterns
-" --skip-git-repo-check -s danger-full-access
+" resume --last --skip-git-repo-check -s danger-full-access
 ```
 
-## 📋 Planning Checklist
+#### Interactive Session Resume
+```bash
+# Resume previous session with picker
+codex resume
 
-For every development task:
-- [ ] **Purpose defined** - Clear goal and intent
-- [ ] **Mode selected** - Execution mode and permission level determined
-- [ ] **Context gathered** - File references and session memory documented
-- [ ] **Gemini analysis** completed for understanding
-- [ ] **Template selected** - Appropriate template chosen
-- [ ] **Constraints specified** - File patterns, scope, requirements
-- [ ] **Implementation approach** - Tool selection and workflow
-- [ ] **Quality measures** - Testing and validation plan
-- [ ] **Tool configuration** - Review `.gemini/CLAUDE.md` or `.codex/Agent.md` if needed
+# Or resume most recent session directly
+codex resume --last
+```
 
-## 🎯 Key Features
-
-### Gemini (全权限)
-- **Command**: `~/.claude/scripts/gemini-wrapper`
-- **Strengths**: Large context window, pattern recognition
-- **Best For**: Analysis, documentation generation, code exploration
-- **Permissions**: 可读写，MODE=write 时自动启用 --approval-mode yolo
-- **Default MODE**: `analysis`
-
-### Qwen (仅分析)
-- **Command**: `~/.claude/scripts/qwen-wrapper`
-- **Strengths**: Architecture analysis, pattern recognition
-- **Best For**: System design analysis, architectural review
-- **Permissions**: 仅分析，不生成代码
-- **Default MODE**: `analysis`
-
-### Codex
-- **Command**: `codex --full-auto exec`
-- **Strengths**: Autonomous development, mathematical reasoning
-- **Best For**: Implementation, testing, automation
-- **Required**: `-s danger-full-access` and `--skip-git-repo-check` for development
-- **Default MODE**: `auto`
-
-### File Patterns
-- All files: `@{**/*}`
-- Source files: `@{src/**/*}`
-- TypeScript: `@{*.ts,*.tsx}`
-- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
-- Tests: `@{src/**/*.test.*}`
+---
 
 ## 🔧 Best Practices
 
+### General Guidelines
 - **Start with templates** - Use predefined templates for consistency
 - **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields
 - **Include constraints** - File patterns, scope, requirements in RULES
-- **Test patterns first** - Validate file patterns with `ls`
+- **Discover patterns first** - Use rg/MCP for complex file discovery before CLI execution
+- **Build precise CONTEXT** - Convert discovery results to explicit file references
 - **Document context** - Always reference CLAUDE.md for context
 
 ### Context Optimization Strategy
@@ -310,4 +438,42 @@ CONTEXT: @{**/*.ts}
 EXPECTED: Code improvements and fixes
 RULES: Maintain backward compatibility
 " --skip-git-repo-check -s danger-full-access
-```
+```
+
+### Planning Checklist
+
+For every development task:
+- [ ] **Purpose defined** - Clear goal and intent
+- [ ] **Mode selected** - Execution mode and permission level determined
+- [ ] **Context gathered** - File references and session memory documented
+- [ ] **Gemini analysis** completed for understanding
+- [ ] **Template selected** - Appropriate template chosen
+- [ ] **Constraints specified** - File patterns, scope, requirements
+- [ ] **Implementation approach** - Tool selection and workflow
+- [ ] **Quality measures** - Testing and validation plan
+- [ ] **Tool configuration** - Review `.gemini/CLAUDE.md` or `.codex/Agent.md` if needed
+
+---
+
+## ⚙️ Execution Configuration
+
+### Core Execution Rules
+- **Dynamic Timeout (20-120min)**: Allocate execution time based on task complexity
+  - Simple tasks (analysis, search): 20-40min (1200000-2400000ms)
+  - Medium tasks (refactoring, documentation): 40-60min (2400000-3600000ms)
+  - Complex tasks (implementation, migration): 60-120min (3600000-7200000ms)
+- **Codex Multiplier**: Codex commands use 1.5x of allocated time
+- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions
+- **Command Examples**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
+- **Auto-detect**: Analyze PURPOSE and TASK fields to determine appropriate timeout
+
+### Permission Framework
+- **⚠️ WRITE PROTECTION**: Local codebase write/modify requires EXPLICIT user confirmation
+  - **Analysis Mode (default)**: Read-only, safe for auto-execution
+  - **Write Mode**: Requires user explicitly states MODE=write or MODE=auto in prompt
+  - **Exception**: User provides clear instructions like "modify", "create", "implement"
+- **Gemini/Qwen Write Access**: Use `--approval-mode yolo` ONLY when MODE=write explicitly specified
+  - **Parameter Position**: Place AFTER the wrapper command: `gemini-wrapper --approval-mode yolo -p "..."`
+- **Codex Write Access**: Use `-s danger-full-access` and `--skip-git-repo-check` ONLY when MODE=auto explicitly specified
+  - **Parameter Position**: Place AFTER the prompt string at command END: `codex ... exec "..." --skip-git-repo-check -s danger-full-access`
+- **Default Behavior**: All tools default to analysis/read-only mode without explicit write permission

.claude/workflows/workflow-architecture.md

@@ -266,28 +266,105 @@ All workflows use the same file structure definition regardless of complexity. *
 
 #### Complete Structure Reference
 ```
-.workflow/WFS-[topic-slug]/
-├── workflow-session.json        # Session metadata and state (REQUIRED)
-├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
-├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
-│   ├── chat-*.md              # Saved chat sessions
-│   └── analysis-*.md          # Analysis results
-├── [.process/]                 # Planning analysis results (created by /workflow:plan)
-│   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
-├── IMPL_PLAN.md                # Planning document (REQUIRED)
-├── TODO_LIST.md                # Progress tracking (REQUIRED)
-├── [.summaries/]               # Task completion summaries (created when tasks complete)
-│   ├── IMPL-*-summary.md      # Main task summaries
-│   └── IMPL-*.*-summary.md    # Subtask summaries
-└── .task/                      # Task definitions (REQUIRED)
-    ├── IMPL-*.json             # Main task definitions
-    └── IMPL-*.*.json           # Subtask definitions (created dynamically)
+.workflow/
+├── [.scratchpad/]              # Non-session-specific outputs (created when needed)
+│   ├── analyze-*-[timestamp].md        # One-off analysis results
+│   ├── chat-*-[timestamp].md           # Standalone chat sessions
+│   ├── plan-*-[timestamp].md           # Ad-hoc planning notes
+│   ├── bug-index-*-[timestamp].md      # Quick bug analyses
+│   ├── code-analysis-*-[timestamp].md  # Standalone code analysis
+│   ├── 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
+│       ├── style-extraction/   # Style analysis results
+│       ├── style-consolidation/ # Design system tokens (per-style)
+│       │   ├── style-1/        # design-tokens.json, style-guide.md
+│       │   └── style-N/
+│       ├── prototypes/         # Generated HTML/CSS prototypes
+│       │   ├── _templates/     # Target-specific layout plans and templates
+│       │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+│       │   │   ├── {target}-layout-{n}.html  # HTML template
+│       │   │   └── {target}-layout-{n}.css   # CSS template
+│       │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+│       │   ├── compare.html    # Interactive matrix view
+│       │   └── index.html      # Navigation page
+│       └── .run-metadata.json  # Run configuration
+│
+└── WFS-[topic-slug]/
+    ├── workflow-session.json        # Session metadata and state (REQUIRED)
+    ├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
+    ├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
+    │   ├── chat-*.md              # Saved chat sessions
+    │   └── analysis-*.md          # Analysis results
+    ├── [.process/]                 # Planning analysis results (created by /workflow:plan)
+    │   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
+    ├── IMPL_PLAN.md                # Planning document (REQUIRED)
+    ├── TODO_LIST.md                # Progress tracking (REQUIRED)
+    ├── [.summaries/]               # Task completion summaries (created when tasks complete)
+    │   ├── IMPL-*-summary.md      # Main task summaries
+    │   └── IMPL-*.*-summary.md    # Subtask summaries
+    ├── [design-*/]                 # UI design outputs (created by ui-design workflows)
+    │   ├── style-extraction/       # Style analysis results
+    │   ├── style-consolidation/    # Design system tokens (per-style)
+    │   │   ├── style-1/            # design-tokens.json, style-guide.md
+    │   │   └── style-N/
+    │   ├── prototypes/             # Generated HTML/CSS prototypes
+    │   │   ├── _templates/         # Target-specific layout plans and templates
+    │   │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+    │   │   │   ├── {target}-layout-{n}.html  # HTML template
+    │   │   │   └── {target}-layout-{n}.css   # CSS template
+    │   │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+    │   │   ├── compare.html        # Interactive matrix view
+    │   │   └── index.html          # Navigation page
+    │   └── .run-metadata.json      # Run configuration
+    └── .task/                      # Task definitions (REQUIRED)
+        ├── IMPL-*.json             # Main task definitions
+        └── IMPL-*.*.json           # Subtask definitions (created dynamically)
 ```
 
 #### Creation Strategy
 - **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
 - **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
+- **Layout Planning**: `prototypes/_templates/` contains target-specific layout plans (JSON) generated during UI generation phase
+
+#### Scratchpad Directory (.scratchpad/)
+**Purpose**: Centralized location for non-session-specific CLI outputs
+
+**When to Use**:
+1. **No Active Session**: CLI analysis/chat commands run without an active workflow session
+2. **Unrelated Analysis**: Quick analysis not related to current active session
+3. **Exploratory Work**: Ad-hoc investigation before creating formal workflow
+4. **One-Off Queries**: Standalone questions or debugging without workflow context
+
+**Output Routing Logic**:
+- **IF** active session exists AND command is session-relevant:
+  - Save to `.workflow/WFS-[id]/.chat/[command]-[timestamp].md`
+- **ELSE** (no session OR one-off analysis):
+  - Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md`
+
+**File Naming Pattern**: `[command-type]-[brief-description]-[timestamp].md`
+
+**Examples**:
+
+*Analysis Commands (read-only):*
+- `/cli:analyze "security"` (no session) → `.scratchpad/analyze-security-20250105-143022.md`
+- `/cli:chat "build process"` (unrelated to active session) → `.scratchpad/chat-build-process-20250105-143045.md`
+- `/cli:mode:plan "feature idea"` (exploratory) → `.scratchpad/plan-feature-idea-20250105-143110.md`
+- `/cli:mode:code-analysis "trace auth flow"` (no session) → `.scratchpad/code-analysis-auth-flow-20250105-143130.md`
+
+*Implementation Commands (⚠️ modifies code):*
+- `/cli:execute "implement JWT auth"` (no session) → `.scratchpad/execute-jwt-auth-20250105-143200.md`
+- `/cli:codex-execute "refactor API layer"` (no session) → `.scratchpad/codex-execute-api-refactor-20250105-143230.md`
+
+**Maintenance**:
+- Periodically review and clean up old scratchpad files
+- Promote useful analyses to formal workflow sessions if needed
+- No automatic cleanup - manual management recommended
 
 ### File Naming Conventions
 

.codex/AGENTS.md

@@ -6,6 +6,8 @@
 
 ## Prompt Structure
 
+### Single-Task Format
+
 **Receive prompts in this format**:
 
 ```
@@ -17,11 +19,61 @@ EXPECTED: [deliverables]
 RULES: [constraints and templates]
 ```
 
+### Multi-Task Format (Subtask Execution)
+
+**First subtask** (creates new session):
+```
+PURPOSE: [overall goal]
+TASK: [subtask 1 description]
+MODE: auto
+CONTEXT: [file patterns]
+EXPECTED: [subtask deliverables]
+RULES: [constraints]
+Subtask 1 of N: [subtask title]
+```
+
+**Subsequent subtasks** (continues via `resume --last`):
+```
+CONTINUE TO NEXT SUBTASK:
+Subtask N of M: [subtask title]
+
+PURPOSE: [continuation goal]
+TASK: [subtask N description]
+CONTEXT: Previous work completed, now focus on [new files]
+EXPECTED: [subtask deliverables]
+RULES: Build on previous subtask, maintain consistency
+```
+
 ## Execution Requirements
 
+### System Optimization
+
+**Hard Requirement**: Call binaries directly in `functions.shell`, always set `workdir`, and avoid shell wrappers such as `bash -lc`, `sh -lc`, `zsh -lc`, `cmd /c`, `pwsh.exe -NoLogo -NoProfile -Command`, and `powershell.exe -NoLogo -NoProfile -Command`.
+
+**Text Editing Priority**: Use the `apply_patch` tool for all routine text edits; fall back to `sed` for single-line substitutions only if `apply_patch` is unavailable, and avoid `python` editing scripts unless both options fail.
+
+**`apply_patch` Usage**: Invoke `apply_patch` with the patch payload as the second element in the command array (no shell-style flags). Provide `workdir` and, when helpful, a short `justification` alongside the command.
+
+**Example invocation**:
+```json
+{
+  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
+  "workdir": "<workdir>",
+  "justification": "Brief reason for the change"
+}
+```
+
+**Windows UTF-8 Encoding**: Before executing commands on Windows systems, ensure proper UTF-8 encoding by running:
+```powershell
+[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+chcp 65001 > $null
+```
+
 ### ALWAYS
 
-- **Parse all six fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
+- **Parse all fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
+- **Detect subtask format** - Check for "Subtask N of M" or "CONTINUE TO NEXT SUBTASK"
 - **Follow MODE strictly** - Respect execution boundaries
 - **Study CONTEXT files** - Find 3+ similar patterns before implementing
 - **Apply RULES** - Follow templates and constraints exactly
@@ -29,6 +81,10 @@ RULES: [constraints and templates]
 - **Commit incrementally** - Small, working commits
 - **Match project style** - Follow existing patterns exactly
 - **Validate EXPECTED** - Ensure all deliverables are met
+- **Report context** (subtasks) - Summarize key info for next subtask
+- **Use direct binary calls** - Avoid shell wrappers for efficiency
+- **Prefer apply_patch** - Use for text edits over Python scripts
+- **Configure Windows encoding** - Set UTF-8 for Chinese character support
 
 ### NEVER
 
@@ -49,7 +105,7 @@ RULES: [constraints and templates]
 - Run tests and builds
 - Commit code incrementally
 
-**Execute**:
+**Execute (Single Task)**:
 1. Parse PURPOSE and TASK
 2. Analyze CONTEXT files - find 3+ similar patterns
 3. Plan implementation approach
@@ -60,7 +116,17 @@ RULES: [constraints and templates]
 8. Validate all EXPECTED deliverables
 9. Report results
 
-**Use For**: Feature implementation, bug fixes, refactoring
+**Execute (Multi-Task/Subtask)**:
+1. **First subtask**: Follow single-task flow above
+2. **Subsequent subtasks** (via `resume --last`):
+   - Recall context from previous subtask(s)
+   - Build on previous work (don't repeat)
+   - Maintain consistency with previous decisions
+   - Focus on current subtask scope only
+   - Test integration with previous subtasks
+   - Report subtask completion status
+
+**Use For**: Feature implementation, bug fixes, refactoring, multi-step tasks
 
 ### MODE: write
 
@@ -119,7 +185,7 @@ RULES: [constraints and templates]
 
 ## Progress Reporting
 
-### During Execution
+### During Execution (Single Task)
 
 ```
 [1/5] Analyzing existing code patterns...
@@ -129,7 +195,17 @@ RULES: [constraints and templates]
 [5/5] Running validation...
 ```
 
-### On Success
+### During Execution (Subtask)
+
+```
+[Subtask N/M: Subtask Title]
+[1/4] Recalling context from previous subtasks...
+[2/4] Implementing current subtask...
+[3/4] Testing integration with previous work...
+[4/4] Validating subtask completion...
+```
+
+### On Success (Single Task)
 
 ```
 ✅ Task completed
@@ -146,6 +222,26 @@ Validation:
 Next Steps: [recommendations]
 ```
 
+### On Success (Subtask)
+
+```
+✅ Subtask N/M completed
+
+Changes:
+- Created: [files]
+- Modified: [files]
+
+Integration:
+✅ Compatible with previous subtasks
+✅ Tests: [count] passing
+✅ Build: Success
+
+Context for next subtask:
+- [Key decisions made]
+- [Files created/modified]
+- [Patterns established]
+```
+
 ### On Partial Completion
 
 ```
@@ -178,6 +274,60 @@ Recommendation: [next steps]
 - Graceful degradation
 - Don't expose sensitive info
 
+## Multi-Step Task Execution
+
+### Context Continuity via Resume
+
+When executing subtasks via `codex exec "..." resume --last`:
+
+**Advantages**:
+- Session memory preserves previous decisions
+- Maintains implementation style consistency
+- Avoids redundant context re-injection
+- Enables incremental testing and validation
+
+**Best Practices**:
+1. **First subtask**: Establish patterns and architecture
+2. **Subsequent subtasks**: Build on established patterns
+3. **Test integration**: After each subtask, verify compatibility
+4. **Report context**: Summarize key decisions for next subtask
+5. **Maintain scope**: Focus only on current subtask goals
+
+### Subtask Coordination
+
+**DO**:
+- Remember decisions from previous subtasks
+- Reuse patterns established earlier
+- Test integration with previous work
+- Report what's ready for next subtask
+
+**DON'T**:
+- Re-implement what previous subtasks completed
+- Change patterns established earlier (unless explicitly requested)
+- Skip testing integration points
+- Assume next subtask's requirements
+
+### Example Flow
+
+```
+Subtask 1: Create data models
+→ Establishes: Schema patterns, validation approach
+→ Delivers: Models with tests
+→ Context for next: Model structure, validation rules
+
+Subtask 2: Implement API endpoints (resume --last)
+→ Recalls: Model structure from subtask 1
+→ Builds on: Uses established models
+→ Delivers: API with integration tests
+→ Context for next: API patterns, error handling
+
+Subtask 3: Add authentication (resume --last)
+→ Recalls: API patterns from subtask 2
+→ Integrates: Auth middleware into existing endpoints
+→ Delivers: Secured API
+→ Final validation: Full integration test
+```
+
 ## Philosophy
 
 - **Incremental progress over big bangs** - Small, testable changes
@@ -186,6 +336,7 @@ Recommendation: [next steps]
 - **Clear intent over clever code** - Boring, obvious solutions
 - **Simple over complex** - Avoid over-engineering
 - **Follow existing style** - Match project patterns exactly
+- **Context continuity** - Leverage resume for multi-step consistency
 
 ## Execution Checklist
 
@@ -211,5 +362,10 @@ Recommendation: [next steps]
 
 ---
 
-**Version**: 2.0.0
-**Last Updated**: 2025-10-02
+**Version**: 2.2.0
+**Last Updated**: 2025-10-04
+**Changes**:
+- Added system optimization requirements for direct binary calls
+- Added apply_patch tool priority for text editing
+- Added Windows UTF-8 encoding configuration for Chinese character support
+- Previous: Multi-step task execution support with resume mechanism

.gitignore

@@ -17,4 +17,7 @@ yarn-error.log*
 Thumbs.db
 
 .env
-settings.local.json
+settings.local.json
+.workflow
+version.json
+ref

.qwen/QWEN.md

@@ -0,0 +1,143 @@
+# QWEN Execution Protocol
+
+## Overview
+
+**Role**: QWEN - code analysis and documentation generation
+
+## Prompt Structure
+
+**Receive prompts in this format**:
+
+```
+PURPOSE: [goal statement]
+TASK: [specific task]
+MODE: [analysis|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [constraints and templates]
+```
+
+## Execution Requirements
+
+### ALWAYS
+
+- **Parse all six fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
+- **Follow MODE strictly** - Respect permission boundaries
+- **Analyze CONTEXT files** - Read all matching patterns thoroughly
+- **Apply RULES** - Follow templates and constraints exactly
+- **Provide evidence** - Quote code with file:line references
+- **Match EXPECTED** - Deliver exactly what's requested
+
+### NEVER
+
+- **Assume behavior** - Verify with actual code
+- **Ignore CONTEXT** - Stay within specified file patterns
+- **Skip RULES** - Templates are mandatory when provided
+- **Make unsubstantiated claims** - Always back with code references
+- **Deviate from MODE** - Respect read/write boundaries
+
+## MODE Behavior
+
+### MODE: analysis (default)
+
+**Permissions**:
+- Read all CONTEXT files
+- Create/modify documentation files
+
+**Execute**:
+1. Read and analyze CONTEXT files
+2. Identify patterns and issues
+3. Generate insights and recommendations
+4. Create documentation if needed
+5. Output structured analysis
+
+**Constraint**: Do NOT modify source code files
+
+### MODE: write
+
+**Permissions**:
+- Full file operations
+- Create/modify any files
+
+**Execute**:
+1. Read CONTEXT files
+2. Perform requested file operations
+3. Create/modify files as specified
+4. Validate changes
+5. Report file changes
+
+## Output Format
+
+### Standard Analysis Structure
+
+```markdown
+# Analysis: [TASK Title]
+
+## Summary
+[2-3 sentence overview]
+
+## Key Findings
+1. [Finding] - path/to/file:123
+2. [Finding] - path/to/file:456
+
+## Detailed Analysis
+[Evidence-based analysis with code quotes]
+
+## Recommendations
+1. [Actionable recommendation]
+2. [Actionable recommendation]
+```
+
+### Code References
+
+Always use format: `path/to/file:line_number`
+
+Example: "Authentication logic at `src/auth/jwt.ts:45` uses deprecated algorithm"
+
+## RULES Processing
+
+- **Parse the RULES field** to identify template content and additional constraints
+- **Recognize `|` as separator** between template and additional constraints
+- **ALWAYS apply all template guidelines** provided in the prompt
+- **ALWAYS apply all additional constraints** specified after `|`
+- **Treat all rules as mandatory** - both template and constraints must be followed
+- **Failure to follow any rule** constitutes task failure
+
+## Error Handling
+
+**File Not Found**:
+- Report missing files
+- Continue with available files
+- Note in output
+
+**Invalid CONTEXT Pattern**:
+- Report invalid pattern
+- Request correction
+- Do not guess
+
+## Quality Standards
+
+### Thoroughness
+- Analyze ALL files in CONTEXT
+- Check cross-file patterns
+- Identify edge cases
+- Quantify when possible
+
+### Evidence-Based
+- Quote relevant code
+- Provide file:line references
+- Link related patterns
+
+### Actionable
+- Clear recommendations
+- Prioritized by impact
+- Specific, not vague
+
+## Philosophy
+
+- **Incremental over big bangs** - Suggest small, testable changes
+- **Learn from existing code** - Reference project patterns
+- **Pragmatic over dogmatic** - Adapt to project reality
+- **Clear over clever** - Prefer obvious solutions
+- **Simple over complex** - Avoid over-engineering
+

CLAUDE.md

@@ -28,6 +28,7 @@ For all CLI tool usage, command syntax, and integration guidelines:
 - **Learning from existing code** - Study and plan before implementing
 - **Clear intent over clever code** - Be boring and obvious
 - **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **No unsolicited reports** - Task summaries can be performed internally, but NEVER generate additional reports, documentation files, or summary files without explicit user permission
 
 ### Simplicity Means
 
@@ -56,6 +57,7 @@ For all CLI tool usage, command syntax, and integration guidelines:
 
 **NEVER**:
 - Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
 
 **ALWAYS**:
 - Plan complex tasks thoroughly before implementation

INSTALL.md

@@ -186,7 +186,7 @@ cd Dmsflow
 .\Install-Claude.ps1 -Global
 
 # 4. Start using Claude Code with Agent workflows!
-# Use /workflow commands and DMS system for development
+# Use /workflow commands and memory system for development
 ```
 
 ## Verification
@@ -207,7 +207,7 @@ After installation, verify:
    - Check that global `.claude` directory is recognized
    - Verify workflow commands and DMS commands are available
    - Test `/workflow` commands for agent coordination
-   - Test `/dmsflow version` to check version information
+   - Test `/workflow version` to check version information
 
 ## Troubleshooting
 

INSTALL_CN.md

@@ -162,7 +162,7 @@ cd Dmsflow
 .\Install-Claude.ps1 -Global
 
 # 4. 开始使用 Claude Code Agent 工作流！
-# 使用 /workflow 命令和 DMS 系统进行开发
+# 使用 /workflow 命令和内存系统进行开发
 ```
 
 ## 验证
@@ -181,9 +181,9 @@ cd Dmsflow
 2. **测试 Claude Code：**
    - 在项目中打开 Claude Code
    - 检查全局 `.claude` 目录是否被识别
-   - 验证工作流命令和 DMS 命令是否可用
+   - 验证工作流命令和内存命令是否可用
    - 测试 `/workflow` 命令的 Agent 协调功能
-   - 测试 `/dmsflow version` 检查版本信息
+   - 测试 `/workflow version` 检查版本信息
 
 ## 故障排除
 

Install-Claude.ps1

@@ -63,7 +63,9 @@ param(
 
     [string]$SourceVersion = "",
 
-    [string]$SourceBranch = ""
+    [string]$SourceBranch = "",
+
+    [string]$SourceCommit = ""
 )
 
 # Set encoding for proper Unicode support
@@ -78,7 +80,10 @@ if ($PSVersionTable.PSVersion.Major -ge 6) {
 
 # Script metadata
 $ScriptName = "Claude Code Workflow System Installer"
-$Version = "2.1.0"
+$ScriptVersion = "2.2.0"  # Installer script version
+
+# Default version (will be overridden by -SourceVersion from install-remote.ps1)
+$DefaultVersion = "unknown"
 
 # Initialize backup behavior - backup is enabled by default unless NoBackup is specified
 if (-not $BackupAll -and -not $NoBackup) {
@@ -141,8 +146,15 @@ function Show-Banner {
 }
 
 function Show-Header {
+    param(
+        [string]$InstallVersion = $DefaultVersion
+    )
+
     Show-Banner
-    Write-ColorOutput "    $ScriptName v$Version" $ColorInfo
+    Write-ColorOutput "    $ScriptName v$ScriptVersion" $ColorInfo
+    if ($InstallVersion -ne "unknown") {
+        Write-ColorOutput "    Installing Claude Code Workflow v$InstallVersion" $ColorInfo
+    }
     Write-ColorOutput "    Unified workflow system with comprehensive coordination" $ColorInfo
     Write-ColorOutput "========================================================================" $ColorInfo
     if ($NoBackup) {
@@ -167,6 +179,7 @@ function Test-Prerequisites {
     $claudeMd = Join-Path $sourceDir "CLAUDE.md"
     $codexDir = Join-Path $sourceDir ".codex"
     $geminiDir = Join-Path $sourceDir ".gemini"
+    $qwenDir = Join-Path $sourceDir ".qwen"
 
     if (-not (Test-Path $claudeDir)) {
         Write-ColorOutput "ERROR: .claude directory not found in $sourceDir" $ColorError
@@ -188,6 +201,11 @@ function Test-Prerequisites {
         return $false
     }
 
+    if (-not (Test-Path $qwenDir)) {
+        Write-ColorOutput "ERROR: .qwen directory not found in $sourceDir" $ColorError
+        return $false
+    }
+
     Write-ColorOutput "Prerequisites check passed" $ColorSuccess
     return $true
 }
@@ -632,24 +650,27 @@ function Create-VersionJson {
         [string]$InstallationMode
     )
 
-    # Determine version from source or default
-    $versionNumber = if ($SourceVersion) { $SourceVersion } else { $Version }
+    # Determine version from source parameter (passed from install-remote.ps1)
+    $versionNumber = if ($SourceVersion) { $SourceVersion } else { $DefaultVersion }
     $sourceBranch = if ($SourceBranch) { $SourceBranch } else { "unknown" }
+    $commitSha = if ($SourceCommit) { $SourceCommit } else { "unknown" }
 
     # Create version.json content
     $versionInfo = @{
         version = $versionNumber
+        commit_sha = $commitSha
         installation_mode = $InstallationMode
         installation_path = $TargetClaudeDir
         installation_date_utc = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
         source_branch = $sourceBranch
+        installer_version = $ScriptVersion
     }
 
     $versionJsonPath = Join-Path $TargetClaudeDir "version.json"
 
     try {
         $versionInfo | ConvertTo-Json | Out-File -FilePath $versionJsonPath -Encoding utf8 -Force
-        Write-ColorOutput "Created version.json: $versionNumber ($InstallationMode)" $ColorSuccess
+        Write-ColorOutput "Created version.json: $versionNumber ($commitSha) - $InstallationMode" $ColorSuccess
         return $true
     } catch {
         Write-ColorOutput "WARNING: Failed to create version.json: $($_.Exception.Message)" $ColorWarning
@@ -666,6 +687,7 @@ function Install-Global {
     $globalClaudeMd = Join-Path $globalClaudeDir "CLAUDE.md"
     $globalCodexDir = Join-Path $userProfile ".codex"
     $globalGeminiDir = Join-Path $userProfile ".gemini"
+    $globalQwenDir = Join-Path $userProfile ".qwen"
 
     Write-ColorOutput "Global installation path: $userProfile" $ColorInfo
 
@@ -675,11 +697,12 @@ function Install-Global {
     $sourceClaudeMd = Join-Path $sourceDir "CLAUDE.md"
     $sourceCodexDir = Join-Path $sourceDir ".codex"
     $sourceGeminiDir = Join-Path $sourceDir ".gemini"
+    $sourceQwenDir = Join-Path $sourceDir ".qwen"
 
     # Create backup folder if needed (default behavior unless NoBackup is specified)
     $backupFolder = $null
     if (-not $NoBackup) {
-        if ((Test-Path $globalClaudeDir) -or (Test-Path $globalCodexDir) -or (Test-Path $globalGeminiDir)) {
+        if ((Test-Path $globalClaudeDir) -or (Test-Path $globalCodexDir) -or (Test-Path $globalGeminiDir) -or (Test-Path $globalQwenDir)) {
             $existingFiles = @()
             if (Test-Path $globalClaudeDir) {
                 $existingFiles += Get-ChildItem $globalClaudeDir -Recurse -File -ErrorAction SilentlyContinue
@@ -690,6 +713,9 @@ function Install-Global {
             if (Test-Path $globalGeminiDir) {
                 $existingFiles += Get-ChildItem $globalGeminiDir -Recurse -File -ErrorAction SilentlyContinue
             }
+            if (Test-Path $globalQwenDir) {
+                $existingFiles += Get-ChildItem $globalQwenDir -Recurse -File -ErrorAction SilentlyContinue
+            }
             if (($existingFiles -and ($existingFiles | Measure-Object).Count -gt 0)) {
                 $backupFolder = Get-BackupDirectory -TargetDirectory $userProfile
                 Write-ColorOutput "Backup folder created: $backupFolder" $ColorInfo
@@ -717,6 +743,10 @@ function Install-Global {
     Write-ColorOutput "Merging .gemini directory contents..." $ColorInfo
     $geminiMerged = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory contents" -BackupFolder $backupFolder
 
+    # Merge .qwen directory contents
+    Write-ColorOutput "Merging .qwen directory contents..." $ColorInfo
+    $qwenMerged = Merge-DirectoryContents -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory contents" -BackupFolder $backupFolder
+
     # Create version.json in global .claude directory
     Write-ColorOutput "Creating version.json..." $ColorInfo
     Create-VersionJson -TargetClaudeDir $globalClaudeDir -InstallationMode "Global"
@@ -753,16 +783,18 @@ function Install-Path {
     $sourceClaudeMd = Join-Path $sourceDir "CLAUDE.md"
     $sourceCodexDir = Join-Path $sourceDir ".codex"
     $sourceGeminiDir = Join-Path $sourceDir ".gemini"
+    $sourceQwenDir = Join-Path $sourceDir ".qwen"
 
-    # Local paths - for agents, commands, output-styles, .codex, .gemini
+    # Local paths - for agents, commands, output-styles, .codex, .gemini, .qwen
     $localClaudeDir = Join-Path $TargetDirectory ".claude"
     $localCodexDir = Join-Path $TargetDirectory ".codex"
     $localGeminiDir = Join-Path $TargetDirectory ".gemini"
+    $localQwenDir = Join-Path $TargetDirectory ".qwen"
 
     # Create backup folder if needed
     $backupFolder = $null
     if (-not $NoBackup) {
-        if ((Test-Path $localClaudeDir) -or (Test-Path $localCodexDir) -or (Test-Path $localGeminiDir) -or (Test-Path $globalClaudeDir)) {
+        if ((Test-Path $localClaudeDir) -or (Test-Path $localCodexDir) -or (Test-Path $localGeminiDir) -or (Test-Path $localQwenDir) -or (Test-Path $globalClaudeDir)) {
             $backupFolder = Get-BackupDirectory -TargetDirectory $TargetDirectory
             Write-ColorOutput "Backup folder created: $backupFolder" $ColorInfo
         }
@@ -858,6 +890,10 @@ function Install-Path {
     Write-ColorOutput "Merging .gemini directory contents to local location..." $ColorInfo
     $geminiMerged = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory contents" -BackupFolder $backupFolder
 
+    # Merge .qwen directory contents to local location
+    Write-ColorOutput "Merging .qwen directory contents to local location..." $ColorInfo
+    $qwenMerged = Merge-DirectoryContents -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory contents" -BackupFolder $backupFolder
+
     # Create version.json in local .claude directory
     Write-ColorOutput "Creating version.json in local directory..." $ColorInfo
     Create-VersionJson -TargetClaudeDir $localClaudeDir -InstallationMode "Path"
@@ -971,11 +1007,11 @@ function Show-Summary {
     if ($Mode -eq "Path") {
         Write-Host "  Local Path: $Path"
         Write-Host "  Global Path: $([Environment]::GetFolderPath('UserProfile'))"
-        Write-Host "  Local Components: agents, commands, output-styles, .codex, .gemini"
+        Write-Host "  Local Components: agents, commands, output-styles, .codex, .gemini, .qwen"
         Write-Host "  Global Components: workflows, scripts, python_script, etc."
     } else {
         Write-Host "  Path: $Path"
-        Write-Host "  Global Components: .claude, .codex, .gemini"
+        Write-Host "  Global Components: .claude, .codex, .gemini, .qwen"
     }
 
     if ($NoBackup) {
@@ -991,10 +1027,11 @@ function Show-Summary {
     Write-Host "1. Review CLAUDE.md - Customize guidelines for your project"
     Write-Host "2. Review .codex/Agent.md - Codex agent execution protocol"
     Write-Host "3. Review .gemini/CLAUDE.md - Gemini agent execution protocol"
-    Write-Host "4. Configure settings - Edit .claude/settings.local.json as needed"
-    Write-Host "5. Start using Claude Code with Agent workflow coordination!"
-    Write-Host "6. Use /workflow commands for task execution"
-    Write-Host "7. Use /update-memory commands for memory system management"
+    Write-Host "4. Review .qwen/QWEN.md - Qwen agent execution protocol"
+    Write-Host "5. Configure settings - Edit .claude/settings.local.json as needed"
+    Write-Host "6. Start using Claude Code with Agent workflow coordination!"
+    Write-Host "7. Use /workflow commands for task execution"
+    Write-Host "8. Use /update-memory commands for memory system management"
 
     Write-Host ""
     Write-ColorOutput "Documentation: https://github.com/catlog22/Claude-CCW" $ColorInfo
@@ -1002,7 +1039,10 @@ function Show-Summary {
 }
 
 function Main {
-    Show-Header
+    # Use SourceVersion parameter if provided, otherwise use default
+    $installVersion = if ($SourceVersion) { $SourceVersion } else { $DefaultVersion }
+
+    Show-Header -InstallVersion $installVersion
 
     # Test prerequisites
     Write-ColorOutput "Checking system requirements..." $ColorInfo

Install-Claude.sh

@@ -24,6 +24,9 @@ FORCE=false
 NON_INTERACTIVE=false
 BACKUP_ALL=true  # Enabled by default
 NO_BACKUP=false
+SOURCE_VERSION=""  # Version from remote installer
+SOURCE_BRANCH=""   # Branch from remote installer
+SOURCE_COMMIT=""   # Commit SHA from remote installer
 
 # Functions
 function write_color() {
@@ -87,8 +90,8 @@ function show_header() {
 
 function test_prerequisites() {
     # Test bash version
-    if [ "${BASH_VERSINFO[0]}" -lt 4 ]; then
-        write_color "ERROR: Bash 4.0 or higher is required" "$COLOR_ERROR"
+    if [ "${BASH_VERSINFO[0]}" -lt 2 ]; then
+        write_color "ERROR: Bash 2.0 or higher is required" "$COLOR_ERROR"
         write_color "Current version: ${BASH_VERSION}" "$COLOR_ERROR"
         return 1
     fi
@@ -99,6 +102,7 @@ function test_prerequisites() {
     local claude_md="$script_dir/CLAUDE.md"
     local codex_dir="$script_dir/.codex"
     local gemini_dir="$script_dir/.gemini"
+    local qwen_dir="$script_dir/.qwen"
 
     if [ ! -d "$claude_dir" ]; then
         write_color "ERROR: .claude directory not found in $script_dir" "$COLOR_ERROR"
@@ -120,6 +124,11 @@ function test_prerequisites() {
         return 1
     fi
 
+    if [ ! -d "$qwen_dir" ]; then
+        write_color "ERROR: .qwen directory not found in $script_dir" "$COLOR_ERROR"
+        return 1
+    fi
+
     write_color "✓ Prerequisites check passed" "$COLOR_SUCCESS"
     return 0
 }
@@ -403,6 +412,7 @@ function install_global() {
     local global_claude_md="${global_claude_dir}/CLAUDE.md"
     local global_codex_dir="${user_home}/.codex"
     local global_gemini_dir="${user_home}/.gemini"
+    local global_qwen_dir="${user_home}/.qwen"
 
     write_color "Global installation path: $user_home" "$COLOR_INFO"
 
@@ -412,6 +422,7 @@ function install_global() {
     local source_claude_md="${script_dir}/CLAUDE.md"
     local source_codex_dir="${script_dir}/.codex"
     local source_gemini_dir="${script_dir}/.gemini"
+    local source_qwen_dir="${script_dir}/.qwen"
 
     # Create backup folder if needed
     local backup_folder=""
@@ -424,6 +435,8 @@ function install_global() {
             has_existing_files=true
         elif [ -d "$global_gemini_dir" ] && [ "$(ls -A "$global_gemini_dir" 2>/dev/null)" ]; then
             has_existing_files=true
+        elif [ -d "$global_qwen_dir" ] && [ "$(ls -A "$global_qwen_dir" 2>/dev/null)" ]; then
+            has_existing_files=true
         elif [ -f "$global_claude_md" ]; then
             has_existing_files=true
         fi
@@ -450,6 +463,10 @@ function install_global() {
     write_color "Merging .gemini directory contents..." "$COLOR_INFO"
     merge_directory_contents "$source_gemini_dir" "$global_gemini_dir" ".gemini directory contents" "$backup_folder"
 
+    # Merge .qwen directory contents
+    write_color "Merging .qwen directory contents..." "$COLOR_INFO"
+    merge_directory_contents "$source_qwen_dir" "$global_qwen_dir" ".qwen directory contents" "$backup_folder"
+
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then
         if [ -z "$(ls -A "$backup_folder" 2>/dev/null)" ]; then
@@ -458,6 +475,10 @@ function install_global() {
         fi
     fi
 
+    # Create version.json in global .claude directory
+    write_color "Creating version.json..." "$COLOR_INFO"
+    create_version_json "$global_claude_dir" "Global"
+
     return 0
 }
 
@@ -477,16 +498,18 @@ function install_path() {
     local source_claude_md="${script_dir}/CLAUDE.md"
     local source_codex_dir="${script_dir}/.codex"
     local source_gemini_dir="${script_dir}/.gemini"
+    local source_qwen_dir="${script_dir}/.qwen"
 
     # Local paths
     local local_claude_dir="${target_dir}/.claude"
     local local_codex_dir="${target_dir}/.codex"
     local local_gemini_dir="${target_dir}/.gemini"
+    local local_qwen_dir="${target_dir}/.qwen"
 
     # Create backup folder if needed
     local backup_folder=""
     if [ "$NO_BACKUP" = false ]; then
-        if [ -d "$local_claude_dir" ] || [ -d "$local_codex_dir" ] || [ -d "$local_gemini_dir" ] || [ -d "$global_claude_dir" ]; then
+        if [ -d "$local_claude_dir" ] || [ -d "$local_codex_dir" ] || [ -d "$local_gemini_dir" ] || [ -d "$local_qwen_dir" ] || [ -d "$global_claude_dir" ]; then
             backup_folder=$(get_backup_directory "$target_dir")
             write_color "Backup folder created: $backup_folder" "$COLOR_INFO"
         fi
@@ -575,6 +598,10 @@ function install_path() {
     write_color "Merging .gemini directory contents to local location..." "$COLOR_INFO"
     merge_directory_contents "$source_gemini_dir" "$local_gemini_dir" ".gemini directory contents" "$backup_folder"
 
+    # Merge .qwen directory contents to local location
+    write_color "Merging .qwen directory contents to local location..." "$COLOR_INFO"
+    merge_directory_contents "$source_qwen_dir" "$local_qwen_dir" ".qwen directory contents" "$backup_folder"
+
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then
         if [ -z "$(ls -A "$backup_folder" 2>/dev/null)" ]; then
@@ -583,12 +610,20 @@ function install_path() {
         fi
     fi
 
+    # Create version.json in local .claude directory
+    write_color "Creating version.json in local directory..." "$COLOR_INFO"
+    create_version_json "$local_claude_dir" "Path"
+
+    # Also create version.json in global .claude directory
+    write_color "Creating version.json in global directory..." "$COLOR_INFO"
+    create_version_json "$global_claude_dir" "Global"
+
     return 0
 }
 
 function get_installation_mode() {
     if [ -n "$INSTALL_MODE" ]; then
-        write_color "Installation mode: $INSTALL_MODE" "$COLOR_INFO"
+        write_color "Installation mode: $INSTALL_MODE" "$COLOR_INFO" >&2
         echo "$INSTALL_MODE"
         return
     fi
@@ -658,6 +693,42 @@ function get_installation_path() {
     done
 }
 
+function create_version_json() {
+    local target_claude_dir="$1"
+    local installation_mode="$2"
+
+    # Determine version from source parameter (passed from install-remote.sh)
+    local version_number="${SOURCE_VERSION:-unknown}"
+    local source_branch="${SOURCE_BRANCH:-unknown}"
+    local commit_sha="${SOURCE_COMMIT:-unknown}"
+
+    # Get current UTC timestamp
+    local installation_date_utc=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Create version.json content
+    local version_json_path="${target_claude_dir}/version.json"
+
+    cat > "$version_json_path" << EOF
+{
+  "version": "$version_number",
+  "commit_sha": "$commit_sha",
+  "installation_mode": "$installation_mode",
+  "installation_path": "$target_claude_dir",
+  "installation_date_utc": "$installation_date_utc",
+  "source_branch": "$source_branch",
+  "installer_version": "$VERSION"
+}
+EOF
+
+    if [ -f "$version_json_path" ]; then
+        write_color "Created version.json: $version_number ($commit_sha) - $installation_mode" "$COLOR_SUCCESS"
+        return 0
+    else
+        write_color "WARNING: Failed to create version.json" "$COLOR_WARNING"
+        return 1
+    fi
+}
+
 function show_summary() {
     local mode="$1"
     local path="$2"
@@ -676,11 +747,11 @@ function show_summary() {
     if [ "$mode" = "Path" ]; then
         echo "  Local Path: $path"
         echo "  Global Path: $HOME"
-        echo "  Local Components: agents, commands, output-styles, .codex, .gemini"
+        echo "  Local Components: agents, commands, output-styles, .codex, .gemini, .qwen"
         echo "  Global Components: workflows, scripts, python_script, etc."
     else
         echo "  Path: $path"
-        echo "  Global Components: .claude, .codex, .gemini"
+        echo "  Global Components: .claude, .codex, .gemini, .qwen"
     fi
 
     if [ "$NO_BACKUP" = true ]; then
@@ -696,10 +767,11 @@ function show_summary() {
     echo "1. Review CLAUDE.md - Customize guidelines for your project"
     echo "2. Review .codex/Agent.md - Codex agent execution protocol"
     echo "3. Review .gemini/CLAUDE.md - Gemini agent execution protocol"
-    echo "4. Configure settings - Edit .claude/settings.local.json as needed"
-    echo "5. Start using Claude Code with Agent workflow coordination!"
-    echo "6. Use /workflow commands for task execution"
-    echo "7. Use /update-memory commands for memory system management"
+    echo "4. Review .qwen/QWEN.md - Qwen agent execution protocol"
+    echo "5. Configure settings - Edit .claude/settings.local.json as needed"
+    echo "6. Start using Claude Code with Agent workflow coordination!"
+    echo "7. Use /workflow commands for task execution"
+    echo "8. Use /update-memory commands for memory system management"
 
     echo ""
     write_color "Documentation: https://github.com/catlog22/Claude-Code-Workflow" "$COLOR_INFO"
@@ -735,6 +807,18 @@ function parse_arguments() {
                 BACKUP_ALL=false
                 shift
                 ;;
+            -SourceVersion)
+                SOURCE_VERSION="$2"
+                shift 2
+                ;;
+            -SourceBranch)
+                SOURCE_BRANCH="$2"
+                shift 2
+                ;;
+            -SourceCommit)
+                SOURCE_COMMIT="$2"
+                shift 2
+                ;;
             --help|-h)
                 show_help
                 exit 0
@@ -761,6 +845,9 @@ Options:
     -NonInteractive       Run in non-interactive mode with default options
     -BackupAll            Automatically backup all existing files (default)
     -NoBackup             Disable automatic backup functionality
+    -SourceVersion <ver>  Source version (passed from install-remote.sh)
+    -SourceBranch <name>  Source branch (passed from install-remote.sh)
+    -SourceCommit <sha>   Source commit SHA (passed from install-remote.sh)
     --help, -h            Show this help message
 
 Examples:
@@ -776,6 +863,9 @@ Examples:
     # Installation without backup
     $0 -NoBackup
 
+    # With version info (typically called by install-remote.sh)
+    $0 -InstallMode Global -Force -SourceVersion "3.4.2" -SourceBranch "main" -SourceCommit "abc1234"
+
 EOF
 }
 

README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v3.2.3-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.2.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,14 +15,13 @@
 
 **Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework that orchestrates complex software development tasks through intelligent workflow management and autonomous execution.
 
-> **🎉 Latest: v3.2.3** - Version management system with upgrade notifications. See [CHANGELOG.md](CHANGELOG.md) for details.
+> **🎉 Latest: v4.2.1** - Documentation Refactoring for UI Design Workflow. See [CHANGELOG.md](CHANGELOG.md) for details.
 >
-> **What's New in v3.2.3**:
-> - 🔍 New `/version` command for checking installed versions
-> - 📊 GitHub API integration for latest release detection
-> - 🔄 Automatic upgrade notifications and recommendations
-> - 📁 Version tracking in both local and global installations
-> - ⚡ Quick version check with comprehensive status display
+> **What's New in v4.2.1**:
+> - 📚 **Documentation Optimization**: Reduced file sizes by 15-20% while preserving all functionality
+> - 🎯 **Clearer Structure**: Merged duplicate concepts and streamlined content organization
+> - ✨ **Improved Maintainability**: Better content separation and consistent formatting patterns
+> - 📖 **Zero Functionality Loss**: All features, workflows, and technical details preserved
 
 ---
 
@@ -143,6 +142,98 @@ After installation, run the following command to ensure CCW is working:
 
 ---
 
+## ⚙️ Configuration
+
+### **Prerequisites: Required Tools**
+
+Before using CCW, install the following command-line tools:
+
+#### **Core CLI Tools**
+
+| Tool | Purpose | Installation |
+|------|---------|--------------|
+| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
+| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
+| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) |
+
+#### **System Utilities**
+
+| Tool | Purpose | Installation |
+|------|---------|--------------|
+| **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
+| **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) |
+
+**Quick Install (All Tools):**
+
+```bash
+# macOS
+brew install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Ubuntu/Debian
+sudo apt install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Windows (Chocolatey)
+choco install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+```
+
+### **Essential: Gemini CLI Setup**
+
+Configure Gemini CLI for optimal integration:
+
+```json
+// ~/.gemini/settings.json
+{
+  "contextFileName": ["CLAUDE.md", "GEMINI.md"]
+}
+```
+
+### **Recommended: .geminiignore**
+
+Optimize performance by excluding unnecessary files:
+
+```bash
+# .geminiignore (in project root)
+/dist/
+/build/
+/node_modules/
+/.next/
+*.tmp
+*.log
+/temp/
+
+# Include important docs
+!README.md
+!**/CLAUDE.md
+```
+
+### **Recommended: MCP Tools** *(Enhanced Analysis)*
+
+MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recommended installation** - While CCW has fallback mechanisms, not installing MCP tools may lead to unexpected behavior or degraded performance in some workflows.
+
+#### Available MCP Servers
+
+| MCP Server | Purpose | Installation Guide |
+|------------|---------|-------------------|
+| **Exa MCP** | External API patterns & best practices | [Install Guide](https://smithery.ai/server/exa) |
+| **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) |
+
+#### Benefits When Enabled
+- 📊 **Faster Analysis**: Direct codebase indexing vs manual searching
+- 🌐 **External Context**: Real-world API patterns and examples
+- 🔍 **Advanced Search**: Pattern matching and similarity detection
+- ⚡ **Better Reliability**: Primary tools for certain workflows
+
+⚠️ **Note**: Some workflows expect MCP tools to be available. Without them, you may experience:
+- Slower code analysis and search operations
+- Reduced context quality in some scenarios
+- Fallback to less efficient traditional tools
+- Potential unexpected behavior in advanced workflows
+
+---
+
 ## 🚀 Getting Started
 
 ### Complete Development Workflow
@@ -157,7 +248,32 @@ After installation, run the following command to ensure CCW is working:
 /workflow:brainstorm:synthesis  # Generate consolidated specification
 ```
 
-**Phase 2: Action Planning**
+**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
+```bash
+# Matrix Exploration Mode - Multiple style/layout variants (v4.2.1+)
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
+
+# Fast Imitation Mode - Single design replication (v4.2.1+)
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# With session integration
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+
+# Or run individual design phases
+/workflow:ui-design:extract --images "refs/*.png" --variants 3
+/workflow:ui-design:consolidate --variants "variant-1,variant-3"
+/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
+
+# Preview generated prototypes
+# Option 1: Open .workflow/WFS-auth/.design/prototypes/compare.html in browser
+# Option 2: Start local server
+cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
+# Visit http://localhost:8080 for interactive preview with comparison tools
+
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
+```
+
+**Phase 3: Action Planning**
 ```bash
 # Create executable implementation plan
 /workflow:plan "Implement JWT-based authentication system"
@@ -166,7 +282,7 @@ After installation, run the following command to ensure CCW is working:
 /workflow:tdd-plan "Implement authentication with test-first development"
 ```
 
-**Phase 3: Execution**
+**Phase 4: Execution**
 ```bash
 # Execute tasks with AI agents
 /workflow:execute
@@ -175,7 +291,7 @@ After installation, run the following command to ensure CCW is working:
 /workflow:status
 ```
 
-**Phase 4: Testing & Quality Assurance**
+**Phase 5: Testing & Quality Assurance**
 ```bash
 # Generate independent test-fix workflow (v3.2.2+)
 /workflow:test-gen WFS-auth  # Creates WFS-test-auth session
@@ -248,13 +364,141 @@ After installation, run the following command to ensure CCW is working:
 |---|---|
 | `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
 | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
+| `/workflow:ui-design:explore-auto` | **v4.2.1** Matrix exploration mode - Generate multiple style × layout variants for comprehensive design exploration. |
+| `/workflow:ui-design:imitate-auto` | **v4.2.1** Fast imitation mode - Rapid single-design replication with auto-screenshot and direct token extraction. |
+| `/workflow:ui-design:extract` | **v4.2.1** Extract design from images/text using Claude-native analysis. Single-pass variant generation. |
+| `/workflow:ui-design:consolidate` | **v4.2.1** Consolidate style variants into validated design tokens using Claude synthesis. |
+| `/workflow:ui-design:generate` | **v4.2.1** Generate token-driven HTML/CSS prototypes in matrix mode (style × layout combinations). |
+| `/workflow:ui-design:update` | **v4.2.1** Integrate finalized design system into brainstorming artifacts. |
 | `/workflow:plan` | Create a detailed, executable plan from a description. |
-| `/workflow:tdd-plan` | Create a Test-Driven Development workflow with Red-Green-Refactor cycles. |
+| `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. |
 | `/workflow:execute` | Execute the current workflow plan autonomously. |
 | `/workflow:status` | Display the current status of the workflow. |
-| `/workflow:test-gen` | Create independent test-fix workflow for validating completed implementation. |
+| `/workflow:test-gen [--use-codex] <session>` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. |
 | `/workflow:tdd-verify` | Verify TDD compliance and generate quality report. |
 | `/workflow:review` | **Optional** manual review (only use when explicitly needed - passing tests = approved code). |
+| `/workflow:tools:test-context-gather` | Analyze test coverage and identify missing test files. |
+| `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. |
+| `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. |
+
+### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.2.1)*
+
+The design workflow system provides complete UI design refinement with **pure Claude execution**, **intelligent page inference**, and **zero external dependencies**.
+
+#### Core Commands
+
+**`/workflow:ui-design:explore-auto`** - Matrix exploration mode
+```bash
+# Comprehensive exploration - multiple style × layout variants
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
+
+# With images and session integration
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+
+# Text-only mode with page inference
+/workflow:ui-design:explore-auto --prompt "E-commerce: home, product, cart" --style-variants 2 --layout-variants 2
+```
+- **🎯 Matrix Mode**: Generate all style × layout combinations
+- **📊 Comprehensive Exploration**: Compare multiple design directions
+- **🔍 Interactive Comparison**: Side-by-side comparison with viewport controls
+- **✅ Cross-page Validation**: Automatic consistency checks for multi-page designs
+- **⚡ Batch Selection**: Quick selection by style or layout
+
+**`/workflow:ui-design:imitate-auto`** - Fast imitation mode
+```bash
+# Rapid single-design replication
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# With session integration
+/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
+
+# Auto-screenshot from URL (requires Playwright)
+/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
+```
+- **⚡ Speed Optimized**: 5-10x faster than explore-auto
+- **📸 Auto-Screenshot**: Automatic URL screenshot capture with Playwright/Chrome
+- **🎯 Direct Extraction**: Skip variant selection, go straight to implementation
+- **🔧 Single Design Focus**: Best for copying existing designs quickly
+
+**`/workflow:ui-design:extract`** - Style analysis with dual input sources
+```bash
+# Pure text prompt
+/workflow:ui-design:extract --prompt "Modern minimalist, dark theme" --variants 3
+
+# Pure images
+/workflow:ui-design:extract --images "refs/*.png" --variants 3
+
+# Hybrid (text guides image analysis)
+/workflow:ui-design:extract --images "refs/*.png" --prompt "Linear.app style" --variants 2
+```
+- **Claude-Native**: Single-pass analysis, no external tools
+- **Enhanced Output**: `style-cards.json` with embedded `proposed_tokens`
+- **Reproducible**: Deterministic structure, version-controlled logic
+- **Output**: 1 file (vs 4+ in previous versions)
+
+**`/workflow:ui-design:consolidate`** - Validate and merge tokens
+```bash
+# Consolidate selected style variants
+/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3"
+```
+- **Claude Synthesis**: Single-pass generation of all design system files
+- **Features**: WCAG AA validation, OKLCH colors, W3C token format
+- **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`, `validation-report.json`
+
+**`/workflow:ui-design:generate`** - Generate HTML/CSS prototypes
+```bash
+# Matrix mode - style × layout combinations
+/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
+
+# Single page with multiple variants
+/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
+```
+- **🎯 Matrix Generation**: Creates all style × layout combinations
+- **📊 Multi-page Support**: Consistent design system across pages
+- **✅ Consistency Validation**: Automatic cross-page consistency reports (v4.2.0+)
+- **🔍 Interactive Preview**: `compare.html` with side-by-side comparison
+- **📋 Batch Selection**: Quick selection by style or layout filters
+
+**`/workflow:ui-design:update`** - Integrate design system
+```bash
+# Update brainstorming artifacts with design system
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "login-variant-1"
+```
+- **Updates**: `synthesis-specification.md`, `ui-designer/style-guide.md`
+- **Makes design tokens available for task generation**
+
+#### Preview System
+
+After running `ui-generate`, you get interactive preview tools:
+
+**Quick Preview** (Direct Browser):
+```bash
+# Navigate to prototypes directory
+cd .workflow/WFS-auth/.design/prototypes
+# Open index.html in browser (double-click or):
+open index.html  # macOS
+start index.html  # Windows
+xdg-open index.html  # Linux
+```
+
+**Full Preview** (Local Server - Recommended):
+```bash
+cd .workflow/WFS-auth/.design/prototypes
+# Choose one:
+python -m http.server 8080      # Python
+npx http-server -p 8080         # Node.js
+php -S localhost:8080           # PHP
+# Visit: http://localhost:8080
+```
+
+**Preview Features**:
+- `index.html`: Master navigation with all prototypes
+- `compare.html`: Side-by-side comparison with viewport controls (Desktop/Tablet/Mobile)
+- Synchronized scrolling for layout comparison
+- Dynamic page switching
+- Real-time responsive testing
+
+---
 
 ### **Task & Memory Commands**
 
@@ -267,92 +511,6 @@ After installation, run the following command to ensure CCW is working:
 
 ---
 
-## ⚙️ Configuration
-
-### **Prerequisites: Required Tools**
-
-Before using CCW, install the following command-line tools:
-
-#### **Core CLI Tools**
-
-| Tool | Purpose | Installation |
-|------|---------|--------------|
-| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
-| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
-| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) |
-
-#### **System Utilities**
-
-| Tool | Purpose | Installation |
-|------|---------|--------------|
-| **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
-| **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) |
-
-**Quick Install (All Tools):**
-
-```bash
-# macOS
-brew install ripgrep jq
-npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
-
-# Ubuntu/Debian
-sudo apt install ripgrep jq
-npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
-
-# Windows (Chocolatey)
-choco install ripgrep jq
-npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
-```
-
-### **Essential: Gemini CLI Setup**
-
-Configure Gemini CLI for optimal integration:
-
-```json
-// ~/.gemini/settings.json
-{
-  "contextFileName": ["CLAUDE.md", "GEMINI.md"]
-}
-```
-
-### **Recommended: .geminiignore**
-
-Optimize performance by excluding unnecessary files:
-
-```bash
-# .geminiignore (in project root)
-/dist/
-/build/
-/node_modules/
-/.next/
-*.tmp
-*.log
-/temp/
-
-# Include important docs
-!README.md
-!**/CLAUDE.md
-```
-
-### **Optional: MCP Tools** *(Enhanced Analysis)*
-
-MCP (Model Context Protocol) tools provide advanced codebase analysis. **Completely optional** - CCW works perfectly without them.
-
-#### Available MCP Servers
-
-| MCP Server | Purpose | Installation Guide |
-|------------|---------|-------------------|
-| **Exa MCP** | External API patterns & best practices | [Install Guide](https://github.com/exa-labs/exa-mcp-server) |
-| **Code Index MCP** | Advanced internal code search | [Install Guide](https://github.com/johnhuang316/code-index-mcp) |
-
-#### Benefits When Enabled
-- 📊 **Faster Analysis**: Direct codebase indexing vs manual searching
-- 🌐 **External Context**: Real-world API patterns and examples
-- 🔍 **Advanced Search**: Pattern matching and similarity detection
-- ⚡ **Automatic Fallback**: Uses traditional tools when MCP unavailable
-
----
-
 ## 🧩 How It Works: Design Philosophy
 
 ### The Core Problem

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v3.2.3-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.2.1-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,14 +15,13 @@
 
 **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
 
-> **🎉 最新版本: v3.2.3** - 版本管理系统与升级通知。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v4.2.1** - UI 设计工作流文档重构。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v3.2.3 版本新特性**:
-> - 🔍 新增 `/version` 命令用于检查已安装版本
-> - 📊 GitHub API 集成，获取最新版本信息
-> - 🔄 自动升级通知与建议
-> - 📁 支持本地和全局安装的版本跟踪
-> - ⚡ 一键版本检查，全面展示状态信息
+> **v4.2.1 版本新特性**:
+> - 📚 **文档优化**: 文件大小减少 15-20%，同时保留所有功能
+> - 🎯 **更清晰的结构**: 合并重复概念，优化内容组织
+> - ✨ **改进的可维护性**: 更好的内容分离和一致的格式模式
+> - 📖 **零功能损失**: 保留所有特性、工作流和技术细节
 
 ---
 
@@ -143,6 +142,98 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 
 ---
 
+## ⚙️ 配置
+
+### **前置要求：必需工具**
+
+在使用 CCW 之前，请安装以下命令行工具：
+
+#### **核心 CLI 工具**
+
+| 工具 | 用途 | 安装方式 |
+|------|------|----------|
+| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
+| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
+| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) |
+
+#### **系统实用工具**
+
+| 工具 | 用途 | 安装方式 |
+|------|------|----------|
+| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
+| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) |
+
+**快速安装（所有工具）：**
+
+```bash
+# macOS
+brew install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Ubuntu/Debian
+sudo apt install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Windows (Chocolatey)
+choco install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+```
+
+### **必需: Gemini CLI 设置**
+
+配置 Gemini CLI 以实现最佳集成：
+
+```json
+// ~/.gemini/settings.json
+{
+  "contextFileName": ["CLAUDE.md", "GEMINI.md"]
+}
+```
+
+### **推荐: .geminiignore**
+
+通过排除不必要的文件来优化性能：
+
+```bash
+# .geminiignore (在项目根目录)
+/dist/
+/build/
+/node_modules/
+/.next/
+*.tmp
+*.log
+/temp/
+
+# 包含重要文档
+!README.md
+!**/CLAUDE.md
+```
+
+### **推荐: MCP 工具** *(增强分析)*
+
+MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装** - 虽然 CCW 具有回退机制，但不安装 MCP 工具可能会导致某些工作流出现意外行为或性能下降。
+
+#### 可用的 MCP 服务器
+
+| MCP 服务器 | 用途 | 安装指南 |
+|------------|------|---------|
+| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://smithery.ai/server/exa) |
+| **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) |
+
+#### 启用后的好处
+- 📊 **更快分析**: 直接代码库索引 vs 手动搜索
+- 🌐 **外部上下文**: 真实世界的 API 模式和示例
+- 🔍 **高级搜索**: 模式匹配和相似性检测
+- ⚡ **更好的可靠性**: 某些工作流的主要工具
+
+⚠️ **注意**: 某些工作流期望 MCP 工具可用。如果没有安装，您可能会遇到：
+- 代码分析和搜索操作速度较慢
+- 某些场景下上下文质量降低
+- 回退到效率较低的传统工具
+- 高级工作流中可能出现意外行为
+
+---
+
 ## 🚀 快速入门
 
 ### 完整开发工作流
@@ -157,7 +248,32 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 /workflow:brainstorm:synthesis  # 生成综合规范
 ```
 
-**阶段 2：行动规划**
+**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
+```bash
+# 矩阵探索模式 - 多个风格×布局变体（v4.2.1+）
+/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
+
+# 快速模仿模式 - 单一设计快速复制（v4.2.1+）
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# 与会话集成
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+
+# 或者运行单独的设计阶段
+/workflow:ui-design:extract --images "refs/*.png" --variants 3
+/workflow:ui-design:consolidate --variants "variant-1,variant-3"
+/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
+
+# 预览生成的原型
+# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/compare.html
+# 选项2：启动本地服务器
+cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
+# 访问 http://localhost:8080 获取交互式预览和对比工具
+
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
+```
+
+**阶段 3：行动规划**
 ```bash
 # 创建可执行的实现计划
 /workflow:plan "实现基于 JWT 的认证系统"
@@ -166,7 +282,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 /workflow:tdd-plan "使用测试优先开发实现认证"
 ```
 
-**阶段 3：执行**
+**阶段 4：执行**
 ```bash
 # 使用 AI 智能体执行任务
 /workflow:execute
@@ -175,7 +291,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 /workflow:status
 ```
 
-**阶段 4：测试与质量保证**
+**阶段 5：测试与质量保证**
 ```bash
 # 生成独立测试修复工作流（v3.2.2+）
 /workflow:test-gen WFS-auth  # 创建 WFS-test-auth 会话
@@ -248,13 +364,124 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 |---|---|
 | `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
 | `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
+| `/workflow:ui-design:explore-auto` | **v4.2.1** 矩阵探索模式 - 生成多个风格×布局变体，全面探索设计方向。 |
+| `/workflow:ui-design:imitate-auto` | **v4.2.1** 快速模仿模式 - 单一设计快速复制，自动截图和直接令牌提取。 |
+| `/workflow:ui-design:extract` | **v4.2.1** 使用 Claude 原生分析从图像/文本提取设计。单次生成变体。 |
+| `/workflow:ui-design:consolidate` | **v4.2.1** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
+| `/workflow:ui-design:generate` | **v4.2.1** 生成矩阵模式（风格×布局组合）的令牌驱动 HTML/CSS 原型。 |
+| `/workflow:ui-design:update` | **v4.2.1** 将最终确定的设计系统集成到头脑风暴产物中。 |
 | `/workflow:plan` | 从描述创建详细、可执行的计划。 |
-| `/workflow:tdd-plan` | 创建测试驱动开发工作流，包含 Red-Green-Refactor 循环。 |
+| `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
 | `/workflow:execute` | 自主执行当前的工作流计划。 |
 | `/workflow:status` | 显示工作流的当前状态。 |
-| `/workflow:test-gen` | 创建独立测试修复工作流，用于验证已完成的实现。 |
+| `/workflow:test-gen [--use-codex] <session>` | 为已完成实现创建独立测试生成工作流，支持自动诊断和修复。 |
 | `/workflow:tdd-verify` | 验证 TDD 合规性并生成质量报告。 |
 | `/workflow:review` | **可选** 手动审查（仅在明确需要时使用，测试通过即代表代码已批准）。 |
+| `/workflow:tools:test-context-gather` | 分析测试覆盖率，识别缺失的测试文件。 |
+| `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
+| `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
+
+### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.2.1)*
+
+设计工作流系统提供完整的 UI 设计精炼，具备**纯 Claude 执行**、**智能页面推断**和**零外部依赖**。
+
+#### 核心命令
+
+**`/workflow:ui-design:explore-auto`** - 矩阵探索模式
+```bash
+# 全面探索 - 多个风格×布局变体
+/workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
+
+# 与图像和会话集成
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+
+# 纯文本模式，带页面推断
+/workflow:ui-design:explore-auto --prompt "电商：首页，产品，购物车" --style-variants 2 --layout-variants 2
+```
+- **🎯 矩阵模式**: 生成所有风格×布局组合
+- **📊 全面探索**: 比较多个设计方向
+- **🔍 交互式对比**: 带视口控制的并排比较
+- **✅ 跨页面验证**: 多页面设计的自动一致性检查
+- **⚡ 批量选择**: 按风格或布局快速选择
+
+**`/workflow:ui-design:imitate-auto`** - 快速模仿模式
+```bash
+# 快速单一设计复制
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# 与会话集成
+/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
+
+# 从 URL 自动截图（需要 Playwright）
+/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
+```
+- **⚡ 速度优化**: 比 explore-auto 快 5-10 倍
+- **📸 自动截图**: 使用 Playwright/Chrome 自动捕获 URL 截图
+- **🎯 直接提取**: 跳过变体选择，直接进入实现
+- **🔧 单一设计聚焦**: 最适合快速复制现有设计
+
+**`/workflow:ui-design:style-consolidate`** - 验证和合并令牌
+```bash
+# 整合选定的风格变体
+/workflow:ui-design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+```
+- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
+- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
+
+**`/workflow:ui-design:generate`** - 生成 HTML/CSS 原型
+```bash
+# 矩阵模式 - 风格×布局组合
+/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
+
+# 单页面多变体
+/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
+```
+- **🎯 矩阵生成**: 创建所有风格×布局组合
+- **📊 多页面支持**: 跨页面一致的设计系统
+- **✅ 一致性验证**: 自动跨页面一致性报告（v4.2.0+）
+- **🔍 交互式预览**: `compare.html` 并排比较
+- **📋 批量选择**: 按风格或布局过滤器快速选择
+
+**`/workflow:ui-design:update`** - 集成设计系统
+```bash
+# 使用设计系统更新头脑风暴产物
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
+```
+- **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md`
+- **使设计令牌可用于任务生成**
+
+#### 预览系统
+
+运行 `ui-generate` 后，您将获得交互式预览工具：
+
+**快速预览**（直接浏览器）:
+```bash
+# 导航到原型目录
+cd .workflow/WFS-auth/.design/prototypes
+# 在浏览器中打开 index.html（双击或执行）:
+open index.html  # macOS
+start index.html  # Windows
+xdg-open index.html  # Linux
+```
+
+**完整预览**（本地服务器 - 推荐）:
+```bash
+cd .workflow/WFS-auth/.design/prototypes
+# 选择一个:
+python -m http.server 8080      # Python
+npx http-server -p 8080         # Node.js
+php -S localhost:8080           # PHP
+# 访问: http://localhost:8080
+```
+
+**预览功能**:
+- `index.html`: 包含所有原型的主导航
+- `compare.html`: 带视口控制的并排对比（桌面/平板/移动）
+- 同步滚动用于布局对比
+- 动态页面切换
+- 实时响应式测试
+
+---
 
 ### **任务与内存命令**
 
@@ -267,92 +494,6 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 
 ---
 
-## ⚙️ 配置
-
-### **前置要求：必需工具**
-
-在使用 CCW 之前，请安装以下命令行工具：
-
-#### **核心 CLI 工具**
-
-| 工具 | 用途 | 安装方式 |
-|------|------|----------|
-| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
-| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
-| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) |
-
-#### **系统实用工具**
-
-| 工具 | 用途 | 安装方式 |
-|------|------|----------|
-| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
-| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) |
-
-**快速安装（所有工具）：**
-
-```bash
-# macOS
-brew install ripgrep jq
-npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
-
-# Ubuntu/Debian
-sudo apt install ripgrep jq
-npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
-
-# Windows (Chocolatey)
-choco install ripgrep jq
-npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
-```
-
-### **必需: Gemini CLI 设置**
-
-配置 Gemini CLI 以实现最佳集成：
-
-```json
-// ~/.gemini/settings.json
-{
-  "contextFileName": ["CLAUDE.md", "GEMINI.md"]
-}
-```
-
-### **推荐: .geminiignore**
-
-通过排除不必要的文件来优化性能：
-
-```bash
-# .geminiignore (在项目根目录)
-/dist/
-/build/
-/node_modules/
-/.next/
-*.tmp
-*.log
-/temp/
-
-# 包含重要文档
-!README.md
-!**/CLAUDE.md
-```
-
-### **可选: MCP 工具** *(增强分析)*
-
-MCP (模型上下文协议) 工具提供高级代码库分析。**完全可选** - CCW 在没有它们的情况下也能完美工作。
-
-#### 可用的 MCP 服务器
-
-| MCP 服务器 | 用途 | 安装指南 |
-|------------|------|---------|
-| **Exa MCP** | 外部 API 模式和最佳实践 | [安装指南](https://github.com/exa-labs/exa-mcp-server) |
-| **Code Index MCP** | 高级内部代码搜索 | [安装指南](https://github.com/johnhuang316/code-index-mcp) |
-
-#### 启用后的好处
-- 📊 **更快分析**: 直接代码库索引 vs 手动搜索
-- 🌐 **外部上下文**: 真实世界的 API 模式和示例
-- 🔍 **高级搜索**: 模式匹配和相似性检测
-- ⚡ **自动回退**: MCP 不可用时使用传统工具
-
----
-
 ## 🧩 工作原理：设计理念
 
 ### 核心问题

RELEASE_NOTES_v3.2.3.md

@@ -1,252 +0,0 @@
-# v3.2.3 - Version Management System
-
-## 🎉 Release Date
-2025-10-03
-
-## ✨ Overview
-
-This release introduces a comprehensive version management and upgrade notification system, making it easy to track your Claude Code Workflow installation and stay up-to-date with the latest releases.
-
-## 🆕 New Features
-
-### `/version` Command
-
-A powerful new command that provides complete version information and automatic update checking:
-
-**Features:**
-- 📊 **Version Display**: Shows both local and global installation versions
-- 🌐 **GitHub Integration**: Fetches latest stable release and development commits
-- 🔄 **Smart Comparison**: Automatically compares installed version with latest available
-- 💡 **Upgrade Recommendations**: Provides installation commands for easy upgrading
-- ⚡ **Fast Execution**: 30-second timeout for network calls, graceful offline handling
-
-**Usage:**
-```bash
-/version
-```
-
-**Example Output:**
-```
-Installation Status:
-- Local: No project-specific installation
-- Global: ✅ Installed at ~/.claude
-  - Version: v3.2.3
-  - Installed: 2025-10-03T05:01:34Z
-
-Latest Releases:
-- Stable: v3.2.3 (2025-10-03T04:10:08Z)
-  - v3.2.3: Version Management System
-- Latest Commit: c5c36a2 (2025-10-03T05:00:06Z)
-  - fix: Optimize version command API calls and data extraction
-
-Status: ✅ You are on the latest stable version (3.2.3)
-```
-
-### Version Tracking System
-
-**Version Files:**
-- `.claude/version.json` - Local project installation tracking
-- `~/.claude/version.json` - Global installation tracking
-
-**Tracked Information:**
-```json
-{
-  "version": "v3.2.3",
-  "installation_mode": "Global",
-  "installation_path": "C:\\Users\\username\\.claude",
-  "source_branch": "main",
-  "installation_date_utc": "2025-10-03T05:01:34Z"
-}
-```
-
-### GitHub API Integration
-
-**Endpoints Used:**
-- **Latest Release**: `https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest`
-  - Extracts: tag_name, release name, published date
-- **Latest Commit**: `https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main`
-  - Extracts: commit SHA, message, author date
-
-**Network Handling:**
-- 30-second timeout for slow connections
-- Graceful error handling for offline scenarios
-- No external dependencies (uses curl and grep/sed)
-
-## 🔄 What's Changed
-
-### Documentation Updates
-
-**Updated Files:**
-- ✅ `CHANGELOG.md` - Added comprehensive v3.2.3 release notes
-- ✅ `README.md` - Updated version badge to v3.2.3, added `/version` command
-- ✅ `README_CN.md` - Updated version badge and command reference (Chinese)
-- ✅ `.claude/commands/version.md` - Complete implementation guide
-
-**Version References:**
-- All version badges updated from v3.2.2 to v3.2.3
-- "What's New" sections updated with v3.2.3 features
-- Command reference tables include `/version` command
-
-### Installation Scripts Enhancement
-
-**Future Enhancement** (for next release):
-- Installation scripts will automatically create `version.json` files
-- Track installation mode (local vs global)
-- Record installation timestamp
-- Support version tracking for both stable and development installations
-
-## 📋 Version Comparison Scenarios
-
-### Scenario 1: Up to Date
-```
-✅ You are on the latest stable version (3.2.3)
-```
-
-### Scenario 2: Upgrade Available
-```
-⬆️ A newer stable version is available: v3.2.4
-Your version: 3.2.3
-
-To upgrade:
-PowerShell: iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1)
-Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
-```
-
-### Scenario 3: Development Version
-```
-✨ You are running a development version (3.3.0-dev)
-This is newer than the latest stable release (v3.2.3)
-```
-
-## 🛠️ Technical Details
-
-### Implementation Highlights
-
-**Simple Bash Commands:**
-- No jq dependency required (uses grep/sed for JSON parsing)
-- Cross-platform compatible (Windows Git Bash, Linux, macOS)
-- Version comparison using `sort -V` for semantic versioning
-- Direct API access using curl with error suppression
-
-**Command Structure:**
-```bash
-# Check local version
-test -f ./.claude/version.json && cat ./.claude/version.json
-
-# Check global version
-test -f ~/.claude/version.json && cat ~/.claude/version.json
-
-# Fetch latest release (with timeout)
-curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null
-
-# Extract version
-grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4
-
-# Compare versions
-printf "%s\n%s" "3.2.2" "3.2.3" | sort -V | tail -n 1
-```
-
-## 📊 Benefits
-
-### User Experience
-- 🔍 **Quick version check** with single command
-- 📊 **Comprehensive information** display (local, global, stable, dev)
-- 🔄 **Automatic upgrade notifications** when new versions available
-- 📈 **Development version tracking** for cutting-edge features
-- 🌐 **GitHub integration** for latest updates
-
-### DevOps
-- 📁 **Version tracking** in both local and global installations
-- 🕐 **Installation timestamp** for audit trails
-- 🔀 **Support for both stable and development** branches
-- ⚡ **Fast execution** with 30-second network timeout
-- 🛡️ **Graceful error handling** for offline scenarios
-
-## 🔗 Related Commands
-
-- `/cli:cli-init` - Initialize CLI tool configurations
-- `/workflow:session:list` - List workflow sessions
-- `/update-memory-full` - Update project documentation
-
-## 📦 Installation
-
-### Fresh Installation
-
-**Windows (PowerShell):**
-```powershell
-iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1)
-```
-
-**Linux/macOS (Bash):**
-```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
-```
-
-### Upgrade from v3.2.2
-
-Use the same installation commands above. The installer will automatically:
-1. Detect your existing installation
-2. Back up current files (if using `-BackupAll`)
-3. Update to v3.2.3
-4. Create/update `version.json` files
-
-## 🐛 Bug Fixes
-
-- Fixed commit message extraction to handle JSON escape sequences
-- Improved API endpoint from `/branches/main` to `/commits/main` for reliable commit info
-- Added 30-second timeout to all network calls for slow connections
-- Enhanced release name and published date extraction
-
-## 📚 Documentation
-
-### New Documentation
-- `.claude/commands/version.md` - Complete command implementation guide
-  - API endpoints and usage
-  - Timeout configuration
-  - Error handling scenarios
-  - Simple bash command examples
-
-### Updated Documentation
-- `CHANGELOG.md` - v3.2.3 release notes
-- `README.md` - Version badge and command reference
-- `README_CN.md` - Chinese version updates
-
-## 🙏 Credits
-
-This release includes contributions and improvements based on:
-- GitHub API integration for version detection
-- Cross-platform bash command compatibility
-- User feedback on installation and upgrade processes
-
-## 📝 Notes
-
-- **Backward Compatible**: All existing commands and workflows continue to work
-- **No Breaking Changes**: This is a minor release with new features only
-- **Optional Feature**: `/version` command is entirely optional, existing workflows unaffected
-
-## 🚀 What's Next
-
-**Planned for v3.2.4:**
-- Enhanced installation script to auto-create version.json
-- Version tracking in all installation modes
-- Automatic version detection during installation
-
-**Future Enhancements:**
-- Auto-update functionality (opt-in)
-- Version comparison in workflow sessions
-- Release notes display in CLI
-
----
-
-**Full Changelog**: [v3.2.2...v3.2.3](https://github.com/catlog22/Claude-Code-Workflow/compare/v3.2.2...v3.2.3)
-
-**Installation:**
-```bash
-# One-line install (recommended)
-bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
-
-# Or use specific version tag
-git clone -b v3.2.3 https://github.com/catlog22/Claude-Code-Workflow.git
-```
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)

install-remote.ps1

@@ -260,7 +260,8 @@ function Invoke-LocalInstaller {
     param(
         [string]$RepoDir,
         [string]$VersionInfo = "",
-        [string]$BranchInfo = ""
+        [string]$BranchInfo = "",
+        [string]$CommitSha = ""
     )
 
     $installerPath = Join-Path $RepoDir "Install-Claude.ps1"
@@ -285,9 +286,10 @@ function Invoke-LocalInstaller {
     if ($NonInteractive) { $params["NonInteractive"] = $NonInteractive }
     if ($BackupAll) { $params["BackupAll"] = $BackupAll }
 
-    # Pass version and branch information
+    # Pass version, branch, and commit information
     if ($VersionInfo) { $params["SourceVersion"] = $VersionInfo }
     if ($BranchInfo) { $params["SourceBranch"] = $BranchInfo }
+    if ($CommitSha) { $params["SourceCommit"] = $CommitSha }
 
     try {
         # Change to repo directory and run installer
@@ -416,10 +418,10 @@ function Get-UserVersionChoice {
         $response = Invoke-RestMethod -Uri $apiUrl -UseBasicParsing -TimeoutSec 5
         $latestVersion = $response.tag_name
 
-        # Parse and format release date
+        # Parse and format release date to local time
         if ($response.published_at) {
-            $publishDate = [DateTime]::Parse($response.published_at)
-            $latestStableDate = $publishDate.ToString("yyyy-MM-dd HH:mm UTC")
+            $publishDate = [DateTime]::Parse($response.published_at).ToLocalTime()
+            $latestStableDate = $publishDate.ToString("yyyy-MM-dd HH:mm")
         }
 
         Write-ColorOutput "Latest stable: $latestVersion ($latestStableDate)" $ColorSuccess
@@ -433,10 +435,10 @@ function Get-UserVersionChoice {
         $commitResponse = Invoke-RestMethod -Uri $commitUrl -UseBasicParsing -TimeoutSec 5
         $latestCommitId = $commitResponse.sha.Substring(0, 7)
 
-        # Parse and format commit date
+        # Parse and format commit date to local time
         if ($commitResponse.commit.committer.date) {
-            $commitDate = [DateTime]::Parse($commitResponse.commit.committer.date)
-            $latestCommitDate = $commitDate.ToString("yyyy-MM-dd HH:mm UTC")
+            $commitDate = [DateTime]::Parse($commitResponse.commit.committer.date).ToLocalTime()
+            $latestCommitDate = $commitDate.ToString("yyyy-MM-dd HH:mm")
         }
 
         Write-ColorOutput "Latest commit: $latestCommitId ($latestCommitDate)" $ColorSuccess
@@ -562,14 +564,51 @@ function Main {
             throw "Extraction failed"
         }
 
+        # Get commit SHA from the downloaded repository first
+        $commitSha = ""
+        try {
+            Push-Location $repoDir
+            $commitSha = (git rev-parse --short HEAD 2>$null)
+            if (-not $commitSha) {
+                # Fallback: try to get from GitHub API
+                $commitUrl = "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/$Branch"
+                $commitResponse = Invoke-RestMethod -Uri $commitUrl -UseBasicParsing -TimeoutSec 5 -ErrorAction SilentlyContinue
+                if ($commitResponse.sha) {
+                    $commitSha = $commitResponse.sha.Substring(0, 7)
+                }
+            }
+            Pop-Location
+        } catch {
+            Pop-Location
+            $commitSha = "unknown"
+        }
+
         # Determine version and branch information to pass
-        $versionToPass = if ($Tag) { $Tag } else { "latest" }
+        $versionToPass = ""
+
+        if ($Tag) {
+            # Specific tag version
+            $versionToPass = $Tag -replace '^v', ''  # Remove 'v' prefix
+        } elseif ($Version -eq "stable") {
+            # Auto-detected latest stable
+            $latestTag = Get-LatestRelease
+            if ($latestTag) {
+                $versionToPass = $latestTag -replace '^v', ''
+            } else {
+                # Fallback: use commit SHA as version
+                $versionToPass = "dev-$commitSha"
+            }
+        } else {
+            # Latest development or branch - use commit SHA as version
+            $versionToPass = "dev-$commitSha"
+        }
+
         $branchToPass = if ($Version -eq "branch") { $Branch } elseif ($Version -eq "latest") { "main" } elseif ($Tag) { $Tag } else { "main" }
 
-        Write-ColorOutput "Version info: $versionToPass (branch: $branchToPass)" $ColorInfo
+        Write-ColorOutput "Version info: $versionToPass (branch: $branchToPass, commit: $commitSha)" $ColorInfo
 
         # Run local installer with version information
-        $success = Invoke-LocalInstaller -RepoDir $repoDir -VersionInfo $versionToPass -BranchInfo $branchToPass
+        $success = Invoke-LocalInstaller -RepoDir $repoDir -VersionInfo $versionToPass -BranchInfo $branchToPass -CommitSha $commitSha
         if (-not $success) {
             throw "Installation script failed"
         }

install-remote.sh

@@ -43,8 +43,8 @@ function show_header() {
 
 function test_prerequisites() {
     # Test bash version
-    if [ "${BASH_VERSINFO[0]}" -lt 4 ]; then
-        write_color "ERROR: Bash 4.0 or higher is required" "$COLOR_ERROR"
+    if [ "${BASH_VERSINFO[0]}" -lt 2 ]; then
+        write_color "ERROR: Bash 2.0 or higher is required" "$COLOR_ERROR"
         write_color "Current version: ${BASH_VERSION}" "$COLOR_ERROR"
         return 1
     fi
@@ -209,6 +209,9 @@ function extract_repository() {
 
 function invoke_local_installer() {
     local repo_dir="$1"
+    local version_info="$2"
+    local branch_info="$3"
+    local commit_sha="$4"
     local installer_path="${repo_dir}/Install-Claude.sh"
 
     # Make installer executable
@@ -249,6 +252,19 @@ function invoke_local_installer() {
         params+=("-BackupAll")
     fi
 
+    # Pass version, branch, and commit information
+    if [ -n "$version_info" ]; then
+        params+=("-SourceVersion" "$version_info")
+    fi
+
+    if [ -n "$branch_info" ]; then
+        params+=("-SourceBranch" "$branch_info")
+    fi
+
+    if [ -n "$commit_sha" ]; then
+        params+=("-SourceCommit" "$commit_sha")
+    fi
+
     # Execute installer
     if (cd "$repo_dir" && "$installer_path" "${params[@]}"); then
         return 0
@@ -452,14 +468,19 @@ function get_user_version_choice() {
             latest_version=$(echo "$release_data" | jq -r '.tag_name' 2>/dev/null)
             local published_at=$(echo "$release_data" | jq -r '.published_at' 2>/dev/null)
             if [ -n "$published_at" ] && [ "$published_at" != "null" ]; then
-                # Format: 2025-10-02T04:27:21Z -> 2025-10-02 04:27 UTC
-                latest_date=$(echo "$published_at" | sed 's/T/ /' | sed 's/Z/ UTC/' | cut -d'.' -f1)
+                # Convert UTC to local time
+                if command -v date &> /dev/null; then
+                    latest_date=$(date -d "$published_at" '+%Y-%m-%d %H:%M' 2>/dev/null || date -jf '%Y-%m-%dT%H:%M:%SZ' "$published_at" '+%Y-%m-%d %H:%M' 2>/dev/null)
+                fi
             fi
         else
             latest_version=$(echo "$release_data" | grep -o '"tag_name":\s*"[^"]*"' | sed 's/"tag_name":\s*"\([^"]*\)"/\1/')
             local published_at=$(echo "$release_data" | grep -o '"published_at":\s*"[^"]*"' | sed 's/"published_at":\s*"\([^"]*\)"/\1/')
             if [ -n "$published_at" ]; then
-                latest_date=$(echo "$published_at" | sed 's/T/ /' | sed 's/Z/ UTC/' | cut -d'.' -f1)
+                # Convert UTC to local time
+                if command -v date &> /dev/null; then
+                    latest_date=$(date -d "$published_at" '+%Y-%m-%d %H:%M' 2>/dev/null || date -jf '%Y-%m-%dT%H:%M:%SZ' "$published_at" '+%Y-%m-%d %H:%M' 2>/dev/null)
+                fi
             fi
         fi
     fi
@@ -480,13 +501,19 @@ function get_user_version_choice() {
             commit_id=$(echo "$commit_data" | jq -r '.sha' 2>/dev/null | cut -c1-7)
             local committer_date=$(echo "$commit_data" | jq -r '.commit.committer.date' 2>/dev/null)
             if [ -n "$committer_date" ] && [ "$committer_date" != "null" ]; then
-                commit_date=$(echo "$committer_date" | sed 's/T/ /' | sed 's/Z/ UTC/' | cut -d'.' -f1)
+                # Convert UTC to local time
+                if command -v date &> /dev/null; then
+                    commit_date=$(date -d "$committer_date" '+%Y-%m-%d %H:%M' 2>/dev/null || date -jf '%Y-%m-%dT%H:%M:%SZ' "$committer_date" '+%Y-%m-%d %H:%M' 2>/dev/null)
+                fi
             fi
         else
             commit_id=$(echo "$commit_data" | grep -o '"sha":\s*"[^"]*"' | head -1 | sed 's/"sha":\s*"\([^"]*\)"/\1/' | cut -c1-7)
             local committer_date=$(echo "$commit_data" | grep -o '"date":\s*"[^"]*"' | head -1 | sed 's/"date":\s*"\([^"]*\)"/\1/')
             if [ -n "$committer_date" ]; then
-                commit_date=$(echo "$committer_date" | sed 's/T/ /' | sed 's/Z/ UTC/' | cut -d'.' -f1)
+                # Convert UTC to local time
+                if command -v date &> /dev/null; then
+                    commit_date=$(date -d "$committer_date" '+%Y-%m-%d %H:%M' 2>/dev/null || date -jf '%Y-%m-%dT%H:%M:%SZ' "$committer_date" '+%Y-%m-%d %H:%M' 2>/dev/null)
+                fi
             fi
         fi
     fi
@@ -621,8 +648,54 @@ function main() {
         if [ $extract_status -eq 0 ] && [ -n "$repo_dir" ] && [ -d "$repo_dir" ]; then
             write_color "Extraction successful: $repo_dir" "$COLOR_SUCCESS"
 
-            # Run local installer
-            if invoke_local_installer "$repo_dir"; then
+            # Get commit SHA from the downloaded repository first
+            local commit_sha=""
+            if command -v git &> /dev/null && [ -d "$repo_dir/.git" ]; then
+                commit_sha=$(cd "$repo_dir" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+            else
+                # Fallback: try to get from GitHub API
+                local temp_branch="main"
+                [ "$VERSION_TYPE" = "branch" ] && temp_branch="$BRANCH"
+                commit_sha=$(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/$temp_branch" 2>/dev/null | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4 | cut -c1-7)
+                [ -z "$commit_sha" ] && commit_sha="unknown"
+            fi
+
+            # Determine version and branch information to pass
+            local version_to_pass=""
+            local branch_to_pass=""
+
+            if [ -n "$TAG_VERSION" ]; then
+                # Specific tag version - remove 'v' prefix
+                version_to_pass="${TAG_VERSION#v}"
+            elif [ "$VERSION_TYPE" = "stable" ]; then
+                # Auto-detected latest stable
+                local latest_tag
+                latest_tag=$(get_latest_release)
+                if [ -n "$latest_tag" ]; then
+                    version_to_pass="${latest_tag#v}"
+                else
+                    # Fallback: use commit SHA as version
+                    version_to_pass="dev-$commit_sha"
+                fi
+            else
+                # Latest development or branch - use commit SHA as version
+                version_to_pass="dev-$commit_sha"
+            fi
+
+            if [ "$VERSION_TYPE" = "branch" ]; then
+                branch_to_pass="$BRANCH"
+            elif [ "$VERSION_TYPE" = "latest" ]; then
+                branch_to_pass="main"
+            elif [ -n "$TAG_VERSION" ]; then
+                branch_to_pass="$TAG_VERSION"
+            else
+                branch_to_pass="main"
+            fi
+
+            write_color "Version info: $version_to_pass (branch: $branch_to_pass, commit: $commit_sha)" "$COLOR_INFO"
+
+            # Run local installer with version information
+            if invoke_local_installer "$repo_dir" "$version_to_pass" "$branch_to_pass" "$commit_sha"; then
                 success=true
                 echo ""
                 write_color "✓ Remote installation completed successfully!" "$COLOR_SUCCESS"

ui-instantiate-analysis.md

@@ -0,0 +1,231 @@
+# UI原型实例化脚本分析报告
+
+## 问题现象
+
+在执行 `ui-instantiate-prototypes.sh` 脚本时，生成了 `style-4` 的原型文件（如 `login-style-4-layout-1.html`），但实际上 `style-consolidation` 目录下只有3个样式目录（style-1, style-2, style-3）。
+
+## 调查结果
+
+### 1. 目录结构验证
+
+```bash
+# 实际存在的样式目录
+.workflow/.design/run-20251009-210559/style-consolidation/
+├── style-1/
+├── style-2/
+└── style-3/
+
+# 生成的原型文件包含
+prototypes/login-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
+prototypes/sidebar-style-4-layout-1.html  ❌ 引用不存在的 ../style-consolidation/style-4/tokens.css
+```
+
+### 2. consolidation-report.json 确认
+
+```json
+{
+  "variant_count": 3,  // 明确显示只有3个变体
+  "variants": [
+    {"id": "style-1"},
+    {"id": "style-2"},
+    {"id": "style-3"}
+  ]
+}
+```
+
+### 3. PREVIEW.md 显示异常
+
+```markdown
+- **Style Variants:** 4  ⚠️ 与实际不符
+- **Total Prototypes:** 24  (4 × 3 × 2 = 24)
+```
+
+### 4. 脚本auto_detect_style_variants()函数
+
+```bash
+# 位置：.claude/scripts/ui-instantiate-prototypes.sh 第52-71行
+auto_detect_style_variants() {
+    local base_path="$1"
+    local style_dir="$base_path/../style-consolidation"
+
+    # 统计style-*目录数量
+    local count=$(find "$style_dir" -maxdepth 1 -type d -name "style-*" | wc -l)
+    echo "$count"
+}
+```
+
+**验证测试**：
+```bash
+cd .workflow/.design/run-20251009-210559/style-consolidation
+find . -maxdepth 1 -type d -name "style-*" | wc -l
+# 输出：3 ✅ 函数逻辑正确
+```
+
+## 根本原因分析
+
+### ⚠️ 参数覆盖问题
+
+脚本虽然有自动检测功能，但**允许手动参数覆盖**：
+
+```bash
+# 自动检测模式（正确）
+ui-instantiate-prototypes.sh prototypes/  # 会自动检测到3个样式
+
+# 手动模式（错误来源）
+ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 4 3  # 强制指定4个样式变体 ❌
+```
+
+### 🔍 实际调用场景
+
+根据工作流命令 `.claude/commands/workflow/ui-design/generate.md` 第79-82行：
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # 默认为3
+```
+
+**推断的问题来源**：
+1. 工作流命令被手动调用时，传入了 `--style-variants 4`
+2. 这个参数被直接传递给 `ui-instantiate-prototypes.sh` 脚本
+3. 脚本没有验证参数值与实际目录数量是否匹配
+4. 导致生成了引用不存在的style-4目录的HTML文件
+
+## 问题影响
+
+### 生成的style-4文件问题
+
+所有 `*-style-4-*.html` 文件都会出现CSS加载失败：
+
+```html
+<!-- 文件中的CSS引用 -->
+<link rel="stylesheet" href="../style-consolidation/style-4/tokens.css">
+<!-- ❌ 该路径不存在，导致样式无法加载 -->
+```
+
+### 影响范围
+
+- `login-style-4-layout-{1,2,3}.html` - 3个文件 ❌
+- `sidebar-style-4-layout-{1,2,3}.html` - 3个文件 ❌
+- 对应的 `*-notes.md` 文件 - 6个说明文件（内容错误）
+
+## 解决方案
+
+### 方案1：重新生成（推荐）
+
+```bash
+cd .workflow/.design/run-20251009-210559/prototypes
+
+# 删除错误的style-4文件
+rm -f *-style-4-*
+
+# 重新运行脚本（使用自动检测）
+~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
+```
+
+### 方案2：脚本增强（预防）
+
+在 `ui-instantiate-prototypes.sh` 中添加参数验证：
+
+```bash
+# 在第239行之后添加
+# Validate STYLE_VARIANTS matches actual directories
+actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" | wc -l)
+if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+    log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+    log_info "Auto-correcting to $actual_styles style variants"
+    STYLE_VARIANTS=$actual_styles
+fi
+```
+
+### 方案3：工作流命令修复
+
+在 `.claude/commands/workflow/ui-design/generate.md` 中添加验证：
+
+```bash
+# Phase 1: Path Resolution & Context Loading (第79-82行之后)
+style_variants = --style-variants OR 3  # Default to 3
+
+# 添加验证逻辑
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+IF style_variants > actual_styles:
+    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
+    REPORT: "Auto-correcting to {actual_styles} style variants"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= 5
+```
+
+## 预防措施
+
+1. **优先使用自动检测**：
+   ```bash
+   # ✅ 推荐：让脚本自动检测
+   ui-instantiate-prototypes.sh prototypes/
+
+   # ⚠️ 谨慎：手动指定参数（需确保正确）
+   ui-instantiate-prototypes.sh prototypes/ "login,sidebar" 3 3
+   ```
+
+2. **验证consolidation输出**：
+   ```bash
+   # 生成原型前，先确认样式数量
+   jq '.variant_count' style-consolidation/consolidation-report.json
+   ```
+
+3. **使用工作流命令**：
+   ```bash
+   # 工作流命令会自动处理参数验证
+   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+   ```
+
+## 技术细节
+
+### 自动检测逻辑流程
+
+```mermaid
+graph TD
+    A[调用脚本] --> B{检查参数数量}
+    B -->|1个参数| C[自动检测模式]
+    B -->|4个参数| D[手动模式]
+    C --> E[检测style目录]
+    D --> F[使用传入参数]
+    E --> G[验证目录存在]
+    F --> G
+    G -->|不匹配| H[⚠️ 生成错误文件]
+    G -->|匹配| I[✅ 正常生成]
+```
+
+### find命令行为
+
+```bash
+# 正确的检测命令
+find style-consolidation -maxdepth 1 -type d -name "style-*"
+# 输出：
+# style-consolidation/style-1
+# style-consolidation/style-2
+# style-consolidation/style-3
+
+# wc -l 统计行数 = 3 ✅
+
+# 注意：style-extraction 不会被匹配（它在父目录）
+# find . -maxdepth 1 -type d -name "style-*"
+# 只会在当前目录搜索，不会递归到子目录
+```
+
+## 总结
+
+### 问题根源
+✅ **确认**：脚本被手动调用时传入了错误的 `--style-variants 4` 参数，但实际只有3个样式目录存在。
+
+### 脚本行为
+✅ **确认**：`auto_detect_style_variants()` 函数逻辑正确，能够正确检测到3个样式目录。
+
+### 修复优先级
+1. 🔴 **立即**：删除错误的style-4文件，重新生成
+2. 🟡 **短期**：在脚本中添加参数验证逻辑
+3. 🟢 **长期**：在工作流命令中添加防护验证
+
+### 最佳实践
+- 优先使用脚本的自动检测模式
+- 在手动指定参数前，先验证 `consolidation-report.json`
+- 使用工作流命令而非直接调用脚本

ui-workflow-parameter-clarity-report.md

@@ -0,0 +1,425 @@
+# UI设计工作流参数清晰度分析报告
+
+## 📋 执行摘要
+
+**问题来源**：用户手动调用 `/workflow:ui-design:generate` 时传入了 `--style-variants 4`，但实际只有3个样式目录存在，导致生成了引用不存在CSS文件的 `style-4` 原型。
+
+**根本原因**：工作流命令链中参数命名不一致、验证缺失、文档说明不清晰。
+
+## 🔍 关键发现
+
+### 1. 参数命名不一致
+
+| 命令 | 参数名称 | 默认值 | 说明 |
+|------|---------|--------|------|
+| `extract` | `--variants` | 1 | ⚠️ 未在文档中明确说明默认值 |
+| `consolidate` | `--variants` | 所有变体 | ⚠️ 与extract同名但语义不同 |
+| `generate` | `--style-variants` | 3 | ⚠️ 名称不一致，默认值说明不清晰 |
+
+**问题**：
+- `extract` 和 `consolidate` 使用 `--variants`，但 `generate` 使用 `--style-variants`
+- `--variants` 在两个命令中含义不同：
+  - `extract`：生成多少个变体
+  - `consolidate`：处理多少个变体
+
+### 2. 命名转换混淆
+
+```
+extract 输出        → consolidate 处理      → generate 使用
+variant-1           → style-1/              → login-style-1-layout-1.html
+variant-2           → style-2/              → login-style-2-layout-1.html
+variant-3           → style-3/              → login-style-3-layout-1.html
+```
+
+**问题**：
+- `variant-N` 到 `style-N` 的转换没有文档说明
+- 增加了用户的认知负担
+- 容易造成混淆和错误
+
+### 3. 验证缺失
+
+#### ❌ 当前状态（generate.md 第79-82行）
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # Default to 3
+VALIDATE: 1 <= style_variants <= 5
+```
+
+**问题**：
+- ✅ 验证范围（1-5）
+- ❌ 不验证是否匹配实际目录数量
+- ❌ 允许传入 `4` 但实际只有 `3` 个目录
+
+#### ✅ 应有的验证
+
+```bash
+style_variants = --style-variants OR 3
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+
+IF style_variants > actual_styles:
+    WARN: "Requested {style_variants} styles, but only {actual_styles} exist"
+    REPORT: "Auto-correcting to {actual_styles} style variants"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= actual_styles
+```
+
+### 4. 文档清晰度问题
+
+#### extract.md
+
+**问题点**：
+- ⚠️ 默认值 `1` 未在 `usage` 或 `argument-hint` 中说明
+- ⚠️ 输出的 `variant-N` 命名未解释后续转换为 `style-N`
+
+**当前文档**（第580行附近）：
+```
+"id": "variant-2"  # 缺少说明这会成为 style-2 目录
+```
+
+#### consolidate.md
+
+**问题点**：
+- ⚠️ `--variants` 与 `extract` 同名但语义不同
+- ⚠️ 默认行为（处理所有变体）不够突出
+- ⚠️ `variant-N` → `style-N` 转换未文档化
+
+#### generate.md
+
+**问题点**：
+- ⚠️ `--style-variants` 名称与前置命令不一致
+- ⚠️ 默认值 `3` 的来源和意义不清晰
+- ⚠️ 自动检测机制未说明
+- ❌ 手动覆盖无验证
+
+**当前文档**（第79-82行）：
+```bash
+style_variants = --style-variants OR 3  # Default to 3
+VALIDATE: 1 <= style_variants <= 5
+```
+
+## 💡 改进方案
+
+### 方案1：代码层面改进（推荐）
+
+#### 1.1 统一参数命名
+
+```diff
+# extract.md
+- usage: /workflow:ui-design:extract [--variants <count>]
++ usage: /workflow:ui-design:extract [--style-variants <count>]
+
+# consolidate.md
+- usage: /workflow:ui-design:consolidate [--variants <count>]
++ usage: /workflow:ui-design:consolidate [--style-variants <count>]
+
+# generate.md (保持不变)
+  usage: /workflow:ui-design:generate [--style-variants <count>]
+```
+
+**优点**：
+- ✅ 全链路参数名称统一
+- ✅ 语义清晰（style-variants）
+- ✅ 降低混淆风险
+
+#### 1.2 添加验证逻辑（关键）
+
+##### generate.md 改进
+
+```bash
+# Phase 1: Path Resolution & Context Loading
+style_variants = --style-variants OR 3  # Default to 3
+
+# 🆕 添加验证逻辑
+actual_styles = count_directories({base_path}/style-consolidation/style-*)
+
+IF actual_styles == 0:
+    ERROR: "No style directories found in {base_path}/style-consolidation/"
+    SUGGEST: "Run /workflow:ui-design:consolidate first"
+    EXIT 1
+
+IF style_variants > actual_styles:
+    WARN: "⚠️ Requested {style_variants} style variants, but only {actual_styles} directories exist"
+    REPORT: "   Auto-correcting to {actual_styles} style variants"
+    REPORT: "   Available styles: {list_directories(style-consolidation/style-*)}"
+    style_variants = actual_styles
+
+VALIDATE: 1 <= style_variants <= actual_styles
+```
+
+##### ui-instantiate-prototypes.sh 改进
+
+在脚本第239行之后添加：
+
+```bash
+# Validate STYLE_VARIANTS matches actual directories
+if [ "$STYLE_VARIANTS" -gt 0 ]; then
+    actual_styles=$(find "$BASE_PATH/../style-consolidation" -maxdepth 1 -type d -name "style-*" 2>/dev/null | wc -l)
+
+    if [ "$actual_styles" -eq 0 ]; then
+        log_error "No style directories found in style-consolidation/"
+        log_info "Run /workflow:ui-design:consolidate first"
+        exit 1
+    fi
+
+    if [ "$STYLE_VARIANTS" -gt "$actual_styles" ]; then
+        log_warning "Requested $STYLE_VARIANTS style variants, but only found $actual_styles directories"
+        log_info "Auto-correcting to $actual_styles style variants"
+        STYLE_VARIANTS=$actual_styles
+    fi
+fi
+```
+
+#### 1.3 统一命名约定
+
+##### extract.md 改进
+
+修改输出格式（第580行附近）：
+
+```diff
+# style-cards.json 格式
+{
+  "style_cards": [
+    {
+-     "id": "variant-1",
++     "id": "style-1",
+      "name": "Modern Minimalist",
+      ...
+    }
+  ]
+}
+```
+
+### 方案2：文档层面改进
+
+#### 2.1 extract.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to extract. **Default: 1**
+  - Range: 1-5
+  - Each variant will become an independent design system (style-1, style-2, etc.)
+  - Output IDs use `style-N` format for consistency across the workflow
+
+## Output Format
+
+style-cards.json uses `style-N` IDs that directly correspond to directory names
+created by the consolidate command:
+
+- `style-1` → `style-consolidation/style-1/`
+- `style-2` → `style-consolidation/style-2/`
+```
+
+#### 2.2 consolidate.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to process from style-cards.json.
+  **Default: all available variants**
+  - Processes the first N variants from the style-cards array
+  - Creates separate `style-{n}` directories for each variant
+  - Range: 1 to count available in style-cards.json
+
+## Naming Convention
+
+Variants from extraction are materialized into style directories:
+- Input: `style-cards.json` with `style-1`, `style-2`, `style-3`
+- Output: `style-consolidation/style-1/`, `style-2/`, `style-3/` directories
+```
+
+#### 2.3 generate.md 文档改进
+
+```markdown
+## Parameters
+
+- `--style-variants <count>`: Number of style variants to generate prototypes for.
+  **Default: 3** (can be overridden)
+  - Range: 1-5
+  - ⚠️ **IMPORTANT**: This value MUST match the number of style-* directories in style-consolidation/
+  - If mismatched, the command will auto-correct to the actual directory count
+  - Use auto-detection (omit parameter) for safety
+
+## Auto-Detection vs Manual Override
+
+The command uses intelligent auto-detection:
+
+1. **Auto-Detection** (Recommended):
+   ```bash
+   /workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+   # Automatically counts style-1/, style-2/, style-3/ → uses 3
+   ```
+
+2. **Manual Override** (Use with caution):
+   ```bash
+   /workflow:ui-design:generate --style-variants 4
+   # If only 3 styles exist, auto-corrects to 3 with warning
+   ```
+
+3. **Safety Check**:
+   - Command validates against actual `style-consolidation/style-*` directories
+   - Prevents generation of prototypes referencing non-existent styles
+   - Displays warning and auto-corrects if mismatch detected
+```
+
+### 方案3：用户指南改进
+
+创建 `.claude/commands/workflow/ui-design/README.md`：
+
+```markdown
+# UI Design Workflow Parameter Guide
+
+## Style Variant Count Flow
+
+### 1. Extract Phase
+```bash
+/workflow:ui-design:extract --style-variants 3
+# Generates: style-cards.json with 3 style variants (style-1, style-2, style-3)
+```
+
+### 2. Consolidate Phase
+```bash
+/workflow:ui-design:consolidate --style-variants 3
+# Creates: style-consolidation/style-1/, style-2/, style-3/
+```
+
+### 3. Generate Phase
+```bash
+# ✅ Recommended: Let it auto-detect
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+
+# ⚠️ Manual: Must match consolidation output
+/workflow:ui-design:generate --style-variants 3
+```
+
+## ⚠️ Common Mistakes
+
+### Mistake 1: Mismatched Counts
+```bash
+# ❌ Wrong: Request 4 styles when only 3 exist
+/workflow:ui-design:generate --style-variants 4
+# Only 3 directories in style-consolidation/ → ERROR
+
+# ✅ Correct: Omit parameter for auto-detection
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+```
+
+### Mistake 2: Naming Confusion
+```bash
+# ❌ Don't confuse variant-N with style-N
+# variant-N was old naming in style-cards.json
+# style-N is the current standard across all commands
+```
+
+## 🎯 Best Practices
+
+1. **Use auto-detection**: Omit `--style-variants` in generate command
+2. **Verify consolidation**: Check `consolidation-report.json` before generating
+3. **Use explore-auto**: Automated workflow prevents parameter mismatches
+4. **Check directories**: `ls .workflow/.design/run-xxx/style-consolidation/`
+```
+
+## 🎯 实施优先级
+
+### 🔴 高优先级（立即实施）
+
+1. **generate.md 添加验证逻辑**
+   - 防止参数不匹配问题再次发生
+   - 影响范围：所有手动调用 generate 命令的场景
+
+2. **ui-instantiate-prototypes.sh 添加验证**
+   - 脚本层面的最后防线
+   - 影响范围：所有原型生成操作
+
+3. **文档说明默认值和验证机制**
+   - 降低用户误用风险
+   - 影响范围：所有新用户和手动操作场景
+
+### 🟡 中优先级（短期改进）
+
+4. **统一参数命名为 --style-variants**
+   - 提高一致性，减少混淆
+   - 影响范围：需要更新多个命令文件
+
+5. **extract.md 统一使用 style-N 命名**
+   - 消除命名转换混淆
+   - 影响范围：需要更新 style-cards.json 格式
+
+### 🟢 低优先级（长期优化）
+
+6. **创建用户指南 README.md**
+   - 提供完整的参数使用指南
+   - 影响范围：文档层面，不影响功能
+
+## 📊 改进效果预测
+
+### 实施前
+
+```
+用户手动调用: /workflow:ui-design:generate --style-variants 4
+实际目录数: 3
+结果: ❌ 生成 login-style-4-layout-1.html 引用不存在的 CSS
+```
+
+### 实施后
+
+```
+用户手动调用: /workflow:ui-design:generate --style-variants 4
+实际目录数: 3
+
+验证检查:
+⚠️ Requested 4 style variants, but only 3 directories exist
+   Available: style-1, style-2, style-3
+   Auto-correcting to 3 style variants
+
+结果: ✅ 生成正确的 style-1, style-2, style-3 原型，避免错误
+```
+
+## 🔧 快速修复指南（针对当前问题）
+
+### 立即修复生成的错误文件
+
+```bash
+cd .workflow/.design/run-20251009-210559/prototypes
+
+# 删除错误的 style-4 文件
+rm -f *-style-4-*
+
+# 重新生成（使用自动检测）
+~/.claude/scripts/ui-instantiate-prototypes.sh . --session-id run-20251009-210559
+```
+
+### 预防未来错误
+
+```bash
+# ✅ 推荐：使用自动检测
+/workflow:ui-design:generate --base-path ".workflow/.design/run-xxx"
+
+# ⚠️ 如果必须手动指定，先验证
+jq '.variant_count' .workflow/.design/run-xxx/style-consolidation/consolidation-report.json
+# 输出: 3
+# 然后使用该数字
+/workflow:ui-design:generate --style-variants 3
+```
+
+## 📝 总结
+
+**核心问题**：
+- 参数命名不统一（`--variants` vs `--style-variants`）
+- 命名转换混淆（`variant-N` → `style-N`）
+- 验证缺失（不检查参数是否匹配实际目录）
+- 文档不清晰（默认值、自动检测机制说明不足）
+
+**关键改进**：
+1. ✅ 添加参数验证逻辑（防止不匹配）
+2. ✅ 统一参数命名（提高一致性）
+3. ✅ 完善文档说明（降低误用风险）
+4. ✅ 提供清晰的用户指南
+
+**预期效果**：
+- 🔒 杜绝参数不匹配问题
+- 📈 提高工作流鲁棒性
+- 🎓 降低用户学习成本
+- 🚀 提升整体用户体验