Release v4.4.0: UI Design Workflow V3 - Layout/Style Separation Architecture

## Breaking Changes

- **Command Renamed**: `extract` → `style-extract`
- **New Required Phase**: `layout-extract` now mandatory before `generate`
- **Workflow Changed**: Old flow (extract → consolidate → generate)
  → New flow (style-extract → consolidate → layout-extract → generate)

## Added

**New Command: layout-extract**
- Extract structural layout separate from visual style
- Agent-powered with ui-design-agent
- Dual-mode: imitate (high-fidelity) / explore (multiple variants)
- Device-aware: desktop, mobile, tablet, responsive
- MCP-integrated layout pattern research (explore mode)
- Output: layout-templates.json with DOM structure + CSS layout rules

**Enhanced Architecture**
- Layout/Style Separation: Clear responsibility boundaries
- Pure Assembler: generate command combines pre-extracted components
- Device-Aware Layouts: Optimized structures for different devices
- Token-Based CSS: var() placeholders for spacing/breakpoints

## Changed

**style-extract (Renamed from extract)**
- File renamed: extract.md → style-extract.md
- Scope clarified: Visual style only (colors, typography, spacing)
- No functionality change, all features preserved

**generate (Refactored to Pure Assembler)**
- Before: Agent designed layout + applied style
- After: Pure assembly - combines layout-templates.json + design-tokens.json
- No design logic: All decisions made in previous phases
- Simplified agent instructions: Focus on assembly only

**Workflow Commands Updated**
- imitate-auto: Added Phase 2.5 (layout extraction)
- explore-auto: Added Phase 2.5 (layout extraction)
- Both workflows now include layout-extract step

## Removed

- ❌ V2 Commands: generate-v2, explore-auto-v2 (merged into main commands)
- ❌ Old extract command (renamed to style-extract)
- ❌ ui-generate-preview-v2.sh (merged into ui-generate-preview.sh)

## Files Changed

- Renamed: extract.md → style-extract.md
- Added: layout-extract.md (370+ lines)
- Modified: generate.md, imitate-auto.md, explore-auto.md, consolidate.md
- Removed: 2 deprecated v2 command files
- Updated: CHANGELOG.md, README.md

## Benefits

- ✅ Single Responsibility: Each phase has one clear job
- ✅ Better Layout Variety: Explore mode generates structurally distinct layouts
- ✅ Reusability: Layout templates work with any style
- ✅ Clarity: All structural decisions visible in layout-templates.json
- ✅ Testability: Layout structure and visual style tested independently

🤖 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,71 +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
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for complete tool details
+
+## 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 (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first
-3. Detect analysis type and select template
-4. Build and execute command
-5. Return results
+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
 
-## Enhancement Integration
+## File Pattern Auto-Detection
 
-**When `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) to build the analysis command.
+Keywords trigger specific file patterns:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "component" → `@{src/components/**/*,**/*.component.*}`
+- "API" → `@{**/api/**/*,**/routes/**/*}`
+- "test" → `@{**/*.test.*,**/*.spec.*}`
+- "config" → `@{*.config.*,**/config/**/*}`
+- Generic → `@{src/**/*}`
 
+For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
 ## Command Template
 
-**Gemini/Qwen**:
 ```bash
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper -p "
-PURPOSE: [analysis goal]
-TASK: [specific task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+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]
 "
 ```
 
-**Codex**:
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [analysis goal]
-TASK: [specific task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [output format]
-RULES: [constraints]
-" --skip-git-repo-check -s danger-full-access
-
-# With image attachment (e.g., UI screenshots, diagrams)
-codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
-```
-
 ## Examples
 
+**Basic Analysis**:
 ```bash
-/cli:analyze "authentication patterns"              # Gemini (default)
-/cli:analyze --tool qwen "component architecture"   # Qwen architecture
-/cli:analyze --tool codex "performance bottlenecks" # Codex deep analysis
-/cli:analyze --enhance "fix auth issues"            # Enhanced prompt first
+/cli:analyze "authentication patterns"
+# Executes: Gemini analysis with auth file patterns
+# Returns: Pattern analysis, architecture insights, recommendations
 ```
 
-## File Pattern Logic
+**Architecture Analysis**:
+```bash
+/cli:analyze --tool qwen "component architecture"
+# Executes: Qwen with component file patterns
+# Returns: Architecture review, design patterns, improvement suggestions
+```
 
-Auto-detect file patterns from keywords:
-- "auth" → `@{**/*auth*}`
-- "component" → `@{src/components/**/*}`
-- "API" → `@{**/api/**/*}`
-- "test" → `@{**/*.test.*}`
-- Generic → `@{src/**/*}`
+**Performance Analysis**:
+```bash
+/cli:analyze --tool codex "performance bottlenecks"
+# Executes: Codex deep analysis with performance focus
+# Returns: Bottleneck identification, optimization recommendations
+```
 
-## Session Integration
+**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)
+```
 
-- **Active Session**: Save results to `.workflow/WFS-[id]/.chat/analysis-[timestamp].md`
-- **No Session**: Return results directly to user
+## Output Routing
 
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No active session OR one-off analysis**:
+  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
+- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
+
+## 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,84 +8,114 @@ examples:
   - /cli:chat --tool qwen --enhance "optimize React component"
   - /cli:chat --tool codex "review security vulnerabilities"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
+# CLI Chat Command (/cli:chat)
+
 ## Purpose
 
-Direct interaction with CLI tools for codebase analysis and Q&A.
+Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
 
+**Intent**: Ask questions, get explanations, understand codebase structure
 **Supported Tools**: codex, gemini (default), qwen
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for complete tool details
+
+## Core Behavior
+
+1. **Conversational Analysis**: Direct question-answer interaction about codebase
+2. **Read-Only**: This command ONLY provides information and analysis
+3. **No Code Modification**: Results are explanations and insights
+4. **Flexible Context**: Choose specific files or entire codebase
 
 ## Parameters
 
-- `<inquiry>` (Required): Question or analysis request
-- `--tool <codex|gemini|qwen>` (Optional): Select CLI tool (default: gemini)
-- `--enhance` (Optional): Enhance inquiry with `/enhance-prompt` first
-- `--all-files` (Optional): Include entire codebase in context
-- `--save-session` (Optional): Save interaction to workflow session
+- `<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
 
 ## Execution Flow
 
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first
-3. Assemble context (files + CLAUDE.md)
-4. Execute CLI tool
-5. Optional: Save to session
-
-## Enhancement Integration
-
-**When `--enhance` flag present**: Execute `/enhance-prompt "[inquiry]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) to build the chat command.
+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
 
 ## Context Assembly
 
-Context gathered from:
-1. **Project Guidelines**: `@{CLAUDE.md,**/*CLAUDE.md}` (always)
-2. **User-Explicit Files**: Files specified by user
-3. **All Files Flag**: `--all-files` includes entire codebase
+**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
+
+**Optional**:
+- User-explicit files from inquiry keywords
+- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
+
+For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
 
 ## Command Template
 
-**Gemini/Qwen**:
 ```bash
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper -p "
-PURPOSE: [inquiry goal]
-TASK: [specific question]
-CONTEXT: @{CLAUDE.md} @{target_files}
-EXPECTED: [response format]
-RULES: [constraints]
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+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
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper --all-files -p "..."
-```
-
-**Codex**:
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [inquiry goal]
-TASK: [specific question]
-CONTEXT: @{CLAUDE.md} @{target_files}
-EXPECTED: [response format]
-RULES: [constraints]
-" --skip-git-repo-check -s danger-full-access
-
-# With image attachment
-codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
 ```
 
 ## Examples
 
+**Basic Question**:
 ```bash
-/cli:chat "analyze the authentication flow"              # Gemini (default)
-/cli:chat --tool qwen "optimize React component"         # Qwen
-/cli:chat --tool codex "review security vulnerabilities" # Codex
-/cli:chat --enhance "fix the login"                      # Enhanced prompt
-/cli:chat --all-files "find all API endpoints"           # Full codebase
+/cli:chat "analyze the authentication flow"
+# Executes: Gemini analysis
+# Returns: Explanation of auth flow, components involved, data flow
 ```
 
-## Session Persistence
+**Architecture Question**:
+```bash
+/cli:chat --tool qwen "how does React component optimization work here"
+# Executes: Qwen architecture analysis
+# Returns: Component structure explanation, optimization patterns used
+```
 
-- **Active Session**: Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No Session**: Return results directly
+**Security Analysis**:
+```bash
+/cli:chat --tool codex "review security vulnerabilities"
+# Executes: Codex security analysis
+# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
+```
+
+**Enhanced Inquiry**:
+```bash
+/cli:chat --enhance "explain the login issue"
+# Step 1: Enhance to expand login context
+# Step 2: Analysis with expanded understanding
+# Returns: Detailed explanation of login flow and potential issues
+```
+
+**Broad Context**:
+```bash
+/cli:chat --all-files "find all API endpoints"
+# Executes: Analysis across entire codebase
+# Returns: List and explanation of API endpoints (NO code generation)
+```
+
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND query is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
+- **No active session OR unrelated query**:
+  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
+- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
+
+## 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

@@ -17,18 +17,23 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 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)
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for Codex details
 
 ## Core Workflow
 
 ```
-Task Input → Decompose into Subtasks → TodoWrite Tracking →
-For Each Subtask:
-  0. Stage existing changes (git add -A) if valid git repo
-  1. Execute with Codex
-  2. [Optional] Git verification
-  3. Mark complete in TodoWrite
-  4. Resume next subtask with `codex resume --last`
+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
 ```
 
@@ -41,17 +46,49 @@ For Each Subtask:
 
 ## Execution Flow
 
-### Phase 1: Input Processing & Decomposition
+### 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 & Decompose**:
+2. **Analyze Dependencies & Create Task Flow Diagram**:
    - Analyze task complexity and scope
-   - Break down into 3-8 subtasks
-   - Create TodoWrite tracker with all subtasks
+   - 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**:
@@ -59,8 +96,30 @@ For Each Subtask:
 - Clear, testable outcomes
 - Explicit dependencies
 - Focused file scope (1-5 files per subtask)
+- **Group coherence**: Subtasks in same group share context/files
 
-### Phase 2: Sequential Execution
+### 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
@@ -70,37 +129,61 @@ git add -A
 git status --short
 ```
 
-**For First Subtask**:
+**For First Subtask in Each Group** (New Session):
 ```bash
-# Initial execution (no resume needed)
+# Start new Codex session for independent task group
 codex -C [dir] --full-auto exec "
-PURPOSE: [task goal]
-TASK: [subtask 1 description]
+PURPOSE: [group goal]
+TASK: [subtask description - first in group]
 CONTEXT: @{relevant_files} @{CLAUDE.md}
 EXPECTED: [specific deliverables]
 RULES: [constraints]
-Subtask 1 of N: [subtask title]
+Group [X]: [group name] - Subtask 1 of N in this group
 " --skip-git-repo-check -s danger-full-access
 ```
 
-**For Subsequent Subtasks** (using resume --last):
+**For Related Subtasks in Same Group** (Resume Session):
 ```bash
 # Stage changes from previous subtask (if valid git repository)
 git add -A
 
-# Resume previous session for context continuity
+# Resume session ONLY for subtasks in same group
 codex exec "
-CONTINUE TO NEXT SUBTASK:
-Subtask N of M: [subtask title]
+CONTINUE IN SAME GROUP:
+Group [X]: [group name] - Subtask N of M
 
-PURPOSE: [continuation goal]
+PURPOSE: [continuation goal within group]
 TASK: [subtask N description]
-CONTEXT: Previous work completed, now focus on @{new_relevant_files}
+CONTEXT: Previous work in this group completed, now focus on @{new_relevant_files}
 EXPECTED: [specific deliverables]
-RULES: Build on previous subtask, maintain consistency
+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:
@@ -121,16 +204,26 @@ git ls-files --others --exclude-standard
 - No merge conflicts or errors
 - Code compiles/runs (if applicable)
 
-### Phase 4: TodoWrite Tracking
+### Phase 4: TodoWrite Tracking with Groups
 
-**Initial Setup**:
+**Initial Setup with Task Flow**:
 ```javascript
 TodoWrite({
   todos: [
-    { content: "Subtask 1: [description]", status: "in_progress", activeForm: "Executing subtask 1" },
-    { content: "Subtask 2: [description]", status: "pending", activeForm: "Executing subtask 2" },
-    { content: "Subtask 3: [description]", status: "pending", activeForm: "Executing subtask 3" },
-    // ... more subtasks
+    // 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" }
   ]
 })
@@ -140,8 +233,9 @@ TodoWrite({
 ```javascript
 TodoWrite({
   todos: [
-    { content: "Subtask 1: [description]", status: "completed", activeForm: "Executing subtask 1" },
-    { content: "Subtask 2: [description]", status: "in_progress", activeForm: "Executing subtask 2" },
+    { 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
   ]
 })
@@ -149,18 +243,36 @@ TodoWrite({
 
 ## Codex Resume Mechanism
 
-**Why `codex resume --last`?**
-- Maintains conversation context across subtasks
-- Codex remembers previous decisions and patterns
-- Reduces context repetition
-- Ensures consistency in implementation style
+**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 creates new Codex session
-2. After completion, session is saved
-3. Subsequent subtasks use `codex resume --last` to continue
-4. Each subtask builds on previous context
-5. Final subtask completes full task
+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
@@ -199,25 +311,47 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 
 **During Execution**:
 ```
-📋 Task Decomposition:
-  1. [Subtask 1 description]
-  2. [Subtask 2 description]
-  ...
+📊 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
 
-▶️  Executing Subtask 1/N: [title]
-  Codex session started...
+[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/file1.ts
-  A  src/file2.ts
+  M  src/models/user.ts
   ✅ Changes verified
 
-▶️  Executing Subtask 2/N: [title]
-  Resuming Codex session...
+▶️  [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
@@ -248,16 +382,30 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 
 ## Examples
 
-**Example 1: Simple Task**
+**Example 1: Simple Task with Groups**
 ```bash
 /cli:codex-execute "implement user authentication system"
 
-# Decomposes into:
-# 1. Create user model and database schema
-# 2. Implement JWT token generation
-# 3. Create authentication middleware
-# 4. Add login/logout endpoints
-# 5. Write tests for auth flow
+# 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**
@@ -280,13 +428,16 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 
 ## Best Practices
 
-1. **Subtask Granularity**: Keep subtasks small and focused
-2. **Clear Boundaries**: Each subtask should have well-defined input/output
-3. **Git Hygiene**: Use `--verify-git` for critical refactoring
-4. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications
-5. **Context Continuity**: Let `codex resume --last` maintain context
-6. **Recovery Points**: TodoWrite provides clear progress tracking
-7. **Image References**: Attach design files for UI tasks
+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
 
@@ -306,10 +457,45 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 }
 ```
 
+## 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: `.chat/codex-execute-[timestamp].md` (if workflow active)
-- Summary: `.summaries/[TASK-ID]-summary.md` (if task ID provided)
-- TodoWrite tracking embedded in session
+- 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
 
@@ -320,3 +506,8 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 **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,29 +9,33 @@ 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)
 
 ## Purpose
 
-Execute implementation tasks with YOLO permissions (auto-approves all confirmations).
+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
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for complete tool details
+**Key Feature**: Automatic context inference and file pattern detection
 
-## YOLO Permissions
+## Core Behavior
 
-Auto-approves: file pattern inference, execution, file modifications, summary generation
+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
 
-## Enhancement Integration
+## Core Concepts
 
-**When `--enhance` flag present** (Description Mode only): Execute `/enhance-prompt "[description]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) for execution.
+### YOLO Permissions
+Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**Note**: Task ID Mode uses task JSON directly (no enhancement).
+**⚠️ WARNING**: This command will make actual code changes without manual confirmation
 
-## Execution Modes
+### Execution Modes
 
 **1. Description Mode** (supports `--enhance`):
 - Input: Natural language description
@@ -41,71 +45,141 @@ Auto-approves: file pattern inference, execution, file modifications, summary ge
 - Input: Workflow task identifier (e.g., `IMPL-001`)
 - Process: Task JSON parsing → Scope analysis → Execute
 
-## Context Inference
+### Context Inference
 
-Auto-selects files based on:
-- **Keywords**: "auth" → `@{**/*auth*,**/*user*}`
-- **Technology**: "React" → `@{src/**/*.{jsx,tsx}}`
-- **Task Type**: "api" → `@{**/api/**/*,**/routes/**/*}`
-- **Always**: `@{CLAUDE.md,**/*CLAUDE.md}`
+Auto-selects files based on keywords and technology:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "React" → `@{src/**/*.{jsx,tsx}}`
+- "api" → `@{**/api/**/*,**/routes/**/*}`
+- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
 
-## Options
+For precise file targeting, use `rg` or MCP tools to discover files first.
 
-- `--debug`: Verbose logging
-- `--save-session`: Save execution to workflow session
+### Codex Session Continuity
+
+**Resume Pattern** for related tasks:
+```bash
+# First task - establish session
+codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access
+
+# Related task - continue session
+codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules.
+
+## Parameters
+
+- `--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 `.workflow/.active-*` marker
-- **Active**: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- **None**: Create new session
+- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- No session: Create new session or save to scratchpad
 
 **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
 
-**Gemini/Qwen** (with YOLO approval):
 ```bash
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper --approval-mode yolo -p "
+# Gemini/Qwen: MODE=write with --approval-mode yolo
+cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
 PURPOSE: [implementation goal]
