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/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-verify
+name: concept-clarify
 description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
-usage: /workflow:concept-verify [--session <session-id>]
-argument-hint: "optional: --session <session-id>"
-examples:
-  - /workflow:concept-verify
-  - /workflow:concept-verify --session WFS-auth
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
@@ -255,7 +251,7 @@ You **MUST** consider the user input before proceeding (if not empty).
 
    - ✅ **PROCEED to /workflow:plan**: Conceptual foundation is clear
    - OR ⚠️ **Address Outstanding Items First**: {list critical outstanding items}
-   - OR 🔄 **Run /workflow:concept-verify Again**: If new information available
+   - OR 🔄 **Run /workflow:concept-clarify Again**: If new information available
 
    ### Next Steps
    ```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/auto.md

@@ -1,383 +0,0 @@
----
-name: auto
-description: Fully autonomous UI design workflow with style extraction, consolidation, prototype generation (3×3 matrix), and design system integration
-usage: /workflow:ui-design:auto [--prompt "<desc>"] [--images "<glob>"] [--pages "<list>"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
-argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]"
-examples:
-  - /workflow:ui-design:auto --prompt "Generate 3 style variants for modern blog: home, article, author"
-  - /workflow:ui-design:auto --prompt "SaaS dashboard and settings with 2 layout options"
-  - /workflow:ui-design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:auto --session WFS-auth --images "refs/*.png"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
----
-
-# UI Design Auto Workflow Command
-
-## Overview
-Fully autonomous UI design workflow: style extraction → consolidation → UI generation → design update → optional batch planning. This command orchestrates the entire design process without user intervention.
-
-## Coordinator Role
-**Fully autonomous orchestrator**: Executes all phases sequentially, parsing outputs from one phase to construct the inputs for the next. Supports both standard sequential mode and parallel creative mode for generating diverse design variants.
-
-## Execution Model - Autonomous Workflow
-
-This workflow runs **fully autonomously** from start to finish:
-
-1. **User triggers**: `/workflow:ui-design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" [--batch-plan]`
-2. **Phase 1 executes** (style-extract) → Auto-continues
-3. **Phase 2 executes** (style-consolidate) → Auto-continues
-4. **Phase 3 executes** (ui-generate) → Auto-continues
-5. **Phase 4 executes** (design-update) → Auto-continues
-6. **Phase 5 executes** (batch-plan, optional) → Reports task files
-
-**Auto-Continue Mechanism**:
-- The workflow uses `TodoWrite` to track the state of each phase
-- Upon successful completion of a phase, the coordinator immediately constructs and executes the command for the next phase
-- This pattern ensures a seamless flow
-
-## Core Rules
-
-1. **Start Immediately**: First action is `TodoWrite` initialization, second action is Phase 1 command execution
-2. **No Preliminary Analysis**: Do not read files or validate before Phase 1 (sub-commands handle their own validation)
-3. **Parse Every Output**: Extract required data from each command's output for the next phase
-4. **Auto-Continue**: After each phase, automatically proceed to the next without pausing
-5. **Track Progress**: Update `TodoWrite` after every phase completion
-6. **Default to All**: When selecting variants or prototypes for the next phase, the autonomous workflow defaults to using **all** generated items
-
-## Parameter Requirements
-
-**Optional Parameters** (all have smart defaults):
-- `--pages "<page_list>"`: Pages to generate (if omitted, inferred from prompt/session)
-- `--session <session_id>`: Workflow session ID (if omitted, runs in standalone mode)
-- `--images "<glob_pattern>"`: Reference image paths (default: `design-refs/*`)
-- `--prompt "<description>"`: Text description of design style and pages (supports intelligent parsing)
-- `--style-variants <count>`: Number of style variants to generate (default: inferred from prompt or 3, range: 1-5)
-- `--layout-variants <count>`: Number of layout variants per style (default: inferred from prompt or 3, range: 1-5)
-- `--batch-plan`: Auto-generate implementation tasks after design-update (integrated mode only)
-
-**Input Source Rules**:
-- Must provide at least one of: `--images` or `--prompt`
-- Both can be combined for guided style analysis
-
-**Intelligent Prompt Parsing**:
-The workflow extracts variant counts from natural language:
-- "Generate **3 style variants**" → `--style-variants 3`
-- "**2 layout options**" → `--layout-variants 2`
-- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
-- Explicit flags override prompt inference
-
-## Execution Modes
-
-### Matrix Mode (Default and Only)
-- Generates `style_variants × layout_variants × pages` prototypes in 3×3 matrix pattern
-- **Phase 1 (Style Extraction)**: Generates `style_variants` style options
-- **Phase 2 (Style Consolidation)**: Creates `style_variants` independent design systems
-- **Phase 3 (Matrix Generation)**: Generates `style_variants × layout_variants` prototypes per page
-- This is the only supported mode - focused on systematic design exploration
-
-### Integrated vs. Standalone Mode
-- `--session` flag determines if the workflow is integrated with a larger session or runs standalone
-
-## 6-Phase Execution
-
-### Phase 0a: Intelligent Prompt Parsing
-```bash
-# Extract variant counts from prompt if not explicitly provided
-IF --prompt provided AND (NOT --style-variants OR NOT --layout-variants):
-    prompt_text = {--prompt value}
-
-    # Parse style variants: "3 style variants", "generate 4 styles", etc.
-    style_match = regex_search(prompt_text, r"(\d+)\s*(style\s*variants?|styles?)")
-    IF style_match AND NOT --style-variants:
-        style_variants = int(style_match.group(1))
-    ELSE:
-        style_variants = --style-variants OR 3  # Default to 3
-
-    # Parse layout variants: "2 layout options", "3 layouts each", etc.
-    layout_match = regex_search(prompt_text, r"(\d+)\s*(layout\s*(variants?|options?)|layouts?)")
-    IF layout_match AND NOT --layout-variants:
-        layout_variants = int(layout_match.group(1))
-    ELSE:
-        layout_variants = --layout-variants OR 3  # Default to 3
-ELSE:
-    style_variants = --style-variants OR 3
-    layout_variants = --layout-variants OR 3
-
-VALIDATE: 1 <= style_variants <= 5
-VALIDATE: 1 <= layout_variants <= 5
-
-STORE: style_variants, layout_variants  # For Phase 1 and Phase 3
-```
-
-### Phase 0b: Run Initialization & Directory Setup
-```bash
-# Generate run ID with timestamp
-run_id = "run-$(date +%Y%m%d-%H%M%S)"
-
-# Determine base path
-IF --session:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
-ELSE:
-    # Standalone mode: use scratchpad
-    session_id = "design-session-$(date +%Y%m%d-%H%M%S)"
-    base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
-
-# Create run directory structure
-Bash(mkdir -p "${base_path}/.design/style-extraction")
-Bash(mkdir -p "${base_path}/.design/style-consolidation")
-Bash(mkdir -p "${base_path}/.design/prototypes")
-
-# Initialize run metadata
-Write({base_path}/.run-metadata.json):
-{
-  "run_id": "${run_id}",
-  "session_id": "${session_id}",
-  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
-  "workflow": "ui-design:auto",
-  "parameters": {
-    "style_variants": ${style_variants},
-    "layout_variants": ${layout_variants},
-    "pages": "${inferred_page_list}",
-    "prompt": "${prompt_text}",
-    "images": "${images_pattern}"
-  },
-  "status": "in_progress"
-}
-
-# Update "latest" symlink (Windows-compatible)
-IF --session:
-    Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
-ELSE:
-    # Standalone mode: create symlink in scratchpad session dir
-    Bash(cd ".workflow/.scratchpad/${session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
-
-STORE: run_id, base_path  # Use throughout workflow
-```
-
-### Phase 0c: Page Inference
-```bash
-# Infer page list if not explicitly provided
-IF --pages provided:
-    page_list = parse_csv({--pages value})
-ELSE IF --prompt provided:
-    # Extract page names from prompt (e.g., "blog with home, article, author pages")
-    page_list = extract_pages_from_prompt({--prompt value})
-ELSE IF --session AND exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md):
-    synthesis = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-    page_list = extract_pages_from_synthesis(synthesis)
-ELSE:
-    page_list = ["home"]  # Default fallback
-
-STORE: inferred_page_list = page_list  # For Phase 3
-```
-
-### Phase 1: Style Extraction
-**Command Construction**:
-```bash
-images_flag = --images present ? "--images \"{image_glob}\"" : ""
-prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
-
-# Use run-scoped base path
-run_base_flag = "--base-path \"{base_path}/.design\""
-
-# Use style_variants from Phase 0a
-command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
-SlashCommand(command=command)
-```
-**Auto-Continue**: On completion, proceeds to Phase 2
-
----
-
-### Phase 2: Style Consolidation with Separation (Auto-Triggered)
-**Action**: Consolidates each style variant into separate design systems for matrix generation
-
-**Command Construction**:
-```bash
-# Use run-scoped base path and keep styles separate
-run_base_flag = "--base-path \"{base_path}/.design\""
-
-# Use count-based parameter (automatically uses all style_variants)
-command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --keep-separate"
-```
-**Command**: `SlashCommand(command=command)`
-**Result**: Generates `style_variants` independent design systems:
-- `.design/style-consolidation/style-1/design-tokens.json`
-- `.design/style-consolidation/style-2/design-tokens.json`
-- `.design/style-consolidation/style-3/design-tokens.json`
-
-**Auto-Continue**: On completion, proceeds to Phase 3
-
----
-
-### Phase 3: Matrix UI Generation (Auto-Triggered)
-**Action**: Generates `style_variants × layout_variants × pages` prototypes using matrix mode
-
-**Command Construction**:
-```bash
-run_base_flag = "--base-path \"{base_path}/.design\""
-pages_flag = "--pages \"{inferred_page_list}\""
-
-# Matrix mode is default in generate.md, no mode flag needed
-command = "/workflow:ui-design:generate {run_base_flag} {pages_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
-SlashCommand(command=command)
-```
-
-**Result**: Generates `style_variants × layout_variants × pages` prototypes:
-- File naming: `{page}-style-{s}-layout-{l}.html`
-- Total prototypes: `style_variants * layout_variants * len(inferred_page_list)`
-- Matrix visualization: `compare.html` with interactive 3×3 grid
-
-**Auto-Continue**: On completion, proceeds to Phase 4
-
----
-
-### Phase 4: Design System Integration (Auto-Triggered)
-**Action**: Integrates all generated prototypes and the design system into the brainstorming artifacts
-
-**Command Construction**:
-```bash
-session_flag = --session present ? "--session {session_id}" : ""
-# --selected-prototypes is omitted to default to ALL generated prototypes
-command = "/workflow:ui-design:update {session_flag}"
-```
-**Command**: `SlashCommand(command=command)`
-**Auto-Continue**: If `--batch-plan` is present, proceeds to Phase 5. Otherwise, the workflow completes
-
----
-
-### Phase 5: Batch Task Generation (Optional, Auto-Triggered)
-**Condition**: Only executes if `--batch-plan` flag is present
-
-**Execution**:
-```bash
-FOR each page IN inferred_page_list:
-  SlashCommand(command="/workflow:plan --agent \"Implement {page} page based on design system\"")
-```
-**Completion**: The workflow is now complete
-
-## TodoWrite Pattern (Autonomous)
-
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
-  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing style consolidation"},
-  {"content": "Execute UI prototype generation", "status": "pending", "activeForm": "Executing UI generation"},
-  {"content": "Execute design system integration", "status": "pending", "activeForm": "Executing design system integration"}
-]})
-
-// After Phase 1 completes, before Phase 2 starts
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "completed", "activeForm": "Executing style extraction"},
-  {"content": "Execute style consolidation", "status": "in_progress", "activeForm": "Executing style consolidation"},
-  // ... rest are pending
-]})
-
-// After Phase 2 completes, before Phase 3 starts
-TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "completed"},
-  {"content": "Execute style consolidation", "status": "completed", "activeForm": "Executing style consolidation"},
-  {"content": "Execute UI prototype generation", "status": "in_progress", "activeForm": "Executing UI generation"},
-  // ... rest are pending
-]})
-
-// This pattern continues until all phases are complete
-```
-
-## Error Handling
-
-- **Phase Execution Failures**: The workflow will halt, keeping the failed phase `in_progress`. It will report the error and provide recovery instructions, suggesting a manual command execution with corrected parameters
-- **Default Behavior**: In case of ambiguity (e.g., which variants to select), the system defaults to selecting ALL available items to ensure the workflow can proceed autonomously
-
-## Key Improvements Over Previous Version
-
-1. **Zero External Dependencies**: Pure Claude + agents, no CLI tools
-2. **Streamlined Commands**: Removed `--tool` parameter and all CLI tool flags
-3. **Consistent Execution**: All sub-commands use unified patterns
-4. **Reproducible**: Deterministic flow with clear phase dependencies
-5. **Simpler**: Fewer moving parts, easier to understand and debug
-
-## Workflow Position
-
-The workflow acts as the bridge between brainstorming (`synthesis-specification.md`) and planning (`/workflow:plan`), providing this connection in a fully automated fashion with options for deep creative exploration through parallel agents.
-
-## Example Execution Flows
-
-### Example 1: Default 3×3 Matrix (Prompt Inference)
-```bash
-/workflow:ui-design:auto --prompt "Modern minimalist blog with home, article, and author pages"
-
-# Inferred: 3 style variants, 3 layout variants (default)
-# Executes:
-# 1. /workflow:ui-design:extract --base-path ".../run-xxx/.design" --prompt "..." --variants 3
-# 2. /workflow:ui-design:consolidate --base-path ".../run-xxx/.design" --variants 3 --keep-separate
-# 3. /workflow:ui-design:generate --base-path ".../run-xxx/.design" --pages "home,article,author" --style-variants 3 --layout-variants 3
-# 4. /workflow:ui-design:update
-# Total: 27 prototypes (3 styles × 3 layouts × 3 pages)
-```
-
-### Example 2: Custom 2×2 Matrix with Explicit Parameters
-```bash
-/workflow:ui-design:auto --session WFS-ecommerce --images "refs/*.png" --prompt "E-commerce" --style-variants 2 --layout-variants 2
-
-# Executes:
-# 1. /workflow:ui-design:extract --base-path ".workflow/WFS-ecommerce/runs/run-xxx/.design" --images "refs/*.png" --variants 2
-# 2. /workflow:ui-design:consolidate --base-path "..." --variants 2 --keep-separate
-# 3. /workflow:ui-design:generate --base-path "..." --pages "{inferred}" --style-variants 2 --layout-variants 2
-# 4. /workflow:ui-design:update --session WFS-ecommerce
-# Total: 2×2×N prototypes
-```
-
-### Example 3: Intelligent Parsing with Batch Planning
-```bash
-/workflow:ui-design:auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan
-
-# Parsed: --style-variants 4, --layout-variants 2
-# Executes:
-# 1. /workflow:ui-design:extract --variants 4
-# 2. /workflow:ui-design:consolidate --variants 4 --keep-separate
-# 3. /workflow:ui-design:generate --pages "dashboard,settings" --style-variants 4 --layout-variants 2
-#    (generates 16 prototypes: 4 styles × 2 layouts × 2 pages)
-# 4. /workflow:ui-design:update --session WFS-saas
-# 5. /workflow:plan --agent "Implement dashboard page..."
-#    /workflow:plan --agent "Implement settings page..."
-```
-
-## Final Completion Message
-
-```
-✅ UI Design Auto Workflow Complete!
-
-Run ID: {run_id}
-Session: {session_id or "standalone"}
-Matrix: {style_variants}×{layout_variants} ({total_prototypes} total prototypes)
-Input: {images and/or prompt summary}
-
-Phase 1 - Style Extraction: {style_variants} style variants
-Phase 2 - Style Consolidation: {style_variants} independent design systems
-Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{pages_count} = {total_prototypes} prototypes
-Phase 4 - Design Update: Brainstorming artifacts updated
-{IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
-
-📂 Run Output: {base_path}/
-  ├── .design/style-consolidation/  ({style_variants} design systems)
-  ├── .design/prototypes/           ({total_prototypes} HTML/CSS files)
-  └── .run-metadata.json            (run configuration)
-
-🌐 Interactive Preview: {base_path}/.design/prototypes/compare.html
-  - 3×3 matrix view with synchronized scrolling
-  - Zoom controls and fullscreen mode
-  - Selection export for implementation
-
-{IF batch-plan:
-📋 Implementation Tasks: .workflow/WFS-{session}/.task/
-Next: /workflow:execute to begin implementation
-}
-{ELSE:
-Next Steps:
-1. Open compare.html to preview all variants
-2. Select preferred style×layout combinations
-3. Run /workflow:plan to create implementation tasks
-}
-```

.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,501 +1,267 @@
 ---
 name: consolidate
-description: Consolidate style variants into unified or separate design systems
-usage: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--keep-separate]
-argument-hint: "[--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--variants 3] [--keep-separate]"
-examples:
-  - /workflow:ui-design:consolidate --base-path ".workflow/WFS-auth/latest/.design" --variants 3 --keep-separate
-  - /workflow:ui-design:consolidate --session WFS-auth --variants 2
-  - /workflow:ui-design:consolidate --base-path "./design-session-xxx/.design"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*)
+description: Consolidate style variants into independent design systems and plan layout strategies
+argument-hint: /workflow:ui-design:consolidate [--base-path <path>] [--session <id>] [--variants <count>] [--layout-variants <count>]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(*)
 ---
 
-# Style Consolidation Command
+# Design System Consolidation Command
 
 ## Overview
-Consolidate user-selected style variants into a unified, production-ready design system using Claude's native synthesis capabilities. Merges token proposals from multiple style cards into a cohesive design language.
+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
-- **Claude-Native**: 100% Claude-driven consolidation, no external tools
-- **Token Merging**: Combines `proposed_tokens` from selected variants
-- **Intelligent Synthesis**: Resolves conflicts, ensures consistency
-- **Production-Ready**: Complete design system with documentation
+**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: Setup & Validation
 
-### Phase 1: Path Resolution & Variant Loading
+### Step 1: Resolve Base Path & Load Style Cards
 ```bash
 # Determine base path
-IF --base-path provided:
-    base_path = {provided_base_path}  # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design"
-ELSE IF --session provided:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/latest/.design"  # Use latest run
-ELSE:
-    # Standalone mode: search for most recent design-session in scratchpad
-    base_path = find_latest_design_session(".workflow/.scratchpad/")
-
-# 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 (Count-Based)
+### Step 2: Memory Check (Skip if Already Done)
 ```bash
-# Determine how many variants to consolidate
-IF --variants provided:
-    variants_count = {provided_count}
-    VALIDATE: 1 <= variants_count <= total_variants
-ELSE:
-    # Default to all variants
-    variants_count = total_variants
-
-# Select first N variants
-selected_variants = style_cards.style_cards[0:variants_count]
-VERIFY: selected_variants.length > 0
-
-# Determine consolidation mode
-IF --keep-separate provided:
-    consolidation_mode = "separate"  # Generate N independent design systems
-ELSE:
-    consolidation_mode = "unified"    # Merge into 1 design system
+# 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({base_path}/.brainstorming/synthesis-specification.md)
-ELSE IF exists({base_path}/.brainstorming/ui-designer/analysis.md):
-    design_context = Read({base_path}/.brainstorming/ui-designer/analysis.md)
+# Determine variant count (default: all from style-cards.json)
+bash(cat style-cards.json | grep -c "\"id\": \"variant-")
+
+# Validate variant count
+# Priority: --variants parameter → total_variants from style-cards.json
 ```
 
-### Phase 4: Design System Synthesis (Claude)
+**Output**: `variants_count`, `selected_variants[]`
 
-**Route based on consolidation_mode**:
-
-#### Mode A: Unified Consolidation (Default)
-Merges all style variants into a single, cohesive design system.
-
-**Synthesis Prompt Template**:
-```
-Create a unified, production-ready design system by consolidating the following style variants.
-
-SESSION: {session_id}
-SELECTED VARIANTS: {variant_ids}
-
-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)}
-  ---
-}
-
-{IF design_context:
-DESIGN CONTEXT (from brainstorming):
-{design_context}
-}
-
-TASK: Consolidate these {selected_variants.length} style variant(s) into a single, cohesive design system.
-
-CONSOLIDATION RULES:
-1. **Merge Token Proposals**: Combine all `proposed_tokens` into one unified system
-2. **Resolve Conflicts**: When variants disagree (e.g., different primary colors), choose the most appropriate value or create a balanced compromise
-3. **Maintain Completeness**: Ensure all token categories are present (colors, typography, spacing, etc.)
-4. **Semantic Naming**: Use clear, semantic names (e.g., "brand-primary" not "color-1")
-5. **Accessibility**: Validate WCAG AA contrast ratios (4.5:1 text, 3:1 UI)
-6. **OKLCH Format**: All colors must use oklch(L C H / A) format
-7. **Design Philosophy**: Synthesize a unified philosophy statement from variant descriptions
-
-OUTPUT: Generate the following files as JSON/Markdown:
-
-FILE 1: design-tokens.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": "...", ..., "4xl": "..." },
-    "font_weight": { "normal": "...", "medium": "...", "semibold": "...", "bold": "..." },
-    "line_height": { "tight": "...", "normal": "...", "relaxed": "..." },
-    "letter_spacing": { "tight": "...", "normal": "...", "wide": "..." }
-  },
-  "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" }
-}
-
-FILE 2: style-guide.md
-# Design System Style Guide
-
-## Design Philosophy
-{Synthesized philosophy from all variants}
-
-## Color System
-### Brand Colors
-- **Primary**: {value} - {usage description}
-- **Secondary**: {value} - {usage description}
-- **Accent**: {value} - {usage description}
-
-### Surface Colors
-{List all surface colors with usage}
-
-### Semantic Colors
-{List semantic colors with accessibility notes}
-
-### Text Colors
-{List text colors with contrast ratios}
-
-## Typography
-### Font Families
-{List font families with fallbacks}
-
-### Type Scale
-{Show scale with examples}
-
-### Usage Examples
-```css
-.heading-primary {
-  font-family: var(--font-family-heading);
-  font-size: var(--font-size-3xl);
-  font-weight: var(--font-weight-bold);
-}
-```
-
-## Spacing System
-{Describe spacing scale and usage patterns}
-
-## Component Guidelines
-### Buttons
-{Token-based button styling examples}
-
-### Cards
-{Token-based card styling examples}
-
-### Forms
-{Token-based form styling examples}
-
-## Accessibility
-- All text meets WCAG AA (4.5:1 minimum)
-- UI components meet WCAG AA (3:1 minimum)
-- Focus indicators are clearly visible
-
-FILE 3: tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        brand: {
-          primary: '{value}',
-          secondary: '{value}',
-          accent: '{value}'
-        },
-        // ... all color tokens
-      },
-      fontFamily: {
-        heading: [{fonts}],
-        body: [{fonts}],
-        mono: [{fonts}]
-      },
-      fontSize: {
-        // ... all size tokens
-      },
-      spacing: {
-        // ... all spacing tokens
-      },
-      borderRadius: {
-        // ... all radius tokens
-      },
-      boxShadow: {
-        // ... all shadow tokens
-      },
-      screens: {
-        // ... all breakpoint tokens
-      }
-    }
-  }
-}
-
-FILE 4: validation-report.json
-{
-  "session_id": "{session_id}",
-  "consolidated_variants": {variant_ids},
-  "timestamp": "{ISO timestamp}",
-  "validation_results": {
-    "colors": {
-      "total": {count},
-      "wcag_aa_compliant": {count},
-      "warnings": [{any contrast issues}]
-    },
-    "typography": {
-      "font_families": {count},
-      "scale_sizes": {count}
-    },
-    "spacing": {
-      "scale_values": {count}
-    },
-    "accessibility": {
-      "status": "pass|warnings",
-      "issues": [{list any issues}]
-    },
-    "completeness": {
-      "required_categories": ["colors", "typography", "spacing", "border_radius", "shadows", "breakpoints"],
-      "present_categories": [{list}],
-      "missing_categories": [{list if any}]
-    }
-  }
-}
-
-RESPONSE FORMAT:
-Provide each file's content in clearly labeled sections:
-
-===== design-tokens.json =====
-{JSON content}
-
-===== style-guide.md =====
-{Markdown content}
-
-===== tailwind.config.js =====
-{JavaScript content}
-
-===== validation-report.json =====
-{JSON content}
-```
-
-### Phase 5: Parse & Write Output Files
+### Step 4: Load Design Context (Optional)
 ```bash
-# Parse Claude's response into separate files
-CREATE: {base_path}/.design/style-consolidation/
+# Load brainstorming context
+bash(test -f {base_path}/.brainstorming/synthesis-specification.md && cat it)
 
-# Extract and write each file
-parsed_output = parse_claude_response(claude_response)
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/design-tokens.json",
-  content: parsed_output.design_tokens
-})
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/style-guide.md",
-  content: parsed_output.style_guide
-})
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/tailwind.config.js",
-  content: parsed_output.tailwind_config
-})
-
-Write({
-  file_path: "{base_path}/.design/style-consolidation/validation-report.json",
-  content: parsed_output.validation_report
-})
+# Load design space analysis
+bash(test -f {base_path}/style-extraction/design-space-analysis.json && cat it)
 ```
 
-### Phase 6: TodoWrite & Completion
+**Output**: `design_context`, `design_space_analysis`
+
+## Phase 2: Design System Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)` for all variants
+
+### Step 1: Create Output Directories
+```bash
+bash(mkdir -p {base_path}/style-consolidation/style-{{1..{variants_count}}})
+```
+
+### Step 2: Launch Agent Task
+For all variants (1 to {variants_count}):
 ```javascript
-TodoWrite({
-  todos: [
-    {content: "Load session and style cards", status: "completed", activeForm: "Loading style cards"},
-    {content: "Select and validate variant IDs", status: "completed", activeForm: "Selecting variants"},
-    {content: "Load design context from brainstorming", status: "completed", activeForm: "Loading context"},
-    {content: "Synthesize unified design system with Claude", status: "completed", activeForm: "Synthesizing design system"},
-    {content: "Write consolidated design system files", status: "completed", activeForm: "Writing output files"}
-  ]
-});
+Task(ui-design-agent): `
+  [DESIGN_TOKEN_GENERATION_TASK]
+  Generate {variants_count} independent design systems using philosophy-driven refinement
+
+  SESSION: {session_id} | MODE: Philosophy-driven refinement | BASE_PATH: {base_path}
+
+  CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
+
+  VARIANT DATA:
+  {FOR each variant with index N:
+    VARIANT INDEX: {N} | ID: {variant.id} | NAME: {variant.name}
+    Design Philosophy: {variant.design_philosophy}
+    Proposed Tokens: {variant.proposed_tokens}
+    {IF design_space_analysis: Design Attributes: {attributes}, Anti-keywords: {anti_keywords}}
+  }
+
+  ## 参考
+  - Style cards: Each variant's proposed_tokens and design_philosophy
+  - Design space analysis: design_attributes (saturation, weight, formality, organic/geometric, innovation, density)
+  - Anti-keywords: Explicit constraints to avoid
+  - WCAG AA: 4.5:1 text, 3:1 UI (use built-in AI knowledge)
+
+  ## 生成
+  For EACH variant (use loop index N for paths):
+  1. {base_path}/style-consolidation/style-{N}/design-tokens.json
+     - Complete token structure: colors, typography, spacing, border_radius, shadows, breakpoints
+     - All colors in OKLCH format
+     - Apply design_attributes to token values (saturation→chroma, density→spacing, etc.)
+
+  2. {base_path}/style-consolidation/style-{N}/style-guide.md
+     - Expanded design philosophy
+     - Complete color system with accessibility notes
+     - Typography documentation
+     - Usage guidelines
+
+  ## 注意
+  - ✅ Use Write() tool immediately for each file
+  - ✅ Use loop index N for directory names: style-1/, style-2/, etc.
+  - ❌ DO NOT use variant.id in paths (metadata only)
+  - ❌ NO external research or MCP calls (pure AI refinement)
+  - Apply philosophy-driven refinement: design_attributes guide token values
+  - Maintain divergence: Use anti_keywords to prevent variant convergence
+  - Complete each variant's files before moving to next variant
+`
 ```
 
-**Completion Message**:
+**Output**: Agent generates `variants_count × 2` files
+
+## Phase 3: Verify Output
+
+### Step 1: Check Files Created
+```bash
+# Verify all design systems created
+bash(ls {base_path}/style-consolidation/style-*/design-tokens.json | wc -l)
+
+# Validate structure
+bash(cat {base_path}/style-consolidation/style-1/design-tokens.json | grep -q "colors" && echo "valid")
 ```
-✅ Style consolidation complete for session: {session_id}
 
-Consolidated {selected_variants.length} variant(s):
-{FOR each variant: - {variant.name} ({variant.id})}
+### Step 2: Verify File Sizes
+```bash
+bash(ls -lh {base_path}/style-consolidation/style-1/)
+```
 
-Validation Summary:
-- Colors: {total_colors} (WCAG AA: {compliant_count}/{total_colors})
-- Typography: {scale_count} sizes
-- Spacing: {scale_count} values
-- Accessibility: {status}
+**Output**: `variants_count × 2` files verified
 
-📂 Output: {base_path}/.design/style-consolidation/
-  ├── design-tokens.json        (Final token definitions)
-  ├── style-guide.md             (Design system documentation)
-  ├── tailwind.config.js         (Tailwind configuration)
-  └── validation-report.json     (Validation audit)
+## Completion
 
-Next: /workflow:ui-design:generate --session {session_id} --pages "dashboard,auth"
+### 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"}
+]});
+```
 
-Note: When called from /workflow:ui-design:auto, UI generation is triggered automatically.
+### 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
 
 ```
