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-clarify
 description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
-usage: /workflow:concept-clarify [--session <session-id>]
-argument-hint: "optional: --session <session-id>"
-examples:
-  - /workflow:concept-clarify
-  - /workflow:concept-clarify --session WFS-auth
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 

.claude/commands/workflow/execute.md

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

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

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

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

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

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

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

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

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

.claude/commands/workflow/plan.md

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

.claude/commands/workflow/resume.md

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

.claude/commands/workflow/review.md

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

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

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

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

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

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

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

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

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

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

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

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

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

.claude/commands/workflow/status.md

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -1,15 +1,7 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations (3×3 matrix exploration)
-usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
-examples:
-  - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
-  - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
-  - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
-  - /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --prompt "Compare 3 navigation bar designs" --style-variants 3 --layout-variants 2
-  - /workflow:ui-design:explore-auto --targets "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
-  - /workflow:ui-design:explore-auto --targets "home,dashboard" --target-type "page"
+description: Exploratory UI design workflow with style-centric batch generation
+argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 
@@ -26,11 +18,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 1. User triggers: `/workflow:ui-design:explore-auto [params]`
-2. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
-3. Phase 2 (style-consolidate) → **WAIT for completion** → Auto-continues
-4. Phase 3 (ui-generate) → **WAIT for completion** → Auto-continues with unified target list
-5. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
-6. Phase 5 (batch-plan, optional) → Reports completion
+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).
 
@@ -50,6 +50,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 **Optional Parameters** (all have smart defaults):
 - `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
 - `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
+- `--device-type "desktop|mobile|tablet|responsive|auto"`: Device type for layout optimization (default: `auto` - intelligent detection)
+  - **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+  - **Mobile**: 375×812px - Touch-friendly, compact layouts
+  - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+  - **Responsive**: 1920×1080px base with mobile-first breakpoints
 - `--session <id>`: Workflow session ID (standalone mode if omitted)
 - `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
 - `--prompt "<description>"`: Design style and target description
@@ -84,17 +89,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 ## Execution Modes
 
-**Matrix Mode** (unified):
+**Matrix Mode** (style-centric):
 - Generates `style_variants × layout_variants × targets` prototypes
-- **Phase 1**: `style_variants` style options (extract)
+- **Phase 1**: `style_variants` style options with design_attributes (extract)
 - **Phase 2**: `style_variants` independent design systems (consolidate)
-- **Phase 3**: Layout planning + UI generation (generate)
+- **Phase 3**: Style-centric batch generation (generate)
   - Sub-phase 1: `targets × layout_variants` target-specific layout plans
-  - Sub-phase 2: `layout_variants × targets` HTML/CSS templates
+  - **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
   - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - Performance: Efficient parallel execution with S agents
+  - Quality: HTML structure adapts to design_attributes
   - Pages: Full-page layouts with complete structure
   - Components: Isolated elements with minimal wrapper
-  - Mixed: Combination based on intelligent detection
 
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
@@ -114,6 +120,51 @@ ELSE:
 VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
 ```
 
+### Phase 0a-2: Device Type Inference
+```bash
+# Device type inference
+device_type = "auto"
+
+# Step 1: Explicit parameter (highest priority)
+IF --device-type AND --device-type != "auto":
+    device_type = --device-type
+    device_source = "explicit"
+ELSE:
+    # Step 2: Prompt analysis
+    IF --prompt:
+        device_keywords = {
+            "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
+            "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
+            "tablet": ["tablet", "ipad", "medium screen"],
+            "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
+        }
+        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        IF detected_device:
+            device_type = detected_device
+            device_source = "prompt_inference"
+
+    # Step 3: Target type inference
+    IF device_type == "auto":
+        # Components are typically desktop-first, pages can vary
+        device_type = target_type == "component" ? "desktop" : "responsive"
+        device_source = "target_type_inference"
+
+STORE: device_type, device_source
+```
+
+**Device Type Presets**:
+- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+- **Mobile**: 375×812px - Touch-friendly, compact layouts
+- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+- **Responsive**: 1920×1080px base with mobile-first breakpoints
+
+**Detection Keywords**:
+- Prompt contains "mobile", "phone", "smartphone" → mobile
+- Prompt contains "tablet", "ipad" → tablet
+- Prompt contains "desktop", "web", "laptop" → desktop
+- Prompt contains "responsive", "adaptive" → responsive
+- Otherwise: Inferred from target type (components→desktop, pages→responsive)
+
 ### Phase 0b: Run Initialization & Directory Setup
 ```bash
 run_id = "run-$(date +%Y%m%d-%H%M%S)"
@@ -124,10 +175,13 @@ Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
 Write({base_path}/.run-metadata.json): {
   "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
   "workflow": "ui-design:auto",
+  "architecture": "style-centric-batch-generation",
   "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
                   "targets": "${inferred_target_list}", "target_type": "${target_type}",
-                  "prompt": "${prompt_text}", "images": "${images_pattern}" },
-  "status": "in_progress"
+                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "device_type": "${device_type}", "device_source": "${device_source}" },
+  "status": "in_progress",
+  "performance_mode": "optimized"
 }
 ```
 