-TASK: [specific task]
+TASK: [specific implementation]
 MODE: write
-CONTEXT: @{inferred_patterns} @{CLAUDE.md}
-EXPECTED: Implementation with file:line references
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
+CONTEXT: @{CLAUDE.md} [auto-detected files]
+EXPECTED: Working implementation with code changes
+RULES: [constraints] | Auto-approve all changes
 "
-```
 
-**Codex**:
-```bash
-codex -C [dir] --full-auto exec "
+# Codex: MODE=auto with danger-full-access
+codex -C . --full-auto exec "
 PURPOSE: [implementation goal]
-TASK: [specific task]
+TASK: [specific implementation]
 MODE: auto
-CONTEXT: @{inferred_patterns} @{CLAUDE.md}
-EXPECTED: Implementation with file:line references
-RULES: [constraints]
+CONTEXT: [auto-detected files]
+EXPECTED: Complete implementation with tests
 " --skip-git-repo-check -s danger-full-access
-
-# With image attachment
-codex -C [dir] -i design.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
 ```
 
 ## Examples
 
+**Basic Implementation** (⚠️ modifies code):
 ```bash
-/cli:execute "implement JWT authentication with middleware"  # Description mode
-/cli:execute --enhance "implement JWT authentication"        # Enhanced
-/cli:execute IMPL-001                                        # Task ID mode
-/cli:execute --tool codex "optimize database queries"        # Codex execution
+/cli:execute "implement JWT authentication with middleware"
+# Executes: Creates auth middleware, updates routes, modifies config
+# Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-## Auto-Generated Outputs
+**Enhanced Implementation** (⚠️ modifies code):
+```bash
+/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
+```
 
-- **Summary**: `.summaries/[TASK-ID]-summary.md`
-- **Session**: `.chat/execute-[timestamp].md`
+**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
+```
+
+**Codex Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --tool codex "optimize database queries"
+# Executes: Codex with full file access
+# Result: MODIFIED query code, new indexes, updated tests
+```
+
+**Qwen Code Generation** (⚠️ modifies code):
+```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
+```
+
+## Comparison with Analysis Commands
+
+| 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** |
 
 ## Notes
 
-**vs. `/cli:analyze`**: Execute performs implementation, analyze is read-only.
-
+- 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

@@ -45,7 +45,7 @@ count=$(echo "$modules" | wc -l)
 
 # 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
 #
@@ -60,7 +60,7 @@ After the bash script completes the initial analysis, the model takes control to
 2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files
 3. **Choose Strategy**:
    - Simple projects: Present execution plan with CLAUDE.md paths to user
-   - Complex projects: Delegate to memory-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
 
@@ -119,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 [tool] with 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

@@ -51,7 +51,7 @@ count=$(echo "$changed" | wc -l)
 
 # 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
 #
@@ -66,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
 
@@ -126,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 [tool] with 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/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