-.workflow/WFS-{session}/.design/style-consolidation/
-├── design-tokens.json           # Final validated CSS tokens
-├── style-guide.md               # Comprehensive design system documentation
-├── tailwind.config.js           # Tailwind theme configuration
-└── validation-report.json       # Validation audit results
+{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
+## design-tokens.json Format
+
 ```json
 {
   "colors": {
-    "brand": {
-      "primary": "oklch(0.45 0.20 270 / 1)",
-      "secondary": "oklch(0.60 0.15 320 / 1)",
-      "accent": "oklch(0.70 0.18 150 / 1)"
-    },
-    "surface": {
-      "background": "oklch(0.98 0.01 270 / 1)",
-      "elevated": "oklch(1.00 0.00 0 / 1)",
-      "overlay": "oklch(0.95 0.01 270 / 1)"
-    },
-    "semantic": {
-      "success": "oklch(0.60 0.15 142 / 1)",
-      "warning": "oklch(0.75 0.12 85 / 1)",
-      "error": "oklch(0.55 0.22 27 / 1)",
-      "info": "oklch(0.55 0.18 252 / 1)"
-    },
-    "text": {
-      "primary": "oklch(0.20 0.01 270 / 1)",
-      "secondary": "oklch(0.45 0.01 270 / 1)",
-      "tertiary": "oklch(0.60 0.01 270 / 1)",
-      "inverse": "oklch(0.95 0.01 270 / 1)"
-    },
-    "border": {
-      "default": "oklch(0.85 0.01 270 / 1)",
-      "strong": "oklch(0.70 0.01 270 / 1)",
-      "subtle": "oklch(0.92 0.01 270 / 1)"
-    }
+    "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": "Inter, system-ui, sans-serif",
-      "body": "Inter, system-ui, sans-serif",
-      "mono": "JetBrains Mono, Consolas, monospace"
-    },
-    "font_size": {
-      "xs": "0.75rem",
-      "sm": "0.875rem",
-      "base": "1rem",
-      "lg": "1.125rem",
-      "xl": "1.25rem",
-      "2xl": "1.5rem",
-      "3xl": "1.875rem",
-      "4xl": "2.25rem"
-    },
-    "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"
-  }
+  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
 }
 ```
 
+**Requirements**: OKLCH colors, complete coverage, semantic naming
+
 ## Error Handling
-- **No style cards found**: Report error, suggest running `/workflow:ui-design:extract` first
-- **Invalid variant IDs**: List available IDs, auto-select all if called from auto workflow
-- **Parsing errors**: Retry with stricter format instructions
-- **Validation warnings**: Report but continue (non-blocking)
 
-## Key Improvements Over Previous Version
+### Common Errors
+```
+ERROR: No style cards found
+→ Run /workflow:ui-design:style-extract first
 
-1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude
-2. **Direct Token Merging**: Reads `proposed_tokens` from style cards directly
-3. **Single-Pass Synthesis**: One comprehensive prompt generates all outputs
-4. **Reproducible**: Deterministic structure with clear consolidation rules
-5. **Streamlined**: `Load → Synthesize → Write` (3 steps vs 7+ previously)
+ERROR: Invalid variant count
+→ List available count, auto-select all
 
-## Integration Points
-- **Input**: `style-cards.json` from `/workflow:ui-design:extract` (with `proposed_tokens`)
-- **Output**: `design-tokens.json` for `/workflow:ui-design:generate`
-- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md`
+ERROR: Agent file creation failed
+→ Check agent output, verify Write() operations
+```
+
+## Key Features
+
+- **Philosophy-Driven Refinement** - Pure AI token refinement using design_attributes
+- **Agent-Driven** - Uses ui-design-agent for multi-file generation
+- **Separate Design Systems** - N independent systems (one per variant)
+- **Production-Ready** - WCAG AA compliant, OKLCH colors, semantic naming
+- **Zero MCP Calls** - Faster execution, better divergence preservation
+
+## Integration
+
+**Input**: `style-cards.json` from `/workflow:ui-design:style-extract`
+**Output**: `style-consolidation/style-{N}/` for each variant
+**Next**: `/workflow:ui-design:generate --style-variants N`
+
+**Note**: After consolidate, use `/workflow:ui-design:layout-extract` to generate layout templates before running generate.

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

@@ -0,0 +1,489 @@
+---
+name: explore-auto
+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)
+---
+
+# UI Design Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning.
+
+**Unified Target System**: Generates `style_variants × layout_variants × targets` prototypes, where targets can be:
+- **Pages** (full-page layouts): home, dashboard, settings, etc.
+- **Components** (isolated UI elements): navbar, card, hero, form, etc.
+- **Mixed**: Can combine both in a single workflow
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:explore-auto [params]`
+2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
+3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
+4. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
+5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
+6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
+7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+8. Phase 5 (batch-plan, optional) → Reports completion
+
+**Phase Transition Mechanism**:
+- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
+- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
+- Upon each phase completion: Automatically process output and execute next phase
+- No additional user interaction after Phase 0c confirmation
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
+
+**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+2. **No Preliminary Validation**: Sub-commands handle their own validation
+3. **Parse & Pass**: Extract data from each output for next phase
+4. **Default to All**: When selecting variants/prototypes, use ALL generated items
+5. **Track Progress**: Update TodoWrite after each phase
+6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
+
+## Parameter Requirements
+
+**Optional Parameters** (all have smart defaults):
+- `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
+- `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
+- `--device-type "desktop|mobile|tablet|responsive|auto"`: Device type for layout optimization (default: `auto` - intelligent detection)
+  - **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+  - **Mobile**: 375×812px - Touch-friendly, compact layouts
+  - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+  - **Responsive**: 1920×1080px base with mobile-first breakpoints
+- `--session <id>`: Workflow session ID (standalone mode if omitted)
+- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
+- `--prompt "<description>"`: Design style and target description
+- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
+- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
+- `--batch-plan`: Auto-generate implementation tasks after design-update
+
+**Legacy Parameters** (maintained for backward compatibility):
+- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
+- `--components "<list>"`: Alias for `--targets` with `--target-type component`
+
+**Input Rules**:
+- Must provide at least one: `--images` or `--prompt` or `--targets`
+- Multiple parameters can be combined for guided analysis
+- If `--targets` not provided, intelligently inferred from prompt/session
+
+**Supported Target Types**:
+- **Pages** (full layouts): home, dashboard, settings, profile, login, etc.
+- **Components** (UI elements):
+  - Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
+  - Content: hero, card, list, table, grid, timeline
+  - Input: form, search, filter, input-group
+  - Feedback: modal, alert, toast, badge, progress
+  - Media: gallery, carousel, video-player, image-card
+  - Other: footer, pagination, dropdown, tooltip, avatar
+
+**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
+- "Generate **3 style variants**" → `--style-variants 3`
+- "**2 layout options**" → `--layout-variants 2`
+- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
+- Explicit flags override prompt inference
+
+## Execution Modes
+
+**Matrix Mode** (style-centric):
+- Generates `style_variants × layout_variants × targets` prototypes
+- **Phase 1**: `style_variants` style options with design_attributes (extract)
+- **Phase 2**: `style_variants` independent design systems (consolidate)
+- **Phase 3**: Style-centric batch generation (generate)
+  - Sub-phase 1: `targets × layout_variants` target-specific layout plans
+  - **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
+  - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - Performance: Efficient parallel execution with S agents
+  - Quality: HTML structure adapts to design_attributes
+  - Pages: Full-page layouts with complete structure
+  - Components: Isolated elements with minimal wrapper
+
+**Integrated vs. Standalone**:
+- `--session` flag determines session integration or standalone execution
+
+## 6-Phase Execution
+
+### Phase 0a: Intelligent Prompt Parsing
+```bash
+# Parse variant counts from prompt or use explicit/default values
+IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
+    style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
+    layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
+ELSE:
+    style_variants = --style-variants OR 3
+    layout_variants = --layout-variants OR 3
+
+VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+```
+
+### Phase 0a-2: Device Type Inference
+```bash
+# Device type inference
+device_type = "auto"
+
+# Step 1: Explicit parameter (highest priority)
+IF --device-type AND --device-type != "auto":
+    device_type = --device-type
+    device_source = "explicit"
+ELSE:
+    # Step 2: Prompt analysis
+    IF --prompt:
+        device_keywords = {
+            "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
+            "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
+            "tablet": ["tablet", "ipad", "medium screen"],
+            "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
+        }
+        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        IF detected_device:
+            device_type = detected_device
+            device_source = "prompt_inference"
+
+    # Step 3: Target type inference
+    IF device_type == "auto":
+        # Components are typically desktop-first, pages can vary
+        device_type = target_type == "component" ? "desktop" : "responsive"
+        device_source = "target_type_inference"
+
+STORE: device_type, device_source
+```
+
+**Device Type Presets**:
+- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+- **Mobile**: 375×812px - Touch-friendly, compact layouts
+- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+- **Responsive**: 1920×1080px base with mobile-first breakpoints
+
+**Detection Keywords**:
+- Prompt contains "mobile", "phone", "smartphone" → mobile
+- Prompt contains "tablet", "ipad" → tablet
+- Prompt contains "desktop", "web", "laptop" → desktop
+- Prompt contains "responsive", "adaptive" → responsive
+- Otherwise: Inferred from target type (components→desktop, pages→responsive)
+
+### Phase 0b: Run Initialization & Directory Setup
+```bash
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "workflow": "ui-design:auto",
+  "architecture": "style-centric-batch-generation",
+  "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
+                  "targets": "${inferred_target_list}", "target_type": "${target_type}",
+                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "device_type": "${device_type}", "device_source": "${device_source}" },
+  "status": "in_progress",
+  "performance_mode": "optimized"
+}
+```
+
+### Phase 0c: Unified Target Inference with Intelligent Type Detection
+```bash
+# Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
+target_list = []; target_type = "auto"; target_source = "none"
+
+# Step 1-2: Explicit parameters (legacy or unified)
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets); target_source = "explicit"
+    target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
+
+# Step 3: Prompt analysis (Claude internal analysis)
+ELSE IF --prompt:
+    analysis_result = analyze_prompt("{prompt_text}")  # Extract targets, types, purpose
+    target_list = analysis_result.targets
+    target_type = analysis_result.primary_type OR detect_target_type(target_list)
+    target_source = "prompt_analysis"
+
+# Step 4: Session synthesis
+ELSE IF --session AND exists(synthesis-specification.md):
+    target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
+
+# Step 5: Fallback
+IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [normalize(t) for t in target_list if is_valid(t)]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+IF --target-type != "auto": target_type = --target-type
+
+# Interactive confirmation
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets, device_type, device_source):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION (Style-Centric)"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Device: {device_type} | Source: {device_source}"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Performance: {style_variants} agent calls"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Modification Options:"
+  "  • 'continue/yes/ok' - Proceed with current configuration"
+  "  • 'targets: a,b,c' - Replace target list"
+  "  • 'skip: x,y' - Remove specific targets"
+  "  • 'add: z' - Add new targets"
+  "  • 'type: page|component' - Change target type"
+  "  • 'device: desktop|mobile|tablet|responsive' - Change device type"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+user_input = WAIT_FOR_USER_INPUT()
+
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  "device: ..." → device_type = extract_device()
+  default → proceed with current list
+
+STORE: inferred_target_list, target_type, target_inference_source
+
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# This is the only user interaction point in the workflow
+# After this point, all subsequent phases execute automatically without user intervention
+```
+
+**Helper Function: detect_target_type()**
+```bash
+detect_target_type(target_list):
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
+
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
+
+    RETURN "component" IF component_matches > page_matches ELSE "page"
+```
+
+### Phase 1: Style Extraction
+```bash
+command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--mode explore --variants {style_variants}"
+SlashCommand(command)
+
+# Output: {style_variants} style cards with design_attributes
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2 (auto-continue)
+```
+
+### Phase 2: Style Consolidation
+```bash
+command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
+          "--variants {style_variants}"
+SlashCommand(command)
+
+# Output: {style_variants} independent design systems with tokens.css
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
+```
+
+### Phase 2.5: Layout Extraction
+```bash
+targets_string = ",".join(inferred_target_list)
+command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--targets \"{targets_string}\" " +
+          "--mode explore --variants {layout_variants} " +
+          "--device-type \"{device_type}\""
+
+REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
+REPORT: "   → Targets: {targets_string}"
+REPORT: "   → Layout variants: {layout_variants}"
+REPORT: "   → Device: {device_type}"
+
+SlashCommand(command)
+
+# Output: layout-templates.json with {targets × layout_variants} layout structures
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
+```
+
+### Phase 3: UI Assembly
+```bash
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
+
+total = style_variants × layout_variants × len(inferred_target_list)
+
+REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "   → Pure assembly: Combining layout templates + design tokens"
+REPORT: "   → Device: {device_type} (from layout templates)"
+REPORT: "   → Assembly tasks: {total} combinations"
+
+SlashCommand(command)
+
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
+# Output:
+# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
+# - {target}-style-{s}-layout-{l}.css
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
+```
+
+### Phase 4: Design System Integration
+```bash
+command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
+SlashCommand(command)
+
+# SlashCommand blocks until phase complete
+# Upon completion:
+#   - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
+#   - If no --batch-plan: Workflow complete, display final report
+```
+
+### Phase 5: Batch Task Generation (Optional)
+```bash
+IF --batch-plan:
+    FOR target IN inferred_target_list:
+        task_desc = "Implement {target} {target_type} based on design system"
+        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
+```
+
+## TodoWrite Pattern
+```javascript
+// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
+  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
+]})
+
+// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
+// 1. SlashCommand blocks and returns when phase is complete
+// 2. Update current phase: status → "completed"
+// 3. Update next phase: status → "in_progress"
+// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+// This ensures continuous workflow tracking and prevents premature stopping
+```
+
+## Key Features
+
+- **🚀 Performance**: Style-centric batch generation with S agent calls
+- **🎨 Style-Aware**: HTML structure adapts to design_attributes
+- **✅ Perfect Consistency**: Each style by single agent
+- **📦 Autonomous**: No user intervention required between phases
+- **🧠 Intelligent**: Parses natural language, infers targets/types
+- **🔄 Reproducible**: Deterministic flow with isolated run directories
+- **🎯 Flexible**: Supports pages, components, or mixed targets
+
+## Examples
+
+### 1. Page Mode (Prompt Inference)
+```bash
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
+# Result: 27 prototypes (3×3×3) - responsive layouts (default)
+```
+
+### 2. Mobile-First Design
+```bash
+/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
+# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
+```
+
+### 3. Desktop Application
+```bash
+/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
+# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
+```
+
+### 4. Tablet Interface
+```bash
+/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
+# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
+```
+
+### 5. Custom Matrix with Session
+```bash
+/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
+# Result: 2×2×N prototypes - device type inferred from session
+```
+
+### 6. Component Mode (Desktop)
+```bash
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2) - desktop components
+```
+
+### 7. Intelligent Parsing + Batch Planning
+```bash
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
+```
+
+### 8. Large Scale Responsive
+```bash
+/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
+# Result: 36 prototypes (3×3×4) - responsive layouts
+```
+
+## Completion Output
+```
+✅ UI Design Explore-Auto Workflow Complete!
+
+Architecture: Style-Centric Batch Generation
+Run ID: {run_id} | Session: {session_id or "standalone"}
+Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
+
+Phase 1: {s} style variants with design_attributes (style-extract)
+Phase 2: {s} design systems with tokens.css (consolidate)
+Phase 2.5: {n×l} layout templates (layout-extract explore mode)
+  - Device: {device_type} layouts
+  - {n} targets × {l} layout variants = {n×l} structural templates
+Phase 3: UI Assembly (generate)
+  - Pure assembly: layout templates + design tokens
+  - {s}×{l}×{n} = {total} final prototypes
+Phase 4: Brainstorming artifacts updated
+[Phase 5: {n} implementation tasks created]  # if --batch-plan
+
+Assembly Process:
+✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
+✅ Layout Extraction: {n×l} reusable structural templates
+✅ Pure Assembly: No design decisions in generate phase
+✅ Device-Optimized: Layouts designed for {device_type}
+
+Design Quality:
+✅ Token-Driven Styling: 100% var() usage
+✅ Structural Variety: {l} distinct layouts per target
+✅ Style Variety: {s} independent design systems
+✅ Device-Optimized: Layouts designed for {device_type}
+
+📂 {base_path}/
+  ├── style-extraction/       ({s} style cards + design-space-analysis.json)
+  ├── style-consolidation/    ({s} design systems with tokens.css)
+  ├── layout-extraction/      ({n×l} layout templates + layout-space-analysis.json)
+  ├── prototypes/             ({total} assembled prototypes)
+  └── .run-metadata.json      (includes device type)
+
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive {s}×{l} matrix view
+  - Side-by-side comparison
+  - Target-specific layouts with style-aware structure
+  - Toggle between {n} targets
+
+{icon} Targets: {', '.join(targets)} (type: {target_type})
+  - Each target has {l} custom-designed layouts
+  - Each style × target × layout has unique HTML structure (not just CSS!)
+  - Layout plans stored as structured JSON
+  - Optimized for {device_type} viewing
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+```
+

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

@@ -0,0 +1,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,327 +0,0 @@
----
-name: extract
-description: Extract design style from reference images or text prompts using Claude's analysis
-usage: /workflow:ui-design:extract [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>]
-argument-hint: "[--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3]"
-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
-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
-- **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"
-
-# Detect session mode
-IF --session:
-    session_mode = "integrated"
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/"
-ELSE:
-    session_mode = "standalone"
-    session_id = "design-session-" + timestamp()
-    base_path = ".workflow/.scratchpad/{session_id}/"
-
-# Set variant count
-variants_count = --variants provided ? {count} : 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 IN expanded_images:
-        image_data[i] = Read({image_path})  # Load for analysis
-
-IF input_mode IN ["text", "hybrid"]:
-    VALIDATE: --prompt is non-empty string
-    prompt_guidance = {--prompt value}
-
-# Create output directory
-CREATE: {base_path}/.design/style-extraction/
-```
-
-### Phase 2: Unified Style Analysis (Claude)
-This is a single-pass analysis that replaces all external tool calls.
-
-**Analysis Prompt Template**:
-```
-Analyze the following design references and generate {variants_count} distinct design style proposals.
-
-INPUT MODE: {input_mode}
-
-{IF input_mode IN ["image", "hybrid"]}
-VISUAL REFERENCES: {list of loaded images}
-Identify: color palettes, typography patterns, spacing rhythms, visual hierarchy, component styles
-{ENDIF}
-
-{IF input_mode IN ["text", "hybrid"]}
-TEXT GUIDANCE: "{prompt_guidance}"
-Use this to guide the aesthetic direction and feature requirements
-{ENDIF}
-
-TASK: Generate {variants_count} design style variants that:
-1. Each have a distinct visual identity and design philosophy
-2. Use OKLCH color space for all color values
-3. Include complete, production-ready design token proposals
-4. Are semantically organized (brand, surface, semantic colors)
-
-OUTPUT FORMAT: JSON matching this exact structure:
-{
-  "extraction_metadata": {
-    "session_id": "{session_id}",
-    "input_mode": "{input_mode}",
-    "timestamp": "{ISO timestamp}",
-    "variants_count": {variants_count}
-  },
-  "style_cards": [
-    {
-      "id": "variant-1",
-      "name": "Concise Style Name (e.g., Modern Minimalist)",
-      "description": "2-3 sentence description of this style's visual language and user experience",
-      "design_philosophy": "Core design principles for this variant",
-      "preview": {
-        "primary": "oklch(0.45 0.20 270 / 1)",
-        "background": "oklch(0.98 0.01 270 / 1)",
-        "font_heading": "Inter, system-ui, sans-serif",
-        "border_radius": "0.5rem"
-      },
-      "proposed_tokens": {
-        "colors": {
-          "brand": {
-            "primary": "oklch(0.45 0.20 270 / 1)",
-            "secondary": "oklch(0.60 0.15 320 / 1)",
-            "accent": "oklch(0.70 0.18 150 / 1)"
-          },
-          "surface": {
-            "background": "oklch(0.98 0.01 270 / 1)",
-            "elevated": "oklch(1.00 0.00 0 / 1)",
-            "overlay": "oklch(0.95 0.01 270 / 1)"
-          },
-          "semantic": {
-            "success": "oklch(0.60 0.15 142 / 1)",
-            "warning": "oklch(0.75 0.12 85 / 1)",
-            "error": "oklch(0.55 0.22 27 / 1)",
-            "info": "oklch(0.55 0.18 252 / 1)"
-          },
-          "text": {
-            "primary": "oklch(0.20 0.01 270 / 1)",
-            "secondary": "oklch(0.45 0.01 270 / 1)",
-            "tertiary": "oklch(0.60 0.01 270 / 1)",
-            "inverse": "oklch(0.95 0.01 270 / 1)"
-          },
-          "border": {
-            "default": "oklch(0.85 0.01 270 / 1)",
-            "strong": "oklch(0.70 0.01 270 / 1)",
-            "subtle": "oklch(0.92 0.01 270 / 1)"
-          }
-        },
-        "typography": {
-          "font_family": {
-            "heading": "Inter, system-ui, sans-serif",
-            "body": "Inter, system-ui, sans-serif",
-            "mono": "JetBrains Mono, Consolas, monospace"
-          },
-          "font_size": {
-            "xs": "0.75rem",
-            "sm": "0.875rem",
-            "base": "1rem",
-            "lg": "1.125rem",
-            "xl": "1.25rem",
-            "2xl": "1.5rem",
-            "3xl": "1.875rem",
-            "4xl": "2.25rem"
-          },
-          "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"
-        }
-      }
-    }
-  ]
-}
-
-RULES:
-- Each variant must be distinct in visual character
-- All colors MUST use OKLCH format: oklch(L C H / A)
-- Token structures must be complete and production-ready
-- Use semantic naming throughout
-- Ensure accessibility (contrast ratios, readable font sizes)
-```
-
-### Phase 3: Generate & Write Output
-```bash
-# Parse Claude's JSON response
-style_cards_data = parse_json(claude_response)
-
-# Write single output file
-Write({
-  file_path: "{base_path}/.design/style-extraction/style-cards.json",
-  content: style_cards_data
-})
-```
-
-### Phase 4: TodoWrite & Completion
-```javascript
-TodoWrite({
-  todos: [
-    {content: "Validate inputs and create directories", status: "completed", activeForm: "Validating inputs"},
-    {content: "Analyze design references with Claude", status: "completed", activeForm: "Analyzing design"},
-    {content: "Generate {variants_count} style cards with token proposals", status: "completed", activeForm: "Generating style cards"}
-  ]
-});
-```
-
-**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}"}
-
-Generated {variants_count} style variant(s):
-{FOR each card: - {card.name} ({card.id})}
-
-📂 Output: {base_path}/.design/style-extraction/style-cards.json
-
-Next: /workflow:ui-design:consolidate --session {session_id} --variants "{all_variant_ids}"
-
-Note: When called from /workflow:ui-design:auto, consolidation is triggered automatically.
-```
-
-## Output Structure
-
-```
-.workflow/WFS-{session}/.design/style-extraction/
-└── style-cards.json    # Single comprehensive output
-```
-
-### style-cards.json Format (Enhanced)
-```json
-{
-  "extraction_metadata": {
-    "session_id": "WFS-xxx or design-session-xxx",
-    "input_mode": "image|text|hybrid",
-    "timestamp": "2025-01-15T10:30:00Z",
-    "variants_count": 3
-  },
-  "style_cards": [
-    {
-      "id": "variant-1",
-      "name": "Modern Minimalist",
-      "description": "Clean, high-contrast design with bold typography and ample whitespace",
-      "design_philosophy": "Less is more - focus on content clarity and visual breathing room",
-      "preview": {
-        "primary": "oklch(0.45 0.20 270 / 1)",
-        "background": "oklch(0.98 0.01 270 / 1)",
-        "font_heading": "Inter, system-ui, sans-serif",
-        "border_radius": "0.5rem"
-      },
-      "proposed_tokens": {
-        "colors": { /* complete color system */ },
-        "typography": { /* complete typography system */ },
-        "spacing": { /* complete spacing scale */ },
-        "border_radius": { /* border radius scale */ },
-        "shadows": { /* shadow system */ },
-        "breakpoints": { /* responsive breakpoints */ }
-      }
-    }
-  ]
-}
-```
-
-## 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
-
-## Key Improvements Over Previous Version
-
-1. **Zero External Dependencies**: No `gemini-wrapper`, no `codex` - pure Claude
-2. **Single Output File**: Eliminates `semantic_style_analysis.json`, `design-tokens.json`, `tailwind-tokens.js` clutter
-3. **Complete Token Proposals**: Each style card contains a full design system proposal
-4. **Reproducible**: Same inputs = same output structure (content may vary based on Claude model)
-5. **Streamlined Flow**: `Input → Analysis → style-cards.json` (3 steps vs 7+ previously)
-
-## Integration Points
-- **Input**: Reference images (PNG, JPG, WebP) or text prompts
-- **Output**: `style-cards.json` for `/workflow:ui-design:consolidate`
-- **Context**: Optional `synthesis-specification.md` or `ui-designer/analysis.md` can guide prompts

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

@@ -1,441 +1,320 @@
 ---
 name: generate
-description: Generate UI prototypes in matrix mode (style × layout combinations)
-usage: /workflow:ui-design:generate [--pages "<list>"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
-argument-hint: "[--pages \"dashboard,auth\"] [--base-path \".workflow/WFS-xxx/runs/run-xxx/.design\"] [--style-variants 3] [--layout-variants 3]"
-examples:
-  - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/runs/run-xxx/.design" --pages "dashboard,settings" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:generate --session WFS-auth --pages "home,pricing" --style-variants 2 --layout-variants 2
-  - /workflow:ui-design:generate --base-path "./design-session-xxx/.design" --style-variants 3 --layout-variants 3
-allowed-tools: TodoWrite(*), Read(*), Write(*), Task(conceptual-planning-agent), Bash(*)
+description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
+argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---
 
-# UI Generation Command (Matrix Mode)
+# Generate UI Prototypes (/workflow:ui-design:generate)
 
 ## Overview
-Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix mode, strictly adhering to consolidated design tokens from separate style design systems.
+Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
 
-## Core Philosophy
-- **Matrix-Only**: Single mode generating `style_variants × layout_variants × pages` prototypes
-- **Agent-Driven**: Uses `Task(conceptual-planning-agent)` for parallel generation
-- **Token-Driven**: All styles reference per-style design-tokens.json; no hardcoded values
-- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
+**Strategy**: Pure Assembly
+- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available)
+- **Process**: Combine structure (DOM) with style (tokens)
+- **Output**: Complete HTML/CSS prototypes
+- **No Design Logic**: All layout and style decisions already made
+- **Automatic Image Reference**: If source images exist in layout templates, they're automatically used for visual context
 
-## Execution Protocol
+**Prerequisite Commands**:
+- `/workflow:ui-design:style-extract` → Style tokens
+- `/workflow:ui-design:consolidate` → Final design tokens
+- `/workflow:ui-design:layout-extract` → Layout structure
 
-### Phase 1: Path Resolution & Context Loading
+## Phase 1: Setup & Validation
+
+### Step 1: Resolve Base Path & Parse Configuration
 ```bash
-# Determine base path
-IF --base-path provided:
-    base_path = {provided_base_path}  # e.g., ".workflow/WFS-xxx/runs/run-xxx/.design"
-ELSE IF --session provided:
-    session_id = {provided_session}
-    base_path = ".workflow/WFS-{session_id}/latest/.design"  # Use latest run
-ELSE:
-    # Standalone mode: search for most recent design-session in scratchpad
-    base_path = find_latest_design_session(".workflow/.scratchpad/")
+# Determine working directory
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
 
-# Determine style and layout variant counts
-style_variants = --style-variants OR 3  # Default to 3
-layout_variants = --layout-variants OR 3  # Default to 3
+# Get style count
+bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
 
-VALIDATE: 1 <= style_variants <= 5
-VALIDATE: 1 <= layout_variants <= 5
-
-# Infer page list if not provided
-IF --pages provided:
-    page_list = parse_csv({--pages value})
-ELSE IF --session:
-    # Read synthesis-specification.md to extract page requirements
-    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-    page_list = extract_pages_from_synthesis(synthesis_spec)
-ELSE:
-    # Infer from existing prototypes or default
-    page_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]
-
-VALIDATE: page_list not empty
-
-# Verify design systems exist for all styles
-FOR style_id IN range(1, style_variants + 1):
-    VERIFY: {base_path}/style-consolidation/style-{style_id}/design-tokens.json exists
-    VERIFY: {base_path}/style-consolidation/style-{style_id}/style-guide.md exists
-
-# Load requirements (if integrated mode)
-IF --session:
-    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+# Image reference auto-detected from layout template source_image_path
 ```
 
-### Phase 2: Matrix UI Generation (Parallel, Layout-Based)
-Execute parallel agents to generate `style_variants × layout_variants × pages` prototypes.
-Each agent handles ONE layout strategy across MULTIPLE styles (batched to max 8 styles per agent).
-
+### Step 2: Load Layout Templates
 ```bash
-# Create output directory
-CREATE: {base_path}/prototypes/
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
 
-# Calculate style batches (max 8 styles per agent)
-batch_size = 8
-all_style_ids = range(1, style_variants + 1)
-style_batches = split_into_chunks(all_style_ids, batch_size)  # e.g., [[1-8], [9-16]]
-
-# Launch layout_variants × num_batches parallel tasks
-FOR layout_id IN range(1, layout_variants + 1):
-    FOR style_batch IN style_batches:
-        Task(conceptual-planning-agent): "
-          [UI_GENERATION_MATRIX_BATCH]
-
-          Generate prototypes for layout-{layout_id} across a batch of styles.
-
-          ## Context
-          LAYOUT_ID: {layout_id}
-          STYLE_IDS_BATCH: {style_batch}  # e.g., [1, 2, 3, 4, 5, 6, 7, 8]
-          PAGES: {page_list}
-          BASE_PATH: {base_path}
-
-          ## Input Files
-          For each style_id in your batch, you MUST load its corresponding files:
-          - Design Tokens: {base_path}/style-consolidation/style-{style_id}/design-tokens.json
-          - Style Guide: {base_path}/style-consolidation/style-{style_id}/style-guide.md
-          {IF --session: - Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
-
-          ## Task
-          For each style_id in {style_batch}:
-            For each page in [{page_list}]:
-              Generate the prototype files for the specific combination:
-              - {page}-style-{style_id}-layout-{layout_id}.html (semantic HTML5)
-              - {page}-style-{style_id}-layout-{layout_id}.css (token-driven, no hardcoded values)
-              - {page}-style-{style_id}-layout-{layout_id}-notes.md (implementation notes)
-
-          ## Layout Diversity Strategy
-          You are responsible for Layout {layout_id}. Apply this strategy CONSISTENTLY to all styles in your batch.
-
-          {IF layout_id == 1}
-          **Layout 1: Classic Hierarchy**
-          - Traditional F-pattern reading flow
-          - Top navigation with sidebar
-          - Card-based content sections
-          {ELSE IF layout_id == 2}
-          **Layout 2: Modern Asymmetric**
-          - Z-pattern visual flow
-          - Split-screen hero sections
-          - Grid-based modular content
-          {ELSE IF layout_id == 3}
-          **Layout 3: Minimal Focus**
-          - Centered single-column content
-          - Floating navigation
-          - Generous whitespace and breathing room
-          {ELSE}
-          **Layout {layout_id}: Custom Variant**
-          - Develop a unique and consistent layout structure different from the standard three
-          {ENDIF}
-
-          Adapt this strategy to each page's purpose while maintaining layout consistency.
-
-          ## Token Usage Requirements (STRICT)
-          - For each style, load design tokens from its specific file: {base_path}/style-consolidation/style-{style_id}/design-tokens.json
-          - All colors: var(--color-brand-primary), var(--color-surface-background), etc.
-          - All spacing: var(--spacing-4), var(--spacing-6), etc.
-          - All typography: var(--font-family-heading), var(--font-size-lg), etc.
-          - NO hardcoded values (e.g., #4F46E5, 16px) allowed
-
-          ## HTML Requirements
-          - Semantic HTML5 elements (<header>, <nav>, <main>, <section>, <article>)
-          - ARIA attributes for accessibility (role, aria-label, aria-labelledby)
-          - Proper heading hierarchy (h1 → h2 → h3)
-          - Mobile-first responsive design
-
-          ## CSS Requirements
-          - Link to design-tokens.css: <link rel=\"stylesheet\" href=\"../../design-tokens.css\">
-          - Use CSS custom properties from design-tokens.json
-          - Mobile-first media queries using token breakpoints
-          - No inline styles
-          - BEM or semantic class naming
-
-          ## Responsive Design
-          - Mobile: 375px+ (single column, stacked)
-          - Tablet: var(--breakpoint-md) (adapted layout)
-          - Desktop: var(--breakpoint-lg)+ (full layout)
-
-          ## Output Location
-          {base_path}/prototypes/
-
-          ## Deliverables
-          For each page-style-layout combination in your assigned batch:
-          1. HTML file with token-driven structure
-          2. CSS file with custom property references
-          3. Notes file with implementation details and layout rationale
-
-          Total files to generate: {len(page_list) * len(style_batch) * 3}
-        "
-
-# Wait for all {layout_variants * len(style_batches)} parallel tasks to complete
-# Total prototypes: {style_variants * layout_variants * len(page_list)}
+# Load layout templates
+Read({base_path}/layout-extraction/layout-templates.json)
+# Extract: targets, layout_variants count, device_type, template structures
 ```
 
-### Phase 3: Generate Preview Files
+**Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
 
+### Step 3: Validate Design Tokens
 ```bash
-# Read matrix visualization template
-template_content = Read("~/.claude/workflows/_template-compare-matrix.html")
+# Check design tokens exist for all styles
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
 
-# Prepare template variables
-pages_json = JSON.stringify(page_list)
-run_id = extract_run_id_from_base_path({base_path})
-
-# Inject variables into template
-injected_content = template_content
-    .replace("{{run_id}}", run_id)
-    .replace("{{style_variants}}", style_variants)
-    .replace("{{layout_variants}}", layout_variants)
-    .replace("{{pages_json}}", pages_json)
-
-# Write interactive matrix comparison
-Write({base_path}/prototypes/compare.html, injected_content)
-
-# Generate design-tokens.css (unified CSS custom properties for all styles)
-Write({base_path}/prototypes/design-tokens.css):
-/* Auto-generated from all style design systems */
-/* Note: Each prototype links to its specific style's tokens */
-
-:root {
-  /* Fallback tokens - each HTML file should link to its style-specific tokens */
-  /* See style-consolidation/style-{n}/design-tokens.json for actual values */
-}
-
-# Generate simple index.html for quick navigation
-Write({base_path}/prototypes/index.html):
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>UI Prototypes - Matrix View</title>
-  <style>
-    body {
-      font-family: system-ui, sans-serif;
-      max-width: 800px;
-      margin: 2rem auto;
-      padding: 0 1rem;
-    }
-    h1 { color: #2563eb; }
-    .info {
-      background: #f3f4f6;
-      padding: 1rem;
-      border-radius: 0.5rem;
-      margin: 1rem 0;
-    }
-    .cta {
-      display: inline-block;
-      background: #2563eb;
-      color: white;
-      padding: 0.75rem 1.5rem;
-      border-radius: 0.5rem;
-      text-decoration: none;
-      font-weight: 600;
-      margin-top: 1rem;
-    }
-    .cta:hover { background: #1d4ed8; }
-    .stats {
-      display: grid;
-      grid-template-columns: repeat(3, 1fr);
-      gap: 1rem;
-      margin: 1.5rem 0;
-    }
-    .stat {
-      background: white;
-      border: 1px solid #e5e7eb;
-      padding: 1rem;
-      border-radius: 0.5rem;
-      text-align: center;
-    }
-    .stat-value {
-      font-size: 2rem;
-      font-weight: bold;
-      color: #2563eb;
-    }
-    .stat-label {
-      color: #6b7280;
-      font-size: 0.875rem;
-      margin-top: 0.25rem;
-    }
-  </style>
-</head>
-<body>
-  <h1>🎨 UI Prototype Matrix</h1>
-
-  <div class="info">
-    <p><strong>Matrix Configuration:</strong> {style_variants} styles × {layout_variants} layouts × {len(page_list)} pages</p>
-    <p><strong>Total Prototypes:</strong> {style_variants * layout_variants * len(page_list)}</p>
-  </div>
-
-  <div class="stats">
-    <div class="stat">
-      <div class="stat-value">{style_variants}</div>
-      <div class="stat-label">Style Variants</div>
-    </div>
-    <div class="stat">
-      <div class="stat-value">{layout_variants}</div>
-      <div class="stat-label">Layout Options</div>
-    </div>
-    <div class="stat">
-      <div class="stat-value">{len(page_list)}</div>
-      <div class="stat-label">Pages</div>
-    </div>
-  </div>
-
-  <a href="compare.html" class="cta">🔍 Open Interactive Matrix Comparison →</a>
-
-  <h2>Features</h2>
-  <ul>
-    <li>3×3 matrix grid view with synchronized scrolling</li>
-    <li>Zoom controls (25%, 50%, 75%, 100%)</li>
-    <li>Fullscreen mode for individual prototypes</li>
-    <li>Selection system with export functionality</li>
-    <li>Page switcher for multi-page comparison</li>
-  </ul>
-
-  <h2>Generated Pages</h2>
-  <ul>
-    {FOR page IN page_list:
-      <li><strong>{page}</strong>: {style_variants × layout_variants} variants</li>
-    }
-  </ul>
-</body>
-</html>
-
-# Generate PREVIEW.md with instructions
-Write({base_path}/prototypes/PREVIEW.md):
-# UI Prototype Preview Guide
-
-## Quick Start
-1. Open `compare.html` in a modern browser
-2. Use the page selector to switch between pages
-3. Interact with prototypes in the 3×3 matrix
-
-## Matrix Configuration
-- **Style Variants:** {style_variants}
-- **Layout Options:** {layout_variants}
-- **Pages:** {page_list}
-- **Total Prototypes:** {style_variants * layout_variants * len(page_list)}
-
-## File Naming Convention
-`{page}-style-{s}-layout-{l}.html`
-
-Example: `dashboard-style-1-layout-2.html`
-- Page: dashboard
-- Style: Design system 1
-- Layout: Layout variant 2
-
-## Interactive Features
-- **Synchronized Scroll:** All prototypes scroll together
-- **Zoom Controls:** Adjust viewport scale (25%-100%)
-- **Fullscreen:** Click any prototype for detailed view
-- **Selection:** Mark favorites for implementation
-- **Export:** Save selections as JSON
-
-## Design System References
-Each prototype uses tokens from:
-`../style-consolidation/style-{s}/design-tokens.json`
-
-Refer to corresponding `style-guide.md` for design philosophy and usage guidelines.
-
-## Next Steps
-1. Review all variants in compare.html
-2. Select preferred style×layout combinations
-3. Export selections for implementation planning
-4. Run `/workflow:ui-design:update` to integrate chosen designs
+# For each style variant: Load design tokens
+Read({base_path}/style-consolidation/style-{id}/design-tokens.json)
 ```
 
-### Phase 4: TodoWrite & Completion
+**Output**: `design_tokens[]` for all style variants
 
+## Phase 2: Assembly (Agent)
+
+**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
+
+### Step 1: Launch Assembly Tasks
+```bash
+bash(mkdir -p {base_path}/prototypes)
+```
+
+For each `target × style_id × layout_id`:
 ```javascript
-TodoWrite({
-  todos: [
-    {content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
-    {content: `Generate ${style_variants}×${layout_variants}×${page_list.length} prototypes`, status: "completed", activeForm: "Generating matrix prototypes"},
-    {content: "Generate interactive preview files", status: "completed", activeForm: "Generating preview"}
-  ]
-});
+Task(ui-design-agent): `
+  [LAYOUT_STYLE_ASSEMBLY]
+  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
+  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
+
+  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
+  BASE_PATH: {base_path}
+
+  ## Inputs (READ ONLY - NO DESIGN DECISIONS)
+  1. Layout Template:
+     Read("{base_path}/layout-extraction/layout-templates.json")
+     Find template where: target={target} AND variant_id="layout-{layout_id}"
+     Extract: dom_structure, css_layout_rules, device_type, source_image_path
+
+  2. Design Tokens:
+     Read("{base_path}/style-consolidation/style-{style_id}/design-tokens.json")
+     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+
+  3. Reference Image (AUTO-DETECTED):
+     IF template.source_image_path exists:
+       Read(template.source_image_path)
+       Purpose: Additional visual context for better placeholder content generation
+       Note: This is for reference only - layout and style decisions already made
+     ELSE:
+       Use generic placeholder content
+
+  ## Assembly Process
+  1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
+     - Recursively build from template.dom_structure
+     - Add: <!DOCTYPE html>, <head>, <meta viewport>
+     - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
+     - Inject placeholder content:
+       * Default: Use Lorem ipsum, generic sample data
+       * If reference image available: Generate more contextually appropriate placeholders
+         (e.g., realistic headings, meaningful text snippets that match the visual context)
+     - Preserve all attributes from dom_structure
+
+  2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
+     - Start with template.css_layout_rules
+     - Replace ALL var(--*) with actual token values from design-tokens.json
+       Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
+       Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+     - Add visual styling using design tokens:
+       * Colors: tokens.colors.*
+       * Typography: tokens.typography.*
+       * Shadows: tokens.shadows.*
+       * Border radius: tokens.border_radius.*
+     - Device-optimized for template.device_type
+
+  ## Assembly Rules
+  - ✅ Pure assembly: Combine existing structure + existing style
+  - ❌ NO layout design decisions (structure pre-defined)
+  - ❌ NO style design decisions (tokens pre-defined)
+  - ✅ Replace var() with actual values
+  - ✅ Add placeholder content only
+  - Write files IMMEDIATELY
+  - CSS filename MUST match HTML <link href="...">
+`
 ```
 
-**Completion Message**:
+### Step 2: Verify Generated Files
+```bash
+# Count expected vs found
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Validate samples
+Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
+# Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
 ```
-✅ Matrix UI generation complete!
+
+**Output**: `S × L × T × 2` files verified
+
+## Phase 3: Generate Preview Files
+
+### Step 1: Run Preview Generation Script
+```bash
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+**Script generates**:
+- `compare.html` (interactive matrix)
+- `index.html` (navigation)
+- `PREVIEW.md` (instructions)
+
+### Step 2: Verify Preview Files
+```bash
+bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {base_path}/prototypes/PREVIEW.md)
+```
+
+**Output**: 3 preview files
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
+  {content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
+  {content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
+  {content: "Verify files", status: "completed", activeForm: "Validating output"},
+  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
+]});
+```
+
+### Output Message
+```
+✅ UI prototype assembly complete!
 
 Configuration:
 - Style Variants: {style_variants}
-- Layout Options: {layout_variants}
-- Pages: {page_list}
-- Total Prototypes: {style_variants * layout_variants * len(page_list)}
+- Layout Variants: {layout_variants} (from layout-templates.json)
+- Device Type: {device_type}
+- Targets: {targets}
+- Total Prototypes: {S × L × T}
+- Image Reference: Auto-detected (uses source images when available in layout templates)
+
+Assembly Process:
+- Pure assembly: Combined pre-extracted layouts + design tokens
+- No design decisions: All structure and style pre-defined
+- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations
+
+Quality:
+- Structure: From layout-extract (DOM, CSS layout rules)
+- Style: From consolidate (design tokens)
+- CSS: Token values directly applied (var() replaced)
+- Device-optimized: Layouts match device_type from templates
 
 Generated Files:
-{FOR style_id IN range(1, style_variants + 1):
-  {FOR layout_id IN range(1, layout_variants + 1):
-    {FOR page IN page_list:
-      - {page}-style-{style_id}-layout-{layout_id}.html
-    }
-  }
-}
+{base_path}/prototypes/
+├── _templates/
+│   └── layout-templates.json (input, pre-extracted)
+├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
+├── {target}-style-{s}-layout-{l}.css
+├── compare.html (interactive matrix)
+├── index.html (navigation)
+└── PREVIEW.md (instructions)
 
-📂 Location: {base_path}/prototypes/
+Preview:
+1. Open compare.html (recommended)
+2. Open index.html
+3. Read PREVIEW.md
 
-🌐 Interactive Preview:
-1. Matrix View: Open compare.html (recommended)
-2. Quick Index: Open index.html
-3. Instructions: See PREVIEW.md
+Next: /workflow:ui-design:update
+```
 
