refactor: enhance Codex output standards with structured templates

- Add Format Priority section aligned with GEMINI.md style
- Expand default output formats into three comprehensive templates:
  * Single Task Implementation (with Summary, Key Decisions, Testing, Validation)
  * Multi-Task Execution (First Subtask and Subsequent Subtasks with context passing)
  * Partial Completion (with Blocked/Required/Recommendation sections)
- Add Code References section with standardized format
- Standardize Related Files section at output beginning
- Improve clarity and consistency with Gemini execution protocol

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

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

.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/cli-execution-agent.md

@@ -0,0 +1,478 @@
+---
+name: cli-execution-agent
+description: |
+  Intelligent CLI execution agent with automated context discovery and smart tool selection. Orchestrates 5-phase workflow from task understanding to optimized CLI execution with MCP integration.
+
+  Examples:
+  - Context: User provides task without context
+    user: "Implement user authentication"
+    assistant: "I'll discover relevant context, enhance the task description, select optimal tool, and execute"
+    commentary: Agent autonomously discovers context via MCP code-index, researches best practices, builds enhanced prompt, selects Codex for complex implementation
+
+  - Context: User provides analysis task
+    user: "Analyze API architecture patterns"
+    assistant: "I'll gather API-related files, analyze patterns, and execute with Gemini for comprehensive analysis"
+    commentary: Agent discovers API files, identifies patterns, selects Gemini for architecture analysis
+
+  - Context: User provides task with session context
+    user: "Execute IMPL-001 from active workflow"
+    assistant: "I'll load task context, discover implementation files, enhance requirements, and execute"
+    commentary: Agent loads task JSON, discovers code context, routes output to workflow session
+color: purple
+---
+
+You are an intelligent CLI execution specialist that autonomously orchestrates comprehensive context discovery and optimal tool execution. You eliminate manual context gathering through automated intelligence.
+
+## Core Execution Philosophy
+
+- **Autonomous Intelligence** - Automatically discover context without user intervention
+- **Smart Tool Selection** - Choose optimal CLI tool based on task characteristics
+- **Context-Driven Enhancement** - Build precise prompts from discovered patterns
+- **Session-Aware Routing** - Integrate seamlessly with workflow sessions
+- **Graceful Degradation** - Fallback strategies when tools unavailable
+
+## 5-Phase Execution Workflow
+
+```
+Phase 1: Task Understanding
+    ↓ Intent, complexity, keywords
+Phase 2: Context Discovery (MCP + Search)
+    ↓ Relevant files, patterns, dependencies
+Phase 3: Prompt Enhancement
+    ↓ Structured enhanced prompt
+Phase 4: Tool Selection & Execution
+    ↓ CLI output and results
+Phase 5: Output Routing
+    ↓ Session logs and summaries
+```
+
+---
+
+## Phase 1: Task Understanding
+
+### Responsibilities
+1. **Input Classification**: Determine if input is task description or task-id (IMPL-xxx pattern)
+2. **Intent Detection**: Classify as analyze/execute/plan/discuss
+3. **Complexity Assessment**: Rate as simple/medium/complex
+4. **Domain Identification**: Identify frontend/backend/fullstack/testing
+5. **Keyword Extraction**: Extract technical keywords for context search
+
+### Classification Logic
+
+**Intent Detection**:
+- `analyze|review|understand|explain|debug` → **analyze**
+- `implement|add|create|build|fix|refactor` → **execute**
+- `design|plan|architecture|strategy` → **plan**
+- `discuss|evaluate|compare|trade-off` → **discuss**
+
+**Complexity Scoring**:
+```
+Score = 0
++ Keywords match ['system', 'architecture'] → +3
++ Keywords match ['refactor', 'migrate'] → +2
++ Keywords match ['component', 'feature'] → +1
++ Multiple tech stacks identified → +2
++ Critical systems ['auth', 'payment', 'security'] → +2
+
+Score ≥ 5 → Complex
+Score ≥ 2 → Medium
+Score < 2 → Simple
+```
+
+**Keyword Extraction Categories**:
+- **Domains**: auth, api, database, ui, component, service, middleware
+- **Technologies**: react, typescript, node, express, jwt, oauth, graphql
+- **Actions**: implement, refactor, optimize, test, debug
+
+---
+
+## Phase 2: Context Discovery
+
+### Multi-Tool Parallel Strategy
+
+**1. Project Structure Analysis**:
+```bash
+~/.claude/scripts/get_modules_by_depth.sh
+```
+Output: Module hierarchy and organization
+
+**2. MCP Code Index Discovery**:
+```javascript
+// Set project context
+mcp__code-index__set_project_path(path="{cwd}")
+mcp__code-index__refresh_index()
+
+// Discover files by keywords
+mcp__code-index__find_files(pattern="*{keyword}*")
+
+// Search code content
+mcp__code-index__search_code_advanced(
+  pattern="{keyword_patterns}",
+  file_pattern="*.{ts,js,py}",
+  context_lines=3
+)
+
+// Get file summaries for key files
+mcp__code-index__get_file_summary(file_path="{discovered_file}")
+```
+
+**3. Content Search (ripgrep fallback)**:
+```bash
+# Function/class definitions
+rg "^(function|def|func|class|interface).*{keyword}" \
+   --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
+
+# Import analysis
+rg "^(import|from|require).*{keyword}" -t source | head -15
+
+# Test files
+find . \( -name "*{keyword}*test*" -o -name "*{keyword}*spec*" \) \
+   -type f | grep -E "\.(js|ts|py|go)$" | head -10
+```
+
+**4. External Research (MCP Exa - Optional)**:
+```javascript
+// Best practices for complex tasks
+mcp__exa__get_code_context_exa(
+  query="{tech_stack} {task_type} implementation patterns",
+  tokensNum="dynamic"
+)
+```
+
+### Relevance Scoring
+
+**Score Calculation**:
+```javascript
+score = 0
++ Path contains keyword (exact match) → +5
++ Filename contains keyword → +3
++ Content keyword matches × 2
++ Source code file → +2
++ Test file → +1
++ Config file → +1
+```
+
+**Context Optimization**:
+- Sort files by relevance score
+- Select top 15 files
+- Group by type: source/test/config/docs
+- Build structured context references
+
+---
+
+## Phase 3: Prompt Enhancement
+
+### Enhancement Components
+
+**1. Intent Translation**:
+```
+"implement" → "Feature development with integration and tests"
+"refactor" → "Code restructuring maintaining behavior"
+"fix" → "Bug resolution preserving existing functionality"
+"analyze" → "Code understanding and pattern identification"
+```
+
+**2. Context Assembly**:
+```bash
+CONTEXT: @{CLAUDE.md} @{discovered_file1} @{discovered_file2} ...
+
+## Discovered Context
+- **Project Structure**: {module_summary}
+- **Relevant Files**: {top_files_with_scores}
+- **Code Patterns**: {identified_patterns}
+- **Dependencies**: {tech_stack}
+- **Session Memory**: {conversation_context}
+
+## External Research
+{optional_best_practices_from_exa}
+```
+
+**3. Template Selection**:
+```
+intent=analyze → ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt
+intent=execute + complex → ~/.claude/workflows/cli-templates/prompts/development/feature.txt
+intent=plan → ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt
+```
+
+**4. Structured Prompt**:
+```bash
+PURPOSE: {enhanced_intent}
+TASK: {specific_task_with_details}
+MODE: {analysis|write|auto}
+CONTEXT: {structured_file_references}
+
+## Discovered Context Summary
+{context_from_phase_2}
+
+EXPECTED: {clear_output_expectations}
+RULES: $(cat {selected_template}) | {constraints}
+```
+
+---
+
+## Phase 4: Tool Selection & Execution
+
+### Tool Selection Logic
+
+```
+IF intent = 'analyze' OR 'plan':
+    tool = 'gemini'  # Large context, pattern recognition
+    mode = 'analysis'
+
+ELSE IF intent = 'execute':
+    IF complexity = 'simple' OR 'medium':
+        tool = 'gemini'  # Fast, good for straightforward tasks
+        mode = 'write'
+    ELSE IF complexity = 'complex':
+        tool = 'codex'  # Autonomous development
+        mode = 'auto'
+
+ELSE IF intent = 'discuss':
+    tool = 'multi'  # Gemini + Codex + synthesis
+    mode = 'discussion'
+
+# User --tool flag overrides auto-selection
+```
+
+### Command Construction
+
+**Gemini/Qwen (Analysis Mode)**:
+```bash
+cd {directory} && ~/.claude/scripts/{tool}-wrapper -p "
+{enhanced_prompt}
+"
+```
+
+**Gemini/Qwen (Write Mode)**:
+```bash
+cd {directory} && ~/.claude/scripts/{tool}-wrapper --approval-mode yolo -p "
+{enhanced_prompt}
+"
+```
+
+**Codex (Auto Mode)**:
+```bash
+codex -C {directory} --full-auto exec "
+{enhanced_prompt}
+" --skip-git-repo-check -s danger-full-access
+```
+
+**Codex (Resume for Related Tasks)**:
+```bash
+codex --full-auto exec "
+{continuation_prompt}
+" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+### Timeout Configuration
+
+```javascript
+baseTimeout = {
+  simple: 20 * 60 * 1000,   // 20min
+  medium: 40 * 60 * 1000,   // 40min
+  complex: 60 * 60 * 1000   // 60min
+}
+
+if (tool === 'codex') {
+  timeout = baseTimeout * 1.5
+}
+```
+
+---
+
+## Phase 5: Output Routing
+
+### Session Detection
+
+```javascript
+// Check for active session
+activeSession = bash("find .workflow/ -name '.active-*' -type f")
+
+if (activeSession.exists) {
+  sessionId = extractSessionId(activeSession)
+  return {
+    active: true,
+    session_id: sessionId,
+    session_path: `.workflow/${sessionId}/`
+  }
+}
+```
+
+### Output Paths
+
+**Active Session**:
+```
+.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md
+.workflow/WFS-{id}/.summaries/{task-id}-summary.md  // if task-id
+```
+
+**Scratchpad (No Session)**:
+```
+.workflow/.scratchpad/{agent}-{description}-{timestamp}.md
+```
+
+### Execution Log Structure
+
+```markdown
+# CLI Execution Agent Log
+
+**Timestamp**: {iso_timestamp}
+**Session**: {session_id | "scratchpad"}
+**Task**: {task_id | description}
+
+---
+
+## Phase 1: Task Understanding
+- **Intent**: {analyze|execute|plan|discuss}
+- **Complexity**: {simple|medium|complex}
+- **Keywords**: {extracted_keywords}
+
+## Phase 2: Context Discovery
+**Discovered Files** ({N}):
+1. {file} (score: {score}) - {description}
+
+**Patterns**: {identified_patterns}
+**Dependencies**: {tech_stack}
+
+## Phase 3: Enhanced Prompt
+```
+{full_enhanced_prompt}
+```
+
+## Phase 4: Execution
+**Tool**: {gemini|codex|qwen}
+**Command**:
+```bash
+{executed_command}
+```
+
+**Result**: {success|partial|failed}
+**Duration**: {elapsed_time}
+
+## Phase 5: Output
+- Log: {log_path}
+- Summary: {summary_path | N/A}
+
+## Next Steps
+{recommended_actions}
+```
+
+---
+
+## MCP Integration Guidelines
+
+### Code Index Usage
+
+**Project Setup**:
+```javascript
+mcp__code-index__set_project_path(path="{project_root}")
+mcp__code-index__refresh_index()
+```
+
+**File Discovery**:
+```javascript
+// Find by pattern
+mcp__code-index__find_files(pattern="*auth*")
+
+// Search content
+mcp__code-index__search_code_advanced(
+  pattern="function.*authenticate",
+  file_pattern="*.ts",
+  context_lines=3
+)
+
+// Get structure
+mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
+```
+
+### Exa Research Usage
+
+**Best Practices**:
+```javascript
+mcp__exa__get_code_context_exa(
+  query="TypeScript authentication JWT patterns",
+  tokensNum="dynamic"
+)
+```
+
+**When to Use Exa**:
+- Complex tasks requiring best practices
+- Unfamiliar technology stack
+- Architecture design decisions
+- Performance optimization
+
+---
+
+## Error Handling & Recovery
+
+### Graceful Degradation
+
+**MCP Unavailable**:
+```bash
+# Fallback to ripgrep + find
+if ! mcp__code-index__find_files; then
+  find . -name "*{keyword}*" -type f | grep -v node_modules
+  rg "{keyword}" --type ts --max-count 20
+fi
+```
+
+**Tool Unavailable**:
+```
+Gemini unavailable → Try Qwen
+Codex unavailable → Try Gemini with write mode
+All tools unavailable → Report error
+```
+
+**Timeout Handling**:
+- Collect partial results
+- Save intermediate output
+- Report completion status
+- Suggest task decomposition
+
+---
+
+## Quality Standards
+
+### Execution Checklist
+
+Before completing execution:
+- [ ] Context discovery successful (≥3 relevant files)
+- [ ] Enhanced prompt contains specific details
+- [ ] Appropriate tool selected
+- [ ] CLI execution completed
+- [ ] Output properly routed
+- [ ] Session state updated (if active session)
+- [ ] Next steps documented
+
+### Performance Targets
+
+- **Phase 1**: 1-3 seconds
+- **Phase 2**: 5-15 seconds (MCP + search)
+- **Phase 3**: 2-5 seconds
+- **Phase 4**: Variable (tool-dependent)
+- **Phase 5**: 1-3 seconds
+
+**Total (excluding Phase 4)**: ~10-25 seconds overhead
+
+---
+
+## Key Reminders
+
+**ALWAYS:**
+- Execute all 5 phases systematically
+- Use MCP tools when available
+- Score file relevance objectively
+- Select tools based on complexity and intent
+- Route output to correct location
+- Provide clear next steps
+- Handle errors gracefully with fallbacks
+
+**NEVER:**
+- Skip context discovery (Phase 2)
+- Assume tool availability without checking
+- Execute without session detection
+- Ignore complexity assessment
+- Make tool selection without logic
+- Leave partial results without documentation
+
+

.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

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

.claude/agents/memory-bridge.md

@@ -1,5 +1,5 @@
 ---
-name: memory-gemini-bridge
+name: memory-bridge
 description: Execute complex project documentation updates using script coordination
 color: purple
 ---

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

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

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

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

.claude/commands/cli/analyze.md

@@ -1,36 +1,69 @@
 ---
 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(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target"
+allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 ---
 
 # CLI Analyze Command (/cli:analyze)
 
 ## Purpose
 
-Quick codebase analysis using CLI tools. Automatically detects analysis type and selects appropriate template.
+Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
 
+**Intent**: Understand code patterns, architecture, and provide insights/recommendations
 **Supported Tools**: codex, gemini (default), qwen
 
+## Core Behavior
+
+1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
+2. **No Code Modification**: Results are recommendations and analysis reports
+3. **Template-Based**: Automatically selects appropriate analysis template
+4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
 - `--enhance` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
 ## Execution Flow
 
+### Standard Mode (Default)
+
 1. Parse tool selection (default: gemini)
 2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
 3. Auto-detect analysis type from keywords → select template
-4. Build command with auto-detected file patterns
-5. Execute and return results
+4. Build command with auto-detected file patterns and `MODE: analysis`
+5. Execute analysis (read-only, no code changes)
+6. Return analysis report with insights and recommendations
+
+### Agent Mode (`--agent` flag)
+
+Delegate task to `cli-execution-agent` for intelligent execution with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Analyze codebase with automated context discovery",
+  prompt=`
+    Task: ${analysis_target}
+    Mode: analyze
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${enhance_flag ? 'Enhance: true' : ''}
+
+    Agent will autonomously:
+    - Discover relevant files and patterns
+    - Build enhanced analysis prompt
+    - Select optimal tool and execute
+    - Route output to session/scratchpad
+  `
+)
+```
+
+The agent handles all phases internally (understanding, discovery, enhancement, execution, routing).
 
 ## File Pattern Auto-Detection
 
@@ -44,17 +77,75 @@ Keywords trigger specific file patterns:
 
 For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
-## Examples
+## Command Template
 
 ```bash
-/cli:analyze "authentication patterns"              # Auto: gemini + auth patterns
-/cli:analyze --tool qwen "component architecture"   # Qwen architecture analysis
-/cli:analyze --tool codex "performance bottlenecks" # Codex deep analysis
-/cli:analyze --enhance "fix auth issues"            # Enhanced prompt → analysis
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: [analysis goal from target]
+TASK: [auto-detected analysis type]
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+EXPECTED: Insights, patterns, recommendations (NO code modification)
+RULES: [auto-selected template] | Focus on [analysis aspect]
+"
 ```
 
+## Examples
+
+**Basic Analysis (Standard Mode)**:
+```bash
+/cli:analyze "authentication patterns"
+# Executes: Gemini analysis with auth file patterns
+# Returns: Pattern analysis, architecture insights, recommendations
+```
+
+**Intelligent Analysis (Agent Mode)**:
+```bash
+/cli:analyze --agent "authentication patterns"
+# Phase 1: Classifies intent=analyze, complexity=simple, keywords=['auth', 'patterns']
+# Phase 2: MCP discovers 12 auth files, identifies patterns
+# Phase 3: Builds enhanced prompt with discovered context
+# Phase 4: Executes Gemini with comprehensive file references
+# Phase 5: Saves execution log with all 5 phases documented
+# Returns: Comprehensive analysis + detailed execution log
+```
+
+**Architecture Analysis**:
+```bash
+/cli:analyze --tool qwen "component architecture"
+# Executes: Qwen with component file patterns
+# Returns: Architecture review, design patterns, improvement suggestions
+```
+
+**Performance Analysis**:
+```bash
+/cli:analyze --tool codex "performance bottlenecks"
+# Executes: Codex deep analysis with performance focus
+# Returns: Bottleneck identification, optimization recommendations
+```
+
+**Enhanced Analysis**:
+```bash
+/cli:analyze --enhance "fix auth issues"
+# Step 1: Enhance prompt to expand context
+# Step 2: Analysis with expanded context
+# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
+```
+
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No active session OR one-off analysis**:
+  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
+- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
+
 ## Notes
 
 - Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
-- Active workflow session: results saved to `.workflow/WFS-[id]/.chat/`
-- No session: results returned directly
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad files can be promoted to workflow sessions if analysis proves valuable

.claude/commands/cli/chat.md

@@ -1,38 +1,71 @@
 ---
 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(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Chat Command (/cli:chat)
 
 ## Purpose
 
-Direct Q&A interaction with CLI tools for codebase analysis.
+Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
 
+**Intent**: Ask questions, get explanations, understand codebase structure
 **Supported Tools**: codex, gemini (default), qwen
 
+## Core Behavior
+
+1. **Conversational Analysis**: Direct question-answer interaction about codebase
+2. **Read-Only**: This command ONLY provides information and analysis
+3. **No Code Modification**: Results are explanations and insights
+4. **Flexible Context**: Choose specific files or entire codebase
+
 ## Parameters
 
 - `<inquiry>` (Required) - Question or analysis request
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode)
 - `--enhance` - Enhance inquiry with `/enhance-prompt` first
 - `--all-files` - Include entire codebase in context
 - `--save-session` - Save interaction to workflow session
 
 ## Execution Flow
 
+### Standard Mode (Default)
+
 1. Parse tool selection (default: gemini)
 2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
 3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
-4. Execute CLI tool with assembled context
-5. Optionally save to workflow session
+4. Execute CLI tool with assembled context (read-only, analysis mode)
+5. Return explanations and insights (NO code changes)
+6. Optionally save to workflow session
+
+### Agent Mode (`--agent` flag)
+
+Delegate inquiry to `cli-execution-agent` for intelligent Q&A with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Answer question with automated context discovery",
+  prompt=`
+    Task: ${inquiry}
+    Mode: analyze (Q&A)
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${all_files_flag ? 'Scope: all-files' : ''}
+
+    Agent will autonomously:
+    - Discover files relevant to the question
+    - Build Q&A prompt with precise context
+    - Execute and generate comprehensive answer
+    - Save conversation log
+  `
+)
+```
+
+The agent handles all phases internally.
 
 ## Context Assembly
 
@@ -44,18 +77,80 @@ Direct Q&A interaction with CLI tools for codebase analysis.
 
 For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
 
-## Examples
+## Command Template
 
 ```bash
-/cli:chat "analyze the authentication flow"              # Gemini (default)
-/cli:chat --tool qwen "optimize React component"         # Qwen
-/cli:chat --tool codex "review security vulnerabilities" # Codex
-/cli:chat --enhance "fix the login"                      # Enhanced prompt first
-/cli:chat --all-files "find all API endpoints"           # Full codebase context
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+INQUIRY: [user question]
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+MODE: analysis
+RESPONSE: Direct answer, explanation, insights (NO code modification)
+"
 ```
 
+## Examples
+
+**Basic Question (Standard Mode)**:
+```bash
+/cli:chat "analyze the authentication flow"
+# Executes: Gemini analysis
+# Returns: Explanation of auth flow, components involved, data flow
+```
+
+**Intelligent Q&A (Agent Mode)**:
+```bash
+/cli:chat --agent "how does JWT token refresh work in this codebase"
+# Phase 1: Understands inquiry = JWT refresh mechanism
+# Phase 2: Discovers JWT files, refresh logic, middleware patterns
+# Phase 3: Builds Q&A prompt with discovered implementation details
+# Phase 4: Executes Gemini with precise context for accurate answer
+# Phase 5: Saves conversation log with discovered context
+# Returns: Detailed answer with code references + execution log
+```
+
+**Architecture Question**:
+```bash
+/cli:chat --tool qwen "how does React component optimization work here"
+# Executes: Qwen architecture analysis
+# Returns: Component structure explanation, optimization patterns used
+```
+
+**Security Analysis**:
+```bash
+/cli:chat --tool codex "review security vulnerabilities"
+# Executes: Codex security analysis
+# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
+```
+
+**Enhanced Inquiry**:
+```bash
+/cli:chat --enhance "explain the login issue"
+# Step 1: Enhance to expand login context
+# Step 2: Analysis with expanded understanding
+# Returns: Detailed explanation of login flow and potential issues
+```
+
+**Broad Context**:
+```bash
+/cli:chat --all-files "find all API endpoints"
+# Executes: Analysis across entire codebase
+# Returns: List and explanation of API endpoints (NO code generation)
+```
+
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND query is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
+- **No active session OR unrelated query**:
+  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
+- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
+
 ## Notes
 
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Active workflow session: results saved to `.workflow/WFS-[id]/.chat/`
-- No session: results returned directly
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad conversations preserved for future reference

.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(*)
 ---
 
@@ -457,10 +452,45 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 }
 ```
 
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Execution log: `.workflow/WFS-[id]/.chat/codex-execute-[timestamp].md`
+  - Task summaries: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+  - Task updates: `.workflow/WFS-[id]/.task/[TASK-ID].json` status updates
+  - TodoWrite tracking: Embedded in execution log
+- **ELSE** (no active session):
+  - **Recommended**: Create workflow session first (`/workflow:session:start`)
+  - **Alternative**: Save to `.workflow/.scratchpad/codex-execute-[description]-[timestamp].md`
+
+**Output Files** (during execution):
+```
+.workflow/WFS-[session-id]/
+├── .chat/
+│   └── codex-execute-20250105-143022.md    # Full execution log with task flow
+├── .summaries/
+│   ├── IMPL-001.1-summary.md               # Subtask summaries
+│   ├── IMPL-001.2-summary.md
+│   └── IMPL-001-summary.md                 # Final task summary
+└── .task/
+    ├── IMPL-001.json                       # Updated task status
+    └── [subtask JSONs if decomposed]
+```
+
+**Examples**:
+- During session `WFS-auth-system`, executing multi-stage auth implementation:
+  - Log: `.workflow/WFS-auth-system/.chat/codex-execute-20250105-143022.md`
+  - Summaries: `.workflow/WFS-auth-system/.summaries/IMPL-001.{1,2,3}-summary.md`
+  - Task status: `.workflow/WFS-auth-system/.task/IMPL-001.json` (status: completed)
+- No session, ad-hoc multi-stage task:
+  - Log: `.workflow/.scratchpad/codex-execute-auth-refactor-20250105-143045.md`
+
 **Save Results**:
-- Execution log: `.chat/codex-execute-[timestamp].md` (if workflow active)
-- Summary: `.summaries/[TASK-ID]-summary.md` (if task ID provided)
-- TodoWrite tracking embedded in session
+- Execution log with task flow diagram and TodoWrite tracking
+- Individual summaries for each completed subtask
+- Final consolidated summary when all subtasks complete
+- Modified code files throughout project
 
 ## Notes
 
@@ -471,3 +501,8 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 **Input Flexibility**: Accepts both freeform descriptions and task IDs (auto-detects and loads JSON)
 
 **Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
+
+**Output Details**:
+- Output routing and scratchpad details: see workflow-architecture.md
+- Session management: see intelligent-tools-strategy.md
+- **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

.claude/commands/cli/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 --full-auto exec "
+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
+" --skip-git-repo-check
+
+# Subsequent rounds (resume discussion)
+codex --full-auto exec "
+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 --skip-git-repo-check
+```
+
+**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,29 +1,33 @@
 ---
 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(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Execute Command (/cli:execute)
 
 ## Purpose
 
-Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations).
+Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **MODIFIES CODE**.
 
+**Intent**: Autonomous code implementation, modification, and generation
 **Supported Tools**: codex, gemini (default), qwen
 **Key Feature**: Automatic context inference and file pattern detection
 
+## Core Behavior
+
+1. **Code Modification**: This command MODIFIES, CREATES, and DELETES code files
+2. **Auto-Approval**: YOLO mode bypasses confirmation prompts for all operations
+3. **Implementation Focus**: Executes actual code changes, not just recommendations
+4. **Requires Explicit Intent**: Use only when implementation is intended
+
 ## Core Concepts
 
 ### YOLO Permissions
-Auto-approves: file pattern inference, execution, file modifications, summary generation
+Auto-approves: file pattern inference, execution, **file modifications**, summary generation
+
+**⚠️ WARNING**: This command will make actual code changes without manual confirmation
 
 ### Execution Modes
 
@@ -35,6 +39,10 @@ Auto-approves: file pattern inference, execution, file modifications, summary ge
 - Input: Workflow task identifier (e.g., `IMPL-001`)
 - Process: Task JSON parsing → Scope analysis → Execute
 
+**3. Agent Mode** (`--agent` flag):
+- Input: Description or task-id
+- Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
+
 ### Context Inference
 
 Auto-selects files based on keywords and technology:
@@ -60,7 +68,8 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode unless specified)
 - `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
 - `<description|task-id>` - Natural language description or task identifier
 - `--debug` - Verbose logging
@@ -70,30 +79,144 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 **Session Management**: Auto-detects `.workflow/.active-*` marker
 - Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- No session: Create new session
+- No session: Create new session or save to scratchpad
 
 **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
 
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+  - Update task status in `.task/[TASK-ID].json` (if task ID provided)
+  - Generate summary in `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md`
+- **ELSE** (no active session):
+  - **Option 1**: Create new workflow session for task
+  - **Option 2**: Save to `.workflow/.scratchpad/execute-[description]-[timestamp].md`
+
+**Output Files** (when active session exists):
+- Execution log: `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- Task summary: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+- Modified code: Project files per implementation
+
+**Examples**:
+- During session `WFS-auth-system`, executing `IMPL-001`:
+  - Log: `.workflow/WFS-auth-system/.chat/execute-20250105-143022.md`
+  - Summary: `.workflow/WFS-auth-system/.summaries/IMPL-001-summary.md`
+- No session, ad-hoc implementation:
+  - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
+
+## Execution Modes
+
+### Standard Mode (Default)
+```bash
+# Gemini/Qwen: MODE=write with --approval-mode yolo
+cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+PURPOSE: [implementation goal]
+TASK: [specific implementation]
+MODE: write
+CONTEXT: @{CLAUDE.md} [auto-detected files]
+EXPECTED: Working implementation with code changes
+RULES: [constraints] | Auto-approve all changes
+"
+
+# Codex: MODE=auto with danger-full-access
+codex -C . --full-auto exec "
+PURPOSE: [implementation goal]
+TASK: [specific implementation]
+MODE: auto
+CONTEXT: [auto-detected files]
+EXPECTED: Complete implementation with tests
+" --skip-git-repo-check -s danger-full-access
+```
+
+### Agent Mode (`--agent` flag)
+
+Delegate implementation to `cli-execution-agent` for intelligent execution with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Implement with automated context discovery and optimal tool selection",
+  prompt=`
+    Task: ${description_or_task_id}
+    Mode: execute
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${enhance_flag ? 'Enhance: true' : ''}
+
+    Agent will autonomously:
+    - Discover implementation files and dependencies
+    - Assess complexity and select optimal tool
+    - Execute with YOLO permissions (auto-approve)
+    - Generate task summary if task-id provided
+  `
+)
+```
+
+The agent handles all phases internally, including complexity-based tool selection.
+
 ## Examples
 
+**Basic Implementation (Standard Mode)** (⚠️ modifies code):
 ```bash
-# Description mode with auto-detection
 /cli:execute "implement JWT authentication with middleware"
-
-# Enhanced prompt
-/cli:execute --enhance "implement JWT authentication"
-
-# Task ID mode
-/cli:execute IMPL-001
-
-# Codex execution
-/cli:execute --tool codex "optimize database queries"
-
-# Qwen with enhancement
-/cli:execute --tool qwen --enhance "refactor auth module"
+# Executes: Creates auth middleware, updates routes, modifies config
+# Result: NEW/MODIFIED code files with JWT implementation
 ```
 