@@ -436,4 +436,65 @@ Upon completion, update `workflow-session.json`:
 - [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
 - [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
 - [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+- [ ] **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

@@ -143,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

.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
 
-## 6-Phase Execution
+## 7-Phase Execution (with Concept Verification)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -79,7 +80,22 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
 
-### Phase 5: TDD Task Generation
+### 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`
@@ -93,10 +109,10 @@ TEST_FOCUS: [Test scenarios]
 - IMPL tasks include test-fix-cycle configuration
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 
-### Phase 6: 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")
@@ -117,20 +133,26 @@ Structure:
 
 Plan:
 - Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
-  (includes TDD Task Chains section)
+  (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 (6 phases now)
+// Initialize (7 phases now with concept verification)
 [
   {content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
-  {content: "Execute context gathering", status: "pending", activeForm: "Executing context gathering"},
-  {content: "Execute test coverage analysis", status: "pending", activeForm: "Executing test coverage analysis"},
-  {content: "Execute TDD analysis", status: "pending", activeForm: "Executing TDD analysis"},
+  {content: "Execute 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"}
 ]

.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

@@ -238,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

@@ -305,27 +305,279 @@ For each feature, generate 3 tasks with ID format:
 
 ### Phase 4: Unified IMPL_PLAN.md Generation
 
-Generate single comprehensive IMPL_PLAN.md with:
+Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
 
 **Frontmatter**:
 ```yaml
 ---
 identifier: WFS-{session-id}
-workflow_type: "tdd"
+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
 ---
 ```
 
-**Structure**:
-1. **Summary**: Project overview
-2. **TDD Task Chains** (TDD-specific section):
-   - Visual representation of TEST → IMPL → REFACTOR chains
-   - Feature-by-feature breakdown with phase indicators
-3. **Task Breakdown**: Standard task listing
-4. **Implementation Strategy**: Execution approach
-5. **Success Criteria**: Acceptance conditions
+**Complete Structure** (8 Sections):
+
+```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
 

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

@@ -240,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/ui-design/batch-generate.md

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

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

@@ -0,0 +1,366 @@
+---
+name: capture
+description: Batch screenshot capture for UI design workflows using MCP or local fallback
+usage: /workflow:ui-design:capture --url-map "<map>" [--base-path <path>] [--session <id>]
+argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
+examples:
+  - /workflow:ui-design:capture --url-map "home:https://linear.app, pricing:https://linear.app/pricing"
+  - /workflow:ui-design:capture --session WFS-auth --url-map "dashboard:https://app.com/dash"
+  - /workflow:ui-design:capture --base-path ".workflow/.design/run-20250110" --url-map "hero:https://example.com#hero"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), ListMcpResourcesTool(*), mcp__chrome-devtools__*, mcp__playwright__*
+---
+
+# Batch Screenshot Capture (/workflow:ui-design:capture)
+
+## Overview
+Batch screenshot tool with MCP-first strategy and multi-tier fallback. Processes multiple URLs in parallel.
+
+**Strategy**: MCP → Playwright → Chrome → Manual
+**Output**: Flat structure `screenshots/{target}.png`
+
+## Phase 1: Initialize & Parse
+
+### Step 1: Determine Base Path
+```bash
+# Priority: --base-path > session > standalone
+bash(if [ -n "$BASE_PATH" ]; then
+  echo "$BASE_PATH"
+elif [ -n "$SESSION_ID" ]; then
+  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
+  echo ".workflow/WFS-$SESSION_ID/design-run-$(date +%Y%m%d-%H%M%S)"
+else
+  echo ".workflow/.design/run-$(date +%Y%m%d-%H%M%S)"
+fi)
+
+bash(mkdir -p $BASE_PATH/screenshots)
+```
+
+### Step 2: Parse URL Map
+```javascript
+// Input: "home:https://linear.app, pricing:https://linear.app/pricing"
+url_entries = []
+
+FOR pair IN split(params["--url-map"], ","):
+  parts = pair.split(":", 1)
+
+  IF len(parts) != 2:
+    ERROR: "Invalid format: {pair}. Expected: 'target:url'"
+    EXIT 1
+
+  target = parts[0].strip().lower().replace(" ", "-")
+  url = parts[1].strip()
+
+  // Validate target name
+  IF NOT regex_match(target, r"^[a-z0-9][a-z0-9_-]*$"):
+    ERROR: "Invalid target: {target}"
+    EXIT 1
+
+  // Add https:// if missing
+  IF NOT url.startswith("http"):
+    url = f"https://{url}"
+
+  url_entries.append({target, url})
+```
+
+**Output**: `base_path`, `url_entries[]`
+
+### Step 3: Initialize Todos
+```javascript
+TodoWrite({todos: [
+  {content: "Parse url-map", status: "completed", activeForm: "Parsing"},
+  {content: "Detect MCP tools", status: "in_progress", activeForm: "Detecting"},
+  {content: "Capture screenshots", status: "pending", activeForm: "Capturing"},
+  {content: "Verify results", status: "pending", activeForm: "Verifying"}
+]})
+```
+
+## Phase 2: Detect Screenshot Tools
+
+### Step 1: Check MCP Availability
+```javascript
+// List available MCP servers
+all_resources = ListMcpResourcesTool()
+available_servers = unique([r.server for r in all_resources])
+
+// Check Chrome DevTools MCP
+chrome_devtools = "chrome-devtools" IN available_servers
+chrome_screenshot = check_tool_exists("mcp__chrome-devtools__take_screenshot")
+
+// Check Playwright MCP
+playwright_mcp = "playwright" IN available_servers
+playwright_screenshot = check_tool_exists("mcp__playwright__screenshot")
+
+// Determine primary tool
+IF chrome_devtools AND chrome_screenshot:
+  tool = "chrome-devtools"
+ELSE IF playwright_mcp AND playwright_screenshot:
+  tool = "playwright"
+ELSE:
+  tool = null
+```
+
+**Output**: `tool` (chrome-devtools | playwright | null)
+
+### Step 2: Check Local Fallback
+```bash
+# Only if MCP unavailable
+bash(which playwright 2>/dev/null || echo "")
+bash(which google-chrome || which chrome || which chromium 2>/dev/null || echo "")
+```
+
+**Output**: `local_tools[]`
+
+## Phase 3: Capture Screenshots
+
+### Screenshot Format Options
+
+**PNG Format** (default, lossless):
+- **Pros**: Lossless quality, best for detailed UI screenshots
+- **Cons**: Larger file sizes (typically 200-500 KB per screenshot)
+- **Parameters**: `format: "png"` (no quality parameter)
+- **Use case**: High-fidelity UI replication, design system extraction
+
+**WebP Format** (optional, lossy/lossless):
+- **Pros**: Smaller file sizes with good quality (50-70% smaller than PNG)
+- **Cons**: Requires quality parameter, slight quality loss at high compression
+- **Parameters**: `format: "webp", quality: 90` (80-100 recommended)
+- **Use case**: Batch captures, network-constrained environments
+
+**JPEG Format** (optional, lossy):
+- **Pros**: Smallest file sizes
+- **Cons**: Lossy compression, not recommended for UI screenshots
+- **Parameters**: `format: "jpeg", quality: 90`
+- **Use case**: Photo-heavy pages, not recommended for UI design
+
+### Step 1: MCP Capture (If Available)
+```javascript
+IF tool == "chrome-devtools":
+  // Get or create page
+  pages = mcp__chrome-devtools__list_pages()
+
+  IF pages.length == 0:
+    mcp__chrome-devtools__new_page({url: url_entries[0].url})
+    page_idx = 0
+  ELSE:
+    page_idx = 0
+
+  mcp__chrome-devtools__select_page({pageIdx: page_idx})
+
+  // Capture each URL
+  FOR entry IN url_entries:
+    mcp__chrome-devtools__navigate_page({url: entry.url, timeout: 30000})
+    bash(sleep 2)
+
+    // PNG format doesn't support quality parameter
+    // Use PNG for lossless quality (larger files)
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: true,
+      format: "png",
+      filePath: f"{base_path}/screenshots/{entry.target}.png"
+    })
+
+    // Alternative: Use WebP with quality for smaller files
+    // mcp__chrome-devtools__take_screenshot({
+    //   fullPage: true,
+    //   format: "webp",
+    //   quality: 90,
+    //   filePath: f"{base_path}/screenshots/{entry.target}.webp"
+    // })
+
+ELSE IF tool == "playwright":
+  FOR entry IN url_entries:
+    mcp__playwright__screenshot({
+      url: entry.url,
+      output_path: f"{base_path}/screenshots/{entry.target}.png",
+      full_page: true,
+      timeout: 30000
+    })
+```
+
+### Step 2: Local Fallback (If MCP Failed)
+```bash
+# Try Playwright CLI
+bash(playwright screenshot "$url" "$output_file" --full-page --timeout 30000)
+
+# Try Chrome headless
+bash($chrome --headless --screenshot="$output_file" --window-size=1920,1080 "$url")
+```
+
+### Step 3: Manual Mode (If All Failed)
+```
+⚠️ Manual Screenshot Required
+
+Failed URLs:
+  home: https://linear.app
+  Save to: .workflow/.design/run-20250110/screenshots/home.png
+
+Steps:
+  1. Visit URL in browser
+  2. Take full-page screenshot
+  3. Save to path above
+  4. Type 'ready' to continue
+
+Options: ready | skip | abort
+```
+
+## Phase 4: Verification
+
+### Step 1: Scan Captured Files
+```bash
+bash(ls -1 $base_path/screenshots/*.{png,jpg,jpeg,webp} 2>/dev/null)
+bash(du -h $base_path/screenshots/*.png 2>/dev/null)
+```
+
+### Step 2: Generate Metadata
+```javascript
+captured_files = Glob(f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}")
+captured_targets = [basename_no_ext(f) for f in captured_files]
+
+metadata = {
+  "timestamp": current_timestamp(),
+  "total_requested": len(url_entries),
+  "total_captured": len(captured_targets),
+  "screenshots": []
+}
+
+FOR entry IN url_entries:
+  is_captured = entry.target IN captured_targets
+
+  metadata.screenshots.append({
+    "target": entry.target,
+    "url": entry.url,
+    "captured": is_captured,
+    "path": f"{base_path}/screenshots/{entry.target}.png" IF is_captured ELSE null,
+    "size_kb": file_size_kb IF is_captured ELSE null
+  })
+
+Write(f"{base_path}/screenshots/capture-metadata.json", JSON.stringify(metadata))
+```
+
+**Output**: `capture-metadata.json`
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Parse url-map", status: "completed", activeForm: "Parsing"},
+  {content: "Detect MCP tools", status: "completed", activeForm: "Detecting"},
+  {content: "Capture screenshots", status: "completed", activeForm: "Capturing"},
+  {content: "Verify results", status: "completed", activeForm: "Verifying"}
+]})
+```
+
+### Output Message
+```
+✅ Batch screenshot capture complete!
+
+Summary:
+- Requested: {total_requested}
+- Captured: {total_captured}
+- Success rate: {success_rate}%
+- Method: {tool || "Local fallback"}
+
+Output:
+{base_path}/screenshots/
+├── home.png (245.3 KB)
+├── pricing.png (198.7 KB)
+└── capture-metadata.json
+
+Next: /workflow:ui-design:extract --images "screenshots/*.png"
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create screenshot directory
+bash(mkdir -p $BASE_PATH/screenshots)
+```
+
+### Tool Detection
+```bash
+# Check MCP
+all_resources = ListMcpResourcesTool()
+
+# Check local tools
+bash(which playwright 2>/dev/null)
+bash(which google-chrome 2>/dev/null)
+```
+
+### Verification
+```bash
+# List captures
+bash(ls -1 $base_path/screenshots/*.png 2>/dev/null)
+
+# File sizes
+bash(du -h $base_path/screenshots/*.png)
+```
+
+## Output Structure
+
+```
+{base_path}/
+└── screenshots/
+    ├── home.png
+    ├── pricing.png
+    ├── about.png
+    └── capture-metadata.json
+```
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: Invalid url-map format
+→ Use: "target:url, target2:url2"
+
+ERROR: png screenshots do not support 'quality'
+→ PNG format is lossless, no quality parameter needed
+→ Remove quality parameter OR switch to webp/jpeg format
+
+ERROR: MCP unavailable
+→ Using local fallback
+
+ERROR: All tools failed
+→ Manual mode activated
+```
+
+### Format-Specific Errors
+```
+❌ Wrong: format: "png", quality: 90
+✅ Right: format: "png"
+
+✅ Or use: format: "webp", quality: 90
+✅ Or use: format: "jpeg", quality: 90
+```
+
+### Recovery
+- **Partial success**: Keep successful captures
+- **Retry**: Re-run with failed targets only
+- **Manual**: Follow interactive guidance
+
+## Quality Checklist
+
+- [ ] All requested URLs processed
+- [ ] File sizes > 1KB (valid images)
+- [ ] Metadata JSON generated
+- [ ] No missing targets (or documented)
+
+## Key Features
+
+- **MCP-first**: Prioritize managed tools
+- **Multi-tier fallback**: 4 layers (MCP → Local → Manual)
+- **Batch processing**: Parallel capture
+- **Error tolerance**: Partial failures handled
+- **Structured output**: Flat, predictable
+
+## Integration
+
+**Input**: `--url-map` (multiple target:url pairs)
+**Output**: `screenshots/*.png` + `capture-metadata.json`
+**Called by**: `/workflow:ui-design:imitate-auto`, `/workflow:ui-design:explore-auto`
+**Next**: `/workflow:ui-design:extract` or `/workflow:ui-design:explore-layers`

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

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

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

@@ -0,0 +1,495 @@
+---
+name: explore-auto
+description: Exploratory UI design workflow with style-centric batch generation
+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" --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 [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 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
+6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
+7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+8. Phase 5 (batch-plan, optional) → Reports completion
+
+**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)
+- `--device-type "desktop|mobile|tablet|responsive|auto"`: Device type for layout optimization (default: `auto` - intelligent detection)
+  - **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+  - **Mobile**: 375×812px - Touch-friendly, compact layouts
+  - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+  - **Responsive**: 1920×1080px base with mobile-first breakpoints
+- `--session <id>`: Workflow session ID (standalone mode if omitted)
+- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
+- `--prompt "<description>"`: Design style and target description
+- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
+- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
+- `--batch-plan`: Auto-generate implementation tasks after design-update
+
+**Legacy Parameters** (maintained for backward compatibility):
+- `--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)
+  - 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 0a-2: Device Type Inference
+```bash
+# Device type inference
+device_type = "auto"
+
+# Step 1: Explicit parameter (highest priority)
+IF --device-type AND --device-type != "auto":
+    device_type = --device-type
+    device_source = "explicit"
+ELSE:
+    # Step 2: Prompt analysis
+    IF --prompt:
+        device_keywords = {
+            "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
+            "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
+            "tablet": ["tablet", "ipad", "medium screen"],
+            "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
+        }
+        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        IF detected_device:
+            device_type = detected_device
+            device_source = "prompt_inference"
+
+    # Step 3: Target type inference
+    IF device_type == "auto":
+        # Components are typically desktop-first, pages can vary
+        device_type = target_type == "component" ? "desktop" : "responsive"
+        device_source = "target_type_inference"
+
+STORE: device_type, device_source
+```
+
+**Device Type Presets**:
+- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+- **Mobile**: 375×812px - Touch-friendly, compact layouts
+- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+- **Responsive**: 1920×1080px base with mobile-first breakpoints
+
+**Detection Keywords**:
+- Prompt contains "mobile", "phone", "smartphone" → mobile
+- Prompt contains "tablet", "ipad" → tablet
+- Prompt contains "desktop", "web", "laptop" → desktop
+- Prompt contains "responsive", "adaptive" → responsive
+- Otherwise: Inferred from target type (components→desktop, pages→responsive)
+
+### 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",
+  "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}",
+                  "device_type": "${device_type}", "device_source": "${device_source}" },
+  "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, device_type, device_source):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION (Style-Centric)"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Device: {device_type} | Source: {device_source}"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Performance: {style_variants} agent calls"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Modification Options:"
+  "  • 'continue/yes/ok' - Proceed with current configuration"
+  "  • 'targets: a,b,c' - Replace target list"
+  "  • 'skip: x,y' - Remove specific targets"
+  "  • 'add: z' - Add new targets"
+  "  • 'type: page|component' - Change target type"
+  "  • 'device: desktop|mobile|tablet|responsive' - Change device type"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+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()
+  "device: ..." → device_type = extract_device()
+  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:style-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--mode explore --variants {style_variants}"
+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 2.5 (auto-continue)
+```
+
+### Phase 2.5: Layout Extraction
+```bash
+targets_string = ",".join(inferred_target_list)
+command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--targets \"{targets_string}\" " +
+          "--mode explore --variants {layout_variants} " +
+          "--device-type \"{device_type}\""
+
+REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
+REPORT: "   → Targets: {targets_string}"
+REPORT: "   → Layout variants: {layout_variants}"
+REPORT: "   → Device: {device_type}"
+
+SlashCommand(command)
+
+# Output: layout-templates.json with {targets × layout_variants} layout structures
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
+```
+
+### Phase 3: UI Assembly
+```bash
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
+
+total = style_variants × layout_variants × len(inferred_target_list)
+
+REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "   → Pure assembly: Combining layout templates + design tokens"
+REPORT: "   → Device: {device_type} (from layout templates)"
+REPORT: "   → Assembly tasks: {total} combinations"
+
+SlashCommand(command)
+
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
+# Output:
+# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
+# - {target}-style-{s}-layout-{l}.css
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
+```
+
+### 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 layout extraction", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI assembly", "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 --prompt "Modern blog: home, article, author"
+# Result: 27 prototypes (3×3×3) - responsive layouts (default)
+```
+
+### 2. Mobile-First Design
+```bash
+/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
+# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
+```
+
+### 3. Desktop Application
+```bash
+/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
+# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
+```
+
+### 4. Tablet Interface
+```bash
+/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
+# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
+```
+
+### 5. Custom Matrix with Session
+```bash
+/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
+# Result: 2×2×N prototypes - device type inferred from session
+```
+
+### 6. Component Mode (Desktop)
+```bash
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2) - desktop components
+```
+
+### 7. Intelligent Parsing + Batch Planning
+```bash
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
+```
+
+### 8. Large Scale Responsive
+```bash
+/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
+# Result: 36 prototypes (3×3×4) - responsive layouts
+```
+
+## 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} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
+
+Phase 1: {s} style variants with design_attributes (style-extract)
+Phase 2: {s} design systems with tokens.css (consolidate)
+Phase 2.5: {n×l} layout templates (layout-extract explore mode)
+  - Device: {device_type} layouts
+  - {n} targets × {l} layout variants = {n×l} structural templates
+Phase 3: UI Assembly (generate)
+  - Pure assembly: layout templates + design tokens
+  - {s}×{l}×{n} = {total} final prototypes
+Phase 4: Brainstorming artifacts updated
+[Phase 5: {n} implementation tasks created]  # if --batch-plan
+
+Assembly Process:
+✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
+✅ Layout Extraction: {n×l} reusable structural templates
+✅ Pure Assembly: No design decisions in generate phase
+✅ Device-Optimized: Layouts designed for {device_type}
+
+Design Quality:
+✅ Token-Driven Styling: 100% var() usage
+✅ Structural Variety: {l} distinct layouts per target
+✅ Style Variety: {s} independent design systems
+✅ Device-Optimized: Layouts designed for {device_type}
+
+📂 {base_path}/
+  ├── style-extraction/       ({s} style cards + design-space-analysis.json)
+  ├── style-consolidation/    ({s} design systems with tokens.css)
+  ├── layout-extraction/      ({n×l} layout templates + layout-space-analysis.json)
+  ├── prototypes/             ({total} assembled prototypes)
+  └── .run-metadata.json      (includes device type)
+
+🌐 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
+  - Optimized for {device_type} viewing
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+```
+

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

@@ -0,0 +1,594 @@
+---
+name: explore-layers
+description: Interactive deep UI capture with depth-controlled layer exploration
+usage: /workflow:ui-design:explore-layers --url <url> --depth <1-5> [--session <id>] [--base-path <path>]
+argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
+examples:
+  - /workflow:ui-design:explore-layers --url "https://app.linear.app" --depth 3
+  - /workflow:ui-design:explore-layers --url "https://notion.so" --depth 2 --session WFS-notion-ui
+  - /workflow:ui-design:explore-layers --url "https://app.com/dashboard" --depth 4
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), mcp__chrome-devtools__*
+---
+
+# Interactive Layer Exploration (/workflow:ui-design:explore-layers)
+
+## Overview
+Single-URL depth-controlled interactive capture. Progressively explores UI layers from pages to Shadow DOM.
+
+**Depth Levels**:
+- `1` = Page (full-page screenshot)
+- `2` = Elements (key components)
+- `3` = Interactions (modals, dropdowns)
+- `4` = Embedded (iframes, widgets)
+- `5` = Shadow DOM (web components)
+
+**Requirements**: Chrome DevTools MCP
+
+## Phase 1: Setup & Validation
+
+### Step 1: Parse Parameters
+```javascript
+url = params["--url"]
+depth = int(params["--depth"])
+
+// Validate URL
+IF NOT url.startswith("http"):
+  url = f"https://{url}"
+
+// Validate depth
+IF depth NOT IN [1, 2, 3, 4, 5]:
+  ERROR: "Invalid depth: {depth}. Use 1-5"
+  EXIT 1
+```
+
+### Step 2: Determine Base Path
+```bash
+bash(if [ -n "$BASE_PATH" ]; then
+  echo "$BASE_PATH"
+elif [ -n "$SESSION_ID" ]; then
+  find .workflow/WFS-$SESSION_ID/design-* -type d | head -1 || \
+  echo ".workflow/WFS-$SESSION_ID/design-layers-$(date +%Y%m%d-%H%M%S)"
+else
+  echo ".workflow/.design/layers-$(date +%Y%m%d-%H%M%S)"
+fi)
+
+# Create depth directories
+bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
+```
+
+**Output**: `url`, `depth`, `base_path`
+
+### Step 3: Validate MCP Availability
+```javascript
+all_resources = ListMcpResourcesTool()
+chrome_devtools = "chrome-devtools" IN [r.server for r in all_resources]
+
+IF NOT chrome_devtools:
+  ERROR: "explore-layers requires Chrome DevTools MCP"
+  ERROR: "Install: npm i -g @modelcontextprotocol/server-chrome-devtools"
+  EXIT 1
+```
+
+### Step 4: Initialize Todos
+```javascript
+todos = [
+  {content: "Setup and validation", status: "completed", activeForm: "Setting up"}
+]
+
+FOR level IN range(1, depth + 1):
+  todos.append({
+    content: f"Depth {level}: {DEPTH_NAMES[level]}",
+    status: "pending",
+    activeForm: f"Capturing depth {level}"
+  })
+
+todos.append({content: "Generate layer map", status: "pending", activeForm: "Mapping"})
+
+TodoWrite({todos})
+```
+
+## Phase 2: Navigate & Load Page
+
+### Step 1: Get or Create Browser Page
+```javascript
+pages = mcp__chrome-devtools__list_pages()
+
+IF pages.length == 0:
+  mcp__chrome-devtools__new_page({url: url, timeout: 30000})
+  page_idx = 0
+ELSE:
+  page_idx = 0
+  mcp__chrome-devtools__select_page({pageIdx: page_idx})
+  mcp__chrome-devtools__navigate_page({url: url, timeout: 30000})
+
+bash(sleep 3)  // Wait for page load
+```
+
+**Output**: `page_idx`
+
+## Phase 3: Depth 1 - Page Level
+
+### Step 1: Capture Full Page
+```javascript
+TodoWrite(mark_in_progress: "Depth 1: Page")
+
+output_file = f"{base_path}/screenshots/depth-1/full-page.png"
+
+mcp__chrome-devtools__take_screenshot({
+  fullPage: true,
+  format: "png",
+  quality: 90,
+  filePath: output_file
+})
+
+layer_map = {
+  "url": url,
+  "depth": depth,
+  "layers": {
+    "depth-1": {
+      "type": "page",
+      "captures": [{
+        "name": "full-page",
+        "path": output_file,
+        "size_kb": file_size_kb(output_file)
+      }]
+    }
+  }
+}
+
+TodoWrite(mark_completed: "Depth 1: Page")
+```
+
+**Output**: `depth-1/full-page.png`
+
+## Phase 4: Depth 2 - Element Level (If depth >= 2)
+
+### Step 1: Analyze Page Structure
+```javascript
+IF depth < 2: SKIP
+
+TodoWrite(mark_in_progress: "Depth 2: Elements")
+
+snapshot = mcp__chrome-devtools__take_snapshot()
+
+// Filter key elements
+key_types = ["nav", "header", "footer", "aside", "button", "form", "article"]
+key_elements = [
+  el for el in snapshot.interactiveElements
+  if el.type IN key_types OR el.role IN ["navigation", "banner", "main"]
+][:10]  // Limit to top 10
+```
+
+### Step 2: Capture Element Screenshots
+```javascript
+depth_2_captures = []
+
+FOR idx, element IN enumerate(key_elements):
+  element_name = sanitize(element.text[:20] or element.type) or f"element-{idx}"
+  output_file = f"{base_path}/screenshots/depth-2/{element_name}.png"
+
+  TRY:
+    mcp__chrome-devtools__take_screenshot({
+      uid: element.uid,
+      format: "png",
+      quality: 85,
+      filePath: output_file
+    })
+
+    depth_2_captures.append({
+      "name": element_name,
+      "type": element.type,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+  CATCH error:
+    REPORT: f"Skip {element_name}: {error}"
+
+layer_map.layers["depth-2"] = {
+  "type": "elements",
+  "captures": depth_2_captures
+}
+
+TodoWrite(mark_completed: "Depth 2: Elements")
+```
+
+**Output**: `depth-2/{element}.png` × N
+
+## Phase 5: Depth 3 - Interaction Level (If depth >= 3)
+
+### Step 1: Analyze Interactive Triggers
+```javascript
+IF depth < 3: SKIP
+
+TodoWrite(mark_in_progress: "Depth 3: Interactions")
+
+// Detect structure
+structure = mcp__chrome-devtools__evaluate_script({
+  function: `() => ({
+    modals: document.querySelectorAll('[role="dialog"], .modal').length,
+    dropdowns: document.querySelectorAll('[role="menu"], .dropdown').length,
+    tooltips: document.querySelectorAll('[role="tooltip"], [title]').length
+  })`
+})
+
+// Identify triggers
+triggers = []
+FOR element IN snapshot.interactiveElements:
+  IF element.attributes CONTAINS ("data-toggle", "aria-haspopup"):
+    triggers.append({
+      uid: element.uid,
+      type: "modal" IF "modal" IN element.classes ELSE "dropdown",
+      trigger: "click",
+      text: element.text
+    })
+  ELSE IF element.attributes CONTAINS ("title", "data-tooltip"):
+    triggers.append({
+      uid: element.uid,
+      type: "tooltip",
+      trigger: "hover",
+      text: element.text
+    })
+
+triggers = triggers[:10]  // Limit
+```
+
+### Step 2: Trigger Interactions & Capture
+```javascript
+depth_3_captures = []
+
+FOR idx, trigger IN enumerate(triggers):
+  layer_name = f"{trigger.type}-{sanitize(trigger.text[:15]) or idx}"
+  output_file = f"{base_path}/screenshots/depth-3/{layer_name}.png"
+
+  TRY:
+    // Trigger interaction
+    IF trigger.trigger == "click":
+      mcp__chrome-devtools__click({uid: trigger.uid})
+    ELSE:
+      mcp__chrome-devtools__hover({uid: trigger.uid})
+
+    bash(sleep 1)
+
+    // Capture
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: false,  // Viewport only
+      format: "png",
+      quality: 90,
+      filePath: output_file
+    })
+
+    depth_3_captures.append({
+      "name": layer_name,
+      "type": trigger.type,
+      "trigger_method": trigger.trigger,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+
+    // Dismiss (ESC key)
+    mcp__chrome-devtools__evaluate_script({
+      function: `() => {
+        document.dispatchEvent(new KeyboardEvent('keydown', {key: 'Escape'}));
+      }`
+    })
+    bash(sleep 0.5)
+
+  CATCH error:
+    REPORT: f"Skip {layer_name}: {error}"
+
+layer_map.layers["depth-3"] = {
+  "type": "interactions",
+  "triggers": structure,
+  "captures": depth_3_captures
+}
+
+TodoWrite(mark_completed: "Depth 3: Interactions")
+```
+
+**Output**: `depth-3/{interaction}.png` × N
+
+## Phase 6: Depth 4 - Embedded Level (If depth >= 4)
+
+### Step 1: Detect Iframes
+```javascript
+IF depth < 4: SKIP
+
+TodoWrite(mark_in_progress: "Depth 4: Embedded")
+
+iframes = mcp__chrome-devtools__evaluate_script({
+  function: `() => {
+    return Array.from(document.querySelectorAll('iframe')).map(iframe => ({
+      src: iframe.src,
+      id: iframe.id || 'iframe',
+      title: iframe.title || 'untitled'
+    })).filter(i => i.src && i.src.startsWith('http'));
+  }`
+})
+```
+
+### Step 2: Capture Iframe Content
+```javascript
+depth_4_captures = []
+
+FOR idx, iframe IN enumerate(iframes):
+  iframe_name = f"iframe-{sanitize(iframe.title or iframe.id)}-{idx}"
+  output_file = f"{base_path}/screenshots/depth-4/{iframe_name}.png"
+
+  TRY:
+    // Navigate to iframe URL in new tab
+    mcp__chrome-devtools__new_page({url: iframe.src, timeout: 30000})
+    bash(sleep 2)
+
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: true,
+      format: "png",
+      quality: 90,
+      filePath: output_file
+    })
+
+    depth_4_captures.append({
+      "name": iframe_name,
+      "url": iframe.src,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+
+    // Close iframe tab
+    current_pages = mcp__chrome-devtools__list_pages()
+    mcp__chrome-devtools__close_page({pageIdx: current_pages.length - 1})
+
+  CATCH error:
+    REPORT: f"Skip {iframe_name}: {error}"
+
+layer_map.layers["depth-4"] = {
+  "type": "embedded",
+  "captures": depth_4_captures
+}
+
+TodoWrite(mark_completed: "Depth 4: Embedded")
+```
+
+**Output**: `depth-4/iframe-*.png` × N
+
+## Phase 7: Depth 5 - Shadow DOM (If depth = 5)
+
+### Step 1: Detect Shadow Roots
+```javascript
+IF depth < 5: SKIP
+
+TodoWrite(mark_in_progress: "Depth 5: Shadow DOM")
+
+shadow_elements = mcp__chrome-devtools__evaluate_script({
+  function: `() => {
+    const elements = Array.from(document.querySelectorAll('*'));
+    return elements
+      .filter(el => el.shadowRoot)
+      .map((el, idx) => ({
+        tag: el.tagName.toLowerCase(),
+        id: el.id || \`shadow-\${idx}\`,
+        innerHTML: el.shadowRoot.innerHTML.substring(0, 100)
+      }));
+  }`
+})
+```
+
+### Step 2: Capture Shadow DOM Components
+```javascript
+depth_5_captures = []
+
+FOR idx, shadow IN enumerate(shadow_elements):
+  shadow_name = f"shadow-{sanitize(shadow.id)}"
+  output_file = f"{base_path}/screenshots/depth-5/{shadow_name}.png"
+
+  TRY:
+    // Inject highlight script
+    mcp__chrome-devtools__evaluate_script({
+      function: `() => {
+        const el = document.querySelector('${shadow.tag}${shadow.id ? "#" + shadow.id : ""}');
+        if (el) {
+          el.scrollIntoView({behavior: 'smooth', block: 'center'});
+          el.style.outline = '3px solid red';
+        }
+      }`
+    })
+
+    bash(sleep 0.5)
+
+    // Full-page screenshot (component highlighted)
+    mcp__chrome-devtools__take_screenshot({
+      fullPage: false,
+      format: "png",
+      quality: 90,
+      filePath: output_file
+    })
+
+    depth_5_captures.append({
+      "name": shadow_name,
+      "tag": shadow.tag,
+      "path": output_file,
+      "size_kb": file_size_kb(output_file)
+    })
+
+  CATCH error:
+    REPORT: f"Skip {shadow_name}: {error}"
+
+layer_map.layers["depth-5"] = {
+  "type": "shadow-dom",
+  "captures": depth_5_captures
+}
+
+TodoWrite(mark_completed: "Depth 5: Shadow DOM")
+```
+
+**Output**: `depth-5/shadow-*.png` × N
+
+## Phase 8: Generate Layer Map
+
+### Step 1: Compile Metadata
+```javascript
+TodoWrite(mark_in_progress: "Generate layer map")
+
+// Calculate totals
+total_captures = sum(len(layer.captures) for layer in layer_map.layers.values())
+total_size_kb = sum(
+  sum(c.size_kb for c in layer.captures)
+  for layer in layer_map.layers.values()
+)
+
+layer_map["summary"] = {
+  "timestamp": current_timestamp(),
+  "total_depth": depth,
+  "total_captures": total_captures,
+  "total_size_kb": total_size_kb
+}
+
+Write(f"{base_path}/screenshots/layer-map.json", JSON.stringify(layer_map, indent=2))
+
+TodoWrite(mark_completed: "Generate layer map")
+```
+
+**Output**: `layer-map.json`
+
+## Completion
+
+### Todo Update
+```javascript
+all_todos_completed = true
+TodoWrite({todos: all_completed_todos})
+```
+
+### Output Message
+```
+✅ Interactive layer exploration complete!
+
+Configuration:
+- URL: {url}
+- Max depth: {depth}
+- Layers explored: {len(layer_map.layers)}
+
+Capture Summary:
+  Depth 1 (Page):        {depth_1_count} screenshot(s)
+  Depth 2 (Elements):    {depth_2_count} screenshot(s)
+  Depth 3 (Interactions): {depth_3_count} screenshot(s)
+  Depth 4 (Embedded):    {depth_4_count} screenshot(s)
+  Depth 5 (Shadow DOM):  {depth_5_count} screenshot(s)
+
+Total: {total_captures} captures ({total_size_kb:.1f} KB)
+
+Output Structure:
+{base_path}/screenshots/
+├── depth-1/
+│   └── full-page.png
+├── depth-2/
+│   ├── navbar.png
+│   └── footer.png
+├── depth-3/
+│   ├── modal-login.png
+│   └── dropdown-menu.png
+├── depth-4/
+│   └── iframe-analytics.png
+├── depth-5/
+│   └── shadow-button.png
+└── layer-map.json
+
+Next: /workflow:ui-design:extract --images "screenshots/**/*.png"
+```
+
+## Simple Bash Commands
+
+### Directory Setup
+```bash
+# Create depth directories
+bash(for i in $(seq 1 $depth); do mkdir -p $BASE_PATH/screenshots/depth-$i; done)
+```
+
+### Validation
+```bash
+# Check MCP
+all_resources = ListMcpResourcesTool()
+
+# Count captures per depth
+bash(ls $base_path/screenshots/depth-{1..5}/*.png 2>/dev/null | wc -l)
+```
+
+### File Operations
+```bash
+# List all captures
+bash(find $base_path/screenshots -name "*.png" -type f)
+
+# Total size
+bash(du -sh $base_path/screenshots)
+```
+
+## Output Structure
+
+```
+{base_path}/screenshots/
+├── depth-1/
+│   └── full-page.png
+├── depth-2/
+│   ├── {element}.png
+│   └── ...
+├── depth-3/
+│   ├── {interaction}.png
+│   └── ...
+├── depth-4/
+│   ├── iframe-*.png
+│   └── ...
+├── depth-5/
+│   ├── shadow-*.png
+│   └── ...
+└── layer-map.json
+```
+
+## Depth Level Details
+
+| Depth | Name | Captures | Time | Use Case |
+|-------|------|----------|------|----------|
+| 1 | Page | Full page | 30s | Quick preview |
+| 2 | Elements | Key components | 1-2min | Component library |
+| 3 | Interactions | Modals, dropdowns | 2-4min | UI flows |
+| 4 | Embedded | Iframes | 3-6min | Complete context |
+| 5 | Shadow DOM | Web components | 4-8min | Full coverage |
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: Chrome DevTools MCP required
+→ Install: npm i -g @modelcontextprotocol/server-chrome-devtools
+
+ERROR: Invalid depth
+→ Use: 1-5
+
+ERROR: Interaction trigger failed
+→ Some modals may be skipped, check layer-map.json
+```
+
+### Recovery
+- **Partial success**: Lower depth captures preserved
+- **Trigger failures**: Interaction layer may be incomplete
+- **Iframe restrictions**: Cross-origin iframes skipped
+
+## Quality Checklist
+
+- [ ] All depths up to specified level captured
+- [ ] layer-map.json generated with metadata
+- [ ] File sizes valid (> 500 bytes)
+- [ ] Interaction triggers executed
+- [ ] Shadow DOM elements highlighted
+
+## Key Features
+
+- **Depth-controlled**: Progressive capture 1-5 levels
+- **Interactive triggers**: Click/hover for hidden layers
+- **Iframe support**: Embedded content captured
+- **Shadow DOM**: Web component internals
+- **Structured output**: Organized by depth
+
+## Integration
+
+**Input**: Single URL + depth level (1-5)
+**Output**: Hierarchical screenshots + layer-map.json
+**Complements**: `/workflow:ui-design:capture` (multi-URL batch)
+**Next**: `/workflow:ui-design:extract` for design analysis

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

@@ -0,0 +1,309 @@
+---
+name: generate
+description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
+usage: /workflow:ui-design:generate [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+examples:
+  - /workflow:ui-design:generate --session WFS-auth
+  - /workflow:ui-design:generate --style-variants 2 --layout-variants 2
+  - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
+---
+
+# Generate UI Prototypes (/workflow:ui-design:generate)
+
+## Overview
+Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
+
+**Strategy**: Pure Assembly
+- **Input**: `layout-templates.json` + `design-tokens.json`
+- **Process**: Combine structure (DOM) with style (tokens)
+- **Output**: Complete HTML/CSS prototypes
+- **No Design Logic**: All layout and style decisions already made
+
+**Prerequisite Commands**:
+- `/workflow:ui-design:style-extract` → Style tokens
+- `/workflow:ui-design:consolidate` → Final design tokens
+- `/workflow:ui-design:layout-extract` → Layout structure
+
+## Phase 1: Setup & Validation
+
+### Step 1: Resolve Base Path & Parse Configuration
+```bash
+# Determine working directory
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+
+# Get style count
+bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+```
+
+### Step 2: Load Layout Templates
+```bash
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Load layout templates
+Read({base_path}/layout-extraction/layout-templates.json)
+# Extract: targets, layout_variants count, device_type, template structures
+```
+
+**Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
+
+### Step 3: Validate Design Tokens
+```bash
+# Check design tokens exist for all styles
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
+
+# For each style variant: Load design tokens
+Read({base_path}/style-consolidation/style-{id}/design-tokens.json)
+```
+
+**Output**: `design_tokens[]` for all style variants
+
+## Phase 2: Assembly (Agent)
+
+**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
+
+### Step 1: Launch Assembly Tasks
+```bash
+bash(mkdir -p {base_path}/prototypes)
+```
+
+For each `target × style_id × layout_id`:
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_STYLE_ASSEMBLY]
+  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
+  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
+
+  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
+  BASE_PATH: {base_path}
+
+  ## Inputs (READ ONLY - NO DESIGN DECISIONS)
+  1. Layout Template:
+     Read("{base_path}/layout-extraction/layout-templates.json")
+     Find template where: target={target} AND variant_id="layout-{layout_id}"
+     Extract: dom_structure, css_layout_rules, device_type
+
+  2. Design Tokens:
+     Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
+     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+
+  ## Assembly Process
+  1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
+     - Recursively build from template.dom_structure
+     - Add: <!DOCTYPE html>, <head>, <meta viewport>
+     - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
+     - Inject placeholder content (Lorem ipsum, sample data)
+     - Preserve all attributes from dom_structure
+
+  2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
+     - Start with template.css_layout_rules
+     - Replace ALL var(--*) with actual token values from design-tokens.json
+       Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
+       Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+     - Add visual styling using design tokens:
+       * Colors: tokens.colors.*
+       * Typography: tokens.typography.*
+       * Shadows: tokens.shadows.*
+       * Border radius: tokens.border_radius.*
+     - Device-optimized for template.device_type
+
+  ## Assembly Rules
+  - ✅ Pure assembly: Combine existing structure + existing style
+  - ❌ NO layout design decisions (structure pre-defined)
+  - ❌ NO style design decisions (tokens pre-defined)
+  - ✅ Replace var() with actual values
+  - ✅ Add placeholder content only
+  - Write files IMMEDIATELY
+  - CSS filename MUST match HTML <link href="...">
+`
+```
+
+### Step 2: Verify Generated Files
+```bash
+# Count expected vs found
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Validate samples
+Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
+# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
+```
+
+**Output**: `S × L × T × 2` files verified
+
+## Phase 3: Generate Preview Files
+
+### Step 1: Run Preview Generation Script
+```bash
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+**Script generates**:
+- `compare.html` (interactive matrix)
+- `index.html` (navigation)
+- `PREVIEW.md` (instructions)
+
+### Step 2: Verify Preview Files
+```bash
+bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
+```
+
+**Output**: 3 preview files
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
+  {content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
+  {content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
+  {content: "Verify files", status: "completed", activeForm: "Validating output"},
+  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
+]});
+```
+
+### Output Message
+```
+✅ UI prototype assembly complete!
+
+Configuration:
+- Style Variants: {style_variants}
+- Layout Variants: {layout_variants} (from layout-templates.json)
+- Device Type: {device_type}
+- Targets: {targets}
+- Total Prototypes: {S × L × T}
+
+Assembly Process:
+- Pure assembly: Combined pre-extracted layouts + design tokens
+- No design decisions: All structure and style pre-defined
+- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations
+
+Quality:
+- Structure: From layout-extract (DOM, CSS layout rules)
+- Style: From consolidate (design tokens)
+- CSS: Token values directly applied (var() replaced)
+- Device-optimized: Layouts match device_type from templates
+
+Generated Files:
+{base_path}/prototypes/
+├── _templates/
+│   └── layout-templates.json (input, pre-extracted)
+├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
+├── {target}-style-{s}-layout-{l}.css
+├── compare.html (interactive matrix)
+├── index.html (navigation)
+└── PREVIEW.md (instructions)
+
+Preview:
+1. Open compare.html (recommended)
+2. Open index.html
+3. Read PREVIEW.md
+
+Next: /workflow:ui-design:update
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Count style variants
+bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+```
+
+### Validation Commands
+```bash
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Check design tokens exist
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
+
+# Count generated files
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Verify preview
+bash(test -f {base_path}/prototypes/compare.html && echo "exists")
+```
+
+### File Operations
+```bash
+# Create directories
+bash(mkdir -p {base_path}/prototypes)
+
+# Run preview script
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── layout-extraction/
+│   └── layout-templates.json      # Input (from layout-extract)
+├── style-consolidation/
+│   └── style-{s}/
+│       ├── design-tokens.json     # Input (from consolidate)
+│       └── style-guide.md
+└── prototypes/
+    ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
+    ├── {target}-style-{s}-layout-{l}.css
+    ├── compare.html
+    ├── index.html
+    └── PREVIEW.md
+```
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: Layout templates not found
+→ Run /workflow:ui-design:layout-extract first
+
+ERROR: Design tokens not found
+→ Run /workflow:ui-design:consolidate first
+
+ERROR: Agent assembly failed
+→ Check inputs exist, validate JSON structure
+
+ERROR: Script permission denied
+→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
+```
+
+### Recovery Strategies
+- **Partial success**: Keep successful assembly combinations
+- **Invalid template structure**: Validate layout-templates.json
+- **Invalid tokens**: Validate design-tokens.json structure
+
+## Quality Checklist
+
+- [ ] CSS uses direct token values (var() replaced)
+- [ ] HTML structure matches layout template exactly
+- [ ] Semantic HTML5 structure preserved
+- [ ] ARIA attributes from template present
+- [ ] Device-specific optimizations applied
+- [ ] All token references resolved
+- [ ] compare.html works
+
+## Key Features
+
+- **Pure Assembly**: No design decisions, only combination
+- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
+- **Token Resolution**: var() placeholders replaced with actual values
+- **Pre-validated**: Inputs already validated by extract/consolidate
+- **Efficient**: Simple assembly vs complex generation
+- **Production-Ready**: Semantic, accessible, token-driven
+
+## Integration
+
+**Prerequisites**:
+- `/workflow:ui-design:style-extract` → `style-cards.json`
+- `/workflow:ui-design:consolidate` → `design-tokens.json`
+- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+
+**Input**: `layout-templates.json` + `design-tokens.json`
+**Output**: S×L×T prototypes for `/workflow:ui-design:update`
+**Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`

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

@@ -0,0 +1,903 @@
+---
+name: imitate-auto
+description: High-speed multi-page UI replication with batch screenshot and optional token refinement
+usage: /workflow:ui-design:imitate-auto --url-map "<map>" [--capture-mode <batch|deep>] [--depth <1-5>] [--session <id>] [--refine-tokens] [--prompt "<desc>"]
+examples:
+  - /workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
+  - /workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing"
+  - /workflow:ui-design:imitate-auto --url-map "dashboard:https://app.com/dash" --refine-tokens
+  - /workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
+  - /workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*)
+---
+
+# UI Design Imitate-Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous replication orchestrator**: Efficiently replicate multiple web pages through sequential execution from screenshot capture to design integration.
+
+**Dual Capture Strategy**: Supports two capture modes for different use cases:
+- **Batch Mode** (default): Fast multi-URL screenshot capture via `/workflow:ui-design:capture`
+- **Deep Mode**: Interactive layer exploration for single URL via `/workflow:ui-design:explore-layers`
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:imitate-auto --url-map "..."`
+2. Phase 0: Initialize and parse parameters
+3. Phase 1: Screenshot capture (batch or deep mode) → **WAIT for completion** → Auto-continues
+4. Phase 2: Style extraction (visual tokens) → **WAIT for completion** → Auto-continues
+5. Phase 2.5: Layout extraction (structure templates) → **WAIT for completion** → Auto-continues
+6. Phase 3: Token processing (conditional consolidate) → **WAIT for completion** → Auto-continues
+7. Phase 4: Batch UI assembly → **WAIT for completion** → Auto-continues
+8. Phase 5: Design system integration → Reports completion
+
+**Phase Transition Mechanism**:
+- `SlashCommand` is BLOCKING - execution pauses until completion
+- Upon each phase completion: Automatically process output and execute next phase
+- No user interaction required after initial parameter parsing
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 5.
+
+## 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. **Track Progress**: Update TodoWrite after each phase
+5. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 5.
+
+## Parameter Requirements
+
+**Required Parameters**:
+- `--url-map "<map>"`: Target page mapping
+  - Format: `"target1:url1, target2:url2, ..."`
+  - Example: `"home:https://linear.app, pricing:https://linear.app/pricing"`
+  - First target serves as primary style source
+
+**Optional Parameters**:
+- `--capture-mode <batch|deep>` (Optional, default: batch): Screenshot capture strategy
+  - `batch` (default): Multi-URL fast batch capture via `/workflow:ui-design:capture`
+  - `deep`: Single-URL interactive depth exploration via `/workflow:ui-design:explore-layers`
+  - **Note**: `deep` mode only uses first URL from url-map
+
+- `--depth <1-5>` (Optional, default: 3): Capture depth for deep mode
+  - `1`: Page level (full-page screenshot)
+  - `2`: Element level (+ key components)
+  - `3`: Interaction level (+ modals, dropdowns)
+  - `4`: Embedded level (+ iframes)
+  - `5`: Shadow DOM (+ web components)
+  - **Only applies when** `--capture-mode deep`
+
+- `--session <id>` (Optional): Workflow session ID
+  - Integrate into existing session (`.workflow/WFS-{session}/`)
+  - Enable automatic design system integration (Phase 5)
+  - If not provided: standalone mode (`.workflow/.design/`)
+
+- `--refine-tokens` (Optional, default: false): Enable full token refinement
+  - `false` (default): Fast path, skip consolidate (~30-60s faster)
+  - `true`: Production quality, execute full consolidate (philosophy-driven refinement)
+
+- `--prompt "<desc>"` (Optional): Style extraction guidance
+  - Influences extract command analysis focus
+  - Example: `"Focus on dark mode"`, `"Emphasize minimalist design"`
+
+## Execution Modes
+
+**Capture Modes**:
+- **Batch Mode** (default): Multi-URL screenshot capture for fast replication
+  - Uses `/workflow:ui-design:capture` for parallel screenshot capture
+  - Optimized for replicating multiple pages efficiently
+- **Deep Mode**: Single-URL layer exploration for detailed analysis
+  - Uses `/workflow:ui-design:explore-layers` for interactive depth traversal
+  - Captures page layers at different depths (1-5)
+  - Only processes first URL from url-map
+
+**Token Processing Modes**:
+- **Fast-Track** (default): Skip consolidate, use proposed tokens directly (~2s)
+  - Best for rapid prototyping and testing
+  - Tokens may lack philosophy-driven refinement
+- **Production** (--refine-tokens): Full consolidate with WCAG validation (~60s)
+  - Philosophy-driven token refinement
+  - Complete accessibility validation
+  - Production-ready design system
+
+**Session Integration**:
+- `--session` flag determines session integration or standalone execution
+- Integrated: Design system automatically added to session artifacts
+- Standalone: Output in `.workflow/.design/{run_id}/`
+
+## 6-Phase Execution
+
+### Phase 0: Initialization and Target Parsing
+
+```bash
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 UI Design Imitate-Auto"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Constants
+DEPTH_NAMES = {
+    1: "Page level",
+    2: "Element level",
+    3: "Interaction level",
+    4: "Embedded level",
+    5: "Shadow DOM"
+}
+
+# Generate run ID
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+
+# Determine base path and session mode
+IF --session:
+    session_id = {provided_session}
+    base_path = ".workflow/WFS-{session_id}/design-{run_id}"
+    session_mode = "integrated"
+    REPORT: "Mode: Integrated (Session: {session_id})"
+ELSE:
+    session_id = null
+    base_path = ".workflow/.design/{run_id}"
+    session_mode = "standalone"
+    REPORT: "Mode: Standalone"
+
+# Create base directory
+Bash(mkdir -p "{base_path}")
+
+# Parse url-map
+url_map_string = {--url-map}
+VALIDATE: url_map_string is not empty, "--url-map parameter is required"
+
+# Parse target:url pairs
+url_map = {}  # {target_name: url}
+target_names = []
+
+FOR pair IN split(url_map_string, ","):
+    pair = pair.strip()
+
+    IF ":" NOT IN pair:
+        ERROR: "Invalid url-map format: '{pair}'"
+        ERROR: "Expected format: 'target:url'"
+        ERROR: "Example: 'home:https://example.com, pricing:https://example.com/pricing'"
+        EXIT 1
+
+    target, url = pair.split(":", 1)
+    target = target.strip().lower().replace(" ", "-")
+    url = url.strip()
+
+    url_map[target] = url
+    target_names.append(target)
+
+VALIDATE: len(target_names) > 0, "url-map must contain at least one target:url pair"
+
+primary_target = target_names[0]  # First target as primary style source
+refine_tokens_mode = --refine-tokens OR false
+
+# Parse capture mode
+capture_mode = --capture-mode OR "batch"
+depth = int(--depth OR 3)
+
+# Validate capture mode
+IF capture_mode NOT IN ["batch", "deep"]:
+    ERROR: "Invalid --capture-mode: {capture_mode}"
+    ERROR: "Valid options: batch, deep"
+    EXIT 1
+
+# Validate depth (only for deep mode)
+IF capture_mode == "deep":
+    IF depth NOT IN [1, 2, 3, 4, 5]:
+        ERROR: "Invalid --depth: {depth}"
+        ERROR: "Valid range: 1-5"
+        EXIT 1
+
+    # Warn if multiple URLs in deep mode
+    IF len(target_names) > 1:
+        WARN: "⚠️ Deep mode only uses first URL: '{primary_target}'"
+        WARN: "   Other URLs will be ignored: {', '.join(target_names[1:])}"
+        WARN: "   For multi-URL, use --capture-mode batch"
+
+# Write metadata
+metadata = {
+    "workflow": "imitate-auto",
+    "run_id": run_id,
+    "session_id": session_id,
+    "timestamp": current_timestamp(),
+    "parameters": {
+        "url_map": url_map,
+        "capture_mode": capture_mode,
+        "depth": depth IF capture_mode == "deep" ELSE null,
+        "refine_tokens": refine_tokens_mode,
+        "prompt": --prompt OR null
+    },
+    "targets": target_names,
+    "status": "in_progress"
+}
+
+Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
+
+REPORT: ""
+REPORT: "Configuration:"
+REPORT: "  Capture mode: {capture_mode}"
+IF capture_mode == "deep":
+    REPORT: "    Depth level: {depth} ({DEPTH_NAMES[depth]})"
+    REPORT: "    Target: '{primary_target}' ({url_map[primary_target]})"
+ELSE:
+    REPORT: "    Targets: {len(target_names)} pages"
+    REPORT: "    Primary source: '{primary_target}' ({url_map[primary_target]})"
+    REPORT: "    All targets: {', '.join(target_names)}"
+REPORT: "  Token refinement: {refine_tokens_mode ? 'Enabled (production quality)' : 'Disabled (fast-track)'}"
+IF --prompt:
+    REPORT: "  Prompt guidance: \"{--prompt}\""
+REPORT: ""
+
+# Initialize TodoWrite
+TodoWrite({todos: [
+  {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
+  {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "pending", activeForm: "Capturing screenshots"},
+  {content: "Extract style (visual tokens)", status: "pending", activeForm: "Extracting style"},
+  {content: "Extract layout (structure templates)", status: "pending", activeForm: "Extracting layout"},
+  {content: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation (skip consolidate)", status: "pending", activeForm: "Processing tokens"},
+  {content: f"Assemble UI for {len(target_names)} targets", status: "pending", activeForm: "Assembling UI"},
+  {content: session_id ? "Integrate design system" : "Standalone completion", status: "pending", activeForm: "Completing"}
+]})
+```
+
+### Phase 1: Screenshot Capture (Dual Mode)
+
+```bash
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: f"🚀 Phase 1: Screenshot Capture ({capture_mode} mode)"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+IF capture_mode == "batch":
+    # Mode A: Batch Multi-URL Capture
+    REPORT: "Using batch capture for multiple URLs..."
+
+    # Build url-map string for capture command
+    url_map_command_string = ",".join([f"{name}:{url}" for name, url in url_map.items()])
+
+    # Call capture command
+    capture_command = f"/workflow:ui-design:capture --base-path \"{base_path}\" --url-map \"{url_map_command_string}\""
+
+    REPORT: f"  Command: {capture_command}"
+    REPORT: f"  Targets: {len(target_names)}"
+
+    TRY:
+        SlashCommand(capture_command)
+    CATCH error:
+        ERROR: "Batch capture failed: {error}"
+        ERROR: "Cannot proceed without screenshots"
+        EXIT 1
+
+    # Verify batch capture results
+    screenshot_metadata_path = "{base_path}/screenshots/capture-metadata.json"
+
+    IF NOT exists(screenshot_metadata_path):
+        ERROR: "capture command did not generate metadata file"
+        ERROR: "Expected: {screenshot_metadata_path}"
+        EXIT 1
+
+    screenshot_metadata = Read(screenshot_metadata_path)
+    captured_count = screenshot_metadata.total_captured
+    total_requested = screenshot_metadata.total_requested
+    missing_count = total_requested - captured_count
+
+    REPORT: ""
+    REPORT: "✅ Batch capture complete:"
+    REPORT: "   Captured: {captured_count}/{total_requested} screenshots ({(captured_count/total_requested*100):.1f}%)"
+
+    IF missing_count > 0:
+        missing_targets = [s.target for s in screenshot_metadata.screenshots if not s.captured]
+        WARN: "   ⚠️ Missing {missing_count} screenshots: {', '.join(missing_targets)}"
+        WARN: "   Proceeding with available screenshots for extract phase"
+
+    # If all screenshots failed, terminate
+    IF captured_count == 0:
+        ERROR: "No screenshots captured - cannot proceed"
+        ERROR: "Please check URLs and tool availability"
+        EXIT 1
+
+ELSE:  # capture_mode == "deep"
+    # Mode B: Deep Interactive Layer Exploration
+    REPORT: "Using deep exploration for single URL..."
+
+    primary_url = url_map[primary_target]
+
+    # Call explore-layers command
+    explore_command = f"/workflow:ui-design:explore-layers --url \"{primary_url}\" --depth {depth} --base-path \"{base_path}\""
+
+    REPORT: f"  Command: {explore_command}"
+    REPORT: f"  URL: {primary_url}"
+    REPORT: f"  Depth: {depth} ({DEPTH_NAMES[depth]})"
+
+    TRY:
+        SlashCommand(explore_command)
+    CATCH error:
+        ERROR: "Deep exploration failed: {error}"
+        ERROR: "Cannot proceed without screenshots"
+        EXIT 1
+
+    # Verify deep exploration results
+    layer_map_path = "{base_path}/screenshots/layer-map.json"
+
+    IF NOT exists(layer_map_path):
+        ERROR: "explore-layers did not generate layer-map.json"
+        ERROR: "Expected: {layer_map_path}"
+        EXIT 1
+
+    layer_map = Read(layer_map_path)
+    total_layers = len(layer_map.layers)
+    captured_count = layer_map.summary.total_captures
+
+    REPORT: ""
+    REPORT: "✅ Deep exploration complete:"
+    REPORT: "   Layers: {total_layers} (depth 1-{depth})"
+    REPORT: "   Captures: {captured_count} screenshots"
+    REPORT: "   Total size: {layer_map.summary.total_size_kb:.1f} KB"
+
+    # Count actual images for extract phase
+    total_requested = captured_count  # For consistency with batch mode
+
+TodoWrite(mark_completed: f"Batch screenshot capture ({len(target_names)} targets)" IF capture_mode == "batch" ELSE f"Deep exploration (depth {depth})",
+          mark_in_progress: "Extract style (visual tokens)")
+```
+
+### Phase 2: Style Extraction (Visual Tokens)
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 2: Extract Style (Visual Tokens)"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Use all screenshots as input to extract single design system
+IF capture_mode == "batch":
+    images_glob = f"{base_path}/screenshots/*.{{png,jpg,jpeg,webp}}"
+ELSE:  # deep mode
+    images_glob = f"{base_path}/screenshots/**/*.{{png,jpg,jpeg,webp}}"  # Include all depth directories
+
+# Build extraction prompt
+IF --prompt:
+    user_guidance = {--prompt}
+    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency. User guidance: {user_guidance}"
+ELSE:
+    extraction_prompt = f"Extract visual style tokens (colors, typography, spacing) from the '{primary_target}' page. Use other screenshots for consistency across all pages."
+
+# Call style-extract command (imitate mode, automatically uses single variant)
+extract_command = f"/workflow:ui-design:style-extract --base-path \"{base_path}\" --images \"{images_glob}\" --prompt \"{extraction_prompt}\" --mode imitate"
+
+REPORT: "Calling style-extract command..."
+REPORT: f"  Mode: imitate (high-fidelity single style, auto variants=1)"
+REPORT: f"  Primary source: '{primary_target}'"
+REPORT: f"  Images: {images_glob}"
+
+TRY:
+    SlashCommand(extract_command)
+CATCH error:
+    ERROR: "Style extraction failed: {error}"
+    ERROR: "Cannot proceed without visual tokens"
+    EXIT 1
+
+# style-extract outputs to: {base_path}/style-extraction/style-cards.json
+
+# Verify extraction results
+style_cards_path = "{base_path}/style-extraction/style-cards.json"
+
+IF NOT exists(style_cards_path):
+    ERROR: "style-extract command did not generate style-cards.json"
+    ERROR: "Expected: {style_cards_path}"
+    EXIT 1
+
+style_cards = Read(style_cards_path)
+
+IF len(style_cards.style_cards) != 1:
+    ERROR: "Expected single variant in imitate mode, got {len(style_cards.style_cards)}"
+    EXIT 1
+
+extracted_style = style_cards.style_cards[0]
+
+REPORT: ""
+REPORT: "✅ Phase 2 complete:"
+REPORT: "   Style: '{extracted_style.name}'"
+REPORT: "   Philosophy: {extracted_style.design_philosophy}"
+REPORT: "   Tokens: {count_tokens(extracted_style.proposed_tokens)} visual tokens"
+
+TodoWrite(mark_completed: "Extract style (visual tokens)",
+          mark_in_progress: "Extract layout (structure templates)")
+```
+
+### Phase 2.5: Layout Extraction (Structure Templates)
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 2.5: Extract Layout (Structure Templates)"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Reuse same screenshots for layout extraction
+# Build URL map for layout-extract (uses first URL from each target)
+url_map_for_layout = ",".join([f"{target}:{url}" for target, url in url_map.items()])
+
+# Call layout-extract command (imitate mode for structure replication)
+layout_extract_command = f"/workflow:ui-design:layout-extract --base-path \"{base_path}\" --images \"{images_glob}\" --targets \"{','.join(target_names)}\" --mode imitate"
+
+REPORT: "Calling layout-extract command..."
+REPORT: f"  Mode: imitate (high-fidelity structure replication)"
+REPORT: f"  Targets: {', '.join(target_names)}"
+REPORT: f"  Images: {images_glob}"
+
+TRY:
+    SlashCommand(layout_extract_command)
+CATCH error:
+    ERROR: "Layout extraction failed: {error}"
+    ERROR: "Cannot proceed without layout templates"
+    EXIT 1
+
+# layout-extract outputs to: {base_path}/layout-extraction/layout-templates.json
+
+# Verify layout extraction results
+layout_templates_path = "{base_path}/layout-extraction/layout-templates.json"
+
+IF NOT exists(layout_templates_path):
+    ERROR: "layout-extract command did not generate layout-templates.json"
+    ERROR: "Expected: {layout_templates_path}"
+    EXIT 1
+
+layout_templates = Read(layout_templates_path)
+template_count = len(layout_templates.layout_templates)
+
+REPORT: ""
+REPORT: "✅ Phase 2.5 complete:"
+REPORT: "   Templates: {template_count} layout structures"
+REPORT: "   Targets: {', '.join(target_names)}"
+
+TodoWrite(mark_completed: "Extract layout (structure templates)",
+          mark_in_progress: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation")
+```
+
+### Phase 3: Token Processing (Conditional Consolidate)
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 3: Token Processing"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+IF refine_tokens_mode:
+    # Path A: Full consolidate (production quality)
+    REPORT: "🔧 Using full consolidate for production-ready tokens"
+    REPORT: "   Benefits:"
+    REPORT: "   • Philosophy-driven token refinement"
+    REPORT: "   • WCAG AA accessibility validation"
+    REPORT: "   • Complete design system documentation"
+    REPORT: "   • Token gap filling and consistency checks"
+    REPORT: ""
+
+    consolidate_command = f"/workflow:ui-design:consolidate --base-path \"{base_path}\" --variants 1"
+
+    REPORT: f"Calling consolidate command..."
+
+    TRY:
+        SlashCommand(consolidate_command)
+    CATCH error:
+        ERROR: "Token consolidation failed: {error}"
+        ERROR: "Cannot proceed without refined tokens"
+        EXIT 1
+
+    # consolidate outputs to: {base_path}/style-consolidation/style-1/design-tokens.json
+    tokens_path = "{base_path}/style-consolidation/style-1/design-tokens.json"
+
+    IF NOT exists(tokens_path):
+        ERROR: "consolidate command did not generate design-tokens.json"
+        ERROR: "Expected: {tokens_path}"
+        EXIT 1
+
+    REPORT: ""
+    REPORT: "✅ Full consolidate complete"
+    REPORT: "   Output: style-consolidation/style-1/"
+    REPORT: "   Quality: Production-ready"
+    token_quality = "production-ready (consolidated)"
+    time_spent_estimate = "~60s"
+
+ELSE:
+    # Path B: Fast Token Adaptation
+    REPORT: "⚡ Fast token adaptation (skipping consolidate for speed)"
+    REPORT: "   Note: Using proposed tokens from extraction phase"
+    REPORT: "   For production quality, re-run with --refine-tokens flag"
+    REPORT: ""
+
+    # Directly copy proposed_tokens to consolidation directory
+    style_cards = Read("{base_path}/style-extraction/style-cards.json")
+    proposed_tokens = style_cards.style_cards[0].proposed_tokens
+
+    # Create directory and write tokens
+    consolidation_dir = "{base_path}/style-consolidation/style-1"
+    Bash(mkdir -p "{consolidation_dir}")
+
+    tokens_path = f"{consolidation_dir}/design-tokens.json"
+    Write(tokens_path, JSON.stringify(proposed_tokens, null, 2))
+
+    # Create simplified style guide
+    variant = style_cards.style_cards[0]
+    simple_guide = f"""# Design System: {variant.name}
+
+## Design Philosophy
+{variant.design_philosophy}
+
+## Description
+{variant.description}
+
+## Design Tokens
+All tokens in `design-tokens.json` follow OKLCH color space.
+
+**Note**: Generated in fast-track imitate mode using proposed tokens from extraction.
+For production-ready quality with philosophy-driven refinement, re-run with `--refine-tokens` flag.
+
+## Color Preview
+- Primary: {variant.preview.primary if variant.preview else "N/A"}
+- Background: {variant.preview.background if variant.preview else "N/A"}
+
+## Typography Preview
+- Heading Font: {variant.preview.font_heading if variant.preview else "N/A"}
+
+## Token Categories
+{list_token_categories(proposed_tokens)}
+"""
+
+    Write(f"{consolidation_dir}/style-guide.md", simple_guide)
+
+    REPORT: "✅ Fast adaptation complete (~2s vs ~60s with consolidate)"
+    REPORT: "   Output: style-consolidation/style-1/"
+    REPORT: "   Quality: Proposed (not refined)"
+    REPORT: "   Time saved: ~30-60s"
+    token_quality = "proposed (fast-track)"
+    time_spent_estimate = "~2s"
+
+REPORT: ""
+REPORT: "Token processing summary:"
+REPORT: "   Path: {refine_tokens_mode ? 'Full consolidate' : 'Fast adaptation'}"
+REPORT: "   Quality: {token_quality}"
+REPORT: "   Time: {time_spent_estimate}"
+
+TodoWrite(mark_completed: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation",
+          mark_in_progress: f"Assemble UI for {len(target_names)} targets")
+```
+
+### Phase 4: Batch UI Assembly
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 4: Batch UI Assembly"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# Build targets string
+targets_string = ",".join(target_names)
+
+# Call generate command (now pure assembler - combines layout templates + design tokens)
+generate_command = f"/workflow:ui-design:generate --base-path \"{base_path}\" --style-variants 1 --layout-variants 1"
+
+REPORT: "Calling generate command (pure assembler)..."
+REPORT: f"  Targets: {targets_string} (from layout templates)"
+REPORT: f"  Configuration: 1 style × 1 layout × {len(target_names)} pages"
+REPORT: f"  Inputs: layout-templates.json + design-tokens.json"
+
+TRY:
+    SlashCommand(generate_command)
+CATCH error:
+    ERROR: "UI assembly failed: {error}"
+    ERROR: "Layout templates or design tokens may be invalid"
+    EXIT 1
+
+# generate outputs to: {base_path}/prototypes/{target}-style-1-layout-1.html
+
+# Verify assembly results
+prototypes_dir = "{base_path}/prototypes"
+generated_html_files = Glob(f"{prototypes_dir}/*-style-1-layout-1.html")
+generated_count = len(generated_html_files)
+
+REPORT: ""
+REPORT: "✅ Phase 4 complete:"
+REPORT: "   Assembled: {generated_count} HTML prototypes"
+REPORT: "   Targets: {', '.join(target_names)}"
+REPORT: "   Output: {prototypes_dir}/"
+
+IF generated_count < len(target_names):
+    WARN: "   ⚠️ Expected {len(target_names)} prototypes, assembled {generated_count}"
+    WARN: "   Some targets may have failed - check generate output"
+
+TodoWrite(mark_completed: f"Assemble UI for {len(target_names)} targets",
+          mark_in_progress: session_id ? "Integrate design system" : "Standalone completion")
+```
+
+### Phase 5: Design System Integration
+
+```bash
+REPORT: ""
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+REPORT: "🚀 Phase 5: Design System Integration"
+REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+IF session_id:
+    REPORT: "Integrating design system into session {session_id}..."
+
+    update_command = f"/workflow:ui-design:update --session {session_id}"
+
+    TRY:
+        SlashCommand(update_command)
+    CATCH error:
+        WARN: "Design system integration failed: {error}"
+        WARN: "Prototypes are still available at {base_path}/prototypes/"
+        # Don't terminate, prototypes already generated
+
+    REPORT: "✅ Design system integrated into session {session_id}"
+ELSE:
+    REPORT: "ℹ️ Standalone mode: Skipping integration"
+    REPORT: "   Prototypes available at: {base_path}/prototypes/"
+    REPORT: "   To integrate later:"
+    REPORT: "   1. Create a workflow session"
+    REPORT: "   2. Copy design-tokens.json to session artifacts"
+
+# Update metadata
+metadata = Read("{base_path}/.run-metadata.json")
+metadata.status = "completed"
+metadata.completion_time = current_timestamp()
+metadata.outputs = {
+    "screenshots": f"{base_path}/screenshots/",
+    "style_system": f"{base_path}/style-consolidation/style-1/",
+    "prototypes": f"{base_path}/prototypes/",
+    "token_quality": token_quality,
+    "captured_count": captured_count,
+    "generated_count": generated_count
+}
+Write("{base_path}/.run-metadata.json", JSON.stringify(metadata, null, 2))
+
+TodoWrite(mark_completed: session_id ? "Integrate design system" : "Standalone completion")
+
+# Mark all phases complete
+TodoWrite({todos: [
+  {content: "Initialize and parse url-map", status: "completed", activeForm: "Initializing"},
+  {content: capture_mode == "batch" ? f"Batch screenshot capture ({len(target_names)} targets)" : f"Deep exploration (depth {depth})", status: "completed", activeForm: "Capturing"},
+  {content: "Extract unified design system", status: "completed", activeForm: "Extracting"},
+  {content: refine_tokens_mode ? "Refine design tokens via consolidate" : "Fast token adaptation", status: "completed", activeForm: "Processing"},
+  {content: f"Generate UI for {len(target_names)} targets", status: "completed", activeForm: "Generating"},
+  {content: session_id ? "Integrate design system" : "Standalone completion", status: "completed", activeForm: "Completing"}
+]})
+```
+
+### Phase 6: Completion Report
+
+**Completion Message**:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+✅ UI Design Imitate-Auto Complete!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+━━━ 📊 Workflow Summary ━━━
+
+Mode: {capture_mode == "batch" ? "Batch Multi-Page Replication" : f"Deep Interactive Exploration (depth {depth})"}
+Session: {session_id or "standalone"}
+Run ID: {run_id}
+
+Phase 1 - Screenshot Capture: ✅ {IF capture_mode == "batch": f"{captured_count}/{total_requested} screenshots" ELSE: f"{captured_count} screenshots ({total_layers} layers)"}
+  {IF capture_mode == "batch" AND captured_count < total_requested: f"⚠️ {total_requested - captured_count} missing" ELSE: "All targets captured"}
+
+Phase 2 - Style Extraction: ✅ Single unified design system
+  Style: {extracted_style.name}
+  Philosophy: {extracted_style.design_philosophy[:80]}...
+
+Phase 3 - Token Processing: ✅ {token_quality}
+  {IF refine_tokens_mode:
+    "Full consolidate (~60s)"
+    "Quality: Production-ready with philosophy-driven refinement"
+  ELSE:
+    "Fast adaptation (~2s, saved ~30-60s)"
+    "Quality: Proposed tokens (for production, use --refine-tokens)"
+  }
+
+Phase 4 - UI Generation: ✅ {generated_count} pages generated
+  Targets: {', '.join(target_names)}
+  Configuration: 1 style × 1 layout × {generated_count} pages
+
+Phase 5 - Integration: {IF session_id: "✅ Integrated into session" ELSE: "⏭️ Standalone mode"}
+
+━━━ 📂 Output Structure ━━━
+
+{base_path}/
+├── screenshots/                    # {captured_count} screenshots
+{IF capture_mode == "batch":
+│   ├── {target1}.png
+│   ├── {target2}.png
+│   └── capture-metadata.json
+ELSE:
+│   ├── depth-1/
+│   │   └── full-page.png
+│   ├── depth-2/
+│   │   └── {elements}.png
+│   ├── depth-{depth}/
+│   │   └── {layers}.png
+│   └── layer-map.json
+}
+├── style-extraction/               # Design analysis
+│   └── style-cards.json
+├── style-consolidation/            # {token_quality}
+│   └── style-1/
+│       ├── design-tokens.json
+│       └── style-guide.md
+└── prototypes/                     # {generated_count} HTML/CSS files
+    ├── {target1}-style-1-layout-1.html + .css
+    ├── {target2}-style-1-layout-1.html + .css
+    ├── compare.html                # Interactive preview
+    └── index.html                  # Quick navigation
+
+━━━ ⚡ Performance ━━━
+
+Total workflow time: ~{estimate_total_time()} minutes
+  Screenshot capture: ~{capture_time}
+  Style extraction: ~{extract_time}
+  Token processing: ~{token_processing_time}
+  UI generation: ~{generate_time}
+
+━━━ 🌐 Next Steps ━━━
+
+1. Preview prototypes:
+   • Interactive matrix: Open {base_path}/prototypes/compare.html
+   • Quick navigation: Open {base_path}/prototypes/index.html
+
+{IF session_id:
+2. Create implementation tasks:
+   /workflow:plan --session {session_id}
+
+3. Generate tests (if needed):
+   /workflow:test-gen {session_id}
+ELSE:
+2. To integrate into a workflow session:
+   • Create session: /workflow:session:start
+   • Copy design-tokens.json to session artifacts
+
+3. Explore prototypes in {base_path}/prototypes/ directory
+}
+
+{IF NOT refine_tokens_mode:
+💡 Production Quality Tip:
+   Fast-track mode used proposed tokens for speed.
+   For production-ready quality with full token refinement:
+   /workflow:ui-design:imitate-auto --url-map "{url_map_command_string}" --refine-tokens {f"--session {session_id}" if session_id else ""}
+}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize IMMEDIATELY at start of Phase 0 to track multi-phase execution
+TodoWrite({todos: [
+  {content: "Initialize and parse url-map", status: "in_progress", activeForm: "Initializing"},
+  {content: "Batch screenshot capture", status: "pending", activeForm: "Capturing screenshots"},
+  {content: "Extract unified design system", status: "pending", activeForm: "Extracting style"},
+  {content: refine_tokens ? "Refine tokens via consolidate" : "Fast token adaptation", status: "pending", activeForm: "Processing tokens"},
+  {content: "Generate UI for all targets", status: "pending", activeForm: "Generating UI"},
+  {content: "Integrate design system", status: "pending", activeForm: "Integrating"}
+]})
+
+// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
+// 1. SlashCommand blocks and returns when phase is complete
+// 2. Update current phase: status → "completed"
+// 3. Update next phase: status → "in_progress"
+// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+// This ensures continuous workflow tracking and prevents premature stopping
+```
+
+## Error Handling
+
+### Pre-execution Checks
+- **url-map format validation**: Clear error message with format example
+- **Empty url-map**: Error and exit
+- **Invalid target names**: Regex validation with suggestions
+
+### Phase-Specific Errors
+- **Screenshot capture failure (Phase 1)**:
+  - If total_captured == 0: Terminate workflow
+  - If partial failure: Warn but continue with available screenshots
+
+- **Style extraction failure (Phase 2)**:
+  - If extract fails: Terminate with clear error
+  - If style-cards.json missing: Terminate with debugging info
+
+- **Token processing failure (Phase 3)**:
+  - Consolidate mode: Terminate if consolidate fails
+  - Fast mode: Validate proposed_tokens exist before copying
+
+- **UI generation failure (Phase 4)**:
+  - If generate fails: Terminate with error
+  - If generated_count < target_count: Warn but proceed
+
+- **Integration failure (Phase 5)**:
+  - Non-blocking: Warn but don't terminate
+  - Prototypes already available
+
+### Recovery Strategies
+- **Partial screenshot failure**: Continue with available screenshots, list missing in warning
+- **Generate failure**: Report specific target failures, user can re-generate individually
+- **Integration failure**: Prototypes still usable, can integrate manually
+
+
+## Key Features
+
+- **🚀 Dual Capture**: Batch mode for speed, deep mode for detail
+- **⚡ Fast-Track Option**: Skip consolidate for 30-60s time savings
+- **🎨 High-Fidelity**: Single unified design system from primary target
+- **📦 Autonomous**: No user intervention required between phases
+- **🔄 Reproducible**: Deterministic flow with isolated run directories
+- **🎯 Flexible**: Standalone or session-integrated modes
+
+## Examples
+
+### 1. Basic Multi-Page Replication
+```bash
+/workflow:ui-design:imitate-auto --url-map "home:https://linear.app, features:https://linear.app/features"
+# Result: 2 prototypes with fast-track tokens
+```
+
+### 2. Production-Ready with Session
+```bash
+/workflow:ui-design:imitate-auto --session WFS-payment --url-map "pricing:https://stripe.com/pricing" --refine-tokens
+# Result: 1 prototype with production tokens, integrated into session
+```
+
+### 3. Deep Exploration Mode
+```bash
+/workflow:ui-design:imitate-auto --url-map "app:https://app.com" --capture-mode deep --depth 3
+# Result: Interactive layer capture + prototype
+```
+
+### 4. Guided Style Extraction
+```bash
+/workflow:ui-design:imitate-auto --url-map "home:https://example.com, about:https://example.com/about" --prompt "Focus on minimalist design"
+# Result: 2 prototypes with minimalist style focus
+```
+
+## Integration Points
+
+- **Input**: `--url-map` (multiple target:url pairs) + optional `--capture-mode`, `--depth`, `--session`, `--refine-tokens`, `--prompt`
+- **Output**: Complete design system in `{base_path}/` (screenshots, style-extraction, style-consolidation, prototypes)
+- **Sub-commands Called**:
+  1. Phase 1 (conditional):
+     - `--capture-mode batch`: `/workflow:ui-design:capture` (multi-URL batch)
+     - `--capture-mode deep`: `/workflow:ui-design:explore-layers` (single-URL depth exploration)
+  2. `/workflow:ui-design:extract` (Phase 2)
+  3. `/workflow:ui-design:consolidate` (Phase 3, conditional)
+  4. `/workflow:ui-design:generate` (Phase 4)
+  5. `/workflow:ui-design:update` (Phase 5, if --session)
+
+## Completion Output
+
+```
+✅ UI Design Imitate-Auto Workflow Complete!
+
+Mode: {capture_mode} | Session: {session_id or "standalone"}
+Run ID: {run_id}
+
+Phase 1 - Screenshot Capture: ✅ {captured_count} screenshots
+Phase 2 - Style Extraction: ✅ Single unified design system
+Phase 3 - Token Processing: ✅ {token_quality}
+Phase 4 - UI Generation: ✅ {generated_count} pages generated
+Phase 5 - Integration: {IF session_id: "✅ Integrated" ELSE: "⏭️ Standalone"}
+
+Design Quality:
+✅ High-Fidelity Replication: Accurate style from primary target
+✅ Token-Driven Styling: 100% var() usage
+✅ {IF refine_tokens: "Production-Ready: WCAG validated" ELSE: "Fast-Track: Proposed tokens"}
+
+📂 {base_path}/
+  ├── screenshots/                  # {captured_count} screenshots
+  ├── style-extraction/             # Design analysis
+  ├── style-consolidation/          # {token_quality}
+  └── prototypes/                   # {generated_count} HTML/CSS files
+
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive preview
+  - Side-by-side comparison
+  - {generated_count} replicated pages
+
+Next: [/workflow:execute] OR [Open compare.html → /workflow:plan]
+```

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

@@ -0,0 +1,371 @@
+---
+name: layout-extract
+description: Extract structural layout information from reference images, URLs, or text prompts
+usage: /workflow:ui-design:layout-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
+examples:
+  - /workflow:ui-design:layout-extract --urls "home:https://linear.app" --mode imitate --targets "home"
+  - /workflow:ui-design:layout-extract --images "refs/*.png" --mode explore --variants 3 --targets "dashboard"
+  - /workflow:ui-design:layout-extract --prompt "Two-column blog with sticky sidebar" --mode explore --variants 2 --targets "blog-post"
+  - /workflow:ui-design:layout-extract --session WFS-auth --urls "login:https://clerk.dev" --device-type mobile --targets "login"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
+---
+
+# Layout Extraction Command
+
+## Overview
+Extract structural layout information from reference images, URLs, or text prompts using AI analysis. This command separates the "scaffolding" (HTML structure and CSS layout) from the "paint" (visual tokens handled by `style-extract`).
+
+**Strategy**: AI-Driven Structural Analysis
+- **Agent-Powered**: Uses `ui-design-agent` for deep structural analysis
+- **Dual-Mode**:
+  - `imitate`: High-fidelity replication of single layout structure
+  - `explore`: Multiple structurally distinct layout variations
+- **Single Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
+- **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
+- **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input, Mode & Targets
+```bash
+# Detect input source
+# Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
+
+# Determine extraction mode
+extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+
+# Set variants count based on mode
+IF extraction_mode == "imitate":
+    variants_count = 1  # Force single variant (ignore --variants)
+ELSE IF extraction_mode == "explore":
+    variants_count = --variants OR 3  # Default to 3
+    VALIDATE: 1 <= variants_count <= 5
+
+# Resolve targets
+# Priority: --targets → prompt analysis → default ["page"]
+targets = --targets OR extract_from_prompt(--prompt) OR ["page"]
+
+# Resolve device type
+device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Inputs & Create Directories
+```bash
+# For image mode
+bash(ls {images_pattern})  # Expand glob pattern
+Read({image_path})  # Load each image
+
+# For URL mode
+# Parse URL list format: "target:url,target:url"
+# Validate URLs are accessible
+
+# For text mode
+# Validate --prompt is non-empty
+
+# Create output directory
+bash(mkdir -p {base_path}/layout-extraction)
+```
+
+### Step 3: Memory Check (Skip if Already Done)
+```bash
+# Check if layouts already extracted
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+```
+
+**If exists**: Skip to completion message
+
+**Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+
+## Phase 1: Layout Research (Explore Mode Only)
+
+### Step 1: Check Extraction Mode
+```bash
+# extraction_mode == "imitate" → skip this phase
+# extraction_mode == "explore" → execute this phase
+```
+
+**If imitate mode**: Skip to Phase 2
+
+### Step 2: Gather Layout Inspiration (Explore Mode)
+```bash
+bash(mkdir -p {base_path}/layout-extraction/_inspirations)
+
+# For each target: Research via MCP
+# mcp__exa__web_search_exa(query="{target} layout patterns {device_type}", numResults=5)
+
+# Write inspiration file
+Write({base_path}/layout-extraction/_inspirations/{target}-layout-ideas.txt, inspiration_content)
+```
+
+**Output**: Inspiration text files for each target (explore mode only)
+
+## Phase 2: Layout Analysis & Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)`
+
+### Step 1: Launch Agent Task
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_EXTRACTION_TASK]
+  Analyze references and extract structural layout templates.
+  Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
+
+  REFERENCES:
+  - Input: {reference_material}  // Images, URLs, or prompt
+  - Mode: {extraction_mode}  // 'imitate' or 'explore'
+  - Targets: {targets}  // List of page/component names
+  - Variants per Target: {variants_count}
+  - Device Type: {device_type}
+  ${exploration_mode ? "- Layout Inspiration: Read('" + base_path + "/layout-extraction/_inspirations/{target}-layout-ideas.txt')" : ""}
+
+  ## Analysis & Generation
+  For EACH target in {targets}:
+    For EACH variant (1 to {variants_count}):
+      1. **Analyze Structure**: Deconstruct reference to understand layout, hierarchy, responsiveness
+      2. **Define Philosophy**: Short description (e.g., "Asymmetrical grid with overlapping content areas")
+      3. **Generate DOM Structure**: JSON object representing semantic HTML5 structure
+         - Semantic tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+         - ARIA roles and accessibility attributes
+         - Device-specific structure:
+           * mobile: Single column, stacked sections, touch targets ≥44px
+           * desktop: Multi-column grids, hover states, larger hit areas
+           * tablet: Hybrid layouts, flexible columns
+           * responsive: Breakpoint-driven adaptive layouts (mobile-first)
+         - In 'explore' mode: Each variant structurally DISTINCT
+      4. **Define Component Hierarchy**: High-level array of main layout regions
+         Example: ["header", "main-content", "sidebar", "footer"]
+      5. **Generate CSS Layout Rules**:
+         - Focus ONLY on layout (Grid, Flexbox, position, alignment, gap, etc.)
+         - Use CSS Custom Properties for spacing/breakpoints: var(--spacing-4), var(--breakpoint-md)
+         - Device-specific styles (mobile-first @media for responsive)
+         - NO colors, NO fonts, NO shadows - layout structure only
+
+  ## Output Format
+  Return JSON object with layout_templates array.
+  Each template must include:
+  - target (string)
+  - variant_id (string, e.g., "layout-1")
+  - device_type (string)
+  - design_philosophy (string)
+  - dom_structure (JSON object)
+  - component_hierarchy (array of strings)
+  - css_layout_rules (string)
+
+  ## Notes
+  - Structure only, no visual styling
+  - Use var() for all spacing/sizing
+  - Layouts must be structurally distinct in explore mode
+  - Write complete layout-templates.json
+`
+```
+
+**Output**: Agent returns JSON with `layout_templates` array
+
+### Step 2: Write Output File
+```bash
+# Take JSON output from agent
+bash(echo '{agent_json_output}' > {base_path}/layout-extraction/layout-templates.json)
+
+# Verify output
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_templates" && echo "valid")
+```
+
+**Output**: `layout-templates.json` created and verified
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "Layout research (explore mode)", status: "completed", activeForm: "Researching layout patterns"},
+  {content: "Layout analysis and synthesis (agent)", status: "completed", activeForm: "Generating layout templates"},
+  {content: "Write layout-templates.json", status: "completed", activeForm: "Saving templates"}
+]});
+```
+
+### Output Message
+```
+✅ Layout extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (imitate/explore)
+- Device Type: {device_type}
+- Targets: {targets}
+- Variants per Target: {variants_count}
+- Total Templates: {targets.length × variants_count}
+
+{IF extraction_mode == "explore":
+Layout Research:
+- {targets.length} inspiration files generated
+- Pattern search focused on {device_type} layouts
+}
+
+Generated Templates:
+{FOR each template: - Target: {template.target} | Variant: {template.variant_id} | Philosophy: {template.design_philosophy}}
+
+Output File:
+- {base_path}/layout-extraction/layout-templates.json
+
+Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create output directories
+bash(mkdir -p {base_path}/layout-extraction)
+bash(mkdir -p {base_path}/layout-extraction/_inspirations)  # explore mode only
+```
+
+### Validation Commands
+```bash
+# Check if already extracted
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Validate JSON structure
+bash(cat layout-templates.json | grep -q "layout_templates" && echo "valid")
+
+# Count templates
+bash(cat layout-templates.json | grep -c "\"target\":")
+```
+
+### File Operations
+```bash
+# Load image references
+bash(ls {images_pattern})
+Read({image_path})
+
+# Write inspiration files (explore mode)
+Write({base_path}/layout-extraction/_inspirations/{target}-layout-ideas.txt, content)
+
+# Write layout templates
+bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
+```
+
+## Output Structure
+
+```
+{base_path}/
+└── layout-extraction/
+    ├── layout-templates.json         # Structural layout templates
+    ├── layout-space-analysis.json    # Layout directions (explore mode only)
+    └── _inspirations/                 # Explore mode only
+        └── {target}-layout-ideas.txt  # Layout inspiration research
+```
+
+## layout-templates.json Format
+
+```json
+{
+  "extraction_metadata": {
+    "session_id": "...",
+    "input_mode": "image|url|prompt|hybrid",
+    "extraction_mode": "imitate|explore",
+    "device_type": "desktop|mobile|tablet|responsive",
+    "timestamp": "...",
+    "variants_count": 3,
+    "targets": ["home", "dashboard"]
+  },
+  "layout_templates": [
+    {
+      "target": "home",
+      "variant_id": "layout-1",
+      "device_type": "responsive",
+      "design_philosophy": "Responsive 3-column holy grail layout with fixed header and footer",
+      "dom_structure": {
+        "tag": "body",
+        "children": [
+          {
+            "tag": "header",
+            "attributes": {"class": "layout-header"},
+            "children": [{"tag": "nav"}]
+          },
+          {
+            "tag": "div",
+            "attributes": {"class": "layout-main-wrapper"},
+            "children": [
+              {"tag": "main", "attributes": {"class": "layout-main-content"}},
+              {"tag": "aside", "attributes": {"class": "layout-sidebar-left"}},
+              {"tag": "aside", "attributes": {"class": "layout-sidebar-right"}}
+            ]
+          },
+          {"tag": "footer", "attributes": {"class": "layout-footer"}}
+        ]
+      },
+      "component_hierarchy": [
+        "header",
+        "main-content",
+        "sidebar-left",
+        "sidebar-right",
+        "footer"
+      ],
+      "css_layout_rules": ".layout-main-wrapper { display: grid; grid-template-columns: 1fr 3fr 1fr; gap: var(--spacing-6); } @media (max-width: var(--breakpoint-md)) { .layout-main-wrapper { grid-template-columns: 1fr; } }"
+    }
+  ]
+}
+```
+
+**Requirements**: Token-based CSS (var()), semantic HTML5, device-specific structure, accessibility attributes
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No inputs provided
+→ Provide --images, --urls, or --prompt
+
+ERROR: Invalid target name
+→ Use lowercase, alphanumeric, hyphens only
+
+ERROR: Agent task failed
+→ Check agent output, retry with simplified prompt
+
+ERROR: MCP search failed (explore mode)
+→ Check network, retry
+```
+
+### Recovery Strategies
+- **Partial success**: Keep successfully extracted templates
+- **Invalid JSON**: Retry with stricter format requirements
+- **Missing inspiration**: Works without (less informed exploration)
+
+## Key Features
+
+- **Separation of Concerns** - Decouples layout (structure) from style (visuals)
+- **Structural Exploration** - Explore mode enables A/B testing of different layouts
+- **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
+- **Device-Specific** - Tailored structures for different screen sizes
+- **Foundation for Assembly** - Provides structural blueprint for refactored `generate` command
+- **Agent-Powered** - Deep structural analysis with AI
+
+## Integration
+
+**Workflow Position**: Between style extraction and prototype generation
+
+**New Workflow**:
+1. `/workflow:ui-design:style-extract` → `style-cards.json` (Visual tokens)
+2. `/workflow:ui-design:consolidate` → `design-tokens.json` (Final visual system)
+3. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
+4. `/workflow:ui-design:generate` (Refactored as assembler):
+   - **Reads**: `design-tokens.json` + `layout-templates.json`
+   - **Action**: For each style × layout combination:
+     1. Build HTML from `dom_structure`
+     2. Create layout CSS from `css_layout_rules`
+     3. Link design tokens CSS
+     4. Inject placeholder content
+   - **Output**: Complete token-driven HTML/CSS prototypes
+
+**Input**: Reference images, URLs, or text prompts
+**Output**: `layout-templates.json` for `/workflow:ui-design:generate`
+**Next**: `/workflow:ui-design:generate --session {session_id}`

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