-Features:
-- 3×3 matrix grid with synchronized scrolling
-- Zoom controls and fullscreen mode
-- Selection export for implementation
-- Per-page comparison
+## Simple Bash Commands
 
-Next: /workflow:ui-design:update {--session flag if applicable}
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
 
-Note: When called from /workflow:ui-design:auto, design-update is triggered automatically.
+# Count style variants
+bash(ls {base_path}/style-consolidation/style-* -d | wc -l)
+```
+
+### Validation Commands
+```bash
+# Check layout templates exist
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Check design tokens exist
+bash(test -f {base_path}/style-consolidation/style-1/design-tokens.json && echo "valid")
+
+# Count generated files
+bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
+
+# Verify preview
+bash(test -f {base_path}/prototypes/compare.html && echo "exists")
+```
+
+### File Operations
+```bash
+# Create directories
+bash(mkdir -p {base_path}/prototypes)
+
+# Run preview script
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 ```
 
 ## Output Structure
 
 ```
-{base_path}/prototypes/
-├── compare.html                           # Interactive matrix visualization
-├── index.html                             # Simple navigation page
-├── PREVIEW.md                             # Preview instructions
-├── design-tokens.css                      # CSS custom properties fallback
-├── {page}-style-{s}-layout-{l}.html      # Matrix prototype files
-├── {page}-style-{s}-layout-{l}.css
-├── {page}-style-{s}-layout-{l}-notes.md
-└── ... (all style×layout×page combinations)
+{base_path}/
+├── layout-extraction/
+│   └── layout-templates.json      # Input (from layout-extract)
+├── style-consolidation/
+│   └── style-{s}/
+│       ├── design-tokens.json     # Input (from consolidate)
+│       └── style-guide.md
+└── prototypes/
+    ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
+    ├── {target}-style-{s}-layout-{l}.css
+    ├── compare.html
+    ├── index.html
+    └── PREVIEW.md
 ```
 
 ## Error Handling
-- **No design systems found**: Run `/workflow:ui-design:consolidate --keep-separate` first
-- **Invalid page names**: Extract from synthesis-specification.md or error
-- **Agent execution errors**: Report details, suggest retry
-- **Missing template**: Provide fallback or error with template path
 
-## Quality Checks
-After generation, ensure:
-- [ ] All CSS values reference design token custom properties
-- [ ] No hardcoded colors, spacing, or typography
-- [ ] Semantic HTML structure
-- [ ] ARIA attributes present
-- [ ] Responsive design implemented
-- [ ] Mobile-first approach
-- [ ] File naming follows `{page}-style-{s}-layout-{l}` convention
-- [ ] compare.html loads correctly with all prototypes
+### Common Errors
+```
+ERROR: Layout templates not found
+→ Run /workflow:ui-design:layout-extract first
+
+ERROR: Design tokens not found
+→ Run /workflow:ui-design:consolidate first
+
+ERROR: Agent assembly failed
+→ Check inputs exist, validate JSON structure
+
+ERROR: Script permission denied
+→ chmod +x ~/.claude/scripts/ui-generate-preview.sh
+```
+
+### Recovery Strategies
+- **Partial success**: Keep successful assembly combinations
+- **Invalid template structure**: Validate layout-templates.json
+- **Invalid tokens**: Validate design-tokens.json structure
+
+## Quality Checklist
+
+- [ ] CSS uses direct token values (var() replaced)
+- [ ] HTML structure matches layout template exactly
+- [ ] Semantic HTML5 structure preserved
+- [ ] ARIA attributes from template present
+- [ ] Device-specific optimizations applied
+- [ ] All token references resolved
+- [ ] compare.html works
 
 ## Key Features
 
-1. **Matrix-Only Mode**: Simplified, focused workflow
-2. **Parallel Generation**: All style×layout combinations in parallel
-3. **Interactive Visualization**: Full-featured compare.html from template
-4. **Per-Style Tokens**: Each prototype references its style's design system
-5. **Systematic Exploration**: Consistent layout strategies across all styles
+- **Pure Assembly**: No design decisions, only combination
+- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
+- **Token Resolution**: var() placeholders replaced with actual values
+- **Pre-validated**: Inputs already validated by extract/consolidate
+- **Efficient**: Simple assembly vs complex generation
+- **Production-Ready**: Semantic, accessible, token-driven
 
-## Integration Points
-- **Input**: Per-style design-tokens.json from `/workflow:ui-design:consolidate --keep-separate`
-- **Output**: Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
-- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
-- **Context**: synthesis-specification.md for page requirements (optional)
+## Integration
+
+**Prerequisites**:
+- `/workflow:ui-design:style-extract` → `style-cards.json`
+- `/workflow:ui-design:consolidate` → `design-tokens.json`
+- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+
+**Input**: `layout-templates.json` + `design-tokens.json`
+**Output**: S×L×T prototypes for `/workflow:ui-design:update`
+**Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`

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

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

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