@@ -163,13 +217,24 @@ IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
 IF --target-type != "auto": target_type = --target-type
 
 # Interactive confirmation
-DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
-  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-  "{emoji} {LABEL} CONFIRMATION"
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets, device_type, device_source):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION (Style-Centric)"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
   "Type: {target_type} | Source: {target_source}"
   "Targets ({count}): {', '.join(validated_targets)}"
-  "Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
-  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Device: {device_type} | Source: {device_source}"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Performance: {style_variants} agent calls"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Modification Options:"
+  "  • 'continue/yes/ok' - Proceed with current configuration"
+  "  • 'targets: a,b,c' - Replace target list"
+  "  • 'skip: x,y' - Remove specific targets"
+  "  • 'add: z' - Add new targets"
+  "  • 'type: page|component' - Change target type"
+  "  • 'device: desktop|mobile|tablet|responsive' - Change device type"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 user_input = WAIT_FOR_USER_INPUT()
 
@@ -180,9 +245,14 @@ MATCH user_input:
   "skip: ..." → validated_targets = remove_items()
   "add: ..." → validated_targets = add_items()
   "type: ..." → target_type = extract_type()
+  "device: ..." → device_type = extract_device()
   default → proceed with current list
 
 STORE: inferred_target_list, target_type, target_inference_source
+
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# This is the only user interaction point in the workflow
+# After this point, all subsequent phases execute automatically without user intervention
 ```
 
 **Helper Function: detect_target_type()**
@@ -199,14 +269,15 @@ detect_target_type(target_list):
 
 ### Phase 1: Style Extraction
 ```bash
-command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
+command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
           (--images ? "--images \"{images}\" " : "") +
           (--prompt ? "--prompt \"{prompt}\" " : "") +
-          "--variants {style_variants} --mode explore"
+          "--mode explore --variants {style_variants}"
 SlashCommand(command)
 
-# WAIT for extract command to complete, then IMMEDIATELY continue to Phase 2
-# DO NOT STOP - Phase 2 must execute automatically
+# 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
@@ -215,30 +286,54 @@ command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
           "--variants {style_variants}"
 SlashCommand(command)
 
-# WAIT for consolidate command to complete, then IMMEDIATELY continue to Phase 3
-# DO NOT STOP - Phase 3 must execute automatically
-# Output: style_variants independent design systems (design tokens and style guides)
+# Output: {style_variants} independent design systems with tokens.css
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
 ```
 
-### Phase 3: Matrix UI Generation (with Layout Planning)
+### Phase 2.5: Layout Extraction
 ```bash
 targets_string = ",".join(inferred_target_list)
-command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
-          "--targets \"{targets_string}\" --target-type \"{target_type}\" " +
-          "--style-variants {style_variants} --layout-variants {layout_variants}"
+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}\""
 
-total = style_variants × layout_variants × len(inferred_target_list)
-REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l}×{n} = {total} prototypes"
-REPORT: "   → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
+REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
+REPORT: "   → Targets: {targets_string}"
+REPORT: "   → Layout variants: {layout_variants}"
+REPORT: "   → Device: {device_type}"
 
 SlashCommand(command)
 
-# WAIT for generate command to complete, then IMMEDIATELY continue to Phase 4
-# DO NOT STOP - Phase 4 must execute automatically
+# 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}-layout-{l}.json (target-specific layout plans)
-# - {target}-style-{s}-layout-{l}.html (final prototypes)
-# - compare.html (matrix view)
+# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
+# - {target}-style-{s}-layout-{l}.css
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
 ```
 
 ### Phase 4: Design System Integration
@@ -246,9 +341,10 @@ SlashCommand(command)
 command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
 SlashCommand(command)
 
-# WAIT for update command to complete
-# If --batch-plan flag present: IMMEDIATELY continue to Phase 5
-# If no --batch-plan: Workflow complete, display final report
+# 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)
@@ -261,90 +357,133 @@ IF --batch-plan:
 
 ## TodoWrite Pattern
 ```javascript