@@ -0,0 +1,277 @@
+---
+name: style-extract
+description: Extract design style from reference images or text prompts using Claude's analysis
+usage: /workflow:ui-design:style-extract [--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]
+examples:
+  - /workflow:ui-design:style-extract --images "design-refs/*.png" --mode explore --variants 3
+  - /workflow:ui-design:style-extract --prompt "Modern minimalist blog, dark theme" --mode explore --variants 3
+  - /workflow:ui-design:style-extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --mode imitate
+  - /workflow:ui-design:style-extract --base-path ".workflow/WFS-auth/design-run-20250109-143022" --images "refs/*.png" --mode explore --variants 3
+  - /workflow:ui-design:style-extract --prompt "Bold vibrant" --mode imitate  # High-fidelity single style
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
+---
+
+# Style Extraction Command
+
+## Overview
+Extract design style from reference images or text prompts using Claude's built-in analysis. Generates `style-cards.json` with multiple design variants containing token proposals for consolidation.
+
+**Strategy**: AI-Driven Design Space Exploration
+- **Claude-Native**: 100% Claude analysis, no external tools
+- **Single Output**: `style-cards.json` with embedded token proposals
+- **Flexible Input**: Images, text prompts, or both (hybrid mode)
+- **Maximum Contrast**: AI generates maximally divergent design directions
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input Mode, Extraction Mode & Base Path
+```bash
+# Detect input source
+# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
+
+# Determine extraction mode
+# Priority: --mode parameter → default "imitate"
+extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+
+# Set variants count based on mode
+IF extraction_mode == "imitate":
+    variants_count = 1  # Force single variant for imitate mode (ignore --variants)
+ELSE IF extraction_mode == "explore":
+    variants_count = --variants OR 3  # Default to 3 for explore mode
+    VALIDATE: 1 <= variants_count <= 5
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Inputs
+```bash
+# For image mode
+bash(ls {images_pattern})  # Expand glob pattern
+Read({image_path})  # Load each image
+
+# For text mode
+# Validate --prompt is non-empty
+
+# Create output directory
+bash(mkdir -p {base_path}/style-extraction/)
+```
+
+### Step 3: Memory Check (Skip if Already Done)
+```bash
+# Check if already extracted
+bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
+```
+
+**If exists**: Skip to completion message
+
+**Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`
+
+## Phase 1: Design Space Analysis (Explore Mode Only)
+
+### Step 1: Check Extraction Mode
+```bash
+# Check extraction mode
+# extraction_mode == "imitate" → skip this phase
+# extraction_mode == "explore" → execute this phase
+```
+
+**If imitate mode**: Skip to Phase 2
+
+### Step 2: Load Project Context (Explore Mode)
+```bash
+# Load brainstorming context if available
+bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
+```
+
+### Step 3: Generate Divergent Directions (Claude Native)
+AI analyzes requirements and generates `variants_count` maximally contrasting design directions:
+
+**Input**: User prompt + project context + image count
+**Analysis**: 6D attribute space (color saturation, visual weight, formality, organic/geometric, innovation, density)
+**Output**: JSON with divergent_directions, each having:
+- philosophy_name (2-3 words)
+- design_attributes (specific scores)
+- search_keywords (3-5 keywords)
+- anti_keywords (2-3 keywords)
+- rationale (contrast explanation)
+
+### Step 4: Write Design Space Analysis
+```bash
+bash(echo '{design_space_analysis}' > {base_path}/style-extraction/design-space-analysis.json)
+
+# Verify output
+bash(test -f design-space-analysis.json && echo "saved")
+```
+
+**Output**: `design-space-analysis.json` for consolidation phase
+
+## Phase 2: Style Synthesis & File Write
+
+### Step 1: Claude Native Analysis
+AI generates `variants_count` design style proposals:
+
+**Input**:
+- Input mode (image/text/hybrid)
+- Visual references or text guidance
+- Design space analysis (explore mode only)
+- Variant-specific directions (explore mode only)
+
+**Analysis Rules**:
+- **Explore mode**: Each variant follows pre-defined philosophy and attributes, maintains maximum contrast
+- **Imitate mode**: High-fidelity replication of reference design
+- OKLCH color format
+- Complete token proposals (colors, typography, spacing, border_radius, shadows, breakpoints)
+- WCAG AA accessibility (4.5:1 text, 3:1 UI)
+
+**Output Format**: `style-cards.json` with:
+- extraction_metadata (session_id, input_mode, extraction_mode, timestamp, variants_count)
+- style_cards[] (id, name, description, design_philosophy, preview, proposed_tokens)
+
+### Step 2: Write Style Cards
+```bash
+bash(echo '{style_cards_json}' > {base_path}/style-extraction/style-cards.json)
+```
+
+**Output**: `style-cards.json` with `variants_count` complete variants
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "Design space analysis (explore mode)", status: "completed", activeForm: "Analyzing design space"},
+  {content: "Style synthesis and file write", status: "completed", activeForm: "Generating style cards"}
+]});
+```
+
+### Output Message
+```
+✅ Style extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (imitate/explore)
+- Input Mode: {input_mode} (image/text/hybrid)
+- Variants: {variants_count}
+
+{IF extraction_mode == "explore":
+Design Space Analysis:
+- {variants_count} maximally contrasting design directions
+- Min contrast distance: {design_space_analysis.contrast_verification.min_pairwise_distance}
+}
+
+Generated Variants:
+{FOR each card: - {card.name} - {card.design_philosophy}}
+
+Output Files:
+- {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}
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Expand image pattern
+bash(ls {images_pattern})
+
+# Create output directory
+bash(mkdir -p {base_path}/style-extraction/)
+```
+
+### Validation Commands
+```bash
+# Check if already extracted
+bash(test -f {base_path}/style-extraction/style-cards.json && echo "exists")
+
+# Count variants
+bash(cat style-cards.json | grep -c "\"id\": \"variant-")
+
+# Validate JSON
+bash(cat style-cards.json | grep -q "extraction_metadata" && echo "valid")
+```
+
+### File Operations
+```bash
+# Load brainstorming context
+bash(test -f .brainstorming/synthesis-specification.md && cat it)
+
+# Write output
+bash(echo '{json}' > {base_path}/style-extraction/style-cards.json)
+
+# Verify output
+bash(test -f design-space-analysis.json && echo "saved")
+```
+
+## Output Structure
+
+```
+{base_path}/style-extraction/
+├── style-cards.json              # Complete style variants with token proposals
+└── design-space-analysis.json    # Design directions (explore mode only)
+```
+
+## style-cards.json Format
+
+```json
+{
+  "extraction_metadata": {"session_id": "...", "input_mode": "image|text|hybrid", "extraction_mode": "imitate|explore", "timestamp": "...", "variants_count": N},
+  "style_cards": [
+    {
+      "id": "variant-1", "name": "Style Name", "description": "...",
+      "design_philosophy": "Core principles",
+      "preview": {"primary": "oklch(...)", "background": "oklch(...)", "font_heading": "...", "border_radius": "..."},
+      "proposed_tokens": {
+        "colors": {"brand": {...}, "surface": {...}, "semantic": {...}, "text": {...}, "border": {...}},
+        "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+        "spacing": {"0": "0", ..., "24": "6rem"},
+        "border_radius": {"none": "0", ..., "full": "9999px"},
+        "shadows": {"sm": "...", ..., "xl": "..."},
+        "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
+      }
+    }
+    // Repeat for all variants
+  ]
+}
+```
+
+**Requirements**: All colors in OKLCH format, complete token proposals, semantic naming
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No images found
+→ Check glob pattern
+
+ERROR: Invalid prompt
+→ Provide non-empty string
+
+ERROR: Claude JSON parsing error
+→ Retry with stricter format
+```
+
+## Key Features
+
+- **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
+- **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
+- **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
+- **Claude-Native** - No external tools, fast deterministic synthesis
+- **Flexible Input** - Images, text, or hybrid mode
+- **Production-Ready** - OKLCH colors, WCAG AA, semantic naming
+
+## Integration
+
+**Input**: Reference images or text prompts
+**Output**: `style-cards.json` for consolidation
+**Next**: `/workflow:ui-design:consolidate --session {session_id} --variants {count}`
+
+**Note**: This command only extracts visual style (colors, typography, spacing). For layout structure extraction, use `/workflow:ui-design:layout-extract`.

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