@@ -0,0 +1,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,96 +1,99 @@
 ---
 name: update
-description: Update brainstorming artifacts with finalized design system
-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"
-allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*), Bash(*)
+description: Update brainstorming artifacts with finalized design system references
+argument-hint: --session <session_id> [--selected-prototypes "<list>"]
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Design Update Command
 
 ## Overview
-Synchronize finalized design system (tokens, style guide, selected prototypes) back to brainstorming artifacts, preparing for `/workflow:plan` phase consumption.
+
+Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
 
 ## Core Philosophy
-- **Main Claude Execution**: Direct updates by main Claude (avoid Agent context loss, following synthesis pattern)
-- **Reference-Based Integration**: Use @ references, not content duplication
+
+- **Reference-Only Updates**: Use @ references, no content duplication
+- **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
 - **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
-- **UI Designer Sync**: Mirror design system to ui-designer/style-guide.md
 - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
+- **Minimal Reading**: Verify file existence, don't read design content
 
 ## Execution Protocol
 
-### Phase 1: Session & Design System Validation
+### Phase 1: Session & Artifact Validation
+
 ```bash
-# Validate session and verify design system completeness
-CHECK: .workflow/.active-* marker files
-VALIDATE: session_id matches active session
+# Validate session
+CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
 
-VERIFY required artifacts:
-- .design/style-consolidation/design-tokens.json
-- .design/style-consolidation/style-guide.md
-- .design/style-consolidation/tailwind.config.js
-- .design/prototypes/*.html (at least one prototype)
+# Verify design artifacts in latest design run
+latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
 
-IF --selected-prototypes provided:
-    VALIDATE: Specified prototypes exist
+# Detect design system structure (unified vs separate)
+IF exists({latest_design}/style-consolidation/design-tokens.json):
+    design_system_mode = "unified"; design_tokens_path = "style-consolidation/design-tokens.json"; style_guide_path = "style-consolidation/style-guide.md"
+ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
+    design_system_mode = "separate"; design_tokens_path = "style-consolidation/style-1/design-tokens.json"; style_guide_path = "style-consolidation/style-1/style-guide.md"
 ELSE:
-    AUTO-SELECT: Use all generated prototypes
+    ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"
+
+VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
+
+REPORT: "📋 Design system mode: {design_system_mode} | Tokens: {design_tokens_path}"
+
+# Prototype selection
+selected_list = --selected-prototypes ? parse_comma_separated(--selected-prototypes) : Glob({latest_design}/prototypes/*.html)
+VALIDATE: Specified prototypes exist IF --selected-prototypes
+
+REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
 ```
 
