Release v4.4.1: Implementation approach structure refactoring

- Refactor implementation_approach from object to array format
- Add step-based execution with dependency management
- Add CLI execution mode support with --cli-execute flag
- Add Codex resume mechanism for context continuity
- Update 15 files across agents, commands, and core architecture
- Major docs.md refactoring (67% size reduction)
- Enhanced workflow-architecture.md with flow control documentation

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

@@ -142,37 +142,6 @@ mcp__exa__get_code_context_exa(
 }
 ```
 
-**Legacy Pre-Execution Analysis** (backward compatibility):
-- **Multi-step Pre-Analysis**: Execute comprehensive analysis BEFORE implementation begins
-  - **Sequential Processing**: Process each step sequentially, expanding brief actions
-  - **Template Usage**: Use full template paths with $(cat template_path)
-  - **Method Selection**: gemini/codex/manual/auto-detected
-- **CLI Commands**:
-  - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [action]")`
-  - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [action]" -s danger-full-access)`
-- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md 
-
-### Pre-Execution Analysis
-**When [MULTI_STEP_ANALYSIS] marker is present:**
-
-#### Multi-Step Pre-Analysis Execution
-1. Process each analysis step sequentially from pre_analysis array
-2. For each step:
-   - Expand brief action into comprehensive analysis task
-   - Use specified template with $(cat template_path)
-   - Execute with specified method (gemini/codex/manual/auto-detected)
-3. Accumulate results across all steps for comprehensive context
-4. Use consolidated analysis to inform implementation stages and task breakdown
-
-#### Analysis Dimensions Coverage
-- **Exa Research**: Use `mcp__exa__get_code_context_exa` for technology stack selection and API patterns
-- Architecture patterns and component relationships
-- Implementation conventions and coding standards
-- Module dependencies and integration points
-- Testing requirements and coverage patterns
-- Security considerations and performance implications
-3. Use Codex insights to create self-guided implementation stages
-
 ## Core Functions
 
 ### 1. Stage Design
@@ -222,11 +191,26 @@ Generate individual `.task/IMPL-*.json` files with:
         "output_to": "codebase_structure"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement following synthesis specification",
-      "modification_points": ["Apply requirements"],
-      "logic_flow": ["Load spec", "Analyze", "Implement", "Validate"]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Load and analyze synthesis specification",
+        "description": "Load synthesis specification from artifacts and extract requirements",
+        "modification_points": ["Load synthesis specification", "Extract requirements and design patterns"],
+        "logic_flow": ["Read synthesis specification from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
+        "depends_on": [],
+        "output": "synthesis_requirements"
+      },
+      {
+        "step": 2,
+        "title": "Implement following specification",
+        "description": "Implement task requirements following consolidated synthesis specification",
+        "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
+        "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
+        "depends_on": [1],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }

.claude/agents/code-developer.md

@@ -90,6 +90,32 @@ ELIF context insufficient OR task has flow control marker:
 - Get API examples: `mcp__exa__get_code_context_exa(query="React authentication hooks", tokensNum="dynamic")`
 - Update after changes: `mcp__code-index__refresh_index()`
 
+**Implementation Approach Execution**:
+When task JSON contains `flow_control.implementation_approach` array:
+1. **Sequential Processing**: Execute steps in order, respecting `depends_on` dependencies
+2. **Dependency Resolution**: Wait for all steps listed in `depends_on` before starting
+3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
+4. **Step Structure**:
+   - `step`: Unique identifier (1, 2, 3...)
+   - `title`: Step title
+   - `description`: Detailed description with variable references
+   - `modification_points`: Code modification targets
+   - `logic_flow`: Business logic sequence
+   - `command`: Optional CLI command (only when explicitly specified)
+   - `depends_on`: Array of step numbers that must complete first
+   - `output`: Variable name for this step's output
+5. **Execution Rules**:
+   - Execute step 1 first (typically has `depends_on: []`)
+   - For each subsequent step, verify all `depends_on` steps completed
+   - Substitute `[variable_name]` with actual outputs from previous steps
+   - Store this step's result in the `output` variable for future steps
+   - If `command` field present, execute it; otherwise use agent capabilities
+
+**CLI Command Execution (CLI Execute Mode)**:
+When step contains `command` field with Codex CLI, execute via Bash tool. For Codex resume:
+- First task (`depends_on: []`): `codex -C [path] --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
+- Subsequent tasks (has `depends_on`): Add `resume --last` flag to maintain session context
+
 **Test-Driven Development**:
 - Write tests first (red → green → refactor)
 - Focus on core functionality and edge cases

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

@@ -83,6 +83,54 @@ def handle_brainstorm_assignment(prompt):
         generate_brainstorm_analysis(role, context_vars, output_location, topic)
 ```
 
+## Flow Control Format Handling
+
+This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm workflows.
+
+### Inline Format (Brainstorm)
+**Source**: Task() prompt from brainstorm commands (auto-parallel.md, etc.)
+
+**Structure**: Markdown list format (3-5 steps)
+
+**Example**:
+```markdown
+[FLOW_CONTROL]
+
+### Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Output: topic_framework
+
+2. **load_role_template**
+   - Action: Load role-specific planning template
+   - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
+   - Output: role_template
+
+3. **load_session_metadata**
+   - Action: Load session metadata
+   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json)
+   - Output: session_metadata
+```
+
+**Characteristics**:
+- 3-5 simple context loading steps
+- Written directly in prompt (not persistent)
+- No dependency management
+- Used for temporary context preparation
+
+### NOT Handled by This Agent
+
+**JSON format** (used by code-developer, test-fix-agent):
+```json
+"flow_control": {
+  "pre_analysis": [...],
+  "implementation_approach": [...]
+}
+```
+
+This complete JSON format is stored in `.task/IMPL-*.json` files and handled by implementation agents, not conceptual-planning-agent.
+
 ### Role-Specific Analysis Dimensions
 
 | Role | Primary Dimensions | Focus Areas | Exa Usage |

.claude/agents/doc-generator.md

@@ -68,8 +68,17 @@ You are an expert technical documentation specialist. Your responsibility is to
 
 ### 3. Documentation Generation
 - **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation.
-- **Instructions**: Follow the `implementation_approach` defined in the `flow_control` block.
-- **Templates**: Apply templates as specified in `meta.template` or `implementation_approach`.
+- **Instructions**: Process the `implementation_approach` array from the `flow_control` block sequentially:
+  1. **Array Structure**: `implementation_approach` is an array of step objects
+  2. **Sequential Execution**: Execute steps in order, respecting `depends_on` dependencies
+  3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
+  4. **Step Processing**:
+     - Verify all `depends_on` steps completed before starting
+     - Follow `modification_points` and `logic_flow` for each step
+     - Execute `command` if present, otherwise use agent capabilities
+     - Store result in `output` variable for future steps
+  5. **CLI Command Execution**: When step contains `command` field, execute via Bash tool (Codex/Gemini CLI). For Codex with dependencies, use `resume --last` flag.
+- **Templates**: Apply templates as specified in `meta.template` or step-level templates.
 - **Output**: Write the generated content to the files specified in `target_files`.
 
 ### 4. Progress Tracking with TodoWrite

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

@@ -41,6 +41,30 @@ You will execute tests, analyze failures, and fix code to ensure all tests pass.
 
 ## Execution Process
 
+### Flow Control Execution
+When task JSON contains `flow_control` field, execute preparation and implementation steps systematically.
+
+**Pre-Analysis Steps** (`flow_control.pre_analysis`):
+1. **Sequential Processing**: Execute steps in order, accumulating context
+2. **Variable Substitution**: Use `[variable_name]` to reference previous outputs
+3. **Error Handling**: Follow step-specific strategies (`skip_optional`, `fail`, `retry_once`)
+
+**Implementation Approach** (`flow_control.implementation_approach`):
+When task JSON contains implementation_approach array:
+1. **Sequential Execution**: Process steps in order, respecting `depends_on` dependencies
+2. **Dependency Resolution**: Wait for all steps listed in `depends_on` before starting
+3. **Variable References**: Use `[variable_name]` to reference outputs from previous steps
+4. **Step Structure**:
+   - `step`: Step number (1, 2, 3...)
+   - `title`: Step title
+   - `description`: Detailed description with variable references
+   - `modification_points`: Test and code modification targets
+   - `logic_flow`: Test-fix iteration sequence
+   - `command`: Optional CLI command (only when explicitly specified)
+   - `depends_on`: Array of step numbers that must complete first
+   - `output`: Variable name for this step's output
+
+
 ### 1. Context Assessment & Test Discovery
 - Analyze task context to identify test files and source code paths
 - Load test framework configuration (Jest, Pytest, Mocha, etc.)
@@ -61,16 +85,34 @@ fi
 - Parse test results to identify failures
 
 ### 3. Failure Diagnosis & Fixing Loop
+
+**Execution Modes**:
+
+**A. Manual Mode (Default, meta.use_codex=false)**:
 ```
-WHILE tests are failing:
-    1. Analyze failure output
-    2. Identify root cause in source code
-    3. Modify source code to fix issue
-    4. Re-run affected tests
+WHILE tests are failing AND iterations < max_iterations:
+    1. Use Gemini to diagnose failure (bug-fix template)
+    2. Present fix recommendations to user
+    3. User applies fixes manually
+    4. Re-run test suite
     5. Verify fix doesn't break other tests
 END WHILE
 ```
 
+**B. Codex Mode (meta.use_codex=true)**:
+```
+WHILE tests are failing AND iterations < max_iterations:
+    1. Use Gemini to diagnose failure (bug-fix template)
+    2. Use Codex to apply fixes automatically with resume mechanism
+    3. Re-run test suite
+    4. Verify fix doesn't break other tests
+END WHILE
+```
+
+**Codex Resume in Test-Fix Cycle** (when `meta.use_codex=true`):
+- First iteration: Start new Codex session with full context
+- Subsequent iterations: Use `resume --last` to maintain fix history and apply consistent strategies
+
 ### 4. Code Quality Certification
 - All tests pass → Code is APPROVED ✅
 - Generate summary documenting:

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

@@ -12,7 +12,6 @@ description: |
 
   Integration points:
   - Exa MCP: Design trend research, modern UI patterns, implementation best practices
-  - Code Index MCP: Codebase pattern discovery, existing implementation analysis
 
 color: orange
 ---
@@ -33,25 +32,13 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 - `layout-strategies.json`: MCP-researched layout variant definitions
 - `tokens.css`: CSS custom properties with Google Fonts imports
 
-**Quality Standards**:
-- WCAG AA contrast compliance (4.5:1 text, 3:1 UI)
-- Complete token coverage (colors, typography, spacing, radius, shadows, breakpoints)
-- Semantic naming conventions
-- OKLCH color format for all color values
-
 ### 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
+**Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends)
 
-**Process**:
-- Query Exa MCP for modern UI layout trends (2024-2025)
-- Extract project type and tech stack context
-- Generate 3-5 layout strategies with semantic names
-- Document rationale and application guidelines
-
-**Output**: layout-strategies.json with strategy definitions
+**Output**: layout-strategies.json with strategy definitions and rationale
 
 ### 3. UI Prototype Generation
 
@@ -70,13 +57,40 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 - `{target}-layout-{id}.html`: Style-agnostic HTML structure
 - `{target}-layout-{id}.css`: Token-driven structural CSS
 
-**Quality Standards**:
-- 🎯 **ADAPTIVE**: Multi-device responsive (375px+, 768px+, 1024px+)
-- 🔄 **STYLE-SWITCHABLE**: Runtime theme switching via token swapping
-- 🏗️ **SEMANTIC**: HTML5 structure with proper element hierarchy
-- ♿ **ACCESSIBLE**: ARIA attributes for WCAG AA compliance
-- 📱 **MOBILE-FIRST**: Progressive enhancement approach
-- 🎨 **TOKEN-DRIVEN**: Zero hardcoded values
+**⚠️ 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
 
@@ -84,11 +98,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 **Input**: Multiple target prototypes for same style/layout combination
 **Task**: Validate cross-target design consistency
 
-**Deliverables**:
-- Consistency reports identifying shared component variations
-- Token usage verification
-- Accessibility compliance checks
-- Layout strategy adherence validation
+**Deliverables**: Consistency reports, token usage verification, accessibility compliance checks, layout strategy adherence validation
 
 ## Design Standards
 
@@ -215,8 +225,104 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 - 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:
@@ -272,15 +378,17 @@ You are invoked by orchestrator commands to execute specific generation tasks:
 
 ### Performance Optimization
 
-**Two-Layer Generation**:
-- **Layer 1**: Generate style-agnostic templates (creative, expensive)
-- **Layer 2**: Instantiate style-specific prototypes (fast file operations)
-- **Performance gain**: S× faster (S = style variant count)
+**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
 
-**Script Integration**:
-- `convert_tokens_to_css.sh`: Token JSON → CSS conversion (~200ms)
-- `ui-instantiate-prototypes.sh`: Template instantiation (~5-10s for full matrix)
-- Auto-detection of configuration from directory structure
+**Your Focus**: Generate high-quality, reusable templates. Orchestrator handles file operations and instantiation.
 
 ### Scope & Boundaries
 
@@ -305,60 +413,35 @@ You are invoked by orchestrator commands to execute specific generation tasks:
 **Exa MCP: Design Research & Trends**
 
 *Use Cases*:
-1. **Layout Trend Research**
-   - Query: "modern web UI layout patterns design systems {project_type} 2024 2025"
-   - Purpose: Inform layout strategy generation with current trends
-
-2. **Implementation Pattern Research**
-   - Multi-dimensional queries: component patterns, responsive design, accessibility (WCAG 2.2), HTML semantics, CSS architecture
-   - Purpose: Inform template generation with modern best practices
+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 `tokensNum="dynamic"` for token efficiency
+- 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
-// Generic pattern
-research_results = mcp__exa__get_code_context_exa(
-  query="specific topic + context + year range",
-  tokensNum="dynamic"
-)
-
-// Web search for trends
+// Design trend research
 trend_results = mcp__exa__web_search_exa(
-  query="UI design trends {domain} 2024",
+  query="modern UI design color palette trends {domain} 2024 2025",
   numResults=5
 )