@@ -0,0 +1,287 @@
+---
+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 1.1: Memory Check (Skip if Already Updated)
+
+```bash
+# Check if synthesis-specification.md contains current design run reference
+synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/synthesis-specification.md"
+current_design_run = basename(latest_design)  # e.g., "design-run-20250109-143022"
+
+IF exists(synthesis_spec_path):
+    synthesis_content = Read(synthesis_spec_path)
+    IF "## UI/UX Guidelines" in synthesis_content AND current_design_run in synthesis_content:
+        REPORT: "✅ Design system references already updated (found in memory)"
+        REPORT: "   Skipping: Phase 2-5 (Load Target Artifacts, Update Synthesis, Update UI Designer Guide, Completion)"
+        EXIT 0
+```
+
+### 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/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.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.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/version.json

@@ -1,7 +0,0 @@
-{
-  "version": "3.4.0",
-  "installation_mode": "Local",
-  "installation_path": "D:\\Claude_dms3\\.claude",
-  "source_branch": "main",
-  "installation_date_utc": "2025-10-04T00:00:00Z"
-}

.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/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 (primary)
+- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
+- **Codex**: Development, implementation & automation
 
 ### Decision Principles
 - **Use tools early and often** - Tools are faster, more thorough, and reliable than manual approaches