-### Phase 2: Load Design System Context
-**Direct Claude Code Execution** (no Agent invocation)
+### Phase 1.1: Memory Check (Skip if Already Updated)
 
 ```bash
-# Load all design system artifacts
-Read(.workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)
-Read(.workflow/WFS-{session}/.design/style-consolidation/style-guide.md)
-Read(.workflow/WFS-{session}/.design/style-consolidation/tailwind.config.js)
-Read(.workflow/WFS-{session}/.design/style-consolidation/validation-report.json)
+# 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"
 
-# Load selected prototype files
-FOR each selected_prototype IN selected_prototypes:
-    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}.html)
-    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
+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
+```
 
-# Load target brainstorming artifacts
+### Phase 2: Load Target Artifacts Only
+
+**What to Load**: Only the files we need to **update**, not the design files we're referencing.
+
+```bash
+# Load target brainstorming artifacts (files to be updated)
 Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
+IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
+
+# Optional: Read prototype notes for descriptions (minimal context)
+FOR each selected_prototype IN selected_list:
+    Read({latest_design}/prototypes/{selected_prototype}-notes.md)  # Extract: layout_strategy, page_name only
+
+# Note: Do NOT read design-tokens.json, style-guide.md, or prototype HTML. Only verify existence and generate @ references.
 ```
 
 ### Phase 3: Update Synthesis Specification
-**Direct Write by Main Claude**
 
-Update `.brainstorming/synthesis-specification.md`:
+Update `.brainstorming/synthesis-specification.md` with design system references.
 