-```
 
-**Code Index MCP: Pattern Discovery**
-
-*Use Cases*:
-1. **Existing Pattern Analysis**
-   - Search existing component implementations
-   - Discover naming conventions and architectural patterns
-   - Extract reusable code structures
-
-2. **File Discovery & Verification**
-   - Find generated template files
-   - Verify output structure completeness
-   - Validate file organization
-
-*Tool Usage*:
-```javascript
-// Find patterns
-patterns = mcp__code-index__search_code_advanced(
-  pattern="component.*interface|class.*Component",
-  file_pattern="*.{tsx,jsx,ts,js}"
+// Accessibility research
+accessibility_results = mcp__exa__web_search_exa(
+  query="WCAG 2.2 accessibility contrast patterns best practices 2024",
+  numResults=5
 )
 
-// Discover files
-templates = mcp__code-index__find_files(pattern="*template*.{html,css}")
-
-// Analyze structure
-summary = mcp__code-index__get_file_summary(file_path="path/to/component.tsx")
+// Layout pattern research
+layout_results = mcp__exa__web_search_exa(
+  query="modern web layout design systems responsive patterns 2024",
+  numResults=5
+)
 ```
 
 ### Tool Operations
@@ -390,54 +473,6 @@ summary = mcp__code-index__get_file_summary(file_path="path/to/component.tsx")
   ✅ Written: style-1/style-guide.md (8.3 KB)
   ```
 
-**Script Execution**:
-```bash
-# Token conversion
-cat design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css
-
-# Prototype instantiation
-~/.claude/scripts/ui-instantiate-prototypes.sh {prototypes_dir} \
-  --session-id {id} \
-  --mode {page|component}
-```
-
-**Agent Delegation Pattern**:
-```javascript
-Task(ui-design-agent): "
-  [TASK_TYPE_IDENTIFIER]
-
-  Clear task description with context and requirements
-
-  ## Context
-  - Key parameters and input files
-  - Quality standards and constraints
-  - BASE_PATH: {absolute_path_to_output_directory}
-
-  ## File Write Instructions
-  Generate and WRITE files directly using Write() tool:
-
-  1. File 1:
-     Path: {absolute_path}/file1.json
-     Content: [specification]
-
-  2. File 2:
-     Path: {absolute_path}/file2.md
-     Content: [specification]
-
-  ## Instructions
-  - Use Write() tool for each file with provided absolute paths
-  - Create directories if needed: Bash('mkdir -p {directory}')
-  - Verify each write operation succeeds
-  - Report completion with file paths and sizes
-
-  ## Expected Final Report
-  ✅ Written: file1.json (12.5 KB)
-  ✅ Written: file2.md (8.3 KB)
-
-  DO NOT return file contents as text - write them directly to the file system.
-"
-```
-
 ## Quality Assurance
 
 ### Validation Checks
@@ -504,86 +539,50 @@ Task(ui-design-agent): "
    - Recovery: Adjust OKLCH lightness (L) channel, regenerate tokens
    - Prevention: Test contrast ratios during token generation
 
-## Reference
+## Key Reminders
 
-### Token System Reference
+### ALWAYS:
 
-**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`
+**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
 
-**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
+**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)
 
-**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)
+**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
 
-**CSS Generation Pattern**:
-```css
-:root {
-  /* Colors (OKLCH) */
-  --primary: oklch(0.5555 0.15 270);
-  --background: oklch(1.0000 0 0);
+### NEVER:
 
-  /* Typography */
-  --font-sans: 'Inter', system-ui, sans-serif;
+**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
 
-  /* Visual Effects */
-  --radius: 0.5rem;
-  --shadow-sm: 0 1px 3px 0 hsl(0 0% 0% / 0.1);
-  --spacing: 0.25rem;
-}
+**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
 
-/* 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);
-}
-```
-
-### Version & Changelog
-
-**Version**: 4.2.0
-**Last Updated**: 2025-10-09
-
-**Changelog**:
-- **4.2.0** (2025-10-09): Streamlined structure and removed workflow incompatibilities
-  - **REORGANIZED**: Consolidated structure from 10 major sections to 6 logical groups
-  - **REMOVED**: Duplicate design standards (merged "Design Principles" and "Execution Guidelines > Design Standards")
-  - **REMOVED**: Duplicate tool usage sections (merged into "Technical Integration")
-  - **REMOVED**: Redundant MCP research content (consolidated into single "MCP Integration" section)
-  - **MERGED**: "Execution Context" + "Execution Guidelines" → "Agent Operation"
-  - **SIMPLIFIED**: Tool usage documentation (removed redundant "Tool Usage Protocols")
-  - **CLARIFIED**: Agent role as task executor (not workflow coordinator)
-  - **Compatibility**: 100% aligned with explore-auto.md and generate.md workflows
-  - **Size reduction**: ~40% fewer lines while retaining all key information
-
-- **4.1.0** (2025-10-09): Integrated design.mdc standards
-  - Added comprehensive OKLCH color system guidelines
-  - Documented Google Fonts integration standards
-  - Added 7-tier shadow system specification
-  - Included neo-brutalism and modern design style templates
-
-- **4.0.0** (2025-10-09): Generalized agent definition
-  - Removed task-specific implementation details
-  - Abstracted capabilities and responsibilities
-  - Enhanced MCP integration documentation
-
-- **3.0.0** (2025-10-09): Task-focused architecture
-  - Added consolidate.md and generate.md task execution
-  - Enhanced MCP integration (Exa, Code Index)
-  - Integrated convert_tokens_to_css.sh and ui-instantiate-prototypes.sh
+**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

@@ -1,12 +1,7 @@
 ---
 name: analyze
 description: Quick codebase analysis using CLI tools (codex/gemini/qwen)
-usage: /cli:analyze [--tool <codex|gemini|qwen>] [--enhance] <analysis-target>
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
-examples:
-  - /cli:analyze "authentication patterns"
-  - /cli:analyze --tool qwen "API security"
-  - /cli:analyze --tool codex --enhance "performance bottlenecks"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
 

.claude/commands/cli/chat.md

@@ -1,12 +1,7 @@
 ---
 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"
-examples:
-  - /cli:chat "analyze the authentication flow"
-  - /cli:chat --tool qwen --enhance "optimize React component"
-  - /cli:chat --tool codex "review security vulnerabilities"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

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

@@ -1,13 +1,7 @@
 ---
 name: cli-init
 description: Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis
-usage: /cli:cli-init [--tool <gemini|qwen|all>] [--output=<path>] [--preview]
 argument-hint: "[--tool gemini|qwen|all] [--output path] [--preview]"
-examples:
-  - /cli:cli-init
-  - /cli:cli-init --tool qwen
-  - /cli:cli-init --tool all --preview
-  - /cli:cli-init --output=.config/
 allowed-tools: Bash(*), Read(*), Write(*), Glob(*)
 ---
 
@@ -452,4 +446,4 @@ docker-compose.override.yml
 | **Gemini-only workflow** | `/cli:cli-init --tool gemini` | Creates .gemini/ and .geminiignore only |
 | **Qwen-only workflow** | `/cli:cli-init --tool qwen` | Creates .qwen/ and .qwenignore only |
 | **Preview before commit** | `/cli:cli-init --preview` | Shows what would be generated |
-| **Update configurations** | `/cli:cli-init` | Regenerates all files with backups |
+| **Update configurations** | `/cli:cli-init` | Regenerates all files with backups |

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

@@ -1,12 +1,7 @@
 ---
 name: codex-execute
 description: Automated task decomposition and execution with Codex using resume mechanism
-usage: /cli:codex-execute [--verify-git] <task-description|task-id>
 argument-hint: "[--verify-git] task description or task-id"
-examples:
-  - /cli:codex-execute "implement user authentication system"
-  - /cli:codex-execute --verify-git "refactor API layer"
-  - /cli:codex-execute IMPL-001
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
 

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

@@ -0,0 +1,308 @@
+---
+name: discuss-plan
+description: Orchestrates an iterative, multi-model discussion for planning and analysis without implementation.
+argument-hint: "[--topic '...'] [--task-id '...'] [--rounds N]"
+allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
+---
+
+# CLI Discuss-Plan Command (/cli:discuss-plan)
+
+## Purpose
+
+Orchestrates a multi-model collaborative discussion for in-depth planning and problem analysis. This command facilitates an iterative dialogue between Gemini, Codex, and Claude (the orchestrating AI) to explore a topic from multiple perspectives, refine ideas, and build a robust plan.
+
+**This command is for discussion and planning ONLY. It does NOT modify any code.**
+
+## Core Workflow: The Discussion Loop
+
+The command operates in iterative rounds, allowing the plan to evolve with each cycle. The user can choose to continue for more rounds or conclude when consensus is reached.
+
+```
+Topic Input → [Round 1: Gemini → Codex → Claude] → [User Review] →
+[Round 2: Gemini → Codex → Claude] → ... → Final Plan
+```
+
+### Model Roles & Priority
+
+**Priority Order**: Gemini > Codex > Claude
+
+1.  **Gemini (The Analyst)** - Priority 1
+    - Kicks off each round with deep analysis
+    - Provides foundational ideas and draft plans
+    - Analyzes current context or previous synthesis
+
+2.  **Codex (The Architect/Critic)** - Priority 2
+    - Reviews Gemini's output critically
+    - Uses deep reasoning for technical trade-offs
+    - Proposes alternative strategies
+    - **Participates purely in conversational/reasoning capacity**
+    - Uses resume mechanism to maintain discussion context
+
+3.  **Claude (The Synthesizer/Moderator)** - Priority 3
+    - Synthesizes discussion from Gemini and Codex
+    - Highlights agreements and contentions
+    - Structures refined plan
+    - Poses key questions for next round
+
+## Parameters
+
+-   `<input>` (Required): Topic description or task ID (e.g., "Design a new caching layer" or `PLAN-002`)
+-   `--rounds <N>` (Optional): Maximum number of discussion rounds (default: prompts after each round)
+-   `--task-id <id>` (Optional): Associates discussion with workflow task ID
+-   `--topic <description>` (Optional): High-level topic for discussion
+
+## Execution Flow
+
+### Phase 1: Initial Setup
+
+1.  **Input Processing**: Parse topic or task ID
+2.  **Context Gathering**: Identify relevant files based on topic
+
+### Phase 2: Discussion Round
+
+Each round consists of three sequential steps, tracked via `TodoWrite`.
+
+**Step 1: Gemini's Analysis (Priority 1)**
+
+Gemini analyzes the topic and proposes preliminary plan.
+
+```bash
+# Round 1: CONTEXT_INPUT is the initial topic
+# Subsequent rounds: CONTEXT_INPUT is the synthesis from previous round
+~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze and propose a plan for '[topic]'
+TASK: Provide initial analysis, identify key modules, and draft implementation plan
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected files]
+INPUT: [CONTEXT_INPUT]
+EXPECTED: Structured analysis and draft plan for discussion
+RULES: Focus on technical depth and practical considerations
+"
+```
+
+**Step 2: Codex's Critique (Priority 2)**
+
+Codex reviews Gemini's output using conversational reasoning. Uses `resume --last` to maintain context across rounds.
+
+```bash
+# First round (new session)
+codex chat "
+PURPOSE: Critically review technical plan
+TASK: Review the provided plan, identify weaknesses, suggest alternatives, reason about trade-offs
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [relevant files]
+INPUT_PLAN: [Output from Gemini's analysis]
+EXPECTED: Critical review with alternative ideas and risk analysis
+RULES: Focus on architectural soundness and implementation feasibility
+"
+
+# Subsequent rounds (resume discussion)
+codex chat "
+PURPOSE: Re-evaluate plan based on latest synthesis
+TASK: Review updated plan and discussion points, provide further critique or refined ideas
+MODE: analysis
+CONTEXT: Previous discussion context (maintained via resume)
+INPUT_PLAN: [Output from Gemini's analysis for current round]
+EXPECTED: Updated critique building on previous discussion
+RULES: Build on previous insights, avoid repeating points
+" resume --last
+```
+
+**Step 3: Claude's Synthesis (Priority 3)**
+
+Claude (orchestrating AI) synthesizes both outputs:
+
+-   Summarizes Gemini's proposal and Codex's critique
+-   Highlights agreements and disagreements
+-   Structures consolidated plan
+-   Presents open questions for next round
+-   This synthesis becomes input for next round
+
+### Phase 3: User Review and Iteration
+
+1.  **Present Synthesis**: Show synthesized plan and key discussion points
+2.  **Continue or Conclude**: Prompt user:
+    - **(1)** Start another round of discussion
+    - **(2)** Conclude and finalize the plan
+3.  **Loop or Finalize**:
+    -   Continue → New round with Gemini analyzing latest synthesis
+    -   Conclude → Save final synthesized document
+
+## TodoWrite Tracking
+
+Progress tracked for each round and model.
+
+```javascript
+// Example for 2-round discussion
+TodoWrite({
+  todos: [
+    // Round 1
+    { content: "[Round 1] Gemini: Analyzing topic", status: "completed", activeForm: "Analyzing with Gemini" },
+    { content: "[Round 1] Codex: Critiquing plan", status: "completed", activeForm: "Critiquing with Codex" },
+    { content: "[Round 1] Claude: Synthesizing discussion", status: "completed", activeForm: "Synthesizing discussion" },
+    { content: "[User Action] Review Round 1 and decide next step", status: "in_progress", activeForm: "Awaiting user decision" },
+
+    // Round 2
+    { content: "[Round 2] Gemini: Analyzing refined plan", status: "pending", activeForm: "Analyzing refined plan" },
+    { content: "[Round 2] Codex: Re-evaluating plan [resume]", status: "pending", activeForm: "Re-evaluating with Codex" },
+    { content: "[Round 2] Claude: Finalizing plan", status: "pending", activeForm: "Finalizing plan" },
+    { content: "Discussion complete - Final plan generated", status: "pending", activeForm: "Generating final document" }
+  ]
+})
+```
+
+## Output Routing
+
+-   **Primary Log**: Entire multi-round discussion logged to single file:
+    -   `.workflow/WFS-[id]/.chat/discuss-plan-[topic]-[timestamp].md`
+-   **Final Plan**: Clean final version saved upon conclusion:
+    -   `.workflow/WFS-[id]/.summaries/plan-[topic].md`
+-   **Scratchpad**: If no session active:
+    -   `.workflow/.scratchpad/discuss-plan-[topic]-[timestamp].md`
+
+## Discussion Structure
+
+Each round's output is structured as:
+
+```markdown
+## Round N: [Topic]
+
+### Gemini's Analysis (Priority 1)
+[Gemini's full analysis and proposal]
+
+### Codex's Critique (Priority 2)
+[Codex's critical review and alternatives]
+
+### Claude's Synthesis (Priority 3)
+**Points of Agreement:**
+- [Agreement 1]
+- [Agreement 2]
+
+**Points of Contention:**
+- [Issue 1]: Gemini suggests X, Codex suggests Y
+- [Issue 2]: Trade-off between A and B
+
+**Consolidated Plan:**
+[Structured plan incorporating both perspectives]
+
+**Open Questions for Next Round:**
+1. [Question 1]
+2. [Question 2]
+```
+
+## Examples
+
+### Example 1: Multi-Round Architecture Discussion
+
+**Command**: `/cli:discuss-plan --topic "Design a real-time notification system"`
+
+**Round 1**:
+1.  **Gemini**: Proposes WebSocket-based architecture with RabbitMQ message queue
+2.  **Codex**: Critiques as overly complex for MVP. Suggests Server-Sent Events (SSE) for simplicity (one-way notifications). Questions RabbitMQ necessity, proposes simpler Redis Pub/Sub
+3.  **Claude**: Synthesizes views:
+    -   **Plan A (Gemini)**: WebSockets + RabbitMQ (highly scalable, complex)
+    -   **Plan B (Codex)**: SSE + Redis (simpler, less overhead)
+    -   **Open Question**: Is bi-directional communication critical, or is simplicity priority?
+4.  **User Action**: Opts for another round to explore trade-offs
+
+**Round 2**:
+1.  **Gemini**: Analyzes synthesized document. Notes that if features like "user is typing" indicators are roadmapped, WebSockets better long-term. Drafts plan starting with SSE/Redis but designing for easy migration
+2.  **Codex**: Reviews migration plan. Reasons that migration itself could be complex. If feature set likely to expand, starting with WebSockets using managed service might be best cost/benefit
+3.  **Claude**: Synthesizes new discussion:
+    -   **Consensus**: Simple SSE/Redis too short-sighted
+    -   **Refined Options**:
+        1.  Phased approach (SSE → WebSocket) with clear migration plan
+        2.  Direct WebSocket with managed service (Pusher, Ably) to reduce ops overhead
+    -   **Recommendation**: Option 2 most robust and future-proof
+4.  **User Action**: Agrees with recommendation, concludes discussion
+
+**Final Output**: Planning document saved with:
+- Chosen architecture (Managed WebSocket service)
+- Multi-round reasoning
+- High-level implementation steps
+
+### Example 2: Feature Design Discussion
+
+**Command**: `/cli:discuss-plan --topic "Design user permission system" --rounds 2`
+
+**Round 1**:
+1.  **Gemini**: Proposes RBAC (Role-Based Access Control) with predefined roles
+2.  **Codex**: Suggests ABAC (Attribute-Based Access Control) for more flexibility
+3.  **Claude**: Synthesizes trade-offs between simplicity (RBAC) vs flexibility (ABAC)
+
+**Round 2**:
+1.  **Gemini**: Analyzes hybrid approach - RBAC for core permissions, attributes for fine-grained control
+2.  **Codex**: Reviews hybrid model, identifies implementation challenges
+3.  **Claude**: Final plan with phased rollout strategy
+
+**Automatic Conclusion**: Command concludes after 2 rounds as specified
+
+### Example 3: Problem-Solving Discussion
+
+**Command**: `/cli:discuss-plan --topic "Debug memory leak in data pipeline" --task-id ISSUE-042`
+
+**Round 1**:
+1.  **Gemini**: Identifies potential leak sources (unclosed handles, growing cache, event listeners)
+2.  **Codex**: Adds profiling tool recommendations, suggests memory monitoring
+3.  **Claude**: Structures debugging plan with phased approach
+
+**User Decision**: Single round sufficient, concludes with debugging strategy
+
+## Consensus Mechanisms
+
+**When to Continue:**
+- Significant disagreement between models
+- Open questions requiring deeper analysis
+- Trade-offs need more exploration
+- User wants additional perspectives
+
+**When to Conclude:**
+- Models converge on solution
+- All key questions addressed
+- User satisfied with plan depth
+- Maximum rounds reached (if specified)
+
+## Comparison with Other Commands
+
+| Command | Models | Rounds | Discussion | Implementation | Use Case |
+|---------|--------|--------|------------|----------------|----------|
+| `/cli:mode:plan` | Gemini | 1 | ❌ NO | ❌ NO | Single-model planning |
+| `/cli:analyze` | Gemini/Qwen | 1 | ❌ NO | ❌ NO | Code analysis |
+| `/cli:execute` | Any | 1 | ❌ NO | ✅ YES | Direct implementation |
+| `/cli:codex-execute` | Codex | 1 | ❌ NO | ✅ YES | Multi-stage implementation |
+| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | ✅ **YES** | ❌ **NO** | **Multi-perspective planning** |
+
+## Best Practices
+
+1.  **Use for Complex Decisions**: Ideal for architectural decisions, design trade-offs, problem-solving
+2.  **Start with Broad Topic**: Let first round establish scope, subsequent rounds refine
+3.  **Review Each Synthesis**: Claude's synthesis is key decision point - review carefully
+4.  **Know When to Stop**: Don't over-iterate - 2-3 rounds usually sufficient
+5.  **Task Association**: Use `--task-id` for traceability in workflow
+6.  **Save Intermediate Results**: Each round's synthesis saved automatically
+7.  **Let Models Disagree**: Divergent views often reveal important trade-offs
+8.  **Focus Questions**: Use Claude's open questions to guide next round
+
+## Breaking Discussion Loops
+
+**Detecting Loops:**
+- Models repeating same arguments
+- No new insights emerging
+- Trade-offs well understood
+
+**Breaking Strategies:**
+1.  **User Decision**: Make executive decision when enough info gathered
+2.  **Timeboxing**: Set max rounds upfront with `--rounds`
+3.  **Criteria-Based**: Define decision criteria before starting
+4.  **Hybrid Approach**: Accept multiple valid solutions in final plan
+
+## Notes
+
+-   **Pure Discussion**: This command NEVER modifies code - only produces planning documents
+-   **Codex Role**: Codex participates as reasoning/critique tool, not executor
+-   **Resume Context**: Codex maintains discussion context via `resume --last`
+-   **Priority System**: Ensures Gemini leads analysis, Codex provides critique, Claude synthesizes
+-   **Output Quality**: Multi-perspective discussion produces more robust plans than single-model analysis
+-   Command patterns and session management: see intelligent-tools-strategy.md (loaded in memory)
+-   Output routing details: see workflow-architecture.md
+-   For implementation after discussion, use `/cli:execute` or `/cli:codex-execute` separately

.claude/commands/cli/execute.md

@@ -1,13 +1,7 @@
 ---
 name: execute
 description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
-usage: /cli:execute [--tool <codex|gemini|qwen>] [--enhance] <description|task-id>
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
-examples:
-  - /cli:execute "implement user authentication system"
-  - /cli:execute --tool qwen --enhance "optimize React component"
-  - /cli:execute --tool codex IMPL-001
-  - /cli:execute --enhance "fix API performance issues"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: bug-index
 description: Bug analysis and fix suggestions using CLI tools
-usage: /cli:mode:bug-index [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "bug description"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
-examples:
-  - /cli:mode:bug-index "authentication null pointer error"
-  - /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(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: code-analysis
 description: Deep code analysis and debugging using CLI tools with specialized template
-usage: /cli:mode:code-analysis [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "analysis target"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
-examples:
-  - /cli:mode:code-analysis "analyze authentication flow logic"
-  - /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(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: plan
 description: Project planning and architecture analysis using CLI tools
-usage: /cli:mode:plan [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "topic"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
-examples:
-  - /cli:mode:plan "design user dashboard"
-  - /cli:mode:plan --tool qwen --enhance "plan microservices migration"
-  - /cli:mode:plan --tool codex --cd "src/auth" "authentication system"
 allowed-tools: SlashCommand(*), Bash(*)
 ---
 

.claude/commands/enhance-prompt.md

@@ -1,12 +1,7 @@
 ---
 name: enhance-prompt
 description: Context-aware prompt enhancement using session memory and codebase analysis
-usage: /enhance-prompt <user_input>
 argument-hint: "user input to enhance"
-examples:
-  - /enhance-prompt "add user profile editing"
-  - /enhance-prompt "fix login button"
-  - /enhance-prompt "clean up the payment code"
 ---
 
 ## Overview

.claude/commands/task/breakdown.md

@@ -1,12 +1,7 @@
 ---
 name: breakdown
 description: Intelligent task decomposition with context-aware subtask generation
-usage: /task:breakdown <task-id>
-argument-hint: task-id
-examples:
-  - /task:breakdown IMPL-1
-  - /task:breakdown IMPL-1.1
-  - /task:breakdown impl-3
+argument-hint: "task-id"
 ---
 
 # Task Breakdown Command (/task:breakdown)

.claude/commands/task/create.md

@@ -1,12 +1,7 @@
 ---
 name: create
 description: Create implementation tasks with automatic context awareness
-usage: /task:create "title"
-argument-hint: "task title"
-examples:
-  - /task:create "Implement user authentication"
-  - /task:create "Build REST API endpoints"
-  - /task:create "Fix login validation bug"
+argument-hint: "\"task title\""
 ---
 
 # Task Create Command (/task:create)

.claude/commands/task/execute.md

@@ -1,12 +1,7 @@
 ---
 name: execute
 description: Execute tasks with appropriate agents and context-aware orchestration
-usage: /task:execute <task-id>
-argument-hint: task-id
-examples:
-  - /task:execute IMPL-1
-  - /task:execute IMPL-1.2
-  - /task:execute IMPL-3
+argument-hint: "task-id"
 ---
 
 ### 🚀 **Command Overview: `/task:execute`**

.claude/commands/task/replan.md

@@ -1,12 +1,7 @@
 ---
 name: replan
 description: Replan individual tasks with detailed user input and change tracking
-usage: /task:replan <task-id> [input]
-argument-hint: task-id ["text"|file.md|ISS-001]
-examples:
-  - /task:replan IMPL-1 "Add OAuth2 authentication support"
-  - /task:replan IMPL-1 updated-specs.md
-  - /task:replan IMPL-1 ISS-001
+argument-hint: "task-id [\"text\"|file.md]"
 ---
 
 # Task Replan Command (/task:replan)
@@ -38,12 +33,6 @@ Replans individual tasks with multiple input options, change tracking, and versi
 ```
 Supports: .md, .txt, .json, .yaml
 
-### Issue Reference
-```bash
-/task:replan IMPL-1 ISS-001
-```
-Loads issue description and requirements
-
 ### Interactive Mode
 ```bash
 /task:replan IMPL-1 --interactive

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

@@ -1,12 +1,7 @@
 ---
 name: update-memory-full
 description: Complete project-wide CLAUDE.md documentation update
-usage: /update-memory-full [--tool <gemini|qwen|codex>]
 argument-hint: "[--tool gemini|qwen|codex]"
-examples:
-  - /update-memory-full                      # Full project documentation update (gemini default)
-  - /update-memory-full --tool qwen          # Use Qwen for architecture analysis
-  - /update-memory-full --tool codex         # Use Codex for implementation validation
 ---
 
 ### 🚀 Command Overview: `/update-memory-full`

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

@@ -1,12 +1,7 @@
 ---
 name: update-memory-related
 description: Context-aware CLAUDE.md documentation updates based on recent changes
-usage: /update-memory-related [--tool <gemini|qwen|codex>]
 argument-hint: "[--tool gemini|qwen|codex]"
-examples:
-  - /update-memory-related                    # Update documentation based on recent changes (gemini default)
-  - /update-memory-related --tool qwen        # Use Qwen for architecture analysis
-  - /update-memory-related --tool codex       # Use Codex for implementation validation
 ---
 
 ### 🚀 Command Overview: `/update-memory-related`

.claude/commands/version.md

@@ -1,9 +1,6 @@
 ---
 name: version
 description: Display version information and check for updates
-usage: /version
-examples:
-  - /version
 allowed-tools: Bash(*)
 ---
 

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

@@ -1,11 +1,7 @@
 ---
 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
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: artifacts
 description: Generate role-specific topic-framework.md dynamically based on selected roles
-usage: /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
 argument-hint: "topic or challenge description for framework generation"
-examples:
-  - /workflow:brainstorm:artifacts "Build real-time collaboration feature"
-  - /workflow:brainstorm:artifacts "Optimize database performance" --roles "system-architect,data-architect,subject-matter-expert"
-  - /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,ux-expert,subject-matter-expert"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
@@ -368,4 +363,4 @@ ELSE:
 ### Integration Points
 - **Compatible with**: Other brainstorming commands in the same session
 - **Builds foundation for**: More detailed planning and implementation phases
-- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration
+- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration

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

@@ -1,12 +1,7 @@
 ---
 name: auto-parallel
 description: Parallel brainstorming automation with dynamic role selection and concurrent execution
-usage: /workflow:brainstorm:auto-parallel "<topic>"
 argument-hint: "topic or challenge description"
-examples:
-  - /workflow:brainstorm:auto-parallel "Build real-time collaboration feature"
-  - /workflow:brainstorm:auto-parallel "Optimize database performance for millions of users"
-  - /workflow:brainstorm:auto-parallel "Implement secure authentication system"
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
@@ -327,4 +322,4 @@ Command coordination model: artifacts command → parallel role analysis → syn
 - **Agent self-management**: Agents handle their own workflow and validation
 - **Concurrent operation**: No inter-agent dependencies enabling parallel execution
 - **Reference-based synthesis**: Post-processing integration without content duplication
-- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process
+- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process

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

@@ -1,12 +1,7 @@
 ---
 name: auto-squeeze
 description: Orchestrate 3-phase brainstorming workflow by executing commands sequentially
-usage: /workflow:brainstorm:auto-squeeze "<topic>"
 argument-hint: "topic or challenge description for coordinated brainstorming"
-examples:
-  - /workflow:brainstorm:auto-squeeze "Build real-time collaboration feature"
-  - /workflow:brainstorm:auto-squeeze "Optimize database performance for millions of users"
-  - /workflow:brainstorm:auto-squeeze "Implement secure authentication system"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
 ---
 
@@ -255,4 +250,4 @@ Return summary to user
 ✅ Update TodoWrite after each role completion
 ✅ Execute Phase 3 (synthesis) after all roles complete
 ✅ Validate synthesis-report.md exists
-✅ Return summary with all generated files
+✅ Return summary with all generated files

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

@@ -1,12 +1,7 @@
 ---
 name: data-architect
 description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:data-architect [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:data-architect
-  - /workflow:brainstorm:data-architect "user analytics data pipeline"
-  - /workflow:brainstorm:data-architect "real-time data processing system"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
@@ -202,4 +197,4 @@ TodoWrite({
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
 - **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,12 +1,7 @@
 ---
 name: product-manager
 description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:product-manager [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:product-manager
-  - /workflow:brainstorm:product-manager "user authentication redesign"
-  - /workflow:brainstorm:product-manager "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: product-owner
 description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:product-owner [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:product-owner
-  - /workflow:brainstorm:product-owner "user authentication redesign"
-  - /workflow:brainstorm:product-owner "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: scrum-master
 description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:scrum-master [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:scrum-master
-  - /workflow:brainstorm:scrum-master "user authentication redesign"
-  - /workflow:brainstorm:scrum-master "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

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

@@ -1,12 +1,7 @@
 ---
 name: subject-matter-expert
 description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:subject-matter-expert [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:subject-matter-expert
-  - /workflow:brainstorm:subject-matter-expert "user authentication redesign"
-  - /workflow:brainstorm:subject-matter-expert "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

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

@@ -1,10 +1,7 @@
 ---
 name: synthesis
 description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
-usage: /workflow:brainstorm:synthesis
 argument-hint: "no arguments required - synthesizes existing framework and role analyses"
-examples:
-  - /workflow:brainstorm:synthesis
 allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
 ---
 
@@ -497,4 +494,4 @@ If you want to skip verification and proceed directly:
 /workflow:execute --session WFS-{session-id}
 ```
 
-⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.
+⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

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

@@ -1,11 +1,7 @@
 ---
 name: system-architect
 description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:system-architect [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:system-architect
-  - /workflow:brainstorm:system-architect "user authentication redesign"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
@@ -369,4 +365,4 @@ System architect perspective provides:
 - [ ] **Resource Planning**: Resource requirements clearly defined and realistic
 - [ ] **Risk Management**: Technical risks identified with mitigation plans
 - [ ] **Performance Validation**: Architecture can meet performance requirements
-- [ ] **Evolution Strategy**: Design allows for future growth and changes
+- [ ] **Evolution Strategy**: Design allows for future growth and changes

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

@@ -1,12 +1,7 @@
 ---
 name: ui-designer
 description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:ui-designer [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:ui-designer
-  - /workflow:brainstorm:ui-designer "user authentication redesign"
-  - /workflow:brainstorm:ui-designer "mobile app navigation improvement"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
@@ -202,4 +197,4 @@ TodoWrite({
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
 - **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,12 +1,7 @@
 ---
 name: ux-expert
 description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:ux-expert [topic]
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:ux-expert
-  - /workflow:brainstorm:ux-expert "user authentication redesign"
-  - /workflow:brainstorm:ux-expert "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 

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

@@ -1,11 +1,7 @@
 ---
 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
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 

.claude/commands/workflow/execute.md

@@ -1,11 +1,7 @@
 ---
 name: execute
 description: Coordinate agents for existing workflow tasks with automatic discovery
-usage: /workflow:execute [--resume-session="session-id"]
-argument-hint: [--resume-session="session-id"]
-examples:
-  - /workflow:execute
-  - /workflow:execute --resume-session="WFS-user-auth"
+argument-hint: "[--resume-session=\"session-id\"]"
 ---
 
 # Workflow Execute Command
@@ -429,10 +425,28 @@ Task(subagent_type="{meta.agent}",
         "on_error": "skip_optional|fail|retry_once"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement following consolidated synthesis specification...",
-      "modification_points": ["Apply synthesis specification requirements..."]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following synthesis specification",
+        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from synthesis-specification.md",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load synthesis specification",
+          "Parse architecture and requirements",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }

.claude/commands/workflow/issue/close.md

@@ -1,142 +0,0 @@
----
-name: close
-description: Close a completed or obsolete workflow issue
-usage: /workflow:issue:close <issue-id> [reason]
-
-examples:
-  - /workflow:issue:close ISS-001
-  - /workflow:issue:close ISS-001 "Feature implemented in PR #42"
-  - /workflow:issue:close ISS-002 "Duplicate of ISS-001"
----
-
-# Close Workflow Issue (/workflow:issue:close)
-
-## Purpose
-Mark an issue as closed/resolved with optional reason documentation.
-
-## Usage
-```bash
-/workflow:issue:close <issue-id> ["reason"]
-```
-
-## Closing Process
-
-### Quick Close
-Simple closure without reason:
-```bash
-/workflow:issue:close ISS-001
-```
-
-### Close with Reason
-Include closure reason:
-```bash
-/workflow:issue:close ISS-001 "Feature implemented in PR #42"
-/workflow/issue/close ISS-002 "Duplicate of ISS-001"  
-/workflow/issue/close ISS-003 "No longer relevant"
-```
-
-### Interactive Close (Default)
-Without reason, prompts for details:
-```
-Closing Issue ISS-001: Add OAuth2 social login support
-Current Status: Open | Priority: High | Type: Feature
-
-Why is this issue being closed?
-1. ✅ Completed - Issue resolved successfully
-2. 🔄 Duplicate - Duplicate of another issue
-3. ❌ Invalid - Issue is invalid or not applicable  
-4. 🚫 Won't Fix - Decided not to implement
-5. 📝 Custom reason
-
-Choice: _
-```
-
-## Closure Categories
-
-### Completed (Default)
-- Issue was successfully resolved
-- Implementation finished
-- Requirements met
-- Ready for review/testing
-
-### Duplicate
-- Same as existing issue
-- Consolidated into another issue
-- Reference to primary issue provided
-
-### Invalid
-- Issue description unclear
-- Not a valid problem/request
-- Outside project scope
-- Misunderstanding resolved
-
-### Won't Fix
-- Decided not to implement
-- Business decision to decline
-- Technical constraints prevent
-- Priority too low
-
-### Custom Reason
-- Specific project context
-- Detailed explanation needed
-- Complex closure scenario
-
-## Closure Effects
-
-### Status Update
-- Changes status from "open" to "closed"
-- Records closure details
-- Saves closure reason and category
-
-### Integration Cleanup
-- Unlinks from workflow tasks (if integrated)
-- Removes from active TodoWrite items
-- Updates session statistics
-
-### History Preservation
-- Maintains full issue history
-- Records closure details
-- Preserves for future reference
-
-## Session Updates
-
-### Statistics
-Updates session issue counts:
-- Decrements open issues
-- Increments closed issues
-- Updates completion metrics
-
-### Progress Tracking
-- Updates workflow progress
-- Refreshes TodoWrite status
-- Updates session health metrics
-
-## Output
-Displays:
-- Issue closure confirmation
-- Closure reason and category
-- Updated session statistics  
-- Related actions taken
-
-## Reopening
-Closed issues can be reopened:
-```bash
-/workflow/issue/update ISS-001 --status=open
-```
-
-## Error Handling
-- **Issue not found**: Lists available open issues
-- **Already closed**: Shows current status and closure info
-- **Integration conflicts**: Handles task unlinking gracefully
-- **File errors**: Validates and repairs issue files
-
-## Archive Management
-Closed issues:
-- Remain in .issues/ directory
-- Are excluded from default listings
-- Can be viewed with `/workflow/issue/list --closed`
-- Maintain full searchability
-
----
-
-**Result**: Issue properly closed with documented reason and session cleanup

.claude/commands/workflow/issue/create.md

@@ -1,106 +0,0 @@
----
-name: create
-description: Create a new issue or change request
-usage: /workflow:issue:create "issue description"
-
-examples:
-  - /workflow:issue:create "Add OAuth2 social login support"
-  - /workflow:issue:create "Fix user avatar security vulnerability"
----
-
-# Create Workflow Issue (/workflow:issue:create)
-
-## Purpose
-Create a new issue or change request within the current workflow session.
-
-## Usage
-```bash
-/workflow:issue:create "issue description"
-```
-
-## Automatic Behavior
-
-### Issue ID Generation
-- Generates unique ID: ISS-001, ISS-002, etc.
-- Sequential numbering within session
-- Stored in session's .issues/ directory
-
-### Type Detection
-Automatically detects issue type from description:
-- **Bug**: Contains words like "fix", "error", "bug", "broken"
-- **Feature**: Contains words like "add", "implement", "create", "new"
-- **Optimization**: Contains words like "improve", "optimize", "performance"
-- **Documentation**: Contains words like "document", "readme", "docs"
-- **Refactor**: Contains words like "refactor", "cleanup", "restructure"
-
-### Priority Assessment
-Auto-assigns priority based on keywords:
-- **Critical**: "critical", "urgent", "blocker", "security"
-- **High**: "important", "major", "significant"
-- **Medium**: Default for most issues
-- **Low**: "minor", "enhancement", "nice-to-have"
-
-## Issue Storage
-
-### File Structure
-```
-.workflow/WFS-[session]/.issues/
-├── ISS-001.json          # Issue metadata
-├── ISS-002.json          # Another issue
-└── issue-registry.json   # Issue index
-```
-
-### Issue Metadata
-Each issue stores:
-```json
-{
-  "id": "ISS-001",
-  "title": "Add OAuth2 social login support",
-  "type": "feature",
-  "priority": "high",
-  "status": "open",
-  "created_at": "2025-09-08T10:00:00Z",
-  "category": "authentication",
-  "estimated_impact": "medium",
-  "blocking": false,
-  "session_id": "WFS-oauth-integration"
-}
-```
-
-## Session Integration
-
-### Active Session Check
-- Uses current active session (marker file)
-- Creates .issues/ directory if needed
-- Updates session's issue tracking
-
-### TodoWrite Integration
-Optionally adds to task list:
-- Creates todo for issue investigation
-- Links issue to implementation tasks
-- Updates progress tracking
-
-## Output
-Displays:
-- Generated issue ID
-- Detected type and priority
-- Storage location
-- Integration status
-- Quick actions available
-
-## Quick Actions
-After creation:
-- **View**: `/workflow:issue:list`
-- **Update**: `/workflow:issue:update ISS-001`
-- **Integrate**: Link to workflow tasks
-- **Close**: `/workflow:issue:close ISS-001`
-
-## Error Handling
-- **No active session**: Prompts to start session first
-- **Directory creation**: Handles permission issues
-- **Duplicate description**: Warns about similar issues
-- **Invalid description**: Prompts for meaningful description
-
----
-
-**Result**: New issue created and ready for management within workflow

.claude/commands/workflow/issue/list.md

@@ -1,104 +0,0 @@
----
-name: list
-description: List and filter workflow issues
-usage: /workflow:issue:list
-examples:
-  - /workflow:issue:list
-  - /workflow:issue:list --open
-  - /workflow:issue:list --priority=high
----
-
-# List Workflow Issues (/workflow:issue:list)
-
-## Purpose
-Display all issues and change requests within the current workflow session.
-
-## Usage
-```bash
-/workflow:issue:list [filter]
-```
-
-## Optional Filters
-Simple keyword-based filtering:
-```bash
-/workflow:issue:list --open           # Only open issues
-/workflow:issue:list --closed         # Only closed issues
-/workflow:issue:list --critical       # Critical priority
-/workflow:issue:list --high           # High priority
-/workflow:issue:list --bug            # Bug type issues
-/workflow:issue:list --feature        # Feature type issues
-/workflow:issue:list --blocking       # Blocking issues only
-```
-
-## Display Format
-
-### Open Issues
-```
-🔴 ISS-001: Add OAuth2 social login support
-   Type: Feature | Priority: High | Created: 2025-09-07
-   Status: Open | Impact: Medium
-   
-🔴 ISS-002: Fix user avatar security vulnerability  
-   Type: Bug | Priority: Critical | Created: 2025-09-08
-   Status: Open | Impact: High | 🚫 BLOCKING
-```
-
-### Closed Issues
-```
-✅ ISS-003: Update authentication documentation
-   Type: Documentation | Priority: Low
-   Status: Closed | Completed: 2025-09-05
-   Reason: Documentation updated in PR #45
-```
-
-### Integrated Issues
-```
-🔗 ISS-004: Implement rate limiting
-   Type: Feature | Priority: Medium
-   Status: Integrated → IMPL-003
-   Integrated: 2025-09-06 | Task: IMPL-3.json
-```
-
-## Summary Stats
-```
-📊 Issue Summary for WFS-oauth-integration:
-   Total: 4 issues
-   🔴 Open: 2 | ✅ Closed: 1 | 🔗 Integrated: 1
-   🚫 Blocking: 1 | ⚡ Critical: 1 | 📈 High: 1
-```
-
-## Empty State
-If no issues exist:
-```
-No issues found for current session.
-
-Create your first issue:
-/workflow:issue:create "describe the issue or request"
-```
-
-## Quick Actions
-For each issue, shows available actions:
-- **Update**: `/workflow:issue:update ISS-001`
-- **Integrate**: Link to workflow tasks  
-- **Close**: `/workflow:issue:close ISS-001`
-- **View Details**: Full issue information
-
-## Session Context
-- Lists issues from current active session
-- Shows session name and directory
-- Indicates if .issues/ directory exists
-
-## Sorting
-Issues are sorted by:
-1. Blocking status (blocking first)
-2. Priority (critical → high → medium → low)
-3. Creation date (newest first)
-
-## Performance
-- Fast loading from JSON files
-- Cached issue registry
-- Efficient filtering
-
----
-
-**Result**: Complete overview of all workflow issues with their current status

.claude/commands/workflow/issue/update.md

@@ -1,135 +0,0 @@
----
-name: update
-description: Update an existing workflow issue
-usage: /workflow:issue:update <issue-id> [changes]
-
-examples:
-  - /workflow:issue:update ISS-001
-  - /workflow:issue:update ISS-001 --priority=critical
-  - /workflow:issue:update ISS-001 --status=closed
----
-
-# Update Workflow Issue (/workflow:issue:update)
-
-## Purpose
-Modify attributes and status of an existing workflow issue.
-
-## Usage
-```bash
-/workflow:issue:update <issue-id> [options]
-```
-
-## Quick Updates
-Simple attribute changes:
-```bash
-/workflow:issue:update ISS-001 --priority=critical
-/workflow:issue:update ISS-001 --status=closed
-/workflow:issue:update ISS-001 --blocking
-/workflow:issue:update ISS-001 --type=bug
-```
-
-## Interactive Mode (Default)
-Without options, opens interactive editor:
-```
-Issue ISS-001: Add OAuth2 social login support
-Current Status: Open | Priority: High | Type: Feature
-
-What would you like to update?
-1. Status (open → closed/integrated)
-2. Priority (high → critical/medium/low)  
-3. Type (feature → bug/optimization/etc)
-4. Description
-5. Add comment
-6. Toggle blocking status
-7. Cancel
-
-Choice: _
-```
-
-## Available Updates
-
-### Status Changes
-- **open** → **closed**: Issue resolved
-- **open** → **integrated**: Linked to workflow task
-- **closed** → **open**: Reopen issue
-- **integrated** → **open**: Unlink from tasks
-
-### Priority Levels
-- **critical**: Urgent, blocking progress
-- **high**: Important, should address soon
-- **medium**: Standard priority
-- **low**: Nice-to-have, can defer
-
-### Issue Types  
-- **bug**: Something broken that needs fixing
-- **feature**: New functionality to implement
-- **optimization**: Performance or efficiency improvement
-- **refactor**: Code structure improvement
-- **documentation**: Documentation updates
-
-### Additional Options
-- **blocking/non-blocking**: Whether issue blocks progress
-- **description**: Update issue description
-- **comments**: Add notes and updates
-
-## Update Process
-
-### Validation
-- Verifies issue exists in current session
-- Checks valid status transitions
-- Validates priority and type values
-
-### Change Tracking
-- Records update details
-- Tracks who made changes
-- Maintains change history
-
-### File Updates
-- Updates ISS-XXX.json file
-- Refreshes issue-registry.json
-- Updates session statistics
-
-## Change History
-Maintains audit trail:
-```json
-{
-  "changes": [
-    {
-      "field": "priority",
-      "old_value": "high",
-      "new_value": "critical",
-      "reason": "Security implications discovered"
-    }
-  ]
-}
-```
-
-## Integration Effects
-
-### Task Integration
-When status changes to "integrated":
-- Links to workflow task (optional)
-- Updates task context with issue reference
-- Creates bidirectional linking
-
-### Session Updates
-- Updates session issue statistics
-- Refreshes TodoWrite if applicable
-- Updates workflow progress tracking
-
-## Output
-Shows:
-- What was changed
-- Before and after values
-- Integration status
-- Available next actions
-
-## Error Handling
-- **Issue not found**: Lists available issues
-- **Invalid status**: Shows valid transitions
-- **Permission errors**: Clear error messages
-- **File corruption**: Validates and repairs
-
----
-
-**Result**: Issue successfully updated with change tracking and integration

.claude/commands/workflow/plan.md

@@ -1,13 +1,7 @@
 ---
 name: plan
 description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
-usage: /workflow:plan [--agent] <input>
-argument-hint: "[--agent] \"text description\"|file.md|ISS-001"
-examples:
-  - /workflow:plan "Build authentication system"
-  - /workflow:plan --agent "Build authentication system"
-  - /workflow:plan requirements.md
-  - /workflow:plan ISS-001
+argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -36,6 +30,7 @@ This workflow runs **fully autonomously** once triggered. Each phase completes,
 **Execution Modes**:
 - **Manual Mode** (default): Use `/workflow:tools:task-generate`
 - **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
+- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
 
 ## Core Rules
 
@@ -124,9 +119,23 @@ CONTEXT: Existing user database schema, REST API endpoints
 - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
 - Task generation translates high-level specifications into concrete, actionable work items
 
-**Command**:
+**Command Selection**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
 - Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
+- CLI Execute: Add `--cli-execute` flag to either command
+
+**Flag Combination**:
+- `--cli-execute` alone: Manual task generation with CLI execution
+- `--agent --cli-execute`: Agent task generation with CLI execution
+
+**Command Examples**:
+```bash
+# Manual with CLI execution
+/workflow:tools:task-generate --session WFS-auth --cli-execute
+
+# Agent with CLI execution
+/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+```
 
 **Input**: `sessionId` from Phase 1
 
@@ -202,12 +211,6 @@ TodoWrite({todos: [
    - Extract goal, scope, requirements
    - Format into structured description
 
-4. **Issue Reference** (e.g., `ISS-001`) → Read and structure:
-   - Read issue file
-   - Extract title as goal
-   - Extract description as scope/context
-   - Format into structured description
-
 ## Data Flow
 
 ```
@@ -266,7 +269,10 @@ Return summary to user
 ✅ Parse context path from Phase 2 output, store in memory
 ✅ Pass session ID and context path to Phase 3 command
 ✅ Verify ANALYSIS_RESULTS.md after Phase 3
-✅ Select correct Phase 4 command based on --agent flag
+✅ **Build Phase 4 command** based on flags:
+  - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
+  - Add `--session [sessionId]`
+  - Add `--cli-execute` if flag present
 ✅ Pass session ID to Phase 4 command
 ✅ Verify all Phase 4 outputs
 ✅ Update TodoWrite after each phase
@@ -297,4 +303,4 @@ CONSTRAINTS: [Limitations or boundaries]
 
 # Phase 2
 /workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
-```
+```

.claude/commands/workflow/resume.md

@@ -1,12 +1,7 @@
 ---
 name: resume
 description: Intelligent workflow session resumption with automatic progress analysis
-usage: /workflow:resume "<session-id>"
 argument-hint: "session-id for workflow session to resume"
-examples:
-  - /workflow:resume "WFS-user-auth"
-  - /workflow:resume "WFS-api-integration"
-  - /workflow:resume "WFS-database-migration"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 

.claude/commands/workflow/review.md

@@ -1,13 +1,7 @@
 ---
 name: review
 description: Optional specialized review (security, architecture, docs) for completed implementation
-usage: /workflow:review [--type=<type>] [session-id]
-argument-hint: "[--type=security|architecture|action-items|quality] [session-id]"
-examples:
-  - /workflow:review                           # Quality review of active session
-  - /workflow:review --type=security           # Security audit of active session
-  - /workflow:review --type=architecture WFS-user-auth  # Architecture review of specific session
-  - /workflow:review --type=action-items       # Pre-deployment verification
+argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
 ---
 
 ### 🚀 Command Overview: `/workflow:review`

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

@@ -1,7 +1,6 @@
 ---
 name: complete
 description: Mark the active workflow session as complete and remove active flag
-usage: /workflow:session:complete
 examples:
   - /workflow:session:complete
   - /workflow:session:complete --detailed

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

@@ -1,7 +1,6 @@
 ---
 name: list
 description: List all workflow sessions with status
-usage: /workflow:session:list
 examples:
   - /workflow:session:list
 ---

.claude/commands/workflow/session/pause.md

@@ -1,69 +0,0 @@
----
-name: pause
-description: Pause the active workflow session
-usage: /workflow:session:pause
-examples:
-  - /workflow:session:pause
----
-
-# Pause Workflow Session (/workflow:session:pause)
-
-## Overview
-Pause the currently active workflow session, saving all state for later resumption.
-
-## Usage
-```bash
-/workflow:session:pause      # Pause current active session
-```
-
-## Implementation Flow
-
-### Step 1: Find Active Session
-```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-```
-
-### Step 2: Get Session Name
-```bash
-basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
-```
-
-### Step 3: Update Session Status
-```bash
-jq '.status = "paused"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
-```
-
-### Step 4: Add Pause Timestamp
-```bash
-jq '.paused_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
-```
-
-### Step 5: Remove Active Marker
-```bash
-rm .workflow/.active-WFS-session-name
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Find active session**: `ls .workflow/.active-*`
-- **Get session name**: `basename marker | sed 's/^\.active-//'`
-- **Update status**: `jq '.status = "paused"' session.json > temp.json`
-- **Add timestamp**: `jq '.paused_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Remove marker**: `rm .workflow/.active-session`
-
-### Pause Result
-```
-Session WFS-user-auth paused
-- Status: paused
-- Paused at: 2025-09-15T14:30:00Z
-- Tasks preserved: 8 tasks
-- Can resume with: /workflow:session:resume
-```
-
-## Related Commands
-- `/workflow:session:resume` - Resume paused session
-- `/workflow:session:list` - Show all sessions including paused
-- `/workflow:session:status` - Check session state

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

@@ -1,9 +1,6 @@
 ---
 name: resume
 description: Resume the most recently paused workflow session
-usage: /workflow:session:resume
-examples:
-  - /workflow:session:resume
 ---
 
 # Resume Workflow Session (/workflow:session:resume)

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

@@ -1,7 +1,6 @@
 ---
 name: start
 description: Discover existing sessions or start a new workflow session with intelligent session management
-usage: /workflow:session:start [--auto|--new] [task_description]
 argument-hint: [--auto|--new] [optional: task description for new session]
 examples:
   - /workflow:session:start

.claude/commands/workflow/session/switch.md

@@ -1,87 +0,0 @@
----
-name: switch
-description: Switch to a different workflow session
-usage: /workflow:session:switch <session-id>
-argument-hint: session-id to switch to
-examples:
-  - /workflow:session:switch WFS-oauth-integration
-  - /workflow:session:switch WFS-user-profile
----
-
-# Switch Workflow Session (/workflow:session:switch)
-
-## Overview
-Switch the active session to a different workflow session.
-
-## Usage
-```bash
-/workflow:session:switch WFS-session-name     # Switch to specific session
-```
-
-## Implementation Flow
-
-### Step 1: Validate Target Session
-```bash
-test -d .workflow/WFS-target-session && echo "Session exists"
-```
-
-### Step 2: Pause Current Session
-```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-jq '.status = "paused"' .workflow/current-session/workflow-session.json > temp.json
-```
-
-### Step 3: Remove Current Active Marker
-```bash
-rm .workflow/.active-* 2>/dev/null
-```
-
-### Step 4: Activate Target Session
-```bash
-jq '.status = "active"' .workflow/WFS-target/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-target/workflow-session.json
-```
-
-### Step 5: Create New Active Marker
-```bash
-touch .workflow/.active-WFS-target-session
-```
-
-### Step 6: Add Switch Timestamp
-```bash
-jq '.switched_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-target/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-target/workflow-session.json
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Check session exists**: `test -d .workflow/WFS-session`
-- **Find current active**: `ls .workflow/.active-*`
-- **Pause current**: `jq '.status = "paused"' session.json > temp.json`
-- **Remove marker**: `rm .workflow/.active-*`
-- **Activate target**: `jq '.status = "active"' target.json > temp.json`
-- **Create marker**: `touch .workflow/.active-target`
-
-### Switch Result
-```
-Switched to session: WFS-oauth-integration
-- Previous: WFS-user-auth (paused)
-- Current: WFS-oauth-integration (active)
-- Switched at: 2025-09-15T15:45:00Z
-- Ready for: /workflow:execute
-```
-
-### Error Handling
-```bash
-# Session not found
-test -d .workflow/WFS-nonexistent || echo "Error: Session not found"
-
-# No sessions available
-ls .workflow/WFS-* 2>/dev/null || echo "No sessions available"
-```
-
-## Related Commands
-- `/workflow:session:list` - Show all available sessions
-- `/workflow:session:pause` - Pause current before switching
-- `/workflow:execute` - Continue with new active session

.claude/commands/workflow/status.md

@@ -1,12 +1,7 @@
 ---
 name: workflow:status
 description: Generate on-demand views from JSON task data
-usage: /workflow:status [task-id]
-argument-hint: [optional: task-id]
-examples:
-  - /workflow:status
-  - /workflow:status impl-1
-  - /workflow:status --validate
+argument-hint: "[optional: task-id]"
 ---
 
 # Workflow Status Command (/workflow:status)

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

@@ -1,12 +1,7 @@
 ---
 name: tdd-plan
 description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
-usage: /workflow:tdd-plan [--agent] <input>
-argument-hint: "[--agent] \"feature description\"|file.md|ISS-001"
-examples:
-  - /workflow:tdd-plan "Implement user authentication"
-  - /workflow:tdd-plan --agent requirements.md
-  - /workflow:tdd-plan ISS-001
+argument-hint: "[--agent] \"feature description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 

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

@@ -1,11 +1,8 @@
 ---
 name: tdd-verify
 description: Verify TDD workflow compliance and generate quality report
-usage: /workflow:tdd-verify [session-id]
-argument-hint: "[WFS-session-id]"
-examples:
-  - /workflow:tdd-verify
-  - /workflow:tdd-verify WFS-auth
+
+argument-hint: "[optional: WFS-session-id]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
 ---
 

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

@@ -1,11 +1,7 @@
 ---
 name: test-gen
 description: Create independent test-fix workflow session by analyzing completed implementation
-usage: /workflow:test-gen [--use-codex] <source-session-id>
-argument-hint: "[--use-codex] <source-session-id>"
-examples:
-  - /workflow:test-gen WFS-user-auth
-  - /workflow:test-gen --use-codex WFS-api-refactor
+argument-hint: "[--use-codex] [--cli-execute] source-session-id"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -127,11 +123,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
 ### Phase 4: Generate Test Tasks
-**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] --session [testSessionId]")`
+**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
 
 **Input**:
 - `testSessionId` from Phase 1
-- `--use-codex` flag (if present in original command)
+- `--use-codex` flag (if present in original command) - Controls IMPL-002 fix mode
+- `--cli-execute` flag (if present in original command) - Controls IMPL-001 generation mode
 
 **Expected Behavior**:
 - Parse TEST_ANALYSIS_RESULTS.md from Phase 3

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

@@ -1,7 +1,6 @@
 ---
 name: concept-enhanced
 description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation
-usage: /workflow:tools:concept-enhanced --session <session_id> --context <context_package_path>
 argument-hint: "--session WFS-session-id --context path/to/context-package.json"
 examples:
   - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json

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

@@ -1,7 +1,6 @@
 ---
 name: gather
 description: Intelligently collect project context based on task description and package into standardized JSON
-usage: /workflow:tools:context-gather --session <session_id> "<task_description>"
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"

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

@@ -1,7 +1,6 @@
 ---
 name: task-generate-agent
 description: Autonomous task generation using action-planning-agent with discovery and output phases
-usage: /workflow:tools:task-generate-agent --session <session_id>
 argument-hint: "--session WFS-session-id"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
@@ -216,17 +215,29 @@ Task(
         "on_error": "fail"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-      "modification_points": ["Apply requirements from synthesis"],
-      "logic_flow": [
-        "Load synthesis specification",
-        "Analyze existing patterns",
-        "Implement following specification",
-        "Consult artifacts for technical details when needed",
-        "Validate against acceptance criteria"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following synthesis specification",
+        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from synthesis-specification.md",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load synthesis specification and relevant role artifacts",
+          "Execute MCP code-index discovery for relevant files",
+          "Analyze existing patterns and identify modification targets",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }

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

@@ -1,11 +1,7 @@
 ---
 name: task-generate-tdd
 description: Generate TDD task chains with Red-Green-Refactor dependencies
-usage: /workflow:tools:task-generate-tdd --session <session_id> [--agent]
 argument-hint: "--session WFS-session-id [--agent]"
-examples:
-  - /workflow:tools:task-generate-tdd --session WFS-auth
-  - /workflow:tools:task-generate-tdd --session WFS-auth --agent
 allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
 ---
 
@@ -178,51 +174,53 @@ For each feature, generate 3 tasks with ID format:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Write minimal code to pass tests, then enter iterative fix cycle if they still fail",
-      "initial_implementation": [
-        "Write minimal code based on test requirements",
-        "Execute test suite: bash(npm test -- tests/auth/login.test.ts)",
-        "If tests pass → Complete task",
-        "If tests fail → Capture failure logs and proceed to test-fix cycle"
-      ],
-      "test_fix_cycle": {
-        "max_iterations": 3,
-        "cycle_pattern": "gemini_diagnose → manual_fix (or codex if meta.use_codex=true) → retest",
-        "tools": {
-          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
-          "fix_application": "manual (default) or codex if meta.use_codex=true",
-          "verification": "bash(npm test -- tests/auth/login.test.ts)"
-        },
-        "exit_conditions": {
-          "success": "all_tests_pass",
-          "failure": "max_iterations_reached"
-        },
-        "steps": [
-          "ITERATION LOOP (max 3):",
-          "  1. Gemini Diagnosis:",
-          "     bash(cd .workflow/WFS-xxx/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
-          "     PURPOSE: Diagnose TDD Green phase test failure iteration [N]",
-          "     TASK: Systematic bug analysis and fix recommendations",
-          "     MODE: analysis",
-          "     CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
-          "              Test output: [test_failures]",
-          "              Test requirements: [test_requirements]",
-          "              Implementation: [focus_paths]",
-          "     EXPECTED: Root cause analysis, code path tracing, targeted fixes",
-          "     RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
-          "            Minimal surgical fixes only - stay in Green phase",
-          "     \" > green-fix-iteration-[N]-diagnosis.md)",
-          "  2. Apply Fix (check meta.use_codex):",
-          "     IF meta.use_codex=false (default): Present diagnosis to user for manual fix",
-          "     IF meta.use_codex=true: Codex applies fix automatically",
-          "  3. Retest: bash(npm test -- tests/auth/login.test.ts)",
-          "  4. If pass → Exit loop, complete task",
-          "     If fail → Continue to next iteration",
-          "IF max_iterations reached: Revert changes, report failure"
-        ]
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement minimal code to pass tests",
+        "description": "Write minimal code based on test requirements following TDD principles - no over-engineering",
+        "modification_points": [
+          "Load test requirements from TEST phase",
+          "Create/modify implementation files",
+          "Implement only what tests require",
+          "Focus on passing tests, not perfection"
+        ],
+        "logic_flow": [
+          "Load test requirements from [test_requirements]",
+          "Parse test expectations and edge cases",
+          "Write minimal implementation code",
+          "Avoid premature optimization or abstraction"
+        ],
+        "depends_on": [],
+        "output": "initial_implementation"
+      },
+      {
+        "step": 2,
+        "title": "Test and iteratively fix until passing",
+        "description": "Run tests and enter iterative fix cycle if needed (max 3 iterations with auto-revert on failure)",
+        "modification_points": [
+          "Execute test suite",
+          "If tests fail: diagnose with Gemini",
+          "Apply fixes (manual or Codex if meta.use_codex=true)",
+          "Retest and iterate"
+        ],
+        "logic_flow": [
+          "Run test suite",
+          "If all tests pass → Complete",
+          "If tests fail → Enter iteration loop (max 3):",
+          "  Extract failure messages and stack traces",
+          "  Use Gemini bug-fix template for diagnosis",
+          "  Generate targeted fix recommendations",
+          "  Apply fixes (manual or Codex)",
+          "  Rerun tests",
+          "  If pass → Complete, if fail → Continue iteration",
+          "If max_iterations reached → Trigger auto-revert"
+        ],
+        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "depends_on": [1],
+        "output": "test_results"
       }
-    },
+    ],
     "post_completion": [
       {
         "step": "verify_tests_passing",

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

@@ -1,10 +1,10 @@
 ---
 name: task-generate
 description: Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration
-usage: /workflow:tools:task-generate --session <session_id>
-argument-hint: "--session WFS-session-id"
+argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate --session WFS-auth
+  - /workflow:tools:task-generate --session WFS-auth --cli-execute
 ---
 
 # Task Generation Command
@@ -12,12 +12,30 @@ examples:
 ## Overview
 Generate task JSON files and IMPL_PLAN.md from analysis results with automatic artifact detection and integration.
 
+## Execution Modes
+
+### Agent Mode (Default)
+Tasks execute within agent context using agent's capabilities:
+- Agent reads synthesis specifications
+- Agent implements following requirements
+- Agent validates implementation
+- **Benefit**: Seamless context within single agent execution
+
+### CLI Execute Mode (`--cli-execute`)
+Tasks execute using Codex CLI with resume mechanism:
+- Each task uses `codex exec` command in `implementation_approach`
+- First task establishes Codex session
+- Subsequent tasks use `codex exec "..." resume --last` for context continuity
+- **Benefit**: Codex's autonomous development capabilities with persistent context
+- **Use Case**: Complex implementation requiring Codex's reasoning and iteration
+
 ## Core Philosophy
 - **Analysis-Driven**: Generate from ANALYSIS_RESULTS.md
 - **Artifact-Aware**: Auto-detect brainstorming outputs
 - **Context-Rich**: Embed comprehensive context in task JSON
 - **Flow-Control Ready**: Pre-define implementation steps
 - **Memory-First**: Reuse loaded documents from memory
+- **CLI-Aware**: Support Codex resume mechanism for persistent context
 
 ## Core Responsibilities
 - Parse analysis results and extract tasks
@@ -154,23 +172,52 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "on_error": "fail"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-      "modification_points": [
-        "Apply consolidated requirements from synthesis-specification.md",
-        "Follow technical guidelines from synthesis",
-        "Consult artifacts for implementation details when needed",
-        "Integrate with existing patterns"
-      ],
-      "logic_flow": [
-        "Load synthesis specification",
-        "Extract requirements and design",
-        "Analyze existing patterns",
-        "Implement following specification",
-        "Consult artifacts for technical details when needed",
-        "Validate against acceptance criteria"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following synthesis specification",
+        "description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from synthesis-specification.md",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load synthesis specification",
+          "Extract requirements and design",
+          "Analyze existing patterns",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
+
+    // CLI Execute Mode: Use Codex command (when --cli-execute flag present)
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Execute implementation with Codex",
+        "description": "Use Codex CLI to implement '[title]' following synthesis specification with autonomous development capabilities",
+        "modification_points": [
+          "Codex loads synthesis specification and artifacts",
+          "Codex implements following requirements",
+          "Codex validates and tests implementation"
+        ],
+        "logic_flow": [
+          "Establish or resume Codex session",
+          "Pass synthesis specification to Codex",
+          "Codex performs autonomous implementation",
+          "Codex validates against acceptance criteria"
+        ],
+        "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: [title] TASK: [requirements] MODE: auto CONTEXT: @{[synthesis_path],[artifacts_paths]} EXPECTED: [acceptance] RULES: Follow synthesis-specification.md\" [resume_flag] --skip-git-repo-check -s danger-full-access)",
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines"]
   }
 }
@@ -182,7 +229,37 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 3. Generate task context (requirements, focus_paths, acceptance)
 4. **Determine modification targets**: Extract specific code locations from analysis
 5. Build flow_control with artifact loading steps and target_files
-6. Create individual task JSON files in `.task/`
+6. **CLI Execute Mode**: If `--cli-execute` flag present, generate Codex commands
+7. Create individual task JSON files in `.task/`
+
+#### Codex Resume Mechanism (CLI Execute Mode)
+
+**Session Continuity Strategy**:
+- **First Task** (no depends_on or depends_on=[]): Establish new Codex session
+  - Command: `codex -C [path] --full-auto exec "[prompt]" --skip-git-repo-check -s danger-full-access`
+  - Creates new session context
+
+- **Subsequent Tasks** (has depends_on): Resume previous Codex session
+  - Command: `codex --full-auto exec "[prompt]" resume --last --skip-git-repo-check -s danger-full-access`
+  - Maintains context from previous implementation
+  - **Critical**: `resume --last` flag enables context continuity
+
+**Resume Flag Logic**:
+```javascript
+// Determine resume flag based on task dependencies
+const resumeFlag = task.context.depends_on && task.context.depends_on.length > 0
+  ? "resume --last"
+  : "";
+
+// First task (IMPL-001): no resume flag
+// Later tasks (IMPL-002, IMPL-003): use "resume --last"
+```
+
+**Benefits**:
+- ✅ Shared context across related tasks
+- ✅ Codex learns from previous implementations
+- ✅ Consistent patterns and conventions
+- ✅ Reduced redundant analysis
 
 #### Target Files Generation (Critical)
 **Purpose**: Identify specific code locations for modification AND new files to create
@@ -543,8 +620,82 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 /workflow:tools:task-generate --session WFS-auth
 ```
 
+## CLI Execute Mode Examples
+
+### Example 1: First Task (Establish Session)
+```json
+{
+  "id": "IMPL-001",
+  "title": "Implement user authentication module",
+  "context": {
+    "depends_on": [],
+    "focus_paths": ["src/auth"],
+    "requirements": ["JWT-based authentication", "Login and registration endpoints"]
+  },
+  "flow_control": {
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Execute implementation with Codex",
+      "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication module TASK: JWT-based authentication with login and registration MODE: auto CONTEXT: @{.workflow/WFS-session/.brainstorming/synthesis-specification.md} EXPECTED: Complete auth module with tests RULES: Follow synthesis specification\" --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "implementation"
+    }]
+  }
+}
+```
+
+### Example 2: Subsequent Task (Resume Session)
+```json
+{
+  "id": "IMPL-002",
+  "title": "Add password reset functionality",
+  "context": {
+    "depends_on": ["IMPL-001"],
+    "focus_paths": ["src/auth"],
+    "requirements": ["Password reset via email", "Token validation"]
+  },
+  "flow_control": {
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Execute implementation with Codex",
+      "command": "bash(codex --full-auto exec \"PURPOSE: Add password reset functionality TASK: Password reset via email with token validation MODE: auto CONTEXT: Previous auth implementation from session EXPECTED: Password reset endpoints with email integration RULES: Maintain consistency with existing auth patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "implementation"
+    }]
+  }
+}
+```
+
+### Example 3: Third Task (Continue Session)
+```json
+{
+  "id": "IMPL-003",
+  "title": "Implement role-based access control",
+  "context": {
+    "depends_on": ["IMPL-001", "IMPL-002"],
+    "focus_paths": ["src/auth"],
+    "requirements": ["User roles and permissions", "Middleware for route protection"]
+  },
+  "flow_control": {
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Execute implementation with Codex",
+      "command": "bash(codex --full-auto exec \"PURPOSE: Implement role-based access control TASK: User roles, permissions, and route protection middleware MODE: auto CONTEXT: Existing auth system from session EXPECTED: RBAC system integrated with current auth RULES: Use established patterns from session context\" resume --last --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "implementation"
+    }]
+  }
+}
+```
+
+**Pattern Summary**:
+- IMPL-001: Fresh start with `-C src/auth` and full prompt
+- IMPL-002: Resume with `resume --last`, references "previous auth implementation"
+- IMPL-003: Resume with `resume --last`, references "existing auth system"
+
 ## Related Commands
 - `/workflow:plan` - Orchestrates entire planning
+- `/workflow:plan --cli-execute` - Planning with CLI execution mode
 - `/workflow:tools:context-gather` - Provides context package
 - `/workflow:tools:concept-enhanced` - Provides analysis results
 - `/workflow:execute` - Executes generated tasks

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

@@ -1,10 +1,7 @@
 ---
 name: tdd-coverage-analysis
 description: Analyze test coverage and TDD cycle execution
-usage: /workflow:tools:tdd-coverage-analysis --session <session_id>
 argument-hint: "--session WFS-session-id"
-examples:
-  - /workflow:tools:tdd-coverage-analysis --session WFS-auth
 allowed-tools: Read(*), Write(*), Bash(*)
 ---
 

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

@@ -1,7 +1,6 @@
 ---
 name: test-concept-enhanced
 description: Analyze test requirements and generate test generation strategy using Gemini
-usage: /workflow:tools:test-concept-enhanced --session <test_session_id> --context <test_context_package_path>
 argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
 examples:
   - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json

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

@@ -1,7 +1,6 @@
 ---
 name: test-context-gather
 description: Collect test coverage context and identify files requiring test generation
-usage: /workflow:tools:test-context-gather --session <test_session_id>
 argument-hint: "--session WFS-test-session-id"
 examples:
   - /workflow:tools:test-context-gather --session WFS-test-auth

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

@@ -1,11 +1,12 @@
 ---
 name: test-task-generate
 description: Generate test-fix task JSON with iterative test-fix-retest cycle specification
-usage: /workflow:tools:test-task-generate [--use-codex] --session <test-session-id>
-argument-hint: "[--use-codex] --session WFS-test-session-id"
+argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
 examples:
   - /workflow:tools:test-task-generate --session WFS-test-auth
   - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+  - /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
+  - /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ---
 
 # Test Task Generation Command
@@ -13,6 +14,16 @@ examples:
 ## Overview
 Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle specification, including Gemini diagnosis (using bug-fix template) and manual fix workflow (Codex automation only when explicitly requested).
 
+## Execution Modes
+
+### Test Generation (IMPL-001)
+- **Agent Mode (Default)**: @code-developer generates tests within agent context
+- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
+
+### Test Fix (IMPL-002)
+- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
+- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
+
 ## Core Philosophy
 - **Analysis-Driven Test Generation**: Use TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
 - **Agent-Based Test Creation**: Call @code-developer agent for comprehensive test generation
@@ -38,8 +49,9 @@ Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle
 ### Phase 1: Input Validation & Discovery
 
 1. **Parameter Parsing**
-   - Parse `--use-codex` flag from command arguments
-   - Store flag value for IMPL-002.json generation
+   - Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
+   - Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
+   - Store flag values for task JSON generation
 
 2. **Test Session Validation**
    - Load `.workflow/{test-session-id}/workflow-session.json`
@@ -143,31 +155,53 @@ Generate **TWO task JSON files**:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
-      "generation_steps": [
-        "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
-        "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
-        "Study existing test patterns from test_context.test_framework.conventions",
-        "For each test file in section 5 (Implementation Targets):",
-        "  - Create test file with specified scenarios",
-        "  - Implement happy path tests",
-        "  - Implement error handling tests",
-        "  - Implement edge case tests",
-        "  - Implement integration tests (if specified)",
-        "  - Add required mocks and fixtures",
-        "Follow test framework conventions and project standards",
-        "Ensure all tests are executable and syntactically valid"
+    // Agent Mode (Default): Agent implements tests
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate comprehensive test suite",
+        "description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
+        "modification_points": [
+          "Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
+          "Study existing test patterns",
+          "Create test files with all required scenarios",
+          "Implement happy path, error handling, edge case, and integration tests",
+          "Add required mocks and fixtures"
+        ],
+        "logic_flow": [
+          "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
+          "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
+          "Study existing test patterns from test_context.test_framework.conventions",
+          "For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
+          "Follow test framework conventions and project standards",
+          "Ensure all tests are executable and syntactically valid"
+        ],
+        "depends_on": [],
+        "output": "test_suite"
+      }
+    ],
+
+    // CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Generate tests using Codex",
+      "description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
+      "modification_points": [
+        "Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
+        "Codex generates all test files listed in analysis section 5",
+        "Codex ensures tests follow framework conventions"
       ],
-      "quality_criteria": [
-        "All test scenarios from analysis are implemented",
-        "Test structure matches existing patterns",
-        "Clear test descriptions and assertions",
-        "Proper setup/teardown and fixtures",
-        "Dependencies properly mocked",
-        "Tests follow project coding standards"
-      ]
-    },
+      "logic_flow": [
+        "Start new Codex session",
+        "Pass TEST_ANALYSIS_RESULTS.md to Codex",
+        "Codex studies existing test patterns",
+        "Codex generates comprehensive test suite",
+        "Codex validates test syntax and executability"
+      ],
+      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @{.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md,.workflow/WFS-test-[session]/.process/test-context-package.json} EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "test_generation"
+    }],
     "target_files": [
       "{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
       "{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
@@ -279,24 +313,27 @@ Generate **TWO task JSON files**:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if explicitly needed)",
-      "test_fix_cycle": {
-        "max_iterations": 5,
-        "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
-        "tools": {
-          "test_execution": "bash(test_command)",
-          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
-          "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
-          "verification": "bash(test_command) + regression_check"
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Execute iterative test-fix-retest cycle",
+        "description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
+        "test_fix_cycle": {
+          "max_iterations": 5,
+          "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
+          "tools": {
+            "test_execution": "bash(test_command)",
+            "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+            "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
+            "verification": "bash(test_command) + regression_check"
+          },
+          "exit_conditions": {
+            "success": "all_tests_pass",
+            "failure": "max_iterations_reached",
+            "error": "test_command_not_found"
+          }
         },
-        "exit_conditions": {
-          "success": "all_tests_pass",
-          "failure": "max_iterations_reached",
-          "error": "test_command_not_found"
-        }
-      },
-      "modification_points": [
+        "modification_points": [
         "PHASE 1: Initial Test Execution",
         "  1.1. Discover test command from framework detection",
         "  1.2. Execute initial test run: bash([test_command])",
@@ -428,33 +465,36 @@ Generate **TWO task JSON files**:
         "  Generate summary (include test generation info)",
         "  Certify code APPROVED"
       ],
-      "error_handling": {
-        "max_iterations_reached": {
-          "action": "revert_all_changes",
-          "commands": [
-            "bash(git reset --hard HEAD)",
-            "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
-          ],
-          "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
+        "error_handling": {
+          "max_iterations_reached": {
+            "action": "revert_all_changes",
+            "commands": [
+              "bash(git reset --hard HEAD)",
+              "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
+            ],
+            "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
+          },
+          "test_command_fails": {
+            "action": "treat_as_test_failure",
+            "context": "Use stderr as failure context for Gemini diagnosis"
+          },
+          "codex_apply_fails": {
+            "action": "retry_once_then_skip",
+            "fallback": "Mark iteration as skipped, continue to next"
+          },
+          "gemini_diagnosis_fails": {
+            "action": "retry_with_simplified_context",
+            "fallback": "Use previous diagnosis, continue"
+          },
+          "regression_detected": {
+            "action": "log_warning_continue",
+            "context": "Include regression info in next Gemini diagnosis"
+          }
         },
-        "test_command_fails": {
-          "action": "treat_as_test_failure",
-          "context": "Use stderr as failure context for Gemini diagnosis"
-        },
-        "codex_apply_fails": {
-          "action": "retry_once_then_skip",
-          "fallback": "Mark iteration as skipped, continue to next"
-        },
-        "gemini_diagnosis_fails": {
-          "action": "retry_with_simplified_context",
-          "fallback": "Use previous diagnosis, continue"
-        },
-        "regression_detected": {
-          "action": "log_warning_continue",
-          "context": "Include regression info in next Gemini diagnosis"
-        }
+        "depends_on": [],
+        "output": "test_fix_results"
       }
-    },
+    ],
     "target_files": [
       "Auto-discovered from test failures",
       "Extracted from Gemini diagnosis each iteration",

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

@@ -0,0 +1,464 @@
+---
+name: batch-generate
+description: Prompt-driven batch UI generation using target-style-centric parallel execution
+argument-hint: [--targets "<list>"] [--target-type "page|component"] [--device-type "desktop|mobile|tablet|responsive"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*), mcp__exa__web_search_exa(*)
+---
+
+# Batch Generate UI Prototypes (/workflow:ui-design:batch-generate)
+
+## Overview
+Prompt-driven UI generation with intelligent target extraction and **target-style-centric batch execution**. Each agent handles all layouts for one target × style combination.
+
+**Strategy**: Prompt → Targets → Batched Generation
+- **Prompt-driven**: Describe what to build, command extracts targets
+- **Agent scope**: Each of `T × S` agents generates `L` layouts
+- **Parallel batching**: Max 6 concurrent agents for optimal throughput
+- **Component isolation**: Complete task independence
+- **Style-aware**: HTML adapts to design_attributes
+- **Self-contained CSS**: Direct token values (no var() refs)
+
+**Supports**: Pages (full layouts) and components (isolated elements)
+
+## Phase 1: Setup & Validation
+
+### Step 1: Parse Prompt & Resolve Configuration
+```bash
+# Parse required parameters
+prompt_text = --prompt
+device_type = --device-type OR "responsive"
+
+# Extract targets from prompt
+IF --targets:
+    target_list = split_and_clean(--targets)
+ELSE:
+    target_list = extract_targets_from_prompt(prompt_text)  # See helpers
+    IF NOT target_list: target_list = ["home"]  # Fallback
+
+# Detect target type
+target_type = --target-type OR detect_target_type(target_list)
+
+# Resolve base path
+IF --base-path:
+    base_path = --base-path
+ELSE IF --session:
+    bash(find .workflow/WFS-{session} -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
+ELSE:
+    bash(find .workflow -type d -name "design-*" -printf "%T@ %p\n" | sort -nr | head -1 | cut -d' ' -f2)
+
+# Get variant counts
+style_variants = --style-variants OR bash(ls {base_path}/style-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,361 @@
+---
+name: capture
+description: Batch screenshot capture for UI design workflows using MCP or local fallback
+argument-hint: --url-map "target:url,..." [--base-path path] [--session id]
+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

@@ -1,203 +1,222 @@
 ---
 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>]
-argument-hint: "[--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--variants 3] [--layout-variants 3]"
-parameters:
-  - name: --variants
-    type: number
-    default: all available variants from style-cards.json
-    description: "Number of style variants to consolidate (1-N). Processes first N variants from style-cards.json. Creates style-N directories."
-  - name: --session
-    type: string
-    description: "Workflow session ID (e.g., WFS-auth). Finds latest design run in session directory."
-  - name: --base-path
-    type: string
-    description: "Custom base path for input/output. Overrides --session if provided."
-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
+argument-hint: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
 ---
 
 # Design System Consolidation Command
 
 ## Overview
-Consolidate user-selected style variants into **independent production-ready design systems**. This command serves as the **Style Planning Phase**, focusing exclusively on design tokens and style guides for the subsequent generation phase.
+Consolidate style variants into independent production-ready design systems. Refines raw token proposals from `style-extract` into finalized design tokens and style guides.
 
-## Core Philosophy
-- **Style System Focus**: Exclusively handles design system consolidation
-- **Agent-Driven**: Uses ui-design-agent for multi-file generation efficiency
-- **Separate Design Systems**: Generates N independent design systems (one per variant)
-- **Token Refinement**: Refines `proposed_tokens` from each variant into complete systems
-- **Intelligent Synthesis**: Ensures completeness and consistency
-- **Production-Ready**: Complete design system(s) with documentation
-- **Matrix-Ready**: Provides style variants for style × layout matrix exploration in generate phase
+**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
 
-## Execution Protocol
-
-### Phase 1: Path Resolution & Variant Loading
+## Phase 1: Setup & Validation
 
+### Step 1: Resolve Base Path & Load Style Cards
 ```bash
 # Determine base path
-IF --base-path: base_path = {provided_base_path}
-ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
-ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
-
-# Verify extraction output exists
-style_cards_path = "{base_path}/style-extraction/style-cards.json"
-VERIFY: exists(style_cards_path)
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
 
 # Load style cards
-style_cards = Read(style_cards_path)
-total_variants = len(style_cards.style_cards)
+bash(cat {base_path}/style-extraction/style-cards.json)
 ```
 
-### Phase 2: Variant Selection
-
+### Step 2: Memory Check (Skip if Already Done)
 ```bash
-# Determine how many variants to consolidate
-IF --variants:
-    variants_count = {provided_count}
-    VALIDATE: 1 <= variants_count <= total_variants
-ELSE:
-    variants_count = total_variants
-
-# Select first N variants
-selected_variants = style_cards.style_cards[0:variants_count]
-VERIFY: selected_variants.length > 0
-
-REPORT: "📦 Generating {variants_count} independent design systems"
+# Check if already consolidated
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "exists")
 ```
 
-### Phase 3: Load Design Context (Optional)
+**If exists**: Skip to completion message
 
+### Step 3: Select Variants
 ```bash
-# Load brainstorming context if available
-design_context = ""
-IF exists({base_path}/.brainstorming/synthesis-specification.md):
-    design_context = Read(synthesis-specification.md)
-ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
-    design_context = Read(ui-designer/analysis.md)
+# Determine variant count (default: all from style-cards.json)
+bash(cat style-cards.json | grep -c "\"id\": \"variant-")
 
-# Load design space analysis from extraction phase
-design_space_analysis = {}
-design_space_path = "{base_path}/style-extraction/design-space-analysis.json"
-IF exists(design_space_path):
-    design_space_analysis = Read(design_space_path)
-    REPORT: "📊 Loaded design space analysis with {len(design_space_analysis.divergent_directions)} variant directions"
-ELSE:
-    REPORT: "⚠️ No design space analysis found - trend research will be skipped"
+# Validate variant count
+# Priority: --variants parameter → total_variants from style-cards.json
 ```
 
-### Phase 4: Design System Synthesis (Agent Execution)
+**Output**: `variants_count`, `selected_variants[]`
 
+### Step 4: Load Design Context (Optional)
 ```bash
-REPORT: "🤖 Using agent for separate design system generation..."
+# Load brainstorming context
+bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
 
-# Create output directories
-Bash(mkdir -p "{base_path}/style-consolidation/style-{{1..{variants_count}}}")
+# Load design space analysis
+bash(test -f {base_path}/style-extraction/design-space-analysis.json && cat it)
+```
 
-# Prepare agent task prompt
-agent_task_prompt = """
-Generate {variants_count} independent production-ready design systems with external trend research and WRITE them to the file system.
+**Output**: `design_context`, `design_space_analysis`
 
-## Context
-SESSION: {session_id}
-MODE: Separate design system generation with MCP trend research
-BASE_PATH: {base_path}
-VARIANTS TO PROCESS: {variants_count}
+## Phase 2: Design System Synthesis (Agent)
 
-## Variant Data
-{FOR each variant IN selected_variants:
-  ---
-  Variant ID: {variant.id} | Name: {variant.name}
-  Description: {variant.description}
-  Design Philosophy: {variant.design_philosophy}
-  Proposed Tokens: {JSON.stringify(variant.proposed_tokens, null, 2)}
-  ---
-}
+**Executor**: `Task(ui-design-agent)` for all variants
 
-{IF design_context: DESIGN CONTEXT (from brainstorming): {design_context}}
+### Step 1: Create Output Directories
+```bash
+bash(mkdir -p {base_path}/style-consolidation/style-{{1..{variants_count}}})
+```
 
-{IF design_space_analysis:
-## Design Space Analysis (for MCP Research)
-{JSON.stringify(design_space_analysis, null, 2)}
+### 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
 
-Note: Each variant has search_keywords and anti_keywords for trend research.
-}
+  SESSION: {session_id} | MODE: Philosophy-driven refinement | BASE_PATH: {base_path}
 
-## Task
-For EACH variant (1 to {variants_count}):
-1. **Perform Variant-Specific Trend Research** (if design space analysis available)
-2. **Refine design tokens** using research insights
-3. **Generate and WRITE 2 files** to the file system
+  CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
 
-## Step 1: Variant-Specific Trend Research (MCP)
+  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}}
+  }
 
-IF design_space_analysis is provided, FOR EACH variant:
+  ## 参考
+  - 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)
 
-1. **Extract Research Parameters** from design space analysis:
-   - philosophy_name: The variant's design philosophy
-   - search_keywords: Keywords for trend research
-   - anti_keywords: Patterns to avoid
+  ## 生成
+  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. **Build Variant-Specific Queries**:
-   ```javascript
-   queries = [
-     `{philosophy_name} UI design color palettes {search_keywords[:3]} 2024 2025`,
-     `{philosophy_name} typography trends {search_keywords[:3]} web design 2024`,
-     `{philosophy_name} layout patterns {search_keywords[:3]} design systems 2024`,
-     `design systems {philosophy_name} NOT {anti_keywords[:2]}`
-   ]
-   ```
+  2. {base_path}/style-consolidation/style-{N}/style-guide.md
+     - Expanded design philosophy
+     - Complete color system with accessibility notes
+     - Typography documentation
+     - Usage guidelines
 
-3. **Execute MCP Searches**:
-   ```javascript
-   trend_research = {
-     colors: mcp__exa__get_code_context_exa(query=queries[0], tokensNum=2000),
-     typography: mcp__exa__get_code_context_exa(query=queries[1], tokensNum=2000),
-     layout: mcp__exa__get_code_context_exa(query=queries[2], tokensNum=2000),
-     contrast: mcp__exa__get_code_context_exa(query=queries[3], tokensNum=2000)
-   }
-   ```
+  ## 注意
+  - ✅ 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
+`
+```
 
-4. **Shared Accessibility Research** (execute once, apply to all variants):
-   ```javascript
-   accessibility_guidelines = mcp__exa__get_code_context_exa(
-     query="WCAG 2.2 accessibility color contrast ARIA best practices 2024",
-     tokensNum=1500
-   )
-   ```
+**Output**: Agent generates `variants_count × 2` files
 
-5. **Use Research Results** to inform token refinement:
-   - Color token refinement guided by `trend_research.colors`
-   - Typography refinement guided by `trend_research.typography`
-   - Layout spacing informed by `trend_research.layout`
-   - Contrast validation using `trend_research.contrast` and `accessibility_guidelines`
+## Phase 3: Verify Output
 
-IF design_space_analysis is NOT provided:
-- Skip trend research
-- Refine tokens based solely on variant's existing philosophy and proposed tokens
+### Step 1: Check Files Created
+```bash
+# Verify all design systems created
+bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
 
-## Step 2: Refinement Rules (apply to each variant)
-1. **Complete Token Coverage**: Ensure all categories present (colors, typography, spacing, etc.)
-2. **Fill Gaps**: Generate missing tokens based on variant's philosophy and trend research
-3. **Maintain Style Identity**: Preserve unique characteristics from proposed tokens
-4. **Semantic Naming**: Use clear names (e.g., "brand-primary" not "color-1")
-5. **Accessibility**: Validate WCAG AA contrast using accessibility guidelines (4.5:1 text, 3:1 UI)
-6. **OKLCH Format**: All colors use oklch(L C H / A) format
-7. **Design Philosophy**: Expand variant's design philosophy using trend insights
-8. **Trend Integration**: Incorporate modern trends from MCP research while maintaining variant identity
+# Validate structure
+bash(cat {base_path}/style-consolidation/style-1/design-tokens.json | grep -q "colors" && echo "valid")
+```
 
-## Step 3: File Write Instructions
-For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files:
+### 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
 
-### File 1: Design Tokens
-**Path**: {base_path}/style-consolidation/style-{variant_id}/design-tokens.json
-**Content**: Complete design token JSON with structure:
 ```json
 {
   "colors": {
@@ -215,205 +234,34 @@ For EACH variant {variant_id} (1 to {variants_count}), WRITE these 2 files:
 }
 ```
 
-### File 2: Style Guide
-**Path**: {base_path}/style-consolidation/style-{variant_id}/style-guide.md
-**Content**: Markdown documentation with structure:
-```markdown
-# Design System Style Guide - {variant.name}
-
-## Design Philosophy
-{Expanded variant philosophy}
-
-## Color System
-### Brand Colors, Surface Colors, Semantic Colors, Text Colors, Border Colors
-{List all with usage and accessibility notes}
-
-## Typography
-### Font Families, Type Scale, Usage Examples
-{Complete typography documentation}
-
-## Spacing System, Component Guidelines
-{Spacing patterns and component token examples}
-
-## Accessibility
-- All text meets WCAG AA (4.5:1 minimum)
-- UI components meet WCAG AA (3:1 minimum)
-- Focus indicators are clearly visible
-```
-
-## Write Operation Instructions
-- Use Write() tool for each file with the absolute paths provided above
-- Verify each write operation succeeds
-- Report completion with file paths and sizes
-- DO NOT return file contents as text
-
-## Example Write Operations
-```javascript
-// For variant 1
-Write("{base_path}/style-consolidation/style-1/design-tokens.json", JSON.stringify(tokens, null, 2))
-Write("{base_path}/style-consolidation/style-1/style-guide.md", guide_content)
-
-// For variant 2
-Write("{base_path}/style-consolidation/style-2/design-tokens.json", JSON.stringify(tokens, null, 2))
-Write("{base_path}/style-consolidation/style-2/style-guide.md", guide_content)
-```
-
-## Expected Final Report
-Report which files were written and their sizes:
-```
-✅ Written: {base_path}/style-consolidation/style-1/design-tokens.json (12.5 KB)
-✅ Written: {base_path}/style-consolidation/style-1/style-guide.md (8.3 KB)
-✅ Written: {base_path}/style-consolidation/style-2/design-tokens.json (11.8 KB)
-✅ Written: {base_path}/style-consolidation/style-2/style-guide.md (7.9 KB)
-... (for all {variants_count} variants)
-```
-
-## Critical Requirements
-- Generate files for ALL {variants_count} variants
-- Use sequential IDs: style-1, style-2, ..., style-{variants_count}
-- Each variant must be complete and independent
-- Maintain consistent structure across all variants
-- Write files directly using Write() tool - do NOT return contents as text
-"""
-
-# Execute agent task
-Task(subagent_type="ui-design-agent", description="Generate {variants_count} separate design systems", prompt=agent_task_prompt)
-
-REPORT: "✅ Agent task dispatched for {variants_count} design systems"
-```
-
-### Phase 5: Verify Agent File Creation
-```bash
-REPORT: "📝 Verifying agent file creation for {variants_count} design systems..."
-
-# Verify each variant's files were created by agent
-FOR variant_id IN range(1, variants_count + 1):
-    tokens_path = "{base_path}/style-consolidation/style-{variant_id}/design-tokens.json"
-    guide_path = "{base_path}/style-consolidation/style-{variant_id}/style-guide.md"
-
-    # Verify files exist
-    VERIFY: exists(tokens_path), "Design tokens not created by agent for style-{variant_id}"
-    VERIFY: exists(guide_path), "Style guide not created by agent for style-{variant_id}"
-
-    # Optional: Validate JSON structure
-    TRY:
-        tokens = Read(tokens_path)
-        tokens_json = parse_json(tokens)
-        VALIDATE: tokens_json.colors exists, "Missing colors in design-tokens.json"
-        VALIDATE: tokens_json.typography exists, "Missing typography in design-tokens.json"
-        VALIDATE: tokens_json.spacing exists, "Missing spacing in design-tokens.json"
-
-        tokens_size = get_file_size(tokens_path)
-        guide_size = get_file_size(guide_path)
-        REPORT: "  ✅ style-{variant_id}/ verified ({tokens_size} KB tokens, {guide_size} KB guide)"
-    CATCH error:
-        ERROR: "Validation failed for style-{variant_id}: {error}"
-        REPORT: "  ⚠️ Files exist but validation failed - review agent output"
-
-REPORT: "✅ All {variants_count} design systems verified"
-```
-
-**Output Structure**:
-```
-{base_path}/style-consolidation/
-├── style-1/ (design-tokens.json, style-guide.md)
-├── style-2/ (same structure)
-└── style-N/ (same structure)
-```
-
-### Phase 6: Completion & Reporting
-
-```javascript
-TodoWrite({todos: [
-  {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
-  {content: "Select variants for consolidation", status: "completed", activeForm: "Selecting variants"},
-  {content: "Load design context and space analysis", status: "completed", activeForm: "Loading context"},
-  {content: "Perform variant-specific trend research", status: "completed", activeForm: "Researching design trends"},
-  {content: "Generate design systems via agent", status: "completed", activeForm: "Generating design systems"},
-  {content: "Process agent results and write files", status: "completed", activeForm: "Writing output files"}
-]});
-```
-
-**Completion Message**:
-```
-✅ Design system consolidation complete for session: {session_id}
-
-{IF design_space_analysis:
-🔍 Trend Research Performed:
-- {variants_count} × 4 variant-specific MCP queries ({variants_count * 4} total)
-- 1 shared accessibility research query
-- Each variant refined with independent trend guidance
-}
-
-Generated {variants_count} independent design systems:
-{FOR each variant: - {variant.name} ({variant.id})}
-
-📂 Output: {base_path}/style-consolidation/
-├── style-1/ (design-tokens.json, style-guide.md)
-├── style-2/ (same structure)
-└── style-{variants_count}/ (same structure)
-
-Next: /workflow:ui-design:generate --session {session_id} --style-variants {variants_count} --targets "dashboard,auth" --layout-variants N
-
-Note: When called from /workflow:ui-design:explore-auto, UI generation is triggered automatically.
-Layout planning is now handled in the generate phase for each specific target.
-```
-
-## design-tokens.json Format
-
-**Token structure** (all variants follow identical structure with different values):
-
-```json
-{
-  "colors": {
-    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
-    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
-    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
-    "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
-    "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
-  },
-  "typography": {
-    "font_family": {"heading": "...", "body": "...", "mono": "..."},
-    "font_size": {"xs": "...", "sm": "...", "base": "...", "lg": "...", "xl": "...", "2xl": "...", "3xl": "...", "4xl": "..."},
-    "font_weight": {"normal": "400", "medium": "500", "semibold": "600", "bold": "700"},
-    "line_height": {"tight": "1.25", "normal": "1.5", "relaxed": "1.75"},
-    "letter_spacing": {"tight": "-0.025em", "normal": "0", "wide": "0.025em"}
-  },
-  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
-  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
-  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
-  "breakpoints": {"sm": "640px", "md": "768px", "lg": "1024px", "xl": "1280px", "2xl": "1536px"}
-}
-```
-
-**Requirements**: All colors in OKLCH format, complete token coverage, semantic naming
+**Requirements**: OKLCH colors, complete coverage, semantic naming
 
 ## Error Handling
 
-- **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first
-- **Invalid variant count**: List available count, auto-select all if called from auto workflow
-- **Parsing errors**: Retry with stricter format instructions
-- **Validation warnings**: Report but continue (non-blocking)
-- **Missing categories**: Claude will fill gaps based on design philosophy
+### 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
 
-1. **Variant-Specific Trend Research** 🆕 - Agent performs independent MCP queries for each variant (4 queries per variant); Uses design space analysis keywords from extraction phase; Each variant researches its specific design philosophy; Shared accessibility research applied to all variants; Eliminates convergence by maintaining variant-specific research
-2. **Agent-Driven Architecture** - Uses ui-design-agent for multi-file generation and MCP research; Parallel generation of N independent design systems with external trend integration; Structured output parsing with labeled sections; Agent handles both research and synthesis
-3. **Separate Design Systems (Matrix-Ready)** - Generates N independent design systems (one per variant); Each variant maintains unique style identity enhanced by trend research; Provides style foundation for style × layout matrix exploration in generate phase
-4. **Token Refinement with Trend Integration** 🆕 - Reads `proposed_tokens` from style cards; Loads design space analysis for research parameters; Agent performs MCP trend research per variant; Refines tokens using research insights while maintaining style identity
-5. **Complete Design System Output** - design-tokens.json (CSS tokens per variant); style-guide.md (documentation per variant with trend insights)
-6. **Production-Ready Quality** - WCAG AA accessibility validation with MCP research; OKLCH color format for perceptual uniformity; Semantic token naming; Complete token coverage; Modern trends integration
-7. **Streamlined Workflow** - Sequential phases with clear responsibilities; Agent handles MCP research, token refinement, and file generation; Reproducible with deterministic structure; Context-aware (integrates brainstorming and design space analysis)
-8. **Clear Separation of Concerns** - Consolidation focuses on style systems with trend research; Extraction focuses on Claude-native analysis; Layout planning delegated to generate phase for target-specific optimization
+- **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 Points
+## Integration
 
-- **Input**:
-  - `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
-  - `design-space-analysis.json` from extraction phase (with search keywords for MCP research)
-  - `--variants` parameter (default: all variants)
-- **Output**: Style Systems: `style-consolidation/style-{n}/design-tokens.json` and `style-guide.md` for each variant (enhanced with trend research)
-- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
-- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow
-- **Next Command**: `/workflow:ui-design:generate --style-variants N --targets "..." --layout-variants M` performs target-specific layout planning
+**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

@@ -1,16 +1,7 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations (3×3 matrix exploration)
-usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
-argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--targets \"dashboard,auth,navbar,hero\"] [--target-type \"auto\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]"
-examples:
-  - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
-  - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
-  - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
-  - /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --prompt "Compare 3 navigation bar designs" --style-variants 3 --layout-variants 2
-  - /workflow:ui-design:explore-auto --targets "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
-  - /workflow:ui-design:explore-auto --targets "home,dashboard" --target-type "page"
+description: Exploratory UI design workflow with style-centric batch generation
+argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 
@@ -25,15 +16,23 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 - **Components** (isolated UI elements): navbar, card, hero, form, etc.
 - **Mixed**: Can combine both in a single workflow
 
-**Autonomous Flow**:
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 1. User triggers: `/workflow:ui-design:explore-auto [params]`
-2. Phase 1 (style-extract) → Auto-continues
-3. Phase 2 (style-consolidate) → Auto-continues
-4. Phase 3 (ui-generate) → Auto-continues with unified target list
-5. Phase 4 (design-update) → Auto-continues
-6. Phase 5 (batch-plan, optional) → Reports completion
+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
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon completion, coordinator constructs next command and executes immediately. No user intervention required.
+**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`.
 
@@ -44,12 +43,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 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
@@ -84,17 +89,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 ## Execution Modes
 
-**Matrix Mode** (unified):
+**Matrix Mode** (style-centric):
 - Generates `style_variants × layout_variants × targets` prototypes
-- **Phase 1**: `style_variants` style options (extract)
+- **Phase 1**: `style_variants` style options with design_attributes (extract)
 - **Phase 2**: `style_variants` independent design systems (consolidate)
-- **Phase 3**: Layout planning + UI generation (generate)
+- **Phase 3**: Style-centric batch generation (generate)
   - Sub-phase 1: `targets × layout_variants` target-specific layout plans
-  - Sub-phase 2: `layout_variants × targets` HTML/CSS templates
+  - **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
-  - Mixed: Combination based on intelligent detection
 
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
@@ -114,6 +120,51 @@ ELSE:
 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)"
@@ -124,10 +175,13 @@ 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}" },
-  "status": "in_progress"
+                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "device_type": "${device_type}", "device_source": "${device_source}" },
+  "status": "in_progress",
+  "performance_mode": "optimized"
 }
 ```
 
@@ -163,13 +217,24 @@ IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
 IF --target-type != "auto": target_type = --target-type
 
 # Interactive confirmation
-DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
-  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  "{emoji} {LABEL} CONFIRMATION"
+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)}"
-  "Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
-  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "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()
 
@@ -180,9 +245,14 @@ MATCH user_input:
   "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()**
@@ -199,43 +269,82 @@ detect_target_type(target_list):
 
 ### Phase 1: Style Extraction
 ```bash
-command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
+command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
           (--images ? "--images \"{images}\" " : "") +
           (--prompt ? "--prompt \"{prompt}\" " : "") +
-          "--variants {style_variants}"
-SlashCommand(command)  # → Phase 2
+          "--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)  # → Phase 3
-# Output: style_variants independent design systems (design tokens and style guides)
+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 3: Matrix UI Generation (with Layout Planning)
+### 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}\" " +
-          "--targets \"{targets_string}\" --target-type \"{target_type}\" " +
           "--style-variants {style_variants} --layout-variants {layout_variants}"
 
 total = style_variants × layout_variants × len(inferred_target_list)
-REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l} | Total: {total} prototypes"
-REPORT: "   → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
 
-SlashCommand(command)  # → Phase 4
+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}-layout-{l}.json (target-specific layout plans)
-# - {target}-style-{s}-layout-{l}.html (final prototypes)
-# - compare.html (matrix view)
+# - {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)  # → Phase 5 if --batch-plan, else complete
+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)
@@ -248,84 +357,133 @@ IF --batch-plan:
 
 ## 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 UI generation", "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..."}
 ]})
-// Update after each phase: current → completed, next → in_progress
+
+// ⚠️ 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
-- **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
+
+- **🚀 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 - inferred defaults)
+# Result: 27 prototypes (3×3×3) - responsive layouts (default)
 ```
 
-### 2. Custom Matrix with Session
+### 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 (targets from synthesis)
+# Result: 2×2×N prototypes - device type inferred from session
 ```
 
-### 3. Component Mode
+### 6. Component Mode (Desktop)
 ```bash
-/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
-# Result: 12 prototypes (3×2×2 components with minimal wrapper)
+/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
 ```
 
-### 4. Intelligent Parsing + Batch Planning
+### 7. Intelligent Parsing + Batch Planning
 ```bash
-/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for dashboard and settings" --batch-plan
-# Result: 16 prototypes (4×2×2) + auto-generated implementation tasks
+/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)
 ```
 
-### 5. Legacy Support
+### 8. Large Scale Responsive
 ```bash
-/workflow:ui-design:explore-auto --pages "home,dashboard,settings"
-# Equivalent to: --targets "home,dashboard,settings" --target-type "page"
+/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} | Matrix: {s}×{l} ({total} prototypes)
+Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
 
-Phase 1: {s} style variants (extract)
-Phase 2: {s} design systems (consolidate)
-Phase 3: Layout planning + generation (generate)
-  - {n}×{l} target-specific layout plans
-  - {l}×{n} HTML/CSS templates
+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-consolidation/  ({s} design systems)
-  ├── prototypes/
-  │   ├── _templates/       ({n}×{l} layout JSON + {l}×{n} HTML/CSS)
-  │   └── ...               ({total} final prototypes)
-  └── .run-metadata.json
+  ├── 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 per prototype
+  - 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,589 @@
+---
+name: explore-layers
+description: Interactive deep UI capture with depth-controlled layer exploration
+argument-hint: --url <url> --depth <1-5> [--session id] [--base-path path]
+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/extract.md

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

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

@@ -0,0 +1,372 @@
+---
+name: layout-extract
+description: Extract structural layout information from reference images, URLs, or text prompts
+argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
+---
+
+# 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")
+  - source_image_path (string, REQUIRED): Path to the primary reference image used for this layout analysis
+    * For image input: Use the actual image file path from {images_pattern}
+    * For URL input: Use the screenshot path if available, or empty string
+    * For text/prompt input: Use empty string
+    * Example: "{base_path}/screenshots/home.png"
+  - 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",
+      "source_image_path": "{base_path}/screenshots/home.png",
+      "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,271 @@
+---
+name: style-extract
+description: Extract design style from reference images or text prompts using Claude's analysis
+argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
+---
+
+# 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

@@ -1,11 +1,7 @@
 ---
 name: update
 description: Update brainstorming artifacts with finalized design system references
-usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
-argument-hint: "--session WFS-session-id [--selected-prototypes \"dashboard-variant-1,auth-variant-2\"]"
-examples:
-  - /workflow:ui-design:update --session WFS-auth
-  - /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
+argument-hint: --session <session_id> [--selected-prototypes "<list>"]
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
@@ -53,6 +49,21 @@ 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.

.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/workflows/cli-templates/prompts/documentation/api-reference.txt

@@ -1,240 +0,0 @@
-# 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/api.txt

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

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

@@ -0,0 +1,68 @@
+# Folder Navigation Documentation Template
+
+Generate a navigation README for directories that contain only subdirectories (no code files). This serves as an index to help readers navigate to specific modules.
+
+## Structure
+
+### 1. Overview
+
+Brief description of what this directory/category contains:
+
+> The `modules/` directory contains the core business logic modules of the application. Each subdirectory represents a self-contained functional module with its own responsibilities.
+
+### 2. Directory Structure
+
+Provide a tree view of the subdirectories with brief descriptions:
+
+```
+modules/
+├── auth/              - User authentication and authorization
+├── api/               - API route handlers and middleware
+├── database/          - Database connections and ORM models
+└── utils/             - Shared utility functions
+```
+
+### 3. Module Quick Reference
+
+Table format for quick scanning:
+
+| Module | Purpose | Key Features |
+|--------|---------|--------------|
+| [auth](./auth/) | Authentication | JWT tokens, session management |
+| [api](./api/) | API routing | REST endpoints, validation |
+| [database](./database/) | Data layer | PostgreSQL, migrations |
+| [utils](./utils/) | Utilities | Logging, helpers |
+
+### 4. How to Navigate
+
+Guidance on which module to explore based on needs:
+
+- **For authentication logic** → [auth module](./auth/)
+- **For API endpoints** → [api module](./api/)
+- **For database queries** → [database module](./database/)
+- **For helper functions** → [utils module](./utils/)
+
+### 5. Module Relationships (Optional)
+
+If modules have significant dependencies, show them:
+
+```
+api → auth (uses for authentication)
+api → database (uses for data access)
+auth → database (uses for user storage)
+```
+
+---
+
+## Rules
+
+1. **Keep it brief** - This is an index, not detailed documentation
+2. **One-line descriptions** - Each module gets a concise purpose statement
+3. **Scannable format** - Use tables and lists for quick navigation
+4. **Link to submodules** - Every module mentioned should link to its README
+5. **No code examples** - This is navigation only
+
+---
+
+**Directory Path**: [Auto-fill with actual directory path]
+**Last Updated**: [Auto-generated timestamp]

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

@@ -1,91 +0,0 @@
-# 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/module-readme.txt

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

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

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

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

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

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

@@ -19,8 +19,8 @@ type: strategic-guideline
 ## ⚡ Core Framework
 
 ### Tool Overview
-- **Gemini**: Analysis, understanding, exploration & documentation
-- **Qwen**: Architecture analysis, code generation & implementation
+- **Gemini**: Analysis, understanding, exploration & documentation (primary)
+- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
 - **Codex**: Development, implementation & automation
 
 ### Decision Principles
@@ -32,8 +32,8 @@ 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
@@ -56,15 +56,16 @@ type: strategic-guideline
 
 ### 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
+- **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**: Explicitly prohibited from auto-calling write mode
+- **⚠️ 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
 
 #### MODE Options
-- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
-- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
+- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini)
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
 
 ### Codex
 - **Command**: `codex --full-auto exec`
@@ -149,13 +150,13 @@ RULES: [template reference and constraints]
 
 #### Qwen Commands
 ```bash
-# Qwen Architecture Analysis (read-only, default)
+# Qwen Analysis (read-only, default) - Same as Gemini, use as fallback
 cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [clear architecture goal]
+PURPOSE: [clear analysis goal]
 TASK: [specific analysis task]
 MODE: analysis
 CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
+EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 
@@ -166,7 +167,7 @@ PURPOSE: [clear goal]
 TASK: [specific task]
 MODE: write
 CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
+EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 ```
@@ -256,14 +257,13 @@ RULES: Focus on type safety and component composition
 
 | 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
 
@@ -302,9 +302,9 @@ tech-stacks/
 ### 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
@@ -333,8 +333,19 @@ RULES: Follow project documentation standards
 "
 ```
 
-#### Architecture Analysis
+#### 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
+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
+"
+
+# 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
@@ -419,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

.claude/workflows/task-core.md

@@ -42,11 +42,17 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement comprehensive JWT authentication system...",
-      "modification_points": ["Add JWT token generation...", "..."],
-      "logic_flow": ["User login request → validate credentials...", "..."]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement JWT authentication system",
+        "description": "Implement comprehensive JWT authentication system with token generation, validation, and refresh logic",
+        "modification_points": ["Add JWT token generation", "Implement token validation middleware", "Create refresh token logic"],
+        "logic_flow": ["User login request → validate credentials", "Generate JWT access and refresh tokens", "Store refresh token securely", "Return tokens to client"],
+        "depends_on": [],
+        "output": "jwt_implementation"
+      }
+    ],
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
       "src/middleware/auth.ts:validateToken",

.claude/workflows/tool-control.yaml

@@ -0,0 +1,10 @@
+# Tool Control Configuration
+# Controls whether CLI tools (Gemini, Qwen, Codex) are enabled in the workspace
+
+tools:
+  gemini:
+    enabled: true
+  qwen:
+    enabled: true
+  codex:
+    enabled: true

.claude/workflows/workflow-architecture.md

@@ -162,17 +162,61 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
         "output_to": "context"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement JWT authentication following [design]",
-      "modification_points": [
-        "Add JWT generation using [parent] patterns",
-        "Implement validation middleware from [context]"
-      ],
-      "logic_flow": [
-        "User login → validate with [inherited] → generate JWT",
-        "Protected route → extract JWT → validate using [shared] rules"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Set up authentication infrastructure",
+        "description": "Install JWT library and create auth config following [design] patterns from [parent]",
+        "modification_points": [
+          "Add JWT library dependencies to package.json",
+          "Create auth configuration file using [parent] patterns"
+        ],
+        "logic_flow": [
+          "Install jsonwebtoken library via npm",
+          "Configure JWT secret and expiration from [inherited]",
+          "Export auth config for use by [jwt_generator]"
+        ],
+        "depends_on": [],
+        "output": "auth_config"
+      },
+      {
+        "step": 2,
+        "title": "Implement JWT generation",
+        "description": "Create JWT token generation logic using [auth_config] and [inherited] validation patterns",
+        "modification_points": [
+          "Add JWT generation function in auth service",
+          "Implement token signing with [auth_config]"
+        ],
+        "logic_flow": [
+          "User login → validate credentials with [inherited]",
+          "Generate JWT payload with user data",
+          "Sign JWT using secret from [auth_config]",
+          "Return signed token"
+        ],
+        "depends_on": [1],
+        "output": "jwt_generator"
+      },
+      {
+        "step": 3,
+        "title": "Implement JWT validation middleware",
+        "description": "Create middleware to validate JWT tokens using [auth_config] and [shared] rules",
+        "modification_points": [
+          "Create validation middleware using [jwt_generator]",
+          "Add token verification using [shared] rules",
+          "Implement user attachment to request object"
+        ],
+        "logic_flow": [
+          "Protected route → extract JWT from Authorization header",
+          "Validate token signature using [auth_config]",
+          "Check token expiration and [shared] rules",
+          "Decode payload and attach user to request",
+          "Call next() or return 401 error"
+        ],
+        "command": "bash(npm test -- middleware.test.ts)",
+        "depends_on": [1, 2],
+        "output": "auth_middleware"
+      }
+    ],
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
       "src/middleware/auth.ts:validateToken",
@@ -208,33 +252,329 @@ Optional field referencing brainstorming outputs for task execution:
 **Types & Priority**: synthesis_specification (highest) → topic_framework (medium) → individual_role_analysis (low)
 
 #### Flow Control Configuration
-The **flow_control** field manages task execution with two main components:
+The **flow_control** field manages task execution through structured sequential steps. For complete format specifications and usage guidelines, see [Flow Control Format Guide](#flow-control-format-guide) below.
 
-**pre_analysis** - Context gathering phase:
-- **Flexible commands**: Supports multiple tool types (see Tool Reference below)
-- **Step structure**: Each step has `step`, `action`, `command` fields
-- **Variable accumulation**: Steps can reference previous outputs via `[variable_name]`
-- **Error handling**: `skip_optional`, `fail`, `retry_once`, `manual_intervention`
+**Quick Reference**:
+- **pre_analysis**: Context gathering steps (supports multiple command types)
+- **implementation_approach**: Implementation steps array with dependency management
+- **target_files**: Target files for modification (file:function:lines format)
+- **Variable references**: Use `[variable_name]` to reference step outputs
+- **Tool integration**: Supports Gemini, Codex, Bash commands, and MCP tools
 
-**implementation_approach** - Implementation definition:
-- **task_description**: Comprehensive implementation description
-- **modification_points**: Specific code modification targets
-- **logic_flow**: Business logic execution sequence
-- **target_files**: Target file list - existing files in `file:function:lines` format, new files as `file` only
+## Flow Control Format Guide
 
-#### Tool Reference
-**Command Types Available**:
-- **Gemini CLI**: `~/.claude/scripts/gemini-wrapper -p "prompt"`
-- **Codex CLI**: `codex --full-auto exec "task" -s danger-full-access`
-- **Built-in Tools**: `grep(pattern)`, `glob(pattern)`, `search(query)`
-- **Bash Commands**: `bash(rg 'pattern' src/)`, `bash(find . -name "*.ts")`
+The `[FLOW_CONTROL]` marker indicates that a task or prompt contains flow control steps for sequential execution. There are **two distinct formats** used in different scenarios:
 
-#### Variable System & Context Flow
-**Flow Control Variables**: Use `[variable_name]` format for dynamic content:
+### Format Comparison Matrix
+
+| Aspect | Inline Format | JSON Format |
+|--------|--------------|-------------|
+| **Used In** | Brainstorm workflows | Implementation tasks |
+| **Agent** | conceptual-planning-agent | code-developer, test-fix-agent, doc-generator |
+| **Location** | Task() prompt (markdown) | .task/IMPL-*.json file |
+| **Persistence** | Temporary (prompt-only) | Persistent (file storage) |
+| **Complexity** | Simple (3-5 steps) | Complex (10+ steps) |
+| **Dependencies** | None | Full `depends_on` support |
+| **Purpose** | Load brainstorming context | Implement task with preparation |
+
+### Inline Format (Brainstorm)
+
+**Marker**: `[FLOW_CONTROL]` written directly in Task() prompt
+
+**Structure**: Markdown list format
+
+**Used By**: Brainstorm commands (`auto-parallel.md`, role commands)
+
+**Agent**: `conceptual-planning-agent`
+
+**Example**:
+```markdown
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
+
+1. **load_topic_framework**
+   - Action: Load structured topic discussion framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Output: topic_framework
+
+2. **load_role_template**
+   - Action: Load role-specific planning template
+   - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
+   - Output: role_template
+
+3. **load_session_metadata**
+   - Action: Load session metadata and topic description
+   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json 2>/dev/null || echo '{}')
+   - Output: session_metadata
+```
+
+**Characteristics**:
+- 3-5 simple context loading steps
+- Written directly in prompt (not persistent)
+- No dependency management between steps
+- Used for temporary context preparation
+- Variables: `[variable_name]` for output references
+
+### JSON Format (Implementation)
+
+**Marker**: `[FLOW_CONTROL]` used in TodoWrite or documentation to indicate task has flow control
+
+**Structure**: Complete JSON structure in task file
+
+**Used By**: Implementation tasks (IMPL-*.json)
+
+**Agents**: `code-developer`, `test-fix-agent`, `doc-generator`
+
+**Example**:
+```json
+"flow_control": {
+  "pre_analysis": [
+    {
+      "step": "load_synthesis_specification",
+      "action": "Load consolidated synthesis specification",
+      "commands": [
+        "bash(ls .workflow/WFS-{session}/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')",
+        "Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)"
+      ],
+      "output_to": "synthesis_specification",
+      "on_error": "skip_optional"
+    },
+    {
+      "step": "mcp_codebase_exploration",
+      "action": "Explore codebase using MCP",
+      "command": "mcp__code-index__find_files(pattern=\"*.ts\") && mcp__code-index__search_code_advanced(pattern=\"auth\")",
+      "output_to": "codebase_structure"
+    }
+  ],
+  "implementation_approach": [
+    {
+      "step": 1,
+      "title": "Setup infrastructure",
+      "description": "Install JWT library and create config following [synthesis_specification]",
+      "modification_points": [
+        "Add JWT library dependencies to package.json",
+        "Create auth configuration file"
+      ],
+      "logic_flow": [
+        "Install jsonwebtoken library via npm",
+        "Configure JWT secret from [synthesis_specification]",
+        "Export auth config for use by [jwt_generator]"
+      ],
+      "depends_on": [],
+      "output": "auth_config"
+    },
+    {
+      "step": 2,
+      "title": "Implement JWT generation",
+      "description": "Create JWT token generation logic using [auth_config]",
+      "modification_points": [
+        "Add JWT generation function in auth service",
+        "Implement token signing with [auth_config]"
+      ],
+      "logic_flow": [
+        "User login → validate credentials",
+        "Generate JWT payload with user data",
+        "Sign JWT using secret from [auth_config]",
+        "Return signed token"
+      ],
+      "depends_on": [1],
+      "output": "jwt_generator"
+    }
+  ],
+  "target_files": [
+    "src/auth/login.ts:handleLogin:75-120",
+    "src/middleware/auth.ts:validateToken"
+  ]
+}
+```
+
+**Characteristics**:
+- Persistent storage in .task/IMPL-*.json files
+- Complete dependency management (`depends_on` arrays)
+- Two-phase structure: `pre_analysis` + `implementation_approach`
+- Error handling strategies (`on_error` field)
+- Target file specifications
+- Variables: `[variable_name]` for cross-step references
+
+### JSON Format Field Specifications
+
+#### pre_analysis Field
+**Purpose**: Context gathering phase before implementation
+
+**Structure**: Array of step objects with sequential execution
+
+**Step Fields**:
+- **step**: Step identifier (string, e.g., "load_synthesis_specification")
+- **action**: Human-readable description of the step
+- **command** or **commands**: Single command string or array of command strings
+- **output_to**: Variable name for storing step output
+- **on_error**: Error handling strategy (`skip_optional`, `fail`, `retry_once`, `manual_intervention`)
+
+**Command Types Supported**:
+- **Bash commands**: `bash(command)` - Any shell command
+- **Tool calls**: `Read(file)`, `Glob(pattern)`, `Grep(pattern)`
+- **MCP tools**: `mcp__code-index__find_files()`, `mcp__exa__get_code_context_exa()`
+- **CLI wrappers**: `~/.claude/scripts/gemini-wrapper`, `codex --full-auto exec`
+
+**Example**:
+```json
+{
+  "step": "load_context",
+  "action": "Load project context and patterns",
+  "commands": [
+    "bash(~/.claude/scripts/get_modules_by_depth.sh)",
+    "Read(CLAUDE.md)"
+  ],
+  "output_to": "project_structure",
+  "on_error": "skip_optional"
+}
+```
+
+#### implementation_approach Field
+**Purpose**: Define implementation steps with dependency management
+
+**Structure**: Array of step objects (NOT object format)
+
+**Step Fields (All Required)**:
+- **step**: Unique step number (1, 2, 3, ...) - serves as step identifier
+- **title**: Brief step title
+- **description**: Comprehensive implementation description with context variable references
+- **modification_points**: Array of specific code modification targets
+- **logic_flow**: Array describing business logic execution sequence
+- **depends_on**: Array of step numbers this step depends on (e.g., `[1]`, `[1, 2]`) - empty array `[]` for independent steps
+- **output**: Output variable name that can be referenced by subsequent steps via `[output_name]`
+
+**Optional Fields**:
+- **command**: Command for step execution (supports any shell command or CLI tool)
+  - When omitted: Agent interprets modification_points and logic_flow to execute
+  - When specified: Command executes the step directly
+
+**Execution Modes**:
+- **Default (without command)**: Agent executes based on modification_points and logic_flow
+- **With command**: Specified command handles execution
+
+**Command Field Usage**:
+- **Default approach**: Omit command field - let agent execute autonomously
+- **CLI tools (codex/gemini/qwen)**: Add ONLY when user explicitly requests CLI tool usage
+- **Simple commands**: Can include bash commands, test commands, validation scripts
+- **Complex workflows**: Use command for multi-step operations or tool coordination
+
+**Command Format Examples** (only when explicitly needed):
+```json
+// Simple Bash
+"command": "bash(npm install package)"
+"command": "bash(npm test)"
+
+// Validation
+"command": "bash(test -f config.ts && grep -q 'JWT_SECRET' config.ts)"
+
+// Codex (user requested)
+"command": "codex -C path --full-auto exec \"task\" --skip-git-repo-check -s danger-full-access"
+
+// Codex Resume (user requested, maintains context)
+"command": "codex --full-auto exec \"task\" resume --last --skip-git-repo-check -s danger-full-access"
+
+// Gemini (user requested)
+"command": "~/.claude/scripts/gemini-wrapper -p \"analyze [context]\""
+
+// Qwen (fallback for Gemini)
+"command": "~/.claude/scripts/qwen-wrapper -p \"analyze [context]\""
+```
+
+**Example Step**:
+```json
+{
+  "step": 2,
+  "title": "Implement JWT generation",
+  "description": "Create JWT token generation logic using [auth_config]",
+  "modification_points": [
+    "Add JWT generation function in auth service",
+    "Implement token signing with [auth_config]"
+  ],
+  "logic_flow": [
+    "User login → validate credentials",
+    "Generate JWT payload with user data",
+    "Sign JWT using secret from [auth_config]",
+    "Return signed token"
+  ],
+  "depends_on": [1],
+  "output": "jwt_generator"
+}
+```
+
+#### target_files Field
+**Purpose**: Specify files to be modified or created
+
+**Format**: Array of strings
+- **Existing files**: `"file:function:lines"` (e.g., `"src/auth/login.ts:handleLogin:75-120"`)
+- **New files**: `"path/to/NewFile.ts"` (file path only)
+
+### Tool Reference
+
+**Available Command Types**:
+
+**Gemini CLI**:
+```bash
+~/.claude/scripts/gemini-wrapper -p "prompt"
+~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "prompt"  # For write mode
+```
+
+**Qwen CLI** (Gemini fallback):
+```bash
+~/.claude/scripts/qwen-wrapper -p "prompt"
+~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "prompt"  # For write mode
+```
+
+**Codex CLI**:
+```bash
+codex -C directory --full-auto exec "task" --skip-git-repo-check -s danger-full-access
+codex --full-auto exec "task" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+**Built-in Tools**:
+- `Read(file_path)` - Read file contents
+- `Glob(pattern)` - Find files by pattern
+- `Grep(pattern)` - Search content with regex
+- `bash(command)` - Execute bash command
+
+**MCP Tools**:
+- `mcp__code-index__find_files(pattern="*.ts")` - Find files using code index
+- `mcp__code-index__search_code_advanced(pattern="auth")` - Search code patterns
+- `mcp__exa__get_code_context_exa(query="...")` - Get code context from Exa
+- `mcp__exa__web_search_exa(query="...")` - Web search via Exa
+
+**Bash Commands**:
+```bash
+bash(rg 'pattern' src/)
+bash(find . -name "*.ts")
+bash(npm test)
+bash(git log --oneline | head -5)
+```
+
+### Variable System & Context Flow
+
+**Variable Reference Syntax**:
+Both formats use `[variable_name]` syntax for referencing outputs from previous steps.
+
+**Variable Types**:
 - **Step outputs**: `[step_output_name]` - Reference any pre_analysis step output
 - **Task properties**: `[task_property]` - Reference any task context field
 - **Previous results**: `[analysis_result]` - Reference accumulated context
-- **Commands**: All commands wrapped with appropriate error handling
+- **Implementation outputs**: Reference outputs from previous implementation steps
+
+**Examples**:
+```json
+// Reference pre_analysis output
+"description": "Install JWT library following [synthesis_specification]"
+
+// Reference previous step output
+"description": "Create middleware using [auth_config] and [jwt_generator]"
+
+// Reference task context
+"command": "bash(cd [focus_paths] && npm test)"
+```
 
 **Context Accumulation Process**:
 1. **Structure Analysis**: `get_modules_by_depth.sh` → project hierarchy
@@ -248,16 +588,76 @@ The **flow_control** field manages task execution with two main components:
 - **Session → Task**: Global session context included in all tasks
 - **Module → Feature**: Module patterns inform feature implementation
 
+### Agent Processing Rules
+
+**conceptual-planning-agent** (Inline Format):
+- Parses markdown list from prompt
+- Executes 3-5 simple loading steps
+- No dependency resolution needed
+- Accumulates context in variables
+- Used only in brainstorm workflows
+
+**code-developer, test-fix-agent** (JSON Format):
+- Loads complete task JSON from file
+- Executes `pre_analysis` steps sequentially
+- Processes `implementation_approach` with dependency resolution
+- Handles complex variable substitution
+- Updates task status in JSON file
+
+### Usage Guidelines
+
+**Use Inline Format When**:
+- Running brainstorm workflows
+- Need 3-5 simple context loading steps
+- No persistence required
+- No dependencies between steps
+- Temporary context preparation
+
+**Use JSON Format When**:
+- Implementing features or tasks
+- Need 10+ complex execution steps
+- Require dependency management
+- Need persistent task definitions
+- Complex variable flow between steps
+- Error handling strategies needed
+
+### Variable Reference Syntax
+
+Both formats use `[variable_name]` syntax for referencing outputs:
+
+**Inline Format**:
+```markdown
+2. **analyze_context**
+   - Action: Analyze using [topic_framework] and [role_template]
+   - Output: analysis_results
+```
+
+**JSON Format**:
+```json
+{
+  "step": 2,
+  "description": "Implement following [synthesis_specification] and [codebase_structure]",
+  "depends_on": [1],
+  "output": "implementation"
+}
+```
+
 ### Task Validation Rules
 1. **ID Uniqueness**: All task IDs must be unique
 2. **Hierarchical Format**: Must follow IMPL-N[.M] pattern (maximum 2 levels)
 3. **Parent References**: All parent IDs must exist as JSON files
 4. **Status Consistency**: Status values from defined enumeration
-5. **Required Fields**: All 5 core fields must be present
+5. **Required Fields**: All 5 core fields must be present (id, title, status, meta, context, flow_control)
 6. **Focus Paths Structure**: context.focus_paths must contain concrete paths (no wildcards)
 7. **Flow Control Format**: pre_analysis must be array with required fields
-8. **Dependency Integrity**: All depends_on task IDs must exist as JSON files
+8. **Dependency Integrity**: All task-level depends_on references must exist as JSON files
 9. **Artifacts Structure**: context.artifacts (optional) must use valid type, priority, and path format
+10. **Implementation Steps Array**: implementation_approach must be array of step objects
+11. **Step Number Uniqueness**: All step numbers within a task must be unique and sequential (1, 2, 3, ...)
+12. **Step Dependencies**: All step-level depends_on numbers must reference valid steps within same task
+13. **Step Sequence**: Step numbers should match array order (first item step=1, second item step=2, etc.)
+14. **Step Required Fields**: Each step must have step, title, description, modification_points, logic_flow, depends_on, output
+15. **Step Optional Fields**: command field is optional - when omitted, agent executes based on modification_points and logic_flow
 
 ## Workflow Structure
 

CHANGELOG.md

@@ -5,6 +5,680 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.4.1] - 2025-10-12
+
+### 🔧 Implementation Approach Structure Refactoring
+
+This release refactors the task generation system from a simple object-based implementation approach to a structured step-based approach with dependency management and CLI execution support.
+
+#### Changed
+
+**Implementation Approach Structure** (Major Refactoring):
+- **Array Format**: Changed from single object to array of step objects
+  - Before (v4.4.0): Single `implementation_approach` object with description
+  - After (v4.4.1): Array of steps with sequential execution and dependencies
+- **Step Structure**: Each step now includes:
+  - `step`: Step number (1, 2, 3...)
+  - `title`: Step title
+  - `description`: Detailed description with variable references
+  - `modification_points`: Specific modification targets
+  - `logic_flow`: Business logic sequence
+  - `command`: Optional CLI command for execution
+  - `depends_on`: Array of step numbers (dependencies)
+  - `output`: Variable name for step output (used in `[variable_name]` references)
+- **Benefits**:
+  - ✅ Multi-step workflows with clear dependencies
+  - ✅ Variable substitution between steps (`[variable_name]`)
+  - ✅ Better task decomposition clarity
+  - ✅ Sequential execution with dependency resolution
+
+**CLI Execution Mode Support**:
+- **New `--cli-execute` Flag**: Added to workflow commands
+  - `/workflow:plan --cli-execute` - Generate tasks with CLI execution
+  - `/workflow:test-gen --cli-execute` - Generate test tasks with CLI execution
+  - `/workflow:tools:task-generate --cli-execute` - Manual task generation with CLI
+  - `/workflow:tools:task-generate-agent --cli-execute` - Agent task generation with CLI
+  - `/workflow:tools:test-task-generate --cli-execute` - Test task generation with CLI
+- **Codex Resume Mechanism**: Maintains session context across steps
+  - First step: `codex exec "..."` (starts new session)
+  - Subsequent steps: `codex exec "..." resume --last` (continues session)
+  - Benefits: Context continuity, consistent implementation style
+
+**Agent Updates**:
+- **action-planning-agent.md**: Updated task generation with step-based approach
+- **code-developer.md**: Added implementation approach execution logic
+- **conceptual-planning-agent.md**: Added flow control format handling documentation
+- **doc-generator.md**: Updated to process step-based implementation approach
+- **test-fix-agent.md**: Added flow control execution and Codex mode support
+
+**Workflow Command Updates**:
+- **execute.md**: Updated task JSON examples with new structure
+- **plan.md**: Added `--cli-execute` flag and command examples
+- **test-gen.md**: Added `--cli-execute` flag support
+- **docs.md**: Refactored from 1328 to 435 lines (67% reduction)
+- **task-generate-agent.md**: Updated to generate step-based tasks
+- **task-generate-tdd.md**: Enhanced with array format and CLI execution
+- **task-generate.md**: Added CLI execution mode documentation
+- **test-task-generate.md**: Added CLI execution mode support
+
+**Core Architecture Updates**:
+- **task-core.md**: Updated implementation approach structure
+- **workflow-architecture.md**: Enhanced with flow control documentation (474 lines added)
+
+#### Technical Details
+
+**Step Execution Flow**:
+```javascript
+// Old approach (v4.4.0)
+"implementation_approach": {
+  "task_description": "Implement feature X",
+  "modification_points": ["File A", "File B"],
+  "logic_flow": ["Step 1", "Step 2"]
+}
+
+// New approach (v4.4.1)
+"implementation_approach": [
+  {
+    "step": 1,
+    "title": "Load requirements",
+    "description": "Load and analyze [previous_output]",
+    "modification_points": ["Parse requirements"],
+    "logic_flow": ["Read input", "Extract data"],
+    "depends_on": [],
+    "output": "requirements"
+  },
+  {
+    "step": 2,
+    "title": "Implement feature",
+    "description": "Implement using [requirements]",
+    "modification_points": ["File A", "File B"],
+    "logic_flow": ["Apply changes", "Validate"],
+    "command": "codex exec '...' resume --last",
+    "depends_on": [1],
+    "output": "implementation"
+  }
+]
+```
+
+**CLI Command Examples**:
+```bash
+# Manual task generation with CLI execution
+/workflow:tools:task-generate --session WFS-auth --cli-execute
+
+# Agent task generation with CLI execution
+/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+
+# Test task generation with CLI execution
+/workflow:tools:test-task-generate --session WFS-test --cli-execute
+
+# Full planning workflow with CLI execution
+/workflow:plan "Implement auth system" --cli-execute
+```
+
+#### Files Changed
+
+**Agents** (5 files):
+- `.claude/agents/action-planning-agent.md`
+- `.claude/agents/code-developer.md`
+- `.claude/agents/conceptual-planning-agent.md`
+- `.claude/agents/doc-generator.md`
+- `.claude/agents/test-fix-agent.md`
+
+**Commands** (7 files):
+- `.claude/commands/workflow/execute.md`
+- `.claude/commands/workflow/plan.md`
+- `.claude/commands/workflow/test-gen.md`
+- `.claude/commands/workflow/tools/docs.md` (major refactoring: 1328→435 lines)
+- `.claude/commands/workflow/tools/task-generate-agent.md`
+- `.claude/commands/workflow/tools/task-generate-tdd.md`
+- `.claude/commands/workflow/tools/task-generate.md`
+- `.claude/commands/workflow/tools/test-task-generate.md`
+
+**Core Architecture** (2 files):
+- `.claude/workflows/task-core.md`
+- `.claude/workflows/workflow-architecture.md` (+474 lines of flow control documentation)
+
+**Total Impact**:
+- 15 files changed
+- +1341 lines, -782 lines
+- Net: +559 lines
+- Major improvements in task generation clarity and CLI execution support
+
+#### Migration Guide
+
+**For Existing Workflows**:
+1. **Backward Compatible**: Old object-based approach still supported
+2. **Gradual Migration**: Can mix old and new formats in same workflow
+3. **Automatic Handling**: Agents detect and handle both formats
+
+**For New Workflows**:
+1. **Use Step-Based Approach**: Better for multi-step tasks
+2. **Enable CLI Execution**: Use `--cli-execute` flag for automated execution
+3. **Leverage Resume**: Use Codex resume for context continuity
+
+**Example Migration**:
+```bash
+# Old workflow (v4.4.0)
+/workflow:plan "Implement auth system"
+
+# New workflow (v4.4.1) - with CLI execution
+/workflow:plan "Implement auth system" --cli-execute
+```
+
+#### Benefits
+
+**Task Generation**:
+- 🎯 **Clearer Structure**: Step-based approach improves task clarity
+- 🔄 **Better Dependencies**: Explicit dependency management between steps
+- 📊 **Variable References**: Cross-step data flow with `[variable_name]`
+- 🤖 **Automated Execution**: CLI execution mode reduces manual intervention
+
+**Development Workflow**:
+- ⚡ **Faster Execution**: Codex resume maintains context
+- 🔍 **Better Traceability**: Each step's output explicitly tracked
+- 🧪 **Easier Testing**: Isolated steps can be tested independently
+- 📚 **Improved Documentation**: Flow control structure self-documenting
+
+---
+
+## [4.4.0] - 2025-10-11
+
+### 🏗️ UI Design Workflow V3 - Layout/Style Separation Architecture
+
+This release introduces a fundamental architectural refactoring that separates layout structure extraction from style token extraction, enabling the `generate` command to become a pure assembler.
+
+#### Breaking Changes
+
+**Command Renaming**:
+```bash
+# ❌ Old (v4.3.0 and earlier)
+/workflow:ui-design:extract
+
+# ✅ New (v4.4.0)
+/workflow:ui-design:style-extract
+```
+
+**New Required Command**:
+- **`/workflow:ui-design:layout-extract`**: Now mandatory for workflows using `generate`
+- Layout templates must be generated before prototype assembly
+- Both `imitate-auto` and `explore-auto` now include Phase 2.5 (layout extraction)
+
+**Workflow Changes**:
+```bash
+# ❌ Old Flow (v4.3.0)
+style-extract → consolidate → generate → update
+
+# ✅ New Flow (v4.4.0)
+style-extract → consolidate → layout-extract → generate (assembler) → update
+```
+
+#### Added
+
+**New Command: `/workflow:ui-design:layout-extract`**:
+- **Purpose**: Extract structural layout information separate from visual style
+- **Features**:
+  - Agent-powered structural analysis using `ui-design-agent`
+  - Dual-mode operation: `imitate` (high-fidelity replication) / `explore` (multiple variants)
+  - Device-aware layouts: desktop, mobile, tablet, responsive
+  - Generates `layout-templates.json` with DOM structure and CSS layout rules
+  - MCP-integrated layout pattern research (explore mode only)
+  - Token-based CSS using `var()` placeholders for spacing and breakpoints
+- **Output**: `layout-extraction/layout-templates.json` with:
+  - DOM structure (semantic HTML5 with ARIA)
+  - Component hierarchy (high-level layout regions)
+  - CSS layout rules (Grid/Flexbox, no visual styling)
+  - Device-specific structures and responsive breakpoints
+
+**Enhanced Layout Extraction Architecture**:
+```json
+{
+  "layout_templates": [
+    {
+      "target": "home",
+      "variant_id": "layout-1",
+      "device_type": "responsive",
+      "design_philosophy": "3-column holy grail with fixed header",
+      "dom_structure": { /* JSON object */ },
+      "component_hierarchy": ["header", "main", "sidebar", "footer"],
+      "css_layout_rules": "/* Grid/Flexbox only, uses var() */"
+    }
+  ]
+}
+```
+
+**Device-Aware Layout Generation**:
+- **Desktop**: 1920×1080px - Multi-column grids, spacious layouts
+- **Mobile**: 375×812px - Single column, stacked sections, touch targets ≥44px
+- **Tablet**: 768×1024px - Hybrid layouts, flexible columns
+- **Responsive**: Mobile-first breakpoint-driven adaptive layouts
+
+**MCP Integration (Explore Mode)**:
+- `mcp__exa__web_search_exa` for layout pattern inspiration
+- Pattern research: `{target} layout patterns {device_type}`
+- Inspiration files: `layout-extraction/_inspirations/{target}-layout-ideas.txt`
+
+#### Changed
+
+**`/workflow:ui-design:style-extract` (Renamed from `extract`)**:
+- **File Renamed**: `extract.md` → `style-extract.md`
+- **Scope Clarified**: Focus exclusively on visual style (colors, typography, spacing)
+- **Documentation Updated**: Added note about layout extraction separation
+- **No Functionality Change**: All style extraction features preserved
+- **Output**: Still generates `style-cards.json` with `proposed_tokens`
+
+**`/workflow:ui-design:generate` (Refactored to Pure Assembler)**:
+- **Before (v4.3.0)**: Layout design + style application agent
+  - Agent made layout decisions during generation
+  - Mixed structural and visual responsibilities
+  - CSS contained both layout and style rules
+
+- **After (v4.4.0)**: Pure assembly only
+  - **Reads**: `layout-templates.json` + `design-tokens.json`
+  - **Action**: Combines pre-extracted components:
+    1. Build HTML from `dom_structure`
+    2. Apply `css_layout_rules` (structure)
+    3. Link design tokens CSS (visual style)
+    4. Inject placeholder content
+  - **No Design Logic**: All layout and style decisions pre-made
+  - **Agent Prompt Updated**: Removed layout design instructions
+
+**Agent Instructions Simplification** (`generate.md`):
+```javascript
+// ❌ Old (v4.3.0): Agent designs layout + applies style
+Agent: "Design page layout based on requirements, then apply design tokens"
+
+// ✅ New (v4.4.0): Agent only assembles
+Agent: "
+  [LAYOUT_STYLE_ASSEMBLY]
+  Read layout-templates.json → Extract dom_structure, css_layout_rules
+  Read design-tokens.json → Extract ALL token values
+  Build HTML from dom_structure
+  Build CSS from css_layout_rules + token values
+  Write files IMMEDIATELY
+"
+```
+
+**Workflow Commands Updated**:
+- **`/workflow:ui-design:imitate-auto`**:
+  - Added Phase 2.5: Layout Extraction (imitate mode, single variant)
+  - Generates `layout-templates.json` before Phase 4 (UI Assembly)
+  - Uses `--mode imitate` for high-fidelity layout replication
+
+- **`/workflow:ui-design:explore-auto`**:
+  - Added Phase 2.5: Layout Extraction (explore mode, multiple variants)
+  - Generates `{targets × layout_variants}` layout templates
+  - Uses `--mode explore` for structural variety
+  - MCP-powered layout pattern research
+
+**Output Structure Changes**:
+```
+{base_path}/
+├── style-extraction/         # Visual tokens (unchanged)
+│   └── style-cards.json
+├── layout-extraction/        # NEW: Structural templates
+│   ├── layout-templates.json
+│   ├── layout-space-analysis.json (explore mode)
+│   └── _inspirations/ (explore mode)
+├── style-consolidation/      # Final design tokens (unchanged)
+│   └── style-1/
+│       └── design-tokens.json
+└── prototypes/               # Assembled output (unchanged)
+    └── {target}-style-{s}-layout-{l}.html
+```
+
+#### Improved
+
+**Separation of Concerns**:
+- 🎨 **Style (style-extract)**: Colors, typography, spacing → design-tokens.json
+- 🏗️ **Layout (layout-extract)**: DOM structure, CSS layout → layout-templates.json
+- 📦 **Assembly (generate)**: Combine structure + style → final prototypes
+- ✅ **Result**: Each phase has single, clear responsibility
+
+**Quality Improvements**:
+- 🎯 **Better Layout Variety**: Explore mode generates structurally distinct layouts
+- 🔄 **Reusability**: Layout templates can be combined with different styles
+- 📊 **Clarity**: All structural decisions in layout-templates.json
+- 🧪 **Testability**: Layout structure and visual style tested independently
+
+**Performance Benefits**:
+- ⚡ **Faster Generation**: Assembly is simpler than design + application
+- 🔄 **Better Caching**: Layout templates reused across style variants
+- 📉 **Reduced Complexity**: Generate agent has single responsibility
+
+#### Technical Details
+
+**Phase Flow Comparison**:
+
+**Old Flow (v4.3.0)**:
+```
+Phase 1: style-extract → style-cards.json
+Phase 2: consolidate → design-tokens.json
+Phase 3: generate (design+apply) → prototypes
+Phase 4: update
+```
+
+**New Flow (v4.4.0)**:
+```
+Phase 1: style-extract → style-cards.json
+Phase 2: consolidate → design-tokens.json
+Phase 2.5: layout-extract → layout-templates.json  [NEW]
+Phase 3: generate (pure assembly) → prototypes
+Phase 4: update
+```
+
+**Agent Task Changes**:
+
+**Before (Mixed Responsibility)**:
+```javascript
+Agent Task: "
+  Design page layout for {target}
+  Apply design tokens from design-tokens.json
+  Generate HTML + CSS
+"
+// Problems:
+// - Layout decisions made during generation
+// - Style application mixed with structure
+// - Agent has dual responsibility
+```
+
+**After (Pure Assembly)**:
+```javascript
+Agent Task: "
+  [LAYOUT_STYLE_ASSEMBLY]
+  INPUT 1: layout-templates.json → dom_structure, css_layout_rules
+  INPUT 2: design-tokens.json → token values
+
+  ASSEMBLY:
+  1. Build HTML from dom_structure
+  2. Build CSS from css_layout_rules (replace var())
+  3. Add visual styling using token values
+  4. Write files IMMEDIATELY
+
+  RULES:
+  ✅ Pure assembly only
+  ❌ NO layout design decisions
+  ❌ NO style design decisions
+"
+```
+
+**Layout Template Structure**:
+```json
+{
+  "target": "home",
+  "variant_id": "layout-1",
+  "device_type": "responsive",
+  "design_philosophy": "F-pattern with sticky nav",
+  "dom_structure": {
+    "tag": "body",
+    "children": [
+      {"tag": "header", "attributes": {"class": "layout-header"}},
+      {"tag": "main", "attributes": {"class": "layout-main"}},
+      {"tag": "footer", "attributes": {"class": "layout-footer"}}
+    ]
+  },
+  "component_hierarchy": ["header", "main", "footer"],
+  "css_layout_rules": ".layout-main { display: grid; grid-template-columns: 1fr 3fr; gap: var(--spacing-6); }"
+}
+```
+
+**Token-Based CSS Pattern**:
+```css
+/* Layout rules use var() for spacing/breakpoints */
+.layout-wrapper {
+  display: grid;
+  gap: var(--spacing-4);
+  padding: var(--spacing-8);
+}
+
+@media (max-width: var(--breakpoint-md)) {
+  .layout-wrapper {
+    grid-template-columns: 1fr;
+  }
+}
+```
+
+#### Migration Guide
+
+**For Existing Workflows**:
+1. **Update Command Names**:
+   ```bash
+   # Old: /workflow:ui-design:extract
+   # New: /workflow:ui-design:style-extract
+   ```
+
+2. **Add Layout Extraction Step**:
+   ```bash
+   # After consolidate, before generate:
+   /workflow:ui-design:layout-extract --session WFS-xxx --targets "dashboard,settings" --mode explore --variants 3
+   ```
+
+3. **Update Orchestrator Workflows**:
+   - `imitate-auto`: Automatically includes Phase 2.5
+   - `explore-auto`: Automatically includes Phase 2.5
+   - Manual workflows: Add `layout-extract` call
+
+**Backward Compatibility**:
+- ✅ Old `extract` command files archived (not deleted)
+- ✅ New `style-extract` command name explicit and clear
+- ✅ All output structures backward compatible
+- ⚠️ **Breaking**: `generate` now requires `layout-templates.json` input
+
+**For New Projects**:
+- Use new workflow: `style-extract → consolidate → layout-extract → generate → update`
+- Leverage layout variants: `--layout-variants` in explore-auto
+- Device-specific layouts: `--device-type` parameter
+
+#### Files Changed
+
+**Renamed**:
+- `.claude/commands/workflow/ui-design/extract.md` → `style-extract.md`
+
+**Added**:
+- `.claude/commands/workflow/ui-design/layout-extract.md` (new command, 370+ lines)
+
+**Modified**:
+- `.claude/commands/workflow/ui-design/generate.md`:
+  - Refactored to pure assembler (agent instructions simplified)
+  - Added Phase 2: Load Layout Templates
+  - Updated agent prompt to focus on assembly only
+  - Documentation updates for separation of concerns
+
+- `.claude/commands/workflow/ui-design/imitate-auto.md`:
+  - Added Phase 2.5: Layout Extraction (imitate mode)
+  - Updated workflow orchestration
+  - Phase numbering shifted (old Phase 3 → Phase 4)
+
+- `.claude/commands/workflow/ui-design/explore-auto.md`:
+  - Added Phase 2.5: Layout Extraction (explore mode)
+  - Updated workflow orchestration
+  - Matrix calculation updated: `style_variants × layout_variants × targets`
+  - Phase numbering shifted (old Phase 3 → Phase 4)
+
+- `.claude/commands/workflow/ui-design/consolidate.md`:
+  - Documentation updates
+  - Note added about layout-extract requirement
+
+**Removed**:
+- ❌ **V2 Commands Deprecated**: All `-v2` command variants removed
+  - `generate-v2.md` removed (merged into main `generate.md`)
+  - `explore-auto-v2.md` removed (merged into main `explore-auto.md`)
+  - Self-contained CSS architecture now standard in all commands
+  - No more v1/v2 split - unified workflow
+
+**Total Impact**:
+- 5 files changed
+- 1 file renamed
+- 1 new command (layout-extract, 370+ lines)
+- 2 deprecated commands removed (generate-v2, explore-auto-v2)
+- ~200 lines modified in existing commands
+- Net: +400 lines (improved separation of concerns)
+
+#### Benefits
+
+**Architectural Clarity**:
+- ✅ **Single Responsibility**: Each command has one job
+- ✅ **Clear Contracts**: Explicit input/output for each phase
+- ✅ **Better Testing**: Components testable independently
+- ✅ **Maintainability**: Changes localized to relevant phase
+
+**Developer Experience**:
+- 🎯 **Predictable**: Layout structure visible before assembly
+- 🔍 **Debuggable**: Easier to identify issues (layout vs style)
+- 🔄 **Flexible**: Reuse layouts with different styles
+- 📚 **Understandable**: Each phase has clear documentation
+
+**Design Quality**:
+- 🎨 **Style Independence**: Visual tokens separate from structure
+- 🏗️ **Layout Variety**: Explore mode generates structurally different layouts
+- 📐 **Device Optimization**: Layout templates device-specific
+- ♿ **Accessibility**: Semantic HTML5 structure with ARIA
+
+**Implementation Quality**:
+- 🧩 **Modular**: Components can be developed independently
+- 🔄 **Reusable**: Layout templates work with any style
+- 🧪 **Testable**: Structure and style tested separately
+- 📦 **Production-Ready**: Token-driven, semantic, accessible
+
+---
+
+## [4.3.0] - 2025-10-10
+
+### 🎨 UI Design Workflow V2 - Self-Contained CSS Architecture
+
+This release introduces a major architectural improvement to the UI Design Workflow, removing the placeholder mechanism and enabling agents to generate fully self-contained CSS files directly from design tokens.
+
+#### Changed
+
+**UI Design Workflow V2 Commands**:
+- **`/workflow:ui-design:generate-v2`**: Enhanced prototype generation with self-contained CSS
+  - Agents now read `design-tokens.json` and generate independent CSS files
+  - CSS contains direct token values (e.g., `#3b82f6`) instead of `var()` references
+  - HTML files reference CSS directly: `<link rel="stylesheet" href="page-style-1-layout-2.css">`
+  - No more placeholder mechanism or post-processing steps
+
+- **`/workflow:ui-design:explore-auto-v2`**: Updated to use new generation architecture
+  - Automatic coordination with `generate-v2` command
+  - Streamlined workflow without placeholder replacement
+
+**Removed Dependencies**:
+- ❌ **No more `tokens.css`**: Eliminated intermediate CSS variable files
+- ❌ **No more Phase 1.6**: Removed token-to-CSS conversion step
+- ❌ **No more placeholder replacement**: Scripts no longer process `{{STYLE_CSS}}` placeholders
+
+**Agent Instructions Enhanced**:
+- Agents receive `design-tokens.json` as primary design system reference
+- Direct CSS generation instructions with token value extraction guidance
+- Better adaptation to `design_attributes` (density, visual_weight, formality, etc.)
+- Example instruction: "Use color values for backgrounds, typography values for fonts"
+
+**Script Simplification** (`ui-generate-preview-v2.sh`):
+- Removed placeholder replacement logic (32 lines removed)
+- Focus solely on preview file generation (compare.html, index.html, PREVIEW.md)
+- Cleaner, more focused responsibility
+
+#### Improved
+
+**Style Differentiation**:
+- 🎨 **Better Style Diversity**: Agents can now freely adapt token values based on design philosophy
+- 🎯 **Stronger Visual Identity**: Each style variant can use different color spaces, typography scales
+- 💡 **Design-Aware Selection**: Agents intelligently select tokens matching design_attributes
+
+**Workflow Simplicity**:
+- 📉 **Reduced Complexity**: 346 lines of code removed (net reduction)
+- ⚡ **Fewer Steps**: Eliminated intermediate conversion and replacement phases
+- 🔧 **Easier Debugging**: All styling visible directly in generated CSS files
+- 📝 **Clearer Agent Tasks**: Agents have single, focused responsibility
+
+**CSS Generation Quality**:
+- 🎨 **Fully Embodies Design**: CSS directly reflects design token values
+- 🔄 **No External Dependencies**: Each CSS file is completely self-contained
+- 📊 **Better Adaptation**: Agents can adjust values based on layout context
+- 🎯 **Style-Specific Implementation**: Same layout + different style = truly different CSS
+
+#### Technical Details
+
+**Before (v4.2.x)**:
+```html
+<!-- Agent generates HTML with placeholders -->
+<link rel="stylesheet" href="{{TOKEN_CSS}}">
+<link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
+
+<!-- Phase 1.6: Convert design-tokens.json → tokens.css -->
+<!-- Phase 3a: Replace placeholders with actual paths -->
+```
+
+**After (v4.3.0)**:
+```html
+<!-- Agent generates HTML with direct reference -->
+<link rel="stylesheet" href="dashboard-style-1-layout-2.css">
+
+<!-- CSS contains direct values from design-tokens.json -->
+.button { background: #3b82f6; font-size: 16px; }
+```
+
+**Workflow Comparison**:
+```
+Old Flow:
+Phase 1.5: Inspiration → Phase 1.6: Token Conversion → Phase 2: Agent Gen →
+Phase 3a: Replace Placeholders → Phase 3b: Preview
+
+New Flow:
+Phase 1.5: Inspiration → Phase 2: Agent Gen (reads tokens.json directly) →
+Phase 3: Preview
+```
+
+#### Benefits
+
+**Developer Experience**:
+- 🚀 **Faster Execution**: Removed 2 intermediate processing steps
+- 📁 **Simpler Output**: No more tokens.css files to manage
+- 🔍 **Easier Inspection**: All styling visible in prototype CSS files
+- 🎯 **Clearer Intent**: Direct mapping from design tokens to CSS
+
+**Design Quality**:
+- 🎨 **Richer Style Variations**: Agents can adapt token usage creatively
+- 💪 **Stronger Differentiation**: Each style truly looks different
+- 🎯 **Context-Aware Styling**: Agents adjust tokens based on layout needs
+- ✨ **Better Design Expression**: No constraints from CSS variable structure
+
+**Maintainability**:
+- 📉 **Less Code**: 346 lines removed (5 files modified)
+- 🔧 **Fewer Moving Parts**: Removed token conversion and placeholder systems
+- 📝 **Clearer Responsibilities**: Scripts focus on single purpose
+- 🧪 **Easier Testing**: Self-contained files easier to validate
+
+#### Files Changed
+
+**Commands Updated**:
+- `.claude/commands/workflow/ui-design/generate-v2.md`: Removed Phase 1.6 and Phase 3a, updated agent instructions
+- `.claude/commands/workflow/ui-design/explore-auto-v2.md`: Updated to work with new architecture
+- `.claude/commands/workflow/ui-design/generate.md`: Documentation updates
+- `.claude/commands/workflow/ui-design/extract.md`: Documentation updates
+
+**Scripts Modified**:
+- `.claude/scripts/ui-generate-preview-v2.sh`: Removed placeholder replacement (32 lines)
+
+**Total Impact**:
+- 5 files changed
+- 471 insertions, 817 deletions
+- Net: -346 lines (31% reduction in UI generation code)
+
+#### Migration Notes
+
+**No Breaking Changes** for users:
+- ✅ V2 commands are separate from V1 (`generate-v2` vs `generate`)
+- ✅ Existing workflows continue to work unchanged
+- ✅ New commands are opt-in
+
+**For New Projects**:
+- Use `/workflow:ui-design:generate-v2` for better style differentiation
+- Use `/workflow:ui-design:explore-auto-v2` for automatic workflow
+
+**Design Token Changes**:
+- `design-tokens.json` structure unchanged
+- `tokens.css` files no longer generated (V2 commands only)
+- Style guides (`style-guide.md`) unchanged
+
 ## [4.2.1] - 2025-10-10
 
 ### 📝 Command Renaming & Documentation Refactoring