+**Intelligent Implementation (Agent Mode)** (⚠️ modifies code):
+```bash
+/cli:execute --agent "implement OAuth2 authentication with token refresh"
+# Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
+# Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
+# Phase 3: Enhances prompt with discovered patterns and best practices
+# Phase 4: Selects Codex (complex task), executes with comprehensive context
+# Phase 5: Saves execution log + generates implementation summary
+# Result: Complete OAuth2 implementation + detailed execution log
+```
+
+**Enhanced Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --enhance "implement JWT authentication"
+# Step 1: Enhance to expand requirements
+# Step 2: Execute implementation with auto-approval
+# Result: Complete auth system with MODIFIED code files
+```
+
+**Task Execution** (⚠️ modifies code):
+```bash
+/cli:execute IMPL-001
+# Reads: .task/IMPL-001.json for requirements
+# Executes: Implementation based on task spec
+# Result: Code changes per task definition
+```
+
+**Codex Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --tool codex "optimize database queries"
+# Executes: Codex with full file access
+# Result: MODIFIED query code, new indexes, updated tests
+```
+
+**Qwen Code Generation** (⚠️ modifies code):
+```bash
+/cli:execute --tool qwen --enhance "refactor auth module"
+# Step 1: Enhanced refactoring plan
+# Step 2: Execute with MODE=write
+# Result: REFACTORED auth code with structural changes
+```
+
+## Comparison with Analysis Commands
+
+| Command | Intent | Code Changes | Auto-Approve |
+|---------|--------|--------------|--------------|
+| `/cli:analyze` | Understand code | ❌ NO | N/A |
+| `/cli:chat` | Ask questions | ❌ NO | N/A |
+| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
+
 ## Notes
 
 - Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
-- Auto-generated outputs: `.summaries/[TASK-ID]-summary.md`, `.chat/execute-[timestamp].md`
+- Output routing and scratchpad details: see workflow-architecture.md
+- **⚠️ Code Modification**: This command modifies code - execution logs document changes made

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