@@ -21,67 +32,89 @@ type: strategic-guideline
 - **⚠️ 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
-2. **Architecture/Code generation?** → Start with Qwen
+1. **Exploring/Understanding?** → Start with Gemini (fallback to Qwen if needed)
+2. **Architecture/Analysis?** → Start with Gemini (fallback to Qwen if needed)
 3. **Building/Fixing?** → Start with Codex
 4. **Not sure?** → Use multiple tools in parallel
 5. **Small task?** → Still use tools - they're faster than manual work
 
-### 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
-- **Codex Write Access**: Use `-s danger-full-access` and `--skip-git-repo-check` ONLY when MODE=auto explicitly specified
-- **Default Behavior**: All tools default to analysis/read-only mode without explicit write permission
+## 🎯 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)
-```bash
-# Gemini Analysis (read/write capable)
-cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [clear analysis goal]
-TASK: [specific analysis task]
-MODE: [analysis|write]
-CONTEXT: [file references and memory context]
-EXPECTED: [expected output]
-RULES: [template reference and constraints]
-"
+#### MODE Options
+- `analysis` (default) - Read-only analysis and documentation generation
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
 
-# Qwen Architecture Analysis (read-only analysis)
-cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [clear architecture goal]
-TASK: [specific analysis task]
-MODE: analysis
-CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
-RULES: [template reference and constraints]
-"
+### Qwen
+- **Command**: `~/.claude/scripts/qwen-wrapper`
+- **Strengths**: Large context window, pattern recognition (same as Gemini)
+- **Best For**: Analysis, documentation generation, code exploration (fallback option when Gemini unavailable)
+- **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
+- **Priority**: Secondary to Gemini - use as fallback for same tasks
 
-# Codex Development
-codex -C [directory] --full-auto exec "
-PURPOSE: [clear development goal]
-TASK: [specific development task]
-MODE: [auto|write]
-CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
-RULES: [template reference and constraints]
-" --skip-git-repo-check -s danger-full-access
-```
+#### MODE Options
+- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini)
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
 