@@ -1400,12 +2074,6 @@ This is a **breaking change release** with significant architectural improvement
 - **Intelligent Modes**: Auto template selection and precise planning
 - **Full Command Suite**: analyze, chat, execute, mode:auto, mode:bug-index, mode:plan
 
-#### 🏷️ Issue Management Commands
-- `/workflow:issue:create` - Create new project issues with priority/type
-- `/workflow:issue:list` - List and filter issues by status/assignment
-- `/workflow:issue:update` - Update existing issue status and assignments
-- `/workflow:issue:close` - Close completed issues with resolution
-
 #### 📋 Enhanced Workflow Commands
 - `/workflow:plan-verify` - Pre-execution validation using dual analysis
 - `/workflow:test-gen` - Generate comprehensive test workflows

CLAUDE.md

@@ -5,6 +5,7 @@
 This document defines project-specific coding standards and development principles.
 ### CLI Tool Context Protocols
 For all CLI tool usage, command syntax, and integration guidelines:
+- **Tool Control Configuration**: @~/.claude/workflows/tool-control.yaml - Controls CLI tool availability for all commands and agent executions (if disabled, use other enabled CLI tools or Claude's own capabilities)
 - **Intelligent Context Strategy**: @~/.claude/workflows/intelligent-tools-strategy.md
 - **Context Search Commands**: @~/.claude/workflows/context-search-strategy.md
 - **MCP Tool Strategy**: @~/.claude/workflows/mcp-tool-strategy.md

Install-Claude.ps1

@@ -570,6 +570,66 @@ function Copy-FileToDestination {
     }
 }
 