+**Target Section**: `## UI/UX Guidelines`
+
+**Content Template**:
 ```markdown
 ## UI/UX Guidelines
 
 ### Design System Reference
-**Finalized Design Tokens**: @../.design/style-consolidation/design-tokens.json
-**Style Guide**: @../.design/style-consolidation/style-guide.md
-**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
-
-### Design Philosophy
-[Extract philosophy section from style-guide.md]
-
-### Token System Overview
-**Colors**: OKLCH-based color system with semantic naming
-- Brand: primary, secondary, accent
-- Surface: background, elevated, sunken
-- Semantic: success, warning, error, info
-
-**Typography**: {font_family_count} font families, {scale_count}-step scale
-- Heading: {heading_font}
-- Body: {body_font}
-- Monospace: {mono_font}
-
-**Spacing**: {scale_count}-step scale ({min}rem to {max}rem)
-
-**Components**: Border radius, shadows, and component tokens defined
+**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../design-{run_id}/{style_guide_path}
+**Design System Mode**: {design_system_mode}
 
 ### Implementation Requirements
 **Token Adherence**: All UI implementations MUST use design token CSS custom properties
@@ -99,68 +102,41 @@ Update `.brainstorming/synthesis-specification.md`:
 **Component Patterns**: Follow patterns documented in style-guide.md
 
 ### Reference Prototypes
-[For each selected prototype:]
-- **{page_name}**: @../.design/prototypes/{prototype}.html
-  - Layout: {layout_description from notes}
-  - Components: {component_list from notes}
-  - Token Usage: {token_usage_summary from notes}
-
-### Design System Assets (for task-generate consumption)
-```json
-{
-  "design_tokens": ".design/style-consolidation/design-tokens.json",
-  "style_guide": ".design/style-consolidation/style-guide.md",
-  "tailwind_config": ".design/style-consolidation/tailwind.config.js",
-  "prototypes": [
-    ".design/prototypes/{prototype-1}.html",
-    ".design/prototypes/{prototype-2}.html"
-  ]
+{FOR each selected_prototype:
+- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
 }
+
+### Design System Assets
+```json
+{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
 ```
 ```
 
 **Implementation**:
 ```bash
-# Edit synthesis-specification.md
-Edit(
-  file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
-  old_string="## UI/UX Guidelines\n[existing content or empty]",
-  new_string="## UI/UX Guidelines\n\n[new design system content with @ references]"
-)
+# Option 1: Edit existing section
+Edit(file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
+     old_string="## UI/UX Guidelines\n[existing content]",
+     new_string="## UI/UX Guidelines\n\n[new design reference content]")
+
+# Option 2: Append if section doesn't exist
+IF section not found:
+    Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
 ```
 
-### Phase 4: Update UI Designer Analysis
-**Create or update** `.brainstorming/ui-designer/style-guide.md`:
+### Phase 4: Update UI Designer Style Guide
+
+Create or update `.brainstorming/ui-designer/style-guide.md`:
 
 ```markdown
 # UI Designer Style Guide
 
 ## Design System Integration
-This style guide integrates the finalized design system from the design refinement phase.
+This style guide references the finalized design system from the design refinement phase.
 
-**Source Design Tokens**: @../../.design/style-consolidation/design-tokens.json
-**Source Style Guide**: @../../.design/style-consolidation/style-guide.md
-
-## Design Philosophy
-[Extract philosophy section from source style-guide.md]
-
-## Design Tokens Reference
-For complete token definitions, see: @../../.design/style-consolidation/design-tokens.json
-
-### Color System
-[Summary of color tokens]
-
-### Typography System
-[Summary of typography tokens]
-
-### Spacing System
-[Summary of spacing tokens]
-
-### Component Tokens
-[Summary of component tokens: border-radius, shadows]
-
-## Component Patterns
-[Reference to style-guide.md component patterns]
+**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Design System Mode**: {design_system_mode}
 
 ## Implementation Guidelines
 1. **Use CSS Custom Properties**: All styles reference design tokens
@@ -169,62 +145,49 @@ For complete token definitions, see: @../../.design/style-consolidation/design-t
 4. **Responsive Design**: Mobile-first with token-based breakpoints
 
 ## Reference Prototypes
-[Links to selected prototypes with descriptions]
+{FOR each selected_prototype:
+- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
+}
+
+## Token System
+For complete token definitions and usage examples, see:
+- Design Tokens: @../../design-{run_id}/{design_tokens_path}
+- Style Guide: @../../design-{run_id}/{style_guide_path}
 
 ---
-*Auto-generated by /workflow:design:design-update*
-*Last updated: {timestamp}*
+*Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
 ```
 
 **Implementation**:
 ```bash
-Write(
-  file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
-  content="[generated style guide content with @ references]"
-)
+Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
+      content="[generated content with @ references]")
 ```
 
-### Phase 5: Create Design System Symlinks (Optional)
-**For easier task-generate discovery**
+### Phase 5: Completion
 
-```bash
-# Create read-only mirror of key design files in brainstorming space
-bash(cd .workflow/WFS-{session}/.brainstorming && \
-     ln -s ../.design/style-consolidation/design-tokens.json design-tokens.json && \
-     ln -s ../.design/style-consolidation/style-guide.md design-style-guide.md)
-```
-
-### Phase 6: TodoWrite Integration
 ```javascript