-### Template Structure
+### 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
@@ -89,24 +122,82 @@ RULES: [template reference and constraints]
 - [ ] **EXPECTED** - Clear expected results
 - [ ] **RULES** - Template reference and constraints
 
-### MODE Field Definition
+### Standard Command Formats
 
-The MODE field controls execution behavior and file permissions:
+#### Gemini Commands
+```bash
+# Gemini Analysis (read-only, default)
+cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: [clear analysis goal]
+TASK: [specific analysis task]
+MODE: analysis
+CONTEXT: [file references and memory context]
+EXPECTED: [expected output]
+RULES: [template reference and constraints]
+"
 
-**For Gemini**:
-- `analysis` (default) - Read-only analysis and documentation generation
-- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
+# 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]
+"
+```
 
-**For Qwen**:
-- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
-- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
+#### Qwen Commands
+```bash
+# Qwen Analysis (read-only, default) - Same as Gemini, use as fallback
+cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
+PURPOSE: [clear analysis goal]
+TASK: [specific analysis task]
+MODE: analysis
+CONTEXT: [file references and memory context]
+EXPECTED: [expected output]
+RULES: [template reference and constraints]
+"
 
-**For Codex**:
-- `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
+# 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 output]
+RULES: [template reference and constraints]
+"
+```
 
-### Directory Context
+#### 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
+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
+```
+
+### 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"`
@@ -114,7 +205,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]
 ```
@@ -125,24 +216,60 @@ 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 |
 |-----------|------|----------|-----------|
-| **Analysis** | Gemini | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
-| **Architecture** | Qwen | System design, code generation, architectural analysis | `analysis/architecture.txt` |
-| **Code Generation** | Qwen | Implementation patterns, code scaffolding, component creation | `development/feature.txt` |
+| **Analysis** | Gemini (Qwen fallback) | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
+| **Architecture** | Gemini (Qwen fallback) | System design, architectural analysis | `analysis/architecture.txt` |
+| **Documentation** | Gemini (Qwen fallback) | Code docs, API specs, guides | `analysis/quality.txt` |
 | **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` |