@@ -1,13 +1,8 @@
 ---
 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(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Bug Index (/cli:mode:bug-index)
@@ -21,40 +16,121 @@ Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bu
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
 - `--enhance` - Enhance bug description with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<bug-description>` (Required) - Bug description or error message
 
 ## Execution Flow
 
-1. Parse tool and directory options
-2. If `--enhance`: Execute `/enhance-prompt` to expand bug context
-3. Use bug-fix template: `~/.claude/prompt-templates/bug-fix.md`
-4. Execute with `--all-files` in target directory
-5. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+### Standard Mode (Default)
+
+1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
+2. **If `--enhance` flag present**: Execute `/enhance-prompt "[bug-description]"` first
+3. Parse bug description (original or enhanced)
+4. Detect target directory (from `--cd` or auto-infer)
+5. Build command for selected tool with bug-fix template
+6. Execute analysis (read-only, provides fix recommendations)
+7. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+
+### Agent Mode (`--agent` flag)
+
+Delegate bug analysis to `cli-execution-agent` for intelligent debugging with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Analyze bug with automated context discovery",
+  prompt=`
+    Task: ${bug_description}
+    Mode: debug (bug analysis)
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Template: bug-fix
+
+    Agent will autonomously:
+    - Discover bug-related files and error traces
+    - Build debug prompt with bug-fix template
+    - Execute analysis and provide fix recommendations
+    - Save analysis log
+  `
+)
+```
+
+The agent handles all phases internally.
+
+## Core Rules
+
+1. **Analysis Only**: This command analyzes bugs and suggests fixes - it does NOT modify code
+2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
+3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+4. **Template Required**: Always use bug-fix template
+5. **Session Output**: Save analysis results and fix recommendations to session chat
 
 ## Analysis Focus (via Template)
 
-- Root cause investigation
-- Code path tracing
-- Targeted minimal fixes
-- Impact assessment
+- Root cause investigation and diagnosis
+- Code path tracing to locate issues
+- Targeted minimal fix recommendations
+- Impact assessment of proposed changes
+
+## Command Template
+
+```bash
+cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: [bug analysis goal]
+TASK: Systematic bug analysis and fix recommendations
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
+RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
+"
+```
 
 ## Examples
 
+**Basic Bug Analysis (Standard Mode)**:
 ```bash
-# Basic bug analysis
-/cli:mode:bug-index "null pointer in authentication"
+/cli:mode:bug-index "null pointer error in login flow"
+# Executes: Gemini with bug-fix template
+# Returns: Root cause analysis, fix recommendations
+```
 
-# Directory-specific
-/cli:mode:bug-index --cd "src/auth" "token validation fails"
+**Intelligent Bug Analysis (Agent Mode)**:
+```bash
+/cli:mode:bug-index --agent "intermittent token validation failure"
+# Phase 1: Classifies as debug task, extracts keywords ['token', 'validation', 'failure']
+# Phase 2: MCP discovers token validation code, middleware, test files with errors
+# Phase 3: Builds debug prompt with bug-fix template + discovered error patterns
+# Phase 4: Executes Gemini with comprehensive bug context
+# Phase 5: Saves analysis log with detailed fix recommendations
+# Returns: Root cause analysis + code path traces + minimal fix suggestions
+```
 
-# Enhanced description
-/cli:mode:bug-index --enhance "login broken"
+**Standard Template Example**:
+```bash
+cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Debug authentication null pointer error
+TASK: Identify root cause and provide fix recommendations
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
+RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
+"
+```
 
-# Qwen for architecture-related bugs
-/cli:mode:bug-index --tool qwen "circular dependency in modules"
+**Directory-Specific**:
+```bash
+cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Fix token validation failure
+TASK: Analyze token validation bug in auth module
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+EXPECTED: Validation logic analysis, fix recommendation with minimal changes
+RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
+"
 ```
 
 ## Bug Investigation Workflow
@@ -62,13 +138,27 @@ Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bu
 ```bash
 # 1. Find bug-related files
 rg "error_keyword" --files-with-matches
+mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")
 
-# 2. Execute bug analysis with focused context
+# 2. Execute bug analysis with focused context (analysis only, no code changes)
 /cli:mode:bug-index --cd "src/module" "specific error description"
 ```
 
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND bug is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+- **No active session OR quick debugging**:
+  - Save to `.workflow/.scratchpad/bug-index-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-payment-fix`, analyzing payment bug → `.chat/bug-index-20250105-143022.md`
+- No session, quick null pointer investigation → `.scratchpad/bug-index-null-pointer-20250105-143045.md`
+
 ## Notes
 
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
 - Template path: `~/.claude/prompt-templates/bug-fix.md`
 - Always uses `--all-files` for comprehensive codebase context

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

@@ -1,13 +1,8 @@
 ---
 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(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Code Analysis (/cli:mode:code-analysis)
@@ -21,55 +16,155 @@ Systematic code analysis with execution path tracing template (`~/.claude/prompt
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
 - `--enhance` - Enhance analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
 
 ## Execution Flow
 
-1. Parse tool and directory options
-2. If `--enhance`: Execute `/enhance-prompt` to expand analysis intent
-3. Use code-analysis template: `~/.claude/prompt-templates/code-analysis.md`
-4. Execute with `--all-files` in target directory
-5. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+### Standard Mode (Default)
+
+1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
+2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first
+3. Parse analysis target (original or enhanced)
+4. Detect target directory (from `--cd` or auto-infer)
+5. Build command for selected tool with code-analysis template
+6. Execute deep analysis (read-only, no code modification)
+7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+
+### Agent Mode (`--agent` flag)
+
+Delegate code analysis to `cli-execution-agent` for intelligent execution path tracing with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Analyze code execution paths with automated context discovery",
+  prompt=`
+    Task: ${analysis_target}
+    Mode: code-analysis (execution tracing)
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Template: code-analysis
+
+    Agent will autonomously:
+    - Discover execution paths and call flows
+    - Build analysis prompt with code-analysis template
+    - Execute deep tracing analysis
+    - Generate call diagrams and save log
+  `
+)
+```
+
+The agent handles all phases internally.
+
+## Core Rules
+
+1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
+2. **Tool Selection**: Use `--tool` value or default to gemini
+3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
+4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+5. **Template Required**: Always use code-analysis template
+6. **Session Output**: Save analysis results to session chat
 
 ## Analysis Capabilities (via Template)
 
-- Execution path tracing with variable states
-- Call flow visualization and diagrams
-- Control & data flow analysis
-- Logical reasoning ("why" behind code behavior)
-- Debugging insights and inefficiency detection
+- **Systematic Code Analysis**: Break down complex code into manageable parts
+- **Execution Path Tracing**: Track variable states and call stacks
+- **Control & Data Flow**: Understand code logic and data transformations
+- **Call Flow Visualization**: Diagram function calling sequences
+- **Logical Reasoning**: Explain "why" behind code behavior
+- **Debugging Insights**: Identify potential bugs or inefficiencies
+
+## Command Template
+
+```bash
+cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: [analysis goal]
+TASK: Systematic code analysis and execution path tracing
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+EXPECTED: Execution trace, call flow diagram, debugging insights
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
+"
+```
 
 ## Examples
 
+**Basic Code Analysis (Standard Mode)**:
 ```bash
-# Basic code analysis
-/cli:mode:code-analysis "trace authentication flow"
+/cli:mode:code-analysis "trace authentication execution flow"
+# Executes: Gemini with code-analysis template
+# Returns: Execution trace, call diagram, debugging insights
+```
 
-# Directory-specific with enhancement
-/cli:mode:code-analysis --cd "src/auth" --enhance "how does JWT work"
+**Intelligent Code Analysis (Agent Mode)**:
+```bash
+/cli:mode:code-analysis --agent "trace JWT token validation from request to database"
+# Phase 1: Classifies as deep analysis, keywords ['jwt', 'token', 'validation', 'database']
+# Phase 2: MCP discovers request handler → middleware → service → repository chain
+# Phase 3: Builds analysis prompt with code-analysis template + complete call path
+# Phase 4: Executes Gemini with traced execution paths
+# Phase 5: Saves detailed analysis with call flow diagrams and variable states
+# Returns: Complete execution trace + call diagram + data flow analysis
+```
 
-# Qwen for architecture analysis
-/cli:mode:code-analysis --tool qwen "explain microservices communication"
+**Standard Template Example**:
+```bash
+cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Trace authentication execution flow
+TASK: Analyze complete auth flow from request to response
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+EXPECTED: Step-by-step execution trace with call diagram, variable states
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
+"
+```
 
-# Codex for deep tracing
-/cli:mode:code-analysis --tool codex --cd "src/api" "trace request lifecycle"
+**Directory-Specific Analysis**:
+```bash
+cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Understand JWT token validation logic
+TASK: Trace JWT validation from middleware to service layer
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+EXPECTED: Validation flow diagram, token lifecycle analysis
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
+"
 ```
 
 ## Code Tracing Workflow
 
 ```bash
-# 1. Find entry points
-rg "function.*main|export.*handler" --files-with-matches
+# 1. Find entry points and related files
+rg "function.*authenticate|class.*AuthService" --files-with-matches
+mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts")
 
-# 2. Execute deep analysis
+# 2. Build call graph understanding
+# entry → middleware → service → repository
+
+# 3. Execute deep analysis (analysis only, no code changes)
 /cli:mode:code-analysis --cd "src" "trace execution from entry point"
 ```
 
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+- **No active session OR standalone analysis**:
+  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
+- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
+
 ## Notes
 
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
 - Template path: `~/.claude/prompt-templates/code-analysis.md`
 - Always uses `--all-files` for comprehensive code context

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

@@ -1,13 +1,8 @@
 ---
 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(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Plan (/cli:mode:plan)
@@ -21,55 +16,153 @@ Comprehensive planning and architecture analysis with strategic planning templat
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
 - `--enhance` - Enhance topic with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused planning
 - `<topic>` (Required) - Planning topic or architectural question
 
 ## Execution Flow
 
-1. Parse tool and directory options
-2. If `--enhance`: Execute `/enhance-prompt` to expand planning context
-3. Use planning template: `~/.claude/prompt-templates/plan.md`
-4. Execute with `--all-files` in target directory
-5. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+### Standard Mode (Default)
+
+1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
+2. **If `--enhance` flag present**: Execute `/enhance-prompt "[topic]"` first
+3. Parse topic (original or enhanced)
+4. Detect target directory (from `--cd` or auto-infer)
+5. Build command for selected tool with planning template
+6. Execute analysis (read-only, no code modification)
+7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+
+### Agent Mode (`--agent` flag)
+
+Delegate planning to `cli-execution-agent` for intelligent strategic planning with automated architecture discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Create strategic plan with automated architecture discovery",
+  prompt=`
+    Task: ${planning_topic}
+    Mode: plan (strategic planning)
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
+    Template: plan
+
+    Agent will autonomously:
+    - Discover project structure and existing architecture
+    - Build planning prompt with plan template
+    - Execute strategic planning analysis
+    - Generate implementation roadmap and save
+  `
+)
+```
+
+The agent handles all phases internally.
+
+## Core Rules
+
+1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
+2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
+3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+4. **Template Required**: Always use planning template
+5. **Session Output**: Save analysis results to session chat
 
 ## Planning Capabilities (via Template)
 
-- Strategic architecture insights
-- Implementation roadmaps
-- Key technical decisions
+- Strategic architecture insights and recommendations
+- Implementation roadmaps and suggestions
+- Key technical decisions analysis
 - Risk assessment
 - Resource planning
 
-## Examples
+## Command Template
 
 ```bash
-# Basic planning
-/cli:mode:plan "design user dashboard"
+cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: [planning goal from topic]
+TASK: Comprehensive planning and architecture analysis
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
+EXPECTED: Strategic insights, implementation recommendations, key decisions
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
+"
+```
 
-# Enhanced with directory scope
-/cli:mode:plan --cd "src/api" --enhance "plan API refactoring"
+## Examples
 
-# Qwen for architecture planning
-/cli:mode:plan --tool qwen "plan microservices migration"
+**Basic Planning Analysis (Standard Mode)**:
+```bash
+/cli:mode:plan "design user dashboard architecture"
+# Executes: Gemini with planning template
+# Returns: Architecture recommendations, component design, roadmap
+```
 
-# Codex for technical planning
-/cli:mode:plan --tool codex "plan testing strategy"
+**Intelligent Planning (Agent Mode)**:
+```bash
+/cli:mode:plan --agent "design microservices architecture for payment system"
+# Phase 1: Classifies as architectural planning, keywords ['microservices', 'payment', 'architecture']
+# Phase 2: MCP discovers existing services, payment flows, integration patterns
+# Phase 3: Builds planning prompt with plan template + current architecture context
+# Phase 4: Executes Gemini with comprehensive project understanding
+# Phase 5: Saves planning document with implementation roadmap and migration strategy
+# Returns: Strategic architecture plan + implementation roadmap + risk assessment
+```
+
+**Standard Template Example**:
+```bash
+cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Design user dashboard architecture
+TASK: Plan dashboard component structure and data flow
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+EXPECTED: Architecture recommendations, component design, data flow diagram
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
+"
+```
+
+**Directory-Specific Planning**:
+```bash
+cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Plan API refactoring strategy
+TASK: Analyze current API structure and recommend improvements
+MODE: analysis
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
+EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
+"
 ```
 
 ## Planning Workflow
 
 ```bash
-# 1. Gather existing architecture info
+# 1. Discover project structure
+~/.claude/scripts/get_modules_by_depth.sh
+mcp__code-index__find_files(pattern="*.ts")
+
+# 2. Gather existing architecture info
 rg "architecture|design" --files-with-matches
 
-# 2. Execute planning analysis
+# 3. Execute planning analysis (analysis only, no code changes)
 /cli:mode:plan "topic for strategic planning"
 ```
 
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND planning is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+- **No active session OR exploratory planning**:
+  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
+- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
+
 ## Notes
 
 - Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
 - Template path: `~/.claude/prompt-templates/plan.md`
 - Always uses `--all-files` for comprehensive project context

.claude/commands/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
@@ -36,7 +31,7 @@ FUNCTION should_use_gemini(user_prompt):
 END
 ```
 
-**Gemini Integration:** @~/.claude/workflows/intelligent-tools-strategy.md
+**Gemini Integration:** ~/.claude/workflows/intelligent-tools-strategy.md
 
 ## Enhancement Rules
 

.claude/commands/memory/docs.md

@@ -0,0 +1,828 @@
+---
+name: docs
+description: Documentation planning and orchestration - creates structured documentation tasks for execution
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-generate]"
+---
+
+# Documentation Workflow (/memory:docs)
+
+## Overview
+Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent.
+
+**Documentation Output**: All generated documentation is placed in `.workflow/docs/` directory with **mirrored project structure**. For example:
+- Source: `src/modules/auth/index.ts` → Docs: `.workflow/docs/src/modules/auth/API.md`
+- Source: `lib/core/utils.js` → Docs: `.workflow/docs/lib/core/README.md`
+
+**Two Execution Modes**:
+- **Default**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs in `implementation_approach`
+- **--cli-generate**: CLI generates docs in `implementation_approach` (MODE=write)
+
+## Path Mirroring Strategy
+
+**Principle**: Documentation structure **mirrors** source code structure.
+
+| Source Path | Documentation Path |
+|------------|-------------------|
+| `src/modules/auth/index.ts` | `.workflow/docs/src/modules/auth/API.md` |
+| `src/modules/auth/middleware/` | `.workflow/docs/src/modules/auth/middleware/README.md` |
+| `lib/core/utils.js` | `.workflow/docs/lib/core/API.md` |
+| `lib/core/helpers/` | `.workflow/docs/lib/core/helpers/README.md` |
+
+**Benefits**:
+- Easy to locate documentation for any source file
+- Maintains logical organization
+- Clear 1:1 mapping between code and docs
+- Supports any project structure (src/, lib/, packages/, etc.)
+
+## Parameters
+
+```bash
+/memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-generate]
+```
+
+- **path**: Target directory (default: current directory)
+  - Specifies the directory to generate documentation for
+
+- **--mode**: Documentation generation mode (default: full)
+  - `full`: Complete documentation (modules + project README + ARCHITECTURE + EXAMPLES)
+    - Level 1: Module tree documentation
+    - Level 2: Project README.md
+    - Level 3: ARCHITECTURE.md + EXAMPLES.md + HTTP API (optional)
+  - `partial`: Module documentation only
+    - Level 1: Module tree documentation (API.md + README.md)
+    - Skips project-level documentation
+
+- **--tool**: CLI tool selection (default: gemini)
+  - `gemini`: Comprehensive documentation, pattern recognition
+  - `qwen`: Architecture analysis, system design focus
+  - `codex`: Implementation validation, code quality
+
+- **--cli-generate**: Enable CLI-based documentation generation (optional)
+  - When enabled: CLI generates docs with MODE=write in implementation_approach
+  - When disabled (default): CLI analyzes with MODE=analysis in pre_analysis
+
+## Planning Workflow
+
+### Phase 1: Initialize Session
+
+#### Step 1: Create Session and Generate Config
+```bash
+# Create session structure and initialize config in one step
+bash(
+  # Parse arguments
+  path="${1:-.}"
+  tool="gemini"
+  mode="full"
+  cli_generate=false
+  shift
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --tool) tool="$2"; shift 2 ;;
+      --mode) mode="$2"; shift 2 ;;
+      --cli-generate) cli_generate=true; shift ;;
+      *) shift ;;
+    esac
+  done
+
+  # Detect paths
+  project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+  if [[ "$path" == /* ]] || [[ "$path" == [A-Z]:* ]]; then
+    target_path="$path"
+  else
+    target_path=$(cd "$path" 2>/dev/null && pwd || echo "$PWD/$path")
+  fi
+
+  # Create session
+  timestamp=$(date +%Y%m%d-%H%M%S)
+  session="WFS-docs-${timestamp}"
+  mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
+  touch ".workflow/.active-${session}"
+
+  # Generate single config file with all info
+  cat > ".workflow/${session}/.process/config.json" <<EOF
+{
+  "session_id": "${session}",
+  "timestamp": "$(date -Iseconds)",
+  "path": "${path}",
+  "target_path": "${target_path}",
+  "project_root": "${project_root}",
+  "mode": "${mode}",
+  "tool": "${tool}",
+  "cli_generate": ${cli_generate}
+}
+EOF
+
+  echo "✓ Session initialized: ${session}"
+  echo "✓ Target: ${target_path}"
+  echo "✓ Mode: ${mode}"
+  echo "✓ Tool: ${tool}, CLI generate: ${cli_generate}"
+)
+```
+
+**Output**:
+```
+✓ Session initialized: WFS-docs-20240120-143022
+✓ Target: /d/Claude_dms3
+✓ Mode: full
+✓ Tool: gemini, CLI generate: false
+```
+
+### Phase 2: Analyze Structure
+
+#### Step 1: Discover and Classify Folders
+```bash
+# Run analysis pipeline (module discovery + folder classification)
+bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh > .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+```
+
+**Output Sample** (folder-analysis.txt):
+```
+./src/modules/auth|code|code:5|dirs:2
+./src/modules/api|code|code:3|dirs:0
+./src/utils|navigation|code:0|dirs:4
+```
+
+#### Step 2: Extract Top-Level Directories
+```bash
+# Group folders by top-level directory
+bash(awk -F'|' '{
+  path = $1
+  gsub(/^\.\//, "", path)
+  split(path, parts, "/")
+  if (length(parts) >= 2) print parts[1] "/" parts[2]
+  else if (length(parts) == 1 && parts[1] != ".") print parts[1]
+}' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | sort -u > .workflow/WFS-docs-20240120/.process/top-level-dirs.txt)
+```
+
+**Output** (top-level-dirs.txt):
+```
+src/modules
+src/utils
+lib/core
+```
+
+#### Step 3: Generate Analysis Summary
+```bash
+# Calculate statistics
+bash(
+  total=$(wc -l < .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+  code_count=$(grep '|code|' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | wc -l)
+  nav_count=$(grep '|navigation|' .workflow/WFS-docs-20240120/.process/folder-analysis.txt | wc -l)
+  top_dirs=$(wc -l < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt)
+
+  echo "📊 Folder Analysis Complete:"
+  echo "  - Total folders: $total"
+  echo "  - Code folders: $code_count"
+  echo "  - Navigation folders: $nav_count"
+  echo "  - Top-level dirs: $top_dirs"
+)
+
+# Update config with statistics
+bash(jq '. + {analysis: {total: "15", code: "8", navigation: "7", top_level: "3"}}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json)
+```
+
+### Phase 3: Detect Update Mode
+
+#### Step 1: Count Existing Documentation in .workflow/docs/
+```bash
+# Check .workflow/docs/ directory and count existing files
+bash(if [[ -d ".workflow/docs" ]]; then
+  find .workflow/docs -name "*.md" 2>/dev/null | wc -l
+else
+  echo "0"
+fi)
+```
+
+**Output**: `5` (existing docs in .workflow/docs/)
+
+#### Step 2: List Existing Documentation
+```bash
+# List existing files in .workflow/docs/ (for task context)
+bash(if [[ -d ".workflow/docs" ]]; then
+  find .workflow/docs -name "*.md" 2>/dev/null > .workflow/WFS-docs-20240120/.process/existing-docs.txt
+else
+  touch .workflow/WFS-docs-20240120/.process/existing-docs.txt
+fi)
+```
+
+**Output** (existing-docs.txt):
+```
+.workflow/docs/src/modules/auth/API.md
+.workflow/docs/src/modules/auth/README.md
+.workflow/docs/lib/core/README.md
+.workflow/docs/README.md
+```
+
+#### Step 3: Update Config with Update Status
+```bash
+# Determine update status (create or update) and update config
+bash(
+  existing_count=$(find .workflow/docs -name "*.md" 2>/dev/null | wc -l)
+  if [[ $existing_count -gt 0 ]]; then
+    jq ". + {update_mode: \"update\", existing_docs: $existing_count}" .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
+  else
+    jq '. + {update_mode: "create", existing_docs: 0}' .workflow/WFS-docs-20240120/.process/config.json > .workflow/WFS-docs-20240120/.process/config.json.tmp && mv .workflow/WFS-docs-20240120/.process/config.json.tmp .workflow/WFS-docs-20240120/.process/config.json
+  fi
+)
+
+# Display strategy summary
+bash(
+  mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+  update_mode=$(jq -r '.update_mode' .workflow/WFS-docs-20240120/.process/config.json)
+  existing=$(jq -r '.existing_docs' .workflow/WFS-docs-20240120/.process/config.json)
+  tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+  cli_gen=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
+
+  echo "📋 Documentation Strategy:"
+  echo "  - Path: $(jq -r '.target_path' .workflow/WFS-docs-20240120/.process/config.json)"
+  echo "  - Mode: $mode ($([ "$mode" = "full" ] && echo "complete docs" || echo "modules only"))"
+  echo "  - Update: $update_mode ($existing existing files)"
+  echo "  - Tool: $tool, CLI generate: $cli_gen"
+)
+```
+
+### Phase 4: Decompose Tasks
+
+#### Task Hierarchy
+```
+Level 1: Module Trees (always, parallel execution)
+  ├─ IMPL-001: Document 'src/modules/'
+  ├─ IMPL-002: Document 'src/utils/'
+  └─ IMPL-003: Document 'lib/'
+
+Level 2: Project README (mode=full only, depends on Level 1)
+  └─ IMPL-004: Generate Project README
+
+Level 3: Architecture & Examples (mode=full only, depends on Level 2)
+  ├─ IMPL-005: Generate ARCHITECTURE.md + EXAMPLES.md
+  └─ IMPL-006: Generate HTTP API (optional)
+```
+
+#### Step 1: Generate Level 1 Tasks (Module Trees)
+```bash
+# Read top-level directories and create tasks
+bash(
+  task_count=0
+  while read -r top_dir; do
+    task_count=$((task_count + 1))
+    task_id=$(printf "IMPL-%03d" $task_count)
+    echo "Creating $task_id for '$top_dir'"
+    # Generate task JSON (see Task Templates section)
+  done < .workflow/WFS-docs-20240120/.process/top-level-dirs.txt
+)
+```
+
+**Output**:
+```
+Creating IMPL-001 for 'src/modules'
+Creating IMPL-002 for 'src/utils'
+Creating IMPL-003 for 'lib'
+```
+
+#### Step 2: Generate Level 2-3 Tasks (Full Mode Only)
+```bash
+# Check documentation mode
+bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+
+# If full mode, create project-level tasks
+bash(
+  mode=$(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+  if [[ "$mode" == "full" ]]; then
+    echo "Creating IMPL-004: Project README"
+    echo "Creating IMPL-005: ARCHITECTURE.md + EXAMPLES.md"
+    # Optional: Check for HTTP API endpoints
+    if grep -r "router\.|@Get\|@Post" src/ >/dev/null 2>&1; then
+      echo "Creating IMPL-006: HTTP API docs"
+    fi
+  else
+    echo "Partial mode: Skipping project-level tasks"
+  fi
+)
+```
+
+### Phase 5: Generate Task JSONs
+
+#### Step 1: Extract Configuration
+```bash
+# Read config values from JSON
+bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+bash(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
+```
+
+**Output**: `tool=gemini`, `cli_generate=false`
+
+#### Step 2: Determine CLI Command Strategy
+```bash
+# Determine MODE and placement based on cli_generate flag
+bash(
+  cli_generate=$(jq -r '.cli_generate' .workflow/WFS-docs-20240120/.process/config.json)
+
+  if [[ "$cli_generate" == "true" ]]; then
+    echo "mode=write"
+    echo "placement=implementation_approach"
+    echo "approval_flag=--approval-mode yolo"
+  else
+    echo "mode=analysis"
+    echo "placement=pre_analysis"
+    echo "approval_flag="
+  fi
+)
+```
+
+**Output**:
+```
+mode=analysis
+placement=pre_analysis
+approval_flag=
+```
+
+#### Step 3: Build Tool-Specific Commands
+```bash
+# Generate command templates based on tool selection
+bash(
+  tool=$(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+
+  if [[ "$tool" == "codex" ]]; then
+    echo "codex -C \${dir} --full-auto exec \"...\" --skip-git-repo-check -s danger-full-access"
+  else
+    echo "bash(cd \${dir} && ~/.claude/scripts/${tool}-wrapper ${approval_flag} -p \"...\")"
+  fi
+)
+```
+
+## Task Templates
+
+### Level 1: Module Tree Task
+
+**Path Mapping**: Source `src/modules/` → Output `.workflow/docs/src/modules/`
+
+**Default Mode (cli_generate=false)**:
+```json
+{
+  "id": "IMPL-001",
+  "title": "Document Module Tree: 'src/modules/'",
+  "status": "pending",
+  "meta": {
+    "type": "docs-tree",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false,
+    "source_path": "src/modules",
+    "output_path": ".workflow/docs/src/modules"
+  },
+  "context": {
+    "requirements": [
+      "Analyze source code in src/modules/",
+      "Generate docs to .workflow/docs/src/modules/ (mirrored structure)",
+      "For code folders: generate API.md + README.md",
+      "For navigation folders: generate README.md only"
+    ],
+    "focus_paths": ["src/modules"],
+    "folder_analysis_file": "${session_dir}/.process/folder-analysis.txt"
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_docs",
+        "command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
+        "output_to": "existing_module_docs"
+      },
+      {
+        "step": "load_folder_analysis",
+        "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
+        "output_to": "target_folders"
+      },
+      {
+        "step": "analyze_module_tree",
+        "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze module structure\\nTASK: Generate documentation outline\\nMODE: analysis\\nCONTEXT: @{**/*} [target_folders]\\nEXPECTED: Structure outline\\nRULES: Analyze only\")",
+        "output_to": "tree_outline",
+        "note": "CLI for analysis only"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate module tree documentation",
+        "description": "Analyze source folders and generate docs to .workflow/docs/ with mirrored structure",
+        "modification_points": [
+          "Parse folder types from [target_folders]",
+          "Parse structure from [tree_outline]",
+          "For src/modules/auth/ → write to .workflow/docs/src/modules/auth/",
+          "Generate API.md for code folders",
+          "Generate README.md for all folders"
+        ],
+        "logic_flow": [
+          "Parse [target_folders] to get folder types",
+          "Parse [tree_outline] for structure",
+          "For each folder in source:",
+          "  - Map source_path to .workflow/docs/{source_path}",
+          "  - If type == 'code': Generate API.md + README.md",
+          "  - Elif type == 'navigation': Generate README.md only"
+        ],
+        "depends_on": [],
+        "output": "module_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/${top_dir}/*/API.md",
+      ".workflow/docs/${top_dir}/*/README.md"
+    ]
+  }
+}
+```
+
+**CLI Generate Mode (cli_generate=true)**:
+```json
+{
+  "id": "IMPL-001",
+  "title": "Document Module Tree: 'src/modules/'",
+  "status": "pending",
+  "meta": {
+    "type": "docs-tree",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": true,
+    "source_path": "src/modules",
+    "output_path": ".workflow/docs/src/modules"
+  },
+  "context": {
+    "requirements": [
+      "Analyze source code in src/modules/",
+      "Generate docs to .workflow/docs/src/modules/ (mirrored structure)",
+      "CLI generates documentation files directly"
+    ],
+    "focus_paths": ["src/modules"]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_docs",
+        "command": "bash(find .workflow/docs/${top_dir} -name '*.md' 2>/dev/null | xargs cat || echo 'No existing docs')",
+        "output_to": "existing_module_docs"
+      },
+      {
+        "step": "load_folder_analysis",
+        "command": "bash(grep '^src/modules' ${session_dir}/.process/folder-analysis.txt)",
+        "output_to": "target_folders"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Parse folder analysis",
+        "description": "Parse [target_folders] to get folder types and structure",
+        "modification_points": ["Extract folder types", "Identify code vs navigation folders"],
+        "logic_flow": ["Parse [target_folders] to get folder types", "Prepare folder list for CLI generation"],
+        "depends_on": [],
+        "output": "folder_types"
+      },
+      {
+        "step": 2,
+        "title": "Generate documentation via CLI",
+        "description": "Call CLI to generate docs to .workflow/docs/ with mirrored structure using MODE=write",
+        "modification_points": [
+          "Execute CLI generation command",
+          "Generate files to .workflow/docs/src/modules/ (mirrored path)",
+          "Generate API.md and README.md files"
+        ],
+        "logic_flow": [
+          "CLI analyzes source code in src/modules/",
+          "CLI writes documentation to .workflow/docs/src/modules/",
+          "Maintains directory structure mirroring"
+        ],
+        "command": "bash(cd src/modules && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation files in .workflow/docs/src/modules/\\nMODE: write\\nCONTEXT: @{**/*} [target_folders] [existing_module_docs]\\nEXPECTED: API.md and README.md in .workflow/docs/src/modules/\\nRULES: Mirror source structure, generate complete docs\")",
+        "depends_on": [1],
+        "output": "generated_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/${top_dir}/*/API.md",
+      ".workflow/docs/${top_dir}/*/README.md"
+    ]
+  }
+}
+```
+
+### Level 2: Project README Task
+
+**Default Mode**:
+```json
+{
+  "id": "IMPL-004",
+  "title": "Generate Project README",
+  "status": "pending",
+  "depends_on": ["IMPL-001", "IMPL-002", "IMPL-003"],
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_readme",
+        "command": "bash(cat .workflow/docs/README.md 2>/dev/null || echo 'No existing README')",
+        "output_to": "existing_readme"
+      },
+      {
+        "step": "load_module_docs",
+        "command": "bash(find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)",
+        "output_to": "all_module_docs",
+        "note": "Load all module docs from mirrored structure"
+      },
+      {
+        "step": "analyze_project",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
+        "output_to": "project_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate project README",
+        "description": "Generate project README with navigation links while preserving existing user modifications",
+        "modification_points": ["Parse [project_outline] and [all_module_docs]", "Generate project README structure", "Add navigation links to modules", "Preserve [existing_readme] user modifications"],
+        "logic_flow": ["Parse [project_outline] and [all_module_docs]", "Generate project README with navigation links", "Preserve [existing_readme] user modifications"],
+        "depends_on": [],
+        "output": "project_readme"
+      }
+    ],
+    "target_files": [".workflow/docs/README.md"]
+  }
+}
+```
+
+### Level 3: Architecture & Examples Documentation Task
+
+**Default Mode**:
+```json
+{
+  "id": "IMPL-005",
+  "title": "Generate Architecture & Examples Documentation",
+  "status": "pending",
+  "depends_on": ["IMPL-004"],
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_docs",
+        "command": "bash(cat .workflow/docs/ARCHITECTURE.md 2>/dev/null || echo 'No existing ARCHITECTURE'; echo '---SEPARATOR---'; cat .workflow/docs/EXAMPLES.md 2>/dev/null || echo 'No existing EXAMPLES')",
+        "output_to": "existing_arch_examples"
+      },
+      {
+        "step": "load_all_docs",
+        "command": "bash(cat .workflow/docs/README.md && find .workflow/docs -type f -name '*.md' ! -path '.workflow/docs/README.md' ! -path '.workflow/docs/ARCHITECTURE.md' ! -path '.workflow/docs/EXAMPLES.md' ! -path '.workflow/docs/api/*' | xargs cat)",
+        "output_to": "all_docs",
+        "note": "Load README + all module docs from mirrored structure"
+      },
+      {
+        "step": "analyze_architecture_and_examples",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze system architecture and generate examples\\nTASK: Synthesize architectural overview and usage patterns\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture outline + Examples outline\")",
+        "output_to": "arch_examples_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate architecture and examples documentation",
+        "description": "Generate ARCHITECTURE.md and EXAMPLES.md while preserving existing user modifications",
+        "modification_points": [
+          "Parse [arch_examples_outline] and [all_docs]",
+          "Generate ARCHITECTURE.md structure with system design and patterns",
+          "Generate EXAMPLES.md structure with code snippets and usage examples",
+          "Preserve [existing_arch_examples] user modifications"
+        ],
+        "logic_flow": [
+          "Parse [arch_examples_outline] and [all_docs]",
+          "Generate ARCHITECTURE.md with system design",
+          "Generate EXAMPLES.md with code snippets",
+          "Preserve [existing_arch_examples] modifications"
+        ],
+        "depends_on": [],
+        "output": "arch_examples_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/ARCHITECTURE.md",
+      ".workflow/docs/EXAMPLES.md"
+    ]
+  }
+}
+```
+
+### Level 3: HTTP API Documentation Task (Optional)
+
+**Default Mode**:
+```json
+{
+  "id": "IMPL-006",
+  "title": "Generate HTTP API Documentation",
+  "status": "pending",
+  "depends_on": ["IMPL-004"],
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_generate": false
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "discover_api_endpoints",
+        "command": "mcp__code-index__search_code_advanced(pattern='router\\.|@(Get|Post)', file_pattern='*.{ts,js}')",
+        "output_to": "endpoint_discovery"
+      },
+      {
+        "step": "load_existing_api_docs",
+        "command": "bash(cat .workflow/docs/api/README.md 2>/dev/null || echo 'No existing API docs')",
+        "output_to": "existing_api_docs"
+      },
+      {
+        "step": "analyze_api",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document HTTP API\\nTASK: Analyze API endpoints\\nMODE: analysis\\nCONTEXT: @{src/api/**/*} [endpoint_discovery]\\nEXPECTED: API outline\")",
+        "output_to": "api_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate HTTP API documentation",
+        "description": "Generate HTTP API documentation while preserving existing user modifications",
+        "modification_points": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Document endpoints and request/response formats", "Preserve [existing_api_docs] modifications"],
+        "logic_flow": ["Parse [api_outline] and [endpoint_discovery]", "Generate HTTP API documentation", "Preserve [existing_api_docs] modifications"],
+        "depends_on": [],
+        "output": "api_docs"
+      }
+    ],
+    "target_files": [".workflow/docs/api/README.md"]
+  }
+}
+```
+
+## Session Structure
+
+```
+.workflow/
+├── .active-WFS-docs-20240120-143022        # Active session marker
+└── WFS-docs-20240120-143022/
+    ├── IMPL_PLAN.md                         # Implementation plan
+    ├── TODO_LIST.md                         # Progress tracker
+    ├── .process/
+    │   ├── config.json                      # Single config (all settings + stats)
+    │   ├── folder-analysis.txt              # Folder classification results
+    │   ├── top-level-dirs.txt               # Top-level directory list
+    │   └── existing-docs.txt                # Existing documentation paths
+    └── .task/
+        ├── IMPL-001.json                    # Module tree task
+        ├── IMPL-002.json                    # Module tree task
+        ├── IMPL-003.json                    # Module tree task
+        ├── IMPL-004.json                    # Project README (full mode)
+        ├── IMPL-005.json                    # ARCHITECTURE.md + EXAMPLES.md (full mode)
+        └── IMPL-006.json                    # HTTP API docs (optional)
+```
+
+**Config File Structure** (config.json):
+```json
+{
+  "session_id": "WFS-docs-20240120-143022",
+  "timestamp": "2024-01-20T14:30:22+08:00",
+  "path": ".",
+  "target_path": "/d/Claude_dms3",
+  "project_root": "/d/Claude_dms3",
+  "mode": "full",
+  "tool": "gemini",
+  "cli_generate": false,
+  "update_mode": "update",
+  "existing_docs": 5,
+  "analysis": {
+    "total": "15",
+    "code": "8",
+    "navigation": "7",
+    "top_level": "3"
+  }
+}
+```
+
+## Generated Documentation
+
+**Structure mirrors project source directories**:
+
+```
+.workflow/docs/
+├── src/                               # Mirrors src/ directory
+│   ├── modules/                       # Level 1 output
+│   │   ├── README.md                  # Navigation for src/modules/
+│   │   ├── auth/
+│   │   │   ├── API.md                 # Auth module API signatures
+│   │   │   ├── README.md              # Auth module documentation
+│   │   │   └── middleware/
+│   │   │       ├── API.md             # Middleware API
+│   │   │       └── README.md          # Middleware docs
+│   │   └── api/
+│   │       ├── API.md                 # API module signatures
+│   │       └── README.md              # API module docs
+│   └── utils/                         # Level 1 output
+│       └── README.md                  # Utils navigation
+├── lib/                               # Mirrors lib/ directory
+│   └── core/
+│       ├── API.md
+│       └── README.md
+├── README.md                          # Level 2 output (root only)
+├── ARCHITECTURE.md                    # Level 3 output (root only)
+├── EXAMPLES.md                        # Level 3 output (root only)
+└── api/                               # Level 3 output (optional)
+    └── README.md                      # HTTP API reference
+```
+
+## Execution Commands
+
+### Full Mode (--mode full)
+```bash
+# Level 1 - Module documentation (parallel)
+/workflow:execute IMPL-001
+/workflow:execute IMPL-002
+/workflow:execute IMPL-003
+
+# Level 2 - Project README (after Level 1)
+/workflow:execute IMPL-004
+
+# Level 3 - Architecture & Examples (after Level 2)
+/workflow:execute IMPL-005  # ARCHITECTURE.md + EXAMPLES.md
+/workflow:execute IMPL-006  # HTTP API (if present)
+```
+
+### Partial Mode (--mode partial)
+```bash
+# Only Level 1 tasks generated (module documentation)
+/workflow:execute IMPL-001
+/workflow:execute IMPL-002
+/workflow:execute IMPL-003
+```
+
+## Simple Bash Commands
+
+### Session Management
+```bash
+# Create session and initialize config (all in one)
+bash(
+  session="WFS-docs-$(date +%Y%m%d-%H%M%S)"
+  mkdir -p ".workflow/${session}"/{.task,.process,.summaries}
+  touch ".workflow/.active-${session}"
+  cat > ".workflow/${session}/.process/config.json" <<EOF
+{"session_id":"${session}","timestamp":"$(date -Iseconds)","path":".","mode":"full","tool":"gemini","cli_generate":false}
+EOF
+  echo "Session: ${session}"
+)
+
+# Read session config
+bash(cat .workflow/WFS-docs-20240120/.process/config.json)
+
+# Extract config values
+bash(jq -r '.tool' .workflow/WFS-docs-20240120/.process/config.json)
+bash(jq -r '.mode' .workflow/WFS-docs-20240120/.process/config.json)
+
+# List session tasks
+bash(ls .workflow/WFS-docs-20240120/.task/*.json)
+```
+
+### Analysis Commands
+```bash
+# Discover and classify folders (scans project source)
+bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
+
+# Count existing docs (in .workflow/docs/ directory)
+bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null | wc -l; else echo "0"; fi)
+
+# List existing documentation (in .workflow/docs/ directory)
+bash(if [[ -d ".workflow/docs" ]]; then find .workflow/docs -name "*.md" 2>/dev/null; fi)
+```
+
+## Template Reference
+
+**Available Templates**:
+- `api.txt`: Unified template for Code API (Part A) and HTTP API (Part B)
+- `module-readme.txt`: Module purpose, usage, dependencies
+- `folder-navigation.txt`: Navigation README for folders with subdirectories
+- `project-readme.txt`: Project overview, getting started, module navigation
+- `project-architecture.txt`: System structure, module map, design patterns
+- `project-examples.txt`: End-to-end usage examples
+
+**Template Location**: `~/.claude/workflows/cli-templates/prompts/documentation/`
+
+## CLI Generate Mode Summary
+
+| Mode | CLI Placement | CLI MODE | Agent Role |
+|------|---------------|----------|------------|
+| **Default** | pre_analysis | analysis | Generates documentation files |
+| **--cli-generate** | implementation_approach | write | Validates and coordinates CLI output |
+
+## Related Commands
+- `/workflow:execute` - Execute documentation tasks
+- `/workflow:status` - View task progress
+- `/workflow:session:complete` - Mark session complete

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

@@ -0,0 +1,330 @@
+---
+name: update-full
+description: Complete project-wide CLAUDE.md documentation update
+argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
+---
+
+# Full Documentation Update (/memory:update-full)
+
+## Coordinator Role
+
+**This command orchestrates project-wide CLAUDE.md updates** using depth-parallel execution strategy with intelligent complexity detection.
+
+**Execution Model**:
+
+1. **Initial Analysis**: Cache git changes, discover module structure
+2. **Complexity Detection**: Analyze module count, determine strategy
+3. **Plan Presentation**: Show user exactly what will be updated
+4. **Depth-Parallel Execution**: Update modules by depth (highest to lowest)
+5. **Safety Verification**: Ensure only CLAUDE.md files modified
+
+**Tool Selection**:
+- `--tool gemini` (default): Documentation generation, pattern recognition
+- `--tool qwen`: Architecture analysis, system design docs
+- `--tool codex`: Implementation validation, code quality analysis
+
+**Path Parameter**:
+- `--path <directory>` (optional): Target specific directory for updates
+- If not specified: Updates entire project from current directory
+- If specified: Changes to target directory before discovery
+
+## Core Rules
+
+1. **Analyze First**: Run git cache and module discovery before any updates
+2. **Scope Control**: Use --path to target specific directories, default is entire project
+3. **Wait for Approval**: Present plan, no execution without user confirmation
+4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
+5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
+6. **Independent Commands**: Each update is a separate bash() call
+7. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
+
+## Execution Workflow
+
+### Phase 1: Discovery & Analysis
+
+**Cache git changes:**
+```bash
+bash(git add -A 2>/dev/null || true)
+```
+
+**Get module structure:**
+
+*If no --path parameter:*
+```bash
+bash(~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+*If --path parameter specified:*
+```bash
+bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+**Example with path:**
+```bash
+# Update only .claude directory
+bash(cd .claude && ~/.claude/scripts/get_modules_by_depth.sh list)
+
+# Update specific feature directory
+bash(cd src/features/auth && ~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+**Parse Output**:
+- Extract module paths from `depth:N|path:<PATH>|...` format
+- Count total modules
+- Identify which modules have/need CLAUDE.md
+
+**Example output:**
+```
+depth:5|path:./.claude/workflows/cli-templates/prompts/analysis|files:5|has_claude:no
+depth:4|path:./.claude/commands/cli/mode|files:3|has_claude:no
+depth:3|path:./.claude/commands/cli|files:6|has_claude:no
+depth:0|path:.|files:14|has_claude:yes
+```
+
+**Validation**:
+- If --path specified, directory exists and is accessible
+- Module list contains depth and path information
+- At least one module exists
+- All paths are relative to target directory (if --path used)
+
+---
+
+### Phase 2: Plan Presentation
+
+**Decision Logic**:
+- **Simple projects (≤20 modules)**: Present plan to user, wait for approval
+- **Complex projects (>20 modules)**: Delegate to memory-bridge agent
+
+**Plan format:**
+```
+📋 Update Plan:
+  Tool: gemini
+  Total modules: 31
+
+  NEW CLAUDE.md files (30):
+    - ./.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
+    - ./.claude/commands/cli/mode/CLAUDE.md
+    - ... (28 more)
+
+  UPDATE existing CLAUDE.md files (1):
+    - ./CLAUDE.md
+
+  ⚠️ Confirm execution? (y/n)
+```
+
+**User Confirmation Required**: No execution without explicit approval
+
+---
+
+### Phase 3: Depth-Parallel Execution
+
+**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
+
+**Command structure:**
+```bash
+bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
+```
+
+**Example - Depth 5 (8 modules):**
+```bash
+bash(cd ./.claude/workflows/cli-templates/prompts/analysis && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+```bash
+bash(cd ./.claude/workflows/cli-templates/prompts/development && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+```bash
+bash(cd ./.claude/workflows/cli-templates/prompts/documentation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+```bash
+bash(cd ./.claude/workflows/cli-templates/prompts/implementation && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+
+*Wait for depth 5 completion...*
+
+**Example - Depth 4 (7 modules):**
+```bash
+bash(cd ./.claude/commands/cli/mode && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+```bash
+bash(cd ./.claude/commands/workflow/brainstorm && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+
+*Continue for remaining depths (3 → 2 → 1 → 0)...*
+
+**Execution Rules**:
+- Each command is separate bash() call
+- Up to 4 concurrent jobs per depth
+- Wait for all jobs in current depth before proceeding
+- Extract path from `depth:N|path:<PATH>|...` format
+- All paths relative to target directory (current dir or --path value)
+
+**Path Context**:
+- Without --path: Paths relative to current directory
+- With --path: Paths relative to specified target directory
+- Module discovery runs in target directory context
+
+---
+
+### Phase 4: Safety Verification
+
+**Check modified files:**
+```bash
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
+```
+
+**Expected output:**
+```
+✅ Only CLAUDE.md files modified
+```
+
+**If non-CLAUDE.md files detected:**
+```
+⚠️ Warning: Non-CLAUDE.md files were modified
+Modified files: src/index.ts, package.json
+→ Run: git restore --staged .
+```
+
+**Display final status:**
+```bash
+bash(git status --short)
+```
+
+**Example output:**
+```
+A  .claude/workflows/cli-templates/prompts/analysis/CLAUDE.md
+A  .claude/commands/cli/mode/CLAUDE.md
+M  CLAUDE.md
+... (30 more files)
+```
+
+## Command Pattern Reference
+
+**Single module update:**
+```bash
+bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "full" "<tool>" &)
+```
+
+**Components**:
+- `cd <module-path>` - Navigate to module (from `path:` field)
+- `&&` - Ensure cd succeeds
+- `update_module_claude.sh` - Update script
+- `"."` - Current directory
+- `"full"` - Full update mode
+- `"<tool>"` - gemini/qwen/codex
+- `&` - Background execution
+
+**Path extraction:**
+```bash
+# From: depth:5|path:./src/auth|files:10|has_claude:no
+# Extract: ./src/auth
+# Command: bash(cd ./src/auth && ~/.claude/scripts/update_module_claude.sh "." "full" "gemini" &)
+```
+
+## Complex Projects Strategy
+
+For projects >20 modules, delegate to memory-bridge agent:
+
+```javascript
+Task(
+  subagent_type="memory-bridge",
+  description="Complex project full update",
+  prompt=`
+CONTEXT:
+- Total modules: ${module_count}
+- Tool: ${tool}
+- Mode: full
+
+MODULE LIST:
+${modules_output}
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level
+2. Process depths N→0 sequentially, max 4 parallel per depth
+3. Command: cd "<path>" && update_module_claude.sh "." "full" "${tool}" &
+4. Extract path from "depth:N|path:<PATH>|..." format
+5. Verify all modules processed
+6. Run safety check
+7. Display git status
+`
+)
+```
+
+## Error Handling
+
+- **Invalid path parameter**: Report error if --path directory doesn't exist, abort execution
+- **Module discovery failure**: Report error, abort execution
+- **User declines approval**: Abort execution, no changes made
+- **Safety check failure**: Automatic staging revert, report modified files
+- **Update script failure**: Report failed modules, continue with remaining
+
+## Coordinator Checklist
+
+✅ Parse `--tool` parameter (default: gemini)
+✅ Parse `--path` parameter (optional, default: current directory)
+✅ Execute git cache in current directory
+✅ Execute module discovery (with cd if --path specified)
+✅ Parse module list, count total modules
+✅ Determine strategy based on module count (≤20 vs >20)
+✅ Present plan with exact file paths
+✅ **Wait for user confirmation** (simple projects only)
+✅ Organize modules by depth
+✅ For each depth (highest to lowest):
+  - Launch up to 5 parallel updates
+  - Wait for depth completion
+  - Proceed to next depth
+✅ Run safety check after all updates
+✅ Display git status
+✅ Report completion summary
+
+
+
+## Tool Parameter Reference
+
+**Gemini** (default):
+- Best for: Documentation generation, pattern recognition, architecture review
+- Context window: Large, handles complex codebases
+- Output style: Comprehensive, detailed explanations
+
+**Qwen**:
+- Best for: Architecture analysis, system design documentation
+- Context window: Large, similar to Gemini
+- Output style: Structured, systematic analysis
+
+**Codex**:
+- Best for: Implementation validation, code quality analysis
+- Capabilities: Mathematical reasoning, autonomous development
+- Output style: Technical, implementation-focused
+
+## Path Parameter Reference
+
+**Use Cases**:
+
+**Update configuration directory only:**
+```bash
+/memory:update-full --path .claude
+```
+- Updates only .claude directory and subdirectories
+- Useful after workflow or command modifications
+- Faster than full project update
+
+**Update specific feature module:**
+```bash
+/memory:update-full --path src/features/auth
+```
+- Updates authentication feature and sub-modules
+- Ideal for feature-specific documentation
+- Isolates scope for targeted updates
+
+**Update nested structure:**
+```bash
+/memory:update-full --path .claude/workflows/cli-templates
+```
+- Updates deeply nested directory tree
+- Maintains relative path structure in output
+- All module paths relative to specified directory
+
+**Best Practices**:
+- Use `--path` when working on specific features/modules
+- Omit `--path` for project-wide architectural changes
+- Combine with `--tool` for specialized documentation needs
+- Verify directory exists before execution (automatic validation)

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

@@ -0,0 +1,306 @@
+---
+name: update-related
+description: Context-aware CLAUDE.md documentation updates based on recent changes
+argument-hint: "[--tool gemini|qwen|codex]"
+---
+
+# Related Documentation Update (/memory:update-related)
+
+## Coordinator Role
+
+**This command orchestrates context-aware CLAUDE.md updates** for modules affected by recent changes using intelligent change detection.
+
+**Execution Model**:
+
+1. **Change Detection**: Analyze git changes to identify affected modules
+2. **Complexity Analysis**: Evaluate change count and determine strategy
+3. **Plan Presentation**: Show user which modules need updates
+4. **Depth-Parallel Execution**: Update affected modules by depth (highest to lowest)
+5. **Safety Verification**: Ensure only CLAUDE.md files modified
+
+**Tool Selection**:
+- `--tool gemini` (default): Documentation generation, pattern recognition
+- `--tool qwen`: Architecture analysis, system design docs
+- `--tool codex`: Implementation validation, code quality analysis
+
+## Core Rules
+
+1. **Detect Changes First**: Use git diff to identify affected modules before updates
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Related Mode**: Update only changed modules and their parent contexts
+4. **Depth-Parallel**: Same depth runs parallel (max 4 jobs), different depths sequential
+5. **Safety Check**: Verify only CLAUDE.md files modified, revert if source files touched
+6. **No Background Bash Tool**: Never use `run_in_background` parameter in bash() calls; use shell `&` for parallelism
+
+## Execution Workflow
+
+### Phase 1: Change Detection & Analysis
+
+**Refresh code index:**
+```bash
+bash(mcp__code-index__refresh_index)
+```
+
+**Detect changed modules:**
+```bash
+bash(~/.claude/scripts/detect_changed_modules.sh list)
+```
+
+**Cache git changes:**
+```bash
+bash(git add -A 2>/dev/null || true)
+```
+
+**Parse Output**:
+- Extract changed module paths from `depth:N|path:<PATH>|...` format
+- Count affected modules
+- Identify which modules have/need CLAUDE.md updates
+
+**Example output:**
+```
+depth:3|path:./src/api/auth|files:5|types:[ts]|has_claude:no|change:new
+depth:2|path:./src/api|files:12|types:[ts]|has_claude:yes|change:modified
+depth:1|path:./src|files:8|types:[ts]|has_claude:yes|change:parent
+depth:0|path:.|files:14|has_claude:yes|change:parent
+```
+
+**Fallback behavior**:
+- If no git changes detected, use recent modules (first 10 by depth)
+
+**Validation**:
+- Changed module list contains valid paths
+- At least one affected module exists
+
+---
+
+### Phase 2: Plan Presentation
+
+**Decision Logic**:
+- **Simple changes (≤15 modules)**: Present plan to user, wait for approval
+- **Complex changes (>15 modules)**: Delegate to memory-bridge agent
+
+**Plan format:**
+```
+📋 Related Update Plan:
+  Tool: gemini
+  Changed modules: 4
+
+  NEW CLAUDE.md files (1):
+    - ./src/api/auth/CLAUDE.md [new module]
+
+  UPDATE existing CLAUDE.md files (3):
+    - ./src/api/CLAUDE.md [parent of changed auth/]
+    - ./src/CLAUDE.md [parent context]
+    - ./CLAUDE.md [root level]
+
+  ⚠️ Confirm execution? (y/n)
+```
+
+**User Confirmation Required**: No execution without explicit approval
+
+---
+
+### Phase 3: Depth-Parallel Execution
+
+**Pattern**: Process highest depth first, parallel within depth, sequential across depths.
+
+**Command structure:**
+```bash
+bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
+```
+
+**Example - Depth 3 (new module):**
+```bash
+bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
+```
+
+*Wait for depth 3 completion...*
+
+**Example - Depth 2 (modified parent):**
+```bash
+bash(cd ./src/api && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
+```
+
+*Wait for depth 2 completion...*
+
+**Example - Depth 1 & 0 (parent contexts):**
+```bash
+bash(cd ./src && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
+```
+```bash
+bash(cd . && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
+```
+
+*Wait for all depths completion...*
+
+**Execution Rules**:
+- Each command is separate bash() call
+- Up to 4 concurrent jobs per depth
+- Wait for all jobs in current depth before proceeding
+- Use "related" mode (not "full") for context-aware updates
+- Extract path from `depth:N|path:<PATH>|...` format
+
+**Related Mode Behavior**:
+- Updates module based on recent git changes
+- Includes parent context for better documentation coherence
+- More efficient than full updates for iterative development
+
+---
+
+### Phase 4: Safety Verification
+
+**Check modified files:**
+```bash
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Only CLAUDE.md files modified")
+```
+
+**Expected output:**
+```
+✅ Only CLAUDE.md files modified
+```
+
+**If non-CLAUDE.md files detected:**
+```
+⚠️ Warning: Non-CLAUDE.md files were modified
+Modified files: src/api/auth/index.ts, package.json
+→ Run: git restore --staged .
+```
+
+**Display final statistics:**
+```bash
+bash(git diff --stat)
+```
+
+**Example output:**
+```
+.claude/workflows/cli-templates/prompts/analysis/CLAUDE.md | 45 +++++++++++++++++++++
+src/api/CLAUDE.md                                          | 23 +++++++++--
+src/CLAUDE.md                                              | 12 ++++--
+CLAUDE.md                                                  | 8 ++--
+4 files changed, 82 insertions(+), 6 deletions(-)
+```
+
+## Command Pattern Reference
+
+**Single module update:**
+```bash
+bash(cd <module-path> && ~/.claude/scripts/update_module_claude.sh "." "related" "<tool>" &)
+```
+
+**Components**:
+- `cd <module-path>` - Navigate to module (from `path:` field)
+- `&&` - Ensure cd succeeds
+- `update_module_claude.sh` - Update script
+- `"."` - Current directory
+- `"related"` - Related mode (context-aware, change-based)
+- `"<tool>"` - gemini/qwen/codex
+- `&` - Background execution
+
+**Path extraction:**
+```bash
+# From: depth:3|path:./src/api/auth|files:5|change:new|has_claude:no
+# Extract: ./src/api/auth
+# Command: bash(cd ./src/api/auth && ~/.claude/scripts/update_module_claude.sh "." "related" "gemini" &)
+```
+
+**Mode comparison:**
+- `"full"` - Complete module documentation regeneration
+- `"related"` - Context-aware update based on recent changes (faster)
+
+## Complex Changes Strategy
+
+For changes affecting >15 modules, delegate to memory-bridge agent:
+
+```javascript
+Task(
+  subagent_type="memory-bridge",
+  description="Complex project related update",
+  prompt=`
+CONTEXT:
+- Total modules: ${change_count}
+- Tool: ${tool}
+- Mode: related
+
+MODULE LIST:
+${changed_modules_output}
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level
+2. Process depths N→0 sequentially, max 4 parallel per depth
+3. Command: cd "<path>" && update_module_claude.sh "." "related" "${tool}" &
+4. Extract path from "depth:N|path:<PATH>|..." format
+5. Verify all ${change_count} modules processed
+6. Run safety check
+7. Display git diff --stat
+`
+)
+```
+
+## Error Handling
+
+- **No changes detected**: Use fallback mode (recent 10 modules)
+- **Change detection failure**: Report error, abort execution
+- **User declines approval**: Abort execution, no changes made
+- **Safety check failure**: Automatic staging revert, report modified files
+- **Update script failure**: Report failed modules, continue with remaining
+
+## Coordinator Checklist
+
+✅ Parse `--tool` parameter (default: gemini)
+✅ Refresh code index for accurate change detection
+✅ Detect changed modules via detect_changed_modules.sh
+✅ Cache git changes to protect current state
+✅ Parse changed module list, count affected modules
+✅ Apply fallback if no changes detected (recent 10 modules)
+✅ Determine strategy based on change count (≤15 vs >15)
+✅ Present plan with exact file paths and change types
+✅ **Wait for user confirmation** (simple changes only)
+✅ Organize modules by depth
+✅ For each depth (highest to lowest):
+  - Launch up to 4 parallel updates with "related" mode
+  - Wait for depth completion
+  - Proceed to next depth
+✅ Run safety check after all updates
+✅ Display git diff statistics
+✅ Report completion summary
+
+## Usage Examples
+
+```bash
+# Daily development update (default: gemini)
+/memory:update-related
+
+# After feature work with specific tool
+/memory:update-related --tool qwen
+
+# Code quality review after implementation
+/memory:update-related --tool codex
+```
+
+## Tool Parameter Reference
+
+**Gemini** (default):
+- Best for: Documentation generation, pattern recognition
+- Use case: Daily development updates, feature documentation
+- Output style: Comprehensive, contextual explanations
+
+**Qwen**:
+- Best for: Architecture analysis, system design
+- Use case: Structural changes, API design updates
+- Output style: Structured, systematic documentation
+
+**Codex**:
+- Best for: Implementation validation, code quality
+- Use case: After implementation, refactoring work
+- Output style: Technical, implementation-focused
+
+## Comparison with Full Update
+
+| Aspect | Related Update | Full Update |
+|--------|----------------|-------------|
+| **Scope** | Changed modules only | All project modules |
+| **Speed** | Fast (minutes) | Slower (10-30 min) |
+| **Use case** | Daily development | Major refactoring |
+| **Mode** | `"related"` | `"full"` |
+| **Trigger** | After commits | After major changes |
+| **Complexity threshold** | ≤15 modules | ≤20 modules |

.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,179 +0,0 @@
----
-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`
-
-Complete project-wide documentation update using depth-parallel execution.
-
-**Tool Selection**:
-- **Gemini (default)**: Documentation generation, pattern recognition, architecture review
-- **Qwen**: Architecture analysis, system design documentation
-- **Codex**: Implementation validation, code quality analysis
-
-### 📝 Execution Template
-
-```bash
-#!/bin/bash
-# Complete project-wide CLAUDE.md documentation update
-
-# Step 1: Parse tool selection (default: gemini)
-tool="gemini"
-[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
-[[ "$*" == *"--tool codex"* ]] && tool="codex"
-
-# Step 2: Code Index architecture analysis
-mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
-mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}")
-
-# Step 3: Cache git changes
-Bash(git add -A 2>/dev/null || true)
-
-# Step 4: Get and display project structure
-modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
-count=$(echo "$modules" | wc -l)
-
-# Step 5: Analysis handover → Model takes control
-# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
-
-# Pseudocode flow:
-# IF (module_count > 20 OR complex_project_detected):
-#     → Task "Complex project full update" subagent_type: "memory-gemini-bridge"
-# ELSE:
-#     → Present plan and WAIT FOR USER APPROVAL before execution
-#
-# Pass tool parameter to update_module_claude.sh: "$tool"
-```
-
-### 🧠 Model Analysis Phase
-
-After the bash script completes the initial analysis, the model takes control to:
-
-1. **Analyze Complexity**: Review module count and project context
-2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files
-3. **Choose Strategy**:
-   - Simple projects: Present execution plan with CLAUDE.md paths to user
-   - Complex projects: Delegate to memory-gemini-bridge agent
-4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated
-5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
-
-### 📋 Execution Strategies
-
-**For Simple Projects (≤20 modules):**
-
-Model will present detailed plan:
-```
-📋 Update Plan:
-  Tool: [gemini|qwen|codex] (from --tool parameter)
-
-  NEW CLAUDE.md files (X):
-    - ./src/components/CLAUDE.md
-    - ./src/services/CLAUDE.md
-
-  UPDATE existing CLAUDE.md files (Y):
-    - ./CLAUDE.md
-    - ./src/CLAUDE.md
-    - ./tests/CLAUDE.md
-
-  Total: N CLAUDE.md files will be processed
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-```pseudo
-# ⚠️ MANDATORY: User confirmation → MUST await explicit approval  
-IF user_explicitly_confirms():
-    continue_execution()
-ELSE:
-    abort_execution()
-
-# Step 4: Organize modules by depth → Prepare execution
-depth_modules = organize_by_depth(modules)
-
-# Step 5: Execute depth-parallel updates → Process by depth
-FOR depth FROM max_depth DOWN TO 0:
-    FOR each module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" "$tool" &)
-    wait_all_jobs()
-
-# Step 6: Safety check and restore staging state
-non_claude=$(Bash(git diff --cached --name-only | grep -v "CLAUDE.md" || true))
-if [ -n "$non_claude" ]; then
-    Bash(git restore --staged .)
-    echo "⚠️ Warning: Non-CLAUDE.md files were modified, staging reverted"
-    echo "Modified files: $non_claude"
-else
-    echo "✅ Only CLAUDE.md files modified, staging preserved"
-fi
-
-# Step 7: Display changes → Final status
-Bash(git status --short)
-```
-
-**For Complex Projects (>20 modules):**
-
-The model will delegate to the memory-gemini-bridge agent with structured context:
-
-```javascript
-Task "Complex project full update"
-subagent_type: "memory-gemini-bridge"
-prompt: `
-CONTEXT:
-- Total modules: ${module_count}
-- Tool: ${tool}  // from --tool parameter, default: gemini
-- Mode: full
-- Existing CLAUDE.md: ${existing_count}
-- New CLAUDE.md needed: ${new_count}
-
-MODULE LIST:
-${modules_output}  // Full output from get_modules_by_depth.sh list
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level before execution
-2. Process depths 5→0 sequentially, max 4 parallel jobs per depth
-3. Command format: update_module_claude.sh "<path>" "full" "${tool}" &
-4. Extract exact path from "depth:N|path:<PATH>|..." format
-5. Verify all ${module_count} modules are processed
-6. Run safety check after completion
-7. Display git status
-
-Execute depth-parallel updates for all modules.
-`
-```
-
-**Agent receives complete context:**
-- Module count and tool selection
-- Full structured module list
-- Clear execution requirements
-- Path extraction format
-- Success criteria
-
-
-### 📚 Usage Examples
-
-```bash
-# Complete project documentation refresh
-/update-memory-full
-
-# After major architectural changes
-/update-memory-full
-```
-
-### ✨ Features
-
-- **Separated Commands**: Each bash operation is a discrete, trackable step
-- **Intelligent Complexity Detection**: Model analyzes project context for optimal strategy
-- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially
-- **Git Integration**: Auto-cache changes before, safety check and show status after
-- **Safety Protection**: Automatic detection and revert of unintended source code modifications
-- **Module Detection**: Uses get_modules_by_depth.sh for structure discovery
-- **User Confirmation**: Clear plan presentation with approval step
-- **CLAUDE.md Only**: Only updates documentation, never source code

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

@@ -1,187 +0,0 @@
----
-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`
-
-Context-aware documentation update for modules affected by recent changes.
-
-**Tool Selection**:
-- **Gemini (default)**: Documentation generation, pattern recognition, architecture review
-- **Qwen**: Architecture analysis, system design documentation
-- **Codex**: Implementation validation, code quality analysis
-
-
-### 📝 Execution Template
-
-```bash
-#!/bin/bash
-# Context-aware CLAUDE.md documentation update
-
-# Step 1: Parse tool selection (default: gemini)
-tool="gemini"
-[[ "$*" == *"--tool qwen"* ]] && tool="qwen"
-[[ "$*" == *"--tool codex"* ]] && tool="codex"
-
-# Step 2: Code Index refresh and architecture analysis
-mcp__code-index__refresh_index()
-mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
-
-# Step 3: Detect changed modules (before staging)
-changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list))
-
-# Step 4: Cache git changes (protect current state)
-Bash(git add -A 2>/dev/null || true)
-
-# Step 5: Use detected changes or fallback
-if [ -z "$changed" ]; then
-    changed=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list | head -10))
-fi
-count=$(echo "$changed" | wc -l)
-
-# Step 6: Analysis handover → Model takes control
-# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
-
-# Pseudocode flow:
-# IF (change_count > 15 OR complex_changes_detected):
-#     → Task "Complex project related update" subagent_type: "memory-gemini-bridge"
-# ELSE:
-#     → Present plan and WAIT FOR USER APPROVAL before execution
-#
-# Pass tool parameter to update_module_claude.sh: "$tool"
-```
-
-### 🧠 Model Analysis Phase
-
-After the bash script completes change detection, the model takes control to:
-
-1. **Analyze Changes**: Review change count and complexity  
-2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files
-3. **Choose Strategy**: 
-   - Simple changes: Present execution plan with CLAUDE.md paths to user
-   - Complex changes: Delegate to memory-gemini-bridge agent
-4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules
-5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
-
-### 📋 Execution Strategies
-
-**For Simple Changes (≤15 modules):**
-
-Model will present detailed plan for affected modules:
-```
-📋 Related Update Plan:
-  Tool: [gemini|qwen|codex] (from --tool parameter)
-
-  CHANGED modules affecting CLAUDE.md:
-
-  NEW CLAUDE.md files (X):
-    - ./src/api/auth/CLAUDE.md  [new module]
-    - ./src/utils/helpers/CLAUDE.md  [new module]
-
-  UPDATE existing CLAUDE.md files (Y):
-    - ./src/api/CLAUDE.md  [parent of changed auth/]
-    - ./src/CLAUDE.md  [root level]
-
-  Total: N CLAUDE.md files will be processed for recent changes
-
-  ⚠️ Confirm execution? (y/n)
-```
-
-```pseudo
-# ⚠️ MANDATORY: User confirmation → MUST await explicit approval
-IF user_explicitly_confirms():
-    continue_execution()
-ELSE:
-    abort_execution()
-
-# Step 4: Organize modules by depth → Prepare execution
-depth_modules = organize_by_depth(changed_modules)
-
-# Step 5: Execute depth-parallel updates → Process by depth
-FOR depth FROM max_depth DOWN TO 0:
-    FOR each module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" "$tool" &)
-    wait_all_jobs()
-
-# Step 6: Safety check and restore staging state
-non_claude=$(Bash(git diff --cached --name-only | grep -v "CLAUDE.md" || true))
-if [ -n "$non_claude" ]; then
-    Bash(git restore --staged .)
-    echo "⚠️ Warning: Non-CLAUDE.md files were modified, staging reverted"
-    echo "Modified files: $non_claude"
-else
-    echo "✅ Only CLAUDE.md files modified, staging preserved"
-fi
-
-# Step 7: Display changes → Final status
-Bash(git diff --stat)
-```
-
-**For Complex Changes (>15 modules):**
-
-The model will delegate to the memory-gemini-bridge agent with structured context:
-
-```javascript
-Task "Complex project related update"
-subagent_type: "memory-gemini-bridge"
-prompt: `
-CONTEXT:
-- Total modules: ${change_count}
-- Tool: ${tool}  // from --tool parameter, default: gemini
-- Mode: related
-- Changed modules detected via: detect_changed_modules.sh
-- Existing CLAUDE.md: ${existing_count}
-- New CLAUDE.md needed: ${new_count}
-
-MODULE LIST:
-${changed_modules_output}  // Full output from detect_changed_modules.sh list
-
-REQUIREMENTS:
-1. Use TodoWrite to track each depth level before execution
-2. Process depths sequentially (deepest→shallowest), max 4 parallel jobs per depth
-3. Command format: update_module_claude.sh "<path>" "related" "${tool}" &
-4. Extract exact path from "depth:N|path:<PATH>|..." format
-5. Verify all ${change_count} modules are processed
-6. Run safety check after completion
-7. Display git diff --stat
-
-Execute depth-parallel updates for changed modules only.
-`
-```
-
-**Agent receives complete context:**
-- Changed module count and tool selection
-- Full structured module list (changed only)
-- Clear execution requirements with "related" mode
-- Path extraction format
-- Success criteria
-
-
-### 📚 Usage Examples
-
-```bash
-# Daily development update
-/update-memory-related
-
-# After feature work
-/update-memory-related
-```
-
-### ✨ Features
-
-- **Separated Commands**: Each bash operation is a discrete, trackable step
-- **Intelligent Change Analysis**: Model analyzes change complexity for optimal strategy
-- **Change Detection**: Automatically finds affected modules using git diff
-- **Depth-Parallel Execution**: Same depth modules run in parallel, depths run sequentially  
-- **Git Integration**: Auto-cache changes, show diff statistics after
-- **Fallback Mode**: Updates recent files when no git changes found
-- **User Confirmation**: Clear plan presentation with approval step
-- **CLAUDE.md Only**: Only updates documentation, never source code

.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

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

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

@@ -0,0 +1,585 @@
+---
+name: api-designer
+description: Generate or update api-designer/analysis.md addressing topic-framework discussion points
+argument-hint: "optional topic - uses existing framework if available"
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
+---
+
+## 🔌 **API Designer Analysis Generator**
+
+### Purpose
+**Specialized command for generating api-designer/analysis.md** that addresses topic-framework.md discussion points from backend API design perspective. Creates or updates role-specific analysis with framework references.
+
+### Core Function
+- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **API Design Focus**: RESTful/GraphQL API design, endpoint structure, and contract definition
+- **Update Mechanism**: Create new or update existing analysis.md
+- **Agent Delegation**: Use conceptual-planning-agent for analysis generation
+
+### Analysis Scope
+- **API Architecture**: RESTful/GraphQL design patterns and best practices
+- **Endpoint Design**: Resource modeling, URL structure, and HTTP method selection
+- **Data Contracts**: Request/response schemas, validation rules, and data transformation
+- **API Documentation**: OpenAPI/Swagger specifications and developer experience
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (API Contract Within Architectural Framework)**
+- **API Contract Definition**: Specific endpoint paths, HTTP methods, and status codes
+- **Resource Modeling**: Mapping domain entities to RESTful resources or GraphQL types
+- **Request/Response Schemas**: Detailed data contracts, validation rules, and error formats
+- **API Versioning Strategy**: Version management, deprecation policies, and migration paths
+- **Developer Experience**: API documentation (OpenAPI/Swagger), code examples, and SDKs
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **System Architecture Decisions**: Microservices vs monolithic, overall communication patterns → Defers to **System Architect**
+- **Canonical Data Model**: Underlying data schemas and entity relationships → Defers to **Data Architect**
+- **UI/Frontend Integration**: How clients consume the API → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **FROM System Architect**: Receives architectural constraints (REST vs GraphQL, sync vs async) that define the design space
+- **FROM Data Architect**: Receives canonical data model and translates it into public API data contracts (as projection/view)
+- **TO Frontend Teams**: Provides complete API specifications, documentation, and integration guides
+
+## ⚙️ **Execution Protocol**
+
+### Phase 1: Session & Framework Detection
+```bash
+# Check active session and framework
+CHECK: .workflow/.active-* marker files
+IF active_session EXISTS:
+    session_id = get_active_session()
+    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+
+    CHECK: brainstorm_dir/topic-framework.md
+    IF EXISTS:
+        framework_mode = true
+        load_framework = true
+    ELSE:
+        IF topic_provided:
+            framework_mode = false  # Create analysis without framework
+        ELSE:
+            ERROR: "No framework found and no topic provided"
+```
+
+### Phase 2: Analysis Mode Detection
+```bash
+# Check existing analysis
+CHECK: brainstorm_dir/api-designer/analysis.md
+IF EXISTS:
+    SHOW existing analysis summary
+    ASK: "Analysis exists. Do you want to:"
+    OPTIONS:
+      1. "Update with new insights" → Update existing
+      2. "Replace completely" → Generate new
+      3. "Cancel" → Exit without changes
+ELSE:
+    CREATE new analysis
+```
+
+### Phase 3: Agent Task Generation
+**Framework-Based Analysis** (when topic-framework.md exists):
+```bash
+Task(subagent_type="conceptual-planning-agent",
+     prompt="Generate API designer analysis addressing topic framework
+
+     ## Framework Integration Required
+     **MANDATORY**: Load and address topic-framework.md discussion points
+     **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+     **Output Location**: {session.brainstorm_dir}/api-designer/analysis.md
+
+     ## Analysis Requirements
+     1. **Load Topic Framework**: Read topic-framework.md completely
+     2. **Address Each Discussion Point**: Respond to all 5 framework sections from API design perspective
+     3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
+     4. **API Design Focus**: Emphasize endpoint structure, data contracts, versioning strategies
+     5. **Structured Response**: Use framework structure for analysis organization
+
+     ## Framework Sections to Address
+     - Core Requirements (from API design perspective)
+     - Technical Considerations (detailed API architecture analysis)
+     - User Experience Factors (developer experience and API usability)
+     - Implementation Challenges (API design risks and solutions)
+     - Success Metrics (API performance metrics and adoption tracking)
+
+     ## Output Structure Required
+     ```markdown
+     # API Designer Analysis: [Topic]
+
+     **Framework Reference**: @../topic-framework.md
+     **Role Focus**: Backend API Design and Contract Definition
+
+     ## Core Requirements Analysis
+     [Address framework requirements from API design perspective]
+
+     ## Technical Considerations
+     [Detailed API architecture and endpoint design analysis]
+
+     ## Developer Experience Factors
+     [API usability, documentation, and integration ease]
+
+     ## Implementation Challenges
+     [API design risks and mitigation strategies]
+
+     ## Success Metrics
+     [API performance metrics, adoption rates, and developer satisfaction]
+
+     ## API Design-Specific Recommendations
+     [Detailed API design recommendations and best practices]
+     ```",
+     description="Generate API designer framework-based analysis")
+```
+
+### Phase 4: Update Mechanism
+**Analysis Update Process**:
+```bash
+# For existing analysis updates
+IF update_mode = "incremental":
+    Task(subagent_type="conceptual-planning-agent",
+         prompt="Update existing API designer analysis
+
+         ## Current Analysis Context
+         **Existing Analysis**: @{session.brainstorm_dir}/api-designer/analysis.md
+         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+
+         ## Update Requirements
+         1. **Preserve Structure**: Maintain existing analysis structure
+         2. **Add New Insights**: Integrate new API design insights and recommendations
+         3. **Framework Alignment**: Ensure continued alignment with topic framework
+         4. **API Updates**: Add new endpoint patterns, versioning strategies, documentation improvements
+         5. **Maintain References**: Keep @../topic-framework.md reference
+
+         ## Update Instructions
+         - Read existing analysis completely
+         - Identify areas for enhancement or new insights
+         - Add API design depth while preserving original structure
+         - Update recommendations with new API design patterns and approaches
+         - Maintain framework discussion point addressing",
+         description="Update API designer analysis incrementally")
+```
+
+## Document Structure
+
+### Output Files
+```
+.workflow/WFS-[topic]/.brainstorming/
+├── topic-framework.md          # Input: Framework (if exists)
+└── api-designer/
+    └── analysis.md            # ★ OUTPUT: Framework-based analysis
+```
+
+### Analysis Structure
+**Required Elements**:
+- **Framework Reference**: @../topic-framework.md (if framework exists)
+- **Role Focus**: Backend API Design and Contract Definition perspective
+- **5 Framework Sections**: Address each framework discussion point
+- **API Design Recommendations**: Endpoint-specific insights and solutions
+
+## ⚡ **Two-Step Execution Flow**
+
+### ⚠️ Session Management - FIRST STEP
+Session detection and selection:
+```bash
+# Check for active sessions
+active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
+if [ multiple_sessions ]; then
+  prompt_user_to_select_session()
+else
+  use_existing_or_create_new()
+fi
+```
+
+### Step 1: Context Gathering Phase
+**API Designer Perspective Questioning**
+
+Before agent assignment, gather comprehensive API design context:
+
+#### 📋 Role-Specific Questions
+1. **API Type & Architecture**
+   - RESTful, GraphQL, or hybrid API approach?
+   - Synchronous vs asynchronous communication patterns?
+   - Real-time requirements (WebSocket, Server-Sent Events)?
+
+2. **Resource Modeling & Endpoints**
+   - What are the core domain resources/entities?
+   - Expected CRUD operations for each resource?
+   - Complex query requirements (filtering, sorting, pagination)?
+
+3. **Data Contracts & Validation**
+   - Request/response data format requirements (JSON, XML, Protocol Buffers)?
+   - Input validation and sanitization requirements?
+   - Data transformation and mapping needs?
+
+4. **API Management & Governance**
+   - API versioning strategy requirements?
+   - Authentication and authorization mechanisms?
+   - Rate limiting and throttling requirements?
+   - API documentation and developer portal needs?
+
+5. **Integration & Compatibility**
+   - Client platforms consuming the API (web, mobile, third-party)?
+   - Backward compatibility requirements?
+   - External API integrations needed?
+
+#### Context Validation
+- **Minimum Response**: Each answer must be ≥50 characters
+- **Re-prompting**: Insufficient detail triggers follow-up questions
+- **Context Storage**: Save responses to `.brainstorming/api-designer-context.md`
+
+### Step 2: Agent Assignment with Flow Control
+**Dedicated Agent Execution**
+
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute dedicated api-designer conceptual analysis for: {topic}
+
+ASSIGNED_ROLE: api-designer
+OUTPUT_LOCATION: .brainstorming/api-designer/
+USER_CONTEXT: {validated_responses_from_context_gathering}
+
+Flow Control Steps:
+[
+  {
+    \"step\": \"load_role_template\",
+    \"action\": \"Load api-designer planning template\",
+    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/api-designer.md))\",
+    \"output_to\": \"role_template\"
+  }
+]
+
+Conceptual Analysis Requirements:
+- Apply api-designer perspective to topic analysis
+- Focus on endpoint design, data contracts, and API governance
+- Use loaded role template framework for analysis structure
+- Generate role-specific deliverables in designated output location
+- Address all user context from questioning phase
+
+Deliverables:
+- analysis.md: Main API design analysis
+- api-specification.md: Detailed endpoint specifications
+- data-contracts.md: Request/response schemas and validation rules
+- api-documentation.md: API documentation strategy and templates
+
+Embody api-designer role expertise for comprehensive conceptual planning."
+```
+
+### Progress Tracking
+TodoWrite tracking for two-step process:
+```json
+[
+  {"content": "Gather API designer context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
+  {"content": "Validate context responses and save to api-designer-context.md", "status": "pending", "activeForm": "Validating context"},
+  {"content": "Load api-designer planning template via flow control", "status": "pending", "activeForm": "Loading template"},
+  {"content": "Execute dedicated conceptual-planning-agent for api-designer role", "status": "pending", "activeForm": "Executing agent"}
+]
+```
+
+## 📊 **Output Specification**
+
+### Output Location
+```
+.workflow/WFS-{topic-slug}/.brainstorming/api-designer/
+├── analysis.md                 # Primary API design analysis
+├── api-specification.md        # Detailed endpoint specifications (OpenAPI/Swagger)
+├── data-contracts.md           # Request/response schemas and validation rules
+├── versioning-strategy.md      # API versioning and backward compatibility plan
+└── developer-guide.md          # API usage documentation and integration examples
+```
+
+### Document Templates
+
+#### analysis.md Structure
+```markdown
+# API Design Analysis: {Topic}
+*Generated: {timestamp}*
+
+## Executive Summary
+[Key API design findings and recommendations overview]
+
+## API Architecture Overview
+### API Type Selection (REST/GraphQL/Hybrid)
+### Communication Patterns
+### Authentication & Authorization Strategy
+
+## Resource Modeling
+### Core Domain Resources
+### Resource Relationships
+### URL Structure and Naming Conventions
+
+## Endpoint Design
+### Resource Endpoints
+- GET /api/v1/resources
+- POST /api/v1/resources
+- GET /api/v1/resources/{id}
+- PUT /api/v1/resources/{id}
+- DELETE /api/v1/resources/{id}
+
+### Query Parameters
+- Filtering: ?filter[field]=value
+- Sorting: ?sort=field,-field2
+- Pagination: ?page=1&limit=20
+
+### HTTP Methods and Status Codes
+- Success responses (2xx)
+- Client errors (4xx)
+- Server errors (5xx)
+
+## Data Contracts
+### Request Schemas
+[JSON Schema or OpenAPI definitions]
+
+### Response Schemas
+[JSON Schema or OpenAPI definitions]
+
+### Validation Rules
+- Required fields
+- Data types and formats
+- Business logic constraints
+
+## API Versioning Strategy
+### Versioning Approach (URL/Header/Accept)
+### Version Lifecycle Management
+### Deprecation Policy
+### Migration Paths
+
+## Security & Governance
+### Authentication Mechanisms
+- OAuth 2.0 / JWT / API Keys
+### Authorization Patterns
+- RBAC / ABAC / Resource-based
+### Rate Limiting & Throttling
+### CORS and Security Headers
+
+## Error Handling
+### Standard Error Response Format
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable error message",
+    "details": [],
+    "trace_id": "uuid"
+  }
+}
+```
+
+### Error Code Taxonomy
+### Validation Error Responses
+
+## API Documentation
+### OpenAPI/Swagger Specification
+### Developer Portal Requirements
+### Code Examples and SDKs
+### Changelog and Migration Guides
+
+## Performance Optimization
+### Response Caching Strategies
+### Compression (gzip, brotli)
+### Field Selection (sparse fieldsets)
+### Bulk Operations and Batch Endpoints
+
+## Monitoring & Observability
+### API Metrics
+- Request count, latency, error rates
+- Endpoint usage analytics
+### Logging Strategy
+### Distributed Tracing
+
+## Developer Experience
+### API Usability Assessment
+### Integration Complexity
+### SDK and Client Library Needs
+### Sandbox and Testing Environments
+```
+
+#### api-specification.md Structure
+```markdown
+# API Specification: {Topic}
+*OpenAPI 3.0 Specification*
+
+## API Information
+- **Title**: {API Name}
+- **Version**: 1.0.0
+- **Base URL**: https://api.example.com/v1
+- **Contact**: api-team@example.com
+
+## Endpoints
+
+### Users API
+
+#### GET /users
+**Description**: Retrieve a list of users
+
+**Parameters**:
+- `page` (query, integer): Page number (default: 1)
+- `limit` (query, integer): Items per page (default: 20, max: 100)
+- `sort` (query, string): Sort field (e.g., "created_at", "-updated_at")
+- `filter[status]` (query, string): Filter by user status
+
+**Response 200**:
+```json
+{
+  "data": [
+    {
+      "id": "uuid",
+      "username": "string",
+      "email": "string",
+      "created_at": "2025-10-15T00:00:00Z"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100
+  },
+  "links": {
+    "self": "/users?page=1",
+    "next": "/users?page=2",
+    "prev": null
+  }
+}
+```
+
+#### POST /users
+**Description**: Create a new user
+
+**Request Body**:
+```json
+{
+  "username": "string (required, 3-50 chars)",
+  "email": "string (required, valid email)",
+  "password": "string (required, min 8 chars)",
+  "profile": {
+    "first_name": "string (optional)",
+    "last_name": "string (optional)"
+  }
+}
+```
+
+**Response 201**:
+```json
+{
+  "data": {
+    "id": "uuid",
+    "username": "string",
+    "email": "string",
+    "created_at": "2025-10-15T00:00:00Z"
+  }
+}
+```
+
+**Response 400** (Validation Error):
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Request validation failed",
+    "details": [
+      {
+        "field": "email",
+        "message": "Invalid email format"
+      }
+    ]
+  }
+}
+```
+
+[Continue for all endpoints...]
+
+## Authentication
+
+### OAuth 2.0 Flow
+1. Client requests authorization
+2. User grants permission
+3. Client receives access token
+4. Client uses token in requests
+
+**Header Format**:
+```
+Authorization: Bearer {access_token}
+```
+
+## Rate Limiting
+
+**Headers**:
+- `X-RateLimit-Limit`: 1000
+- `X-RateLimit-Remaining`: 999
+- `X-RateLimit-Reset`: 1634270400
+
+**Response 429** (Too Many Requests):
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "API rate limit exceeded",
+    "retry_after": 3600
+  }
+}
+```
+```
+
+## 🔄 **Session Integration**
+
+### Status Synchronization
+Upon completion, update `workflow-session.json`:
+```json
+{
+  "phases": {
+    "BRAINSTORM": {
+      "api_designer": {
+        "status": "completed",
+        "completed_at": "timestamp",
+        "output_directory": ".workflow/WFS-{topic}/.brainstorming/api-designer/",
+        "key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
+      }
+    }
+  }
+}
+```
+
+### Cross-Role Collaboration
+API designer perspective provides:
+- **API Contract Specifications** → Frontend Developer
+- **Data Schema Requirements** → Data Architect
+- **Security Requirements** → Security Expert
+- **Integration Endpoints** → System Architect
+- **Performance Constraints** → DevOps Engineer
+
+## ✅ **Quality Assurance**
+
+### Required Analysis Elements
+- [ ] Complete endpoint inventory with HTTP methods and paths
+- [ ] Detailed request/response schemas with validation rules
+- [ ] Clear versioning strategy and backward compatibility plan
+- [ ] Comprehensive error handling and status code usage
+- [ ] API documentation strategy (OpenAPI/Swagger)
+
+### API Design Principles
+- [ ] **Consistency**: Uniform naming conventions and patterns across all endpoints
+- [ ] **Simplicity**: Intuitive resource modeling and URL structures
+- [ ] **Flexibility**: Support for filtering, sorting, pagination, and field selection
+- [ ] **Security**: Proper authentication, authorization, and input validation
+- [ ] **Performance**: Caching strategies, compression, and efficient data structures
+
+### Developer Experience Validation
+- [ ] API is self-documenting with clear endpoint descriptions
+- [ ] Error messages are actionable and helpful for debugging
+- [ ] Response formats are consistent and predictable
+- [ ] Code examples and integration guides are provided
+- [ ] Sandbox environment available for testing
+
+### Technical Completeness
+- [ ] **Resource Modeling**: All domain entities mapped to API resources
+- [ ] **CRUD Coverage**: Complete create, read, update, delete operations
+- [ ] **Query Capabilities**: Advanced filtering, sorting, and search functionality
+- [ ] **Versioning**: Clear version management and migration paths
+- [ ] **Monitoring**: API metrics, logging, and tracing strategies defined
+
+### Integration Readiness
+- [ ] **Client Compatibility**: API works with all target client platforms
+- [ ] **External Integration**: Third-party API dependencies identified
+- [ ] **Backward Compatibility**: Changes don't break existing clients
+- [ ] **Migration Path**: Clear upgrade paths for API consumers
+- [ ] **SDK Support**: Client libraries and code generation considered

.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(*)
 ---
 
@@ -19,6 +14,7 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 ## Role Selection Logic
 - **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert, subject-matter-expert
+- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
 - **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, user-researcher, product-manager, ux-expert, product-owner
 - **Business & Process**: `business|process|workflow|cost|innovation|testing` → business-analyst, innovation-lead, test-strategist
 - **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
@@ -28,7 +24,7 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 **Template Loading**: `bash($(cat "~/.claude/workflows/cli-templates/planning-roles/<role-name>.md"))`
 **Template Source**: `.claude/workflows/cli-templates/planning-roles/`
-**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
+**Available Roles**: api-designer, data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
 **Example**:
 ```bash
@@ -75,6 +71,7 @@ Auto command coordinates independent specialized commands:
 
 **Role Selection Logic**:
 - **Technical**: `architecture|system|performance|database` → system-architect, data-architect, subject-matter-expert
+- **API & Backend**: `api|endpoint|rest|graphql|backend|interface|contract|service` → api-designer, system-architect, data-architect
 - **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, ux-expert, product-manager, product-owner
 - **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
 - **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
@@ -327,4 +324,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,258 +0,0 @@
----
-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(*)
----
-
-# Workflow Brainstorm Auto-Squeeze Command
-
-## Coordinator Role
-
-**This command is a pure orchestrator**: Execute brainstorming commands in sequence (artifacts → roles → synthesis), auto-select relevant roles, and ensure complete brainstorming workflow execution.
-
-**Execution Flow**:
-1. Initialize TodoWrite → Execute Phase 1 (artifacts) → Validate framework → Update TodoWrite
-2. Select 2-3 relevant roles → Display selection → Execute Phase 2 (role analyses) → Update TodoWrite
-3. Execute Phase 3 (synthesis) → Validate outputs → Return summary
-
-## Core Rules
-
-1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
-2. **Auto-Select Roles**: Analyze topic keywords to select 2-3 most relevant roles (max 3)
-3. **Display Selection**: Show selected roles to user before execution
-4. **Sequential Execution**: Execute role commands one by one, not in parallel
-5. **Complete All Phases**: Do not return to user until synthesis completes
-6. **Track Progress**: Update TodoWrite after every command completion
-
-## 3-Phase Execution
-
-### Phase 1: Framework Generation
-
-**Step 1.1: Role Selection**
-Auto-select 2-3 roles based on topic keywords (see Role Selection Logic below)
-
-**Step 1.2: Generate Role-Specific Framework**
-**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"[topic]\" --roles \"[role1,role2,role3]\"")`
-
-**Input**: Selected roles from step 1.1
-
-**Parse Output**:
-- Verify topic-framework.md created with role-specific sections
-
-**Validation**:
-- File `.workflow/[session]/.brainstorming/topic-framework.md` exists
-- Contains sections for each selected role
-- Includes cross-role integration points
-
-**TodoWrite**: Mark phase 1 completed, mark "Display selected roles" as in_progress
-
----
-
-### Phase 2: Role Analysis Execution
-
-**Step 2.1: Role Selection**
-Use keyword analysis to auto-select 2-3 roles:
-
-**Role Selection Logic**:
-- **Technical/Architecture keywords**: `architecture|system|performance|database|api|backend|scalability`
-  → system-architect, data-architect, subject-matter-expert
-- **UI/UX keywords**: `user|ui|ux|interface|design|frontend|experience`
-  → ui-designer, ux-expert
-- **Product/Business keywords**: `product|feature|business|workflow|process|customer`
-  → product-manager, product-owner
-- **Agile/Delivery keywords**: `agile|sprint|scrum|team|collaboration|delivery`
-  → scrum-master, product-owner
-- **Domain Expertise keywords**: `domain|standard|compliance|expertise|regulation`
-  → subject-matter-expert
-- **Default**: product-manager (if no clear match)
-
-**Selection Rules**:
-- Maximum 3 roles
-- Select most relevant role first based on strongest keyword match
-- Include complementary perspectives (e.g., if system-architect selected, also consider security-expert)
-
-**Step 2.2: Display Selected Roles**
-Show selection to user before execution:
-```
-Selected roles for analysis:
-- ui-designer (UI/UX perspective)
-- system-architect (Technical architecture)
-- security-expert (Security considerations)
-```
-
-**Step 2.3: Execute Role Commands Sequentially**
-Execute each selected role command one by one:
-
-**Commands**:
-- `SlashCommand(command="/workflow:brainstorm:ui-designer")`
-- `SlashCommand(command="/workflow:brainstorm:ux-expert")`
-- `SlashCommand(command="/workflow:brainstorm:system-architect")`
-- `SlashCommand(command="/workflow:brainstorm:data-architect")`
-- `SlashCommand(command="/workflow:brainstorm:product-manager")`
-- `SlashCommand(command="/workflow:brainstorm:product-owner")`
-- `SlashCommand(command="/workflow:brainstorm:scrum-master")`
-- `SlashCommand(command="/workflow:brainstorm:subject-matter-expert")`
-- `SlashCommand(command="/workflow:brainstorm:test-strategist")`
-
-**Validation** (after each role):
-- File `.workflow/[session]/.brainstorming/[role]/analysis.md` exists
-- Contains role-specific analysis
-
-**TodoWrite**: Mark each role task completed after execution, start next role as in_progress
-
----
-
-### Phase 3: Synthesis Generation
-**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis")`
-
-**Validation**:
-- File `.workflow/[session]/.brainstorming/synthesis-report.md` exists
-- Contains cross-references to role analyses using @ notation
-
-**TodoWrite**: Mark phase 3 completed
-
-**Return to User**:
-```
-Brainstorming complete for topic: [topic]
-Framework: .workflow/[session]/.brainstorming/topic-framework.md
-Roles analyzed: [role1], [role2], [role3]
-Synthesis: .workflow/[session]/.brainstorming/synthesis-report.md
-```
-
-## TodoWrite Pattern
-
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Generate topic framework", "status": "in_progress", "activeForm": "Generating topic framework"},
-  {"content": "Display selected roles", "status": "pending", "activeForm": "Displaying selected roles"},
-  {"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
-  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
-]})
-
-// After Phase 1
-TodoWrite({todos: [
-  {"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
-  {"content": "Display selected roles", "status": "in_progress", "activeForm": "Displaying selected roles"},
-  {"content": "Execute ui-designer analysis", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
-  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
-]})
-
-// After displaying roles
-TodoWrite({todos: [
-  {"content": "Generate topic framework", "status": "completed", "activeForm": "Generating topic framework"},
-  {"content": "Display selected roles", "status": "completed", "activeForm": "Displaying selected roles"},
-  {"content": "Execute ui-designer analysis", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute system-architect analysis", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute security-expert analysis", "status": "pending", "activeForm": "Executing security-expert analysis"},
-  {"content": "Generate synthesis report", "status": "pending", "activeForm": "Generating synthesis report"}
-]})
-
-// Continue pattern for each role and synthesis...
-```
-
-## Data Flow
-
-```
-User Input (topic)
-    ↓
-Role Selection (analyze topic keywords)
-    ↓ Output: 2-3 selected roles (e.g., ui-designer, system-architect, security-expert)
-    ↓
-Phase 1: artifacts "topic" --roles "role1,role2,role3"
-    ↓ Input: topic + selected roles
-    ↓ Output: role-specific topic-framework.md
-    ↓
-Display: Show selected roles to user
-    ↓
-Phase 2: Execute each role command sequentially
-    ↓ Role 1 → reads role-specific section → analysis.md
-    ↓ Role 2 → reads role-specific section → analysis.md
-    ↓ Role 3 → reads role-specific section → analysis.md
-    ↓
-Phase 3: synthesis
-    ↓ Input: role-specific framework + all role analyses
-    ↓ Output: synthesis-report.md with role-targeted insights
-    ↓
-Return summary to user
-```
-
-**Session Context**: All commands use active brainstorming session, sharing:
-- Role-specific topic framework
-- Role-targeted analyses
-- Cross-role integration points
-- Synthesis with role-specific insights
-
-**Key Improvement**: Framework is generated with roles parameter, ensuring all discussion points are relevant to selected roles
-
-## Role Selection Examples
-
-### Example 1: UI-Focused Topic
-**Topic**: "Redesign user authentication interface"
-**Keywords detected**: user, interface, design
-**Selected roles**:
-- ui-designer (primary: UI/UX match)
-- ux-expert (secondary: user experience)
-- subject-matter-expert (complementary: auth standards)
-
-### Example 2: Architecture Topic
-**Topic**: "Design scalable microservices architecture"
-**Keywords detected**: architecture, scalable, system
-**Selected roles**:
-- system-architect (primary: architecture match)
-- data-architect (secondary: scalability/data)
-- subject-matter-expert (complementary: domain expertise)
-
-### Example 3: Agile Delivery Topic
-**Topic**: "Optimize team sprint planning and delivery process"
-**Keywords detected**: sprint, team, delivery, process
-**Selected roles**:
-- scrum-master (primary: agile process match)
-- product-owner (secondary: backlog/delivery focus)
-- product-manager (complementary: product strategy)
-
-## Error Handling
-
-- **Framework Generation Failure**: Stop workflow, report error, do not proceed to role selection
-- **Role Analysis Failure**: Log failure, continue with remaining roles, note in final summary
-- **Synthesis Failure**: Retry once, if still fails report partial completion with available analyses
-- **Session Error**: Report session issue, prompt user to check session status
-
-## Output Structure
-
-```
-.workflow/[session]/.brainstorming/
-├── topic-framework.md          # Phase 1 output
-├── [role1]/
-│   └── analysis.md            # Phase 2 output (role 1)
-├── [role2]/
-│   └── analysis.md            # Phase 2 output (role 2)
-├── [role3]/
-│   └── analysis.md            # Phase 2 output (role 3)
-└── synthesis-report.md        # Phase 3 output
-```
-
-## Coordinator Checklist
-
-✅ Initialize TodoWrite with framework + display + N roles + synthesis tasks
-✅ Execute Phase 1 (artifacts) immediately
-✅ Validate topic-framework.md exists
-✅ Analyze topic keywords for role selection
-✅ Auto-select 2-3 most relevant roles (max 3)
-✅ Display selected roles to user with rationale
-✅ Execute each role command sequentially
-✅ Validate each role's analysis.md after execution
-✅ 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

.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(*)
 ---
 
@@ -27,6 +22,26 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Data Quality Management**: Data accuracy, completeness, and consistency
 - **Analytics and Insights**: Data analysis and business intelligence solutions
 
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Canonical Data Model - Source of Truth)**
+- **Canonical Data Model**: The authoritative, system-wide data schema representing domain entities and relationships
+- **Entity-Relationship Design**: Defining entities, attributes, relationships, and constraints
+- **Data Normalization & Optimization**: Ensuring data integrity, reducing redundancy, and optimizing storage
+- **Database Schema Design**: Physical database structures, indexes, partitioning strategies
+- **Data Pipeline Architecture**: ETL/ELT processes, data warehousing, and analytics pipelines
+- **Data Governance**: Data quality standards, retention policies, and compliance requirements
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **API Data Contracts**: Public-facing request/response schemas exposed by APIs → Defers to **API Designer**
+- **System Integration Patterns**: How services communicate at the macro level → Defers to **System Architect**
+- **UI Data Presentation**: How data is displayed to users → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **TO API Designer**: Provides canonical data model that API Designer translates into public API data contracts (as projection/view)
+- **TO System Architect**: Provides data flow requirements and storage constraints to inform system design
+- **FROM System Architect**: Receives system-level integration requirements and scalability constraints
+
 ## ⚙️ **Execution Protocol**
 
 ### Phase 1: Session & Framework Detection
@@ -202,4 +217,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(*)
 ---
 
@@ -436,4 +433,65 @@ Upon completion, update `workflow-session.json`:
 - [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
 - [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
 - [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+
+## 🚀 **Recommended Next Steps**
+
+After synthesis completion, follow this recommended workflow:
+
+### Option 1: Standard Planning Workflow (Recommended)
+```bash
+# Step 1: Verify conceptual clarity (Quality Gate)
+/workflow:concept-verify --session WFS-{session-id}
+# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
+
+# Step 2: Proceed to action planning (after concept verification)
+/workflow:plan --session WFS-{session-id}
+# → Generates IMPL_PLAN.md and task.json files
+
+# Step 3: Verify action plan quality (Quality Gate)
+/workflow:action-plan-verify --session WFS-{session-id}
+# → Read-only analysis to catch issues before execution
+
+# Step 4: Start implementation
+/workflow:execute --session WFS-{session-id}
+```
+
+### Option 2: TDD Workflow
+```bash
+# Step 1: Verify conceptual clarity
+/workflow:concept-verify --session WFS-{session-id}
+
+# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
+/workflow:tdd-plan --session WFS-{session-id} "Feature description"
+
+# Step 3: Verify TDD plan quality
+/workflow:action-plan-verify --session WFS-{session-id}
+
+# Step 4: Execute TDD workflow
+/workflow:execute --session WFS-{session-id}
+```
+
+### Quality Gates Explained
+
+**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
+- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
+- **Time**: 10-20 minutes (interactive)
+- **Value**: Reduces downstream rework by 40-60%
+- **Output**: Updated synthesis-specification.md with clarifications
+
+**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
+- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
+- **Time**: 5-10 minutes (read-only analysis)
+- **Value**: Prevents execution of flawed plans, saves 2-5 days
+- **Output**: Verification report with actionable recommendations
+
+### Skip Verification? (Not Recommended)
+
+If you want to skip verification and proceed directly:
+```bash
+/workflow:plan --session WFS-{session-id}
+/workflow:execute --session WFS-{session-id}
+```
+
+⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

.claude/commands/workflow/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(*)
 ---
 
@@ -26,6 +22,25 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Performance & Scalability**: Capacity planning and optimization strategies
 - **Integration Patterns**: System communication and data flow design
 
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Macro-Architecture)**
+- **System-Level Architecture**: Service boundaries, deployment topology, and system composition
+- **Cross-Service Communication Patterns**: Choosing between microservices/monolithic, event-driven/request-response, sync/async patterns
+- **Technology Stack Decisions**: Language, framework, database, and infrastructure choices
+- **Non-Functional Requirements**: Scalability, performance, availability, disaster recovery, and monitoring strategies
+- **Integration Planning**: How systems and services connect at the macro level (not specific API contracts)
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **API Contract Details**: Specific endpoint definitions, URL structures, HTTP methods → Defers to **API Designer**
+- **Data Schemas**: Detailed data model design and entity relationships → Defers to **Data Architect**
+- **UI/UX Design**: Interface design and user experience → Defers to **UX Expert** and **UI Designer**
+
+#### **Handoff Points**
+- **TO API Designer**: Provides architectural constraints (REST vs GraphQL, sync vs async) that define the API design space
+- **TO Data Architect**: Provides system-level data flow requirements and integration patterns
+- **FROM Data Architect**: Receives canonical data model to inform system integration design
+
 ## ⚙️ **Execution Protocol**
 
 ### Phase 1: Session & Framework Detection
@@ -369,4 +384,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(*)
 ---
 
@@ -22,10 +17,31 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
 
 ### Analysis Scope
-- **User Experience Design**: Intuitive and efficient user experiences
-- **Interface Design**: Beautiful and functional user interfaces
-- **Interaction Design**: Smooth user interaction flows and micro-interactions
-- **Accessibility Design**: Inclusive design meeting WCAG compliance
+- **Visual Design**: Color palettes, typography, spacing, and visual hierarchy implementation
+- **High-Fidelity Mockups**: Polished, pixel-perfect interface designs
+- **Design System Implementation**: Component libraries, design tokens, and style guides
+- **Micro-Interactions & Animations**: Transition effects, loading states, and interactive feedback
+- **Responsive Design**: Layout adaptations for different screen sizes and devices
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Concrete Visual Interface Implementation)**
+- **Visual Design Language**: Colors, typography, iconography, spacing, and overall aesthetic
+- **High-Fidelity Mockups**: Polished designs showing exactly how the interface will look
+- **Design System Components**: Building and documenting reusable UI components (buttons, inputs, cards, etc.)
+- **Design Tokens**: Defining variables for colors, spacing, typography that can be used in code
+- **Micro-Interactions**: Hover states, transitions, animations, and interactive feedback details
+- **Responsive Layouts**: Adapting designs for mobile, tablet, and desktop breakpoints
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **User Research & Personas**: User behavior analysis and needs assessment → Defers to **UX Expert**
+- **Information Architecture**: Content structure and navigation strategy → Defers to **UX Expert**
+- **Low-Fidelity Wireframes**: Structural layouts without visual design → Defers to **UX Expert**
+
+#### **Handoff Points**
+- **FROM UX Expert**: Receives wireframes, user flows, and information architecture as the foundation for visual design
+- **TO Frontend Developers**: Provides design specifications, component libraries, and design tokens for implementation
+- **WITH API Designer**: Coordinates on data presentation and form validation feedback (visual aspects only)
 
 ## ⚙️ **Execution Protocol**
 
@@ -202,4 +218,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(*)
 ---
 
@@ -22,10 +17,31 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
 
 ### Analysis Scope
-- **User Interface Design**: Visual hierarchy, layout patterns, and component design
-- **Interaction Patterns**: User flows, navigation, and microinteractions
-- **Usability Optimization**: Accessibility, cognitive load, and user testing strategies
-- **Design Systems**: Component libraries, design tokens, and consistency frameworks
+- **User Research**: User personas, behavioral analysis, and needs assessment
+- **Information Architecture**: Content structure, navigation hierarchy, and mental models
+- **User Journey Mapping**: User flows, task analysis, and interaction models
+- **Usability Strategy**: Accessibility planning, cognitive load reduction, and user testing frameworks
+- **Wireframing**: Low-fidelity layouts and structural prototypes (not visual design)
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Abstract User Experience & Research)**
+- **User Research & Personas**: Understanding target users, their goals, pain points, and behaviors
+- **Information Architecture**: Organizing content and defining navigation structures at a conceptual level
+- **User Journey Mapping**: Defining user flows, task sequences, and interaction models
+- **Wireframes & Low-Fidelity Prototypes**: Structural layouts showing information hierarchy (boxes and arrows, not colors/fonts)
+- **Usability Testing Strategy**: Planning user testing, A/B tests, and validation methods
+- **Accessibility Planning**: WCAG compliance strategy and inclusive design principles
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **Visual Design**: Colors, typography, spacing, visual style → Defers to **UI Designer**
+- **High-Fidelity Mockups**: Polished, pixel-perfect designs → Defers to **UI Designer**
+- **Component Implementation**: Design system components, CSS, animations → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **TO UI Designer**: Provides wireframes, user flows, and information architecture that UI Designer will transform into high-fidelity visual designs
+- **FROM User Research**: May receive external research data to inform UX decisions
+- **TO Product Owner**: Provides user insights and validation results to inform feature prioritization
 
 ## ⚙️ **Execution Protocol**
 

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

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

.claude/commands/workflow/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
 
@@ -114,6 +109,14 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 4
 
+**Memory State Check**:
+- Evaluate current context window usage and memory state
+- If memory usage is high (>110K tokens or approaching context limits):
+  - **Command**: `SlashCommand(command="/compact")`
+  - This optimizes memory before proceeding to Phase 4
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
 ---
 
 ### Phase 4: Task Generation
@@ -124,9 +127,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
 
@@ -143,7 +160,12 @@ Planning complete for session: [sessionId]
 Tasks generated: [count]
 Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
-Next: /workflow:execute or /workflow:status
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
+2. /workflow:status  # Review task breakdown
+3. /workflow:execute  # Start implementation (after verification)
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
@@ -197,12 +219,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
 
 ```
@@ -261,7 +277,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
@@ -292,4 +311,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(*)
 ---
 
@@ -26,10 +21,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data for next phase
 4. **Sequential Execution**: Each phase depends on previous output
-5. **Complete All Phases**: Do not return until Phase 5 completes
+5. **Complete All Phases**: Do not return until Phase 7 completes (with concept verification)
 6. **TDD Context**: All descriptions include "TDD:" prefix
+7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
 
-## 6-Phase Execution
+## 7-Phase Execution (with Concept Verification)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -79,7 +75,22 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
 
-### Phase 5: TDD Task Generation
+### Phase 5: Concept Verification (NEW QUALITY GATE)
+**Command**: `/workflow:concept-verify --session [sessionId]`
+
+**Purpose**: Verify conceptual clarity before TDD task generation
+- Clarify test requirements and acceptance criteria
+- Resolve ambiguities in expected behavior
+- Validate TDD approach is appropriate
+
+**Behavior**:
+- If no ambiguities found → Auto-proceed to Phase 6
+- If ambiguities exist → Interactive clarification (up to 5 questions)
+- After clarifications → Auto-proceed to Phase 6
+
+**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+
+### Phase 6: TDD Task Generation
 **Command**:
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
@@ -93,10 +104,10 @@ TEST_FOCUS: [Test scenarios]
 - IMPL tasks include test-fix-cycle configuration
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 
-### Phase 6: TDD Structure Validation
-**Internal validation (no command)**
+### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
+**Internal validation first, then recommend external verification**
 
-**Validate**:
+**Internal Validation**:
 1. Each feature has TEST → IMPL → REFACTOR chain
 2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
 3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
@@ -117,20 +128,26 @@ Structure:
 
 Plan:
 - Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
-  (includes TDD Task Chains section)
+  (includes TDD Task Chains section with workflow_type: "tdd")
 
-Next: /workflow:execute or /workflow:tdd-verify
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+2. /workflow:execute --session [sessionId]  # Start TDD execution
+3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task dependencies
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize (6 phases now)
+// Initialize (7 phases now with concept verification)
 [
   {content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
-  {content: "Execute context gathering", status: "pending", activeForm: "Executing context gathering"},
-  {content: "Execute test coverage analysis", status: "pending", activeForm: "Executing test coverage analysis"},
-  {content: "Execute TDD analysis", status: "pending", activeForm: "Executing TDD analysis"},
+  {content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
+  {content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
+  {content: "Execute TDD analysis", status: "pending", activeForm": "Executing TDD analysis"},
+  {content: "Execute concept verification", status: "pending", activeForm": "Executing concept verification"},
   {content: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
   {content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
 ]

.claude/commands/workflow/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
@@ -11,47 +10,40 @@ examples:
 # Enhanced Analysis Command (/workflow:tools:concept-enhanced)
 
 ## Overview
-Advanced solution design and feasibility analysis engine with parallel CLI execution that processes standardized context packages and produces comprehensive technical analysis focused on solution improvements, key design decisions, and critical insights.
+Advanced solution design and feasibility analysis engine with parallel CLI execution. Processes standardized context packages to produce ANALYSIS_RESULTS.md focused on solution improvements, key design decisions, and critical insights.
 
-**Analysis Focus**: Produces ANALYSIS_RESULTS.md with solution design, architectural rationale, feasibility assessment, and optimization strategies. Does NOT generate task breakdowns or implementation plans.
+**Scope**: Solution-focused technical analysis only. Does NOT generate task breakdowns or implementation plans.
 
-**Independent Usage**: This command can be called directly by users or as part of the `/workflow:plan` command. It accepts context packages and provides solution-focused technical analysis.
+**Usage**: Standalone command or integrated into `/workflow:plan`. Accepts context packages and orchestrates Gemini/Codex for comprehensive analysis.
 
-## Core Philosophy
-- **Solution-Focused**: Emphasize design decisions, architectural rationale, and critical insights
-- **Context-Driven**: Precise analysis based on comprehensive context packages
-- **Intelligent Tool Selection**: Choose optimal tools based on task complexity (Gemini for design, Codex for validation)
+## Core Philosophy & Responsibilities
+- **Solution-Focused Analysis**: Emphasize design decisions, architectural rationale, and critical insights (exclude task planning)
+- **Context-Driven**: Parse and validate context-package.json for precise analysis
+- **Intelligent Tool Selection**: Gemini for design (all tasks), Codex for validation (complex tasks only)
 - **Parallel Execution**: Execute multiple CLI tools simultaneously for efficiency
-- **No Task Planning**: Exclude implementation steps, task breakdowns, and project planning
+- **Solution Design**: Evaluate architecture, identify key design decisions with rationale
+- **Feasibility Assessment**: Analyze technical complexity, risks, implementation readiness
+- **Optimization Recommendations**: Performance, security, and code quality improvements
+- **Perspective Synthesis**: Integrate multi-tool insights into unified assessment
 - **Single Output**: Generate only ANALYSIS_RESULTS.md with technical analysis
 
-## Core Responsibilities
-- **Context Package Parsing**: Read and validate context-package.json
-- **Parallel CLI Orchestration**: Execute Gemini (solution design) and optionally Codex (feasibility validation)
-- **Solution Design Analysis**: Evaluate architecture, identify key design decisions with rationale
-- **Feasibility Assessment**: Analyze technical complexity, risks, and implementation readiness
-- **Optimization Recommendations**: Propose performance, security, and code quality improvements
-- **Perspective Synthesis**: Integrate Gemini and Codex insights into unified solution assessment
-- **Technical Analysis Report**: Generate ANALYSIS_RESULTS.md focused on design decisions and critical insights (NO task planning)
-
 ## Analysis Strategy Selection
 
 ### Tool Selection by Task Complexity
 
 **Simple Tasks (≤3 modules)**:
-- **Primary Tool**: Gemini (rapid understanding and pattern recognition)
-- **Support Tool**: Code-index (structural analysis)
-- **Execution Mode**: Single-round analysis, focus on existing patterns
+- **Primary**: Gemini (rapid understanding + pattern recognition)
+- **Support**: Code-index (structural analysis)
+- **Mode**: Single-round analysis
 
 **Medium Tasks (4-6 modules)**:
-- **Primary Tool**: Gemini (comprehensive single-round analysis and architecture design)
-- **Support Tools**: Code-index + Exa (external best practices)
-- **Execution Mode**: Single comprehensive analysis covering understanding + architecture design
+- **Primary**: Gemini (comprehensive analysis + architecture design)
+- **Support**: Code-index + Exa (best practices)
+- **Mode**: Single comprehensive round
 
 **Complex Tasks (>6 modules)**:
-- **Primary Tools**: Gemini (single comprehensive analysis) + Codex (implementation validation)
-- **Analysis Strategy**: Gemini handles understanding + architecture in one round, Codex validates implementation
-- **Execution Mode**: Parallel execution - Gemini comprehensive analysis + Codex validation
+- **Primary**: Gemini (comprehensive analysis) + Codex (validation)
+- **Mode**: Parallel execution - Gemini design + Codex feasibility
 
 ### Tool Preferences by Tech Stack
 
@@ -78,168 +70,82 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
 ## Execution Lifecycle
 
 ### Phase 1: Validation & Preparation
-1. **Session Validation**
-   - Verify session directory exists: `.workflow/{session_id}/`
-   - Load session metadata from `workflow-session.json`
-   - Validate session state and task context
-
-2. **Context Package Validation**
-   - Verify context package exists at specified path
-   - Validate JSON format and structure
-   - Assess context package size and complexity
-
-3. **Task Analysis & Classification**
-   - Parse task description and extract keywords
-   - Identify technical domain and complexity level
-   - Determine required analysis depth and scope
-   - Load existing session context and task summaries
-
-4. **Tool Selection Strategy**
-   - **Simple/Medium Tasks**: Single Gemini comprehensive analysis
-   - **Complex Tasks**: Gemini comprehensive + Codex validation
-   - Load appropriate prompt templates and configurations
+1. **Session Validation**: Verify `.workflow/{session_id}/` exists, load `workflow-session.json`
+2. **Context Package Validation**: Verify path, validate JSON format and structure
+3. **Task Analysis**: Extract keywords, identify domain/complexity, determine scope
+4. **Tool Selection**: Gemini (all tasks), +Codex (complex only), load templates
 
 ### Phase 2: Analysis Preparation
-1. **Workspace Setup**
-   - Create analysis output directory: `.workflow/{session_id}/.process/`
-   - Initialize log files and monitoring structures
-   - Set process limits and resource management
-
-2. **Context Optimization**
-   - Filter high-priority assets from context package
-   - Organize project structure and dependencies
-   - Prepare template references and rule configurations
-
-3. **Execution Environment**
-   - Configure CLI tools with write permissions
-   - Set timeout parameters and monitoring intervals
-   - Prepare error handling and recovery mechanisms
+1. **Workspace Setup**: Create `.workflow/{session_id}/.process/`, initialize logs, set resource limits
+2. **Context Optimization**: Filter high-priority assets, organize structure, prepare templates
+3. **Execution Environment**: Configure CLI tools, set timeouts, prepare error handling
 
 ### Phase 3: Parallel Analysis Execution
 1. **Gemini Solution Design & Architecture Analysis**
-   - **Tool Configuration**:
-     ```bash
-     ~/.claude/scripts/gemini-wrapper -p "
-     PURPOSE: Analyze and design optimal solution for {task_description}
-     TASK: Evaluate current architecture, propose solution design, and identify key design decisions
-     CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
+   ```bash
+   ~/.claude/scripts/gemini-wrapper -p "
+   PURPOSE: Analyze and design optimal solution for {task_description}
+   TASK: Evaluate current architecture, propose solution design, identify key design decisions
+   CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
 
-     **MANDATORY FIRST STEP**: Read and analyze .workflow/{session_id}/.process/context-package.json to understand:
-     - Task requirements from metadata.task_description
-     - Relevant source files from assets[] array
-     - Tech stack from tech_stack section
-     - Project structure from statistics section
+   **MANDATORY**: Read context-package.json to understand task requirements, source files, tech stack, project structure
 
-     **ANALYSIS PRIORITY - Use ALL source documents from context-package assets[]**:
-     1. PRIMARY SOURCES (Highest Priority): Individual role analysis.md files (system-architect, ui-designer, product-manager, etc.)
-        - These contain complete technical details, design rationale, ADRs, and decision context
-        - Extract: Technical specs, API schemas, design tokens, caching configs, performance metrics
-     2. SYNTHESIS REFERENCE (Medium Priority): synthesis-specification.md
-        - Use for integrated requirements and cross-role alignment
-        - Validate decisions and identify integration points
-     3. TOPIC FRAMEWORK (Low Priority): topic-framework.md for discussion context
+   **ANALYSIS PRIORITY**:
+   1. PRIMARY: Individual role analysis.md files (system-architect, ui-designer, etc.) - technical details, ADRs, decision context
+   2. SECONDARY: synthesis-specification.md - integrated requirements, cross-role alignment
+   3. REFERENCE: topic-framework.md - discussion context
 
-     EXPECTED:
-     1. CURRENT STATE ANALYSIS: Existing patterns, code structure, integration points, technical debt
-     2. SOLUTION DESIGN: Core architecture principles, system design, key design decisions with rationale
-     3. CRITICAL INSIGHTS: What works well, identified gaps, technical risks, architectural tradeoffs
-     4. OPTIMIZATION STRATEGIES: Performance improvements, security enhancements, code quality recommendations
-     5. FEASIBILITY ASSESSMENT: Complexity analysis, compatibility evaluation, implementation readiness
-     6. **OUTPUT FILE**: Write complete analysis to .workflow/{session_id}/.process/gemini-solution-design.md
+   EXPECTED:
+   1. CURRENT STATE: Existing patterns, code structure, integration points, technical debt
+   2. SOLUTION DESIGN: Core principles, system design, key decisions with rationale
+   3. CRITICAL INSIGHTS: Strengths, gaps, risks, tradeoffs
+   4. OPTIMIZATION: Performance, security, code quality recommendations
+   5. FEASIBILITY: Complexity analysis, compatibility, implementation readiness
+   6. OUTPUT: Write to .workflow/{session_id}/.process/gemini-solution-design.md
 
-     RULES:
-     - Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, NOT task planning
-     - Provide architectural rationale, evaluate alternatives, assess tradeoffs
-     - **CRITICAL**: Identify code targets - existing files as "file:function:lines", new files as "file"
-     - For modifications: specify exact files/functions/line ranges
-     - For new files: specify file path only (no function or lines)
-     - Do NOT create task lists, implementation steps, or code examples
-     - Do NOT generate any code snippets or implementation details
-     - **MUST write output to .workflow/{session_id}/.process/gemini-solution-design.md**
-     - Output ONLY architectural analysis and design recommendations
-     " --approval-mode yolo
-     ```
-   - **Output Location**: `.workflow/{session_id}/.process/gemini-solution-design.md`
+   RULES:
+   - Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS (NO task planning)
+   - Identify code targets: existing "file:function:lines", new files "file"
+   - Do NOT create task lists, implementation steps, or code examples
+   " --approval-mode yolo
+   ```
+   Output: `.workflow/{session_id}/.process/gemini-solution-design.md`
 
 2. **Codex Technical Feasibility Validation** (Complex Tasks Only)
-   - **Tool Configuration**:
-     ```bash
-     codex --full-auto exec "
-     PURPOSE: Validate technical feasibility and identify implementation risks for {task_description}
-     TASK: Assess implementation complexity, validate technology choices, evaluate performance and security implications
-     CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/.process/gemini-solution-design.md,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
+   ```bash
+   codex --full-auto exec "
+   PURPOSE: Validate technical feasibility and identify implementation risks for {task_description}
+   TASK: Assess complexity, validate technology choices, evaluate performance/security implications
+   CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/.process/gemini-solution-design.md,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
 
-     **MANDATORY FIRST STEP**: Read and analyze:
-     - .workflow/{session_id}/.process/context-package.json for task context
-     - .workflow/{session_id}/.process/gemini-solution-design.md for proposed solution design
-     - Relevant source files listed in context-package.json assets[]
+   **MANDATORY**: Read context-package.json, gemini-solution-design.md, and relevant source files
 
-     EXPECTED:
-     1. FEASIBILITY ASSESSMENT: Technical complexity rating, resource requirements, technology compatibility
-     2. RISK ANALYSIS: Implementation risks, integration challenges, performance concerns, security vulnerabilities
-     3. TECHNICAL VALIDATION: Development approach validation, quality standards assessment, maintenance implications
-     4. CRITICAL RECOMMENDATIONS: Must-have requirements, optimization opportunities, security controls
-     5. **OUTPUT FILE**: Write validation results to .workflow/{session_id}/.process/codex-feasibility-validation.md
+   EXPECTED:
+   1. FEASIBILITY: Complexity rating, resource requirements, technology compatibility
+   2. RISK ANALYSIS: Implementation risks, integration challenges, performance/security concerns
+   3. VALIDATION: Development approach, quality standards, maintenance implications
+   4. RECOMMENDATIONS: Must-have requirements, optimization opportunities, security controls
+   5. OUTPUT: Write to .workflow/{session_id}/.process/codex-feasibility-validation.md
 
-     RULES:
-     - Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, NOT implementation planning
-     - Validate architectural decisions, identify potential issues, recommend optimizations
-     - **CRITICAL**: Verify code targets - existing files "file:function:lines", new files "file"
-     - Confirm exact locations for modifications, identify additional new files if needed
-     - Do NOT create task breakdowns, step-by-step guides, or code examples
-     - Do NOT generate any code snippets or implementation details
-     - **MUST write output to .workflow/{session_id}/.process/codex-feasibility-validation.md**
-     - Output ONLY feasibility analysis and risk assessment
-     " --skip-git-repo-check -s danger-full-access
-     ```
-   - **Output Location**: `.workflow/{session_id}/.process/codex-feasibility-validation.md`
+   RULES:
+   - Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT (NO implementation planning)
+   - Verify code targets: existing "file:function:lines", new files "file"
+   - Do NOT create task breakdowns, step-by-step guides, or code examples
+   " --skip-git-repo-check -s danger-full-access
+   ```
+   Output: `.workflow/{session_id}/.process/codex-feasibility-validation.md`
 
-3. **Parallel Execution Management**
-   - Launch both tools simultaneously for complex tasks
-   - Monitor execution progress with timeout controls
-   - Handle process completion and error scenarios
-   - Maintain execution logs for debugging and recovery
+3. **Parallel Execution**: Launch tools simultaneously, monitor progress, handle completion/errors, maintain logs
 
 ### Phase 4: Results Collection & Synthesis
-1. **Output Validation & Collection**
-   - **Gemini Results**: Validate `gemini-solution-design.md` contains complete solution analysis
-   - **Codex Results**: For complex tasks, validate `codex-feasibility-validation.md` with technical assessment
-   - **Fallback Processing**: Use execution logs if primary outputs are incomplete
-   - **Status Classification**: Mark each tool as completed, partial, failed, or skipped
-
-2. **Quality Assessment**
-   - **Design Quality**: Verify architectural decisions have clear rationale and alternatives analysis
-   - **Insight Depth**: Assess quality of critical insights and risk identification
-   - **Feasibility Rigor**: Validate completeness of technical feasibility assessment
-   - **Optimization Value**: Check actionability of optimization recommendations
-
-3. **Analysis Synthesis Strategy**
-   - **Simple/Medium Tasks**: Direct integration of Gemini solution design
-   - **Complex Tasks**: Synthesis of Gemini design with Codex feasibility validation
-   - **Conflict Resolution**: Identify architectural disagreements and provide balanced resolution
-   - **Confidence Scoring**: Assess overall solution confidence based on multi-tool consensus
+1. **Output Validation**: Validate gemini-solution-design.md (all), codex-feasibility-validation.md (complex), use logs if incomplete, classify status
+2. **Quality Assessment**: Verify design rationale, insight depth, feasibility rigor, optimization value
+3. **Synthesis Strategy**: Direct integration (simple/medium), multi-tool synthesis (complex), resolve conflicts, score confidence
 
 ### Phase 5: ANALYSIS_RESULTS.md Generation
-1. **Structured Report Assembly**
-   - **Executive Summary**: Analysis focus, overall assessment, recommendation status
-   - **Current State Analysis**: Architecture overview, compatibility, critical findings
-   - **Proposed Solution Design**: Core principles, system design, key design decisions with rationale
-   - **Implementation Strategy**: Development approach, feasibility assessment, risk mitigation
-   - **Solution Optimization**: Performance, security, code quality recommendations
-   - **Critical Success Factors**: Technical requirements, quality metrics, success validation
-   - **Confidence & Recommendations**: Assessment scores, final recommendation with rationale
-
-2. **Report Generation Guidelines**
-   - **Focus**: Solution improvements, key design decisions, critical insights
-   - **Exclude**: Task breakdowns, implementation steps, project planning
-   - **Emphasize**: Architectural rationale, tradeoff analysis, risk assessment
-   - **Structure**: Clear sections with decision justification and feasibility scoring
-
-3. **Final Output**
-   - **Primary Output**: `ANALYSIS_RESULTS.md` - comprehensive solution design and technical analysis
-   - **Single File Policy**: Only generate ANALYSIS_RESULTS.md, no supplementary files
-   - **Report Location**: `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
-   - **Content Focus**: Technical insights, design decisions, optimization strategies
+1. **Report Sections**: Executive Summary, Current State, Solution Design, Implementation Strategy, Optimization, Success Factors, Confidence Scores
+2. **Guidelines**: Focus on solution improvements and design decisions (exclude task planning), emphasize rationale/tradeoffs/risk assessment
+3. **Output**: Single file `ANALYSIS_RESULTS.md` at `.workflow/{session_id}/.process/` with technical insights and optimization strategies
 
 ## Analysis Results Format
 
@@ -318,35 +224,22 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 ### Code Modification Targets
 **Purpose**: Specific code locations for modification AND new files to create
 
-**Format**:
-- Existing files: `file:function:lines` (with line numbers)
-- New files: `file` (no function or lines)
-
 **Identified Targets**:
 1. **Target**: `src/auth/AuthService.ts:login:45-52`
    - **Type**: Modify existing
    - **Modification**: Enhance error handling
-   - **Rationale**: Current logic lacks validation for edge cases
+   - **Rationale**: Current logic lacks validation
 
 2. **Target**: `src/auth/PasswordReset.ts`
    - **Type**: Create new file
    - **Purpose**: Password reset functionality
    - **Rationale**: New feature requirement
 
-3. **Target**: `src/middleware/auth.ts:validateToken:30-45`
-   - **Type**: Modify existing
-   - **Modification**: Add token expiry check
-   - **Rationale**: Security requirement for JWT validation
-
-4. **Target**: `tests/auth/PasswordReset.test.ts`
-   - **Type**: Create new file
-   - **Purpose**: Test coverage for password reset
-   - **Rationale**: Test requirement for new feature
-
-**Note**:
-- For new files, only specify the file path (no function or lines)
-- For existing files without line numbers, use `file:function:*` format
-- Task generation will refine these during the `analyze_task_patterns` step
+**Format Rules**:
+- Existing files: `file:function:lines` (with line numbers)
+- New files: `file` (no function or lines)
+- Unknown lines: `file:function:*`
+- Task generation will refine these targets during `analyze_task_patterns` step
 
 ### Feasibility Assessment
 - **Technical Complexity**: {complexity_rating_and_analysis}
@@ -438,94 +331,46 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 - **External Resources**: {external_references_and_best_practices}
 ```
 
-## Error Handling & Fallbacks
+## Execution Management
 
-### Error Handling & Recovery Strategies
+### Error Handling & Recovery
+1. **Pre-execution**: Verify session/context package, confirm CLI tools, validate dependencies
+2. **Monitoring & Timeout**: Track progress, 30-min limit, manage parallel execution, maintain status
+3. **Partial Recovery**: Generate results with incomplete outputs, use logs, provide next steps
+4. **Error Recovery**: Auto error detection, structured workflows, graceful degradation
 
-1. **Pre-execution Validation**
-   - **Session Verification**: Ensure session directory and metadata exist
-   - **Context Package Validation**: Verify JSON format and content structure
-   - **Tool Availability**: Confirm CLI tools are accessible and configured
-   - **Prerequisite Checks**: Validate all required dependencies and permissions
-
-2. **Execution Monitoring & Timeout Management**
-   - **Progress Monitoring**: Track analysis execution with regular status checks
-   - **Timeout Controls**: 30-minute execution limit with graceful termination
-   - **Process Management**: Handle parallel tool execution and resource limits
-   - **Status Tracking**: Maintain real-time execution state and completion status
-
-3. **Partial Results Recovery**
-   - **Fallback Strategy**: Generate analysis results even with incomplete outputs
-   - **Log Integration**: Use execution logs when primary outputs are unavailable
-   - **Recovery Mode**: Create partial analysis reports with available data
-   - **Guidance Generation**: Provide next steps and retry recommendations
-
-4. **Resource Management**
-   - **Disk Space Monitoring**: Check available storage and cleanup temporary files
-   - **Process Limits**: Set CPU and memory constraints for analysis execution
-   - **Performance Optimization**: Manage resource utilization and system load
-   - **Cleanup Procedures**: Remove outdated logs and temporary files
-
-5. **Comprehensive Error Recovery**
-   - **Error Detection**: Automatic error identification and classification
-   - **Recovery Workflows**: Structured approach to handling different failure modes
-   - **Status Reporting**: Clear communication of issues and resolution attempts
-   - **Graceful Degradation**: Provide useful outputs even with partial failures
-
-## Performance Optimization
-
-### Analysis Optimization Strategies
-- **Parallel Analysis**: Execute multiple tools in parallel to reduce total time
+### Performance & Resource Optimization
+- **Parallel Analysis**: Execute multiple tools simultaneously to reduce time
 - **Context Sharding**: Analyze large projects by module shards
-- **Caching Mechanism**: Reuse analysis results for similar contexts
-- **Incremental Analysis**: Perform incremental analysis based on changes
+- **Caching**: Reuse results for similar contexts
+- **Resource Management**: Monitor disk/CPU/memory, set limits, cleanup temporary files
+- **Timeout Control**: `timeout 600s` with partial result generation on failure
 
-### Resource Management
-```bash
-# Set analysis timeout
-timeout 600s analysis_command || {
-  echo "⚠️ Analysis timeout, generating partial results"
-  # Generate partial results
-}
+## Integration & Success Criteria
 
-# Memory usage monitoring
-memory_usage=$(ps -o pid,vsz,rss,comm -p $$)
-if [ "$memory_usage" -gt "$memory_limit" ]; then
-  echo "⚠️ High memory usage detected, optimizing..."
-fi
-```
+### Input/Output Interface
+**Input**:
+- `--session` (required): Session ID (e.g., WFS-auth)
+- `--context` (required): Context package path
+- `--depth` (optional): Analysis depth (quick|full|deep)
+- `--focus` (optional): Analysis focus areas
 
-## Integration Points
+**Output**:
+- Single file: `ANALYSIS_RESULTS.md` at `.workflow/{session_id}/.process/`
+- No supplementary files (JSON, roadmap, templates)
 
-### Input Interface
-- **Required**: `--session` parameter specifying session ID (e.g., WFS-auth)
-- **Required**: `--context` parameter specifying context package path
-- **Optional**: `--depth` specify analysis depth (quick|full|deep)
-- **Optional**: `--focus` specify analysis focus areas
+### Quality & Success Validation
+**Quality Checks**: Completeness, consistency, feasibility validation
 
-### Output Interface
-- **Primary**: ANALYSIS_RESULTS.md - solution design and technical analysis
-- **Location**: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
-- **Single Output Policy**: Only ANALYSIS_RESULTS.md is generated
-- **No Supplementary Files**: No additional JSON, roadmap, or template files
-
-## Quality Assurance
-
-### Analysis Quality Checks
-- **Completeness Check**: Ensure all required analysis sections are completed
-- **Consistency Check**: Verify consistency of multi-tool analysis results
-- **Feasibility Validation**: Ensure recommended implementation plans are feasible
-
-### Success Criteria
-- ✅ **Solution-Focused Analysis**: ANALYSIS_RESULTS.md emphasizes solution improvements, design decisions, and critical insights
-- ✅ **Single Output File**: Only ANALYSIS_RESULTS.md generated, no supplementary files
-- ✅ **Design Decision Depth**: Clear rationale for architectural choices with alternatives and tradeoffs
-- ✅ **Feasibility Assessment**: Technical complexity, risk analysis, and implementation readiness evaluation
-- ✅ **Optimization Strategies**: Performance, security, and code quality recommendations
-- ✅ **Parallel Execution**: Efficient concurrent tool execution (Gemini + Codex for complex tasks)
-- ✅ **Robust Error Handling**: Comprehensive validation, timeout management, and partial result recovery
-- ✅ **Confidence Scoring**: Multi-dimensional assessment with clear recommendation status
-- ✅ **No Task Planning**: Exclude task breakdowns, implementation steps, and project planning details
+**Success Criteria**:
+- ✅ Solution-focused analysis (design decisions, critical insights, NO task planning)
+- ✅ Single output file only
+- ✅ Design decision depth with rationale/alternatives/tradeoffs
+- ✅ Feasibility assessment (complexity, risks, readiness)
+- ✅ Optimization strategies (performance, security, quality)
+- ✅ Parallel execution efficiency (Gemini + Codex for complex tasks)
+- ✅ Robust error handling (validation, timeout, partial recovery)
+- ✅ Confidence scoring with clear recommendation status
 
 ## Related Commands
 - `/context:gather` - Generate context packages required by this command

.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/docs.md

@@ -1,256 +0,0 @@
----
-name: docs
-description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
-usage: /workflow:docs <type> [scope]
-argument-hint: "architecture"|"api"|"all"
-examples:
-  - /workflow:docs all
-  - /workflow:docs architecture src/modules
-  - /workflow:docs api --scope api/
----
-
-# Workflow Documentation Command
-
-## Usage
-```bash
-/workflow:docs <type> [scope]
-```
-
-## Input Detection
-- **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
-- **Scope**: Optional module/directory filtering → Focuses documentation generation
-- **Default**: `all` → Complete documentation suite
-
-## Core Workflow
-
-### Planning & Task Creation Process
-The command performs structured planning and task creation:
-
-**0. Pre-Planning Architecture Analysis** ⚠️ MANDATORY FIRST STEP
-- **System Structure Analysis**: MUST run `bash(~/.claude/scripts/get_modules_by_depth.sh)` for dynamic task decomposition
-- **Module Boundary Identification**: Understand module organization and dependencies
-- **Architecture Pattern Recognition**: Identify architectural styles and design patterns
-- **Foundation for documentation**: Use structure analysis to guide task decomposition
-
-**1. Documentation Planning**
-- **Type Analysis**: Determine documentation scope (architecture/api/all)
-- **Module Discovery**: Use architecture analysis results to identify components
-- **Dynamic Task Decomposition**: Analyze project structure to determine optimal task count and module grouping
-- **Session Management**: Create or use existing documentation session
-
-**2. Task Generation**
-- **Create session**: `.workflow/WFS-docs-[timestamp]/`
-- **Create active marker**: `.workflow/.active-WFS-docs-[timestamp]` (must match session folder name)
-- **Generate IMPL_PLAN.md**: Documentation requirements and task breakdown
-- **Create task.json files**: Individual documentation tasks with flow_control
-- **Setup TODO_LIST.md**: Progress tracking for documentation generation
-
-### Session Management ⚠️ CRITICAL
-- **Check for active sessions**: Look for `.workflow/.active-WFS-docs-*` markers
-- **Marker naming**: Active marker must exactly match session folder name
-- **Session creation**: `WFS-docs-[timestamp]` folder with matching `.active-WFS-docs-[timestamp]` marker
-- **Task execution**: Use `/workflow:execute` to run individual documentation tasks within active session
-- **Session isolation**: Each documentation session maintains independent context and state
-
-## Output Structure
-```
-.workflow/docs/
-├── README.md              # System navigation
-├── modules/               # Level 1: Module documentation
-│   ├── [module-1]/
-│   │   ├── overview.md
-│   │   ├── api.md
-│   │   ├── dependencies.md
-│   │   └── examples.md
-│   └── [module-n]/...
-├── architecture/          # Level 2: System architecture
-│   ├── system-design.md
-│   ├── module-map.md
-│   ├── data-flow.md
-│   └── tech-stack.md
-└── api/                   # Level 2: Unified API docs
-    ├── unified-api.md
-    └── openapi.yaml
-```
-
-## Task Decomposition Standards
-
-### Dynamic Task Planning Rules
-**Module Grouping**: Max 3 modules per task, max 30 files per task
-**Task Count**: Calculate based on `total_modules ÷ 3 (rounded up) + base_tasks`
-**File Limits**: Split tasks when file count exceeds 30 in any module group
-**Base Tasks**: System overview (1) + Architecture (1) + API consolidation (1)
-**Module Tasks**: Group related modules by dependency depth and functional similarity
-
-### Documentation Task Types
-**IMPL-001**: System Overview Documentation
-- Project structure analysis
-- Technology stack documentation
-- Main navigation creation
-
-**IMPL-002**: Module Documentation (per module)
-- Individual module analysis
-- API surface documentation
-- Dependencies and relationships
-- Usage examples
-
-**IMPL-003**: Architecture Documentation
-- System design patterns
-- Module interaction mapping
-- Data flow documentation
-- Design principles
-
-**IMPL-004**: API Documentation
-- Endpoint discovery and analysis
-- OpenAPI specification generation
-- Authentication documentation
-- Integration examples
-
-### Task JSON Schema (5-Field Architecture)
-Each documentation task uses the workflow-architecture.md 5-field schema:
-- **id**: IMPL-N format
-- **title**: Documentation task name
-- **status**: pending|active|completed|blocked
-- **meta**: { type: "documentation", agent: "@doc-generator" }
-- **context**: { requirements, focus_paths, acceptance, scope }
-- **flow_control**: { pre_analysis[], implementation_approach, target_files[] }
-
-## Document Generation
-
-### Workflow Process
-**Input Analysis** → **Session Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md** → **Execute Tasks**
-
-**Always Created**:
-- **IMPL_PLAN.md**: Documentation requirements and task breakdown
-- **Session state**: Task references and documentation paths
-
-**Auto-Created (based on scope)**:
-- **TODO_LIST.md**: Progress tracking for documentation tasks
-- **.task/IMPL-*.json**: Individual documentation tasks with flow_control
-- **.process/ANALYSIS_RESULTS.md**: Documentation analysis artifacts
-
-**Document Structure**:
-```
-.workflow/
-├── .active-WFS-docs-20231201-143022  # Active session marker (matches folder name)
-└── WFS-docs-20231201-143022/         # Documentation session folder
-    ├── IMPL_PLAN.md                  # Main documentation plan
-    ├── TODO_LIST.md                  # Progress tracking
-    ├── .process/
-    │   └── ANALYSIS_RESULTS.md       # Documentation analysis
-    └── .task/
-        ├── IMPL-001.json             # System overview task
-        ├── IMPL-002.json             # Module documentation task
-        ├── IMPL-003.json             # Architecture documentation task
-        └── IMPL-004.json             # API documentation task
-```
-
-### Task Flow Control Templates
-
-**System Overview Task (IMPL-001)**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "system_architecture_analysis",
-      "action": "Discover system architecture and module hierarchy",
-      "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
-      "output_to": "system_structure"
-    },
-    {
-      "step": "project_discovery",
-      "action": "Discover project structure and entry points",
-      "command": "bash(find . -type f -name '*.json' -o -name '*.md' -o -name 'package.json' | head -20)",
-      "output_to": "project_structure"
-    },
-    {
-      "step": "analyze_tech_stack",
-      "action": "Analyze technology stack and dependencies using structure analysis",
-      "command": "~/.claude/scripts/gemini-wrapper -p \"Analyze project technology stack and dependencies based on: [system_structure]\"",
-      "output_to": "tech_analysis"
-    }
-  ],
-  "target_files": [".workflow/docs/README.md"]
-}
-```
-
-**Module Documentation Task (IMPL-002)**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "load_system_structure",
-      "action": "Load system architecture analysis from previous task",
-      "command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)",
-      "output_to": "system_context"
-    },
-    {
-      "step": "module_analysis",
-      "action": "Analyze specific module structure and API within system context",
-      "command": "~/.claude/scripts/gemini-wrapper -p \"Analyze module [MODULE_NAME] structure and exported API within system: [system_context]\"",
-      "output_to": "module_context"
-    }
-  ],
-  "target_files": [".workflow/docs/modules/[MODULE_NAME]/overview.md"]
-}
-```
-
-## Analysis Templates
-
-### Project Structure Analysis Rules
-- Identify main modules and purposes
-- Map directory organization patterns
-- Extract entry points and configuration files
-- Recognize architectural styles and design patterns
-- Analyze module relationships and dependencies
-- Document technology stack and requirements
-
-### Module Analysis Rules
-- Identify module boundaries and entry points
-- Extract exported functions, classes, interfaces
-- Document internal organization and structure
-- Analyze API surfaces with types and parameters
-- Map dependencies within and between modules
-- Extract usage patterns and examples
-
-### API Analysis Rules
-- Classify endpoint types (REST, GraphQL, WebSocket, RPC)
-- Extract request/response parameters and schemas
-- Document authentication and authorization requirements
-- Generate OpenAPI 3.0 specification structure
-- Create comprehensive endpoint documentation
-- Provide usage examples and integration guides
-
-## Error Handling
-- **Invalid document type**: Clear error message with valid options
-- **Module not found**: Skip missing modules with warning
-- **Analysis failures**: Fall back to file-based analysis
-- **Permission issues**: Clear guidance on directory access
-
-## Key Benefits
-
-### Structured Documentation Process
-- **Task-based approach**: Documentation broken into manageable, trackable tasks
-- **Flow control integration**: Systematic analysis ensures completeness
-- **Progress visibility**: TODO_LIST.md provides clear completion status
-- **Quality assurance**: Each task has defined acceptance criteria
-
-### Workflow Integration
-- **Planning foundation**: Documentation provides context for implementation planning
-- **Execution consistency**: Same task execution model as implementation
-- **Context accumulation**: Documentation builds comprehensive project understanding
-
-## Usage Examples
-
-### Complete Documentation Workflow
-```bash
-# Step 1: Create documentation plan and tasks
-/workflow:docs all
-
-# Step 2: Execute documentation tasks (after planning)
-/workflow:execute IMPL-001  # System overview
-/workflow:execute IMPL-002  # Module documentation
-/workflow:execute IMPL-003  # Architecture documentation
-/workflow:execute IMPL-004  # API documentation
-```
-The system creates structured documentation tasks with proper session management, task.json files, and integration with the broader workflow system for systematic and trackable documentation generation.

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

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

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

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

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

@@ -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",
@@ -305,27 +303,279 @@ For each feature, generate 3 tasks with ID format:
 
 ### Phase 4: Unified IMPL_PLAN.md Generation
 
-Generate single comprehensive IMPL_PLAN.md with:
+Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
 
 **Frontmatter**:
 ```yaml
 ---
 identifier: WFS-{session-id}
-workflow_type: "tdd"
+source: "User requirements" | "File: path" | "Issue: ISS-001"
+analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+artifacts: .workflow/{session-id}/.brainstorming/
+context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+workflow_type: "tdd"  # TDD-specific workflow
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"  # TDD workflow phases
 feature_count: N
 task_count: 3N
 tdd_chains: N
 ---
 ```
 
-**Structure**:
-1. **Summary**: Project overview
-2. **TDD Task Chains** (TDD-specific section):
-   - Visual representation of TEST → IMPL → REFACTOR chains
-   - Feature-by-feature breakdown with phase indicators
-3. **Task Breakdown**: Standard task listing
-4. **Implementation Strategy**: Execution approach
-5. **Success Criteria**: Acceptance conditions
+**Complete Structure** (8 Sections):
+
+```markdown
+# Implementation Plan: {Project Title}
+
+## 1. Summary
+Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
+
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
+
+**Technical Approach**:
+- TDD-driven development with Red-Green-Refactor cycles
+- [Other high-level approaches]
+
+## 2. Context Analysis
+
+### CCW Workflow Context
+**Phase Progression** (TDD-specific):
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Test Coverage Analysis (test-context-package.json: existing test patterns identified)
+- ✅ Phase 4: TDD Analysis (ANALYSIS_RESULTS.md: test-first requirements with Gemini/Qwen insights)
+- ✅ Phase 5: Concept Verification ({X} clarifications answered, test requirements clarified | skipped)
+- ⏳ Phase 6: TDD Task Generation (current phase - generating IMPL_PLAN.md with TDD chains)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (test requirements clarified, 0 ambiguities) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute for TDD dependency validation)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Test Context**: {existing test patterns, coverage baseline, test framework detected}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {test file count} tests identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+- **TDD Framework**: Testing framework and tools
+
+### Module Structure
+```
+[Directory tree showing key modules and test directories]
+```
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**Testing**: [Test framework, mocking libraries]
+**Development**: [Linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns]
+- **Testing Patterns**: [Unit, integration, E2E patterns]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every TDD task (TEST/IMPL/REFACTOR) references this for requirements and acceptance criteria
+- **How**: Extract testable requirements, architecture decisions, expected behaviors
+- **Priority**: Authoritative - defines what to test and how to implement
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth for TDD
+
+**Context Intelligence (context-package.json & test-context-package.json)**:
+- **What**: Smart context from CCW's context-gather and test-context-gather phases
+- **Content**: Focus paths, dependency graph, existing test patterns, test framework configuration
+- **Usage**: RED phase loads test patterns, GREEN phase loads implementation context
+- **CCW Value**: Automated discovery of existing tests and patterns for TDD consistency
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen parallel analysis with TDD-specific breakdown
+- **Content**: Testable requirements, test scenarios, implementation strategies, risk assessment
+- **Usage**: RED phase references test cases, GREEN phase references implementation approach
+- **CCW Value**: Multi-model analysis providing comprehensive TDD guidance
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, functional/non-functional requirements
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Discussion framework
+- **system-architect/analysis.md**: Architecture specifications
+- **Role-specific analyses**: [Other relevant analyses]
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for test cases and implementation)
+2. test-context-package.json (existing test patterns for TDD consistency)
+3. context-package.json (smart context for execution environment)
+4. ANALYSIS_RESULTS.md (technical analysis with TDD breakdown)
+5. Role-specific analyses (supplementary)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: TDD Cycles (Red-Green-Refactor)
+
+**Rationale**: Test-first approach ensures correctness and reduces bugs
+
+**TDD Cycle Pattern**:
+- RED: Write failing test
+- GREEN: Implement minimal code to pass (with test-fix cycle if needed)
+- REFACTOR: Improve code quality while keeping tests green
+
+**Parallelization Opportunities**:
+- [Independent features that can be developed in parallel]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [TDD-compatible architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [Test isolation strategy]
+
+### Key Dependencies
+**Task Dependency Graph**:
+```
+Feature 1:
+  TEST-1.1 (RED)
+      ↓
+  IMPL-1.1 (GREEN) [with test-fix cycle]
+      ↓
+  REFACTOR-1.1 (REFACTOR)
+
+Feature 2:
+  TEST-2.1 (RED) [depends on REFACTOR-1.1 if related]
+      ↓
+  IMPL-2.1 (GREEN)
+      ↓
+  REFACTOR-2.1 (REFACTOR)
+```
+
+**Critical Path**: [Identify bottleneck features]
+
+### Testing Strategy
+**TDD Testing Approach**:
+- Unit testing: Each feature has comprehensive unit tests
+- Integration testing: Cross-feature integration
+- E2E testing: Critical user flows after all TDD cycles
+
+**Coverage Targets**:
+- Lines: ≥80% (TDD ensures high coverage)
+- Functions: ≥80%
+- Branches: ≥75%
+
+**Quality Gates**:
+- All tests must pass before moving to next phase
+- Refactor phase must maintain test success
+
+## 5. TDD Task Chains (TDD-Specific Section)
+
+### Feature-by-Feature TDD Chains
+
+**Feature 1: {Feature Name}**
+```
+🔴 TEST-1.1: Write failing test for {feature}
+    ↓
+🟢 IMPL-1.1: Implement to pass tests (includes test-fix cycle: max 3 iterations)
+    ↓
+🔵 REFACTOR-1.1: Refactor implementation while keeping tests green
+```
+
+**Feature 2: {Feature Name}**
+```
+🔴 TEST-2.1: Write failing test for {feature}
+    ↓
+🟢 IMPL-2.1: Implement to pass tests (includes test-fix cycle)
+    ↓
+🔵 REFACTOR-2.1: Refactor implementation
+```
+
+[Continue for all N features]
+
+### TDD Task Breakdown Summary
+- **Total Features**: {N}
+- **Total Tasks**: {3N} (N TEST + N IMPL + N REFACTOR)
+- **TDD Chains**: {N}
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**TDD Cycle Execution**: Feature-by-feature sequential TDD cycles
+
+**Phase 1 (Weeks 1-2): Foundation Features**
+- **Features**: Feature 1, Feature 2
+- **Tasks**: TEST-1.1, IMPL-1.1, REFACTOR-1.1, TEST-2.1, IMPL-2.1, REFACTOR-2.1
+- **Deliverables**:
+  - Complete TDD cycles for foundation features
+  - All tests passing
+- **Success Criteria**:
+  - ≥80% test coverage
+  - All RED-GREEN-REFACTOR cycles completed
+
+**Phase 2 (Weeks 3-N): Advanced Features**
+[Continue with remaining features]
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition with TDD experience]
+
+**External Dependencies**:
+- [Testing frameworks, mocking services]
+
+**Infrastructure**:
+- [CI/CD with test automation]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| Tests fail repeatedly in GREEN phase | High | Medium | Test-fix cycle (max 3 iterations) with auto-revert | Dev Team |
+| Complex features hard to test | High | Medium | Break down into smaller testable units | Architect |
+| [Other risks] | Med/Low | Med/Low | [Strategies] | [Owner] |
+
+**Critical Risks** (TDD-Specific):
+- **GREEN phase failures**: Mitigated by test-fix cycle with Gemini diagnosis
+- **Test coverage gaps**: Mitigated by TDD-first approach ensuring tests before code
+
+**Monitoring Strategy**:
+- Track TDD cycle completion rate
+- Monitor test success rate per iteration
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All features implemented through TDD cycles
+- [ ] All RED-GREEN-REFACTOR cycles completed successfully
+
+**Technical Quality**:
+- [ ] Test coverage ≥80% (ensured by TDD)
+- [ ] All tests passing (GREEN state achieved)
+- [ ] Code refactored for quality (REFACTOR phase completed)
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline with automated test execution
+- [ ] Test failure alerting configured
+
+**TDD Compliance**:
+- [ ] Every feature has TEST → IMPL → REFACTOR chain
+- [ ] No implementation without tests (RED-first principle)
+- [ ] Refactoring did not break tests
+```
 
 ### Phase 5: TODO_LIST.md Generation
 

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

@@ -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
@@ -240,33 +317,229 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 identifier: WFS-{session-id}
 source: "User requirements" | "File: path" | "Issue: ISS-001"
 analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+artifacts: .workflow/{session-id}/.brainstorming/
+context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+workflow_type: "standard | tdd | design"  # Indicates execution model
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
 ---
 
 # Implementation Plan: {Project Title}
 
-## Summary
-Core requirements, objectives, and technical approach.
+## 1. Summary
+Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
-## Context Analysis
-- **Project**: Type, patterns, tech stack
-- **Modules**: Components and integration points
-- **Dependencies**: External libraries and constraints
-- **Patterns**: Code conventions and guidelines
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
 
-## Brainstorming Artifacts
-- synthesis-specification.md (Highest priority)
-- topic-framework.md (Medium priority)
-- Role analyses: ui-designer, system-architect, etc.
+**Technical Approach**:
+- [High-level approach]
 
-## Task Breakdown
-- **Task Count**: N tasks, complexity level
-- **Hierarchy**: Flat/Two-level structure
-- **Dependencies**: Task dependency graph
+## 2. Context Analysis
 
-## Implementation Plan
-- **Execution Strategy**: Sequential/Parallel approach
-- **Resource Requirements**: Tools, dependencies, artifacts
-- **Success Criteria**: Metrics and acceptance conditions
+### CCW Workflow Context
+**Phase Progression**:
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
+- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
+- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+
+### Module Structure
+```
+[Directory tree showing key modules]
+```
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**APIs**: [External services]
+**Development**: [Testing, linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns like DI, Event-Driven]
+- **Component Design**: [Design patterns]
+- **State Management**: [State strategy]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every task references this first for requirements and design decisions
+- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
+- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
+
+**Context Intelligence (context-package.json)**:
+- **What**: Smart context gathered by CCW's context-gather phase
+- **Content**: Focus paths, dependency graph, existing patterns, module structure
+- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup
+- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen/Codex parallel analysis results
+- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
+- **Usage**: Referenced in task planning for technical guidance and risk mitigation
+- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Role-specific discussion points and analysis framework
+- **system-architect/analysis.md**: Detailed architecture specifications
+- **ui-designer/analysis.md**: Layout and component specifications
+- **product-manager/analysis.md**: Product vision and user stories
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for all tasks)
+2. context-package.json (smart context for execution environment)
+3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
+4. Role-specific analyses (fallback for detailed specifications)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
+
+**Rationale**: [Why this execution model fits the project]
+
+**Parallelization Opportunities**:
+- [List independent workstreams]
+
+**Serialization Requirements**:
+- [List critical dependencies]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [Justification for architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [State management approach]
+
+### Key Dependencies
+**Task Dependency Graph**:
+```
+[High-level dependency visualization]
+```
+
+**Critical Path**: [Identify bottleneck tasks]
+
+### Testing Strategy
+**Testing Approach**:
+- Unit testing: [Tools, scope]
+- Integration testing: [Key integration points]
+- E2E testing: [Critical user flows]
+
+**Coverage Targets**:
+- Lines: ≥70%
+- Functions: ≥70%
+- Branches: ≥65%
+
+**Quality Gates**:
+- [CI/CD gates]
+- [Performance budgets]
+
+## 5. Task Breakdown Summary
+
+### Task Count
+**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
+
+### Task Structure
+- **IMPL-1**: [Main task title]
+- **IMPL-2**: [Main task title]
+...
+
+### Complexity Assessment
+- **High**: [List with rationale]
+- **Medium**: [List]
+- **Low**: [List]
+
+### Dependencies
+[Reference Section 4.3 for dependency graph]
+
+**Parallelization Opportunities**:
+- [Specific task groups that can run in parallel]
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**Phase 1 (Weeks 1-2): [Phase Name]**
+- **Tasks**: IMPL-1, IMPL-2
+- **Deliverables**:
+  - [Specific deliverable 1]
+  - [Specific deliverable 2]
+- **Success Criteria**:
+  - [Measurable criterion]
+
+**Phase 2 (Weeks 3-N): [Phase Name]**
+...
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition and skills]
+
+**External Dependencies**:
+- [Third-party services, APIs]
+
+**Infrastructure**:
+- [Development, staging, production environments]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
+
+**Critical Risks** (High impact + High probability):
+- [Risk 1]: [Detailed mitigation plan]
+
+**Monitoring Strategy**:
+- [How risks will be monitored]
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All acceptance criteria from task.json files met
+
+**Technical Quality**:
+- [ ] Test coverage ≥70%
+- [ ] Bundle size within budget
+- [ ] Performance targets met
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline operational
+- [ ] Monitoring and logging configured
+- [ ] Documentation complete
+
+**Business Metrics**:
+- [ ] [Key business metrics from synthesis]
 ```
 
 ### Phase 5: TODO_LIST.md Generation
@@ -347,8 +620,82 @@ Core requirements, objectives, and technical approach.
 /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,475 @@
+---
+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-extraction/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: Validate Design Tokens
+```bash
+# Check design tokens exist
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
+
+# Load design space analysis (optional, from intermediates)
+IF exists({base_path}/.intermediates/style-analysis/design-space-analysis.json):
+    design_space_analysis = Read({base_path}/.intermediates/style-analysis/design-space-analysis.json)
+```
+
+**Output**: `design_tokens_valid`, `design_space_analysis`
+
+### Step 3: Gather Layout Inspiration (Reuse or Create)
+```bash
+# Check if layout inspirations already exist from layout-extract phase
+inspiration_source = "{base_path}/.intermediates/layout-analysis/inspirations"
+
+FOR target IN target_list:
+    # Priority 1: Reuse existing inspiration from layout-extract
+    IF exists({inspiration_source}/{target}-layout-ideas.txt):
+        # Reuse existing inspiration (no action needed)
+        REPORT: "Using existing layout inspiration for {target}"
+    ELSE:
+        # Priority 2: Generate new inspiration via MCP
+        bash(mkdir -p {inspiration_source})
+        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 inspiration file to centralized location
+        Write({inspiration_source}/{target}-layout-ideas.txt, inspiration_content)
+        REPORT: "Created new layout inspiration for {target}"
+```
+
+**Output**: `T` inspiration text files (reused or created in `.intermediates/layout-analysis/inspirations/`)
+
+## 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}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt")
+  - Design tokens: Read("{base_path}/style-extraction/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: Production-ready (WCAG AA compliant)
+
+Generated Files:
+{base_path}/prototypes/
+├── {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)
+
+Layout Inspirations:
+{base_path}/.intermediates/layout-analysis/inspirations/ ({T} text files, reused or created)
+
+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-extraction/style-* -d | wc -l)
+
+# Check design tokens exist
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
+```
+
+### 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 prototypes directory
+bash(mkdir -p {base_path}/prototypes)
+
+# Create inspirations directory (if needed)
+bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
+
+# Run preview script
+bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/
+│   └── layout-analysis/
+│       └── inspirations/
+│           └── {target}-layout-ideas.txt  # Layout inspiration (reused or created)
+├── prototypes/
+│   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+│   ├── {target}-style-{s}-layout-{l}.css
+│   ├── compare.html
+│   ├── index.html
+│   └── PREVIEW.md
+└── style-extraction/
+    └── style-{s}/
+        ├── design-tokens.json
+        └── style-guide.md
+```
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No design tokens found
+→ Run /workflow:ui-design:style-extract first
+
+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**:
+- Required: Prompt, design-tokens.json
+- Optional: design-space-analysis.json (from `.intermediates/style-analysis/`)
+- Reuses: Layout inspirations from `.intermediates/layout-analysis/inspirations/` (if available from layout-extract)
+
+**Output**: S×L×T prototypes for `/workflow:ui-design:update`
+**Compatible**: style-extract, explore-auto, imitate-auto outputs
+**Optimization**: Reuses layout inspirations from layout-extract phase, avoiding duplicate MCP searches
+
+## 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/explore-auto.md

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

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

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

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

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

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

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

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

@@ -0,0 +1,443 @@
+---
+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 2.5: Extract DOM Structure (URL Mode - Enhancement)
+```bash
+# If URLs are available, extract real DOM structure
+# This provides accurate layout data to supplement visual analysis
+
+# For each URL in url_list:
+IF url_available AND mcp_chrome_devtools_available:
+    # Read extraction script
+    Read(~/.claude/scripts/extract-layout-structure.js)
+
+    # Open page in Chrome DevTools
+    mcp__chrome-devtools__navigate_page(url="{target_url}")
+
+    # Execute layout extraction script
+    result = mcp__chrome-devtools__evaluate_script(function="[SCRIPT_CONTENT]")
+
+    # Save DOM structure for this target (intermediate file)
+    bash(mkdir -p {base_path}/.intermediates/layout-analysis)
+    Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
+
+    dom_structure_available = true
+ELSE:
+    dom_structure_available = false
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-layout-structure.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
+- `structure`: Hierarchical DOM tree with layout properties
+
+**Benefits**:
+- ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
+- ✅ Accurate element bounds (x, y, width, height)
+- ✅ Structural hierarchy with depth control
+- ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
+
+### Step 3: Memory Check
+```bash
+# 1. Check if inputs cached in session memory
+IF session_has_inputs: SKIP Step 2 file reading
+
+# 2. Check if output already exists
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+IF exists: SKIP to completion
+```
+
+---
+
+**Phase 0 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}/.intermediates/layout-analysis/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}/.intermediates/layout-analysis/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 + "/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt')" : ""}
+  ${dom_structure_available ? "- DOM Structure Data: Read('" + base_path + "/.intermediates/layout-analysis/dom-structure-{target}.json') - USE THIS for accurate layout properties" : ""}
+
+  ## Analysis & Generation
+  ${dom_structure_available ? "IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties, bounds, and hierarchy. Use this data as ground truth for layout analysis." : ""}
+  For EACH target in {targets}:
+    For EACH variant (1 to {variants_count}):
+      1. **Analyze Structure**:
+         ${dom_structure_available ?
+           "- Use DOM structure data as primary source for layout properties" +
+           "- Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)" +
+           "- Use actual element bounds for responsive breakpoint decisions" +
+           "- Preserve identified patterns (flex-row, flex-column, grid-NCol)" +
+           "- Reference screenshots for visual context only" :
+           "- Deconstruct reference images/URLs to understand layout, hierarchy, responsiveness"}
+      2. **Define Philosophy**: Short description (e.g., "Asymmetrical grid with overlapping content areas")
+      3. **Generate DOM Structure**:
+         ${dom_structure_available ?
+           "- Base structure on extracted DOM tree from .intermediates" +
+           "- Preserve semantic tags and hierarchy from dom-structure-{target}.json" +
+           "- Maintain layout patterns identified in patterns field" :
+           "- 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**:
+         ${dom_structure_available ?
+           "- Use real layout properties from DOM structure data" +
+           "- Convert extracted flex/grid values to CSS rules" +
+           "- Preserve actual gap, justifyContent, alignItems values" +
+           "- Use element bounds to inform responsive breakpoints" :
+           "- 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}/.intermediates/layout-analysis/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}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, content)
+
+# Write layout templates
+bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                    # Intermediate analysis files
+│   └── layout-analysis/
+│       ├── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
+│       └── inspirations/                 # Explore mode only
+│           └── {target}-layout-ideas.txt # Layout inspiration research
+└── layout-extraction/                 # Final layout templates
+    ├── layout-templates.json          # Structural layout templates
+    └── layout-space-analysis.json     # Layout directions (explore mode only)
+```
+
+## 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
+
+- **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
+- **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
+- **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
+- **Graceful Fallback** - Works with images/text when URL unavailable
+- **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` → `design-tokens.json` + `style-guide.md` (Complete design systems)
+2. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
+3. `/workflow:ui-design:generate` (Pure 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,391 @@
+---
+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. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
+
+**Strategy**: AI-Driven Design Space Exploration
+- **Claude-Native**: 100% Claude analysis, no external tools
+- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
+- **Flexible Input**: Images, text prompts, or both (hybrid mode)
+- **Maximum Contrast**: AI generates maximally divergent design directions
+- **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
+
+## 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: Extract Computed Styles (URL Mode - Optional Enhancement)
+```bash
+# If URL is available from capture metadata, extract real CSS values
+# This provides accurate design tokens to supplement visual analysis
+
+# Check for URL metadata from capture phase
+Read({base_path}/.metadata/capture-urls.json)  # If exists
+
+# For each URL in capture metadata:
+IF url_available AND mcp_chrome_devtools_available:
+    # Read extraction script
+    Read(~/.claude/scripts/extract-computed-styles.js)
+
+    # Open page in Chrome DevTools
+    mcp__chrome-devtools__navigate_page(url="{target_url}")
+
+    # Execute extraction script directly
+    result = mcp__chrome-devtools__evaluate_script(function="[SCRIPT_CONTENT]")
+
+    # Save computed styles to intermediates directory
+    bash(mkdir -p {base_path}/.intermediates/style-analysis)
+    Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
+
+    computed_styles_available = true
+ELSE:
+    computed_styles_available = false
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `tokens`: Organized design tokens (colors, borderRadii, shadows, fontSizes, fontWeights, spacing)
+
+**Benefits**:
+- ✅ Pixel-perfect accuracy for border-radius, box-shadow, padding, etc.
+- ✅ Eliminates guessing from visual analysis
+- ✅ Provides ground truth for design tokens
+
+### Step 3: 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
+```bash
+# 1. Check if inputs cached in session memory
+IF session_has_inputs: SKIP Step 2 file reading
+
+# 2. Check if output already exists
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
+IF exists: SKIP to completion
+```
+
+---
+
+**Phase 0 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(mkdir -p {base_path}/.intermediates/style-analysis)
+bash(echo '{design_space_analysis}' > {base_path}/.intermediates/style-analysis/design-space-analysis.json)
+
+# Verify output
+bash(test -f {base_path}/.intermediates/style-analysis/design-space-analysis.json && echo "saved")
+```
+
+**Output**: `design-space-analysis.json` (intermediate analysis file)
+
+## Phase 2: Design System Generation (Agent)
+
+**Executor**: `Task(ui-design-agent)` for all variants
+
+### Step 1: Create Output Directories
+```bash
+bash(mkdir -p {base_path}/style-extraction/style-{{1..{variants_count}}})
+```
+
+### Step 2: Launch Agent Task
+For all variants (1 to {variants_count}):
+```javascript
+Task(ui-design-agent): `
+  [DESIGN_SYSTEM_GENERATION_TASK]
+  Generate {variants_count} independent production-ready design systems
+
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+
+  CRITICAL PATH: Use loop index (N) for directories: style-1/, style-2/, ..., style-N/
+
+  VARIANT DATA:
+  {FOR each variant with index N:
+    VARIANT INDEX: {N}
+    {IF extraction_mode == "explore":
+      Design Philosophy: {divergent_direction[N].philosophy_name}
+      Design Attributes: {divergent_direction[N].design_attributes}
+      Search Keywords: {divergent_direction[N].search_keywords}
+      Anti-keywords: {divergent_direction[N].anti_keywords}
+    }
+  }
+
+  ## Input Analysis
+  - Input mode: {input_mode} (image/text/hybrid)
+  - Visual references: {loaded_images OR prompt_guidance}
+  - Computed styles: {computed_styles if available}
+  - Design space analysis: {design_space_analysis if explore mode}
+
+  ## Analysis Rules
+  - **Explore mode**: Each variant follows pre-defined philosophy and attributes
+  - **Imitate mode**: High-fidelity replication of reference design
+    - If computed_styles available: Use as ground truth for border-radius, shadows, spacing, typography, colors
+    - Otherwise: Visual inference
+  - OKLCH color format (convert RGB from computed styles)
+  - WCAG AA compliance: 4.5:1 text, 3:1 UI
+
+  ## Generate (For EACH variant, use loop index N for paths)
+  1. {base_path}/style-extraction/style-{N}/design-tokens.json
+     - Complete token structure: colors, typography, spacing, border_radius, shadows, breakpoints
+     - All colors in OKLCH format
+     - {IF explore mode: Apply design_attributes to token values (saturation→chroma, density→spacing, etc.)}
+
+  2. {base_path}/style-extraction/style-{N}/style-guide.md
+     - Expanded design philosophy
+     - Complete color system with accessibility notes
+     - Typography documentation
+     - Usage guidelines
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for each file
+  - ✅ Use loop index N for directory names: style-1/, style-2/, etc.
+  - ❌ NO external research or MCP calls (pure AI generation)
+  - {IF explore mode: Apply philosophy-driven refinement using design_attributes}
+  - {IF explore mode: Maintain divergence using anti_keywords}
+  - Complete each variant's files before moving to next variant
+`
+```
+
+**Output**: Agent generates `variants_count × 2` files
+
+## Phase 3: Verify Output
+
+### Step 1: Check Files Created
+```bash
+# Verify all design systems created
+bash(ls {base_path}/style-extraction/style-*/design-tokens.json | wc -l)
+
+# Validate structure
+bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
+```
+
+### Step 2: Verify File Sizes
+```bash
+bash(ls -lh {base_path}/style-extraction/style-1/)
+```
+
+**Output**: `variants_count × 2` files verified
+
+## 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: "Design system generation (agent)", status: "completed", activeForm: "Generating design systems"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+### 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}
+- Production-Ready: Complete design systems generated
+
+{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 Files:
+{base_path}/style-extraction/
+├── style-1/ (design-tokens.json, style-guide.md)
+├── style-2/ (same structure)
+└── style-{variants_count}/ (same structure)
+
+{IF extraction_mode == "explore":
+Intermediate Analysis:
+{base_path}/.intermediates/style-analysis/design-space-analysis.json
+}
+
+Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
+  OR: /workflow:ui-design:generate --session {session_id}
+```
+
+## 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-1/design-tokens.json && echo "exists")
+
+# Count variants
+bash(ls {base_path}/style-extraction/style-* -d | wc -l)
+
+# Validate JSON structure
+bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
+```
+
+### File Operations
+```bash
+# Load brainstorming context
+bash(test -f .brainstorming/synthesis-specification.md && cat it)
+
+# Create directories
+bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
+
+# Verify output
+bash(ls {base_path}/style-extraction/style-1/)
+bash(test -f {base_path}/.intermediates/style-analysis/design-space-analysis.json && echo "saved")
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                  # Intermediate analysis files
+│   └── style-analysis/
+│       ├── computed-styles.json     # Extracted CSS values from DOM (if URL available)
+│       └── design-space-analysis.json  # Design directions (explore mode only)
+└── style-extraction/                # Final design systems
+    ├── style-1/
+    │   ├── design-tokens.json       # Production-ready design tokens
+    │   └── style-guide.md           # Design philosophy and usage guide
+    ├── style-2/ (same structure)
+    └── style-N/ (same structure)
+```
+
+## design-tokens.json Format
+
+```json
+{
+  "colors": {
+    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+    "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
+    "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
+  },
+  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
+}
+```
+
+**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance
+
+## 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
+
+- **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
+- **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
+- **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
+- **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
+- **Flexible Input** - Images, text, URLs, or hybrid mode
+- **Graceful Fallback** - Falls back to pure visual inference if URL unavailable
+- **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
+- **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
+
+## Integration
+
+**Input**: Reference images or text prompts
+**Output**: `style-extraction/style-{N}/` with design-tokens.json + style-guide.md
+**Next**: `/workflow:ui-design:layout-extract --session {session_id}` OR `/workflow:ui-design:generate --session {session_id}`
+
+**Note**: This command extracts visual style (colors, typography, spacing) and generates production-ready design systems. For layout structure extraction, use `/workflow:ui-design:layout-extract`.

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

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

.claude/scripts/classify-folders.sh

@@ -0,0 +1,35 @@
+#!/bin/bash
+# Classify folders by type for documentation generation
+# Usage: get_modules_by_depth.sh | classify-folders.sh
+# Output: folder_path|folder_type|code:N|dirs:N
+
+while IFS='|' read -r depth_info path_info files_info types_info claude_info; do
+  # Extract folder path from format "path:./src/modules"
+  folder_path=$(echo "$path_info" | cut -d':' -f2-)
+
+  # Skip if path extraction failed
+  [[ -z "$folder_path" || ! -d "$folder_path" ]] && continue
+
+  # Count code files (maxdepth 1)
+  code_files=$(find "$folder_path" -maxdepth 1 -type f \
+    \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \
+       -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rs" \
+       -o -name "*.c" -o -name "*.cpp" -o -name "*.cs" \) \
+    2>/dev/null | wc -l)
+
+  # Count subdirectories
+  subfolders=$(find "$folder_path" -maxdepth 1 -type d \
+    -not -path "$folder_path" 2>/dev/null | wc -l)
+
+  # Determine folder type
+  if [[ $code_files -gt 0 ]]; then
+    folder_type="code"  # API.md + README.md
+  elif [[ $subfolders -gt 0 ]]; then
+    folder_type="navigation"  # README.md only
+  else
+    folder_type="skip"  # Empty or no relevant content
+  fi
+
+  # Output classification result
+  echo "${folder_path}|${folder_type}|code:${code_files}|dirs:${subfolders}"
+done

.claude/scripts/convert_tokens_to_css.sh

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

.claude/scripts/detect_changed_modules.sh

@@ -2,32 +2,88 @@
 # Detect modules affected by git changes or recent modifications
 # Usage: detect_changed_modules.sh [format]
 #   format: list|grouped|paths (default: paths)
+#
+# Features:
+# - Respects .gitignore patterns (current directory or git root)
+# - Detects git changes (staged, unstaged, or last commit)
+# - Falls back to recently modified files (last 24 hours)
+
+# Build exclusion filters from .gitignore
+build_exclusion_filters() {
+    local filters=""
+
+    # Common system/cache directories to exclude
+    local system_excludes=(
+        ".git" "__pycache__" "node_modules" ".venv" "venv" "env"
+        "dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
+        "coverage" ".nyc_output" "logs" "tmp" "temp"
+    )
+
+    for exclude in "${system_excludes[@]}"; do
+        filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
+    done
+
+    # Find and parse .gitignore (current dir first, then git root)
+    local gitignore_file=""
+
+    # Check current directory first
+    if [ -f ".gitignore" ]; then
+        gitignore_file=".gitignore"
+    else
+        # Try to find git root and check for .gitignore there
+        local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
+        if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
+            gitignore_file="$git_root/.gitignore"
+        fi
+    fi
+
+    # Parse .gitignore if found
+    if [ -n "$gitignore_file" ]; then
+        while IFS= read -r line; do
+            # Skip empty lines and comments
+            [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+
+            # Remove trailing slash and whitespace
+            line=$(echo "$line" | sed 's|/$||' | xargs)
+
+            # Skip wildcards patterns (too complex for simple find)
+            [[ "$line" =~ \* ]] && continue
+
+            # Add to filters
+            filters+=" -not -path '*/$line' -not -path '*/$line/*'"
+        done < "$gitignore_file"
+    fi
+
+    echo "$filters"
+}
 
 detect_changed_modules() {
     local format="${1:-paths}"
     local changed_files=""
     local affected_dirs=""
-    
+    local exclusion_filters=$(build_exclusion_filters)
+
     # Step 1: Try to get git changes (staged + unstaged)
     if git rev-parse --git-dir > /dev/null 2>&1; then
         changed_files=$(git diff --name-only HEAD 2>/dev/null; git diff --name-only --cached 2>/dev/null)
-        
+
         # If no changes in working directory, check last commit
         if [ -z "$changed_files" ]; then
             changed_files=$(git diff --name-only HEAD~1 HEAD 2>/dev/null)
         fi
     fi
-    
+
     # Step 2: If no git changes, find recently modified source files (last 24 hours)
+    # Apply exclusion filters from .gitignore
     if [ -z "$changed_files" ]; then
-        changed_files=$(find . -type f \( \
-            -name "*.md" -o \
-            -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o \
-            -name "*.py" -o -name "*.go" -o -name "*.rs" -o \
-            -name "*.java" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o \
-            -name "*.sh" -o -name "*.ps1" -o \
-            -name "*.json" -o -name "*.yaml" -o -name "*.yml" \
-        \) -not -path '*/.*' -mtime -1 2>/dev/null)
+        changed_files=$(eval "find . -type f \( \
+            -name '*.md' -o \
+            -name '*.js' -o -name '*.ts' -o -name '*.jsx' -o -name '*.tsx' -o \
+            -name '*.py' -o -name '*.go' -o -name '*.rs' -o \
+            -name '*.java' -o -name '*.cpp' -o -name '*.c' -o -name '*.h' -o \
+            -name '*.sh' -o -name '*.ps1' -o \
+            -name '*.json' -o -name '*.yaml' -o -name '*.yml' \
+        \) $exclusion_filters -mtime -1 2>/dev/null")
     fi
     
     # Step 3: Extract unique parent directories

.claude/scripts/extract-computed-styles.js

@@ -0,0 +1,118 @@
+/**
+ * Extract Computed Styles from DOM
+ *
+ * This script extracts real CSS computed styles from a webpage's DOM
+ * to provide accurate design tokens for UI replication.
+ *
+ * Usage: Execute this function via Chrome DevTools evaluate_script
+ */
+
+(() => {
+  /**
+   * Extract unique values from a set and sort them
+   */
+  const uniqueSorted = (set) => {
+    return Array.from(set)
+      .filter(v => v && v !== 'none' && v !== '0px' && v !== 'rgba(0, 0, 0, 0)')
+      .sort();
+  };
+
+  /**
+   * Parse rgb/rgba to OKLCH format (placeholder - returns original for now)
+   */
+  const toOKLCH = (color) => {
+    // TODO: Implement actual RGB to OKLCH conversion
+    // For now, return the original color with a note
+    return `${color} /* TODO: Convert to OKLCH */`;
+  };
+
+  /**
+   * Extract only key styles from an element
+   */
+  const extractKeyStyles = (element) => {
+    const s = window.getComputedStyle(element);
+    return {
+      color: s.color,
+      bg: s.backgroundColor,
+      borderRadius: s.borderRadius,
+      boxShadow: s.boxShadow,
+      fontSize: s.fontSize,
+      fontWeight: s.fontWeight,
+      padding: s.padding,
+      margin: s.margin
+    };
+  };
+
+  /**
+   * Main extraction function - extract all critical design tokens
+   */
+  const extractDesignTokens = () => {
+    // Include all key UI elements
+    const selectors = [
+      'button', '.btn', '[role="button"]',
+      'input', 'textarea', 'select',
+      'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+      '.card', 'article', 'section',
+      'a', 'p', 'nav', 'header', 'footer'
+    ];
+
+    // Collect all design tokens
+    const tokens = {
+      colors: new Set(),
+      borderRadii: new Set(),
+      shadows: new Set(),
+      fontSizes: new Set(),
+      fontWeights: new Set(),
+      spacing: new Set()
+    };
+
+    // Extract from all elements
+    selectors.forEach(selector => {
+      try {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+          const s = extractKeyStyles(element);
+
+          // Collect all tokens (no limits)
+          if (s.color && s.color !== 'rgba(0, 0, 0, 0)') tokens.colors.add(s.color);
+          if (s.bg && s.bg !== 'rgba(0, 0, 0, 0)') tokens.colors.add(s.bg);
+          if (s.borderRadius && s.borderRadius !== '0px') tokens.borderRadii.add(s.borderRadius);
+          if (s.boxShadow && s.boxShadow !== 'none') tokens.shadows.add(s.boxShadow);
+          if (s.fontSize) tokens.fontSizes.add(s.fontSize);
+          if (s.fontWeight) tokens.fontWeights.add(s.fontWeight);
+
+          // Extract all spacing values
+          [s.padding, s.margin].forEach(val => {
+            if (val && val !== '0px') {
+              val.split(' ').forEach(v => {
+                if (v && v !== '0px') tokens.spacing.add(v);
+              });
+            }
+          });
+        });
+      } catch (e) {
+        console.warn(`Error: ${selector}`, e);
+      }
+    });
+
+    // Return all tokens (no element details to save context)
+    return {
+      metadata: {
+        extractedAt: new Date().toISOString(),
+        url: window.location.href,
+        method: 'computed-styles'
+      },
+      tokens: {
+        colors: uniqueSorted(tokens.colors),
+        borderRadii: uniqueSorted(tokens.borderRadii),  // ALL radius values
+        shadows: uniqueSorted(tokens.shadows),          // ALL shadows
+        fontSizes: uniqueSorted(tokens.fontSizes),
+        fontWeights: uniqueSorted(tokens.fontWeights),
+        spacing: uniqueSorted(tokens.spacing)
+      }
+    };
+  };
+
+  // Execute and return results
+  return extractDesignTokens();
+})();

.claude/scripts/extract-layout-structure.js

@@ -0,0 +1,221 @@
+/**
+ * Extract Layout Structure from DOM
+ *
+ * Extracts real layout information from DOM to provide accurate
+ * structural data for UI replication.
+ *
+ * Usage: Execute via Chrome DevTools evaluate_script
+ */
+
+(() => {
+  /**
+   * Get element's bounding box relative to viewport
+   */
+  const getBounds = (element) => {
+    const rect = element.getBoundingClientRect();
+    return {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height)
+    };
+  };
+
+  /**
+   * Extract layout properties from an element
+   */
+  const extractLayoutProps = (element) => {
+    const s = window.getComputedStyle(element);
+
+    return {
+      // Core layout
+      display: s.display,
+      position: s.position,
+
+      // Flexbox
+      flexDirection: s.flexDirection,
+      justifyContent: s.justifyContent,
+      alignItems: s.alignItems,
+      flexWrap: s.flexWrap,
+      gap: s.gap,
+
+      // Grid
+      gridTemplateColumns: s.gridTemplateColumns,
+      gridTemplateRows: s.gridTemplateRows,
+      gridAutoFlow: s.gridAutoFlow,
+
+      // Dimensions
+      width: s.width,
+      height: s.height,
+      maxWidth: s.maxWidth,
+      minWidth: s.minWidth,
+
+      // Spacing
+      padding: s.padding,
+      margin: s.margin
+    };
+  };
+
+  /**
+   * Identify layout pattern for an element
+   */
+  const identifyPattern = (props) => {
+    const { display, flexDirection, gridTemplateColumns } = props;
+
+    if (display === 'flex') {
+      if (flexDirection === 'column') return 'flex-column';
+      if (flexDirection === 'row') return 'flex-row';
+      return 'flex';
+    }
+
+    if (display === 'grid') {
+      const cols = gridTemplateColumns;
+      if (cols && cols !== 'none') {
+        const colCount = cols.split(' ').length;
+        return `grid-${colCount}col`;
+      }
+      return 'grid';
+    }
+
+    if (display === 'inline-flex') return 'inline-flex';
+    if (display === 'block') return 'block';
+
+    return display;
+  };
+
+  /**
+   * Build layout tree recursively
+   */
+  const buildLayoutTree = (element, depth = 0, maxDepth = 3) => {
+    if (depth > maxDepth) return null;
+
+    const props = extractLayoutProps(element);
+    const bounds = getBounds(element);
+    const pattern = identifyPattern(props);
+
+    // Get semantic role
+    const tagName = element.tagName.toLowerCase();
+    const classes = Array.from(element.classList).slice(0, 3); // Max 3 classes
+    const role = element.getAttribute('role');
+
+    // Build node
+    const node = {
+      tag: tagName,
+      classes: classes,
+      role: role,
+      pattern: pattern,
+      bounds: bounds,
+      layout: {
+        display: props.display,
+        position: props.position
+      }
+    };
+
+    // Add flex/grid specific properties
+    if (props.display === 'flex' || props.display === 'inline-flex') {
+      node.layout.flexDirection = props.flexDirection;
+      node.layout.justifyContent = props.justifyContent;
+      node.layout.alignItems = props.alignItems;
+      node.layout.gap = props.gap;
+    }
+
+    if (props.display === 'grid') {
+      node.layout.gridTemplateColumns = props.gridTemplateColumns;
+      node.layout.gridTemplateRows = props.gridTemplateRows;
+      node.layout.gap = props.gap;
+    }
+
+    // Process children for container elements
+    if (props.display === 'flex' || props.display === 'grid' || props.display === 'block') {
+      const children = Array.from(element.children);
+      if (children.length > 0 && children.length < 50) { // Limit to 50 children
+        node.children = children
+          .map(child => buildLayoutTree(child, depth + 1, maxDepth))
+          .filter(child => child !== null);
+      }
+    }
+
+    return node;
+  };
+
+  /**
+   * Find main layout containers
+   */
+  const findMainContainers = () => {
+    const selectors = [
+      'body > header',
+      'body > nav',
+      'body > main',
+      'body > footer',
+      '[role="banner"]',
+      '[role="navigation"]',
+      '[role="main"]',
+      '[role="contentinfo"]'
+    ];
+
+    const containers = [];
+
+    selectors.forEach(selector => {
+      const element = document.querySelector(selector);
+      if (element) {
+        const tree = buildLayoutTree(element, 0, 3);
+        if (tree) {
+          containers.push(tree);
+        }
+      }
+    });
+
+    return containers;
+  };
+
+  /**
+   * Analyze layout patterns
+   */
+  const analyzePatterns = (containers) => {
+    const patterns = {
+      flexColumn: 0,
+      flexRow: 0,
+      grid: 0,
+      sticky: 0,
+      fixed: 0
+    };
+
+    const analyze = (node) => {
+      if (!node) return;
+
+      if (node.pattern === 'flex-column') patterns.flexColumn++;
+      if (node.pattern === 'flex-row') patterns.flexRow++;
+      if (node.pattern && node.pattern.startsWith('grid')) patterns.grid++;
+      if (node.layout.position === 'sticky') patterns.sticky++;
+      if (node.layout.position === 'fixed') patterns.fixed++;
+
+      if (node.children) {
+        node.children.forEach(analyze);
+      }
+    };
+
+    containers.forEach(analyze);
+    return patterns;
+  };
+
+  /**
+   * Main extraction function
+   */
+  const extractLayout = () => {
+    const containers = findMainContainers();
+    const patterns = analyzePatterns(containers);
+
+    return {
+      metadata: {
+        extractedAt: new Date().toISOString(),
+        url: window.location.href,
+        method: 'layout-structure'
+      },
+      patterns: patterns,
+      structure: containers
+    };
+  };
+
+  // Execute and return results
+  return extractLayout();
+})();

.claude/scripts/gemini-wrapper

@@ -52,6 +52,12 @@ GREEN='\033[0;32m'
 YELLOW='\033[1;33m'
 NC='\033[0m' # No Color
 
+# Respect custom Gemini base URL
+if [[ -n "$GOOGLE_GEMINI_BASE_URL" ]]; then
+    echo -e "${GREEN}🌐 Using custom Gemini base URL: $GOOGLE_GEMINI_BASE_URL${NC}" >&2
+    export GOOGLE_GEMINI_BASE_URL
+fi
+
 # Function to count tokens (approximate: chars/4) - optimized version
 count_tokens() {
     local total_chars=0

.claude/scripts/get_modules_by_depth.sh

@@ -58,7 +58,7 @@ build_exclusion_filters() {
 
         # OS and editor files
         ".DS_Store" "Thumbs.db" "desktop.ini"
-        "*.stackdump" "core" "*.core"
+        "*.stackdump" "*.core"
 
         # Cloud and deployment
         ".serverless" ".terraform" "terraform.tfstate"

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

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

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

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

.claude/scripts/update_module_claude.sh

@@ -1,72 +1,101 @@
 #!/bin/bash
-# Update CLAUDE.md for a specific module with automatic layer detection
+# Update CLAUDE.md for a specific module with unified template
 # Usage: update_module_claude.sh <module_path> [update_type] [tool]
 #   module_path: Path to the module directory
 #   update_type: full|related (default: full)
 #   tool: gemini|qwen|codex (default: gemini)
-#   Script automatically detects layer depth and selects appropriate template
+#
+# Features:
+# - Respects .gitignore patterns (current directory or git root)
+# - Unified template for all modules (folders and files)
+# - Template-based documentation generation
+
+# Build exclusion filters from .gitignore
+build_exclusion_filters() {
+    local filters=""
+
+    # Common system/cache directories to exclude
+    local system_excludes=(
+        ".git" "__pycache__" "node_modules" ".venv" "venv" "env"
+        "dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
+        "coverage" ".nyc_output" "logs" "tmp" "temp"
+    )
+
+    for exclude in "${system_excludes[@]}"; do
+        filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
+    done
+
+    # Find and parse .gitignore (current dir first, then git root)
+    local gitignore_file=""
+
+    # Check current directory first
+    if [ -f ".gitignore" ]; then
+        gitignore_file=".gitignore"
+    else
+        # Try to find git root and check for .gitignore there
+        local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
+        if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
+            gitignore_file="$git_root/.gitignore"
+        fi
+    fi
+
+    # Parse .gitignore if found
+    if [ -n "$gitignore_file" ]; then
+        while IFS= read -r line; do
+            # Skip empty lines and comments
+            [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+
+            # Remove trailing slash and whitespace
+            line=$(echo "$line" | sed 's|/$||' | xargs)
+
+            # Skip wildcards patterns (too complex for simple find)
+            [[ "$line" =~ \* ]] && continue
+
+            # Add to filters
+            filters+=" -not -path '*/$line' -not -path '*/$line/*'"
+        done < "$gitignore_file"
+    fi
+
+    echo "$filters"
+}
 
 update_module_claude() {
     local module_path="$1"
     local update_type="${2:-full}"
     local tool="${3:-gemini}"
-    
+
     # Validate parameters
     if [ -z "$module_path" ]; then
         echo "❌ Error: Module path is required"
         echo "Usage: update_module_claude.sh <module_path> [update_type]"
         return 1
     fi
-    
+
     if [ ! -d "$module_path" ]; then
         echo "❌ Error: Directory '$module_path' does not exist"
         return 1
     fi
-    
-    # Check if directory has files
-    local file_count=$(find "$module_path" -maxdepth 1 -type f 2>/dev/null | wc -l)
+
+    # Build exclusion filters from .gitignore
+    local exclusion_filters=$(build_exclusion_filters)
+
+    # Check if directory has files (excluding gitignored paths)
+    local file_count=$(eval "find \"$module_path\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
     if [ $file_count -eq 0 ]; then
-        echo "⚠️  Skipping '$module_path' - no files found"
+        echo "⚠️  Skipping '$module_path' - no files found (after .gitignore filtering)"
         return 0
     fi
     
-    # Determine documentation layer based on path patterns
-    local layer=""
-    local template_path=""
-    local analysis_strategy=""
-    
-    # Clean path for pattern matching
-    local clean_path=$(echo "$module_path" | sed 's|^\./||')
-    
-    # Pattern-based layer detection
-    if [ "$module_path" = "." ]; then
-        # Root directory
-        layer="Layer 1 (Root)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer1-root.txt"
-        analysis_strategy="--all-files"
-    elif [[ "$clean_path" =~ ^[^/]+$ ]]; then
-        # Top-level directories (e.g., .claude, src, tests)
-        layer="Layer 2 (Domain)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer2-domain.txt"
-        analysis_strategy="@{*/CLAUDE.md}"
-    elif [[ "$clean_path" =~ ^[^/]+/[^/]+$ ]]; then
-        # Second-level directories (e.g., .claude/scripts, src/components)
-        layer="Layer 3 (Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer3-module.txt"
-        analysis_strategy="@{*/CLAUDE.md}"
-    else
-        # Deeper directories (e.g., .claude/workflows/cli-templates/prompts)
-        layer="Layer 4 (Sub-Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer4-submodule.txt"
-        analysis_strategy="--all-files"
-    fi
+    # Use unified template for all modules
+    local template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-module-unified.txt"
+    local analysis_strategy="--all-files"
     
     # Prepare logging info
     local module_name=$(basename "$module_path")
 
     echo "⚡ Updating: $module_path"
-    echo "   Layer: $layer | Type: $update_type | Tool: $tool | Files: $file_count"
-    echo "   Template: $(basename "$template_path") | Strategy: $analysis_strategy"
+    echo "   Type: $update_type | Tool: $tool | Files: $file_count"
+    echo "   Template: $(basename "$template_path")"
     
     # Generate prompt with template injection
     local template_content=""
@@ -74,7 +103,7 @@ update_module_claude() {
         template_content=$(cat "$template_path")
     else
         echo "   ⚠️  Template not found: $template_path, using fallback"
-        template_content="Update CLAUDE.md documentation for this module following hierarchy standards."
+        template_content="Update CLAUDE.md documentation for this module: document structure, key components, dependencies, and integration points."
     fi
     
     local update_context=""
@@ -82,8 +111,7 @@ update_module_claude() {
         update_context="
         Update Mode: Complete refresh
         - Perform comprehensive analysis of all content
-        - Document patterns, architecture, and purpose
-        - Consider existing documentation hierarchy
+        - Document module structure, dependencies, and key components
         - Follow template guidelines strictly"
     else
         update_context="
@@ -96,13 +124,13 @@ update_module_claude() {
     
     local base_prompt="
     ⚠️ CRITICAL RULES - MUST FOLLOW:
-    1. ONLY modify CLAUDE.md files at any hierarchy level
+    1. ONLY modify CLAUDE.md files
     2. NEVER modify source code files
     3. Focus exclusively on updating documentation
     4. Follow the template guidelines exactly
-    
+
     $template_content
-    
+
     $update_context"
     
     # Execute update
@@ -116,38 +144,21 @@ update_module_claude() {
         Module Information:
         - Name: $module_name
         - Path: $module_path
-        - Layer: $layer
-        - Tool: $tool
-        - Analysis Strategy: $analysis_strategy"
+        - Tool: $tool"
 
-        # Execute with selected tool
+        # Execute with selected tool (always use --all-files)
         case "$tool" in
             qwen)
-                if [ "$analysis_strategy" = "--all-files" ]; then
-                    qwen --all-files --yolo -p "$final_prompt" 2>&1
-                    tool_result=$?
-                else
-                    qwen --yolo -p "$analysis_strategy $final_prompt" 2>&1
-                    tool_result=$?
-                fi
+                qwen --all-files --yolo -p "$final_prompt" 2>&1
+                tool_result=$?
                 ;;
             codex)
-                if [ "$analysis_strategy" = "--all-files" ]; then
-                    codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
-                    tool_result=$?
-                else
-                    codex --full-auto exec "$final_prompt CONTEXT: $analysis_strategy" --skip-git-repo-check -s danger-full-access 2>&1
-                    tool_result=$?
-                fi
+                codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
+                tool_result=$?
                 ;;
             gemini|*)
-                if [ "$analysis_strategy" = "--all-files" ]; then
-                    gemini --all-files --yolo -p "$final_prompt" 2>&1
-                    tool_result=$?
-                else
-                    gemini --yolo -p "$analysis_strategy $final_prompt" 2>&1
-                    tool_result=$?
-                fi
+                gemini --all-files --yolo -p "$final_prompt" 2>&1
+                tool_result=$?
                 ;;
         esac
 

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

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

.claude/workflows/cli-templates/prompts/analysis/architecture.txt

@@ -1,16 +1,29 @@
-Analyze system architecture and design decisions:
+Analyze system architecture and design decisions.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Analyze system-wide structure, not just isolated components
+□ Provide file:line references for key architectural elements
+□ Distinguish between intended design and actual implementation
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify main architectural patterns and design principles
 2. Map module dependencies and component relationships
 3. Assess integration points and data flow patterns
 4. Evaluate scalability and maintainability aspects
 5. Document architectural trade-offs and design decisions
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Architectural diagrams or textual descriptions
 - Dependency mapping with specific file references
 - Integration point documentation with examples
 - Scalability assessment and bottleneck identification
+- Prioritized recommendations for architectural improvement
 
-Focus on high-level design patterns and system-wide architectural concerns.
+## VERIFICATION CHECKLIST ✓
+□ All major components and their relationships analyzed
+□ Key architectural decisions and trade-offs are documented
+□ Data flow and integration points are clearly mapped
+□ Scalability and maintainability findings are supported by evidence
+
+Focus: High-level design patterns and system-wide architectural concerns.

.claude/workflows/cli-templates/prompts/analysis/pattern.txt

@@ -1,16 +1,28 @@
-Analyze implementation patterns and code structure:
+Analyze implementation patterns and code structure.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Analyze ALL files in CONTEXT (not just samples)
+□ Provide file:line references for every pattern identified
+□ Distinguish between good patterns and anti-patterns
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify common code patterns and architectural decisions
 2. Extract reusable utilities and shared components
 3. Document existing conventions and coding standards
 4. Assess pattern consistency and identify anti-patterns
 5. Suggest improvements and optimization opportunities
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Specific file:line references for all findings
 - Code snippets demonstrating identified patterns
 - Clear recommendations for pattern improvements
-- Standards compliance assessment
+- Standards compliance assessment with priority levels
 
-Focus on actionable insights and concrete implementation guidance.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed (not partial coverage)
+□ Every pattern backed by code reference (file:line)
+□ Anti-patterns clearly distinguished from good patterns
+□ Recommendations prioritized by impact
+
+Focus: Actionable insights with concrete implementation guidance.

.claude/workflows/cli-templates/prompts/analysis/performance.txt

@@ -1,16 +1,29 @@
-Analyze performance characteristics and optimization opportunities:
+Analyze performance characteristics and optimization opportunities.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Focus on measurable metrics (e.g., latency, memory, CPU usage)
+□ Provide file:line references for all identified bottlenecks
+□ Distinguish between algorithmic and resource-based issues
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify performance bottlenecks and resource usage patterns
 2. Assess algorithm efficiency and data structure choices
 3. Evaluate caching strategies and optimization techniques
 4. Review memory management and resource cleanup
 5. Document performance metrics and improvement opportunities
 
-## Output Requirements:
-- Performance bottleneck identification with specific locations
+## OUTPUT REQUIREMENTS
+- Performance bottleneck identification with specific file:line locations
 - Algorithm complexity analysis and optimization suggestions
 - Caching pattern documentation and recommendations
 - Memory usage patterns and optimization opportunities
+- Prioritized list of performance improvements
 
-Focus on measurable performance improvements and concrete optimization strategies.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed for performance characteristics
+□ Every bottleneck is backed by a code reference (file:line)
+□ Both algorithmic and resource-related issues are covered
+□ Recommendations are prioritized by potential impact
+
+Focus: Measurable performance improvements and concrete optimization strategies.

.claude/workflows/cli-templates/prompts/analysis/quality.txt

@@ -1,16 +1,29 @@
-Analyze code quality and maintainability aspects:
+Analyze code quality and maintainability aspects.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Analyze against the project's established coding standards
+□ Provide file:line references for all quality issues
+□ Assess both implementation code and test coverage
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Assess code organization and structural quality
 2. Evaluate naming conventions and readability standards
 3. Review error handling and logging practices
 4. Analyze test coverage and testing strategies
 5. Document technical debt and improvement priorities
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Code quality metrics and specific improvement areas
 - Naming convention consistency analysis
-- Error handling pattern documentation
+- Error handling and logging pattern documentation
 - Test coverage assessment with gap identification
+- Prioritized list of technical debt to address
 
-Focus on maintainability improvements and long-term code health.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed for code quality
+□ Every finding is backed by a code reference (file:line)
+□ Both code and test quality have been evaluated
+□ Recommendations are prioritized by impact on maintainability
+
+Focus: Maintainability improvements and long-term code health.

.claude/workflows/cli-templates/prompts/analysis/security.txt

@@ -1,16 +1,29 @@
-Analyze security implementation and potential vulnerabilities:
+Analyze security implementation and potential vulnerabilities.
 
-## Required Analysis:
+## CORE CHECKLIST ⚡
+□ Identify all data entry points and external system interfaces
+□ Provide file:line references for all potential vulnerabilities
+□ Classify risks by severity and type (e.g., OWASP Top 10)
+□ Apply RULES template requirements exactly as specified
+
+## REQUIRED ANALYSIS
 1. Identify authentication and authorization mechanisms
 2. Assess input validation and sanitization practices
 3. Review data encryption and secure storage methods
 4. Evaluate API security and access control patterns
 5. Document security risks and compliance considerations
 
-## Output Requirements:
+## OUTPUT REQUIREMENTS
 - Security vulnerability findings with file:line references
 - Authentication/authorization pattern documentation
-- Input validation examples and gaps
+- Input validation examples and identified gaps
 - Encryption usage patterns and recommendations
+- Prioritized remediation plan based on risk level
 
-Focus on identifying security gaps and providing actionable remediation steps.
+## VERIFICATION CHECKLIST ✓
+□ All CONTEXT files analyzed for security vulnerabilities
+□ Every finding is backed by a code reference (file:line)
+□ Both authentication and data handling are covered
+□ Recommendations include clear, actionable remediation steps
+
+Focus: Identifying security gaps and providing actionable remediation steps.

.claude/workflows/cli-templates/prompts/development/component.txt

@@ -1,37 +1,55 @@
-You are tasked with creating a reusable component in this codebase. Follow these guidelines:
+Create a reusable component following project conventions and best practices.
 
-## Design Phase:
+## CORE CHECKLIST ⚡
+□ Analyze existing component patterns BEFORE implementing
+□ Follow established naming conventions and prop patterns
+□ Include comprehensive tests (unit + visual + accessibility)
+□ Provide complete TypeScript types and documentation
+
+## IMPLEMENTATION PHASES
+
+### Design Phase
 1. Analyze existing component patterns and structures
 2. Identify reusable design principles and styling approaches
 3. Review component hierarchy and prop patterns
 4. Study existing component documentation and usage
 
-## Development Phase:
+### Development Phase
 1. Create component with proper TypeScript interfaces
 2. Implement following established naming conventions
 3. Add appropriate default props and validation
 4. Include comprehensive prop documentation
 
-## Styling Phase:
+### Styling Phase
 1. Follow existing styling methodology (CSS modules, styled-components, etc.)
 2. Ensure responsive design principles
 3. Add proper theming support if applicable
 4. Include accessibility considerations (ARIA, keyboard navigation)
 
-## Testing Phase:
+### Testing Phase
 1. Write component tests covering all props and states
 2. Test accessibility compliance
 3. Add visual regression tests if applicable
 4. Test component in different contexts and layouts
 
-## Documentation Phase:
+### Documentation Phase
 1. Create usage examples and code snippets
 2. Document all props and their purposes
 3. Include accessibility guidelines
 4. Add integration examples with other components
 
-## Output Requirements:
-- Provide complete component implementation
-- Include comprehensive TypeScript types
-- Show usage examples and integration patterns
-- Document component API and best practices
+## OUTPUT REQUIREMENTS
+- Complete component implementation with TypeScript types
+- Usage examples and integration patterns
+- Component API documentation and best practices
+- Test suite with accessibility validation
+- File:line references for pattern sources
+
+## VERIFICATION CHECKLIST ✓
+□ Implementation follows existing component patterns
+□ Complete TypeScript types and prop documentation
+□ Comprehensive tests (unit + visual + accessibility)
+□ Accessibility compliance (ARIA, keyboard navigation)
+□ Usage examples and integration documented
+
+Focus: Production-ready reusable component with comprehensive documentation and testing.

.claude/workflows/cli-templates/prompts/development/debugging.txt

@@ -1,37 +1,55 @@
-You are tasked with debugging and resolving issues in this codebase. Follow these systematic guidelines:
+Debug and resolve issues systematically in the codebase.
 
-## Issue Analysis Phase:
+## CORE CHECKLIST ⚡
+□ Identify and reproduce the issue completely before fixing
+□ Perform root cause analysis (not just symptom treatment)
+□ Provide file:line references for all changes
+□ Add tests to prevent regression of this specific issue
+
+## IMPLEMENTATION PHASES
+
+### Issue Analysis Phase
 1. Identify and reproduce the reported issue
 2. Analyze error logs and stack traces
 3. Study code flow and identify potential failure points
 4. Review recent changes that might have introduced the issue
 
-## Investigation Phase:
+### Investigation Phase
 1. Add strategic logging and debugging statements
 2. Use debugging tools and profilers as appropriate
 3. Test with different input conditions and edge cases
 4. Isolate the root cause through systematic elimination
 
-## Root Cause Analysis:
+### Root Cause Analysis
 1. Document the exact cause of the issue
 2. Identify contributing factors and conditions
 3. Assess impact scope and affected functionality
 4. Determine if similar issues exist elsewhere
 
-## Resolution Phase:
+### Resolution Phase
 1. Implement minimal, targeted fix for the root cause
 2. Ensure fix doesn't introduce new issues or regressions
 3. Add proper error handling and validation
 4. Include defensive programming measures
 
-## Prevention Phase:
+### Prevention Phase
 1. Add tests to prevent regression of this issue
 2. Improve error messages and logging
 3. Add monitoring or alerts for early detection
 4. Document lessons learned and prevention strategies
 
-## Output Requirements:
-- Provide detailed root cause analysis
-- Show exact code changes made to resolve the issue
-- Include new tests added to prevent regression
-- Document debugging process and lessons learned
+## OUTPUT REQUIREMENTS
+- Detailed root cause analysis with file:line references
+- Exact code changes made to resolve the issue
+- New tests added to prevent regression
+- Debugging process documentation and lessons learned
+- Impact assessment and affected functionality
+
+## VERIFICATION CHECKLIST ✓
+□ Root cause identified and documented (not just symptoms)
+□ Minimal fix applied without introducing new issues
+□ Tests added to prevent this specific regression
+□ Similar issues checked and addressed if found
+□ Prevention measures documented
+
+Focus: Systematic root cause resolution with regression prevention.

.claude/workflows/cli-templates/prompts/development/feature.txt

@@ -1,31 +1,49 @@
-You are tasked with implementing a new feature in this codebase. Follow these guidelines:
+Implement a new feature following project conventions and best practices.
 
-## Analysis Phase:
+## CORE CHECKLIST ⚡
+□ Study existing code patterns BEFORE implementing
+□ Follow established project conventions and architecture
+□ Include comprehensive tests (unit + integration)
+□ Provide file:line references for all changes
+
+## IMPLEMENTATION PHASES
+
+### Analysis Phase
 1. Study existing code patterns and conventions
 2. Identify similar features and their implementation approaches
 3. Review project architecture and design principles
 4. Understand dependencies and integration points
 
-## Implementation Phase:
+### Implementation Phase
 1. Create feature following established patterns
 2. Implement with proper error handling and validation
 3. Add comprehensive logging for debugging
 4. Follow security best practices
 
-## Integration Phase:
+### Integration Phase
 1. Ensure seamless integration with existing systems
 2. Update configuration files as needed
 3. Add proper TypeScript types and interfaces
 4. Update documentation and comments
 
-## Testing Phase:
+### Testing Phase
 1. Write unit tests covering edge cases
 2. Add integration tests for feature workflows
 3. Verify error scenarios are properly handled
 4. Test performance and security implications
 
-## Output Requirements:
-- Provide file:line references for all changes
-- Include code examples demonstrating key patterns
-- Explain architectural decisions made
-- Document any new dependencies or configurations
+## OUTPUT REQUIREMENTS
+- File:line references for all changes
+- Code examples demonstrating key patterns
+- Explanation of architectural decisions made
+- Documentation of new dependencies or configurations
+- Test coverage summary
+
+## VERIFICATION CHECKLIST ✓
+□ Implementation follows existing patterns (no divergence)
+□ Complete test coverage (unit + integration)
+□ Documentation updated (code comments + external docs)
+□ Integration verified (no breaking changes)
+□ Security and performance validated
+
+Focus: Production-ready implementation with comprehensive testing and documentation.