-TodoWrite({
-  todos: [
-    {
-      content: "Validate session and design system completeness",
-      status: "completed",
-      activeForm: "Validating design system"
-    },
-    {
-      content: "Load design tokens, style guide, and selected prototypes",
-      status: "completed",
-      activeForm: "Loading design artifacts"
-    },
-    {
-      content: "Update synthesis-specification.md with design system references",
-      status: "completed",
-      activeForm: "Updating synthesis specification"
-    },
-    {
-      content: "Create or update ui-designer/style-guide.md",
-      status: "completed",
-      activeForm: "Updating UI designer style guide"
-    },
-    {
-      content: "Create design system symlinks for task-generate discovery",
-      status: "completed",
-      activeForm: "Creating artifact symlinks"
-    }
-  ]
-});
+TodoWrite({todos: [
+  {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
+  {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
+  {content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
+  {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Design system references updated for session: WFS-{session}
+
+Updated artifacts:
+✓ synthesis-specification.md - UI/UX Guidelines section with @ references
+✓ ui-designer/style-guide.md - Design system reference guide
+
+Design system assets ready for /workflow:plan:
+- design-tokens.json | style-guide.md | {prototype_count} reference prototypes
+
+Next: /workflow:plan [--agent] "<task description>"
+      The plan phase will automatically discover and utilize the design system.
 ```
 
 ## Output Structure
@@ -233,116 +196,89 @@ TodoWrite({
 ```
 .workflow/WFS-{session}/.brainstorming/
 ├── synthesis-specification.md       # Updated with UI/UX Guidelines section
-├── ui-designer/
-│   └── style-guide.md               # New or updated comprehensive style guide
-├── design-tokens.json               # Symlink to ../.design/style-consolidation/design-tokens.json
-└── design-style-guide.md            # Symlink to ../.design/style-consolidation/style-guide.md
+└── ui-designer/
+    └── style-guide.md               # New or updated design reference guide
 ```
 
-**Reference Structure** (@ references in synthesis-specification.md):
-- `@../.design/style-consolidation/design-tokens.json`
-- `@../.design/style-consolidation/style-guide.md`
-- `@../.design/style-consolidation/tailwind.config.js`
-- `@../.design/prototypes/{prototype}.html`
+**@ Reference Format** (synthesis-specification.md):
+```
+@../design-{run_id}/style-consolidation/design-tokens.json
+@../design-{run_id}/style-consolidation/style-guide.md
+@../design-{run_id}/prototypes/{prototype}.html
+```
 
-## Integration with task-generate
+**@ Reference Format** (ui-designer/style-guide.md):
+```
+@../../design-{run_id}/style-consolidation/design-tokens.json
+@../../design-{run_id}/style-consolidation/style-guide.md
+@../../design-{run_id}/prototypes/{prototype}.html
+```
 
-After this update, `/workflow:tools:task-generate` will discover:
+## Integration with /workflow:plan
 
-**In context.artifacts**:
+After this update, `/workflow:plan` will discover design assets through:
+
+**Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
+- Reads synthesis-specification.md → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
+
+**Phase 4: Task Generation** (`/workflow:tools:task-generate`)
+- Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
+
+**Example Task JSON** (generated by task-generate):
 ```json
 {
-  "artifacts": [
-    {
-      "type": "synthesis_specification",
-      "path": ".brainstorming/synthesis-specification.md"
-    },
-    {
-      "type": "design_tokens",
-      "path": ".design/style-consolidation/design-tokens.json"
-    },
-    {
-      "type": "style_guide",
-      "path": ".design/style-consolidation/style-guide.md"
-    },
-    {
-      "type": "tailwind_config",
-      "path": ".design/style-consolidation/tailwind.config.js"
-    },
-    {
-      "type": "ui_prototypes",
-      "paths": [
-        ".design/prototypes/dashboard-variant-1.html",
-        ".design/prototypes/auth-variant-2.html"
-      ]
+  "task_id": "IMPL-001",
+  "context": {
+    "design_system": {
+      "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
+      "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
+      "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
     }
-  ]
-}
-```
-
-**In flow_control.pre_analysis** (for UI tasks):
-```json
-{
-  "step": "load_design_tokens",
-  "action": "Load design system tokens and style guide",
-  "commands": [
-    "bash(cat .workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)",
-    "bash(cat .workflow/WFS-{session}/.design/style-consolidation/style-guide.md)"
-  ],
-  "output_to": "design_system_context",
-  "on_error": "warn"
+  }
 }
 ```
 
 ## Error Handling
-- **Missing design tokens**: Error, run `/workflow:ui-design:consolidate` first
-- **Missing prototypes**: Error, run `/workflow:ui-design:generate` first
-- **synthesis-specification.md not found**: Warning, create minimal version
-- **Edit conflicts**: Preserve existing content, append design system section
-- **Symlink failures**: Warning only, continue with @ references
+
+- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
+- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
+- **ui-designer/ directory missing**: Create directory and file
+- **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
+- **Invalid prototype names**: Skip invalid entries, continue with valid ones
 
 ## Validation Checks
+
 After update, verify:
 - [ ] synthesis-specification.md contains UI/UX Guidelines section
-- [ ] UI/UX Guidelines include @ references to design system files
+- [ ] UI/UX Guidelines include @ references (not content duplication)
 - [ ] ui-designer/style-guide.md created or updated
-- [ ] design-tokens.json symlink created (if applicable)
-- [ ] All referenced files exist and are readable
+- [ ] All @ referenced files exist and are accessible
+- [ ] @ reference paths are relative and correct
+
+## Key Features
+
+1. **Reference-Only Updates**: Uses @ notation for file references, no content duplication, lightweight and maintainable
+2. **Main Claude Direct Execution**: No Agent handoff (preserves context), simple reference generation, reliable path resolution
+3. **Plan-Ready Output**: `/workflow:plan` Phase 3 can discover design system, task generation includes design asset paths, clear integration points
+4. **Minimal Reading**: Only reads target files to update, verifies design file existence (no content reading), optional prototype notes for descriptions
+5. **Flexible Prototype Selection**: Auto-select all prototypes (default), manual selection via --selected-prototypes parameter, validates existence
 
 ## Integration Points
-- **Input**: design-tokens.json, style-guide.md, prototypes from design phase
-- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md
-- **Next Phase**: `/workflow:plan` can now discover and utilize design system
 
-## Completion Message
+- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
+- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
+- **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
 
-```
-Design system update complete for session: WFS-{session}
-
-Updated artifacts:
-✓ synthesis-specification.md - UI/UX Guidelines section added
-✓ ui-designer/style-guide.md - Comprehensive style guide created
-✓ Design system references: @ notation for all design files
-
-Design system assets ready for task generation:
-- design-tokens.json ({token_count} tokens)
-- style-guide.md (comprehensive component patterns)
-- tailwind.config.js (Tailwind theme extension)
-- {prototype_count} reference prototypes
-
-Next: /workflow:plan [--agent] "<task description>"
-      The plan phase will automatically discover and utilize the design system.
-```
-
-## Main Claude Direct Execution Rationale
+## Why Main Claude Execution?
 
 This command is executed directly by main Claude (not delegated to an Agent) because:
 
-1. **Context Preservation**: Main Claude has full session context and conversation memory
-2. **Integration Complexity**: Requires understanding multiple artifact relationships
-3. **Reference Accuracy**: @ reference generation needs precise path resolution
-4. **Synthesis Pattern**: Follows the same direct-execution pattern as `/workflow:brainstorm:synthesis`
-5. **Minimal Transformation**: Primarily reference integration, not generative analysis
-6. **Error Recovery**: Main Claude can better handle edit conflicts and missing files
+1. **Simple Reference Generation**: Only generating file paths, not complex synthesis
+2. **Context Preservation**: Main Claude has full session and conversation context
+3. **Minimal Transformation**: Primarily updating references, not analyzing content
+4. **Path Resolution**: Requires precise relative path calculation
+5. **Edit Operations**: Better error recovery for Edit conflicts
+6. **Synthesis Pattern**: Follows same direct-execution pattern as other reference updates
 
-This approach ensures reliable, context-aware integration without Agent handoff overhead.
+This ensures reliable, lightweight integration without Agent handoff overhead.

.claude/scripts/convert_tokens_to_css.sh

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

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

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

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

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

.claude/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
 
@@ -276,6 +676,22 @@ All workflows use the same file structure definition regardless of complexity. *
 │   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
 │   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
 │
+├── [.design/]                  # Standalone UI design outputs (created when needed)
+│   └── run-[timestamp]/        # Timestamped design runs without session
+│       ├── style-extraction/   # Style analysis results
+│       ├── style-consolidation/ # Design system tokens (per-style)
+│       │   ├── style-1/        # design-tokens.json, style-guide.md
+│       │   └── style-N/
+│       ├── prototypes/         # Generated HTML/CSS prototypes
+│       │   ├── _templates/     # Target-specific layout plans and templates
+│       │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+│       │   │   ├── {target}-layout-{n}.html  # HTML template
+│       │   │   └── {target}-layout-{n}.css   # CSS template
+│       │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+│       │   ├── compare.html    # Interactive matrix view
+│       │   └── index.html      # Navigation page
+│       └── .run-metadata.json  # Run configuration
+│
 └── WFS-[topic-slug]/
     ├── workflow-session.json        # Session metadata and state (REQUIRED)
     ├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
@@ -289,6 +705,20 @@ All workflows use the same file structure definition regardless of complexity. *
     ├── [.summaries/]               # Task completion summaries (created when tasks complete)
     │   ├── IMPL-*-summary.md      # Main task summaries
     │   └── IMPL-*.*-summary.md    # Subtask summaries
+    ├── [design-*/]                 # UI design outputs (created by ui-design workflows)
+    │   ├── style-extraction/       # Style analysis results
+    │   ├── style-consolidation/    # Design system tokens (per-style)
+    │   │   ├── style-1/            # design-tokens.json, style-guide.md
+    │   │   └── style-N/
+    │   ├── prototypes/             # Generated HTML/CSS prototypes
+    │   │   ├── _templates/         # Target-specific layout plans and templates
+    │   │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+    │   │   │   ├── {target}-layout-{n}.html  # HTML template
+    │   │   │   └── {target}-layout-{n}.css   # CSS template
+    │   │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+    │   │   ├── compare.html        # Interactive matrix view
+    │   │   └── index.html          # Navigation page
+    │   └── .run-metadata.json      # Run configuration
     └── .task/                      # Task definitions (REQUIRED)
         ├── IMPL-*.json             # Main task definitions
         └── IMPL-*.*.json           # Subtask definitions (created dynamically)
@@ -299,6 +729,8 @@ All workflows use the same file structure definition regardless of complexity. *
 - **On-Demand Creation**: Other directories created when first needed
 - **Dynamic Files**: Subtask JSON files created during task decomposition
 - **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
+- **Design Usage**: `design-{timestamp}/` created by UI design workflows, `.design/` for standalone design runs
+- **Layout Planning**: `prototypes/_templates/` contains target-specific layout plans (JSON) generated during UI generation phase
 
 #### Scratchpad Directory (.scratchpad/)
 **Purpose**: Centralized location for non-session-specific CLI outputs

.github/release-notes-v3.5.0.md

@@ -1,235 +0,0 @@
-# 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview
-
-This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, zero agent overhead, and enhanced preview tools for real-time prototype comparison.
-
-## 🌟 Major Features
-
-### UI Design Workflow System
-- **`/workflow:design:auto`**: Semi-autonomous workflow orchestrator with interactive checkpoints
-- **`/workflow:design:style-extract`**: Triple vision analysis (Claude Code + Gemini + Codex)
-- **`/workflow:design:style-consolidate`**: Token validation and style guide generation
-- **`/workflow:design:ui-generate`**: Token-driven HTML/CSS prototype generation with preview tools
-- **`/workflow:design:design-update`**: Design system integration into brainstorming artifacts
-
-### 👁️ Triple Vision Analysis
-- **Claude Code**: Quick initial visual analysis using native Read tool
-- **Gemini Vision**: Deep semantic understanding of design intent
-- **Codex Vision**: Structured pattern recognition with -i parameter
-- **Consensus Synthesis**: Weighted combination strategy for robust results
-
-### ⏸️ Interactive Checkpoints
-- **Checkpoint 1**: User selects preferred style variants after extraction
-- **Checkpoint 2**: User confirms selected prototypes before design update
-- Pause-and-continue pattern for critical design decisions
-
-### 🌐 Preview Enhancement System (NEW!)
-- **`index.html`**: Master preview navigation with grid layout
-- **`compare.html`**: Side-by-side comparison with responsive viewport toggles
-- **`PREVIEW.md`**: Comprehensive preview instructions and server setup guide
-- Synchronized scrolling for layout comparison
-- Dynamic page switching and real-time responsive testing
-
-### 🎯 Zero Agent Overhead
-- Removed Task(conceptual-planning-agent) wrappers from design commands
-- Direct bash execution for gemini-wrapper and codex commands
-- Improved performance while preserving all functionality
-
-## 🚀 Quick Start
-
-### Complete Design Workflow
-```bash
-# Semi-autonomous workflow with user checkpoints
-/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
-```
-
-### Individual Commands
-```bash
-# Extract design styles (triple vision analysis)
-/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
-
-# Consolidate selected variants
-/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
-
-# Generate prototypes with preview tools
-/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
-
-# Preview generated prototypes
-cd .workflow/WFS-auth/.design/prototypes
-python -m http.server 8080  # Visit http://localhost:8080
-
-# Integrate design system
-/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
-```
-
-## 🎨 Design System Features
-- **OKLCH Color Format**: Perceptually uniform color space
-- **W3C Design Tokens**: Standard-compliant token format
-- **WCAG 2.1 AA Compliance**: Automated accessibility validation
-- **Style Override Support**: Runtime token customization with --style-overrides
-- **Batch Task Generation**: Automatic task creation with --batch-plan
-
-## 📊 Preview Tools
-
-### Master Navigation (index.html)
-- Grid layout of all generated prototypes
-- Quick links to individual variants
-- Metadata display (session ID, timestamps, page info)
-- Direct access to implementation notes
-
-### Side-by-Side Comparison (compare.html)
-- Iframe-based comparison for multiple variants
-- Responsive viewport toggles:
-  - Desktop (100%)
-  - Tablet (768px)
-  - Mobile (375px)
-- Synchronized scrolling option
-- Dynamic page switching dropdown
-- Real-time variant comparison
-
-### Preview Options
-```bash
-# Option 1: Direct browser (simplest)
-cd .workflow/WFS-{session}/.design/prototypes
-open index.html  # or double-click
-
-# Option 2: Local server (recommended)
-python -m http.server 8080      # Python
-npx http-server -p 8080         # Node.js
-php -S localhost:8080           # PHP
-# Visit: http://localhost:8080
-```
-
-## 📦 What's Included
-
-### New Commands (5)
-- `/workflow:design:auto`
-- `/workflow:design:style-extract`
-- `/workflow:design:style-consolidate`
-- `/workflow:design:ui-generate`
-- `/workflow:design:design-update`
-
-### Generated Files
-```
-.workflow/WFS-{session}/.design/
-├── style-extraction/
-│   ├── claude_vision_analysis.json
-│   ├── gemini_vision_analysis.json
-│   ├── codex_vision_analysis.json
-│   ├── semantic_style_analysis.json
-│   ├── design-tokens.json
-│   └── style-cards.json
-├── style-consolidation/
-│   ├── design-tokens.json (validated)
-│   ├── style-guide.md
-│   ├── tailwind.config.js
-│   └── validation-report.json
-└── prototypes/
-    ├── index.html (NEW - preview navigation)
-    ├── compare.html (NEW - side-by-side comparison)
-    ├── PREVIEW.md (NEW - setup instructions)
-    ├── {page}-variant-{n}.html
-    ├── {page}-variant-{n}.css
-    └── design-tokens.css
-```
-
-## 🔄 Workflow Integration
-
-Design phase fits seamlessly between brainstorming and planning:
-
-```
-Brainstorming → UI Design → Planning → Execution
-     ↓              ↓           ↓          ↓
-synthesis-   design-tokens  tasks with  token-driven
-specification   + style     design       implementation
-                 guide      context
-```
-
-**Optional but recommended** for UI-heavy projects:
-- User-facing applications
-- Design system creation
-- Brand-critical interfaces
-- Accessibility compliance projects
-
-## 💡 Benefits
-
-### User Experience
-- 🎨 Visual validation before implementation
-- ⏸️ Interactive control at critical decision points
-- 👁️ Comprehensive analysis from three AI vision sources
-- 🌐 Real-time preview with comparison tools
-- 🎯 Zero waiting with direct bash execution
-
-### Code Quality
-- 🔒 100% CSS values use custom properties
-- ♿ WCAG AA validated at design phase
-- 🎨 Single source of truth for visual design
-- 🧪 Production-ready prototypes (semantic HTML5, responsive, accessible)
-
-### Development Workflow
-- 🔄 Seamless integration with existing workflow
-- 🚀 Backward compatible (design phase optional)
-- 📊 Better planning with design system context
-- 🎯 Focused implementation from validated prototypes
-
-## 📚 Documentation
-
-- **README.md**: Updated with UI Design Workflow section
-- **README_CN.md**: Chinese documentation for design workflow
-- **CHANGELOG.md**: Comprehensive release notes with examples
-- **Command Files**: Detailed implementation guides for all 5 commands
-
-## 🔧 Technical Details
-
-**Triple Vision Analysis Flow**:
-```
-Reference Images
-  ↓
-Claude Code (Read tool) → claude_vision_analysis.json
-Gemini Vision (wrapper) → gemini_vision_analysis.json
-Codex Vision (codex -i) → codex_vision_analysis.json
-  ↓
-Main Claude Synthesis → semantic_style_analysis.json
-  ↓
-Codex Token Generation → design-tokens.json, style-cards.json
-```
-
-**Checkpoint Workflow Pattern**:
-```
-User: /workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard"
-  ↓
-Phase 1: style-extract (automatic)
-  ↓ [CHECKPOINT 1: User selects variants]
-User: /workflow:design:style-consolidate --session WFS-xxx --variants "variant-1"
-  ↓
-Phase 3: ui-generate (automatic)
-  ↓ [CHECKPOINT 2: User confirms prototypes]
-User: /workflow:design:design-update --session WFS-xxx --selected-prototypes "dashboard-variant-1"
-  ↓
-Phase 5: batch-plan (optional, if --batch-plan flag)
-```
-
-## 🆙 Upgrade Instructions
-
-```bash
-# Windows (PowerShell)
-Invoke-Expression (Invoke-WebRequest -Uri "https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1" -UseBasicParsing).Content
-
-# Linux/macOS (Bash/Zsh)
-bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
-```
-
-## 🐛 Bug Fixes & Improvements
-- Optimized agent architecture by removing unnecessary wrappers
-- Improved execution performance with direct bash commands
-- Enhanced documentation consistency across English and Chinese versions
-- Updated phase numbering to accommodate new design phase
-
-## 📝 Full Changelog
-See [CHANGELOG.md](https://github.com/catlog22/Claude-Code-Workflow/blob/main/CHANGELOG.md) for complete details.
-
----
-
-**Questions or Issues?**
-- 📖 [Documentation](https://github.com/catlog22/Claude-Code-Workflow)
-- 🐛 [Report Issues](https://github.com/catlog22/Claude-Code-Workflow/issues)
-- 💬 [Discussions](https://github.com/catlog22/Claude-Code-Workflow/discussions)

CHANGELOG-v4.1.0.md

@@ -1,302 +0,0 @@
-# UI Design Workflow v4.1.0 - 纯矩阵模式 + 路径修正
-
-## 📋 发布日期
-2025-10-09
-
-## 🎯 核心变更
-
-### 1. 矩阵模式成为唯一模式
-- ❌ 移除 standard/creative 模式选择
-- ✅ 3×3 矩阵生成为默认且唯一模式
-- ✅ 直接支持 `--style-variants` 和 `--layout-variants` 参数
-
-### 2. 路径符合workflow架构
-- ✅ 有session: `.workflow/WFS-{session_id}/runs/run-xxx/`
-- ✅ 无session: `.workflow/.scratchpad/{session_id}/runs/run-xxx/`
-- ✅ 模板移至全局: `~/.claude/workflows/_template-compare-matrix.html`
-
----
-
-## 📝 文件修改清单
-
-### 核心命令文件
-
-| 文件 | 主要变更 | 状态 |
-|------|---------|------|
-| **auto.md** | 删除模式选择，简化Phase 3，修正路径 | ✅ 已完成 |
-| **generate.md** | 完全重构为矩阵模式，集成模板 | ✅ 已完成 |
-| **consolidate.md** | 修正standalone路径 | ✅ 已完成 |
-| **extract.md** | 修正standalone路径 | ✅ 已完成 |
-| **update.md** | 仅session模式，无需修改 | ✅ 保持不变 |
-
-### 新增文件
-- ✅ `~/.claude/workflows/_template-compare-matrix.html` - 交互式矩阵可视化模板
-
----
-
-## 🔄 参数变更
-
-### 旧参数（废弃）
-```bash
---variants <count>           # 统一变种数
---creative-variants <count>  # 创意变种数
---matrix-mode                # 模式标志
-```
-
-### 新参数（v4.1.0）
-```bash
---style-variants <count>     # 风格变种数（默认3）
---layout-variants <count>    # 布局变种数（默认3）
-# 矩阵为默认模式，无需标志
-```
-
----
-
-## 🚀 工作流对比
-
-### v4.0.x（旧版）
-```bash
-/workflow:ui-design:auto --variants 3 --creative-variants 4
-
-# 问题:
-# - 参数混淆（variants vs creative-variants）
-# - 模式选择复杂
-# - standalone输出到项目根目录
-```
-
-### v4.1.0（新版）
-```bash
-/workflow:ui-design:auto --style-variants 3 --layout-variants 3
-
-# 优势:
-# - 参数语义清晰
-# - 唯一矩阵模式
-# - 输出到 .workflow/.scratchpad/
-# - 总计: 3×3×N 个原型
-```
-
----
-
-## 📊 路径架构
-
-### Standalone模式（无session）
-```
-.workflow/.scratchpad/
-└── design-session-20251009-101530/
-    └── runs/
-        ├── run-20251009-101530/
-        │   └── .design/
-        │       ├── style-extraction/style-cards.json
-        │       ├── style-consolidation/
-        │       │   ├── style-1/design-tokens.json
-        │       │   ├── style-2/design-tokens.json
-        │       │   └── style-3/design-tokens.json
-        │       └── prototypes/
-        │           ├── compare.html (交互式3×3矩阵)
-        │           ├── index.html
-        │           └── {page}-style-{s}-layout-{l}.html
-        └── latest -> run-20251009-101530/
-```
-
-### 集成模式（有session）
-```
-.workflow/WFS-auth-system/
-├── workflow-session.json
-├── IMPL_PLAN.md
-├── .brainstorming/synthesis-specification.md
-└── runs/
-    ├── run-20251009-101530/
-    │   └── .design/ (同上)
-    └── latest -> run-20251009-101530/
-```
-
----
-
-## 🔧 核心改进
-
-### 1. 简化架构
-- **auto.md Phase 3**: 从复杂并行Task循环简化为单一命令
-```bash
-# 旧方式（30+行）
-FOR style_id IN range(...):
-    Task(conceptual-planning-agent): "..."
-
-# 新方式（3行）
-command = "/workflow:ui-design:generate --style-variants {s} --layout-variants {l}"
-SlashCommand(command=command)
-```
-
-### 2. 路径规范化
-```bash
-# auto.md - Phase 0b
-IF --session:
-    base_path = ".workflow/WFS-{session_id}/runs/${run_id}"
-ELSE:
-    base_path = ".workflow/.scratchpad/${session_id}/runs/${run_id}"
-
-# generate/consolidate/extract
-base_path = find_latest_design_session(".workflow/.scratchpad/")
-```
-
-### 3. 可视化增强
-- 集成高级 `_template-compare-matrix.html` 模板
-- 3×3 网格矩阵视图
-- 同步滚动 + 缩放控制
-- 全屏模式 + 选择导出
-
----
-
-## ⚠️ 破坏性变更
-
-### 1. 参数废弃
-```bash
-# ❌ 不再支持
---variants <count>
---creative-variants <count>
-
-# ✅ 必须使用
---style-variants <count>
---layout-variants <count>
-```
-
-### 2. 文件命名强制统一
-```bash
-# ❌ 旧格式不再生成
-{page}-variant-{n}.html
-{page}-creative-variant-{n}.html
-
-# ✅ 强制新格式
-{page}-style-{s}-layout-{l}.html
-```
-
-### 3. Standalone路径变更
-```bash
-# ❌ v4.0.x
-./design-session-xxx/ (项目根目录)
-
-# ✅ v4.1.0
-.workflow/.scratchpad/design-session-xxx/
-```
-
----
-
-## 📖 迁移指南
-
-### 从 v4.0.x 迁移
-
-#### 1. 更新命令参数
-```bash
-# 旧方式
-/workflow:ui-design:auto --variants 3 --creative-variants 4
-
-# 新方式
-/workflow:ui-design:auto --style-variants 3 --layout-variants 4
-
-# 或依赖智能解析
-/workflow:ui-design:auto --prompt "Generate 3 styles with 4 layouts"
-```
-
-#### 2. 更新路径引用
-```bash
-# 旧standalone输出
-./design-session-xxx/
-
-# 新standalone输出
-.workflow/.scratchpad/design-session-xxx/
-
-# 迁移建议: 手动移动旧目录或保留为历史
-mv ./design-session-* .workflow/.scratchpad/
-```
-
-#### 3. 预览文件
-```bash
-# 保持不变
-{base_path}/.design/prototypes/compare.html
-{base_path}/.design/prototypes/index.html
-```
-
----
-
-## ✅ 向后兼容性
-
-### 完全兼容
-- ✅ `--session` 参数
-- ✅ `--pages` 参数
-- ✅ `--prompt` 参数
-- ✅ `--images` 参数
-- ✅ `--batch-plan` 标志
-- ✅ 智能prompt解析
-
-### 不兼容
-- ❌ standard/creative 模式选择
-- ❌ 旧参数 `--variants`, `--creative-variants`
-- ❌ 旧文件命名格式
-
----
-
-## 🧪 测试清单
-
-### 功能测试
-- [ ] 默认3×3矩阵生成
-- [ ] 自定义矩阵（2×2, 4×3等）
-- [ ] 智能prompt解析
-- [ ] 文件命名正确性
-- [ ] compare.html 可视化
-
-### 路径测试
-- [ ] Standalone输出到 `.scratchpad`
-- [ ] Session输出到 `WFS-{id}`
-- [ ] latest symlink正确
-- [ ] 跨命令路径传递
-
-### 集成测试
-- [ ] auto → extract → consolidate → generate → update
-- [ ] 模板正确加载
-- [ ] 设计token引用正确
-
----
-
-## 📚 相关文档
-
-- **workflow-architecture.md**: Workflow系统架构标准
-- **_run-manager.md**: Run-based文件管理文档（如果需要）
-- **~/.claude/workflows/_template-compare-matrix.html**: 可视化模板
-
----
-
-## 🔮 未来增强
-
-### 计划中
-- [ ] 自定义布局策略（覆盖默认 Classic/Modern/Minimal）
-- [ ] compare.html 运行历史对比
-- [ ] Scratchpad自动清理策略
-- [ ] Session升级工作流（scratchpad → WFS）
-
-### 待讨论
-- [ ] 非矩形矩阵支持（2×3）
-- [ ] 恢复 creative 模式（可选）
-- [ ] 更多布局变种（>5）
-
----
-
-## 📝 总结
-
-**v4.1.0 核心价值**:
-1. **极简哲学**: 移除模式选择，矩阵为唯一模式
-2. **清晰参数**: `--style-variants` 和 `--layout-variants` 语义明确
-3. **架构规范**: 严格遵循 workflow-architecture.md 标准
-4. **集中管理**: 所有输出在 `.workflow/` 下
-5. **可视化增强**: 高级交互式矩阵界面
-
-**升级理由**:
-- ✅ 系统化设计探索（风格×布局矩阵）
-- ✅ 简化工作流、减少参数困惑
-- ✅ 符合workflow架构标准
-- ✅ 避免项目根目录污染
-
----
-
-**发布者**: Claude Code
-**版本**: v4.1.0
-**类型**: Major Refactoring + Path Corrections
-**日期**: 2025-10-09

CHANGELOG-v4.1.1.md

@@ -1,219 +0,0 @@
-# UI Design Workflow v4.1.1 - Symlink Fix & Agent Optimization
-
-## 📋 发布日期
-2025-10-09
-
-## 🎯 核心修复与优化
-
-### 1. Windows 符号链接修复
-- **问题**：`latest` 被创建为实际目录而非符号链接，导致创建两套重复目录
-- **根本原因**：使用 `ln -s`（Unix 命令）在 Windows 环境下失败
-- **解决方案**：改用 Windows 原生命令 `mklink /D`
-- **影响范围**：auto.md Phase 0b
-
-### 2. Agent 任务分配优化
-- **旧策略**：按 style 分配（Agent-1 处理 style-1 的所有 layouts）
-- **新策略**：按 layout 分配（Agent-1 处理 layout-1 的所有 styles）
-- **批处理**：支持最多 8 个 styles per agent（超过 8 个 styles 时自动分批）
-- **优势**：
-  - 同一 agent 处理不同 styles（复用 layout 策略）
-  - 不同 agent 处理不同 layouts（并行优化）
-  - 扩展性提升：32 styles × 3 layouts = 12 agents（原方案需 32 agents）
-
----
-
-## 📝 文件修改清单
-
-| 文件 | 主要变更 | 状态 |
-|------|---------|------|
-| **auto.md** | 修复 Windows 符号链接创建逻辑 | ✅ 已完成 |
-| **generate.md** | 重构 agent 分配策略为 layout-based | ✅ 已完成 |
-
----
-
-## 🔄 技术细节
-
-### 修复 1: Symlink Creation (auto.md)
-
-#### 旧代码（错误）
-```bash
-# Phase 0b
-Bash(rm -f ".workflow/WFS-{session_id}/latest")
-Bash(ln -s "runs/${run_id}" ".workflow/WFS-{session_id}/latest")
-```
-
-**问题**：
-- `ln -s` 在 Windows 下失败时会创建实际目录
-- 导致 `latest/` 和 `runs/run-xxx/` 两套重复目录
-
-#### 新代码（修复）
-```bash
-# Phase 0b - Windows-compatible
-Bash(cd ".workflow/WFS-{session_id}" && rm -rf latest && mklink /D latest "runs/${run_id}")
-```
-
-**改进**：
-- 使用 `mklink /D`（Windows 原生目录符号链接命令）
-- `cd` 到父目录确保相对路径正确
-- `rm -rf` 清理旧的目录/符号链接
-
----
-
-### 优化 2: Agent Allocation (generate.md)
-
-#### 旧策略（Style-Based）
-```bash
-FOR style_id IN range(1, style_variants + 1):
-    Task(agent): "Generate all layouts for style-{style_id}"
-```
-
-**问题**：
-- 16 styles → 16 agents
-- 32 styles → 32 agents（扩展性差）
-
-#### 新策略（Layout-Based with Batching）
-```bash
-# Calculate style batches (max 8 styles per agent)
-batch_size = 8
-all_style_ids = range(1, style_variants + 1)
-style_batches = split_into_chunks(all_style_ids, batch_size)
-
-FOR layout_id IN range(1, layout_variants + 1):
-    FOR style_batch IN style_batches:
-        Task(agent): "
-          Generate layout-{layout_id} for styles {style_batch}
-
-          Context:
-          - LAYOUT_ID: {layout_id}
-          - STYLE_IDS_BATCH: {style_batch}  # e.g., [1-8]
-
-          Strategy:
-          - Apply consistent layout-{layout_id} strategy to ALL styles in batch
-          - Load each style's design-tokens.json separately
-        "
-```
-
-**改进**：
-- 按 layout 分配，每个 agent 专注一种 layout 策略
-- 批处理支持：styles > 8 时自动分批
-- 示例：32 styles × 3 layouts
-  - 旧方案：32 agents
-  - 新方案：3 layouts × 4 batches = **12 agents**
-
----
-
-## 📊 性能对比
-
-### Agent 数量对比表
-
-| 配置 | 旧方案 (Style-Based) | 新方案 (Layout-Based) | 优化比例 |
-|------|---------------------|----------------------|---------|
-| 3×3 (默认) | 3 agents | 3 agents | 1:1 |
-| 8×3 | 8 agents | 3 agents | 2.7:1 |
-| 16×3 | 16 agents | 6 agents (3×2 batches) | 2.7:1 |
-| 32×3 | 32 agents | 12 agents (3×4 batches) | 2.7:1 |
-| 3×5 | 3 agents | 5 agents | 0.6:1 |
-| 16×5 | 16 agents | 10 agents (5×2 batches) | 1.6:1 |
-
-**结论**：layout 数量不变时，styles 增加不会线性增加 agent 数量
-
----
-
-## 🚀 工作流影响
-
-### 无影响的部分
-- ✅ 矩阵模式逻辑（仍然是 styles × layouts）
-- ✅ 文件命名格式（`{page}-style-{s}-layout-{l}.html`）
-- ✅ 设计 token 加载机制
-- ✅ 可视化模板（compare.html）
-- ✅ 所有参数（--style-variants, --layout-variants）
-
-### 改进的部分
-- ✅ **符号链接正确性**：不再创建重复目录
-- ✅ **Agent 扩展性**：高 variant 数场景下性能提升 2-3 倍
-- ✅ **Layout 一致性**：同一 agent 负责一种 layout 策略，确保跨 styles 的 layout 一致性
-
----
-
-## ⚠️ 破坏性变更
-
-**无破坏性变更**
-
-- 所有参数保持不变
-- 输出文件格式保持不变
-- API 接口保持不变
-- 向后兼容 v4.1.0
-
----
-
-## 🧪 测试建议
-
-### 符号链接测试
-```bash
-# Windows 环境测试
-/workflow:ui-design:auto --prompt "Test symlink" --style-variants 2
-
-# 验证
-cd .workflow/.scratchpad/design-session-*/
-ls -la  # 应看到 latest -> runs/run-xxx（符号链接，非目录）
-```
-
-### Agent 分配测试
-```bash
-# 小规模测试（3×3）
-/workflow:ui-design:auto --style-variants 3 --layout-variants 3
-# 预期：3 agents（每个 layout 1 个）
-
-# 中规模测试（16×3）
-/workflow:ui-design:auto --style-variants 16 --layout-variants 3
-# 预期：6 agents（3 layouts × 2 batches）
-
-# 大规模测试（32×3）
-/workflow:ui-design:auto --style-variants 32 --layout-variants 3
-# 预期：12 agents（3 layouts × 4 batches）
-```
-
----
-
-## 📚 相关文档
-
-- **workflow-architecture.md**: Workflow 系统架构标准（符号链接规范）
-- **CHANGELOG-v4.1.0.md**: 纯矩阵模式和路径修正
-- **auto.md**: Phase 0b 符号链接创建逻辑
-- **generate.md**: Phase 2 agent 分配策略
-
----
-
-## 🔮 未来优化方向
-
-### 计划中
-- [ ] 自适应批处理大小（根据 agent 性能动态调整）
-- [ ] Layout 策略配置化（允许自定义 layout 策略）
-- [ ] 跨 runs 的 agent 结果缓存
-
-### 待讨论
-- [ ] 是否需要 style-based 模式作为备选？
-- [ ] 批处理大小是否需要参数化（当前固定 8）？
-
----
-
-## 📝 总结
-
-**v4.1.1 核心价值**:
-1. **跨平台兼容性**: Windows 环境符号链接正常工作
-2. **扩展性提升**: 高 variant 数场景下 agent 数量减少 60%+
-3. **Layout 一致性**: 同一 layout 策略由单一 agent 负责
-4. **零破坏性**: 完全向后兼容 v4.1.0
-
-**升级理由**:
-- ✅ 修复 Windows 环境下的符号链接 bug
-- ✅ 大幅提升高 variant 数场景的性能
-- ✅ 改善 layout 策略的一致性
-- ✅ 为未来扩展奠定基础
-
----
-
-**发布者**: Claude Code
-**版本**: v4.1.1
-**类型**: Bugfix + Performance Optimization
-**日期**: 2025-10-09

CHANGELOG.md

@@ -5,6 +5,769 @@ 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
+
+This release includes a command rename for better clarity and refactors UI design workflow documentation for improved maintainability.
+
+#### Changed
+
+**Command Renaming**:
+- **`/workflow:concept-verify` → `/workflow:concept-clarify`**: Renamed for clearer intent
+  - Better reflects the command's purpose of clarifying underspecified areas
+  - Updated all internal references and documentation
+  - Command functionality remains unchanged
+
+**explore-auto.md** (formerly `auto.md`):
+- **File Reorganization**: Reduced from 540 to 435 lines (19.4% reduction)
+- **Merged Duplicate Content**: Consolidated Overview, Coordinator Role, and Execution Model into single "Overview & Execution Model" section
+- **Simplified Core Rules**: From verbose descriptions to 5 concise rules
+- **Streamlined TodoWrite Pattern**: From detailed steps to concise mode with comments
+- **Preserved Functionality**: All 6-phase execution logic, intelligent parsing, interactive confirmation, and matrix mode intact
+
+**imitate-auto.md** (NEW command):
+- **File Reorganization**: Reduced from 566 to 475 lines (16.1% reduction)
+- **Merged Sections**: Combined Overview, Core Philosophy, Execution Model, and Workflow Position into unified structure
+- **Simplified Phase 0.5**: Screenshot capture logic complete but reduced redundant error handling
+- **Consolidated Performance**: Merged "Key Differences" and "Performance Benefits" into single comparison table
+- **Preserved Functionality**: All 5-phase execution, auto-screenshot mechanism, direct token extraction, and error handling intact
+
+#### Improved
+
+**Documentation Quality**:
+- 📚 Clearer structure with merged duplicate concepts
+- 🎯 Reduced redundancy across command documentation
+- ✨ Consistent formatting and organization patterns
+- 📖 Improved maintainability with better content separation
+- 🔍 All key functionality points preserved and highlighted
+
+**Total Impact**:
+- **explore-auto.md**: 105 lines removed (19.4% reduction)
+- **imitate-auto.md**: 91 lines removed (16.1% reduction)
+- **Combined**: 196 lines of documentation optimized
+- **Zero functionality loss**: All features, workflows, and technical details preserved
+
+## [4.2.0] - 2025-10-09
+
+### 🎯 Multi-Page Support Enhancement
+
+Based on Gemini's analysis of the UI Design Workflow, this version implements four key optimizations to improve the multi-page design experience.
+
+#### Added
+
+- **Cross-Page Consistency Validation**: New `Phase 3.5` in `generate` command automatically validates design consistency (shared components, tokens, accessibility) across multiple pages
+- **Side-by-Side Prototype Comparison**: `compare.html` preview tool now includes "Side-by-Side" tab to compare any two prototypes with intelligent consistency hints
+- **Batch Prototype Selection**: `compare.html` features "By Style" and "By Layout" buttons for quick bulk prototype selection
+
+#### Changed
+
+- **Enhanced Page Inference**: `auto` command's page detection uses multiple regex patterns with interactive user confirmation
+- **Improved Export**: Selection export from `compare.html` is now more structured with detailed metadata
+
+## [4.1.1] - 2025-10-09
+
+### 🔧 Symlink Fix & Agent Optimization
+
+#### Fixed
+
+- **Windows Symbolic Link Creation**: Corrected `auto.md` workflow to use `mklink /D` on Windows, preventing duplicate directories instead of symlinks
+
+#### Changed
+
+- **Agent Allocation Strategy**: `generate.md` now allocates tasks by layout (layout-based) instead of style, improving performance and consistency for high variant counts by having one agent handle one layout strategy across multiple styles
+
+## [4.1.0] - 2025-10-09
+
+### 🔄 Matrix-Only UI Design Workflow
+
+#### Changed
+
+- **Matrix Mode by Default**: UI Design workflow now exclusively uses `style × layout` matrix mode with `--style-variants` and `--layout-variants` as standard parameters
+- **Path Standardization**: Standalone design sessions saved to `.workflow/.scratchpad/` adhering to project architecture
+- **Simplified Orchestration**: `auto.md` command simplified to use single `SlashCommand` for generation phase, removing complex loop logic
+
+#### Removed
+
+- **Deprecated Parameters**: Removed `--variants` and `--creative-variants` in favor of explicit `--style-variants` and `--layout-variants`
+- **Standard/Creative Modes**: Distinction between these modes removed
+
+---
+
 ## [4.0.2] - 2025-10-09
 
 ### 🔄 UI Design Workflow - Complete Refactoring
@@ -1311,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.0.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,16 +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.0.1** - UI Design Workflow V2 with Intelligent Page Inference & Agent Mode. 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.0.1**:
-> - 🧠 **Intelligent Page Inference**: Pages auto-extracted from prompt text - no need to specify `--pages` manually
-> - 🤖 **Agent Creative Mode**: `--use-agent` enables parallel exploration of diverse design directions
-> - 🎯 **Unified Variant Control**: Single `--variants` parameter controls both style cards and UI prototypes
-> - 🔀 **Dual Mode Support**: Standalone (quick prototyping) or Integrated (workflow enhancement)
-> - 💬 **Dual Input Sources**: Images, text prompts, or hybrid (text guides image analysis)
-> - ✨ **Extreme Simplification**: All parameters optional with smart defaults
-> - ⚡ **Parallel Execution**: Agent mode generates variants concurrently for speed
+> **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
 
 ---
 
@@ -147,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**
 
@@ -251,26 +274,66 @@ 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
-# Simplest - pages inferred from prompt (v4.0.2+)
-/workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme"
+# Identify and resolve ambiguities in brainstorming artifacts
+/workflow:concept-clarify
 
-# With session integration
-/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 3
+# 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
 
-# Or run individual design phases
-/workflow:ui-design:extract --images "refs/*.png" --variants 3
+**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
+```
+
+**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"
+```
+
+**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
+```
+
+**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 --variants 2
 
-# Preview generated prototypes (NEW!)
-# Option 1: Open .workflow/WFS-auth/.design/prototypes/index.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
 
-/workflow:ui-design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+# 6. Integrate selected design into project
+/workflow:ui-design:update --session WFS-auth --selected-prototypes "dashboard-s1-l2"
 ```
 
 **Phase 3: Action Planning**
@@ -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,15 +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:auto` | **v4.0.2** UI design workflow with pure Claude execution. All parameters optional, no external tools. |
-| `/workflow:ui-design:extract` | **v4.0.2** Extract design from images/text using Claude-native analysis. Single-pass variant generation. |
-| `/workflow:ui-design:consolidate` | **v4.0.2** Consolidate style variants into validated design tokens using Claude synthesis. |
-| `/workflow:ui-design:generate` | **v4.0.2** Generate token-driven HTML/CSS prototypes with agent-based execution. |
-| `/workflow:ui-design:update` | **v4.0.2** 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. |
@@ -380,47 +463,151 @@ 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.0.2)*
+### **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
 
-**`/workflow:ui-design:auto`** - Complete workflow orchestrator
+**`/workflow:ui-design:explore-auto`** - Matrix exploration mode
 ```bash
-# Simplest - pages auto-inferred from prompt (v4.0.2)
-/workflow:ui-design:auto --prompt "Modern blog with home, article and author pages, dark theme"
+# Comprehensive exploration - multiple style × layout variants
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author" --style-variants 3 --layout-variants 2
 
-# Multiple style variants
-/workflow:ui-design:auto --prompt "SaaS dashboard and settings" --variants 3
+# With images and session integration
+/workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png" --style-variants 2 --layout-variants 3
 
-# Hybrid: images + text prompt
-/workflow:ui-design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart"
-
-# Integrated with session + creative mode
-/workflow:ui-design:auto --session WFS-auth --images "refs/*.png" --variants 2 --creative-variants 3
+# Text-only mode with page inference
+/workflow:ui-design:explore-auto --prompt "E-commerce: home, product, cart" --style-variants 2 --layout-variants 2
 ```
-- **🆕 Pure Claude**: No external tools (gemini-wrapper, codex) required
-- **🆕 Zero Dependencies**: All analysis and generation done natively
-- **All Parameters Optional**: Smart defaults and inference for everything
-- **Page Inference**: Auto-extract pages from `--prompt` text
-- **Dual Mode**: Standalone (quick prototyping) or Integrated (workflow enhancement)
+- **🎯 Matrix Mode**: Generate all style × layout combinations
+- **📊 Comprehensive Exploration**: Compare multiple design directions
+- **🔍 Interactive Comparison**: Side-by-side comparison with viewport controls
+- **✅ Cross-page Validation**: Automatic consistency checks for multi-page designs
+- **⚡ Batch Selection**: Quick selection by style or layout
 
-**`/workflow:ui-design:extract`** - Style analysis with dual input sources
+**`/workflow:ui-design:imitate-auto`** - Fast imitation mode
+```bash
+# Rapid single-design replication
+/workflow:ui-design:imitate-auto --images "refs/design.png" --pages "dashboard,settings"
+
+# With session integration
+/workflow:ui-design:imitate-auto --session WFS-auth --images "refs/ui.png" --pages "home,product"
+
+# Auto-screenshot from URL (requires Playwright)
+/workflow:ui-design:imitate-auto --url "https://example.com" --pages "landing"
+```
+- **⚡ Speed Optimized**: 5-10x faster than explore-auto
+- **📸 Auto-Screenshot**: Automatic URL screenshot capture with Playwright/Chrome
+- **🎯 Direct Extraction**: Skip variant selection, go straight to implementation
+- **🔧 Single Design Focus**: Best for copying existing designs quickly
+
+**`/workflow:ui-design:style-extract`** - Visual style extraction (v4.4.0)
 ```bash
 # Pure text prompt
-/workflow:ui-design: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
@@ -431,18 +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
-# Standard mode (consistent layouts)
-/workflow:ui-design:generate --pages "dashboard,auth" --variants 2
+# Combine layout templates + design tokens
+/workflow:ui-design:generate --style-variants 1 --layout-variants 2
 
-# Creative mode (diverse layout exploration)
-/workflow:ui-design:generate --pages "home,product,cart" --creative-variants 3
+# Multiple styles with multiple layouts
+/workflow:ui-design:generate --style-variants 2 --layout-variants 3
 ```
-- **Page Inference**: Auto-detect from session or default to `["home"]`
-- **Agent-Only**: Task(conceptual-planning-agent) execution
-- **Creative Mode**: Parallel agents for diverse layout strategies
-- **Preview Files**: `index.html`, `compare.html`, `PREVIEW.md`
+- **📦 Pure Assembly**: Combines pre-extracted layout-templates.json + design-tokens.json
+- **❌ No Design Logic**: All layout/style decisions made in previous phases
+- **✅ Token Resolution**: Replaces var() placeholders with actual token values
+- **🎯 Matrix Output**: Generates style × layout × targets prototypes
+- **🔍 Interactive Preview**: `compare.html` with side-by-side comparison
 
 **`/workflow:ui-design:update`** - Integrate design system
 ```bash
@@ -483,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**