-| **Planning** | Multiple | Task breakdown, migration planning | `planning/task-breakdown.txt` |
-| **Documentation** | Multiple | Code docs, API specs, guides | `analysis/quality.txt` |
+| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` |
 | **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
-| **Refactoring** | Multiple | Gemini for analysis, Qwen/Codex for execution | `development/refactor.txt` |
+| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` |
 
-## 📁 Template System
+### Template System
 
 **Base Structure**: `~/.claude/workflows/cli-templates/`
 
-### Available Templates
+#### Available Templates
 ```
 prompts/
 ├── analysis/
@@ -168,19 +295,22 @@ tech-stacks/
 └── react-dev.md         - React architecture
 ```
 
+---
+
 ## 🚀 Usage Patterns
 
 ### Workflow Integration (REQUIRED)
 When planning any coding task, **ALWAYS** integrate CLI tools:
 
-1. **Understanding Phase**: Use Gemini for analysis
-2. **Architecture Phase**: Use Qwen for design and code generation
-3. **Implementation Phase**: Use Qwen/Codex for development
+1. **Understanding Phase**: Use Gemini for analysis (Qwen as fallback)
+2. **Architecture Phase**: Use Gemini for design and analysis (Qwen as fallback)
+3. **Implementation Phase**: Use Codex for development
 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
@@ -189,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
@@ -199,9 +331,12 @@ CONTEXT: @{src/api/**/*}
 EXPECTED: API.md with all endpoints documented
 RULES: Follow project documentation standards
 "
+```
 
-# Qwen - Architecture Analysis
-cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
+#### Architecture Analysis (Qwen as Gemini fallback)
+```bash
+# Prefer Gemini for architecture analysis
+cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: Analyze authentication system architecture
 TASK: Review JWT-based auth system design
 MODE: analysis
@@ -210,7 +345,20 @@ EXPECTED: Architecture analysis report with recommendations
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on security
 "
 
-# Codex - Feature Development
+# Use Qwen only if Gemini unavailable
+cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
+PURPOSE: Analyze authentication system architecture
+TASK: Review JWT-based auth system design
+MODE: analysis
+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
+"
+```
+
+#### 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
@@ -220,74 +368,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**: 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
-
-### 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
-
-### 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
-- **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
-
-### 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,7 +430,7 @@ EXPECTED: Pattern documentation
 RULES: Focus on security best practices
 "
 
-# Qwen - Architecture analysis
+# Qwen - Analysis (fallback option, same as Gemini)
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze auth architecture
 TASK: Review auth system design and patterns
@@ -329,4 +449,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

@@ -46,6 +46,30 @@ 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 fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
@@ -58,6 +82,9 @@ RULES: Build on previous subtask, maintain consistency
 - **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
 
@@ -335,6 +362,10 @@ Subtask 3: Add authentication (resume --last)
 
 ---
 
-**Version**: 2.1.0
+**Version**: 2.2.0
 **Last Updated**: 2025-10-04
-**Changes**: Added multi-step task execution support with resume mechanism
+**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

@@ -18,4 +18,6 @@ Thumbs.db
 
 .env
 settings.local.json
-.workflow
+.workflow
+version.json
+ref

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) {
@@ -638,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
@@ -1024,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() {
@@ -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.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.4.0-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,15 +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.4.0** - TDD workflow optimization & test generation enhancements. See [CHANGELOG.md](CHANGELOG.md) for details.
+> **🎉 Latest: v4.4.0** - UI Design Workflow V3 with Layout/Style Separation Architecture. See [CHANGELOG.md](CHANGELOG.md) for details.
 >
-> **What's New in v3.4.0**:
-> - 🧪 **TDD Workflow Streamlining**: Unified IMPL_PLAN.md structure, 33% reduction in redundant files
-> - 🔄 **Test Coverage Analysis**: TDD workflow upgraded to 6 phases with Phase 3 test context gathering
-> - 🔁 **Iterative Green Phase**: Built-in test-fix-cycle in IMPL tasks with Gemini auto-diagnosis
-> - 🛠️ **Manual-First Fixes**: Gemini + bug-fix template diagnosis by default, optional `--use-codex` automation
-> - ✅ **Test-Gen Workflow Enhancement**: Added 3 supporting tool commands for complete test generation flow
-> - ⏱️ **Dynamic Timeout Allocation**: CLI tools default to 20-120min for large-scale analysis
+> **What's New in v4.4.0**:
+> - 🏗️ **Layout/Style Separation**: New `layout-extract` command separates structure from visual tokens
+> - 📦 **Pure Assembler**: `generate` command now purely combines pre-extracted layouts + styles
+> - 🎯 **Better Variety**: Layout exploration generates structurally distinct designs
+> - ✅ **Single Responsibility**: Each phase (style, layout, assembly) has clear purpose
 
 ---
 
@@ -250,7 +248,33 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /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 (v4.4.0+)
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+/workflow:ui-design:consolidate --variants "variant-1,variant-3"
+/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
+/workflow:ui-design:generate --style-variants 1 --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"
@@ -259,7 +283,7 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:tdd-plan "Implement authentication with test-first development"
 ```
 
-**Phase 3: Execution**
+**Phase 4: Execution**
 ```bash
 # Execute tasks with AI agents
 /workflow:execute
@@ -268,7 +292,7 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /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
@@ -341,6 +365,13 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 |---|---|
 | `/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.4.0** Matrix exploration mode - Generate multiple style × layout variants with layout/style separation. |
+| `/workflow:ui-design:imitate-auto` | **v4.4.0** Fast imitation mode - Rapid UI replication with auto-screenshot, layout extraction, and assembly. |
+| `/workflow:ui-design:style-extract` | **v4.4.0** Extract visual style (colors, typography, spacing) from images/text using Claude-native analysis. |
+| `/workflow:ui-design:layout-extract` | **v4.4.0** Extract structural layout (DOM, CSS layout rules) with device-aware templates. |
+| `/workflow:ui-design:consolidate` | **v4.4.0** Consolidate style variants into validated design tokens using Claude synthesis. |
+| `/workflow:ui-design:generate` | **v4.4.0** Pure assembler - Combine layout templates + design tokens → HTML/CSS prototypes. |
+| `/workflow:ui-design:update` | **v4.4.0** Integrate finalized design system into brainstorming artifacts. |
 | `/workflow:plan` | Create a detailed, executable plan from a description. |
 | `/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. |
@@ -352,6 +383,145 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 | `/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.4.0)*
+
+The design workflow system provides complete UI design refinement with **layout/style separation architecture**, **pure Claude execution**, **intelligent target 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:style-extract`** - Visual style extraction (v4.4.0)
+```bash
+# Pure text prompt
+/workflow:ui-design:style-extract --prompt "Modern minimalist, dark theme" --mode explore --variants 3
+
+# Pure images
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# Hybrid (text guides image analysis)
+/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app style" --mode imitate
+
+# High-fidelity single style
+/workflow:ui-design:style-extract --images "design.png" --mode imitate
+```
+- **🎨 Visual Tokens Only**: Colors, typography, spacing (no layout structure)
+- **🔄 Dual Mode**: Imitate (single variant) / Explore (multiple variants)
+- **Claude-Native**: Single-pass analysis, no external tools
+- **Output**: `style-cards.json` with embedded `proposed_tokens`
+
+**`/workflow:ui-design:layout-extract`** - Structural layout extraction (v4.4.0)
+```bash
+# Explore mode - multiple layout variants
+/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive
+
+# Imitate mode - single layout replication
+/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop
+
+# With MCP research (explore mode)
+/workflow:ui-design:layout-extract --prompt "E-commerce checkout" --targets "cart,checkout" --mode explore --variants 2
+```
+- **🏗️ Structure Only**: DOM hierarchy, CSS layout rules (no visual style)
+- **📱 Device-Aware**: Desktop, mobile, tablet, responsive optimizations
+- **🧠 Agent-Powered**: Uses ui-design-agent for structural analysis
+- **🔍 MCP Research**: Layout pattern inspiration (explore mode)
+- **Output**: `layout-templates.json` with token-based CSS
+
+**`/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`** - Pure assembler (v4.4.0)
+```bash
+# Combine layout templates + design tokens
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
+
+# Multiple styles with multiple layouts
+/workflow:ui-design:generate --style-variants 2 --layout-variants 3
+```
+- **📦 Pure Assembly**: Combines pre-extracted layout-templates.json + design-tokens.json
+- **❌ No Design Logic**: All layout/style decisions made in previous phases
+- **✅ Token Resolution**: Replaces var() placeholders with actual token values
+- **🎯 Matrix Output**: Generates style × layout × targets prototypes
+- **🔍 Interactive Preview**: `compare.html` with side-by-side comparison
+
+**`/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**
 
 | Command | Description |

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v3.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v4.3.0-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,15 +15,13 @@
 
 **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
 
-> **🎉 最新版本: v3.4.0** - TDD 工作流优化与测试生成增强。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v4.3.0** - UI 设计工作流 V2 自包含 CSS 架构。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v3.4.0 版本新特性**:
-> - 🧪 **TDD 工作流优化**: 精简文件结构，统一使用 IMPL_PLAN.md，减少 33% 冗余文件
-> - 🔄 **测试覆盖分析**: TDD 工作流升级至 6 阶段，新增 Phase 3 测试上下文收集
-> - 🔁 **迭代 Green Phase**: IMPL 任务内置 test-fix-cycle，支持 Gemini 自动诊断和修复
-> - 🛠️ **手动优先修复**: 默认使用 Gemini + bug-fix 模板诊断，可选 `--use-codex` 自动化
-> - ✅ **test-gen 工作流增强**: 新增 3 个配套工具命令，完整测试生成和修复流程
-> - ⏱️ **动态超时分配**: CLI 工具默认 20-120 分钟超时，适应大型项目分析
+> **v4.3.0 版本新特性**:
+> - 🎨 **自包含 CSS**: Agent 从 design-tokens.json 直接生成独立 CSS
+> - ⚡ **简化工作流**: 移除占位符机制和令牌转换步骤
+> - 💪 **更强风格差异**: CSS 使用直接令牌值，实现更强视觉区分
+> - 📉 **代码减少 31%**: 移除 346 行代码，职责更清晰
 
 ---
 
@@ -250,7 +248,32 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /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 的认证系统"
@@ -259,7 +282,7 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:tdd-plan "使用测试优先开发实现认证"
 ```
 
-**阶段 3：执行**
+**阶段 4：执行**
 ```bash
 # 使用 AI 智能体执行任务
 /workflow:execute
@@ -268,7 +291,7 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:status
 ```
 
-**阶段 4：测试与质量保证**
+**阶段 5：测试与质量保证**
 ```bash
 # 生成独立测试修复工作流（v3.2.2+）
 /workflow:test-gen WFS-auth  # 创建 WFS-test-auth 会话
@@ -341,6 +364,12 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 |---|---|
 | `/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` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
 | `/workflow:execute` | 自主执行当前的工作流计划。 |
@@ -352,6 +381,108 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 | `/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`: 带视口控制的并排对比（桌面/平板/移动）
+- 同步滚动用于布局对比
+- 动态页面切换
+- 实时响应式测试
+
+---
+
 ### **任务与内存命令**
 
 | 命令 | 描述 |

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
@@ -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

@@ -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
@@ -632,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. ✅ 提供清晰的用户指南
+
+**预期效果**：
+- 🔒 杜绝参数不匹配问题
+- 📈 提高工作流鲁棒性
+- 🎓 降低用户学习成本
+- 🚀 提升整体用户体验