+function Backup-AndReplaceDirectory {
+    param(
+        [string]$Source,
+        [string]$Destination,
+        [string]$Description = "directory",
+        [string]$BackupFolder = $null
+    )
+
+    if (-not (Test-Path $Source)) {
+        Write-ColorOutput "WARNING: Source $Description not found: $Source" $ColorWarning
+        return $false
+    }
+
+    # Backup destination if it exists
+    if (Test-Path $Destination) {
+        Write-ColorOutput "Found existing $Description at: $Destination" $ColorInfo
+
+        # Backup entire directory if backup is enabled
+        if (-not $NoBackup -and $BackupFolder) {
+            Write-ColorOutput "Backing up entire $Description..." $ColorInfo
+            if (Backup-DirectoryToFolder -DirectoryPath $Destination -BackupFolder $BackupFolder) {
+                Write-ColorOutput "Backed up $Description to: $BackupFolder" $ColorSuccess
+            }
+        } elseif ($NoBackup) {
+            if (-not (Confirm-Action "Replace existing $Description without backup?" -DefaultYes:$false)) {
+                Write-ColorOutput "Skipping $Description installation" $ColorWarning
+                return $false
+            }
+        }
+
+        # Get all items from source to determine what to clear in destination
+        Write-ColorOutput "Clearing conflicting items in destination $Description..." $ColorInfo
+        $sourceItems = Get-ChildItem -Path $Source -Force
+
+        foreach ($sourceItem in $sourceItems) {
+            $destItemPath = Join-Path $Destination $sourceItem.Name
+            if (Test-Path $destItemPath) {
+                Write-ColorOutput "Removing existing: $($sourceItem.Name)" $ColorInfo
+                Remove-Item -Path $destItemPath -Recurse -Force -ErrorAction SilentlyContinue
+            }
+        }
+        Write-ColorOutput "Cleared conflicting items in destination" $ColorSuccess
+    } else {
+        # Create destination directory if it doesn't exist
+        New-Item -ItemType Directory -Path $Destination -Force | Out-Null
+        Write-ColorOutput "Created destination directory: $Destination" $ColorInfo
+    }
+
+    # Copy all items from source to destination
+    Write-ColorOutput "Copying $Description from $Source to $Destination..." $ColorInfo
+    $sourceItems = Get-ChildItem -Path $Source -Force
+    foreach ($item in $sourceItems) {
+        $destPath = Join-Path $Destination $item.Name
+        Copy-Item -Path $item.FullName -Destination $destPath -Recurse -Force
+    }
+    Write-ColorOutput "$Description installed successfully" $ColorSuccess
+
+    return $true
+}
+
 function Merge-DirectoryContents {
     param(
         [string]$Source,
@@ -577,34 +637,34 @@ function Merge-DirectoryContents {
         [string]$Description = "directory contents",
         [string]$BackupFolder = $null
     )
-    
+
     if (-not (Test-Path $Source)) {
         Write-ColorOutput "WARNING: Source $Description not found: $Source" $ColorWarning
         return $false
     }
-    
+
     # Create destination directory if it doesn't exist
     if (-not (Test-Path $Destination)) {
         New-Item -ItemType Directory -Path $Destination -Force | Out-Null
         Write-ColorOutput "Created destination directory: $Destination" $ColorInfo
     }
-    
+
     # Get all items in source directory
     $sourceItems = Get-ChildItem -Path $Source -Recurse -File
     $mergedCount = 0
     $skippedCount = 0
-    
+
     foreach ($item in $sourceItems) {
         # Calculate relative path from source
         $relativePath = $item.FullName.Substring($Source.Length + 1)
         $destinationPath = Join-Path $Destination $relativePath
-        
+
         # Ensure destination directory exists
         $destinationDir = Split-Path $destinationPath -Parent
         if (-not (Test-Path $destinationDir)) {
             New-Item -ItemType Directory -Path $destinationDir -Force | Out-Null
         }
-        
+
         # Handle file merging
         if (Test-Path $destinationPath) {
             $fileName = Split-Path $relativePath -Leaf
@@ -639,7 +699,7 @@ function Merge-DirectoryContents {
             $mergedCount++
         }
     }
-    
+
     Write-ColorOutput "Merged $mergedCount files, skipped $skippedCount files" $ColorSuccess
     return $true
 }
@@ -727,25 +787,25 @@ function Install-Global {
         }
     }
 
-    # Merge .claude directory contents (don't replace entire directory)
-    Write-ColorOutput "Merging .claude directory contents..." $ColorInfo
-    $claudeMerged = Merge-DirectoryContents -Source $sourceClaudeDir -Destination $globalClaudeDir -Description ".claude directory contents" -BackupFolder $backupFolder
+    # Replace .claude directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .claude directory..." $ColorInfo
+    $claudeInstalled = Backup-AndReplaceDirectory -Source $sourceClaudeDir -Destination $globalClaudeDir -Description ".claude directory" -BackupFolder $backupFolder
 
     # Handle CLAUDE.md file in .claude directory
     Write-ColorOutput "Installing CLAUDE.md to global .claude directory..." $ColorInfo
     $claudeMdInstalled = Copy-FileToDestination -Source $sourceClaudeMd -Destination $globalClaudeMd -Description "CLAUDE.md" -BackupFolder $backupFolder
 
-    # Merge .codex directory contents
-    Write-ColorOutput "Merging .codex directory contents..." $ColorInfo
-    $codexMerged = Merge-DirectoryContents -Source $sourceCodexDir -Destination $globalCodexDir -Description ".codex directory contents" -BackupFolder $backupFolder
+    # Replace .codex directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .codex directory..." $ColorInfo
+    $codexInstalled = Backup-AndReplaceDirectory -Source $sourceCodexDir -Destination $globalCodexDir -Description ".codex directory" -BackupFolder $backupFolder
 
-    # Merge .gemini directory contents
-    Write-ColorOutput "Merging .gemini directory contents..." $ColorInfo
-    $geminiMerged = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory contents" -BackupFolder $backupFolder
+    # Replace .gemini directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .gemini directory..." $ColorInfo
+    $geminiInstalled = Backup-AndReplaceDirectory -Source $sourceGeminiDir -Destination $globalGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
 
-    # Merge .qwen directory contents
-    Write-ColorOutput "Merging .qwen directory contents..." $ColorInfo
-    $qwenMerged = Merge-DirectoryContents -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory contents" -BackupFolder $backupFolder
+    # Replace .qwen directory (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .qwen directory..." $ColorInfo
+    $qwenInstalled = Backup-AndReplaceDirectory -Source $sourceQwenDir -Destination $globalQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
 
     # Create version.json in global .claude directory
     Write-ColorOutput "Creating version.json..." $ColorInfo
@@ -815,13 +875,9 @@ function Install-Path {
         $destFolderPath = Join-Path $localClaudeDir $folder
 
         if (Test-Path $sourceFolderPath) {
-            if (Test-Path $destFolderPath) {
-                if ($backupFolder) {
-                    Backup-DirectoryToFolder -DirectoryPath $destFolderPath -BackupFolder $backupFolder
-                }
-            }
-
-            Copy-DirectoryRecursive -Source $sourceFolderPath -Destination $destFolderPath
+            # Use new backup and replace logic for local folders
+            Write-ColorOutput "Installing local folder: $folder..." $ColorInfo
+            Backup-AndReplaceDirectory -Source $sourceFolderPath -Destination $destFolderPath -Description "$folder folder" -BackupFolder $backupFolder
             Write-ColorOutput "Installed local folder: $folder" $ColorSuccess
         } else {
             Write-ColorOutput "WARNING: Source folder not found: $folder" $ColorWarning
@@ -882,17 +938,17 @@ function Install-Path {
     Write-ColorOutput "Installing CLAUDE.md to global .claude directory..." $ColorInfo
     Copy-FileToDestination -Source $sourceClaudeMd -Destination $globalClaudeMd -Description "CLAUDE.md" -BackupFolder $backupFolder
 
-    # Merge .codex directory contents to local location
-    Write-ColorOutput "Merging .codex directory contents to local location..." $ColorInfo
-    $codexMerged = Merge-DirectoryContents -Source $sourceCodexDir -Destination $localCodexDir -Description ".codex directory contents" -BackupFolder $backupFolder
+    # Replace .codex directory to local location (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .codex directory to local location..." $ColorInfo
+    $codexInstalled = Backup-AndReplaceDirectory -Source $sourceCodexDir -Destination $localCodexDir -Description ".codex directory" -BackupFolder $backupFolder
 
-    # Merge .gemini directory contents to local location
-    Write-ColorOutput "Merging .gemini directory contents to local location..." $ColorInfo
-    $geminiMerged = Merge-DirectoryContents -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory contents" -BackupFolder $backupFolder
+    # Replace .gemini directory to local location (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .gemini directory to local location..." $ColorInfo
+    $geminiInstalled = Backup-AndReplaceDirectory -Source $sourceGeminiDir -Destination $localGeminiDir -Description ".gemini directory" -BackupFolder $backupFolder
 
-    # Merge .qwen directory contents to local location
-    Write-ColorOutput "Merging .qwen directory contents to local location..." $ColorInfo
-    $qwenMerged = Merge-DirectoryContents -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory contents" -BackupFolder $backupFolder
+    # Replace .qwen directory to local location (backup → clear → copy entire folder)
+    Write-ColorOutput "Installing .qwen directory to local location..." $ColorInfo
+    $qwenInstalled = Backup-AndReplaceDirectory -Source $sourceQwenDir -Destination $localQwenDir -Description ".qwen directory" -BackupFolder $backupFolder
 
     # Create version.json in local .claude directory
     Write-ColorOutput "Creating version.json in local directory..." $ColorInfo

Install-Claude.sh

@@ -340,6 +340,64 @@ function copy_file_to_destination() {
     fi
 }
 
+function backup_and_replace_directory() {
+    local source="$1"
+    local destination="$2"
+    local description="${3:-directory}"
+    local backup_folder="${4:-}"
+
+    if [ ! -d "$source" ]; then
+        write_color "WARNING: Source $description not found: $source" "$COLOR_WARNING"
+        return 1
+    fi
+
+    # Backup destination if it exists
+    if [ -d "$destination" ]; then
+        write_color "Found existing $description at: $destination" "$COLOR_INFO"
+
+        # Backup entire directory if backup is enabled
+        if [ "$NO_BACKUP" = false ] && [ -n "$backup_folder" ]; then
+            write_color "Backing up entire $description..." "$COLOR_INFO"
+            if backup_directory_to_folder "$destination" "$backup_folder"; then
+                write_color "Backed up $description to: $backup_folder" "$COLOR_SUCCESS"
+            fi
+        elif [ "$NO_BACKUP" = true ]; then
+            if ! confirm_action "Replace existing $description without backup?" false; then
+                write_color "Skipping $description installation" "$COLOR_WARNING"
+                return 1
+            fi
+        fi
+
+        # Get all items from source to determine what to clear in destination
+        write_color "Clearing conflicting items in destination $description..." "$COLOR_INFO"
+        while IFS= read -r -d '' source_item; do
+            local item_name=$(basename "$source_item")
+            local dest_item_path="${destination}/${item_name}"
+
+            if [ -e "$dest_item_path" ]; then
+                write_color "Removing existing: $item_name" "$COLOR_INFO"
+                rm -rf "$dest_item_path"
+            fi
+        done < <(find "$source" -mindepth 1 -maxdepth 1 -print0)
+        write_color "Cleared conflicting items in destination" "$COLOR_SUCCESS"
+    else
+        # Create destination directory if it doesn't exist
+        mkdir -p "$destination"
+        write_color "Created destination directory: $destination" "$COLOR_INFO"
+    fi
+
+    # Copy all items from source to destination
+    write_color "Copying $description from $source to $destination..." "$COLOR_INFO"
+    while IFS= read -r -d '' item; do
+        local item_name=$(basename "$item")
+        local dest_path="${destination}/${item_name}"
+        cp -r "$item" "$dest_path"
+    done < <(find "$source" -mindepth 1 -maxdepth 1 -print0)
+    write_color "$description installed successfully" "$COLOR_SUCCESS"
+
+    return 0
+}
+
 function merge_directory_contents() {
     local source="$1"
     local destination="$2"
@@ -447,25 +505,25 @@ function install_global() {
         fi
     fi
 
-    # Merge .claude directory contents
-    write_color "Merging .claude directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_claude_dir" "$global_claude_dir" ".claude directory contents" "$backup_folder"
+    # Replace .claude directory (backup → clear conflicting → copy)
+    write_color "Installing .claude directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_claude_dir" "$global_claude_dir" ".claude directory" "$backup_folder"
 
     # Handle CLAUDE.md file
     write_color "Installing CLAUDE.md to global .claude directory..." "$COLOR_INFO"
     copy_file_to_destination "$source_claude_md" "$global_claude_md" "CLAUDE.md" "$backup_folder"
 
-    # Merge .codex directory contents
-    write_color "Merging .codex directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_codex_dir" "$global_codex_dir" ".codex directory contents" "$backup_folder"
+    # Replace .codex directory (backup → clear conflicting → copy)
+    write_color "Installing .codex directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_codex_dir" "$global_codex_dir" ".codex directory" "$backup_folder"
 
-    # Merge .gemini directory contents
-    write_color "Merging .gemini directory contents..." "$COLOR_INFO"
-    merge_directory_contents "$source_gemini_dir" "$global_gemini_dir" ".gemini directory contents" "$backup_folder"
+    # Replace .gemini directory (backup → clear conflicting → copy)
+    write_color "Installing .gemini directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_gemini_dir" "$global_gemini_dir" ".gemini directory" "$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"
+    # Replace .qwen directory (backup → clear conflicting → copy)
+    write_color "Installing .qwen directory..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_qwen_dir" "$global_qwen_dir" ".qwen directory" "$backup_folder"
 
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then
@@ -528,11 +586,9 @@ function install_path() {
         local dest_folder="${local_claude_dir}/${folder}"
 
         if [ -d "$source_folder" ]; then
-            if [ -d "$dest_folder" ] && [ -n "$backup_folder" ]; then
-                backup_directory_to_folder "$dest_folder" "$backup_folder"
-            fi
-
-            copy_directory_recursive "$source_folder" "$dest_folder"
+            # Use new backup and replace logic for local folders
+            write_color "Installing local folder: $folder..." "$COLOR_INFO"
+            backup_and_replace_directory "$source_folder" "$dest_folder" "$folder folder" "$backup_folder"
             write_color "✓ Installed local folder: $folder" "$COLOR_SUCCESS"
         else
             write_color "WARNING: Source folder not found: $folder" "$COLOR_WARNING"
@@ -590,17 +646,17 @@ function install_path() {
     write_color "Installing CLAUDE.md to global .claude directory..." "$COLOR_INFO"
     copy_file_to_destination "$source_claude_md" "$global_claude_md" "CLAUDE.md" "$backup_folder"
 
-    # Merge .codex directory contents to local location
-    write_color "Merging .codex directory contents to local location..." "$COLOR_INFO"
-    merge_directory_contents "$source_codex_dir" "$local_codex_dir" ".codex directory contents" "$backup_folder"
+    # Replace .codex directory to local location (backup → clear conflicting → copy)
+    write_color "Installing .codex directory to local location..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_codex_dir" "$local_codex_dir" ".codex directory" "$backup_folder"
 
-    # Merge .gemini directory contents to local location
-    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"
+    # Replace .gemini directory to local location (backup → clear conflicting → copy)
+    write_color "Installing .gemini directory to local location..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_gemini_dir" "$local_gemini_dir" ".gemini directory" "$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"
+    # Replace .qwen directory to local location (backup → clear conflicting → copy)
+    write_color "Installing .qwen directory to local location..." "$COLOR_INFO"
+    backup_and_replace_directory "$source_qwen_dir" "$local_qwen_dir" ".qwen directory" "$backup_folder"
 
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then

README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v4.2.1-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,13 +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: v4.2.1** - Documentation Refactoring for UI Design Workflow. 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 v4.2.1**:
-> - 📚 **Documentation Optimization**: Reduced file sizes by 15-20% while preserving all functionality
-> - 🎯 **Clearer Structure**: Merged duplicate concepts and streamlined content organization
-> - ✨ **Improved Maintainability**: Better content separation and consistent formatting patterns
-> - 📖 **Zero Functionality Loss**: All features, workflows, and technical details preserved
+> **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
 
 ---
 
@@ -144,17 +144,43 @@ After installation, run the following command to ensure CCW is working:
 
 ## ⚙️ Configuration
 
-### **Prerequisites: Required Tools**
+### **Tool Control System**
 
-Before using CCW, install the following command-line tools:
+CCW uses a **configuration-based tool control system** that makes external CLI tools **optional** rather than required. This allows you to:
 
-#### **Core CLI Tools**
+- ✅ **Start with Claude-only mode** - Work immediately without installing additional tools
+- ✅ **Progressive enhancement** - Add external tools selectively as needed
+- ✅ **Graceful degradation** - Automatic fallback when tools are unavailable
+- ✅ **Flexible configuration** - Control tool availability per project
 
-| Tool | Purpose | Installation |
-|------|---------|--------------|
-| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
-| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
-| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) |
+**Configuration File**: `~/.claude/workflows/tool-control.yaml`
+
+```yaml
+tools:
+  gemini:
+    enabled: false  # Optional: AI analysis & documentation
+  qwen:
+    enabled: true   # Optional: AI architecture & code generation
+  codex:
+    enabled: true   # Optional: AI development & implementation
+```
+
+**Behavior**:
+- **When disabled**: CCW automatically falls back to other enabled tools or Claude's native capabilities
+- **When enabled**: Uses specialized tools for their specific strengths
+- **Default**: All tools disabled - Claude-only mode works out of the box
+
+### **Optional CLI Tools** *(Enhanced Capabilities)*
+
+While CCW works with Claude alone, installing these tools provides enhanced analysis and extended context:
+
+#### **External CLI Tools**
+
+| Tool | Purpose | Installation | Benefits |
+|------|---------|--------------|----------|
+| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | Free quota, extended context for complex projects |
+| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | Autonomous development, mathematical reasoning |
+| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) | Large context window, architecture analysis |
 
 #### **System Utilities**
 
@@ -248,28 +274,65 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:brainstorm:synthesis  # Generate consolidated specification
 ```
 
-**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
+**Phase 1.5: Concept Verification** *(Optional Quality Gate)*
 ```bash
-# Matrix Exploration Mode - Multiple style/layout variants (v4.2.1+)
+# Identify and resolve ambiguities in brainstorming artifacts
+/workflow:concept-clarify
+
+# OR specify session explicitly
+/workflow:concept-clarify --session WFS-auth
+```
+- Runs after `/workflow:brainstorm:synthesis` and before `/workflow:plan`
+- Interactive Q&A to clarify underspecified requirements, architecture decisions, or risks
+- Maximum 5 questions per session with multiple-choice or short-answer format
+- Updates `synthesis-specification.md` with clarifications incrementally
+- Ensures conceptual foundation is clear before detailed planning
+- Generates coverage summary with recommendations to proceed or address outstanding items
+
+**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
+
+**🎯 Choose Your Workflow:**
+
+**Scenario 1: Starting from an idea or concept** → Use `explore-auto`
+```bash
+# Generate multiple style and layout options to explore different directions
 /workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
+# Creates a 3×2 matrix: 3 visual styles × 2 layouts = 6 prototypes to choose from
+```
 
-# Fast Imitation Mode - Single design replication (v4.2.1+)
+**Scenario 2: Replicating an existing design** → Use `imitate-auto`
+```bash
+# Fast, high-fidelity replication of reference designs
 /workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+# Or auto-screenshot from URL (requires Playwright/Chrome DevTools MCP)
+/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
+```
 
-# With session integration
-/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+**Scenario 3: Batch creation from existing design system** → Use `batch-generate`
+```bash
+# Already have a design system? Generate multiple pages quickly
+/workflow:ui-design:batch-generate --prompt "Create profile and settings pages" --layout-variants 2
+```
 
-# Or run individual design phases
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+**Advanced: Manual Step-by-Step Control** (v4.4.0+)
+```bash
+# 1. Extract visual style (colors, typography, spacing)
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# 2. Consolidate into production-ready design tokens
 /workflow:ui-design:consolidate --variants "variant-1,variant-3"
-/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 2
 
-# Preview generated prototypes
-# Option 1: Open .workflow/WFS-auth/.design/prototypes/compare.html in browser
-# Option 2: Start local server
+# 3. Extract layout structure (DOM, CSS layout rules)
+/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
+
+# 4. Combine style + layout → HTML/CSS prototypes
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
+
+# 5. Preview and select
 cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
-# Visit http://localhost:8080 for interactive preview with comparison tools
+# Visit http://localhost:8080/compare.html for side-by-side comparison
 
+# 6. Integrate selected design into project
 /workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
@@ -282,6 +345,22 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 /workflow:tdd-plan "Implement authentication with test-first development"
 ```
 
+**Phase 3.5: Action Plan Verification** *(Optional Pre-Execution Check)*
+```bash
+# Validate plan consistency and completeness
+/workflow:action-plan-verify
+
+# OR specify session explicitly
+/workflow:action-plan-verify --session WFS-auth
+```
+- Runs after `/workflow:plan` or `/workflow:tdd-plan` and before `/workflow:execute`
+- Read-only analysis of `IMPL_PLAN.md` and task JSON files against `synthesis-specification.md`
+- Validates requirements coverage, dependency integrity, and synthesis alignment
+- Identifies inconsistencies, duplications, ambiguities, and underspecified items
+- Generates detailed verification report with severity-rated findings (CRITICAL/HIGH/MEDIUM/LOW)
+- Recommends whether to PROCEED, PROCEED_WITH_FIXES, or BLOCK_EXECUTION
+- Provides actionable remediation suggestions for detected issues
+
 **Phase 4: Execution**
 ```bash
 # Execute tasks with AI agents
@@ -362,16 +441,19 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 
 | Command | Description |
 |---|---|
-| `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
+| `/workflow:session:*` | Manage development sessions (`start`, `resume`, `list`, `complete`). |
 | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
-| `/workflow:ui-design:explore-auto` | **v4.2.1** Matrix exploration mode - Generate multiple style × layout variants for comprehensive design exploration. |
-| `/workflow:ui-design:imitate-auto` | **v4.2.1** Fast imitation mode - Rapid single-design replication with auto-screenshot and direct token extraction. |
-| `/workflow:ui-design:extract` | **v4.2.1** Extract design from images/text using Claude-native analysis. Single-pass variant generation. |
-| `/workflow:ui-design:consolidate` | **v4.2.1** Consolidate style variants into validated design tokens using Claude synthesis. |
-| `/workflow:ui-design:generate` | **v4.2.1** Generate token-driven HTML/CSS prototypes in matrix mode (style × layout combinations). |
-| `/workflow:ui-design:update` | **v4.2.1** Integrate finalized design system into brainstorming artifacts. |
+| `/workflow:concept-clarify` | **Optional** Quality gate - Identify and resolve ambiguities in brainstorming artifacts before planning (runs after synthesis, before plan). |
+| `/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:action-plan-verify` | **Optional** Pre-execution check - Validate IMPL_PLAN.md and task.json consistency and completeness (runs after plan, before execute). |
 | `/workflow:execute` | Execute the current workflow plan autonomously. |
 | `/workflow:status` | Display the current status of the workflow. |
 | `/workflow:test-gen [--use-codex] <session>` | Create test generation workflow with auto-diagnosis and fix cycle for completed implementations. |
@@ -381,9 +463,80 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 | `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. |
 | `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. |
 
-### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.2.1)*
+### **UI Design Workflow Commands (`/workflow:ui-design:*`)** *(v4.4.0)*
 
-The design workflow system provides complete UI design refinement with **pure Claude execution**, **intelligent page inference**, and **zero external dependencies**.
+The design workflow system provides complete UI design refinement with **layout/style separation architecture**, **pure Claude execution**, **intelligent target inference**, and **zero external dependencies**.
+
+#### 📐 Architecture Overview
+
+The UI workflow follows a **separation of concerns** philosophy:
+- **Style (Visual Tokens)**: Colors, typography, spacing, borders → `design-tokens.json`
+- **Layout (Structure)**: DOM hierarchy, CSS layout rules → `layout-templates.json`
+- **Assembly**: Pure combination of style + layout → HTML/CSS prototypes
+
+**Command Categories:**
+
+| Category | Commands | Purpose |
+|----------|----------|---------|
+| **High-Level Orchestrators** | `explore-auto`, `imitate-auto`, `batch-generate` | Complete workflows (recommended) |
+| **Input/Capture** | `capture`, `explore-layers` | Screenshot acquisition |
+| **Analysis/Extraction** | `style-extract`, `layout-extract` | Visual style and structural layout extraction |
+| **Processing/Generation** | `consolidate`, `generate` | Token validation and prototype assembly |
+| **Integration** | `update` | Design system integration into project |
+
+#### 🧭 Decision Tree: Which Command Should I Use?
+
+```
+┌─ Have an idea or text description?
+│  └─→ /workflow:ui-design:explore-auto
+│     (Explores multiple style × layout options)
+│
+┌─ Want to replicate an existing design?
+│  └─→ /workflow:ui-design:imitate-auto
+│     (High-fidelity single design replication)
+│
+┌─ Already have a design system?
+│  └─→ /workflow:ui-design:batch-generate
+│     (Batch create multiple pages/components)
+│
+└─ Need fine-grained control?
+   └─→ Use individual commands in sequence:
+       1. style-extract → Extract colors, fonts, spacing
+       2. consolidate → Validate and merge tokens
+       3. layout-extract → Extract DOM structure
+       4. generate → Combine into prototypes
+       5. update → Integrate into project
+```
+
+#### 🔄 Workflow Diagrams
+
+**Explore Workflow** (Idea → Multiple Designs):
+```
+Prompt/Images → style-extract (explore mode)
+                     ↓
+              consolidate (N variants)
+                     ↓
+              layout-extract (explore mode)
+                     ↓
+              generate (N styles × M layouts)
+                     ↓
+              update (selected designs)
+```
+
+**Imitate Workflow** (Reference → Single Design):
+```
+URL/Images → capture/explore-layers
+                  ↓
+           style-extract (imitate mode)
+                  ↓
+           layout-extract (imitate mode)
+                  ↓
+           consolidate (single variant)
+                  ↓
+           generate (1 style × 1 layout)
+                  ↓
+           update (final design)
+```
 
 #### Core Commands
 
@@ -420,21 +573,41 @@ The design workflow system provides complete UI design refinement with **pure Cl
 - **🎯 Direct Extraction**: Skip variant selection, go straight to implementation
 - **🔧 Single Design Focus**: Best for copying existing designs quickly
 
-**`/workflow:ui-design:extract`** - Style analysis with dual input sources
+**`/workflow:ui-design:style-extract`** - Visual style extraction (v4.4.0)
 ```bash
 # Pure text prompt
-/workflow:ui-design:extract --prompt "Modern minimalist, dark theme" --variants 3
+/workflow:ui-design:style-extract --prompt "Modern minimalist, dark theme" --mode explore --variants 3
 
 # Pure images
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
 
 # Hybrid (text guides image analysis)
-/workflow:ui-design:extract --images "refs/*.png" --prompt "Linear.app style" --variants 2
+/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
-- **Enhanced Output**: `style-cards.json` with embedded `proposed_tokens`
-- **Reproducible**: Deterministic structure, version-controlled logic
-- **Output**: 1 file (vs 4+ in previous versions)
+- **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
@@ -445,19 +618,19 @@ The design workflow system provides complete UI design refinement with **pure Cl
 - **Features**: WCAG AA validation, OKLCH colors, W3C token format
 - **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`, `validation-report.json`
 
-**`/workflow:ui-design:generate`** - Generate HTML/CSS prototypes
+**`/workflow:ui-design:generate`** - Pure assembler (v4.4.0)
 ```bash
-# Matrix mode - style × layout combinations
-/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
+# Combine layout templates + design tokens
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# Single page with multiple variants
-/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
+# Multiple styles with multiple layouts
+/workflow:ui-design:generate --style-variants 2 --layout-variants 3
 ```
-- **🎯 Matrix Generation**: Creates all style × layout combinations
-- **📊 Multi-page Support**: Consistent design system across pages
-- **✅ Consistency Validation**: Automatic cross-page consistency reports (v4.2.0+)
+- **📦 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
-- **📋 Batch Selection**: Quick selection by style or layout filters
 
 **`/workflow:ui-design:update`** - Integrate design system
 ```bash
@@ -498,6 +671,61 @@ php -S localhost:8080           # PHP
 - Dynamic page switching
 - Real-time responsive testing
 
+#### 📦 Output Structure
+
+All UI workflow outputs are organized in the `.design` directory within your session:
+
+```
+.workflow/WFS-<session-id>/.design/
+├── design-run-YYYYMMDD-HHMMSS/          # Timestamped design run
+│   ├── screenshots/                      # 📸 Captured screenshots
+│   │   ├── home.png
+│   │   └── dashboard.png
+│   │
+│   ├── style-extraction/                 # 🎨 Style analysis phase
+│   │   ├── style-cards.json             # AI-proposed style variants
+│   │   └── design-space-analysis.json   # (explore mode) Diversity analysis
+│   │
+│   ├── layout-extraction/                # 🏗️ Layout analysis phase
+│   │   └── layout-templates.json        # Structural templates with token-based CSS
+│   │
+│   ├── style-consolidation/              # ✅ Production design systems
+│   │   ├── style-1/
+│   │   │   ├── design-tokens.json       # W3C design tokens
+│   │   │   ├── style-guide.md           # Visual design documentation
+│   │   │   ├── tailwind.config.js       # Tailwind configuration
+│   │   │   └── validation-report.json   # WCAG AA validation results
+│   │   └── style-2/
+│   │       └── ...
+│   │
+│   └── prototypes/                       # 🎯 Final HTML/CSS prototypes
+│       ├── home-style-1-layout-1.html   # Matrix-generated prototypes
+│       ├── home-style-1-layout-1.css
+│       ├── home-style-1-layout-2.html
+│       ├── dashboard-style-2-layout-1.html
+│       ├── index.html                   # Master navigation page
+│       └── compare.html                 # Side-by-side comparison tool
+│
+└── latest -> design-run-YYYYMMDD-HHMMSS  # Symlink to most recent run
+```
+
+**Key Files:**
+
+| File | Purpose | Generated By |
+|------|---------|--------------|
+| `style-cards.json` | AI-proposed visual styles with embedded tokens | `style-extract` |
+| `layout-templates.json` | Structural templates with token-based CSS | `layout-extract` |
+| `design-tokens.json` | Production-ready W3C design tokens | `consolidate` |
+| `style-guide.md` | Visual design system documentation | `consolidate` |
+| `compare.html` | Interactive prototype comparison matrix | `generate` |
+
+**Best Practices:**
+
+1. **Session Management**: All runs within a session accumulate in `.design/design-run-*/`
+2. **Versioning**: Each run is timestamped for easy rollback
+3. **Integration**: Use `update` command to link final tokens to project artifacts
+4. **Cleanup**: Old runs can be safely deleted; `latest` symlink always points to newest
+
 ---
 
 ### **Task & Memory Commands**

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v4.2.1-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工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,13 +15,13 @@
 
 **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
 
-> **🎉 最新版本: v4.2.1** - UI 设计工作流文档重构。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v4.4.0** - UI 设计工作流 V3 布局/样式分离架构。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v4.2.1 版本新特性**:
-> - 📚 **文档优化**: 文件大小减少 15-20%，同时保留所有功能
-> - 🎯 **更清晰的结构**: 合并重复概念，优化内容组织
-> - ✨ **改进的可维护性**: 更好的内容分离和一致的格式模式
-> - 📖 **零功能损失**: 保留所有特性、工作流和技术细节
+> **v4.4.0 版本新特性**:
+> - 🏗️ **布局/样式分离**: 新的 `layout-extract` 命令将结构与视觉令牌分离
+> - 📦 **纯汇编器**: `generate` 命令现在纯粹组合预提取的布局 + 样式
+> - 🎯 **更好的多样性**: 布局探索生成结构上不同的设计
+> - ✅ **单一职责**: 每个阶段（样式、布局、汇编）都有明确的目的
 
 ---
 
@@ -144,17 +144,43 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 
 ## ⚙️ 配置
 
-### **前置要求：必需工具**
+### **工具控制系统**
 
-在使用 CCW 之前，请安装以下命令行工具：
+CCW 使用**基于配置的工具控制系统**，使外部 CLI 工具成为**可选项**而非必需项。这允许您：
 
-#### **核心 CLI 工具**
+- ✅ **从纯 Claude 模式开始** - 无需安装额外工具即可立即开始工作
+- ✅ **渐进式增强** - 根据需要选择性地添加外部工具
+- ✅ **优雅降级** - 工具不可用时自动回退
+- ✅ **灵活配置** - 按项目控制工具可用性
 
-| 工具 | 用途 | 安装方式 |
-|------|------|----------|
-| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
-| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
-| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) |
+**配置文件**: `~/.claude/workflows/tool-control.yaml`
+
+```yaml
+tools:
+  gemini:
+    enabled: false  # 可选：AI 分析与文档生成
+  qwen:
+    enabled: true   # 可选：AI 架构与代码生成
+  codex:
+    enabled: true   # 可选：AI 开发与实现
+```
+
+**行为**:
+- **禁用时**: CCW 自动回退到其他已启用工具或 Claude 的原生能力
+- **启用时**: 使用专用工具发挥各自优势
+- **默认**: 所有工具禁用 - 纯 Claude 模式开箱即用
+
+### **可选 CLI 工具** *(增强功能)*
+
+虽然 CCW 仅使用 Claude 即可工作，但安装这些工具可提供增强的分析和扩展上下文：
+
+#### **外部 CLI 工具**
+
+| 工具 | 用途 | 安装方式 | 优势 |
+|------|------|----------|------|
+| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) | 免费配额，复杂项目的扩展上下文 |
+| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) | 自主开发，数学推理 |
+| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) | 大上下文窗口，架构分析 |
 
 #### **系统实用工具**
 
@@ -248,28 +274,65 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:brainstorm:synthesis  # 生成综合规范
 ```
 
-**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
+**阶段 1.5：概念验证** *(可选质量关卡)*
 ```bash
-# 矩阵探索模式 - 多个风格×布局变体（v4.2.1+）
+# 识别并解决头脑风暴产物中的歧义
+/workflow:concept-clarify
+
+# 或显式指定会话
+/workflow:concept-clarify --session WFS-auth
+```
+- 在 `/workflow:brainstorm:synthesis` 之后、`/workflow:plan` 之前运行
+- 通过交互式问答澄清未明确的需求、架构决策或风险
+- 每次会话最多 5 个问题，支持多选或简答格式
+- 增量更新 `synthesis-specification.md` 以记录澄清内容
+- 确保概念基础明确后再进行详细规划
+- 生成覆盖度摘要，建议继续或解决未决项
+
+**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
+
+**🎯 选择您的工作流：**
+
+**场景 1：从想法或概念开始** → 使用 `explore-auto`
+```bash
+# 生成多个风格和布局选项来探索不同方向
 /workflow:ui-design:explore-auto --prompt "现代博客：首页，文章，作者" --style-variants 3 --layout-variants 2
+# 创建一个 3×2 矩阵：3种视觉风格 × 2种布局 = 6个原型供选择
+```
 
-# 快速模仿模式 - 单一设计快速复制（v4.2.1+）
+**场景 2：复制现有设计** → 使用 `imitate-auto`
+```bash
+# 快速、高保真复制参考设计
 /workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+# 或从 URL 自动截图（需要 Playwright/Chrome DevTools MCP）
+/workflow:ui-design:imitate-auto --url "https://linear.app" --pages "home,features"
+```
 
-# 与会话集成
-/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
+**场景 3：从现有设计系统批量创建** → 使用 `batch-generate`
+```bash
+# 已有设计系统？快速生成多个页面
+/workflow:ui-design:batch-generate --prompt "创建个人资料和设置页面" --layout-variants 2
+```
 
-# 或者运行单独的设计阶段
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+**高级：手动分步控制** (v4.4.0+)
+```bash
+# 1. 提取视觉样式（颜色、排版、间距）
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# 2. 整合为可用于生产的设计令牌
 /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：启动本地服务器
+# 3. 提取布局结构（DOM、CSS 布局规则）
+/workflow:ui-design:layout-extract --targets "dashboard,auth" --mode explore --variants 2 --device-type responsive
+
+# 4. 组合样式 + 布局 → HTML/CSS 原型
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
+
+# 5. 预览并选择
 cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
-# 访问 http://localhost:8080 获取交互式预览和对比工具
+# 访问 http://localhost:8080/compare.html 进行并排比较
 
+# 6. 将选定的设计集成到项目中
 /workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
@@ -282,6 +345,22 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 /workflow:tdd-plan "使用测试优先开发实现认证"
 ```
 
+**阶段 3.5：行动计划验证** *(可选执行前检查)*
+```bash
+# 验证计划一致性和完整性
+/workflow:action-plan-verify
+
+# 或显式指定会话
+/workflow:action-plan-verify --session WFS-auth
+```
+- 在 `/workflow:plan` 或 `/workflow:tdd-plan` 之后、`/workflow:execute` 之前运行
+- 对 `IMPL_PLAN.md` 和任务 JSON 文件进行只读分析，并与 `synthesis-specification.md` 对照
+- 验证需求覆盖率、依赖完整性和综合对齐性
+- 识别不一致、重复、歧义和未充分说明的项目
+- 生成详细验证报告，包含严重性评级的发现（CRITICAL/HIGH/MEDIUM/LOW）
+- 建议是否 PROCEED、PROCEED_WITH_FIXES 或 BLOCK_EXECUTION
+- 提供针对检测到的问题的可操作修复建议
+
 **阶段 4：执行**
 ```bash
 # 使用 AI 智能体执行任务
@@ -362,16 +441,19 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 
 | 命令 | 描述 |
 |---|---|
-| `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
+| `/workflow:session:*` | 管理开发会话（`start`, `resume`, `list`, `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:concept-clarify` | **可选** 质量关卡 - 在规划之前识别并解决头脑风暴产物中的歧义（在综合后、规划前运行）。 |
+| `/workflow:ui-design:explore-auto` | **v4.4.0** 矩阵探索模式 - 通过布局/样式分离生成多个风格×布局变体。 |
+| `/workflow:ui-design:imitate-auto` | **v4.4.0** 快速模仿模式 - 通过自动截图、布局提取和汇编实现快速 UI 复制。 |
+| `/workflow:ui-design:style-extract` | **v4.4.0** 使用 Claude 原生分析从图像/文本提取视觉样式（颜色、排版、间距）。 |
+| `/workflow:ui-design:layout-extract` | **v4.4.0** 通过设备感知模板提取结构布局（DOM、CSS 布局规则）。 |
+| `/workflow:ui-design:consolidate` | **v4.4.0** 使用 Claude 合成将风格变体整合为经过验证的设计令牌。 |
+| `/workflow:ui-design:generate` | **v4.4.0** 纯汇编器 - 组合布局模板 + 设计令牌 → HTML/CSS 原型。 |
+| `/workflow:ui-design:update` | **v4.4.0** 将最终确定的设计系统集成到头脑风暴产物中。 |
 | `/workflow:plan` | 从描述创建详细、可执行的计划。 |
 | `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
+| `/workflow:action-plan-verify` | **可选** 执行前检查 - 验证 IMPL_PLAN.md 和任务 JSON 的一致性和完整性（在规划后、执行前运行）。 |
 | `/workflow:execute` | 自主执行当前的工作流计划。 |
 | `/workflow:status` | 显示工作流的当前状态。 |
 | `/workflow:test-gen [--use-codex] <session>` | 为已完成实现创建独立测试生成工作流，支持自动诊断和修复。 |
@@ -381,9 +463,80 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 | `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
 | `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
 
-### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.2.1)*
+### **UI 设计工作流命令 (`/workflow:ui-design:*`)** *(v4.4.0)*
 
-设计工作流系统提供完整的 UI 设计精炼，具备**纯 Claude 执行**、**智能页面推断**和**零外部依赖**。
+设计工作流系统提供完整的 UI 设计精炼，具备**布局/样式分离架构**、**纯 Claude 执行**、**智能目标推断**和**零外部依赖**。
+
+#### 📐 架构概述
+
+UI 工作流遵循**关注点分离**哲学：
+- **样式（视觉令牌）**：颜色、排版、间距、边框 → `design-tokens.json`
+- **布局（结构）**：DOM 层次结构、CSS 布局规则 → `layout-templates.json`
+- **汇编**：纯粹组合样式 + 布局 → HTML/CSS 原型
+
+**命令分类：**
+
+| 类别 | 命令 | 目的 |
+|----------|----------|---------|
+| **高级编排器** | `explore-auto`, `imitate-auto`, `batch-generate` | 完整工作流（推荐） |
+| **输入/捕获** | `capture`, `explore-layers` | 截图获取 |
+| **分析/提取** | `style-extract`, `layout-extract` | 视觉样式和结构布局提取 |
+| **处理/生成** | `consolidate`, `generate` | 令牌验证和原型汇编 |
+| **集成** | `update` | 设计系统集成到项目 |
+
+#### 🧭 决策树：应该使用哪个命令？
+
+```
+┌─ 有想法或文本描述？
+│  └─→ /workflow:ui-design:explore-auto
+│     （探索多个风格 × 布局选项）
+│
+┌─ 想复制现有设计？
+│  └─→ /workflow:ui-design:imitate-auto
+│     （高保真单一设计复制）
+│
+┌─ 已有设计系统？
+│  └─→ /workflow:ui-design:batch-generate
+│     （批量创建多个页面/组件）
+│
+└─ 需要细粒度控制？
+   └─→ 按顺序使用单独命令：
+       1. style-extract → 提取颜色、字体、间距
+       2. consolidate → 验证并合并令牌
+       3. layout-extract → 提取 DOM 结构
+       4. generate → 组合为原型
+       5. update → 集成到项目
+```
+
+#### 🔄 工作流程图
+
+**探索工作流**（想法 → 多个设计）：
+```
+提示词/图像 → style-extract（探索模式）
+                     ↓
+              consolidate（N 个变体）
+                     ↓
+              layout-extract（探索模式）
+                     ↓
+              generate（N 个样式 × M 个布局）
+                     ↓
+              update（选定的设计）
+```
+
+**模仿工作流**（参考 → 单一设计）：
+```
+URL/图像 → capture/explore-layers
+                  ↓
+           style-extract（模仿模式）
+                  ↓
+           layout-extract（模仿模式）
+                  ↓
+           consolidate（单一变体）
+                  ↓
+           generate（1 个样式 × 1 个布局）
+                  ↓
+           update（最终设计）
+```
 
 #### 核心命令
 
@@ -420,27 +573,64 @@ cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
 - **🎯 直接提取**: 跳过变体选择，直接进入实现
 - **🔧 单一设计聚焦**: 最适合快速复制现有设计
 
-**`/workflow:ui-design:style-consolidate`** - 验证和合并令牌
+**`/workflow:ui-design:style-extract`** - 视觉样式提取（v4.4.0）
+```bash
+# 纯文本提示
+/workflow:ui-design:style-extract --prompt "现代极简，深色主题" --mode explore --variants 3
+
+# 纯图像
+/workflow:ui-design:style-extract --images "refs/*.png" --mode explore --variants 3
+
+# 混合（文本指导图像分析）
+/workflow:ui-design:style-extract --images "refs/*.png" --prompt "Linear.app 风格" --mode imitate
+
+# 高保真单一风格
+/workflow:ui-design:style-extract --images "design.png" --mode imitate
+```
+- **🎨 仅视觉令牌**：颜色、排版、间距（无布局结构）
+- **🔄 双模式**：模仿（单一变体）/ 探索（多个变体）
+- **Claude 原生**：单次分析，无外部工具
+- **输出**：包含嵌入式 `proposed_tokens` 的 `style-cards.json`
+
+**`/workflow:ui-design:layout-extract`** - 结构布局提取（v4.4.0）
+```bash
+# 探索模式 - 多个布局变体
+/workflow:ui-design:layout-extract --targets "home,dashboard" --mode explore --variants 3 --device-type responsive
+
+# 模仿模式 - 单一布局复制
+/workflow:ui-design:layout-extract --images "refs/*.png" --targets "dashboard" --mode imitate --device-type desktop
+
+# 使用 MCP 研究（探索模式）
+/workflow:ui-design:layout-extract --prompt "电商结账" --targets "cart,checkout" --mode explore --variants 2
+```
+- **🏗️ 仅结构**：DOM 层次结构、CSS 布局规则（无视觉样式）
+- **📱 设备感知**：桌面、移动、平板、响应式优化
+- **🧠 智能体驱动**：使用 ui-design-agent 进行结构分析
+- **🔍 MCP 研究**：布局模式灵感（探索模式）
+- **输出**：包含基于令牌的 CSS 的 `layout-templates.json`
+
+**`/workflow:ui-design:consolidate`** - 验证和合并令牌
 ```bash
 # 整合选定的风格变体
-/workflow:ui-design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+/workflow:ui-design:consolidate --session WFS-auth --variants "variant-1,variant-3"
 ```
-- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
-- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
+- **Claude 合成**：单次生成所有设计系统文件
+- **功能**：WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
+- **输出**：`design-tokens.json`、`style-guide.md`、`tailwind.config.js`、`validation-report.json`
 
-**`/workflow:ui-design:generate`** - 生成 HTML/CSS 原型
+**`/workflow:ui-design:generate`** - 纯汇编器（v4.4.0）
 ```bash
-# 矩阵模式 - 风格×布局组合
-/workflow:ui-design:generate --pages "dashboard,auth" --style-variants 2 --layout-variants 3
+# 组合布局模板 + 设计令牌
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# 单页面多变体
-/workflow:ui-design:generate --pages "home" --style-variants 3 --layout-variants 2
+# 多个样式与多个布局
+/workflow:ui-design:generate --style-variants 2 --layout-variants 3
 ```
-- **🎯 矩阵生成**: 创建所有风格×布局组合
-- **📊 多页面支持**: 跨页面一致的设计系统
-- **✅ 一致性验证**: 自动跨页面一致性报告（v4.2.0+）
-- **🔍 交互式预览**: `compare.html` 并排比较
-- **📋 批量选择**: 按风格或布局过滤器快速选择
+- **📦 纯汇编**：组合预提取的 layout-templates.json + design-tokens.json
+- **❌ 无设计逻辑**：所有布局/样式决策在之前阶段完成
+- **✅ 令牌解析**：用实际令牌值替换 var() 占位符
+- **🎯 矩阵输出**：生成样式 × 布局 × 目标原型
+- **🔍 交互式预览**：`compare.html` 并排比较
 
 **`/workflow:ui-design:update`** - 集成设计系统
 ```bash
@@ -481,6 +671,61 @@ php -S localhost:8080           # PHP
 - 动态页面切换
 - 实时响应式测试
 
+#### 📦 输出结构
+
+所有 UI 工作流输出都组织在会话内的 `.design` 目录中：
+
+```
+.workflow/WFS-<session-id>/.design/
+├── design-run-YYYYMMDD-HHMMSS/          # 带时间戳的设计运行
+│   ├── screenshots/                      # 📸 捕获的截图
+│   │   ├── home.png
+│   │   └── dashboard.png
+│   │
+│   ├── style-extraction/                 # 🎨 样式分析阶段
+│   │   ├── style-cards.json             # AI 提议的风格变体
+│   │   └── design-space-analysis.json   # （探索模式）多样性分析
+│   │
+│   ├── layout-extraction/                # 🏗️ 布局分析阶段
+│   │   └── layout-templates.json        # 包含基于令牌的 CSS 的结构模板
+│   │
+│   ├── style-consolidation/              # ✅ 生产设计系统
+│   │   ├── style-1/
+│   │   │   ├── design-tokens.json       # W3C 设计令牌
+│   │   │   ├── style-guide.md           # 视觉设计文档
+│   │   │   ├── tailwind.config.js       # Tailwind 配置
+│   │   │   └── validation-report.json   # WCAG AA 验证结果
+│   │   └── style-2/
+│   │       └── ...
+│   │
+│   └── prototypes/                       # 🎯 最终 HTML/CSS 原型
+│       ├── home-style-1-layout-1.html   # 矩阵生成的原型
+│       ├── home-style-1-layout-1.css
+│       ├── home-style-1-layout-2.html
+│       ├── dashboard-style-2-layout-1.html
+│       ├── index.html                   # 主导航页面
+│       └── compare.html                 # 并排比较工具
+│
+└── latest -> design-run-YYYYMMDD-HHMMSS  # 指向最新运行的符号链接
+```
+
+**关键文件：**
+
+| 文件 | 目的 | 生成命令 |
+|------|---------|--------------|
+| `style-cards.json` | AI 提议的视觉样式及嵌入的令牌 | `style-extract` |
+| `layout-templates.json` | 包含基于令牌的 CSS 的结构模板 | `layout-extract` |
+| `design-tokens.json` | 可用于生产的 W3C 设计令牌 | `consolidate` |
+| `style-guide.md` | 视觉设计系统文档 | `consolidate` |
+| `compare.html` | 交互式原型比较矩阵 | `generate` |
+
+**最佳实践：**
+
+1. **会话管理**：会话内的所有运行累积在 `.design/design-run-*/`
+2. **版本控制**：每次运行都有时间戳，便于回滚
+3. **集成**：使用 `update` 命令将最终令牌链接到项目产物
+4. **清理**：旧运行可以安全删除；`latest` 符号链接始终指向最新的
+
 ---
 
 ### **任务与内存命令**

WORKFLOW_DIAGRAMS.md

@@ -512,15 +512,13 @@ graph TD
 graph LR
     subgraph "Session Management"
         WFS_START["/workflow:session:start"]
-        WFS_PAUSE["/workflow:session:pause"]
         WFS_RESUME["/workflow:session:resume"]
-        WFS_SWITCH["/workflow:session:switch"]
         WFS_LIST["/workflow:session:list"]
+        WFS_COMPLETE["/workflow:session:complete"]
 
-        WFS_START --> WFS_PAUSE
-        WFS_PAUSE --> WFS_RESUME
-        WFS_RESUME --> WFS_SWITCH
-        WFS_SWITCH --> WFS_LIST
+        WFS_START --> WFS_LIST
+        WFS_LIST --> WFS_RESUME
+        WFS_RESUME --> WFS_COMPLETE
     end
 
     subgraph "Planning Phase"
@@ -554,7 +552,6 @@ graph LR
     WFS_START --> WF_BRAINSTORM
     WF_PLAN --> WF_EXECUTE
     WF_EXECUTE --> TASK_CREATE
-    WF_REVIEW --> WFS_PAUSE
 ```
 
 ## 11. Planning Method Selection Flow

ui-instantiate-analysis.md

@@ -1,231 +0,0 @@
-# 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

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