-// Initialize at workflow start to track multi-phase execution
+// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
 TodoWrite({todos: [
   {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
   {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
-  {"content": "Execute UI generation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
   {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
 ]})
 
-// ⚠️ CRITICAL: After EACH phase completion, you MUST:
-// 1. Update current phase: status → "completed"
-// 2. Update next phase: status → "in_progress"
-// 3. Continue to execute next phase immediately
+// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
+// 1. SlashCommand blocks and returns when phase is complete
+// 2. Update current phase: status → "completed"
+// 3. Update next phase: status → "in_progress"
+// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
 // This ensures continuous workflow tracking and prevents premature stopping
 ```
 
 ## Key Features
-- **Autonomous**: No user intervention required between phases
-- **Intelligent**: Parses natural language, infers targets/types
-- **Reproducible**: Deterministic flow with isolated run directories
-- **Flexible**: Supports pages, components, or mixed targets
+
+- **🚀 Performance**: Style-centric batch generation with S agent calls
+- **🎨 Style-Aware**: HTML structure adapts to design_attributes
+- **✅ Perfect Consistency**: Each style by single agent
+- **📦 Autonomous**: No user intervention required between phases
+- **🧠 Intelligent**: Parses natural language, infers targets/types
+- **🔄 Reproducible**: Deterministic flow with isolated run directories
+- **🎯 Flexible**: Supports pages, components, or mixed targets
 
 ## Examples
 
 ### 1. Page Mode (Prompt Inference)
 ```bash
 /workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
-# Result: 27 prototypes (3×3×3 - inferred defaults)
+# Result: 27 prototypes (3×3×3) - responsive layouts (default)
 ```
 
-### 2. Custom Matrix with Session
+### 2. Mobile-First Design
+```bash
+/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
+# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
+```
+
+### 3. Desktop Application
+```bash
+/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
+# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
+```
+
+### 4. Tablet Interface
+```bash
+/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
+# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
+```
+
+### 5. Custom Matrix with Session
 ```bash
 /workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
-# Result: 2×2×N prototypes (targets from synthesis)
+# Result: 2×2×N prototypes - device type inferred from session
 ```
 
-### 3. Component Mode
+### 6. Component Mode (Desktop)
 ```bash
-/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
-# Result: 12 prototypes (3×2×2 components with minimal wrapper)
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2) - desktop components
 ```
 
-### 4. Intelligent Parsing + Batch Planning
+### 7. Intelligent Parsing + Batch Planning
 ```bash
-/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for dashboard and settings" --batch-plan
-# Result: 16 prototypes (4×2×2) + auto-generated implementation tasks
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
 ```
 
-### 5. Legacy Support
+### 8. Large Scale Responsive
 ```bash
-/workflow:ui-design:explore-auto --pages "home,dashboard,settings"
-# Equivalent to: --targets "home,dashboard,settings" --target-type "page"
+/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
+# Result: 36 prototypes (3×3×4) - responsive layouts
 ```
 
 ## Completion Output
 ```
 ✅ UI Design Explore-Auto Workflow Complete!
 
+Architecture: Style-Centric Batch Generation
 Run ID: {run_id} | Session: {session_id or "standalone"}
-Type: {icon} {target_type} | Matrix: {s}×{l}×{n} = {total} prototypes
+Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
 
-Phase 1: {s} style variants (extract)
-Phase 2: {s} design systems (consolidate)
-Phase 3: Layout planning + generation (generate)
-  - {n}×{l} target-specific layout plans
-  - {l}×{n} HTML/CSS templates
+Phase 1: {s} style variants with design_attributes (style-extract)
+Phase 2: {s} design systems with tokens.css (consolidate)
+Phase 2.5: {n×l} layout templates (layout-extract explore mode)
+  - Device: {device_type} layouts
+  - {n} targets × {l} layout variants = {n×l} structural templates
+Phase 3: UI Assembly (generate)
+  - Pure assembly: layout templates + design tokens
   - {s}×{l}×{n} = {total} final prototypes
 Phase 4: Brainstorming artifacts updated
 [Phase 5: {n} implementation tasks created]  # if --batch-plan
 
+Assembly Process:
+✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
+✅ Layout Extraction: {n×l} reusable structural templates
+✅ Pure Assembly: No design decisions in generate phase
+✅ Device-Optimized: Layouts designed for {device_type}
+
+Design Quality:
+✅ Token-Driven Styling: 100% var() usage
+✅ Structural Variety: {l} distinct layouts per target
+✅ Style Variety: {s} independent design systems
+✅ Device-Optimized: Layouts designed for {device_type}
+
 📂 {base_path}/
-  ├── style-consolidation/  ({s} design systems)
-  ├── prototypes/
-  │   ├── _templates/       ({n}×{l} layout JSON + {l}×{n} HTML/CSS)
-  │   └── ...               ({total} final prototypes)
-  └── .run-metadata.json
+  ├── style-extraction/       ({s} style cards + design-space-analysis.json)
+  ├── style-consolidation/    ({s} design systems with tokens.css)
+  ├── layout-extraction/      ({n×l} layout templates + layout-space-analysis.json)
+  ├── prototypes/             ({total} assembled prototypes)
+  └── .run-metadata.json      (includes device type)
 
 🌐 Preview: {base_path}/prototypes/compare.html
   - Interactive {s}×{l} matrix view
   - Side-by-side comparison
-  - Target-specific layouts per prototype
+  - Target-specific layouts with style-aware structure
+  - Toggle between {n} targets
 
 {icon} Targets: {', '.join(targets)} (type: {target_type})
   - Each target has {l} custom-designed layouts
+  - Each style × target × layout has unique HTML structure (not just CSS!)
   - Layout plans stored as structured JSON
+  - Optimized for {device_type} viewing
 
 Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
 ```
+

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

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

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

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

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

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

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

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

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

@@ -4,7 +4,7 @@
 # Purpose: Generate compare.html and index.html using template substitution
 # Template: ~/.claude/workflows/_template-compare-matrix.html
 #
-# Usage: ui-generate-preview-v2.sh <prototypes_dir> [--template <path>]
+# Usage: ui-generate-preview.sh <prototypes_dir> [--template <path>]
 #
 
 set -e

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

@@ -19,8 +19,8 @@ type: strategic-guideline
 ## ⚡ Core Framework
 
 ### Tool Overview
-- **Gemini**: Analysis, understanding, exploration & documentation
-- **Qwen**: Architecture analysis, code generation & implementation
+- **Gemini**: Analysis, understanding, exploration & documentation (primary)
+- **Qwen**: Analysis, understanding, exploration & documentation (fallback, same capabilities as Gemini)
 - **Codex**: Development, implementation & automation
 
 ### Decision Principles
@@ -32,8 +32,8 @@ type: strategic-guideline
 - **⚠️ Write operation protection** - For local codebase write/modify operations, require EXPLICIT user confirmation unless user provides clear instructions containing MODE=write or MODE=auto
 
 ### Quick Decision Rules
-1. **Exploring/Understanding?** → Start with Gemini
-2. **Architecture/Code generation?** → Start with Qwen
+1. **Exploring/Understanding?** → Start with Gemini (fallback to Qwen if needed)
+2. **Architecture/Analysis?** → Start with Gemini (fallback to Qwen if needed)
 3. **Building/Fixing?** → Start with Codex
 4. **Not sure?** → Use multiple tools in parallel
 5. **Small task?** → Still use tools - they're faster than manual work
@@ -56,15 +56,16 @@ type: strategic-guideline
 
 ### Qwen
 - **Command**: `~/.claude/scripts/qwen-wrapper`
-- **Strengths**: Architecture analysis, pattern recognition
-- **Best For**: System design analysis, architectural review
-- **Permissions**: Architecture analysis only, no automatic code generation
+- **Strengths**: Large context window, pattern recognition (same as Gemini)
+- **Best For**: Analysis, documentation generation, code exploration (fallback option when Gemini unavailable)
+- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
 - **Default MODE**: `analysis` (read-only)
-- **⚠️ Write Trigger**: Explicitly prohibited from auto-calling write mode
+- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
+- **Priority**: Secondary to Gemini - use as fallback for same tasks
 
 #### MODE Options
-- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
-- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
+- `analysis` (default) - Read-only analysis and documentation generation (same as Gemini)
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
 
 ### Codex
 - **Command**: `codex --full-auto exec`
@@ -149,13 +150,13 @@ RULES: [template reference and constraints]
 
 #### Qwen Commands
 ```bash
-# Qwen Architecture Analysis (read-only, default)
+# Qwen Analysis (read-only, default) - Same as Gemini, use as fallback
 cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [clear architecture goal]
+PURPOSE: [clear analysis goal]
 TASK: [specific analysis task]
 MODE: analysis
 CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
+EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 
@@ -166,7 +167,7 @@ PURPOSE: [clear goal]
 TASK: [specific task]
 MODE: write
 CONTEXT: [file references and memory context]
-EXPECTED: [expected deliverables]
+EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 ```
@@ -256,14 +257,13 @@ RULES: Focus on type safety and component composition
 
 | Task Type | Tool | Use Case | Template |
 |-----------|------|----------|-----------|
-| **Analysis** | Gemini | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
-| **Architecture** | Qwen | System design, code generation, architectural analysis | `analysis/architecture.txt` |
-| **Code Generation** | Qwen | Implementation patterns, code scaffolding, component creation | `development/feature.txt` |
+| **Analysis** | Gemini (Qwen fallback) | Code exploration, architecture review, patterns | `analysis/pattern.txt` |
+| **Architecture** | Gemini (Qwen fallback) | System design, architectural analysis | `analysis/architecture.txt` |
+| **Documentation** | Gemini (Qwen fallback) | Code docs, API specs, guides | `analysis/quality.txt` |
 | **Development** | Codex | Feature implementation, bug fixes, testing | `development/feature.txt` |
-| **Planning** | Multiple | Task breakdown, migration planning | `planning/task-breakdown.txt` |
-| **Documentation** | Multiple | Code docs, API specs, guides | `analysis/quality.txt` |
+| **Planning** | Gemini/Qwen | Task breakdown, migration planning | `planning/task-breakdown.txt` |
 | **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
-| **Refactoring** | Multiple | Gemini for analysis, Qwen/Codex for execution | `development/refactor.txt` |
+| **Refactoring** | Multiple | Gemini/Qwen for analysis, Codex for execution | `development/refactor.txt` |
 
 ### Template System
 
@@ -302,9 +302,9 @@ tech-stacks/
 ### Workflow Integration (REQUIRED)
 When planning any coding task, **ALWAYS** integrate CLI tools:
 
-1. **Understanding Phase**: Use Gemini for analysis
-2. **Architecture Phase**: Use Qwen for design and code generation
-3. **Implementation Phase**: Use Qwen/Codex for development
+1. **Understanding Phase**: Use Gemini for analysis (Qwen as fallback)
+2. **Architecture Phase**: Use Gemini for design and analysis (Qwen as fallback)
+3. **Implementation Phase**: Use Codex for development
 4. **Quality Phase**: Use Codex for testing and validation
 
 ### Common Scenarios
@@ -333,8 +333,19 @@ RULES: Follow project documentation standards
 "
 ```
 
-#### Architecture Analysis
+#### Architecture Analysis (Qwen as Gemini fallback)
 ```bash
+# Prefer Gemini for architecture analysis
+cd src/auth && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze authentication system architecture
+TASK: Review JWT-based auth system design
+MODE: analysis
+CONTEXT: @{src/auth/**/*} Existing patterns and requirements
+EXPECTED: Architecture analysis report with recommendations
+RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on security
+"
+
+# Use Qwen only if Gemini unavailable
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze authentication system architecture
 TASK: Review JWT-based auth system design
@@ -419,7 +430,7 @@ EXPECTED: Pattern documentation
 RULES: Focus on security best practices
 "
 
-# Qwen - Architecture analysis
+# Qwen - Analysis (fallback option, same as Gemini)
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze auth architecture
 TASK: Review auth system design and patterns

.claude/workflows/task-core.md

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

.claude/workflows/tool-control.yaml

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

.claude/workflows/workflow-architecture.md

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

CHANGELOG.md

@@ -5,6 +5,542 @@ 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
@@ -1538,12 +2074,6 @@ This is a **breaking change release** with significant architectural improvement
 - **Intelligent Modes**: Auto template selection and precise planning
 - **Full Command Suite**: analyze, chat, execute, mode:auto, mode:bug-index, mode:plan
 
-#### 🏷️ Issue Management Commands
-- `/workflow:issue:create` - Create new project issues with priority/type
-- `/workflow:issue:list` - List and filter issues by status/assignment
-- `/workflow:issue:update` - Update existing issue status and assignments
-- `/workflow:issue:close` - Close completed issues with resolution
-
 #### 📋 Enhanced Workflow Commands
 - `/workflow:plan-verify` - Pre-execution validation using dual analysis
 - `/workflow:test-gen` - Generate comprehensive test workflows

CLAUDE.md

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

Install-Claude.ps1

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

Install-Claude.sh

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

README.md

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

README_CN.md

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

WORKFLOW_DIAGRAMS.md

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

ui-instantiate-analysis.md

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

ui-workflow-parameter-clarity-report.md

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