feat: intelligent page inference from prompt (v4.0.1)

Features:
- --pages parameter now optional with smart inference
- Auto-extract page names from prompt text
  Example: "blog with home, article pages" → ["home", "article"]
- Fallback to synthesis-specification.md in integrated mode
- Default to ["home"] if nothing specified

Changes:
- auto.md: Add Phase 0 page inference logic, update examples
- ui-generate.md: Add page inference in Phase 1, update examples
- CHANGELOG.md: Add v4.0.1 release notes with page inference

Benefits:
- Simplest command: /workflow:design:auto --prompt "Modern blog with home and article pages"
- No need to manually specify --pages in most cases
- More natural and intuitive user experience

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

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

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

@@ -13,7 +13,6 @@ description: |
     user: "Create implementation plan for: real-time notifications system"
     assistant: "I'll create a staged implementation plan using provided context"
     commentary: Agent executes planning based on provided requirements and context
-model: sonnet
 color: yellow
 ---
 

.claude/agents/code-developer.md

@@ -13,7 +13,6 @@ description: |
     user: "Add user authentication"
     assistant: "I need to analyze the codebase first to understand the patterns"
     commentary: Use Gemini to gather implementation context, then execute
-model: sonnet
 color: blue
 ---
 

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

@@ -20,7 +20,6 @@ description: |
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer
     agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in .brainstorming/ui-designer/ directory"
 
-model: sonnet
 color: purple
 ---
 

.claude/agents/doc-generator.md

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

.claude/agents/general-purpose.md

@@ -13,7 +13,6 @@ description: |
     user: "Organize project documentation"
     assistant: "I need to understand the current documentation structure first"
     commentary: Gather context about existing documentation, then execute
-model: sonnet
 color: green
 ---
 

.claude/agents/memory-bridge.md

@@ -0,0 +1,88 @@
+---
+name: memory-bridge
+description: Execute complex project documentation updates using script coordination
+color: purple
+---
+
+You are a documentation update coordinator for complex projects. Orchestrate parallel CLAUDE.md updates efficiently and track every module.
+
+## Core Mission
+
+Execute depth-parallel updates for all modules using `~/.claude/scripts/update_module_claude.sh`. **Every module path must be processed**.
+
+## Input Context
+
+You will receive:
+```
+- Total modules: [count]
+- Tool: [gemini|qwen|codex]
+- Mode: [full|related]
+- Module list (depth|path|files|types|has_claude format)
+```
+
+## Execution Steps
+
+**MANDATORY: Use TodoWrite to track all modules before execution**
+
+### Step 1: Create Task List
+```bash
+# Parse module list and create todo items
+TodoWrite([
+  {content: "Process depth 5 modules (N modules)", status: "pending", activeForm: "Processing depth 5 modules"},
+  {content: "Process depth 4 modules (N modules)", status: "pending", activeForm: "Processing depth 4 modules"},
+  # ... for each depth level
+  {content: "Safety check: verify only CLAUDE.md modified", status: "pending", activeForm: "Running safety check"}
+])
+```
+
+### Step 2: Execute by Depth (Deepest First)
+```bash
+# For each depth level (5 → 0):
+# 1. Mark depth task as in_progress
+# 2. Extract module paths for current depth
+# 3. Launch parallel jobs (max 4)
+
+# Depth 5 example:
+~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/analysis" "full" "gemini" &
+~/.claude/scripts/update_module_claude.sh "./.claude/workflows/cli-templates/prompts/development" "full" "gemini" &
+# ... up to 4 concurrent jobs
+
+# 4. Wait for all depth jobs to complete
+wait
+
+# 5. Mark depth task as completed
+# 6. Move to next depth
+```
+
+### Step 3: Safety Check
+```bash
+# After all depths complete:
+git diff --cached --name-only | grep -v "CLAUDE.md" || echo "✅ Safe"
+git status --short
+```
+
+## Tool Parameter Flow
+
+**Command Format**: `update_module_claude.sh <path> <mode> <tool>`
+
+Examples:
+- Gemini: `update_module_claude.sh "./.claude/agents" "full" "gemini" &`
+- Qwen: `update_module_claude.sh "./src/api" "full" "qwen" &`
+- Codex: `update_module_claude.sh "./tests" "full" "codex" &`
+
+## Execution Rules
+
+1. **Task Tracking**: Create TodoWrite entry for each depth before execution
+2. **Parallelism**: Max 4 jobs per depth, sequential across depths
+3. **Tool Passing**: Always pass tool parameter as 3rd argument
+4. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+5. **Completion**: Mark todo completed only after all depth jobs finish
+6. **No Skipping**: Process every module from input list
+
+## Concise Output
+
+- Start: "Processing [count] modules with [tool]"
+- Progress: Update TodoWrite for each depth
+- End: "✅ Updated [count] CLAUDE.md files" + git status
+
+**Do not explain, just execute efficiently.**

.claude/agents/memory-gemini-bridge.md

@@ -1,82 +0,0 @@
----
-name: memory-gemini-bridge
-description: Execute complex project documentation updates using script coordination
-model: haiku
-color: purple
----
-
-You are a documentation update coordinator for complex projects. Your job is to orchestrate parallel execution of update scripts across multiple modules.
-
-## Core Responsibility
-
-Coordinate parallel execution of `~/.claude/scripts/update_module_claude.sh` script across multiple modules using depth-based hierarchical processing.
-
-## Execution Protocol
-
-### 1. Analyze Project Structure
-```bash
-# Step 1: Code Index architecture analysis
-mcp__code-index__search_code_advanced(pattern="class|function|interface", file_pattern="**/*.{ts,js,py}")
-mcp__code-index__find_files(pattern="**/*.{md,json,yaml,yml}")
-
-# Step 2: Get module list with depth information
-modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
-count=$(echo "$modules" | wc -l)
-
-# Step 3: Display project structure
-Bash(~/.claude/scripts/get_modules_by_depth.sh grouped)
-```
-
-### 2. Organize by Depth
-Group modules by depth level for hierarchical execution (deepest first):
-```pseudo
-# Step 3: Organize modules by depth → Prepare execution
-depth_modules = {}
-FOR each module IN modules_list:
-    depth = extract_depth(module)
-    depth_modules[depth].add(module)
-```
-
-### 3. Execute Updates
-For each depth level, run parallel updates:
-```pseudo
-# Step 4: Execute depth-parallel updates → Process by depth
-FOR depth FROM max_depth DOWN TO 0:
-    FOR each module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(~/.claude/scripts/update_module_claude.sh "$module" "$mode" &)
-    wait_all_jobs()
-```
-
-### 4. Execution Rules
-
-- **Core Command**: `Bash(~/.claude/scripts/update_module_claude.sh "$module" "$mode" &)`
-- **Concurrency Control**: Maximum 4 parallel jobs per depth level
-- **Execution Order**: Process depths sequentially, deepest first
-- **Job Control**: Monitor active jobs before spawning new ones
-- **Independence**: Each module update is independent within the same depth
-
-### 5. Update Modes
-
-- **"full"** mode: Complete refresh → `Bash(update_module_claude.sh "$module" "full" &)`
-- **"related"** mode: Context-aware updates → `Bash(update_module_claude.sh "$module" "related" &)`
-
-### 6. Agent Protocol
-
-```pseudo
-# Agent Coordination Flow:
-RECEIVE task_with(module_count, update_mode)
-modules = Bash(get_modules_by_depth.sh list) 
-Bash(get_modules_by_depth.sh grouped)
-depth_modules = organize_by_depth(modules)
-
-FOR depth FROM max_depth DOWN TO 0:
-    FOR module IN depth_modules[depth]:
-        WHILE active_jobs >= 4: wait(0.1)
-        Bash(update_module_claude.sh module update_mode &)
-    wait_all_jobs()
-
-REPORT final_status()
-```
-
-This agent coordinates the same `Bash()` commands used in direct execution, providing intelligent orchestration for complex projects.

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

@@ -18,7 +18,6 @@ description: |
     user: "Run the full test suite and ensure everything passes"
     assistant: "I'll use the test-fix-agent to execute all tests and fix any issues found"
     commentary: test-fix-agent serves as the quality gate - passing tests = approved code.
-model: sonnet
 color: green
 ---
 

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

@@ -0,0 +1,527 @@
+---
+name: ui-design-agent
+description: |
+  Specialized pure execution agent for UI/UX design workflows. Translates visual concepts, brand guidelines, and design requirements into concrete, structured design artifacts including design tokens, style guides, and production-ready UI prototypes.
+
+  Core mission: Bridge the gap between abstract design vision and engineering implementation through systematic visual analysis, design system generation, and prototype creation with strict quality gates.
+
+  Use this agent for:
+  - Visual analysis and style extraction from reference images (multi-modal)
+  - Design token generation and validation (WCAG AA compliance)
+  - UI prototype generation with token-driven styling
+  - Design system documentation and implementation handoff
+  - Component mapping and feasibility assessment
+
+  Examples:
+  - Context: /workflow:design:style-extract provides reference images
+    command: Assigns ui-design-agent with design_phase: "style-extract"
+    agent: "I'll analyze reference images using Gemini Vision, extract design semantics, then structure tokens via Codex"
+
+  - Context: /workflow:design:ui-generate requests prototypes
+    command: Assigns ui-design-agent with design_phase: "ui-generate"
+    agent: "I'll generate token-driven HTML/CSS prototypes adhering to design-tokens.json and synthesis-specification.md"
+
+color: orange
+icon: 🎨
+capabilities:
+  - vision_analysis
+  - token_generation
+  - prototype_generation
+  - accessibility_validation
+  - design_handoff
+quality_gates:
+  a11y: "AA"
+  token_coverage: 0.90
+  component_mapping_precision: 0.95
+  responsive_breakpoints: 3
+providers:
+  vision:
+    - gemini
+    - codex_image
+  token_generation:
+    - codex
+  prototype_generation:
+    - codex
+---
+
+You are a specialized **UI Design Execution Agent** focused on transforming design concepts into concrete, engineering-ready artifacts. Your expertise lies in systematic visual analysis, design system generation, and creating production-ready prototypes with strict quality validation.
+
+## Core Responsibilities
+
+1. **Visual Analysis**: Multi-modal analysis of reference images, extracting design semantics (color, typography, layout, components)
+2. **Design Token Generation**: Create standardized, validated design token systems (W3C Design Tokens compatible)
+3. **Prototype Creation**: Generate token-driven HTML/CSS prototypes with semantic markup and accessibility attributes
+4. **Quality Validation**: Ensure WCAG AA compliance, token coverage, consistency, and implementation feasibility
+5. **Implementation Handoff**: Produce complete design system documentation and component mapping for development teams
+
+## Agent Positioning & Boundaries
+
+### Differentiation from Existing Agents
+
+| Agent | Core Focus | This Agent's Relationship |
+|-------|-----------|--------------------------|
+| **conceptual-planning-agent** | Strategic thinking, "WHAT" and "WHY" from role perspectives | **Consumes**: analysis.md (ui-designer role), synthesis-specification.md for requirements |
+| **ui-design-agent** (this) | Visual execution, "HOW IT LOOKS" with concrete design artifacts | **Transforms**: Concepts → Design Tokens → Prototypes |
+| **action-planning-agent** | Task decomposition, "HOW TO BUILD" with implementation plans | **Provides to**: Design system, tokens, prototypes, component mapping |
+| **code-developer** | Code implementation, production-grade development | **Consumed by**: Uses design tokens and prototypes as implementation reference |
+
+### Boundaries
+
+**This agent DOES**:
+- Analyze visual references and extract design semantics
+- Generate validated design token systems
+- Create prototype HTML/CSS adhering to tokens
+- Validate accessibility and design consistency
+- Document design systems and component patterns
+
+**This agent DOES NOT**:
+- Define product strategy or business requirements (conceptual-planning-agent)
+- Break down implementation into development tasks (action-planning-agent)
+- Write production application code (code-developer)
+- Make strategic design decisions without requirements input
+
+## Execution Protocol
+
+### Task Reception
+
+**Standard Input Structure**:
+```json
+{
+  "meta": {
+    "type": "design",
+    "agent": "@ui-design-agent",
+    "design_phase": "style-extract|style-consolidate|ui-generate"
+  },
+  "context": {
+    "requirements": ["Design requirements from synthesis"],
+    "focus_paths": ["reference-images/*.png"],
+    "design_tokens_path": ".design/style-consolidation/design-tokens.json",
+    "synthesis_spec": ".brainstorming/synthesis-specification.md"
+  },
+  "flow_control": {
+    "pre_analysis": [...],
+    "implementation_approach": {...}
+  }
+}
+```
+
+### Execution Modes by Design Phase
+
+#### Phase 1: style-extract
+**Purpose**: Extract design semantics from visual references
+
+**Flow Control Steps**:
+1. **vision_analysis** (Gemini Vision primary, Codex -i fallback)
+   - Input: Reference images (PNG, JPG, WebP)
+   - Action: Multi-modal visual analysis
+   - Command: `gemini-wrapper` with image context
+   - Output: `semantic_style_analysis.json`
+   - Quality Gate: Element identification recall/precision thresholds
+
+2. **token_structuring** (Codex)
+   - Input: `semantic_style_analysis.json`
+   - Action: Convert semantics to structured OKLCH tokens
+   - Command: `codex exec` with token generation rules
+   - Output: `design-tokens.json`, `style-cards.json`
+   - Quality Gate: OKLCH format validation, token coverage ≥90%
+
+**Deliverables**:
+- `.design/style-extraction/semantic_style_analysis.json`
+- `.design/style-extraction/design-tokens.json` (preliminary)
+- `.design/style-extraction/style-cards.json` (variants for selection)
+
+#### Phase 2: style-consolidate
+**Purpose**: Consolidate selected variants into validated design system
+
+**Flow Control Steps**:
+1. **style_philosophy_synthesis** (Gemini)
+   - Input: Selected style cards, synthesis-specification.md
+   - Action: Synthesize unified design philosophy and semantic naming
+   - Output: `style-philosophy.md`
+   - Quality Gate: Design principles clarity, naming consistency
+
+2. **token_validation** (Codex)
+   - Input: `style-philosophy.md`, preliminary tokens
+   - Action: Validate, merge, and finalize design tokens
+   - Output: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`, `validation-report.json`
+   - Quality Gate: WCAG AA contrast ≥4.5:1 for text, token coverage ≥90%, no critical validation errors
+
+**Deliverables**:
+- `.design/style-consolidation/style-philosophy.md`
+- `.design/style-consolidation/design-tokens.json` (final, validated)
+- `.design/style-consolidation/style-guide.md`
+- `.design/style-consolidation/tailwind.config.js`
+- `.design/style-consolidation/validation-report.json`
+
+#### Phase 3: ui-generate
+**Purpose**: Generate production-ready UI prototypes
+
+**Flow Control Steps**:
+1. **load_design_system**
+   - Input: `design-tokens.json`, `style-guide.md`
+   - Action: Load finalized design system
+   - Output: Design system context
+
+2. **load_requirements**
+   - Input: `synthesis-specification.md`, optional `ui-designer/analysis.md`
+   - Action: Extract functional and UX requirements
+   - Output: Requirements context
+
+3. **prototype_generation** (Codex, optional Codex -i for mockups)
+   - Input: Design tokens, requirements, optional design mockup images
+   - Action: Generate token-driven HTML/CSS prototypes
+   - Output: `{page}-variant-{n}.html`, `{page}-variant-{n}.css`, implementation notes
+   - Quality Gate: 100% CSS values use custom properties, semantic HTML5, ARIA attributes, responsive breakpoints
+
+**Deliverables**:
+- `.design/prototypes/{page}-variant-{n}.html` (per page, per variant)
+- `.design/prototypes/{page}-variant-{n}.css` (token-driven styles)
+- `.design/prototypes/{page}-variant-{n}-notes.md` (implementation notes)
+- `.design/prototypes/design-tokens.css` (CSS custom properties)
+
+## Multi-Modal Capabilities Integration
+
+### Vision Provider Strategy
+
+**Gemini Vision** (Primary for vision_analysis):
+- **Strengths**: Superior OCR, multi-image context, complex visual scene understanding
+- **Use Cases**: Reference image analysis, competitive analysis, existing UI auditing
+- **Integration**: Via `gemini-wrapper` with `@{image_path}` context
+- **Quality**: Confidence thresholds required, low-confidence items flagged for review
+
+**Codex -i** (Fallback & complementary):
+- **Strengths**: Tight integration with codebase context, structured token generation
+- **Use Cases**: Quick sketch uploads, CLI workflow integration, deterministic token output
+- **Integration**: `codex -i image.png exec` with structured prompts
+- **Quality**: More reliable for structured output (tokens, configs) than pure visual analysis
+
+### Provider Selection Logic
+
+```python
+def select_vision_provider(task_type, images_count, complexity):
+    if task_type == "vision_analysis":
+        if complexity == "high" or images_count > 3:
+            return "gemini_vision"  # Superior multi-image understanding
+        else:
+            return "codex_image"    # Faster for simple cases
+    elif task_type == "token_generation":
+        return "codex"              # Structured output required
+    elif task_type == "prototype_generation":
+        if mockup_provided:
+            return "codex_image"    # Direct mockup-to-code
+        else:
+            return "codex"          # Token-driven generation
+```
+
+### Retry & Fallback Strategy
+
+- **Auto-retry**: Maximum 2 retries per step
+- **Provider fallback**: Gemini Vision failure → Codex -i retry
+- **Degradation**: Low confidence → Flag for human review
+- **Observability**: Log model/version, latency, confidence, errors per step
+
+## Flow Control Specification
+
+### pre_analysis (All Phases)
+
+**Inputs**:
+- `design_brief` (optional): Goals, audience, brand adjectives
+- `brand_guidelines` (optional): Color palettes, typography, icon styles
+- `constraints`: Accessibility requirements, platform constraints
+- `reference_images[]`: JPG/PNG/PDF with source labels
+
+**Actions**:
+1. Parse requirements and extract success criteria
+2. Identify conflicts or ambiguities in constraints
+3. Set quality gates based on requirements
+4. Generate briefing summary and constraints matrix
+
+**Outputs**:
+- `brief_summary.md`: Consolidated requirements
+- `constraints_matrix.json`: Structured constraints
+- `success_criteria.json`: Measurable success metrics
+
+**Quality Gate**: Requirements ambiguity rate low (≥95% key questions answered), conflicts flagged
+
+### implementation_approach (Phase 3: ui-generate)
+
+**Inputs**:
+- `screen_specs`: Generated prototype specifications
+- `design_tokens.json`: Validated design token system
+- `component_library_baseline` (optional): Target component library (React, Vue, Tailwind)
+
+**Actions**:
+1. Map design elements to component library components
+2. Generate component mapping with props, state, and style sources
+3. Define theming and internationalization strategy
+4. Create acceptance checklist for implementation
+
+**Outputs**:
+- `implementation_plan.md`: Implementation strategy, risks, timeline
+- `component_mapping.json`: Design-to-code component mapping
+- `acceptance_checklist.md`: Validation criteria for developers
+
+**Quality Gate**: ≥95% elements mapped to components, styles derivable from tokens, risks/dependencies documented
+
+## Input & Output Specifications
+
+### Input Specification
+
+**design_brief** (optional):
+```json
+{
+  "goals": ["Primary objectives"],
+  "target_audience": "User personas",
+  "brand_adjectives": ["Modern", "Clean", "Trustworthy"],
+  "anti_patterns": ["Avoid cluttered layouts"],
+  "target_platforms": ["Web", "iOS", "Android"]
+}
+```
+
+**brand_guidelines** (optional):
+```json
+{
+  "color_palette": ["#1E40AF", "#10B981"],
+  "typography": {
+    "heading": "Inter",
+    "body": "Inter",
+    "weights": [400, 600, 700]
+  },
+  "icon_style": "outlined",
+  "imagery": "photography"
+}
+```
+
+**constraints** (required):
+```json
+{
+  "accessibility": "WCAG 2.1 AA",
+  "performance_budget": "< 500KB initial load",
+  "i18n": ["en", "zh-CN"],
+  "platform_capabilities": {
+    "web": "CSS Grid, custom properties",
+    "mobile": "iOS 14+, Android 10+"
+  }
+}
+```
+
+**reference_images[]** (required for phase 1):
+```json
+[
+  {
+    "path": "design-refs/homepage.png",
+    "source": "Competitor analysis",
+    "purpose": "Layout inspiration"
+  }
+]
+```
+
+### Output Specification
+
+**design-tokens.json** (W3C Design Tokens compatible):
+```json
+{
+  "colors": {
+    "brand": {
+      "primary": "oklch(0.45 0.20 270 / 1)"
+    }
+  },
+  "typography": {
+    "font_family": {
+      "heading": "Inter, system-ui, sans-serif"
+    }
+  },
+  "spacing": {
+    "4": "1rem"
+  }
+}
+```
+
+See `.claude/workflows/design-tokens-schema.md` for complete schema.
+
+**screen_specs/{page}.json**:
+```json
+{
+  "page": "dashboard",
+  "layout": {
+    "grid": "12-column",
+    "breakpoints": ["640px", "768px", "1024px"]
+  },
+  "components": [
+    {
+      "type": "header",
+      "variant": "elevated",
+      "tokens": {
+        "bg": "surface.elevated",
+        "shadow": "shadow.md"
+      }
+    }
+  ]
+}
+```
+
+**component_mapping.json**:
+```json
+{
+  "mappings": [
+    {
+      "design_element": "Primary Button",
+      "component": "Button",
+      "library": "Tailwind UI",
+      "props": {
+        "variant": "primary",
+        "size": "md"
+      },
+      "tokens": {
+        "bg": "brand.primary",
+        "text": "text.inverse",
+        "padding": "spacing.4"
+      }
+    }
+  ],
+  "unmapped": [],
+  "coverage": 0.98
+}
+```
+
+## Quality Standards
+
+### Accessibility (WCAG 2.1 AA)
+- Text on background: ≥4.5:1 contrast ratio
+- Large text (18pt+ or 14pt+ bold): ≥3:1
+- UI components: ≥3:1 contrast
+- Non-text focus indicators: ≥3:1
+- Minimum touch target: 44×44px
+- Keyboard navigation support
+- Screen reader compatibility (ARIA labels)
+
+### Typography
+- Line length: 45-75 characters
+- Body text: ≥14-16px (desktop), ≥16px (mobile)
+- Heading hierarchy: ≤6 levels
+- Line height: 1.5 for body, 1.25 for headings
+
+### Design Tokens
+- Coverage: ≥90% of all design values
+- Naming convention: Semantic (brand-primary, surface-elevated, not color-1, bg-2)
+- Format: OKLCH for colors, rem for spacing/typography
+- Uniqueness: No duplicate values with different names
+- Consistency: Spacing scale maintains consistent ratio
+
+### Responsive Design
+- Breakpoints: Minimum 3 (mobile, tablet, desktop)
+- Mobile-first approach
+- Flexible layouts (CSS Grid, Flexbox)
+- Responsive typography using clamp() with token values
+
+### Component Mapping
+- Coverage: ≥95% of design elements mapped to components
+- Specificity: Props, state, and style sources documented
+- Feasibility: No "impossible" designs without mitigation
+- Documentation: Clear implementation guidance
+
+## Collaboration with Other Agents
+
+### Data Flow
+
+```
+conceptual-planning-agent (ui-designer role)
+  ↓ Provides: analysis.md, synthesis-specification.md (design requirements)
+ui-design-agent
+  ↓ Generates: design-tokens.json, style-guide.md, prototypes
+action-planning-agent
+  ↓ Consumes: Design artifacts → creates implementation tasks
+code-developer
+  ↓ Implements: Features using design tokens and prototypes
+```
+
+### Input from conceptual-planning-agent
+- `synthesis-specification.md`: Functional requirements, UX guidelines
+- `ui-designer/analysis.md`: UI/UX design principles, user flows
+- Design constraints and success criteria
+
+### Output to action-planning-agent
+- `design-tokens.json`: Referenced in task context.artifacts
+- `style-guide.md`: Component patterns and usage guidelines
+- `component_mapping.json`: Design-to-code mapping for task generation
+- `implementation_plan.md`: Strategy and acceptance criteria
+
+### Integration Pattern
+action-planning-agent adds to task JSON:
+```json
+{
+  "context": {
+    "artifacts": [
+      {
+        "type": "design_tokens",
+        "path": ".design/style-consolidation/design-tokens.json"
+      },
+      {
+        "type": "style_guide",
+        "path": ".design/style-consolidation/style-guide.md"
+      }
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_design_tokens",
+        "action": "Load design system tokens",
+        "command": "Read(.design/style-consolidation/design-tokens.json)",
+        "output_to": "design_system_context"
+      }
+    ]
+  }
+}
+```
+
+## Observability & Metrics
+
+### Per-Step Logging
+```json
+{
+  "step": "vision_analysis",
+  "provider": "gemini_vision",
+  "model": "gemini-1.5-pro",
+  "latency_ms": 2340,
+  "confidence": 0.87,
+  "errors": [],
+  "quality_gate_status": "pass"
+}
+```
+
+### Quality Metrics
+- Token coverage: `(tokens_used / total_values) * 100`
+- Component mapping coverage: `(mapped_elements / total_elements) * 100`
+- WCAG compliance: `(passing_combinations / total_combinations) * 100`
+- Prototype validation: Percentage of CSS using custom properties
+
+## Error Handling & Recovery
+
+### Retry Strategy
+- **Step failure**: Auto-retry up to 2 times
+- **Provider failure**: Switch from Gemini → Codex (vision tasks)
+- **Validation failure**: Flag errors, request human review or adjust parameters
+
+### Degradation Modes
+- **Low confidence vision analysis**: Flag uncertain elements for manual review
+- **Incomplete token coverage**: Document gaps, suggest manual token additions
+- **Mapping gaps**: Identify unmapped elements, request design simplification or custom components
+
+### Human-in-the-Loop
+- Low confidence items (< 0.7): Require manual confirmation
+- WCAG violations: Cannot proceed without fix or documented exception
+- Mapping gaps > 5%: Escalate to design review
+
+## Version & Maintenance
+
+**Version**: 1.0.0
+**Last Updated**: 2025-10-05
+**Changelog**:
+- Initial agent definition
+- Multi-modal vision provider integration (Gemini Vision, Codex -i)
+- W3C Design Tokens compliance
+- WCAG 2.1 AA quality gates
+- Flow control specification for 3 design phases
+
+Your role is to execute design tasks systematically through defined flow control steps, transforming visual concepts into production-ready design artifacts. Prioritize quality gates, accessibility compliance, and seamless handoff to implementation teams. Leverage multi-modal capabilities strategically: Gemini Vision for understanding, Codex for structured generation. Maintain observability and enable human review when confidence is low.

.claude/commands/cli/analyze.md

@@ -14,71 +14,103 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 
 ## Purpose
 
-Execute CLI tool analysis on codebase patterns, architecture, or code quality.
+Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
 
+**Intent**: Understand code patterns, architecture, and provide insights/recommendations
 **Supported Tools**: codex, gemini (default), qwen
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for complete tool details
+
+## Core Behavior
+
+1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
+2. **No Code Modification**: Results are recommendations and analysis reports
+3. **Template-Based**: Automatically selects appropriate analysis template
+4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Use `/enhance-prompt` for context-aware enhancement
+- `<analysis-target>` - Description of what to analyze
 
 ## Execution Flow
 
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first
-3. Detect analysis type and select template
-4. Build and execute command
-5. Return results
+2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
+3. Auto-detect analysis type from keywords → select template
+4. Build command with auto-detected file patterns and `MODE: analysis`
+5. Execute analysis (read-only, no code changes)
+6. Return analysis report with insights and recommendations
 
-## Enhancement Integration
+## File Pattern Auto-Detection
 
-**When `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) to build the analysis command.
+Keywords trigger specific file patterns:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "component" → `@{src/components/**/*,**/*.component.*}`
+- "API" → `@{**/api/**/*,**/routes/**/*}`
+- "test" → `@{**/*.test.*,**/*.spec.*}`
+- "config" → `@{*.config.*,**/config/**/*}`
+- Generic → `@{src/**/*}`
 
+For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
 ## Command Template
 
-**Gemini/Qwen**:
 ```bash
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper -p "
-PURPOSE: [analysis goal]
-TASK: [specific task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: [analysis goal from target]
+TASK: [auto-detected analysis type]
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+EXPECTED: Insights, patterns, recommendations (NO code modification)
+RULES: [auto-selected template] | Focus on [analysis aspect]
 "
 ```
 
-**Codex**:
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [analysis goal]
-TASK: [specific task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [output format]
-RULES: [constraints]
-" --skip-git-repo-check -s danger-full-access
-
-# With image attachment (e.g., UI screenshots, diagrams)
-codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
-```
-
 ## Examples
 
+**Basic Analysis**:
 ```bash
-/cli:analyze "authentication patterns"              # Gemini (default)
-/cli:analyze --tool qwen "component architecture"   # Qwen architecture
-/cli:analyze --tool codex "performance bottlenecks" # Codex deep analysis
-/cli:analyze --enhance "fix auth issues"            # Enhanced prompt first
+/cli:analyze "authentication patterns"
+# Executes: Gemini analysis with auth file patterns
+# Returns: Pattern analysis, architecture insights, recommendations
 ```
 
-## File Pattern Logic
+**Architecture Analysis**:
+```bash
+/cli:analyze --tool qwen "component architecture"
+# Executes: Qwen with component file patterns
+# Returns: Architecture review, design patterns, improvement suggestions
+```
 
-Auto-detect file patterns from keywords:
-- "auth" → `@{**/*auth*}`
-- "component" → `@{src/components/**/*}`
-- "API" → `@{**/api/**/*}`
-- "test" → `@{**/*.test.*}`
-- Generic → `@{src/**/*}`
+**Performance Analysis**:
+```bash
+/cli:analyze --tool codex "performance bottlenecks"
+# Executes: Codex deep analysis with performance focus
+# Returns: Bottleneck identification, optimization recommendations
+```
 
-## Session Integration
+**Enhanced Analysis**:
+```bash
+/cli:analyze --enhance "fix auth issues"
+# Step 1: Enhance prompt to expand context
+# Step 2: Analysis with expanded context
+# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
+```
 
-- **Active Session**: Save results to `.workflow/WFS-[id]/.chat/analysis-[timestamp].md`
-- **No Session**: Return results directly to user
+## Output Routing
 
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No active session OR one-off analysis**:
+  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
+- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
+
+## Notes
+
+- Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad files can be promoted to workflow sessions if analysis proves valuable

.claude/commands/cli/chat.md

@@ -1,6 +1,5 @@
 ---
 name: chat
-
 description: Simple CLI interaction command for direct codebase analysis
 usage: /cli:chat [--tool <codex|gemini|qwen>] [--enhance] "inquiry"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
@@ -9,84 +8,114 @@ examples:
   - /cli:chat --tool qwen --enhance "optimize React component"
   - /cli:chat --tool codex "review security vulnerabilities"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
+# CLI Chat Command (/cli:chat)
+
 ## Purpose
 
-Direct interaction with CLI tools for codebase analysis and Q&A.
+Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
 
+**Intent**: Ask questions, get explanations, understand codebase structure
 **Supported Tools**: codex, gemini (default), qwen
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for complete tool details
+
+## Core Behavior
+
+1. **Conversational Analysis**: Direct question-answer interaction about codebase
+2. **Read-Only**: This command ONLY provides information and analysis
+3. **No Code Modification**: Results are explanations and insights
+4. **Flexible Context**: Choose specific files or entire codebase
 
 ## Parameters
 
-- `<inquiry>` (Required): Question or analysis request
-- `--tool <codex|gemini|qwen>` (Optional): Select CLI tool (default: gemini)
-- `--enhance` (Optional): Enhance inquiry with `/enhance-prompt` first
-- `--all-files` (Optional): Include entire codebase in context
-- `--save-session` (Optional): Save interaction to workflow session
+- `<inquiry>` (Required) - Question or analysis request
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--enhance` - Enhance inquiry with `/enhance-prompt` first
+- `--all-files` - Include entire codebase in context
+- `--save-session` - Save interaction to workflow session
 
 ## Execution Flow
 
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first
-3. Assemble context (files + CLAUDE.md)
-4. Execute CLI tool
-5. Optional: Save to session
-
-## Enhancement Integration
-
-**When `--enhance` flag present**: Execute `/enhance-prompt "[inquiry]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) to build the chat command.
+2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
+3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
+4. Execute CLI tool with assembled context (read-only, analysis mode)
+5. Return explanations and insights (NO code changes)
+6. Optionally save to workflow session
 
 ## Context Assembly
 
-Context gathered from:
-1. **Project Guidelines**: `@{CLAUDE.md,**/*CLAUDE.md}` (always)
-2. **User-Explicit Files**: Files specified by user
-3. **All Files Flag**: `--all-files` includes entire codebase
+**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
+
+**Optional**:
+- User-explicit files from inquiry keywords
+- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
+
+For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
 
 ## Command Template
 
-**Gemini/Qwen**:
 ```bash
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper -p "
-PURPOSE: [inquiry goal]
-TASK: [specific question]
-CONTEXT: @{CLAUDE.md} @{target_files}
-EXPECTED: [response format]
-RULES: [constraints]
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+INQUIRY: [user question]
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+MODE: analysis
+RESPONSE: Direct answer, explanation, insights (NO code modification)
 "
-
-# With --all-files
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper --all-files -p "..."
-```
-
-**Codex**:
-```bash
-codex -C [dir] --full-auto exec "
-PURPOSE: [inquiry goal]
-TASK: [specific question]
-CONTEXT: @{CLAUDE.md} @{target_files}
-EXPECTED: [response format]
-RULES: [constraints]
-" --skip-git-repo-check -s danger-full-access
-
-# With image attachment
-codex -C [dir] -i screenshot.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
 ```
 
 ## Examples
 
+**Basic Question**:
 ```bash
-/cli:chat "analyze the authentication flow"              # Gemini (default)
-/cli:chat --tool qwen "optimize React component"         # Qwen
-/cli:chat --tool codex "review security vulnerabilities" # Codex
-/cli:chat --enhance "fix the login"                      # Enhanced prompt
-/cli:chat --all-files "find all API endpoints"           # Full codebase
+/cli:chat "analyze the authentication flow"
+# Executes: Gemini analysis
+# Returns: Explanation of auth flow, components involved, data flow
 ```
 
-## Session Persistence
+**Architecture Question**:
+```bash
+/cli:chat --tool qwen "how does React component optimization work here"
+# Executes: Qwen architecture analysis
+# Returns: Component structure explanation, optimization patterns used
+```
 
-- **Active Session**: Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No Session**: Return results directly
+**Security Analysis**:
+```bash
+/cli:chat --tool codex "review security vulnerabilities"
+# Executes: Codex security analysis
+# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
+```
+
+**Enhanced Inquiry**:
+```bash
+/cli:chat --enhance "explain the login issue"
+# Step 1: Enhance to expand login context
+# Step 2: Analysis with expanded understanding
+# Returns: Detailed explanation of login flow and potential issues
+```
+
+**Broad Context**:
+```bash
+/cli:chat --all-files "find all API endpoints"
+# Executes: Analysis across entire codebase
+# Returns: List and explanation of API endpoints (NO code generation)
+```
+
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND query is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
+- **No active session OR unrelated query**:
+  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
+- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
+
+## Notes
+
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad conversations preserved for future reference

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

@@ -17,18 +17,23 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 Automated task decomposition and sequential execution with Codex, using `codex exec "..." resume --last` mechanism for continuity between subtasks.
 
 **Input**: User description or task ID (automatically loads from `.task/[ID].json` if applicable)
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for Codex details
 
 ## Core Workflow
 
 ```
-Task Input → Decompose into Subtasks → TodoWrite Tracking →
-For Each Subtask:
-  0. Stage existing changes (git add -A) if valid git repo
-  1. Execute with Codex
-  2. [Optional] Git verification
-  3. Mark complete in TodoWrite
-  4. Resume next subtask with `codex resume --last`
+Task Input → Analyze Dependencies → Create Task Flow Diagram →
+Decompose into Subtask Groups → TodoWrite Tracking →
+For Each Subtask Group:
+  For First Subtask in Group:
+    0. Stage existing changes (git add -A) if valid git repo
+    1. Execute with Codex (new session)
+    2. [Optional] Git verification
+    3. Mark complete in TodoWrite
+  For Related Subtasks in Same Group:
+    0. Stage changes from previous subtask
+    1. Execute with `codex exec "..." resume --last` (continue session)
+    2. [Optional] Git verification
+    3. Mark complete in TodoWrite
 → Final Summary
 ```
 
@@ -41,17 +46,49 @@ For Each Subtask:
 
 ## Execution Flow
 
-### Phase 1: Input Processing & Decomposition
+### Phase 1: Input Processing & Task Flow Analysis
 
 1. **Parse Input**:
    - Check if input matches task ID pattern (e.g., `IMPL-001`, `TASK-123`)
    - If yes: Load from `.task/[ID].json` and extract requirements
    - If no: Use input as task description directly
 
-2. **Analyze & Decompose**:
+2. **Analyze Dependencies & Create Task Flow Diagram**:
    - Analyze task complexity and scope
-   - Break down into 3-8 subtasks
-   - Create TodoWrite tracker with all subtasks
+   - Identify dependencies and relationships between subtasks
+   - Create visual task flow diagram showing:
+     - Independent task groups (parallel execution possible)
+     - Sequential dependencies (must use resume)
+     - Branching logic (conditional paths)
+   - Display flow diagram for user review
+
+**Task Flow Diagram Format**:
+```
+[Group A: Auth Core]
+  A1: Create user model ──┐
+  A2: Add validation     ─┤─► [resume] ─► A3: Database schema
+                          │
+[Group B: API Layer]      │
+  B1: Auth endpoints ─────┘─► [new session]
+  B2: Middleware ────────────► [resume] ─► B3: Error handling
+
+[Group C: Testing]
+  C1: Unit tests ─────────────► [new session]
+  C2: Integration tests ──────► [resume]
+```
+
+**Diagram Symbols**:
+- `──►` Sequential dependency (must resume previous session)
+- `─┐` Branch point (multiple paths)
+- `─┘` Merge point (wait for completion)
+- `[resume]` Use `codex exec "..." resume --last`
+- `[new session]` Start fresh Codex session
+
+3. **Decompose into Subtask Groups**:
+   - Group related subtasks that share context
+   - Break down into 3-8 subtasks total
+   - Assign each subtask to a group
+   - Create TodoWrite tracker with groups
    - Display decomposition for user review
 
 **Decomposition Criteria**:
@@ -59,8 +96,30 @@ For Each Subtask:
 - Clear, testable outcomes
 - Explicit dependencies
 - Focused file scope (1-5 files per subtask)
+- **Group coherence**: Subtasks in same group share context/files
 
-### Phase 2: Sequential Execution
+### File Discovery for Task Decomposition
+
+Use `rg` or MCP tools to discover relevant files, then group by domain:
+
+**Workflow**: Discover → Analyze scope → Group by files → Create task flow
+
+**Example**:
+```bash
+# Discover files
+rg "authentication" --files-with-matches --type ts
+
+# Group by domain
+# Group A: src/auth/model.ts, src/auth/schema.ts
+# Group B: src/api/auth.ts, src/middleware/auth.ts
+# Group C: tests/auth/*.test.ts
+
+# Each group becomes a session with related subtasks
+```
+
+File patterns: see intelligent-tools-strategy.md (loaded in memory)
+
+### Phase 2: Group-Based Execution
 
 **Pre-Execution Git Staging** (if valid git repository):
 ```bash
@@ -70,37 +129,61 @@ git add -A
 git status --short
 ```
 
-**For First Subtask**:
+**For First Subtask in Each Group** (New Session):
 ```bash
-# Initial execution (no resume needed)
+# Start new Codex session for independent task group
 codex -C [dir] --full-auto exec "
-PURPOSE: [task goal]
-TASK: [subtask 1 description]
+PURPOSE: [group goal]
+TASK: [subtask description - first in group]
 CONTEXT: @{relevant_files} @{CLAUDE.md}
 EXPECTED: [specific deliverables]
 RULES: [constraints]
-Subtask 1 of N: [subtask title]
+Group [X]: [group name] - Subtask 1 of N in this group
 " --skip-git-repo-check -s danger-full-access
 ```
 
-**For Subsequent Subtasks** (using resume --last):
+**For Related Subtasks in Same Group** (Resume Session):
 ```bash
 # Stage changes from previous subtask (if valid git repository)
 git add -A
 
-# Resume previous session for context continuity
+# Resume session ONLY for subtasks in same group
 codex exec "
-CONTINUE TO NEXT SUBTASK:
-Subtask N of M: [subtask title]
+CONTINUE IN SAME GROUP:
+Group [X]: [group name] - Subtask N of M
 
-PURPOSE: [continuation goal]
+PURPOSE: [continuation goal within group]
 TASK: [subtask N description]
-CONTEXT: Previous work completed, now focus on @{new_relevant_files}
+CONTEXT: Previous work in this group completed, now focus on @{new_relevant_files}
 EXPECTED: [specific deliverables]
-RULES: Build on previous subtask, maintain consistency
+RULES: Build on previous subtask in group, maintain consistency
 " resume --last --skip-git-repo-check -s danger-full-access
 ```
 
+**For First Subtask in Different Group** (New Session):
+```bash
+# Stage changes from previous group
+git add -A
+
+# Start NEW session for different group (no resume)
+codex -C [dir] --full-auto exec "
+PURPOSE: [new group goal]
+TASK: [subtask description - first in new group]
+CONTEXT: @{different_files} @{CLAUDE.md}
+EXPECTED: [specific deliverables]
+RULES: [constraints]
+Group [Y]: [new group name] - Subtask 1 of N in this group
+" --skip-git-repo-check -s danger-full-access
+```
+
+**Resume Decision Logic**:
+```
+if (subtask.group == previous_subtask.group):
+    use `codex exec "..." resume --last`  # Continue session
+else:
+    use `codex -C [dir] exec "..."`       # New session
+```
+
 ### Phase 3: Verification (if --verify-git enabled)
 
 After each subtask completion:
@@ -121,16 +204,26 @@ git ls-files --others --exclude-standard
 - No merge conflicts or errors
 - Code compiles/runs (if applicable)
 
-### Phase 4: TodoWrite Tracking
+### Phase 4: TodoWrite Tracking with Groups
 
-**Initial Setup**:
+**Initial Setup with Task Flow**:
 ```javascript
 TodoWrite({
   todos: [
-    { content: "Subtask 1: [description]", status: "in_progress", activeForm: "Executing subtask 1" },
-    { content: "Subtask 2: [description]", status: "pending", activeForm: "Executing subtask 2" },
-    { content: "Subtask 3: [description]", status: "pending", activeForm: "Executing subtask 3" },
-    // ... more subtasks
+    // Display task flow diagram first
+    { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" },
+
+    // Group A subtasks (will use resume within group)
+    { content: "[Group A] Subtask 1: [description]", status: "in_progress", activeForm: "Executing Group A subtask 1" },
+    { content: "[Group A] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group A subtask 2" },
+
+    // Group B subtasks (new session, then resume within group)
+    { content: "[Group B] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group B subtask 1" },
+    { content: "[Group B] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group B subtask 2" },
+
+    // Group C subtasks (new session)
+    { content: "[Group C] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group C subtask 1" },
+
     { content: "Final verification and summary", status: "pending", activeForm: "Verifying and summarizing" }
   ]
 })
@@ -140,8 +233,9 @@ TodoWrite({
 ```javascript
 TodoWrite({
   todos: [
-    { content: "Subtask 1: [description]", status: "completed", activeForm: "Executing subtask 1" },
-    { content: "Subtask 2: [description]", status: "in_progress", activeForm: "Executing subtask 2" },
+    { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" },
+    { content: "[Group A] Subtask 1: [description]", status: "completed", activeForm: "Executing Group A subtask 1" },
+    { content: "[Group A] Subtask 2: [description] [resume]", status: "in_progress", activeForm: "Executing Group A subtask 2" },
     // ... update status
   ]
 })
@@ -149,18 +243,36 @@ TodoWrite({
 
 ## Codex Resume Mechanism
 
-**Why `codex resume --last`?**
-- Maintains conversation context across subtasks
-- Codex remembers previous decisions and patterns
-- Reduces context repetition
-- Ensures consistency in implementation style
+**Why Group-Based Resume?**
+- **Within Group**: Maintains conversation context for related subtasks
+  - Codex remembers previous decisions and patterns
+  - Reduces context repetition
+  - Ensures consistency in implementation style
+- **Between Groups**: Fresh session for independent tasks
+  - Avoids context pollution from unrelated work
+  - Prevents confusion when switching domains
+  - Maintains focused attention on current group
 
 **How It Works**:
-1. First subtask creates new Codex session
-2. After completion, session is saved
-3. Subsequent subtasks use `codex resume --last` to continue
-4. Each subtask builds on previous context
-5. Final subtask completes full task
+1. **First subtask in Group A**: Creates new Codex session
+2. **Subsequent subtasks in Group A**: Use `codex resume --last` to continue session
+3. **First subtask in Group B**: Creates NEW Codex session (no resume)
+4. **Subsequent subtasks in Group B**: Use `codex resume --last` within Group B
+5. Each group builds on its own context, isolated from other groups
+
+**When to Resume vs New Session**:
+```
+✅ RESUME (same group):
+  - Subtasks share files/modules
+  - Logical continuation of previous work
+  - Same architectural domain
+
+❌ NEW SESSION (different group):
+  - Independent task area
+  - Different files/modules
+  - Switching architectural domains
+  - Testing after implementation
+```
 
 **Image Support**:
 ```bash
@@ -199,25 +311,47 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 
 **During Execution**:
 ```
-📋 Task Decomposition:
-  1. [Subtask 1 description]
-  2. [Subtask 2 description]
-  ...
+📊 Task Flow Diagram:
+[Group A: Auth Core]
+  A1: Create user model ──┐
+  A2: Add validation     ─┤─► [resume] ─► A3: Database schema
+                          │
+[Group B: API Layer]      │
+  B1: Auth endpoints ─────┘─► [new session]
+  B2: Middleware ────────────► [resume] ─► B3: Error handling
 
-▶️  Executing Subtask 1/N: [title]
-  Codex session started...
+[Group C: Testing]
+  C1: Unit tests ─────────────► [new session]
+  C2: Integration tests ──────► [resume]
+
+📋 Task Decomposition:
+  [Group A] 1. Create user model
+  [Group A] 2. Add validation logic [resume]
+  [Group A] 3. Implement database schema [resume]
+  [Group B] 4. Create auth endpoints [new session]
+  [Group B] 5. Add middleware [resume]
+  [Group B] 6. Error handling [resume]
+  [Group C] 7. Unit tests [new session]
+  [Group C] 8. Integration tests [resume]
+
+▶️  [Group A] Executing Subtask 1/8: Create user model
+  Starting new Codex session for Group A...
   [Codex output]
   ✅ Subtask 1 completed
 
 🔍 Git Verification:
-  M  src/file1.ts
-  A  src/file2.ts
+  M  src/models/user.ts
   ✅ Changes verified
 
-▶️  Executing Subtask 2/N: [title]
-  Resuming Codex session...
+▶️  [Group A] Executing Subtask 2/8: Add validation logic
+  Resuming Codex session (same group)...
   [Codex output]
   ✅ Subtask 2 completed
+
+▶️  [Group B] Executing Subtask 4/8: Create auth endpoints
+  Starting NEW Codex session for Group B...
+  [Codex output]
+  ✅ Subtask 4 completed
 ...
 
 ✅ All Subtasks Completed
@@ -248,16 +382,30 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 
 ## Examples
 
-**Example 1: Simple Task**
+**Example 1: Simple Task with Groups**
 ```bash
 /cli:codex-execute "implement user authentication system"
 
-# Decomposes into:
-# 1. Create user model and database schema
-# 2. Implement JWT token generation
-# 3. Create authentication middleware
-# 4. Add login/logout endpoints
-# 5. Write tests for auth flow
+# Task Flow Diagram:
+# [Group A: Data Layer]
+#   A1: Create user model ──► [resume] ──► A2: Database schema
+#
+# [Group B: Auth Logic]
+#   B1: JWT token generation ──► [new session]
+#   B2: Authentication middleware ──► [resume]
+#
+# [Group C: API Endpoints]
+#   C1: Login/logout endpoints ──► [new session]
+#
+# [Group D: Testing]
+#   D1: Unit tests ──► [new session]
+#   D2: Integration tests ──► [resume]
+
+# Execution:
+# Group A: A1 (new) → A2 (resume)
+# Group B: B1 (new) → B2 (resume)
+# Group C: C1 (new)
+# Group D: D1 (new) → D2 (resume)
 ```
 
 **Example 2: With Git Verification**
@@ -280,13 +428,16 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 
 ## Best Practices
 
-1. **Subtask Granularity**: Keep subtasks small and focused
-2. **Clear Boundaries**: Each subtask should have well-defined input/output
-3. **Git Hygiene**: Use `--verify-git` for critical refactoring
-4. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications
-5. **Context Continuity**: Let `codex resume --last` maintain context
-6. **Recovery Points**: TodoWrite provides clear progress tracking
-7. **Image References**: Attach design files for UI tasks
+1. **Task Flow First**: Always create visual flow diagram before execution
+2. **Group Related Work**: Cluster subtasks by domain/files for efficient resume
+3. **Subtask Granularity**: Keep subtasks small and focused (5-15 min each)
+4. **Clear Boundaries**: Each subtask should have well-defined input/output
+5. **Git Hygiene**: Use `--verify-git` for critical refactoring
+6. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications
+7. **Smart Resume**: Use `resume --last` ONLY within same group
+8. **Fresh Sessions**: Start new session when switching to different group/domain
+9. **Recovery Points**: TodoWrite with group labels provides clear progress tracking
+10. **Image References**: Attach design files for UI tasks (first subtask in group)
 
 ## Input Processing
 
@@ -306,10 +457,45 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 }
 ```
 
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Execution log: `.workflow/WFS-[id]/.chat/codex-execute-[timestamp].md`
+  - Task summaries: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+  - Task updates: `.workflow/WFS-[id]/.task/[TASK-ID].json` status updates
+  - TodoWrite tracking: Embedded in execution log
+- **ELSE** (no active session):
+  - **Recommended**: Create workflow session first (`/workflow:session:start`)
+  - **Alternative**: Save to `.workflow/.scratchpad/codex-execute-[description]-[timestamp].md`
+
+**Output Files** (during execution):
+```
+.workflow/WFS-[session-id]/
+├── .chat/
+│   └── codex-execute-20250105-143022.md    # Full execution log with task flow
+├── .summaries/
+│   ├── IMPL-001.1-summary.md               # Subtask summaries
+│   ├── IMPL-001.2-summary.md
+│   └── IMPL-001-summary.md                 # Final task summary
+└── .task/
+    ├── IMPL-001.json                       # Updated task status
+    └── [subtask JSONs if decomposed]
+```
+
+**Examples**:
+- During session `WFS-auth-system`, executing multi-stage auth implementation:
+  - Log: `.workflow/WFS-auth-system/.chat/codex-execute-20250105-143022.md`
+  - Summaries: `.workflow/WFS-auth-system/.summaries/IMPL-001.{1,2,3}-summary.md`
+  - Task status: `.workflow/WFS-auth-system/.task/IMPL-001.json` (status: completed)
+- No session, ad-hoc multi-stage task:
+  - Log: `.workflow/.scratchpad/codex-execute-auth-refactor-20250105-143045.md`
+
 **Save Results**:
-- Execution log: `.chat/codex-execute-[timestamp].md` (if workflow active)
-- Summary: `.summaries/[TASK-ID]-summary.md` (if task ID provided)
-- TodoWrite tracking embedded in session
+- Execution log with task flow diagram and TodoWrite tracking
+- Individual summaries for each completed subtask
+- Final consolidated summary when all subtasks complete
+- Modified code files throughout project
 
 ## Notes
 
@@ -320,3 +506,8 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 **Input Flexibility**: Accepts both freeform descriptions and task IDs (auto-detects and loads JSON)
 
 **Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
+
+**Output Details**:
+- Output routing and scratchpad details: see workflow-architecture.md
+- Session management: see intelligent-tools-strategy.md
+- **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

.claude/commands/cli/execute.md

@@ -9,29 +9,33 @@ examples:
   - /cli:execute --tool codex IMPL-001
   - /cli:execute --enhance "fix API performance issues"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Execute Command (/cli:execute)
 
 ## Purpose
 
-Execute implementation tasks with YOLO permissions (auto-approves all confirmations).
+Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **MODIFIES CODE**.
 
+**Intent**: Autonomous code implementation, modification, and generation
 **Supported Tools**: codex, gemini (default), qwen
-**Reference**: @~/.claude/workflows/intelligent-tools-strategy.md for complete tool details
+**Key Feature**: Automatic context inference and file pattern detection
 
-## YOLO Permissions
+## Core Behavior
 
-Auto-approves: file pattern inference, execution, file modifications, summary generation
+1. **Code Modification**: This command MODIFIES, CREATES, and DELETES code files
+2. **Auto-Approval**: YOLO mode bypasses confirmation prompts for all operations
+3. **Implementation Focus**: Executes actual code changes, not just recommendations
+4. **Requires Explicit Intent**: Use only when implementation is intended
 
-## Enhancement Integration
+## Core Concepts
 
-**When `--enhance` flag present** (Description Mode only): Execute `/enhance-prompt "[description]"` first, then use enhanced output (INTENT/CONTEXT/ACTION) for execution.
+### YOLO Permissions
+Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**Note**: Task ID Mode uses task JSON directly (no enhancement).
+**⚠️ WARNING**: This command will make actual code changes without manual confirmation
 
-## Execution Modes
+### Execution Modes
 
 **1. Description Mode** (supports `--enhance`):
 - Input: Natural language description
@@ -41,71 +45,141 @@ Auto-approves: file pattern inference, execution, file modifications, summary ge
 - Input: Workflow task identifier (e.g., `IMPL-001`)
 - Process: Task JSON parsing → Scope analysis → Execute
 
-## Context Inference
+### Context Inference
 
-Auto-selects files based on:
-- **Keywords**: "auth" → `@{**/*auth*,**/*user*}`
-- **Technology**: "React" → `@{src/**/*.{jsx,tsx}}`
-- **Task Type**: "api" → `@{**/api/**/*,**/routes/**/*}`
-- **Always**: `@{CLAUDE.md,**/*CLAUDE.md}`
+Auto-selects files based on keywords and technology:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "React" → `@{src/**/*.{jsx,tsx}}`
+- "api" → `@{**/api/**/*,**/routes/**/*}`
+- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
 
-## Options
+For precise file targeting, use `rg` or MCP tools to discover files first.
 
-- `--debug`: Verbose logging
-- `--save-session`: Save execution to workflow session
+### Codex Session Continuity
+
+**Resume Pattern** for related tasks:
+```bash
+# First task - establish session
+codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access
+
+# Related task - continue session
+codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules.
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
+- `<description|task-id>` - Natural language description or task identifier
+- `--debug` - Verbose logging
+- `--save-session` - Save execution to workflow session
 
 ## Workflow Integration
 
 **Session Management**: Auto-detects `.workflow/.active-*` marker
-- **Active**: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- **None**: Create new session
+- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- No session: Create new session or save to scratchpad
 
 **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
 
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+  - Update task status in `.task/[TASK-ID].json` (if task ID provided)
+  - Generate summary in `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md`
+- **ELSE** (no active session):
+  - **Option 1**: Create new workflow session for task
+  - **Option 2**: Save to `.workflow/.scratchpad/execute-[description]-[timestamp].md`
+
+**Output Files** (when active session exists):
+- Execution log: `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- Task summary: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+- Modified code: Project files per implementation
+
+**Examples**:
+- During session `WFS-auth-system`, executing `IMPL-001`:
+  - Log: `.workflow/WFS-auth-system/.chat/execute-20250105-143022.md`
+  - Summary: `.workflow/WFS-auth-system/.summaries/IMPL-001-summary.md`
+- No session, ad-hoc implementation:
+  - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
+
 ## Command Template
 
-**Gemini/Qwen** (with YOLO approval):
 ```bash
-cd [dir] && ~/.claude/scripts/[gemini|qwen]-wrapper --approval-mode yolo -p "
+# Gemini/Qwen: MODE=write with --approval-mode yolo
+cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
 PURPOSE: [implementation goal]
-TASK: [specific task]
+TASK: [specific implementation]
 MODE: write
-CONTEXT: @{inferred_patterns} @{CLAUDE.md}
-EXPECTED: Implementation with file:line references
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
+CONTEXT: @{CLAUDE.md} [auto-detected files]
+EXPECTED: Working implementation with code changes
+RULES: [constraints] | Auto-approve all changes
 "
-```
 
-**Codex**:
-```bash
-codex -C [dir] --full-auto exec "
+# Codex: MODE=auto with danger-full-access
+codex -C . --full-auto exec "
 PURPOSE: [implementation goal]
-TASK: [specific task]
+TASK: [specific implementation]
 MODE: auto
-CONTEXT: @{inferred_patterns} @{CLAUDE.md}
-EXPECTED: Implementation with file:line references
-RULES: [constraints]
+CONTEXT: [auto-detected files]
+EXPECTED: Complete implementation with tests
 " --skip-git-repo-check -s danger-full-access
-
-# With image attachment
-codex -C [dir] -i design.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
 ```
 
 ## Examples
 
+**Basic Implementation** (⚠️ modifies code):
 ```bash
-/cli:execute "implement JWT authentication with middleware"  # Description mode
-/cli:execute --enhance "implement JWT authentication"        # Enhanced
-/cli:execute IMPL-001                                        # Task ID mode
-/cli:execute --tool codex "optimize database queries"        # Codex execution
+/cli:execute "implement JWT authentication with middleware"
+# Executes: Creates auth middleware, updates routes, modifies config
+# Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-## Auto-Generated Outputs
+**Enhanced Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --enhance "implement JWT authentication"
+# Step 1: Enhance to expand requirements
+# Step 2: Execute implementation with auto-approval
+# Result: Complete auth system with MODIFIED code files
+```
 
-- **Summary**: `.summaries/[TASK-ID]-summary.md`
-- **Session**: `.chat/execute-[timestamp].md`
+**Task Execution** (⚠️ modifies code):
+```bash
+/cli:execute IMPL-001
+# Reads: .task/IMPL-001.json for requirements
+# Executes: Implementation based on task spec
+# Result: Code changes per task definition
+```
+
+**Codex Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --tool codex "optimize database queries"
+# Executes: Codex with full file access
+# Result: MODIFIED query code, new indexes, updated tests
+```
+
+**Qwen Code Generation** (⚠️ modifies code):
+```bash
+/cli:execute --tool qwen --enhance "refactor auth module"
+# Step 1: Enhanced refactoring plan
+# Step 2: Execute with MODE=write
+# Result: REFACTORED auth code with structural changes
+```
+
+## Comparison with Analysis Commands
+
+| Command | Intent | Code Changes | Auto-Approve |
+|---------|--------|--------------|--------------|
+| `/cli:analyze` | Understand code | ❌ NO | N/A |
+| `/cli:chat` | Ask questions | ❌ NO | N/A |
+| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
 
 ## Notes
 
-**vs. `/cli:analyze`**: Execute performs implementation, analyze is read-only.
-
+- Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
+- Output routing and scratchpad details: see workflow-architecture.md
+- **⚠️ Code Modification**: This command modifies code - execution logs document changes made

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

@@ -8,16 +8,23 @@ examples:
   - /cli:mode:bug-index --tool qwen --enhance "login not working"
   - /cli:mode:bug-index --tool codex --cd "src/auth" "token validation fails"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Mode: Bug Index (/cli:mode:bug-index)
 
 ## Purpose
 
-Execute systematic bug analysis and fix suggestions using CLI tools with diagnostic template.
+Systematic bug analysis with diagnostic template (`~/.claude/prompt-templates/bug-fix.md`).
 
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: `--cd` flag for directory-scoped analysis
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Enhance bug description with `/enhance-prompt` first
+- `--cd "path"` - Target directory for focused analysis
+- `<bug-description>` (Required) - Bug description or error message
 
 ## Execution Flow
 
@@ -26,26 +33,33 @@ Execute systematic bug analysis and fix suggestions using CLI tools with diagnos
 3. Parse bug description (original or enhanced)
 4. Detect target directory (from `--cd` or auto-infer)
 5. Build command for selected tool with bug-fix template
-6. Execute analysis
-7. Save to session (if active)
+6. Execute analysis (read-only, provides fix recommendations)
+7. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
 
 ## Core Rules
 
-1. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-2. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-3. **Template Required**: Always use bug-fix template
-4. **Session Output**: Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+1. **Analysis Only**: This command analyzes bugs and suggests fixes - it does NOT modify code
+2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
+3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+4. **Template Required**: Always use bug-fix template
+5. **Session Output**: Save analysis results and fix recommendations to session chat
+
+## Analysis Focus (via Template)
+
+- Root cause investigation and diagnosis
+- Code path tracing to locate issues
+- Targeted minimal fix recommendations
+- Impact assessment of proposed changes
 
 ## Command Template
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
 ```bash
 cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: [bug analysis goal]
 TASK: Systematic bug analysis and fix recommendations
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Root cause analysis, code path tracing, targeted fixes
+EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
 "
 ```
@@ -56,9 +70,10 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: Debug authentication null pointer error
-TASK: Identify root cause and provide fix
+TASK: Identify root cause and provide fix recommendations
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Root cause, code path, minimal fix, impact assessment
+EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
 "
 ```
@@ -68,47 +83,39 @@ RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login
 cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: Fix token validation failure
 TASK: Analyze token validation bug in auth module
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation logic analysis, fix recommendation
+EXPECTED: Validation logic analysis, fix recommendation with minimal changes
 RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
 "
 ```
 
-**With Enhancement**:
+## Bug Investigation Workflow
+
 ```bash
-# User: /gemini:mode:bug-index --enhance "login broken"
+# 1. Find bug-related files
+rg "error_keyword" --files-with-matches
+mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")
 
-# Step 1: Enhance
-/enhance-prompt "login broken"
-# Returns:
-# INTENT: Debug login authentication failure
-# CONTEXT: Known session state issue
-# ACTION: Check session management → verify token → test flow
-
-# Step 2: Analyze with enhanced context
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Debug login authentication failure
-TASK: Analyze session management, token handling, auth flow
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} Known: session state issue
-EXPECTED: Root cause in session/token, targeted fix
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Focus on session management
-"
+# 2. Execute bug analysis with focused context (analysis only, no code changes)
+/cli:mode:bug-index --cd "src/module" "specific error description"
 ```
 
-## Analysis Focus
+## Output Routing
 
-**Template provides**:
-- **Root Cause Analysis**: Systematic investigation
-- **Code Path Tracing**: Execution flow analysis
-- **Targeted Solutions**: Minimal, specific fixes
-- **Impact Assessment**: Side effect evaluation
+**Output Destination Logic**:
+- **Active session exists AND bug is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
+- **No active session OR quick debugging**:
+  - Save to `.workflow/.scratchpad/bug-index-[description]-[timestamp].md`
 
-## Session Output
+**Examples**:
+- During active session `WFS-payment-fix`, analyzing payment bug → `.chat/bug-index-20250105-143022.md`
+- No session, quick null pointer investigation → `.scratchpad/bug-index-null-pointer-20250105-143045.md`
 
-**Location**: `.workflow/WFS-[topic]/.chat/bug-index-[timestamp].md`
+## Notes
 
-**Includes**:
-- Bug description
-- Template used
-- Analysis results
-- Recommended actions
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Template path: `~/.claude/prompt-templates/bug-fix.md`
+- Always uses `--all-files` for comprehensive codebase context

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

@@ -8,16 +8,23 @@ examples:
   - /cli:mode:code-analysis --tool qwen --enhance "explain data transformation pipeline"
   - /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Mode: Code Analysis (/cli:mode:code-analysis)
 
 ## Purpose
 
-Execute systematic code analysis and debugging using CLI tools with specialized code analysis template.
+Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`).
 
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: `--cd` flag for directory-scoped analysis
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Enhance analysis target with `/enhance-prompt` first
+- `--cd "path"` - Target directory for focused analysis
+- `<analysis-target>` (Required) - Code analysis target or question
 
 ## Execution Flow
 
@@ -26,20 +33,20 @@ Execute systematic code analysis and debugging using CLI tools with specialized
 3. Parse analysis target (original or enhanced)
 4. Detect target directory (from `--cd` or auto-infer)
 5. Build command for selected tool with code-analysis template
-6. Execute deep analysis
-7. Save to session (if active)
+6. Execute deep analysis (read-only, no code modification)
+7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
 
 ## Core Rules
 
-1. **Tool Selection**: Use `--tool` value or default to gemini
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use code-analysis template
-5. **Session Output**: Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
+2. **Tool Selection**: Use `--tool` value or default to gemini
+3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
+4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+5. **Template Required**: Always use code-analysis template
+6. **Session Output**: Save analysis results to session chat
 
-## Analysis Capabilities
+## Analysis Capabilities (via Template)
 
-The code-analysis template provides:
 - **Systematic Code Analysis**: Break down complex code into manageable parts
 - **Execution Path Tracing**: Track variable states and call stacks
 - **Control & Data Flow**: Understand code logic and data transformations
@@ -47,158 +54,74 @@ The code-analysis template provides:
 - **Logical Reasoning**: Explain "why" behind code behavior
 - **Debugging Insights**: Identify potential bugs or inefficiencies
 
-## Command Templates
+## Command Template
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
-### Gemini (Default)
 ```bash
 cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [analysis goal from target]
-TASK: Deep code analysis with execution path tracing
+PURPOSE: [analysis goal]
+TASK: Systematic code analysis and execution path tracing
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Systematic analysis, call flow diagram, data transformations, logical explanation
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect]
+EXPECTED: Execution trace, call flow diagram, debugging insights
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
 "
 ```
 
-### Qwen
-```bash
-cd [directory] && ~/.claude/scripts/qwen-wrapper --all-files -p "
-PURPOSE: [analysis goal from target]
-TASK: Architecture-level code analysis and pattern recognition
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Architectural insights, design patterns, code structure analysis
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect]
-"
-```
-
-### Codex
-```bash
-codex -C [directory] --full-auto exec "
-PURPOSE: [analysis goal from target]
-TASK: Deep code inspection with debugging insights
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Execution trace, bug identification, optimization opportunities
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [specific aspect]
-" --skip-git-repo-check -s danger-full-access
-```
-
 ## Examples
 
-**Basic Code Analysis (Gemini)**:
+**Basic Code Analysis**:
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Analyze authentication flow logic
-TASK: Trace authentication execution path and identify key functions
+PURPOSE: Trace authentication execution flow
+TASK: Analyze complete auth flow from request to response
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Step-by-step flow, call diagram, data passing between functions
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow and security
+EXPECTED: Step-by-step execution trace with call diagram, variable states
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
 "
 ```
 
-**Architecture Analysis (Qwen)**:
+**Directory-Specific Analysis**:
 ```bash
-# User: /cli:mode:code-analysis --tool qwen "explain data transformation pipeline"
-
-cd . && ~/.claude/scripts/qwen-wrapper --all-files -p "
-PURPOSE: Explain data transformation pipeline architecture
-TASK: Analyze data flow and transformation patterns
+cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Understand JWT token validation logic
+TASK: Trace JWT validation from middleware to service layer
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Pipeline structure, transformation stages, data format changes
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on data flow and patterns
+EXPECTED: Validation flow diagram, token lifecycle analysis
+RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
 "
 ```
 
-**Deep Debugging (Codex)**:
-```bash
-# User: /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
+## Code Tracing Workflow
 
-codex -C src/core --full-auto exec "
-PURPOSE: Trace execution path for user registration
-TASK: Deep analysis of registration flow with debugging insights
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Complete execution trace, variable states, potential issues
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on edge cases and error handling
-" --skip-git-repo-check -s danger-full-access
+```bash
+# 1. Find entry points and related files
+rg "function.*authenticate|class.*AuthService" --files-with-matches
+mcp__code-index__search_code_advanced(pattern="authenticate|login", file_pattern="*.ts")
+
+# 2. Build call graph understanding
+# entry → middleware → service → repository
+
+# 3. Execute deep analysis (analysis only, no code changes)
+/cli:mode:code-analysis --cd "src" "trace execution from entry point"
 ```
 
-**With Enhancement**:
-```bash
-# User: /cli:mode:code-analysis --enhance "why is login slow"
+## Output Routing
 
-# Step 1: Enhance
-/enhance-prompt "why is login slow"
-# Returns:
-# INTENT: Identify performance bottlenecks in login flow
-# CONTEXT: Authentication module, database queries
-# ACTION: Trace execution path → identify slow operations → suggest optimizations
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+- **No active session OR standalone analysis**:
+  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
 
-# Step 2: Analyze with enhanced context
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Identify performance bottlenecks in login flow
-TASK: Trace login execution path and measure operation costs
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{**/*auth*,**/*login*}
-EXPECTED: Performance analysis, bottleneck identification, optimization recommendations
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on performance and database queries
-"
-```
+**Examples**:
+- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
+- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
 
-## Analysis Output Structure
+## Notes
 
-Based on code-analysis.md template, output includes:
-
-### 1. 思考过程 (Thinking Process)
-- Analysis strategy and approach
-- Key assumptions about code behavior
-
-### 2. 对问题的理解 (Understanding)
-- Restate analysis target
-- Confirm understanding of requirements
-
-### 3. 核心解答 (Core Answer)
-- Direct, concise answer to analysis question
-
-### 4. 详细分析与调用逻辑 (Detailed Analysis)
-- **代码段识别**: Relevant code sections
-- **执行流程**: Step-by-step execution flow
-- **调用图**: Visual call flow diagram with symbols:
-  - `───►` Function call
-  - `◄───` Return
-  - `│` Continuation
-  - `├─` Intermediate step
-  - `└─` Last step in block
-- **数据传递**: Data passing and state changes
-- **逻辑解释**: Why code behaves this way
-
-### 5. 总结 (Summary)
-- Key findings and recommendations
-
-## Session Output
-
-**Location**: `.workflow/WFS-[topic]/.chat/code-analysis-[timestamp].md`
-
-**Includes**:
-- Analysis target
-- Template used
-- Complete structured analysis
-- Call flow diagrams
-- Debugging insights
-- Recommendations
-
-## Use Cases
-
-| Use Case | Best Tool | Focus |
-|----------|-----------|-------|
-| **Understand execution flow** | gemini | Call sequences, data flow |
-| **Architectural patterns** | qwen | Design patterns, structure |
-| **Performance debugging** | codex | Bottlenecks, optimizations |
-| **Bug investigation** | codex | Error paths, edge cases |
-| **Code review** | gemini | Logic correctness, clarity |
-| **Refactoring planning** | qwen | Structure improvements |
-
-## Tool Selection Guide
-
-- **Gemini**: Best for general code understanding and tracing
-- **Qwen**: Best for architectural analysis and pattern recognition
-- **Codex**: Best for deep debugging and performance analysis
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Template path: `~/.claude/prompt-templates/code-analysis.md`
+- Always uses `--all-files` for comprehensive code context

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

@@ -8,16 +8,23 @@ examples:
   - /cli:mode:plan --tool qwen --enhance "plan microservices migration"
   - /cli:mode:plan --tool codex --cd "src/auth" "authentication system"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Mode: Plan (/cli:mode:plan)
 
 ## Purpose
 
-Execute planning and architecture analysis using CLI tools with specialized template.
+Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`).
 
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: `--cd` flag for directory-scoped planning
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Enhance topic with `/enhance-prompt` first
+- `--cd "path"` - Target directory for focused planning
+- `<topic>` (Required) - Planning topic or architectural question
 
 ## Execution Flow
 
@@ -26,79 +33,93 @@ Execute planning and architecture analysis using CLI tools with specialized temp
 3. Parse topic (original or enhanced)
 4. Detect target directory (from `--cd` or auto-infer)
 5. Build command for selected tool with planning template
-6. Execute analysis
-7. Save to session (if active)
+6. Execute analysis (read-only, no code modification)
+7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
 
 ## Core Rules
 
-1. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
-2. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-3. **Template Required**: Always use planning template
-4. **Session Output**: Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
+2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
+3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
+4. **Template Required**: Always use planning template
+5. **Session Output**: Save analysis results to session chat
+
+## Planning Capabilities (via Template)
+
+- Strategic architecture insights and recommendations
+- Implementation roadmaps and suggestions
+- Key technical decisions analysis
+- Risk assessment
+- Resource planning
 
 ## Command Template
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
 ```bash
 cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
 PURPOSE: [planning goal from topic]
 TASK: Comprehensive planning and architecture analysis
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Strategic insights, implementation roadmap, key decisions
+EXPECTED: Strategic insights, implementation recommendations, key decisions
 RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
 "
 ```
 
 ## Examples
 
-**Basic Planning**:
+**Basic Planning Analysis**:
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Design user dashboard feature architecture
-TASK: Comprehensive architecture planning for dashboard
+PURPOSE: Design user dashboard architecture
+TASK: Plan dashboard component structure and data flow
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Architecture design, component structure, implementation roadmap
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability and UX
+EXPECTED: Architecture recommendations, component design, data flow diagram
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
 "
 ```
 
-**Directory-Specific**:
+**Directory-Specific Planning**:
 ```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Plan authentication system redesign
-TASK: Analyze current auth and plan improvements
+cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
+PURPOSE: Plan API refactoring strategy
+TASK: Analyze current API structure and recommend improvements
+MODE: analysis
 CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Migration strategy, security improvements, timeline
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on security and backward compatibility
+EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
+RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
 "
 ```
 
-**With Enhancement**:
+## Planning Workflow
+
 ```bash
-# User: /gemini:mode:plan --enhance "fix auth issues"
+# 1. Discover project structure
+~/.claude/scripts/get_modules_by_depth.sh
+mcp__code-index__find_files(pattern="*.ts")
 
-# Step 1: Enhance
-/enhance-prompt "fix auth issues"
-# Returns structured planning context
+# 2. Gather existing architecture info
+rg "architecture|design" --files-with-matches
 
-# Step 2: Plan with enhanced input
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [enhanced goal]
-TASK: [enhanced task description]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [enhanced context]
-EXPECTED: Strategic plan with enhanced requirements
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | [enhanced constraints]
-"
+# 3. Execute planning analysis (analysis only, no code changes)
+/cli:mode:plan "topic for strategic planning"
 ```
 
-## Session Output
+## Output Routing
 
-**Location**: `.workflow/WFS-[topic]/.chat/plan-[timestamp].md`
+**Output Destination Logic**:
+- **Active session exists AND planning is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+- **No active session OR exploratory planning**:
+  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
 
-**Includes**:
-- Planning topic
-- Template used
-- Analysis results
-- Implementation roadmap
-- Key decisions
+**Examples**:
+- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
+- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
+
+## Notes
+
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Template path: `~/.claude/prompt-templates/plan.md`
+- Always uses `--all-files` for comprehensive project context

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

@@ -45,7 +45,7 @@ count=$(echo "$modules" | wc -l)
 
 # Pseudocode flow:
 # IF (module_count > 20 OR complex_project_detected):
-#     → Task "Complex project full update" subagent_type: "memory-gemini-bridge"
+#     → Task "Complex project full update" subagent_type: "memory-bridge"
 # ELSE:
 #     → Present plan and WAIT FOR USER APPROVAL before execution
 #
@@ -60,7 +60,7 @@ After the bash script completes the initial analysis, the model takes control to
 2. **Parse CLAUDE.md Status**: Extract which modules have/need CLAUDE.md files
 3. **Choose Strategy**:
    - Simple projects: Present execution plan with CLAUDE.md paths to user
-   - Complex projects: Delegate to memory-gemini-bridge agent
+   - Complex projects: Delegate to memory-bridge agent
 4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated
 5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
 
@@ -119,13 +119,43 @@ Bash(git status --short)
 ```
 
 **For Complex Projects (>20 modules):**
-The model will delegate to the memory-gemini-bridge agent using the Task tool:
-```
+
+The model will delegate to the memory-bridge agent with structured context:
+
+```javascript
 Task "Complex project full update"
-prompt: "Execute full documentation update for [count] modules using [tool] with depth-parallel execution"
-subagent_type: "memory-gemini-bridge"
+subagent_type: "memory-bridge"
+prompt: `
+CONTEXT:
+- Total modules: ${module_count}
+- Tool: ${tool}  // from --tool parameter, default: gemini
+- Mode: full
+- Existing CLAUDE.md: ${existing_count}
+- New CLAUDE.md needed: ${new_count}
+
+MODULE LIST:
+${modules_output}  // Full output from get_modules_by_depth.sh list
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level before execution
+2. Process depths 5→0 sequentially, max 4 parallel jobs per depth
+3. Command format: update_module_claude.sh "<path>" "full" "${tool}" &
+4. Extract exact path from "depth:N|path:<PATH>|..." format
+5. Verify all ${module_count} modules are processed
+6. Run safety check after completion
+7. Display git status
+
+Execute depth-parallel updates for all modules.
+`
 ```
 
+**Agent receives complete context:**
+- Module count and tool selection
+- Full structured module list
+- Clear execution requirements
+- Path extraction format
+- Success criteria
+
 
 ### 📚 Usage Examples
 

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

@@ -51,7 +51,7 @@ count=$(echo "$changed" | wc -l)
 
 # Pseudocode flow:
 # IF (change_count > 15 OR complex_changes_detected):
-#     → Task "Complex project related update" subagent_type: "memory-gemini-bridge"
+#     → Task "Complex project related update" subagent_type: "memory-bridge"
 # ELSE:
 #     → Present plan and WAIT FOR USER APPROVAL before execution
 #
@@ -66,7 +66,7 @@ After the bash script completes change detection, the model takes control to:
 2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files
 3. **Choose Strategy**: 
    - Simple changes: Present execution plan with CLAUDE.md paths to user
-   - Complex changes: Delegate to memory-gemini-bridge agent
+   - Complex changes: Delegate to memory-bridge agent
 4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules
 5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
 
@@ -126,13 +126,44 @@ Bash(git diff --stat)
 ```
 
 **For Complex Changes (>15 modules):**
-The model will delegate to the memory-gemini-bridge agent using the Task tool:
-```
+
+The model will delegate to the memory-bridge agent with structured context:
+
+```javascript
 Task "Complex project related update"
-prompt: "Execute context-aware update for [count] changed modules using [tool] with depth-parallel execution"
-subagent_type: "memory-gemini-bridge"
+subagent_type: "memory-bridge"
+prompt: `
+CONTEXT:
+- Total modules: ${change_count}
+- Tool: ${tool}  // from --tool parameter, default: gemini
+- Mode: related
+- Changed modules detected via: detect_changed_modules.sh
+- Existing CLAUDE.md: ${existing_count}
+- New CLAUDE.md needed: ${new_count}
+
+MODULE LIST:
+${changed_modules_output}  // Full output from detect_changed_modules.sh list
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level before execution
+2. Process depths sequentially (deepest→shallowest), max 4 parallel jobs per depth
+3. Command format: update_module_claude.sh "<path>" "related" "${tool}" &
+4. Extract exact path from "depth:N|path:<PATH>|..." format
+5. Verify all ${change_count} modules are processed
+6. Run safety check after completion
+7. Display git diff --stat
+
+Execute depth-parallel updates for changed modules only.
+`
 ```
 
+**Agent receives complete context:**
+- Changed module count and tool selection
+- Full structured module list (changed only)
+- Clear execution requirements with "related" mode
+- Path extraction format
+- Success criteria
+
 
 ### 📚 Usage Examples
 

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

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

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

@@ -436,4 +436,65 @@ Upon completion, update `workflow-session.json`:
 - [ ] **Implementation Readiness**: Plans detailed enough for immediate execution, with clear handoff to IMPL_PLAN.md
 - [ ] **Stakeholder Alignment**: Addresses needs and concerns of all key stakeholders
 - [ ] **Decision Traceability**: Every major decision traceable to source role analysis via @ references
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+
+## 🚀 **Recommended Next Steps**
+
+After synthesis completion, follow this recommended workflow:
+
+### Option 1: Standard Planning Workflow (Recommended)
+```bash
+# Step 1: Verify conceptual clarity (Quality Gate)
+/workflow:concept-verify --session WFS-{session-id}
+# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
+
+# Step 2: Proceed to action planning (after concept verification)
+/workflow:plan --session WFS-{session-id}
+# → Generates IMPL_PLAN.md and task.json files
+
+# Step 3: Verify action plan quality (Quality Gate)
+/workflow:action-plan-verify --session WFS-{session-id}
+# → Read-only analysis to catch issues before execution
+
+# Step 4: Start implementation
+/workflow:execute --session WFS-{session-id}
+```
+
+### Option 2: TDD Workflow
+```bash
+# Step 1: Verify conceptual clarity
+/workflow:concept-verify --session WFS-{session-id}
+
+# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
+/workflow:tdd-plan --session WFS-{session-id} "Feature description"
+
+# Step 3: Verify TDD plan quality
+/workflow:action-plan-verify --session WFS-{session-id}
+
+# Step 4: Execute TDD workflow
+/workflow:execute --session WFS-{session-id}
+```
+
+### Quality Gates Explained
+
+**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
+- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
+- **Time**: 10-20 minutes (interactive)
+- **Value**: Reduces downstream rework by 40-60%
+- **Output**: Updated synthesis-specification.md with clarifications
+
+**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
+- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
+- **Time**: 5-10 minutes (read-only analysis)
+- **Value**: Prevents execution of flawed plans, saves 2-5 days
+- **Output**: Verification report with actionable recommendations
+
+### Skip Verification? (Not Recommended)
+
+If you want to skip verification and proceed directly:
+```bash
+/workflow:plan --session WFS-{session-id}
+/workflow:execute --session WFS-{session-id}
+```
+
+⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

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

@@ -0,0 +1,311 @@
+---
+name: concept-verify
+description: Identify underspecified areas in brainstorming artifacts through targeted clarification questions before action planning
+usage: /workflow:concept-verify [--session <session-id>]
+argument-hint: "optional: --session <session-id>"
+examples:
+  - /workflow:concept-verify
+  - /workflow:concept-verify --session WFS-auth
+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-verify 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/design/auto.md

@@ -0,0 +1,451 @@
+---
+name: auto
+description: Orchestrate UI design refinement workflow with interactive checkpoints for user selection
+usage: /workflow:design:auto [--prompt "<desc>"] [--images "<glob>"] [--pages "<list>"] [--session <id>] [--variants <count>] [--use-agent] [--batch-plan]
+argument-hint: "[--prompt \"Modern SaaS\"] [--images \"refs/*.png\"] [--pages \"dashboard,auth\"] [--session WFS-xxx] [--variants 3] [--use-agent]"
+examples:
+  - /workflow:design:auto --prompt "Modern blog with home, article and author pages, dark theme"
+  - /workflow:design:auto --prompt "SaaS dashboard and settings" --variants 3 --use-agent
+  - /workflow:design:auto --images "refs/*.png" --prompt "E-commerce site: home, product, cart"
+  - /workflow:design:auto --session WFS-auth --images "refs/*.png" --variants 2
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*)
+---
+
+# UI Design Auto Workflow Command
+
+## Overview
+Semi-autonomous UI design workflow with interactive checkpoints: style extraction → **user selection** → consolidation → UI generation → **user confirmation** → design update → optional batch planning.
+
+## Coordinator Role
+**Checkpoint-based orchestrator**: Execute Phase 1 automatically, pause for user style selection, execute Phase 3, pause for user prototype confirmation, complete with optional batch task generation.
+
+## Execution Model - Checkpoint Workflow
+
+This workflow runs **semi-autonomously** with user checkpoints:
+
+1. **User triggers**: `/workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth" [--batch-plan]`
+2. **Phase 1 executes** (style-extract) → Reports style cards → **⏸️ PAUSE FOR USER SELECTION**
+3. **User selects variants** → Runs `style-consolidate --variants "..."` → Auto-continues
+4. **Phase 3 executes** (ui-generate) → Reports prototypes → **⏸️ PAUSE FOR USER CONFIRMATION**
+5. **User confirms prototypes** → Runs `design-update --selected-prototypes "..."` → Auto-continues
+6. **Phase 5 executes** (batch-plan, optional) → Reports task files
+
+**Checkpoint Mechanism**:
+- TodoWrite tracks current phase with "awaiting_user_confirmation" status
+- System reports output location and exact command for next step
+- User runs provided command to continue workflow
+- Workflow resumes automatically after user input
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
+2. **No Preliminary Analysis**: Do not read files or validate before Phase 1 (commands handle their own validation)
+3. **Parse Every Output**: Extract required data from each command's output for next phase
+4. **Pause at Checkpoints**: After Phase 1 and Phase 3, pause and prompt user with exact command to continue
+5. **User-Driven Continuation**: Workflow resumes when user runs style-consolidate or design-update commands
+6. **Track Progress**: Update TodoWrite after every phase completion and checkpoint
+
+## Parameter Requirements
+
+**Optional Parameters** (all have smart defaults):
+- `--pages "<page_list>"`: Pages to generate (if omitted, inferred from prompt/session)
+- `--session <session_id>`: Workflow session ID (if omitted, runs in standalone mode)
+- `--images "<glob_pattern>"`: Reference image paths (default: `design-refs/*`)
+- `--prompt "<description>"`: Text description of design style and pages
+- `--variants <count>`: Number of style/UI variants to generate (default: 3, range: 1-5)
+- `--use-agent`: Enable agent-driven creative exploration mode
+- `--batch-plan`: Auto-generate implementation tasks after design-update (integrated mode only)
+
+**Input Source Rules**:
+- Must provide at least one of: `--images` or `--prompt`
+- Both can be combined for guided style analysis
+
+**Page Inference Logic**:
+1. If `--pages` provided: Use explicit list
+2. Else if `--prompt` provided: Extract page names from prompt text
+   - Example: "dashboard and login page" → ["dashboard", "login"]
+   - Example: "Modern SaaS app" → ["home", "dashboard", "settings"]
+3. Else if `--session` provided (integrated mode): Infer from synthesis-specification.md
+4. Else: Default to ["home"]
+
+## Execution Modes
+
+### Integrated Mode (with `--session`)
+- Works within existing workflow session: `.workflow/WFS-{session}/`
+- Reads from `.brainstorming/` artifacts
+- Phase 4 (design-update) updates synthesis-specification.md
+- Enables `--batch-plan` for task generation
+
+### Standalone Mode (without `--session`)
+- Creates new session: `design-session-YYYYMMDD-HHMMSS/`
+- Independent of brainstorming phase
+- Phase 4 (design-update) is **skipped**
+- Outputs final summary instead of artifact updates
+
+### Mode Detection
+```bash
+IF --session provided:
+    mode = "integrated"
+    base_path = ".workflow/WFS-{session}/"
+ELSE:
+    mode = "standalone"
+    session_id = "design-session-" + timestamp()
+    base_path = "./{session_id}/"
+```
+
+## 5-Phase Execution
+
+### Phase 0: Page Inference (if needed)
+**Infer page list if not explicitly provided**:
+```bash
+IF --pages provided:
+    page_list = {explicit_pages}
+ELSE IF --prompt provided:
+    # Extract page names from prompt using Claude analysis
+    page_list = extract_page_names_from_prompt({prompt_text})
+    # Examples:
+    # "dashboard and login page" → ["dashboard", "login"]
+    # "blog with home, article, author pages" → ["home", "article", "author"]
+    # "Modern SaaS app" → ["home", "dashboard", "settings"]
+ELSE IF --session provided:
+    # Read synthesis-specification.md and extract page requirements
+    page_list = extract_pages_from_synthesis({session_id})
+ELSE:
+    page_list = ["home"]  # Default fallback
+
+VALIDATE: page_list not empty
+```
+
+### Phase 1: Style Extraction
+**Command Construction**:
+```bash
+variants_flag = --variants present ? "--variants {variants_count}" : ""
+agent_flag = --use-agent present ? "--use-agent" : ""
+images_flag = --images present ? "--images \"{image_glob}\"" : ""
+prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
+session_flag = --session present ? "--session {session_id}" : ""
+
+command = "/workflow:design:style-extract {session_flag} {images_flag} {prompt_flag} {variants_flag} {agent_flag}"
+```
+
+**Command**: `SlashCommand(command="{constructed_command}")`
+
+**Parse Output**:
+- Verify: `.design/style-extraction/style-cards.json` created
+- Extract: `style_cards_count` (should match `variants_count`)
+- List available style variant IDs
+
+**Validation**:
+- Style cards successfully generated
+- Variant count matches requested count
+
+**TodoWrite**: Mark phase 1 completed, mark checkpoint "awaiting_user_confirmation"
+
+**⏸️ CHECKPOINT 1: Pause for User Style Selection**
+
+```
+Phase 1 Complete: Style Extraction
+Style cards generated: {count}
+Available variants: {variant_ids}
+Location: .workflow/WFS-{session}/.design/style-extraction/
+
+⏸️  USER SELECTION REQUIRED
+Review style cards and select your preferred variants.
+Then run:
+
+/workflow:design:style-consolidate --session WFS-{session} --variants "{variant_ids}"
+
+Example: /workflow:design:style-consolidate --session WFS-{session} --variants "variant-1,variant-3"
+```
+
+---
+
+### Phase 2: Style Consolidation (User-Triggered)
+**User Command**: `/workflow:design:style-consolidate --session {session_id} --variants "{selected_variants}"`
+
+**After user runs command**:
+- Workflow automatically continues to Phase 3
+- Parse output: token_count, validation_status
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**Output**:
+```
+Phase 2 Complete: Style Consolidation
+Design tokens: {count}
+Validation: {pass|warnings}
+Location: .workflow/WFS-{session}/.design/style-consolidation/
+
+Continuing to Phase 3: UI Generation...
+```
+
+---
+
+### Phase 3: UI Generation (Auto-Triggered after Phase 2)
+**Command Construction**:
+
+```bash
+variants_flag = --variants present ? "--variants {variants_count}" : ""
+agent_flag = --use-agent present ? "--use-agent" : ""
+session_flag = --session present ? "--session {session_id}" : ""
+command = "/workflow:design:ui-generate {session_flag} --pages \"{page_list}\" {variants_flag} {agent_flag}"
+```
+
+**Command**: `SlashCommand(command="{constructed_command}")`
+
+**Parse Output**:
+- Verify: `.design/prototypes/*.html` files created
+- Extract: `prototype_count`, `page_list`, `generated_files` list
+
+**Validation**:
+- All requested pages generated
+- HTML and CSS files present for each variant
+
+**TodoWrite**: Mark phase 3 completed, mark checkpoint "awaiting_user_confirmation"
+
+**⏸️ CHECKPOINT 2: Pause for User Prototype Confirmation**
+
+```
+Phase 3 Complete: UI Generation
+Prototypes generated: {count} ({page_list})
+Generated files: {file_list}
+Location: .workflow/WFS-{session}/.design/prototypes/
+
+⏸️  USER CONFIRMATION REQUIRED
+Review the generated prototypes and select your preferred variants.
+Then run:
+
+/workflow:design:design-update --session WFS-{session} --selected-prototypes "{prototype_ids}"
+
+Example: /workflow:design:design-update --session WFS-{session} --selected-prototypes "dashboard-variant-1,auth-variant-2"
+
+Or to use all generated prototypes:
+/workflow:design:design-update --session WFS-{session}
+```
+
+---
+
+### Phase 4: Design System Integration (User-Triggered)
+**User Command**: `/workflow:design:design-update --session {session_id} [--selected-prototypes "{selected_prototypes}"]`
+
+**After user runs command**:
+- Workflow updates brainstorming artifacts
+- If --batch-plan flag present, automatically continues to Phase 5
+
+**Parse Output**:
+- Verify: `synthesis-specification.md` updated
+- Verify: `ui-designer/style-guide.md` created/updated
+
+**TodoWrite**: Mark phase 4 completed
+
+**Output** (if --batch-plan NOT present):
+```
+UI Design Refinement Complete for session: WFS-{session}
+
+Design System Summary:
+- Tokens: {token_count} (OKLCH-based)
+- Prototypes: {prototype_count} ({page_list})
+- Validation: {pass|warnings}
+
+Updated Artifacts:
+✓ synthesis-specification.md (UI/UX Guidelines section)
+✓ ui-designer/style-guide.md (comprehensive style guide)
+✓ Design tokens ready for task generation
+
+Location: .workflow/WFS-{session}/.design/
+
+Next Steps:
+1. Review prototypes: .workflow/WFS-{session}/.design/prototypes/
+2. Continue to planning: /workflow:plan [--agent] "<task description>"
+   (The plan phase will automatically discover and utilize the design system)
+```
+
+**Output** (if --batch-plan present):
+```
+Phase 4 Complete: Design System Integration
+Updated Artifacts:
+✓ synthesis-specification.md
+✓ ui-designer/style-guide.md
+
+Continuing to Phase 5: Batch Task Generation...
+```
+
+---
+
+### Phase 5: Batch Task Generation (Optional, Auto-Triggered if --batch-plan)
+**Condition**: Only executes if `--batch-plan` flag present
+
+**Execution**:
+```bash
+FOR each page IN selected_prototypes_pages:
+  SlashCommand(command="/workflow:plan --agent \"Implement {page} page based on design system\"")
+
+  # Parse output task file location
+  task_files.add(output_location)
+```
+
+**TodoWrite**: Mark phase 5 completed
+
+**Return to User**:
+```
+Phase 5 Complete: Batch Task Generation
+Tasks generated for: {page_count} pages
+
+Generated task files:
+{task_file_list}
+
+Design workflow complete for session: WFS-{session}
+
+Next: /workflow:execute
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Execute style extraction from reference images", "status": "in_progress", "activeForm": "Executing style extraction"},
+  {"content": "Execute style consolidation and token validation", "status": "pending", "activeForm": "Executing style consolidation"},
+  {"content": "Execute UI prototype generation", "status": "pending", "activeForm": "Executing UI generation"},
+  {"content": "Execute design system integration to brainstorming", "status": "pending", "activeForm": "Executing design system integration"}
+]})
+
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Execute style extraction from reference images", "status": "completed", "activeForm": "Executing style extraction"},
+  {"content": "Execute style consolidation and token validation", "status": "in_progress", "activeForm": "Executing style consolidation"},
+  {"content": "Execute UI prototype generation", "status": "pending", "activeForm": "Executing UI generation"},
+  {"content": "Execute design system integration to brainstorming", "status": "pending", "activeForm": "Executing design system integration"}
+]})
+
+// Continue pattern for Phase 2, 3, 4...
+```
+
+## Parameter Processing
+
+### Session Validation
+```bash
+# Verify active session
+CHECK: .workflow/.active-* marker files
+VERIFY: session_id parameter matches active session
+IF mismatch:
+    ERROR: "Session {session_id} is not active. Active session: {active_session_id}"
+```
+
+### Image Glob Expansion
+```bash
+# Expand glob pattern
+expanded_paths = bash(ls {image_glob})
+IF no files found:
+    ERROR: "No images found matching pattern: {image_glob}"
+VALIDATE: All files are image formats (.png, .jpg, .jpeg, .webp)
+```
+
+### Page List Parsing
+```bash
+# Parse comma-separated page list
+pages = split(page_list, ",")
+TRIM: whitespace from each page name
+VALIDATE: page_list not empty
+```
+
+## Data Flow
+
+```
+User Input
+  ├── session_id
+  ├── image_glob → expanded_image_paths
+  ├── page_list → parsed_pages[]
+  ├── --interactive → interactive_mode (bool)
+  └── --variants → variants_count (int)
+    ↓
+Phase 1: style-extract
+  Input: session_id, expanded_image_paths
+  Output: style-cards.json
+    ↓
+Phase 2: style-consolidate
+  Input: session_id, interactive_mode | auto-select
+  Output: design-tokens.json, style-guide.md, tailwind.config.js
+    ↓
+Phase 3: ui-generate
+  Input: session_id, parsed_pages[], variants_count
+  Output: {page}-variant-{n}.html/css for each page
+    ↓
+Phase 4: design-update
+  Input: session_id
+  Output: Updated synthesis-specification.md, ui-designer/style-guide.md
+    ↓
+Return summary to user
+```
+
+## Error Handling
+
+**Phase Execution Failures**:
+- **Keep phase `in_progress`**: Do not proceed to next phase
+- **Report error to user**: Include specific failure message from command
+- **Provide recovery instructions**: Suggest manual command execution with corrected parameters
+
+**Common Errors**:
+1. **Session not found**: Verify session exists and is active
+2. **No images found**: Check image glob pattern and file paths
+3. **Style extraction failed**: Retry with different images or manual style description
+4. **Consolidation validation errors**: Review validation-report.json and address token issues
+5. **UI generation failed**: Check synthesis-specification.md for requirements clarity
+6. **Integration conflicts**: Review synthesis-specification.md edit conflicts
+
+## Workflow Position
+
+**In Complete Development Flow**:
+```
+/workflow:brainstorm:auto-parallel "{topic}"
+    ↓ Generates synthesis-specification.md (WHAT)
+    ↓
+/workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth"
+    ↓ Refines visual design (WHAT → Visual Spec)
+    ↓
+/workflow:plan [--agent] "{task description}"
+    ↓ Generates task breakdown (HOW)
+    ↓
+/workflow:execute
+    ↓ Implements tasks with design system
+```
+
+**Key Benefits**:
+1. **Visual Validation**: Users confirm design before implementation
+2. **Token Enforcement**: Implementation strictly follows design system
+3. **Accessibility**: WCAG AA validated at design phase
+4. **Consistency**: Single source of truth for visual design
+
+## Coordinator Checklist
+
+✅ Initialize TodoWrite before any command execution
+✅ Validate session parameter before Phase 1
+✅ Expand image glob to concrete paths
+✅ Parse page list to array
+✅ Execute Phase 1 immediately (no preliminary analysis)
+✅ Parse style card count from Phase 1 output
+✅ Construct Phase 2 command based on --interactive flag
+✅ Parse token count and validation status from Phase 2
+✅ Construct Phase 3 command with variants parameter
+✅ Parse prototype count from Phase 3 output
+✅ Execute Phase 4 design system integration
+✅ Verify all artifacts updated successfully
+✅ Update TodoWrite after each phase
+✅ After each phase, automatically continue to next phase based on TodoWrite status
+
+## Integration Notes
+
+**Seamless Workflow Transition**:
+- Design phase is **optional but recommended** for UI-heavy projects
+- Can be skipped entirely if visual design is not critical
+- Brainstorming → Plan flow still works without design phase
+- Design artifacts automatically discovered by task-generate if present
+
+**Use Cases**:
+- **Use design workflow**: User-facing applications, design systems, brand-critical UIs
+- **Skip design workflow**: Backend APIs, CLI tools, prototypes, MVPs
+
+**Artifact Discovery**:
+- `task-generate` automatically detects `.design/` directory
+- If present, adds design system to task context.artifacts
+- UI tasks automatically include `load_design_tokens` in flow_control

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

@@ -0,0 +1,348 @@
+---
+name: design-update
+description: Update brainstorming artifacts with finalized design system
+usage: /workflow:design:design-update --session <session_id> [--selected-prototypes "<list>"]
+argument-hint: "--session WFS-session-id [--selected-prototypes \"dashboard-variant-1,auth-variant-2\"]"
+examples:
+  - /workflow:design:design-update --session WFS-auth
+  - /workflow:design:design-update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
+allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*), Bash(*)
+---
+
+# Design Update Command
+
+## Overview
+Synchronize finalized design system (tokens, style guide, selected prototypes) back to brainstorming artifacts, preparing for `/workflow:plan` phase consumption.
+
+## Core Philosophy
+- **Main Claude Execution**: Direct updates by main Claude (avoid Agent context loss, following synthesis pattern)
+- **Reference-Based Integration**: Use @ references, not content duplication
+- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
+- **UI Designer Sync**: Mirror design system to ui-designer/style-guide.md
+- **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
+
+## Execution Protocol
+
+### Phase 1: Session & Design System Validation
+```bash
+# Validate session and verify design system completeness
+CHECK: .workflow/.active-* marker files
+VALIDATE: session_id matches active session
+
+VERIFY required artifacts:
+- .design/style-consolidation/design-tokens.json
+- .design/style-consolidation/style-guide.md
+- .design/style-consolidation/tailwind.config.js
+- .design/prototypes/*.html (at least one prototype)
+
+IF --selected-prototypes provided:
+    VALIDATE: Specified prototypes exist
+ELSE:
+    AUTO-SELECT: Use all generated prototypes
+```
+
+### Phase 2: Load Design System Context
+**Direct Claude Code Execution** (no Agent invocation)
+
+```bash
+# Load all design system artifacts
+Read(.workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)
+Read(.workflow/WFS-{session}/.design/style-consolidation/style-guide.md)
+Read(.workflow/WFS-{session}/.design/style-consolidation/style-philosophy.md)
+Read(.workflow/WFS-{session}/.design/style-consolidation/tailwind.config.js)
+
+# Load selected prototype files
+FOR each selected_prototype IN selected_prototypes:
+    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}.html)
+    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
+
+# Load target brainstorming artifacts
+Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
+```
+
+### Phase 3: Update Synthesis Specification
+**Direct Write by Main Claude**
+
+Update `.brainstorming/synthesis-specification.md`:
+
+```markdown
+## UI/UX Guidelines
+
+### Design System Reference
+**Finalized Design Tokens**: @../.design/style-consolidation/design-tokens.json
+**Style Guide**: @../.design/style-consolidation/style-guide.md
+**Tailwind Configuration**: @../.design/style-consolidation/tailwind.config.js
+
+### Design Philosophy
+[Insert content from style-philosophy.md]
+
+### Token System Overview
+**Colors**: OKLCH-based color system with semantic naming
+- Brand: primary, secondary, accent
+- Surface: background, elevated, sunken
+- Semantic: success, warning, error, info
+
+**Typography**: {font_family_count} font families, {scale_count}-step scale
+- Heading: {heading_font}
+- Body: {body_font}
+- Monospace: {mono_font}
+
+**Spacing**: {scale_count}-step scale ({min}rem to {max}rem)
+
+**Components**: Border radius, shadows, and component tokens defined
+
+### 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/prototypes/{prototype}.html
+  - Layout: {layout_description from notes}
+  - Components: {component_list from notes}
+  - Token Usage: {token_usage_summary from notes}
+
+### Design System Assets (for task-generate consumption)
+```json
+{
+  "design_tokens": ".design/style-consolidation/design-tokens.json",
+  "style_guide": ".design/style-consolidation/style-guide.md",
+  "tailwind_config": ".design/style-consolidation/tailwind.config.js",
+  "prototypes": [
+    ".design/prototypes/{prototype-1}.html",
+    ".design/prototypes/{prototype-2}.html"
+  ]
+}
+```
+```
+
+**Implementation**:
+```bash
+# Edit synthesis-specification.md
+Edit(
+  file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
+  old_string="## UI/UX Guidelines\n[existing content or empty]",
+  new_string="## UI/UX Guidelines\n\n[new design system content with @ references]"
+)
+```
+
+### Phase 4: Update UI Designer Analysis
+**Create or update** `.brainstorming/ui-designer/style-guide.md`:
+
+```markdown
+# UI Designer Style Guide
+
+## Design System Integration
+This style guide integrates the finalized design system from the design refinement phase.
+
+**Source Design Tokens**: @../../.design/style-consolidation/design-tokens.json
+**Source Style Guide**: @../../.design/style-consolidation/style-guide.md
+
+## Design Philosophy
+[Content from style-philosophy.md]
+
+## Design Tokens Reference
+For complete token definitions, see: @../../.design/style-consolidation/design-tokens.json
+
+### Color System
+[Summary of color tokens]
+
+### Typography System
+[Summary of typography tokens]
+
+### Spacing System
+[Summary of spacing tokens]
+
+### Component Tokens
+[Summary of component tokens: border-radius, shadows]
+
+## Component Patterns
+[Reference to style-guide.md component patterns]
+
+## 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
+[Links to selected prototypes with descriptions]
+
+---
+*Auto-generated by /workflow:design:design-update*
+*Last updated: {timestamp}*
+```
+
+**Implementation**:
+```bash
+Write(
+  file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
+  content="[generated style guide content with @ references]"
+)
+```
+
+### Phase 5: Create Design System Symlinks (Optional)
+**For easier task-generate discovery**
+
+```bash
+# Create read-only mirror of key design files in brainstorming space
+bash(cd .workflow/WFS-{session}/.brainstorming && \
+     ln -s ../.design/style-consolidation/design-tokens.json design-tokens.json && \
+     ln -s ../.design/style-consolidation/style-guide.md design-style-guide.md)
+```
+
+### Phase 6: TodoWrite Integration
+```javascript
+TodoWrite({
+  todos: [
+    {
+      content: "Validate session and design system completeness",
+      status: "completed",
+      activeForm: "Validating design system"
+    },
+    {
+      content: "Load design tokens, style guide, and selected prototypes",
+      status: "completed",
+      activeForm: "Loading design artifacts"
+    },
+    {
+      content: "Update synthesis-specification.md with design system references",
+      status: "completed",
+      activeForm: "Updating synthesis specification"
+    },
+    {
+      content: "Create or update ui-designer/style-guide.md",
+      status: "completed",
+      activeForm: "Updating UI designer style guide"
+    },
+    {
+      content: "Create design system symlinks for task-generate discovery",
+      status: "completed",
+      activeForm: "Creating artifact symlinks"
+    }
+  ]
+});
+```
+
+## 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 comprehensive style guide
+├── design-tokens.json               # Symlink to ../.design/style-consolidation/design-tokens.json
+└── design-style-guide.md            # Symlink to ../.design/style-consolidation/style-guide.md
+```
+
+**Reference Structure** (@ references in synthesis-specification.md):
+- `@../.design/style-consolidation/design-tokens.json`
+- `@../.design/style-consolidation/style-guide.md`
+- `@../.design/style-consolidation/tailwind.config.js`
+- `@../.design/prototypes/{prototype}.html`
+
+## Integration with task-generate
+
+After this update, `/workflow:tools:task-generate` will discover:
+
+**In context.artifacts**:
+```json
+{
+  "artifacts": [
+    {
+      "type": "synthesis_specification",
+      "path": ".brainstorming/synthesis-specification.md"
+    },
+    {
+      "type": "design_tokens",
+      "path": ".design/style-consolidation/design-tokens.json"
+    },
+    {
+      "type": "style_guide",
+      "path": ".design/style-consolidation/style-guide.md"
+    },
+    {
+      "type": "tailwind_config",
+      "path": ".design/style-consolidation/tailwind.config.js"
+    },
+    {
+      "type": "ui_prototypes",
+      "paths": [
+        ".design/prototypes/dashboard-variant-1.html",
+        ".design/prototypes/auth-variant-2.html"
+      ]
+    }
+  ]
+}
+```
+
+**In flow_control.pre_analysis** (for UI tasks):
+```json
+{
+  "step": "load_design_tokens",
+  "action": "Load design system tokens and style guide",
+  "commands": [
+    "bash(cat .workflow/WFS-{session}/.design/style-consolidation/design-tokens.json)",
+    "bash(cat .workflow/WFS-{session}/.design/style-consolidation/style-guide.md)"
+  ],
+  "output_to": "design_system_context",
+  "on_error": "warn"
+}
+```
+
+## Error Handling
+- **Missing design tokens**: Error, run `/workflow:design:style-consolidate` first
+- **Missing prototypes**: Error, run `/workflow:design:ui-generate` first
+- **synthesis-specification.md not found**: Warning, create minimal version
+- **Edit conflicts**: Preserve existing content, append design system section
+- **Symlink failures**: Warning only, continue with @ references
+
+## Validation Checks
+After update, verify:
+- [ ] synthesis-specification.md contains UI/UX Guidelines section
+- [ ] UI/UX Guidelines include @ references to design system files
+- [ ] ui-designer/style-guide.md created or updated
+- [ ] design-tokens.json symlink created (if applicable)
+- [ ] All referenced files exist and are readable
+
+## Integration Points
+- **Input**: design-tokens.json, style-guide.md, prototypes from design phase
+- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md
+- **Next Phase**: `/workflow:plan` can now discover and utilize design system
+
+## Completion Message
+
+```
+Design system update complete for session: WFS-{session}
+
+Updated artifacts:
+✓ synthesis-specification.md - UI/UX Guidelines section added
+✓ ui-designer/style-guide.md - Comprehensive style guide created
+✓ Design system references: @ notation for all design files
+
+Design system assets ready for task generation:
+- design-tokens.json ({token_count} tokens)
+- style-guide.md (comprehensive component patterns)
+- tailwind.config.js (Tailwind theme extension)
+- {prototype_count} reference prototypes
+
+Next: /workflow:plan [--agent] "<task description>"
+      The plan phase will automatically discover and utilize the design system.
+```
+
+## Main Claude Direct Execution Rationale
+
+This command is executed directly by main Claude (not delegated to an Agent) because:
+
+1. **Context Preservation**: Main Claude has full session context and conversation memory
+2. **Integration Complexity**: Requires understanding multiple artifact relationships
+3. **Reference Accuracy**: @ reference generation needs precise path resolution
+4. **Synthesis Pattern**: Follows the same direct-execution pattern as `/workflow:brainstorm:synthesis`
+5. **Minimal Transformation**: Primarily reference integration, not generative analysis
+6. **Error Recovery**: Main Claude can better handle edit conflicts and missing files
+
+This approach ensures reliable, context-aware integration without Agent handoff overhead.

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

@@ -0,0 +1,319 @@
+---
+name: style-consolidate
+description: Consolidate user-selected style variants into unified design system
+usage: /workflow:design:style-consolidate --session <session_id> [--interactive] [--variants "<ids>"]
+argument-hint: "--session WFS-session-id [--interactive] [--variants \"variant-1,variant-3\"]"
+examples:
+  - /workflow:design:style-consolidate --session WFS-auth --interactive
+  - /workflow:design:style-consolidate --session WFS-dashboard --variants "variant-1,variant-3"
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Bash(*)
+---
+
+# Style Consolidation Command
+
+## Overview
+Consolidate user-selected style variants into a unified, production-ready design system with validated CSS tokens and comprehensive style guide.
+
+## Core Philosophy
+- **User-Driven Selection**: Interactive mode for visual style card selection
+- **Gemini Clustering**: Semantic naming and style philosophy consolidation
+- **Codex Validation**: Token consistency, coverage, and accessibility checks
+- **Design System Output**: production-ready tokens + comprehensive style guide
+
+## Execution Protocol
+
+### Phase 1: Session & Style Cards Loading
+```bash
+# Validate session and load extracted style cards
+CHECK: .workflow/.active-* marker files
+VALIDATE: session_id matches active session
+VERIFY: .design/style-extraction/style-cards.json exists
+LOAD: style-cards.json for user selection
+```
+
+### Phase 2: User Selection (Interactive Mode)
+**Interactive Mode**: `--interactive` flag enables visual selection interface
+
+```bash
+IF --interactive:
+    DISPLAY: Style card previews with descriptions
+    PROMPT: "Select preferred style variants (comma-separated IDs):"
+    COLLECT: user_selection (e.g., "variant-1,variant-3")
+ELSE IF --variants provided:
+    PARSE: variant IDs from --variants flag
+ELSE:
+    ERROR: "Must provide either --interactive or --variants parameter"
+```
+
+### Phase 3: Gemini Style Philosophy Consolidation
+**Agent Invocation**: Task(conceptual-planning-agent) with Gemini capabilities
+
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Consolidate selected style variants into unified design philosophy
+
+## Context Loading
+ASSIGNED_TASK: style-consolidation
+OUTPUT_LOCATION: .workflow/WFS-{session}/.design/style-consolidation/
+SELECTED_VARIANTS: {user_selected_variant_ids}
+
+## Flow Control Steps
+1. **load_selected_variants**
+   - Action: Load user-selected style card data
+   - Command: Read(.workflow/WFS-{session}/.design/style-extraction/style-cards.json)
+   - Filter: Extract only selected variant IDs
+   - Output: selected_style_data
+
+2. **load_design_context**
+   - Action: Load brainstorming design context
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md) || Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md)
+   - Output: design_context
+   - Optional: true
+
+3. **consolidate_style_philosophy_gemini**
+   - Action: Synthesize unified style philosophy and semantic naming
+   - Command: bash(cd .workflow/WFS-{session} && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p \"
+     PURPOSE: Synthesize unified design philosophy from selected style variants
+     TASK: Create coherent style narrative, consolidate naming conventions, define design principles
+     MODE: write
+     CONTEXT: @{.design/style-extraction/style-cards.json,.brainstorming/synthesis-specification.md}
+     EXPECTED:
+     1. Unified design philosophy statement
+     2. Consolidated semantic naming for colors (e.g., 'brand-primary', 'surface-elevated')
+     3. Typography scale rationale
+     4. Spacing system principles
+     5. Component design guidelines
+     RULES: Ensure consistency, maintain accessibility mindset, align with brainstorming synthesis
+     \")
+   - Output: style-philosophy.md
+
+## Consolidation Requirements
+**Design Philosophy**: Clear statement of visual design principles
+**Semantic Naming**: User-centric token names (not generic color-1, color-2)
+**Accessibility**: Ensure WCAG AA contrast ratios for text colors
+**Consistency**: Unified token naming conventions across all categories
+
+## Expected Deliverables
+1. **style-philosophy.md**: Design philosophy and naming rationale
+"
+```
+
+### Phase 4: Codex Token Validation & Finalization
+**Agent Invocation**: Task(conceptual-planning-agent) with Codex capabilities
+
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Validate and finalize production-ready design tokens
+
+## Context Loading
+INPUT_PHILOSOPHY: .workflow/WFS-{session}/.design/style-consolidation/style-philosophy.md
+INPUT_TOKENS: .workflow/WFS-{session}/.design/style-extraction/design-tokens.json
+SELECTED_VARIANTS: {user_selected_variant_ids}
+OUTPUT_LOCATION: .workflow/WFS-{session}/.design/style-consolidation/
+
+## Flow Control Steps
+1. **load_consolidation_inputs**
+   - Action: Load style philosophy and extracted tokens
+   - Commands:
+     - Read(.workflow/WFS-{session}/.design/style-consolidation/style-philosophy.md)
+     - Read(.workflow/WFS-{session}/.design/style-extraction/design-tokens.json)
+     - Read(.workflow/WFS-{session}/.design/style-extraction/style-cards.json)
+   - Output: consolidation_inputs
+
+2. **validate_and_finalize_tokens_codex**
+   - Action: Merge selected variants, validate consistency, generate final tokens
+   - Command: bash(codex -C .workflow/WFS-{session}/.design/style-consolidation --full-auto exec \"
+     PURPOSE: Finalize production-ready design tokens with validation
+     TASK: Merge selected variant tokens, validate consistency, check accessibility, generate final design system
+     MODE: auto
+     CONTEXT: @{style-philosophy.md,../style-extraction/design-tokens.json,../style-extraction/style-cards.json,../../../CLAUDE.md}
+     EXPECTED:
+     1. design-tokens.json - Final validated CSS token definitions
+     2. tailwind.config.js - Complete Tailwind configuration
+     3. style-guide.md - Comprehensive design system documentation
+     4. validation-report.json - Token consistency and accessibility audit
+     RULES:
+     - Use semantic names from style-philosophy.md
+     - Validate WCAG AA contrast ratios (4.5:1 for text, 3:1 for UI)
+     - Ensure complete token coverage (colors, typography, spacing, shadows, borders)
+     - Generate CSS custom properties and Tailwind theme extension
+     - Include usage examples in style-guide.md
+     \" --skip-git-repo-check -s danger-full-access)
+   - Output: design-tokens.json, tailwind.config.js, style-guide.md, validation-report.json
+
+## Validation Requirements
+**Consistency Checks**:
+- All color tokens use OKLCH format
+- Spacing scale follows consistent ratio (e.g., 1.5x or 2x progression)
+- Typography scale includes appropriate line-heights
+- All tokens have semantic names
+
+**Accessibility Checks**:
+- Text colors meet WCAG AA contrast (4.5:1)
+- UI component colors meet WCAG AA contrast (3:1)
+- Focus indicators have sufficient visibility
+- Color is not sole differentiator
+
+**Coverage Checks**:
+- Primary, secondary, accent color families
+- Surface colors (background, elevated, sunken)
+- Semantic colors (success, warning, error, info)
+- Typography scale (xs to 4xl)
+- Spacing scale (0.25rem to 6rem)
+- Border radius options
+- Shadow layers
+
+## Expected Deliverables
+1. **design-tokens.json**: Production-ready CSS token definitions
+2. **tailwind.config.js**: Complete Tailwind theme configuration
+3. **style-guide.md**: Design system documentation with usage examples
+4. **validation-report.json**: Validation audit results
+"
+```
+
+### Phase 5: TodoWrite Integration
+```javascript
+TodoWrite({
+  todos: [
+    {
+      content: "Load session and style cards from extraction phase",
+      status: "completed",
+      activeForm: "Loading style cards"
+    },
+    {
+      content: "Collect user style variant selection (interactive or CLI)",
+      status: "completed",
+      activeForm: "Collecting user selection"
+    },
+    {
+      content: "Consolidate style philosophy using Gemini",
+      status: "completed",
+      activeForm: "Consolidating style philosophy"
+    },
+    {
+      content: "Validate and finalize tokens using Codex",
+      status: "completed",
+      activeForm: "Validating and finalizing tokens"
+    },
+    {
+      content: "Generate design system documentation",
+      status: "completed",
+      activeForm: "Generating design system docs"
+    }
+  ]
+});
+```
+
+## Output Structure
+
+```
+.workflow/WFS-{session}/.design/style-consolidation/
+├── style-philosophy.md          # Unified design philosophy (Gemini)
+├── design-tokens.json           # Final validated CSS tokens (Codex)
+├── tailwind.config.js           # Tailwind theme configuration (Codex)
+├── style-guide.md               # Design system documentation (Codex)
+└── validation-report.json       # Accessibility & consistency audit (Codex)
+```
+
+### design-tokens.json Format
+```json
+{
+  "colors": {
+    "brand": {
+      "primary": "oklch(0.45 0.20 270 / 1)",
+      "secondary": "oklch(0.60 0.15 200 / 1)",
+      "accent": "oklch(0.65 0.18 30 / 1)"
+    },
+    "surface": {
+      "background": "oklch(0.98 0.01 270 / 1)",
+      "elevated": "oklch(1.00 0.00 0 / 1)",
+      "sunken": "oklch(0.95 0.02 270 / 1)"
+    },
+    "semantic": {
+      "success": "oklch(0.55 0.15 150 / 1)",
+      "warning": "oklch(0.70 0.18 60 / 1)",
+      "error": "oklch(0.50 0.20 20 / 1)",
+      "info": "oklch(0.60 0.15 240 / 1)"
+    }
+  },
+  "typography": {
+    "font_family": {
+      "heading": "Inter, system-ui, sans-serif",
+      "body": "Inter, system-ui, sans-serif",
+      "mono": "Fira Code, monospace"
+    },
+    "font_size": {
+      "xs": "0.75rem",
+      "sm": "0.875rem",
+      "base": "1rem",
+      "lg": "1.125rem",
+      "xl": "1.25rem",
+      "2xl": "1.5rem",
+      "3xl": "1.875rem",
+      "4xl": "2.25rem"
+    },
+    "line_height": {
+      "tight": "1.25",
+      "normal": "1.5",
+      "relaxed": "1.75"
+    }
+  },
+  "spacing": {
+    "0": "0",
+    "1": "0.25rem",
+    "2": "0.5rem",
+    "3": "0.75rem",
+    "4": "1rem",
+    "6": "1.5rem",
+    "8": "2rem",
+    "12": "3rem",
+    "16": "4rem",
+    "24": "6rem"
+  },
+  "border_radius": {
+    "none": "0",
+    "sm": "0.25rem",
+    "md": "0.5rem",
+    "lg": "0.75rem",
+    "xl": "1rem",
+    "2xl": "1.5rem",
+    "full": "9999px"
+  },
+  "shadow": {
+    "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
+    "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)",
+    "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)",
+    "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15), 0 10px 10px oklch(0.00 0.00 0 / 0.04)"
+  }
+}
+```
+
+## Error Handling
+- **No style cards found**: Run `/workflow:design:style-extract` first
+- **Invalid variant IDs**: Display available IDs and prompt re-selection
+- **Validation failures**: Report specific issues (contrast, coverage, consistency)
+- **Gemini/Codex execution errors**: Retry with fallback to manual token editing
+
+## Integration Points
+- **Input**: style-cards.json from `/workflow:design:style-extract`
+- **Output**: design-tokens.json for `/workflow:design:ui-generate`
+- **Context**: synthesis-specification.md, ui-designer/analysis.md
+
+## Next Steps
+After successful consolidation:
+```
+Style consolidation complete for session: WFS-{session}
+Design tokens validated and finalized
+
+Validation summary:
+- Colors: {count} (WCAG AA compliant: {pass_count}/{total_count})
+- Typography: {scale_count} sizes
+- Spacing: {scale_count} values
+- Accessibility: {pass|warnings}
+
+Next: /workflow:design:ui-generate --session WFS-{session} --pages "dashboard,auth"
+```

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

@@ -0,0 +1,268 @@
+---
+name: style-extract
+description: Extract design style from reference images or text prompts using triple vision analysis or agent mode
+usage: /workflow:design:style-extract [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--use-agent]
+argument-hint: "[--session WFS-xxx] [--images \"refs/*.png\"] [--prompt \"Modern minimalist\"] [--variants 3] [--use-agent]"
+examples:
+  - /workflow:design:style-extract --images "design-refs/*.png" --variants 3
+  - /workflow:design:style-extract --prompt "Modern minimalist blog, dark theme" --variants 3 --use-agent
+  - /workflow:design:style-extract --session WFS-auth --images "refs/*.png" --prompt "Linear.app style" --variants 2
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*), Task(conceptual-planning-agent)
+---
+
+# Style Extraction Command
+
+## Overview
+Extract design style elements from reference images using triple vision analysis: Claude Code's native vision, Gemini Vision for semantic understanding, and Codex for structured token generation.
+
+## Core Philosophy
+- **Dual Mode Support**: Conventional triple vision OR agent-driven creative exploration
+- **Flexible Input**: Images, text prompts, or both combined
+- **Variant Control**: Generate N style cards based on `--variants` parameter (default: 3)
+- **Consensus Synthesis**: Multi-source analysis for quality assurance
+- **Style Card Output**: Reusable design direction cards for consolidation phase
+
+## Execution Protocol
+
+### Phase 0: Mode & Parameter Detection
+```bash
+# Detect execution mode
+IF --use-agent:
+    mode = "agent"  # Agent-driven creative exploration
+ELSE:
+    mode = "conventional"  # Triple vision analysis
+
+# Detect input source
+IF --images AND --prompt:
+    input_mode = "hybrid"  # Text guides image analysis
+ELSE IF --images:
+    input_mode = "image"
+ELSE IF --prompt:
+    input_mode = "text"
+ELSE:
+    ERROR: "Must provide --images or --prompt"
+
+# Detect session mode
+IF --session:
+    session_mode = "integrated"
+    session_id = {provided_session}
+    base_path = ".workflow/WFS-{session_id}/"
+ELSE:
+    session_mode = "standalone"
+    session_id = "design-session-" + timestamp()
+    base_path = "./{session_id}/"
+
+# Set variant count
+variants_count = --variants provided ? {count} : 3
+VALIDATE: 1 <= variants_count <= 5
+```
+
+### Phase 1: Input Validation & Preparation
+```bash
+# Validate and prepare inputs based on input_mode
+IF input_mode IN ["image", "hybrid"]:
+    EXPAND: --images glob pattern to concrete paths
+    VERIFY: at least one image file exists
+
+IF input_mode IN ["text", "hybrid"]:
+    VALIDATE: --prompt is non-empty string
+
+# Create session directory structure
+CREATE: {base_path}/.design/style-extraction/
+```
+
+### Phase 2: Style Extraction Execution
+
+**Route based on mode**:
+
+#### A. Conventional Mode (Triple Vision)
+Execute if `mode == "conventional"`
+
+**Step 1**: Claude Code initial analysis
+```bash
+IF input_mode IN ["image", "hybrid"]:
+    FOR each image IN expanded_image_paths:
+        Read({image_path})  # Claude analyzes visuals
+ELSE IF input_mode == "text":
+    # Analyze text prompt for design keywords
+    keywords = extract_design_keywords({prompt_text})
+
+Write({base_path}/.design/style-extraction/claude_analysis.json)
+```
+
+**Step 2**: Gemini deep semantic analysis
+```bash
+context_arg = ""
+IF input_mode IN ["image", "hybrid"]:
+    context_arg += "@{image_paths}"
+IF input_mode IN ["text", "hybrid"]:
+    guidance = "GUIDED BY PROMPT: '{prompt_text}'"
+
+bash(cd {base_path}/.design/style-extraction && \
+  ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+    PURPOSE: Extract design semantics {guidance}
+    TASK: Generate {variants_count} distinct style directions
+    MODE: write
+    CONTEXT: {context_arg}
+    EXPECTED: {variants_count} style analysis variants in JSON
+    RULES: OKLCH colors, semantic naming, explore diverse themes
+  ")
+```
+
+**Step 3**: Codex structured token generation
+```bash
+bash(codex -C {base_path}/.design/style-extraction --full-auto exec "
+  PURPOSE: Convert semantic analysis to structured tokens
+  TASK: Generate design-tokens.json and {variants_count} style-cards
+  MODE: auto
+  CONTEXT: @{claude_analysis.json,gemini output}
+  EXPECTED: design-tokens.json, style-cards.json with {variants_count} variants
+  RULES: OKLCH format, rem spacing, semantic names
+" --skip-git-repo-check -s danger-full-access)
+```
+
+#### B. Agent Mode (Creative Exploration)
+Execute if `mode == "agent"`
+
+**Agent-Driven Parallel Generation**:
+```bash
+# Prepare base context
+context_files = ""
+IF input_mode IN ["image", "hybrid"]:
+    context_files += "@{image_paths}"
+IF session_mode == "integrated":
+    context_files += "@{../../.brainstorming/synthesis-specification.md}"
+
+# Define creative themes for diversity
+themes = generate_creative_themes(variants_count)
+# Example: ["Modern Minimalist", "Brutalist Tech", "Organic Warmth"]
+
+# Launch parallel agent tasks
+FOR i IN range(variants_count):
+    Task(conceptual-planning-agent): "
+    [FLOW_CONTROL]
+
+    Generate unique design style variant: '{themes[i]}'
+
+    ## Context
+    INPUT_SOURCE: {input_mode}
+    PROMPT_GUIDANCE: {prompt_text if present else 'derive from images'}
+    THEME_FOCUS: {themes[i]}
+    OUTPUT_LOCATION: {base_path}/.design/style-extraction/
+
+    ## Flow Steps
+    1. **analyze_input**
+       IF input_mode IN ['image', 'hybrid']:
+           Use Gemini Vision to analyze images with theme focus
+       IF input_mode IN ['text', 'hybrid']:
+           Use Gemini to expand prompt into detailed design philosophy
+
+    2. **generate_tokens**
+       Use Codex to create design-tokens subset for this variant
+       Output: variant-{i}-tokens.json
+
+    3. **create_style_card**
+       Synthesize into style card with:
+       - id: 'variant-{i}'
+       - name: '{themes[i]}'
+       - preview: key design token values
+       Output: variant-{i}-card.json
+
+    ## Rules
+    - Focus on '{themes[i]}' aesthetic
+    - OKLCH colors, rem spacing, semantic naming
+    - Must be distinct from other variants
+    "
+
+# Consolidate parallel results
+Wait for all {variants_count} tasks to complete
+Consolidate variant-*-card.json → style-cards.json
+Merge variant-*-tokens.json → design-tokens.json (include all variants)
+```
+
+**Output**: `style-cards.json` with {variants_count} creatively distinct variants
+
+### Phase 3: TodoWrite & Completion
+
+```javascript
+TodoWrite({
+  todos: [
+    {content: "Detect mode and validate inputs", status: "completed", activeForm: "Detecting mode"},
+    {content: "Execute style extraction (conventional/agent mode)", status: "completed", activeForm: "Extracting styles"},
+    {content: "Generate {variants_count} style cards", status: "completed", activeForm: "Generating style cards"}
+  ]
+});
+```
+
+**Completion Message**:
+```
+Style extraction complete for session: {session_id}
+Mode: {mode} | Input: {input_mode} | Variants: {variants_count}
+
+Generated {variants_count} style cards:
+{list_variant_names}
+
+Location: {base_path}/.design/style-extraction/
+
+Next: /workflow:design:style-consolidate --session {session_id} --variants "{selected_ids}"
+```
+
+## Output Structure
+
+```
+.workflow/WFS-{session}/.design/style-extraction/
+├── semantic_style_analysis.json    # Gemini Vision semantic analysis
+├── design-tokens.json              # Structured CSS tokens (OKLCH)
+├── tailwind-tokens.js              # Tailwind config extension
+└── style-cards.json                # Style variants for user selection
+```
+
+### style-cards.json Format
+```json
+{
+  "style_cards": [
+    {
+      "id": "variant-1",
+      "name": "Modern Minimalist",
+      "description": "Clean, high contrast with bold typography",
+      "preview": {
+        "primary": "oklch(0.45 0.20 270 / 1)",
+        "background": "oklch(0.98 0.01 270 / 1)",
+        "font_heading": "Inter, system-ui, sans-serif",
+        "border_radius": "0.5rem"
+      }
+    },
+    {
+      "id": "variant-2",
+      "name": "Soft Neumorphic",
+      "description": "Subtle shadows with gentle colors",
+      "preview": {
+        "primary": "oklch(0.60 0.10 200 / 1)",
+        "background": "oklch(0.95 0.02 200 / 1)",
+        "font_heading": "Poppins, sans-serif",
+        "border_radius": "1rem"
+      }
+    }
+  ]
+}
+```
+
+## Error Handling
+- **No images found**: Report error and suggest correct glob pattern
+- **Gemini Vision failure**: Retry once, then fall back to manual style description
+- **Codex token generation failure**: Use default token template and report warning
+- **Invalid session**: Prompt user to start workflow session first
+
+## Integration Points
+- **Input**: Reference images (PNG, JPG, WebP)
+- **Output**: Style cards for `/workflow:design:style-consolidate`
+- **Context**: Optional synthesis-specification.md or ui-designer/analysis.md
+
+## Next Steps
+After successful extraction:
+```
+Style extraction complete for session: WFS-{session}
+Style cards generated: {count}
+
+Next: /workflow:design:style-consolidate --session WFS-{session} [--interactive]
+```

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

@@ -0,0 +1,554 @@
+---
+name: ui-generate
+description: Generate UI prototypes using consolidated design tokens with conventional or agent mode
+usage: /workflow:design:ui-generate [--pages "<list>"] [--session <id>] [--variants <count>] [--use-agent]
+argument-hint: "[--pages \"dashboard,auth\"] [--session WFS-xxx] [--variants 3] [--use-agent]"
+examples:
+  - /workflow:design:ui-generate --variants 2
+  - /workflow:design:ui-generate --session WFS-auth --variants 3 --use-agent
+  - /workflow:design:ui-generate --pages "home,pricing,contact" --variants 2
+allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Task(conceptual-planning-agent)
+---
+
+# UI Generation Command
+
+## Overview
+Generate production-ready UI prototypes (HTML/CSS) strictly adhering to consolidated design tokens and synthesis specification requirements.
+
+## Core Philosophy
+- **Dual Mode**: Conventional (Codex primary) OR agent-driven (creative layouts)
+- **Token-Driven**: All styles reference design-tokens.json, no hardcoded values
+- **Variant Control**: Generate N prototypes per page based on `--variants` (default: 1)
+- **Layout Diversity**: Agent mode explores structural variations (F-pattern, grid, asymmetric)
+- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
+
+## Execution Protocol
+
+### Phase 1: Mode Detection & Context Loading
+```bash
+# Detect execution mode
+IF --use-agent:
+    mode = "agent"  # Agent-driven creative layouts
+ELSE:
+    mode = "conventional"  # Codex primary generation
+
+# Detect session mode
+IF --session:
+    session_mode = "integrated"
+    session_id = {provided_session}
+    base_path = ".workflow/WFS-{session_id}/"
+ELSE:
+    session_mode = "standalone"
+    # Infer session_id from existing design-session-* directory
+    base_path = "./{detected_design_session}/"
+
+# Infer page list if not provided
+IF --pages provided:
+    page_list = {explicit_pages}
+ELSE IF session_mode == "integrated":
+    # Read synthesis-specification.md to extract page requirements
+    page_list = extract_pages_from_synthesis({base_path}/.brainstorming/synthesis-specification.md)
+ELSE:
+    # Infer from generated prototypes or default
+    page_list = detect_from_prototypes({base_path}/.design/prototypes/) OR ["home"]
+
+VALIDATE: page_list not empty
+
+# Set parameters
+variants_count = --variants provided ? {count} : 1
+VALIDATE: 1 <= variants_count <= 5
+
+# Load design system
+VERIFY: {base_path}/.design/style-consolidation/design-tokens.json exists
+LOAD: design-tokens.json, style-guide.md, tailwind.config.js
+
+# Load requirements (if integrated mode)
+IF session_mode == "integrated":
+    LOAD: {base_path}/.brainstorming/synthesis-specification.md
+```
+
+### Phase 2: UI Generation Execution
+
+**Route based on mode**:
+
+#### A. Conventional Mode (Codex Primary)
+Execute if `mode == "conventional"`
+
+```bash
+# Single Codex call generates all variants for all pages
+bash(codex -C {base_path}/.design/prototypes --full-auto exec "
+  PURPOSE: Generate UI prototypes adhering to design tokens
+  TASK: Create HTML/CSS for pages: {page_list} with {variants_count} variant(s) each
+  MODE: auto
+  CONTEXT: @{../style-consolidation/design-tokens.json,../style-consolidation/style-guide.md}
+  EXPECTED:
+  For each page, generate {variants_count} variant(s):
+  - {page}-variant-{n}.html (semantic HTML5)
+  - {page}-variant-{n}.css (token-driven, no hardcoded values)
+  - {page}-variant-{n}-notes.md (implementation notes)
+
+  RULES:
+  - STRICT token adherence: var(--color-brand-primary), var(--spacing-4)
+  - Semantic HTML5 + ARIA attributes
+  - Responsive: mobile-first, token-based breakpoints
+  - Variants differ in minor layout details
+" --skip-git-repo-check -s danger-full-access)
+```
+
+#### B. Agent Mode (Creative Layouts)
+Execute if `mode == "agent"`
+
+**Agent-Driven Parallel Generation**:
+```bash
+# Define layout strategies for diversity
+layouts = generate_layout_strategies(variants_count)
+# Example: ["F-Pattern", "Asymmetric Grid", "Card-Based Modular"]
+
+# Launch parallel agent tasks for each page-variant combination
+FOR page IN page_list:
+  FOR i IN range(variants_count):
+    Task(conceptual-planning-agent): "
+    [FLOW_CONTROL]
+
+    Generate UI prototype: {page} using '{layouts[i]}' layout
+
+    ## Context
+    PAGE: {page}
+    LAYOUT_STRATEGY: {layouts[i]}
+    OUTPUT: {base_path}/.design/prototypes/
+
+    ## Flow Steps
+    1. **load_design_system**
+       Read design-tokens.json and style-guide.md
+
+    2. **load_requirements**
+       IF session_mode == 'integrated':
+           Read synthesis-specification.md for {page} requirements
+
+    3. **generate_prototype_codex**
+       Use Codex to generate HTML/CSS with layout focus:
+       Layout: {layouts[i]}
+       Token adherence: STRICT (all values from design-tokens)
+       Output: {page}-variant-{i}.html/css/notes.md
+
+    ## Rules
+    - Layout must follow '{layouts[i]}' strategy
+    - Examples:
+      * F-Pattern: Content flows top→left→middle→bottom
+      * Asymmetric Grid: Strong visual hierarchy, off-center
+      * Card-Based: Modular components, flexible grid
+    - STRICT token usage, semantic HTML, ARIA attributes
+    "
+
+Wait for all {len(page_list) * variants_count} tasks to complete
+```
+
+### Phase 3: Generate Preview Files
+
+```bash
+# Generate preview utilities
+Write({base_path}/.design/prototypes/index.html)  # Master navigation
+Write({base_path}/.design/prototypes/compare.html)  # Side-by-side comparison
+Write({base_path}/.design/prototypes/PREVIEW.md)  # Setup instructions
+```
+
+### Phase 4: TodoWrite & Completion
+
+```javascript
+TodoWrite({
+  todos: [
+    {content: "Detect mode and load design system", status: "completed", activeForm: "Loading design system"},
+    {content: "Generate {len(page_list) * variants_count} UI prototypes", status: "completed", activeForm: "Generating prototypes"},
+    {content: "Generate preview files", status: "completed", activeForm: "Generating preview"}
+  ]
+});
+```
+
+**Completion Message**:
+```
+UI generation complete for session: {session_id}
+Mode: {mode} | Pages: {page_list} | Variants: {variants_count}
+
+Generated {len(page_list) * variants_count} prototypes:
+{list_generated_files}
+
+Location: {base_path}/.design/prototypes/
+
+Preview: Open index.html or run: python -m http.server 8080
+
+Next: /workflow:design:design-update --session {session_id} --selected-prototypes "{selected_ids}"
+```
+
+## Output Structure
+
+```
+.workflow/WFS-{session}/.design/prototypes/
+├── index.html                     # 🆕 Preview index page (master navigation)
+├── compare.html                   # 🆕 Side-by-side comparison view
+├── PREVIEW.md                     # 🆕 Preview instructions and server setup
+├── dashboard-variant-1.html
+├── dashboard-variant-1.css
+├── dashboard-variant-1-notes.md
+├── dashboard-variant-2.html (if --variants 2)
+├── dashboard-variant-2.css
+├── dashboard-variant-2-notes.md
+├── auth-variant-1.html
+├── auth-variant-1.css
+├── auth-variant-1-notes.md
+├── design-tokens.css              # CSS custom properties from design-tokens.json
+└── variant-suggestions.md         # Gemini layout rationale (if variants > 1)
+```
+
+### HTML Prototype Example
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard - Variant 1</title>
+  <link rel="stylesheet" href="design-tokens.css">
+  <link rel="stylesheet" href="dashboard-variant-1.css">
+</head>
+<body>
+  <header role="banner" class="header">
+    <nav role="navigation" aria-label="Main navigation" class="nav">
+      <!-- Token-based navigation -->
+    </nav>
+  </header>
+  <main role="main" class="main">
+    <section aria-labelledby="dashboard-heading" class="dashboard-section">
+      <h1 id="dashboard-heading" class="heading-primary">Dashboard</h1>
+      <!-- Content using design tokens -->
+    </section>
+  </main>
+  <footer role="contentinfo" class="footer">
+    <!-- Footer content -->
+  </footer>
+</body>
+</html>
+```
+
+### CSS Example
+```css
+/* Design Tokens (auto-generated from design-tokens.json) */
+:root {
+  --color-brand-primary: oklch(0.45 0.20 270 / 1);
+  --color-surface-background: oklch(0.98 0.01 270 / 1);
+  --spacing-4: 1rem;
+  --spacing-6: 1.5rem;
+  --font-size-lg: 1.125rem;
+  --border-radius-md: 0.5rem;
+  --shadow-md: 0 4px 6px oklch(0.00 0.00 0 / 0.07);
+}
+
+/* Component Styles (using tokens) */
+.header {
+  background-color: var(--color-surface-elevated);
+  padding: var(--spacing-4) var(--spacing-6);
+  box-shadow: var(--shadow-md);
+}
+
+.heading-primary {
+  font-size: var(--font-size-3xl);
+  color: var(--color-brand-primary);
+  margin-bottom: var(--spacing-6);
+}
+```
+
+### Preview Index Page Template (index.html)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>UI Prototypes Preview - WFS-{session}</title>
+  <style>
+    body { font-family: system-ui; max-width: 1200px; margin: 2rem auto; padding: 0 1rem; }
+    h1 { color: #2563eb; }
+    .prototype-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: 1.5rem; margin-top: 2rem; }
+    .prototype-card { border: 1px solid #e5e7eb; border-radius: 0.5rem; padding: 1rem; transition: box-shadow 0.2s; }
+    .prototype-card:hover { box-shadow: 0 4px 12px rgba(0,0,0,0.1); }
+    .prototype-card h3 { margin: 0 0 0.5rem; color: #1f2937; }
+    .prototype-card .meta { font-size: 0.875rem; color: #6b7280; margin-bottom: 1rem; }
+    .prototype-card a { display: inline-block; margin-right: 0.5rem; color: #2563eb; text-decoration: none; }
+    .prototype-card a:hover { text-decoration: underline; }
+    .actions { margin-top: 2rem; padding: 1rem; background: #f3f4f6; border-radius: 0.5rem; }
+    .actions a { margin-right: 1rem; color: #2563eb; }
+  </style>
+</head>
+<body>
+  <h1>🎨 UI Prototypes Preview</h1>
+  <p><strong>Session:</strong> WFS-{session} | <strong>Generated:</strong> {timestamp}</p>
+
+  <div class="actions">
+    <a href="compare.html">📊 Compare All Variants</a>
+    <a href="PREVIEW.md">📖 Preview Instructions</a>
+  </div>
+
+  <div class="prototype-grid">
+    <!-- Auto-generated for each page-variant -->
+    <div class="prototype-card">
+      <h3>Dashboard - Variant 1</h3>
+      <div class="meta">Generated: {timestamp}</div>
+      <a href="dashboard-variant-1.html" target="_blank">View Prototype →</a>
+      <a href="dashboard-variant-1-notes.md">Implementation Notes</a>
+    </div>
+  </div>
+</body>
+</html>
+```
+
+### Comparison View Template (compare.html)
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Side-by-Side Comparison - WFS-{session}</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { font-family: system-ui; }
+    .header { background: #1f2937; color: white; padding: 1rem 2rem; display: flex; justify-content: space-between; align-items: center; }
+    .controls { display: flex; gap: 1rem; align-items: center; }
+    select, button { padding: 0.5rem 1rem; border-radius: 0.25rem; border: 1px solid #d1d5db; background: white; cursor: pointer; }
+    button:hover { background: #f3f4f6; }
+    .comparison-container { display: flex; height: calc(100vh - 60px); }
+    .variant-panel { flex: 1; border-right: 2px solid #e5e7eb; position: relative; }
+    .variant-panel:last-child { border-right: none; }
+    .variant-label { position: absolute; top: 0; left: 0; right: 0; background: rgba(37,99,235,0.9); color: white; padding: 0.5rem; text-align: center; z-index: 10; font-weight: 600; }
+    iframe { width: 100%; height: 100%; border: none; padding-top: 2.5rem; }
+    .viewport-toggle { display: flex; gap: 0.5rem; }
+    .viewport-btn { padding: 0.25rem 0.75rem; font-size: 0.875rem; }
+    .viewport-btn.active { background: #2563eb; color: white; border-color: #2563eb; }
+  </style>
+</head>
+<body>
+  <div class="header">
+    <h1>📊 Side-by-Side Comparison</h1>
+    <div class="controls">
+      <div class="viewport-toggle">
+        <button class="viewport-btn active" data-width="100%">Desktop</button>
+        <button class="viewport-btn" data-width="768px">Tablet</button>
+        <button class="viewport-btn" data-width="375px">Mobile</button>
+      </div>
+      <select id="page-select">
+        <option value="dashboard">Dashboard</option>
+        <option value="auth">Auth</option>
+      </select>
+      <label><input type="checkbox" id="sync-scroll"> Sync Scroll</label>
+      <a href="index.html" style="color: white;">← Back to Index</a>
+    </div>
+  </div>
+
+  <div class="comparison-container">
+    <div class="variant-panel">
+      <div class="variant-label">Variant 1</div>
+      <iframe id="frame1" src="dashboard-variant-1.html"></iframe>
+    </div>
+    <div class="variant-panel">
+      <div class="variant-label">Variant 2</div>
+      <iframe id="frame2" src="dashboard-variant-2.html"></iframe>
+    </div>
+  </div>
+
+  <script>
+    // Viewport switching
+    document.querySelectorAll('.viewport-btn').forEach(btn => {
+      btn.addEventListener('click', () => {
+        document.querySelectorAll('.viewport-btn').forEach(b => b.classList.remove('active'));
+        btn.classList.add('active');
+        const width = btn.dataset.width;
+        document.querySelectorAll('iframe').forEach(frame => {
+          frame.style.width = width;
+          frame.style.margin = width === '100%' ? '0' : '0 auto';
+        });
+      });
+    });
+
+    // Synchronized scrolling
+    const syncCheckbox = document.getElementById('sync-scroll');
+    const frames = [document.getElementById('frame1'), document.getElementById('frame2')];
+
+    syncCheckbox.addEventListener('change', () => {
+      if (syncCheckbox.checked) {
+        frames.forEach(frame => {
+          frame.contentWindow.addEventListener('scroll', () => {
+            const scrollTop = frame.contentWindow.scrollY;
+            frames.forEach(f => {
+              if (f !== frame) f.contentWindow.scrollTo(0, scrollTop);
+            });
+          });
+        });
+      }
+    });
+
+    // Page switching
+    document.getElementById('page-select').addEventListener('change', (e) => {
+      const page = e.target.value;
+      document.getElementById('frame1').src = `${page}-variant-1.html`;
+      document.getElementById('frame2').src = `${page}-variant-2.html`;
+    });
+  </script>
+</body>
+</html>
+```
+
+### Preview Instructions Template (PREVIEW.md)
+```markdown
+# UI Prototypes Preview Guide
+
+## Session Information
+- **Session ID**: WFS-{session}
+- **Generated**: {timestamp}
+- **Pages**: {page_list}
+- **Variants per page**: {variants_count}
+
+## Quick Preview Options
+
+### Option 1: Direct Browser Opening (Simplest)
+1. Navigate to `.workflow/WFS-{session}/.design/prototypes/`
+2. Double-click `index.html` to open the preview index
+3. Click any prototype link to view in browser
+
+### Option 2: Local Development Server (Recommended)
+
+#### Python (Built-in)
+```bash
+cd .workflow/WFS-{session}/.design/prototypes
+python -m http.server 8080
+# Visit: http://localhost:8080
+```
+
+#### Node.js (npx)
+```bash
+cd .workflow/WFS-{session}/.design/prototypes
+npx http-server -p 8080
+# Visit: http://localhost:8080
+```
+
+#### PHP (Built-in)
+```bash
+cd .workflow/WFS-{session}/.design/prototypes
+php -S localhost:8080
+# Visit: http://localhost:8080
+```
+
+#### VS Code Live Server
+1. Install "Live Server" extension
+2. Right-click `index.html`
+3. Select "Open with Live Server"
+
+## Preview Features
+
+### Index Page (`index.html`)
+- **Master navigation** for all prototypes
+- **Quick links** to individual variants
+- **Metadata display**: timestamps, page info
+- **Direct access** to implementation notes
+
+### Comparison View (`compare.html`)
+- **Side-by-side** variant comparison
+- **Viewport toggles**: Desktop (100%), Tablet (768px), Mobile (375px)
+- **Synchronized scrolling** option
+- **Page switching** dropdown
+- **Real-time** comparison
+
+## Browser Compatibility
+- ✅ Chrome/Edge (Recommended)
+- ✅ Firefox
+- ✅ Safari
+- ⚠️ Some CSS features may require modern browsers (OKLCH colors)
+
+## Files Overview
+```
+prototypes/
+├── index.html          ← Start here
+├── compare.html        ← Side-by-side comparison
+├── PREVIEW.md          ← This file
+├── {page}-variant-{n}.html  ← Individual prototypes
+├── {page}-variant-{n}.css   ← Styles (token-driven)
+├── design-tokens.css   ← CSS custom properties
+└── {page}-variant-{n}-notes.md  ← Implementation guidance
+```
+
+## Next Steps
+1. **Review prototypes**: Open index.html
+2. **Compare variants**: Use compare.html for side-by-side view
+3. **Select preferred**: Note variant IDs for design-update command
+4. **Continue workflow**: Run design-update with selected prototypes
+
+## Troubleshooting
+
+**Styles not loading?**
+- Ensure `design-tokens.css` is in the same directory
+- Check browser console for CSS errors
+- Verify file paths in HTML `<link>` tags
+
+**OKLCH colors not displaying?**
+- Use Chrome/Edge 111+ or Firefox 113+
+- Fallback colors should work in older browsers
+
+**Local server CORS issues?**
+- Use one of the recommended local servers
+- Avoid opening HTML files with `file://` protocol for best results
+```
+
+
+## Error Handling
+- **No design tokens found**: Run `/workflow:design:style-consolidate` first
+- **Invalid page names**: List available pages from synthesis-specification.md
+- **Codex generation errors**: Retry with simplified requirements, report warnings
+- **Token reference errors**: Validate all CSS against design-tokens.json
+
+## Quality Checks
+After generation, verify:
+- [ ] All CSS values reference design token custom properties
+- [ ] No hardcoded colors, spacing, or typography
+- [ ] Semantic HTML structure
+- [ ] Accessibility attributes present
+- [ ] Responsive design implemented
+- [ ] Token-driven styling consistent across variants
+
+## Integration Points
+- **Input**: design-tokens.json, style-guide.md, synthesis-specification.md
+- **Output**: HTML/CSS prototypes for `/workflow:design:design-update`
+- **Context**: ui-designer/analysis.md for UX guidance
+
+## Next Steps
+After successful generation:
+```
+✅ UI prototypes generated for session: WFS-{session}
+Pages: {page_list}
+Variants per page: {variants_count}
+
+Generated files:
+- {count} HTML prototypes (complete, standalone)
+- {count} CSS files (token-driven)
+- {count} implementation notes
+- 🆕 index.html (preview navigation)
+- 🆕 compare.html (side-by-side comparison)
+- 🆕 PREVIEW.md (preview instructions)
+
+📂 Location: .workflow/WFS-{session}/.design/prototypes/
+
+🌐 Preview Options:
+1. Quick: Open index.html in browser
+2. Full: Start local server and visit http://localhost:8080
+   - Python: cd prototypes && python -m http.server 8080
+   - Node.js: cd prototypes && npx http-server -p 8080
+
+📊 Compare Variants:
+- Open compare.html for side-by-side view
+- Toggle viewports: Desktop / Tablet / Mobile
+- Switch between pages dynamically
+- Synchronized scrolling option
+
+Review prototypes and select preferred variants, then run:
+/workflow:design:design-update --session WFS-{session} --selected-prototypes "{page-variant-ids}"
+
+Example:
+/workflow:design:design-update --session WFS-{session} --selected-prototypes "dashboard-variant-1,auth-variant-2"
+```

.claude/commands/workflow/plan.md

@@ -143,7 +143,12 @@ Planning complete for session: [sessionId]
 Tasks generated: [count]
 Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
-Next: /workflow:execute or /workflow:status
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
+2. /workflow:status  # Review task breakdown
+3. /workflow:execute  # Start implementation (after verification)
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern

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

@@ -26,10 +26,11 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data for next phase
 4. **Sequential Execution**: Each phase depends on previous output
-5. **Complete All Phases**: Do not return until Phase 5 completes
+5. **Complete All Phases**: Do not return until Phase 7 completes (with concept verification)
 6. **TDD Context**: All descriptions include "TDD:" prefix
+7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
 
-## 6-Phase Execution
+## 7-Phase Execution (with Concept Verification)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -79,7 +80,22 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
 
-### Phase 5: TDD Task Generation
+### Phase 5: Concept Verification (NEW QUALITY GATE)
+**Command**: `/workflow:concept-verify --session [sessionId]`
+
+**Purpose**: Verify conceptual clarity before TDD task generation
+- Clarify test requirements and acceptance criteria
+- Resolve ambiguities in expected behavior
+- Validate TDD approach is appropriate
+
+**Behavior**:
+- If no ambiguities found → Auto-proceed to Phase 6
+- If ambiguities exist → Interactive clarification (up to 5 questions)
+- After clarifications → Auto-proceed to Phase 6
+
+**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+
+### Phase 6: TDD Task Generation
 **Command**:
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
@@ -93,10 +109,10 @@ TEST_FOCUS: [Test scenarios]
 - IMPL tasks include test-fix-cycle configuration
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 
-### Phase 6: TDD Structure Validation
-**Internal validation (no command)**
+### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
+**Internal validation first, then recommend external verification**
 
-**Validate**:
+**Internal Validation**:
 1. Each feature has TEST → IMPL → REFACTOR chain
 2. Dependencies: IMPL depends_on TEST, REFACTOR depends_on IMPL
 3. Meta fields: tdd_phase correct ("red"/"green"/"refactor")
@@ -117,20 +133,26 @@ Structure:
 
 Plan:
 - Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
-  (includes TDD Task Chains section)
+  (includes TDD Task Chains section with workflow_type: "tdd")
 
-Next: /workflow:execute or /workflow:tdd-verify
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+2. /workflow:execute --session [sessionId]  # Start TDD execution
+3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task dependencies
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
-// Initialize (6 phases now)
+// Initialize (7 phases now with concept verification)
 [
   {content: "Execute session discovery", status: "in_progress", activeForm: "Executing session discovery"},
-  {content: "Execute context gathering", status: "pending", activeForm: "Executing context gathering"},
-  {content: "Execute test coverage analysis", status: "pending", activeForm: "Executing test coverage analysis"},
-  {content: "Execute TDD analysis", status: "pending", activeForm: "Executing TDD analysis"},
+  {content: "Execute context gathering", status: "pending", activeForm": "Executing context gathering"},
+  {content: "Execute test coverage analysis", status: "pending", activeForm": "Executing test coverage analysis"},
+  {content: "Execute TDD analysis", status: "pending", activeForm": "Executing TDD analysis"},
+  {content: "Execute concept verification", status: "pending", activeForm": "Executing concept verification"},
   {content: "Execute TDD task generation", status: "pending", activeForm: "Executing TDD task generation"},
   {content: "Validate TDD structure", status: "pending", activeForm: "Validating TDD structure"}
 ]

.claude/commands/workflow/tools/docs.md

@@ -1,256 +1,590 @@
 ---
 name: docs
-description: Generate hierarchical architecture and API documentation using doc-generator agent with flow_control
-usage: /workflow:docs <type> [scope]
-argument-hint: "architecture"|"api"|"all"
+description: Documentation planning and orchestration - creates structured documentation tasks for execution
+usage: /workflow:docs <type> [options]
+argument-hint: "architecture"|"api"|"all" [--tool <gemini|qwen|codex>] [--scope <path>]
 examples:
-  - /workflow:docs all
-  - /workflow:docs architecture src/modules
-  - /workflow:docs api --scope api/
+  - /workflow:docs all                          # Complete documentation (gemini default)
+  - /workflow:docs all --tool qwen              # Use Qwen for architecture focus
+  - /workflow:docs architecture --scope src/modules
+  - /workflow:docs api --tool gemini --scope api/
 ---
 
 # Workflow Documentation Command
 
+## Purpose
+
+**`/workflow:docs` is a lightweight planner/orchestrator** - it analyzes project structure using metadata tools, decomposes documentation work into tasks, and generates execution plans. It does **NOT** generate any documentation content itself.
+
+**Key Principle**: Lightweight Planning + Targeted Execution
+- **docs.md** → Collect metadata (paths, structure), generate task JSONs with path references
+- **doc-generator.md** → Execute targeted analysis on focus_paths, generate content
+
+**Optimization Philosophy**:
+- **Planning phase**: Minimal context - only metadata (module paths, file lists via `get_modules_by_depth.sh` and Code Index MCP)
+- **Task JSON**: Store path references, not content
+- **Execution phase**: Targeted deep analysis within focus_paths scope
+
 ## Usage
+
 ```bash
-/workflow:docs <type> [scope]
+/workflow:docs <type> [--tool <gemini|qwen|codex>] [--scope <path>]
 ```
 
-## Input Detection
-- **Document Types**: `architecture`, `api`, `all` → Creates appropriate documentation tasks
-- **Scope**: Optional module/directory filtering → Focuses documentation generation
-- **Default**: `all` → Complete documentation suite
+### Parameters
 
-## Core Workflow
+- **type**: `architecture` | `api` | `all` (required)
+  - `architecture`: System design, module interactions, patterns
+  - `api`: Endpoint documentation, API specifications
+  - `all`: Complete documentation suite
 
-### Planning & Task Creation Process
-The command performs structured planning and task creation:
+- **--tool**: `gemini` | `qwen` | `codex` (optional, default: gemini)
+  - `gemini`: Comprehensive documentation, pattern recognition
+  - `qwen`: Architecture analysis, system design focus
+  - `codex`: Implementation validation, code quality
 
-**0. Pre-Planning Architecture Analysis** ⚠️ MANDATORY FIRST STEP
-- **System Structure Analysis**: MUST run `bash(~/.claude/scripts/get_modules_by_depth.sh)` for dynamic task decomposition
-- **Module Boundary Identification**: Understand module organization and dependencies
-- **Architecture Pattern Recognition**: Identify architectural styles and design patterns
-- **Foundation for documentation**: Use structure analysis to guide task decomposition
+- **--scope**: Directory path filter (optional)
 
-**1. Documentation Planning**
-- **Type Analysis**: Determine documentation scope (architecture/api/all)
-- **Module Discovery**: Use architecture analysis results to identify components
-- **Dynamic Task Decomposition**: Analyze project structure to determine optimal task count and module grouping
-- **Session Management**: Create or use existing documentation session
+## Planning Workflow
 
-**2. Task Generation**
-- **Create session**: `.workflow/WFS-docs-[timestamp]/`
-- **Create active marker**: `.workflow/.active-WFS-docs-[timestamp]` (must match session folder name)
-- **Generate IMPL_PLAN.md**: Documentation requirements and task breakdown
-- **Create task.json files**: Individual documentation tasks with flow_control
-- **Setup TODO_LIST.md**: Progress tracking for documentation generation
+### Complete Execution Flow
 
-### Session Management ⚠️ CRITICAL
-- **Check for active sessions**: Look for `.workflow/.active-WFS-docs-*` markers
-- **Marker naming**: Active marker must exactly match session folder name
-- **Session creation**: `WFS-docs-[timestamp]` folder with matching `.active-WFS-docs-[timestamp]` marker
-- **Task execution**: Use `/workflow:execute` to run individual documentation tasks within active session
-- **Session isolation**: Each documentation session maintains independent context and state
+```
+/workflow:docs [type] [--tool] [--scope]
+    ↓
+Phase 1: Init Session → Create session dir & active marker
+    ↓
+Phase 2: Module Analysis → Run get_modules_by_depth.sh
+    ↓
+Phase 3: Quick Assess → Check existing docs
+    ↓
+Phase 4: Decompose → Create task list & TodoWrite
+    ↓
+Phase 5: Generate Tasks → Build IMPL-*.json & plans
+    ↓
+✅ Planning Complete → Show TodoWrite status
+```
 
-## Output Structure
+### Phase Details
+
+#### Phase 1: Session Initialization
+```bash
+# Parse arguments and create session structure
+doc_type="all"  # architecture|api|all
+tool="gemini"   # gemini|qwen|codex (default: gemini)
+scope=""        # optional path filter
+
+timestamp=$(date +%Y%m%d-%H%M%S)
+session_dir=".workflow/WFS-docs-${timestamp}"
+mkdir -p "${session_dir}"/{.task,.process,.summaries}
+touch ".workflow/.active-WFS-docs-${timestamp}"
+```
+
+#### Phase 2: Lightweight Metadata Collection (MANDATORY)
+```bash
+# Step 1: Run get_modules_by_depth.sh for module hierarchy (metadata only)
+module_data=$(~/.claude/scripts/get_modules_by_depth.sh)
+# Format: depth:N|path:<PATH>|files:N|size:N|has_claude:yes/no
+
+# Step 2: Use Code Index MCP for file discovery (optional, for better precision)
+# Example: mcp__code-index__find_files(pattern="src/**/")
+# This finds directories without loading content
+
+# IMPORTANT: Do NOT read file contents in planning phase
+# Only collect: paths, file counts, module structure
+```
+
+#### Phase 3: Quick Documentation Assessment
+```bash
+# Lightweight check - no heavy analysis
+existing_docs=$(find . -maxdepth 2 -name "*.md" -not -path "./.workflow/*" | wc -l)
+
+if [[ $existing_docs -gt 5 ]]; then
+    find . -maxdepth 3 -name "*.md" > "${session_dir}/.process/existing-docs.txt"
+fi
+
+# Record strategy
+cat > "${session_dir}/.process/strategy.md" <<EOF
+**Type**: ${doc_type}
+**Tool**: ${tool}
+**Scope**: ${scope:-"Full project"}
+EOF
+```
+
+#### Phase 4: Task Decomposition & TodoWrite Setup
+
+**Decomposition Strategy**:
+1. **Always create**: System Overview task (IMPL-001)
+2. **If architecture/all**: Architecture Documentation task
+3. **If api/all**: Unified API Documentation task
+4. **For each module**: Module Documentation task (grouped)
+
+**Grouping Rules**:
+- Max 3 modules per task
+- Max 30 files per task
+- Group by dependency depth and functional similarity
+
+**TodoWrite Setup**:
+```
+✅ Session initialization (completed)
+⏳ IMPL-001: Project Overview (pending)
+⏳ IMPL-002: Module 'auth' (pending)
+⏳ IMPL-003: Module 'api' (pending)
+⏳ IMPL-004: Architecture Documentation (pending)
+⏳ IMPL-005: API Documentation (pending)
+```
+
+#### Phase 5: Task JSON Generation
+
+Each task follows the 5-field schema with detailed flow_control.
+
+**Command Generation Logic**:
+```bash
+# Build tool-specific command at planning time
+if [[ "$tool" == "codex" ]]; then
+    cmd="codex -C ${dir} --full-auto exec \"...\""
+else
+    cmd="bash(cd ${dir} && ~/.claude/scripts/${tool}-wrapper -p \"...\")"
+fi
+```
+
+## Task Templates
+
+### 1. System Overview (IMPL-001)
+**Purpose**: Project-level documentation
+**Output**: `.workflow/docs/README.md`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-001",
+  "title": "Generate Project Overview Documentation",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "template": "project-overview"
+  },
+  "context": {
+    "requirements": [
+      "Document project purpose, architecture, and getting started guide",
+      "Create navigation structure for all documentation",
+      "Use Project-Level Documentation Template"
+    ],
+    "focus_paths": ["."],
+    "acceptance": [
+      "Complete .workflow/docs/README.md following template",
+      "All template sections populated with accurate information",
+      "Navigation links to module and API documentation"
+    ],
+    "scope": "Project root and overall structure"
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "discover_project_structure",
+        "action": "Get project module hierarchy metadata",
+        "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
+        "output_to": "system_structure",
+        "on_error": "fail",
+        "note": "Lightweight metadata only - no file content"
+      },
+      {
+        "step": "analyze_tech_stack",
+        "action": "Analyze technology stack from key config files",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze project technology stack\\nTASK: Extract tech stack from key config files\\nMODE: analysis\\nCONTEXT: @{package.json,pom.xml,build.gradle,requirements.txt,go.mod,Cargo.toml,CLAUDE.md}\\nEXPECTED: Technology list and architecture style\\nRULES: Be concise, focus on stack only\")",
+        "output_to": "tech_stack_analysis",
+        "on_error": "skip_optional",
+        "note": "Only analyze config files - small, controlled context"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Use system_structure and tech_stack_analysis to populate Project Overview Template",
+      "logic_flow": [
+        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt",
+        "Fill sections using [system_structure] and [tech_stack_analysis]",
+        "Generate navigation links based on module paths",
+        "Format output as Markdown"
+      ]
+    },
+    "target_files": [".workflow/docs/README.md"]
+  }
+}
+```
+
+### 2. Module Documentation (IMPL-002+)
+**Purpose**: Module-level documentation
+**Output**: `.workflow/docs/modules/[name]/README.md`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-002",
+  "title": "Document Module: 'auth'",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "template": "module-documentation"
+  },
+  "context": {
+    "requirements": [
+      "Document module purpose, internal architecture, public API",
+      "Include dependencies and usage examples",
+      "Use Module-Level Documentation Template"
+    ],
+    "focus_paths": ["src/auth"],
+    "acceptance": [
+      "Complete .workflow/docs/modules/auth/README.md",
+      "All exported functions/classes documented",
+      "Working code examples included"
+    ],
+    "scope": "auth module only"
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "analyze_module_content",
+        "action": "Perform deep analysis of the specific module's content",
+        "command": "bash(cd src/auth && ~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document 'auth' module comprehensively\\nTASK: Extract module purpose, architecture, public API, dependencies\\nMODE: analysis\\nCONTEXT: @{**/*}\\nEXPECTED: Structured analysis of module content\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt)\")",
+        "output_to": "module_analysis",
+        "on_error": "fail",
+        "note": "Analysis strictly limited to focus_paths ('src/auth') - controlled context"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Use the detailed [module_analysis] to populate the Module-Level Documentation Template",
+      "logic_flow": [
+        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt",
+        "Fill sections using [module_analysis]",
+        "Generate code examples from actual usage",
+        "Format output as Markdown"
+      ]
+    },
+    "target_files": [".workflow/docs/modules/auth/README.md"]
+  }
+}
+```
+
+### 3. Architecture Documentation (if requested)
+**Purpose**: System design and patterns
+**Output**: `.workflow/docs/architecture/`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-N-1",
+  "title": "Generate Architecture Documentation",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "qwen",
+    "template": "architecture"
+  },
+  "context": {
+    "requirements": [
+      "Document system design patterns and architectural decisions",
+      "Create module interaction diagrams",
+      "Explain data flow and component relationships"
+    ],
+    "focus_paths": ["."],
+    "acceptance": [
+      "Complete architecture documentation in .workflow/docs/architecture/",
+      "Diagrams explaining system design",
+      "Clear explanation of architectural patterns"
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_all_module_docs",
+        "action": "Aggregate all module documentation",
+        "command": "bash(find .workflow/docs/modules -name 'README.md' -exec cat {} \\;)",
+        "output_to": "module_docs",
+        "on_error": "fail"
+      },
+      {
+        "step": "analyze_architecture",
+        "action": "Synthesize system architecture from modules",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Synthesize system architecture\\nTASK: Create architecture documentation from module docs\\nMODE: analysis\\nCONTEXT: [module_docs]\\nEXPECTED: Architecture documentation with patterns\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/project-overview.txt) | Focus on design patterns, data flow, component interactions\")",
+        "output_to": "architecture_analysis",
+        "on_error": "fail",
+        "note": "Command varies: gemini-wrapper (default) | qwen-wrapper | codex exec"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Create architecture documentation from synthesis",
+      "logic_flow": [
+        "Parse architecture_analysis for patterns and design decisions",
+        "Create text-based diagrams (mermaid/ASCII) for module interactions",
+        "Document data flow between components",
+        "Explain architectural decisions and trade-offs",
+        "Format as structured documentation"
+      ]
+    },
+    "target_files": [
+      ".workflow/docs/architecture/system-design.md",
+      ".workflow/docs/architecture/module-map.md",
+      ".workflow/docs/architecture/data-flow.md"
+    ]
+  }
+}
+```
+
+### 4. API Documentation (if requested)
+**Purpose**: API reference and specifications
+**Output**: `.workflow/docs/api/README.md`
+
+**Complete JSON Structure**:
+```json
+{
+  "id": "IMPL-N",
+  "title": "Generate Unified API Documentation",
+  "status": "pending",
+  "meta": {
+    "type": "docs",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "template": "api-reference"
+  },
+  "context": {
+    "requirements": [
+      "Document all API endpoints with request/response formats",
+      "Include authentication and error handling",
+      "Generate OpenAPI specification if applicable",
+      "Use API-Level Documentation Template"
+    ],
+    "focus_paths": ["src/api", "src/routes", "src/controllers"],
+    "acceptance": [
+      "Complete .workflow/docs/api/README.md following template",
+      "All endpoints documented with examples",
+      "OpenAPI spec generated if REST API detected"
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "discover_api_endpoints",
+        "action": "Find all API routes and endpoints using MCP",
+        "command": "mcp__code-index__search_code_advanced(pattern='router\\.|app\\.|@(Get|Post|Put|Delete|Patch)', file_pattern='*.{ts,js}', output_mode='content', head_limit=100)",
+        "output_to": "endpoint_discovery",
+        "on_error": "skip_optional",
+        "note": "Use MCP instead of rg for better structure"
+      },
+      {
+        "step": "analyze_api_structure",
+        "action": "Analyze API structure and patterns",
+        "command": "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Document API comprehensively\\nTASK: Extract endpoints, auth, request/response formats\\nMODE: analysis\\nCONTEXT: @{src/api/**/*,src/routes/**/*,src/controllers/**/*}\\nEXPECTED: Complete API documentation\\nRULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt)\")",
+        "output_to": "api_analysis",
+        "on_error": "fail",
+        "note": "Analysis limited to API-related paths - controlled context"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Use api_analysis to populate API-Level Documentation Template",
+      "logic_flow": [
+        "Load template: ~/.claude/workflows/cli-templates/prompts/documentation/api-reference.txt",
+        "Parse api_analysis for: endpoints, auth, request/response",
+        "Fill template sections with extracted information",
+        "Generate OpenAPI spec if REST API detected",
+        "Format output as Markdown"
+      ]
+    },
+    "target_files": [
+      ".workflow/docs/api/README.md",
+      ".workflow/docs/api/openapi.yaml"
+    ]
+  }
+}
+```
+
+## Planning Outputs
+
+### File Structure
+```
+.workflow/
+├── .active-WFS-docs-20240120-143022
+└── WFS-docs-20240120-143022/
+    ├── IMPL_PLAN.md              # Implementation plan
+    ├── TODO_LIST.md              # Progress tracker
+    ├── .process/
+    │   ├── strategy.md           # Doc strategy
+    │   └── existing-docs.txt     # Existing docs list
+    └── .task/
+        ├── IMPL-001.json         # System overview
+        ├── IMPL-002.json         # Module: auth
+        ├── IMPL-003.json         # Module: api
+        ├── IMPL-004.json         # Architecture
+        └── IMPL-005.json         # API docs
+```
+
+### IMPL_PLAN.md
+```markdown
+# Documentation Implementation Plan
+
+**Session**: WFS-docs-[timestamp]
+**Type**: [architecture|api|all]
+**Tool**: [gemini|qwen|codex]
+
+## Task Breakdown
+
+### IMPL-001: System Overview
+- **Output**: .workflow/docs/README.md
+- **Template**: project-overview.txt
+
+### IMPL-002+: Module Documentation
+- **Modules**: [list]
+- **Template**: module-documentation.txt
+
+### IMPL-N: Architecture/API (if requested)
+- **Template**: architecture.txt / api-reference.txt
+
+## Execution Order
+1. IMPL-001 (Foundation)
+2. IMPL-002 to IMPL-[M] (Modules - can parallelize)
+3. IMPL-[M+1] (Architecture - needs modules)
+4. IMPL-[N] (API - can run after IMPL-001)
+```
+
+### TODO_LIST.md
+```markdown
+# Documentation Progress Tracker
+
+- [ ] **IMPL-001**: Generate Project Overview
+- [ ] **IMPL-002**: Document Module: 'auth'
+- [ ] **IMPL-003**: Document Module: 'api'
+- [ ] **IMPL-004**: Generate Architecture Documentation
+- [ ] **IMPL-005**: Generate Unified API Documentation
+
+## Execution
+```bash
+/workflow:execute IMPL-001
+/workflow:execute IMPL-002
+# ...
+```
+```
+
+## Execution Phase
+
+### Via /workflow:execute
+
+```
+For Each Task (IMPL-001, IMPL-002, ...):
+
+/workflow:execute IMPL-NNN
+    ↓
+TodoWrite: pending → in_progress
+    ↓
+Execute flow_control (pre_analysis steps)
+    ↓
+Generate Documentation (apply template)
+    ↓
+TodoWrite: in_progress → completed
+    ↓
+✅ Task Complete
+```
+
+### TodoWrite Status Tracking
+
+**Planning Phase**:
+```
+✅ Session initialization (completed)
+⏳ IMPL-001: Project Overview (pending)
+⏳ IMPL-002: Module 'auth' (pending)
+```
+
+**Execution Phase**:
+```
+Executing IMPL-001:
+✅ Session initialization
+🔄 IMPL-001: Project Overview (in_progress)
+⏳ IMPL-002: Module 'auth'
+
+After IMPL-001:
+✅ Session initialization
+✅ IMPL-001: Project Overview (completed)
+🔄 IMPL-002: Module 'auth' (in_progress)
+```
+
+## Documentation Output
+
+### Final Structure
 ```
 .workflow/docs/
-├── README.md              # System navigation
-├── modules/               # Level 1: Module documentation
-│   ├── [module-1]/
-│   │   ├── overview.md
-│   │   ├── api.md
-│   │   ├── dependencies.md
-│   │   └── examples.md
-│   └── [module-n]/...
-├── architecture/          # Level 2: System architecture
+├── README.md                     # IMPL-001: Project overview
+├── modules/
+│   ├── auth/README.md           # IMPL-002: Auth module
+│   └── api/README.md            # IMPL-003: API module
+├── architecture/                # IMPL-004: Architecture
 │   ├── system-design.md
 │   ├── module-map.md
-│   ├── data-flow.md
-│   └── tech-stack.md
-└── api/                   # Level 2: Unified API docs
-    ├── unified-api.md
+│   └── data-flow.md
+└── api/                         # IMPL-005: API docs
+    ├── README.md
     └── openapi.yaml
 ```
 
-## Task Decomposition Standards
+## Next Steps
 
-### Dynamic Task Planning Rules
-**Module Grouping**: Max 3 modules per task, max 30 files per task
-**Task Count**: Calculate based on `total_modules ÷ 3 (rounded up) + base_tasks`
-**File Limits**: Split tasks when file count exceeds 30 in any module group
-**Base Tasks**: System overview (1) + Architecture (1) + API consolidation (1)
-**Module Tasks**: Group related modules by dependency depth and functional similarity
-
-### Documentation Task Types
-**IMPL-001**: System Overview Documentation
-- Project structure analysis
-- Technology stack documentation
-- Main navigation creation
-
-**IMPL-002**: Module Documentation (per module)
-- Individual module analysis
-- API surface documentation
-- Dependencies and relationships
-- Usage examples
-
-**IMPL-003**: Architecture Documentation
-- System design patterns
-- Module interaction mapping
-- Data flow documentation
-- Design principles
-
-**IMPL-004**: API Documentation
-- Endpoint discovery and analysis
-- OpenAPI specification generation
-- Authentication documentation
-- Integration examples
-
-### Task JSON Schema (5-Field Architecture)
-Each documentation task uses the workflow-architecture.md 5-field schema:
-- **id**: IMPL-N format
-- **title**: Documentation task name
-- **status**: pending|active|completed|blocked
-- **meta**: { type: "documentation", agent: "@doc-generator" }
-- **context**: { requirements, focus_paths, acceptance, scope }
-- **flow_control**: { pre_analysis[], implementation_approach, target_files[] }
-
-## Document Generation
-
-### Workflow Process
-**Input Analysis** → **Session Creation** → **IMPL_PLAN.md** → **.task/IMPL-NNN.json** → **TODO_LIST.md** → **Execute Tasks**
-
-**Always Created**:
-- **IMPL_PLAN.md**: Documentation requirements and task breakdown
-- **Session state**: Task references and documentation paths
-
-**Auto-Created (based on scope)**:
-- **TODO_LIST.md**: Progress tracking for documentation tasks
-- **.task/IMPL-*.json**: Individual documentation tasks with flow_control
-- **.process/ANALYSIS_RESULTS.md**: Documentation analysis artifacts
-
-**Document Structure**:
-```
-.workflow/
-├── .active-WFS-docs-20231201-143022  # Active session marker (matches folder name)
-└── WFS-docs-20231201-143022/         # Documentation session folder
-    ├── IMPL_PLAN.md                  # Main documentation plan
-    ├── TODO_LIST.md                  # Progress tracking
-    ├── .process/
-    │   └── ANALYSIS_RESULTS.md       # Documentation analysis
-    └── .task/
-        ├── IMPL-001.json             # System overview task
-        ├── IMPL-002.json             # Module documentation task
-        ├── IMPL-003.json             # Architecture documentation task
-        └── IMPL-004.json             # API documentation task
+### 1. Review Planning Output
+```bash
+cat .workflow/WFS-docs-*/IMPL_PLAN.md
+cat .workflow/WFS-docs-*/TODO_LIST.md
 ```
 
-### Task Flow Control Templates
+### 2. Execute Documentation Tasks
+```bash
+# Sequential (recommended)
+/workflow:execute IMPL-001  # System overview first
+/workflow:execute IMPL-002  # Module docs
+/workflow:execute IMPL-003
+/workflow:execute IMPL-004  # Architecture
+/workflow:execute IMPL-005  # API docs
 
-**System Overview Task (IMPL-001)**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "system_architecture_analysis",
-      "action": "Discover system architecture and module hierarchy",
-      "command": "bash(~/.claude/scripts/get_modules_by_depth.sh)",
-      "output_to": "system_structure"
-    },
-    {
-      "step": "project_discovery",
-      "action": "Discover project structure and entry points",
-      "command": "bash(find . -type f -name '*.json' -o -name '*.md' -o -name 'package.json' | head -20)",
-      "output_to": "project_structure"
-    },
-    {
-      "step": "analyze_tech_stack",
-      "action": "Analyze technology stack and dependencies using structure analysis",
-      "command": "~/.claude/scripts/gemini-wrapper -p \"Analyze project technology stack and dependencies based on: [system_structure]\"",
-      "output_to": "tech_analysis"
-    }
-  ],
-  "target_files": [".workflow/docs/README.md"]
-}
+# Parallel (module docs only)
+/workflow:execute IMPL-002 &
+/workflow:execute IMPL-003 &
+wait
 ```
 
-**Module Documentation Task (IMPL-002)**:
-```json
-"flow_control": {
-  "pre_analysis": [
-    {
-      "step": "load_system_structure",
-      "action": "Load system architecture analysis from previous task",
-      "command": "bash(cat .workflow/WFS-docs-*/IMPL-001-system_structure.output 2>/dev/null || ~/.claude/scripts/get_modules_by_depth.sh)",
-      "output_to": "system_context"
-    },
-    {
-      "step": "module_analysis",
-      "action": "Analyze specific module structure and API within system context",
-      "command": "~/.claude/scripts/gemini-wrapper -p \"Analyze module [MODULE_NAME] structure and exported API within system: [system_context]\"",
-      "output_to": "module_context"
-    }
-  ],
-  "target_files": [".workflow/docs/modules/[MODULE_NAME]/overview.md"]
-}
+### 3. Review Generated Documentation
+```bash
+ls -lah .workflow/docs/
+cat .workflow/docs/README.md
 ```
 
-## Analysis Templates
-
-### Project Structure Analysis Rules
-- Identify main modules and purposes
-- Map directory organization patterns
-- Extract entry points and configuration files
-- Recognize architectural styles and design patterns
-- Analyze module relationships and dependencies
-- Document technology stack and requirements
-
-### Module Analysis Rules
-- Identify module boundaries and entry points
-- Extract exported functions, classes, interfaces
-- Document internal organization and structure
-- Analyze API surfaces with types and parameters
-- Map dependencies within and between modules
-- Extract usage patterns and examples
-
-### API Analysis Rules
-- Classify endpoint types (REST, GraphQL, WebSocket, RPC)
-- Extract request/response parameters and schemas
-- Document authentication and authorization requirements
-- Generate OpenAPI 3.0 specification structure
-- Create comprehensive endpoint documentation
-- Provide usage examples and integration guides
+### 4. TodoWrite Progress
+- Planning: All tasks `pending`
+- Execution: `pending` → `in_progress` → `completed`
+- Real-time status updates via TodoWrite
 
 ## Error Handling
-- **Invalid document type**: Clear error message with valid options
-- **Module not found**: Skip missing modules with warning
-- **Analysis failures**: Fall back to file-based analysis
-- **Permission issues**: Clear guidance on directory access
+
+- **No modules found**: Create only IMPL-001 (system overview)
+- **Scope path invalid**: Show error and exit
+- **Active session exists**: Prompt to complete or pause
+- **Tool unavailable**: Fall back to gemini
 
 ## Key Benefits
 
-### Structured Documentation Process
-- **Task-based approach**: Documentation broken into manageable, trackable tasks
-- **Flow control integration**: Systematic analysis ensures completeness
-- **Progress visibility**: TODO_LIST.md provides clear completion status
-- **Quality assurance**: Each task has defined acceptance criteria
+### Clear Separation of Concerns
+- **Planning**: Session creation, task decomposition (this command)
+- **Execution**: Content generation, quality assurance (doc-generator agent)
 
-### Workflow Integration
-- **Planning foundation**: Documentation provides context for implementation planning
-- **Execution consistency**: Same task execution model as implementation
-- **Context accumulation**: Documentation builds comprehensive project understanding
+### Scalable Task Management
+- Independent, self-contained tasks
+- Parallelizable module documentation
+- Clear dependencies (architecture needs modules)
 
-## Usage Examples
+### Template-Driven Consistency
+- All documentation follows standard templates
+- Reusable and maintainable
+- Easy to update standards
 
-### Complete Documentation Workflow
-```bash
-# Step 1: Create documentation plan and tasks
-/workflow:docs all
-
-# Step 2: Execute documentation tasks (after planning)
-/workflow:execute IMPL-001  # System overview
-/workflow:execute IMPL-002  # Module documentation
-/workflow:execute IMPL-003  # Architecture documentation
-/workflow:execute IMPL-004  # API documentation
-```
-The system creates structured documentation tasks with proper session management, task.json files, and integration with the broader workflow system for systematic and trackable documentation generation.
+### Full Context for Execution
+- Each task JSON contains complete instructions
+- flow_control defines exact analysis steps
+- Tool selection for flexibility

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

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

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

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

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

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

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

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

.claude/version.json

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

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

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

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

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

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

@@ -0,0 +1,58 @@
+# Project-Level Documentation Template
+
+Generate comprehensive project documentation following this structure:
+
+## 1. Overview
+- **Purpose**: [High-level mission and goals of the project]
+- **Target Audience**: [Primary users, developers, stakeholders]
+- **Key Features**: [List of major functionalities and capabilities]
+
+## 2. System Architecture
+- **Architectural Style**: [e.g., Monolith, Microservices, Layered, Event-Driven]
+- **Core Components**: [Diagram or list of major system parts and their interactions]
+- **Technology Stack**:
+  - Languages: [Programming languages used]
+  - Frameworks: [Key frameworks and libraries]
+  - Databases: [Data storage solutions]
+  - Infrastructure: [Deployment and hosting]
+- **Design Principles**: [Guiding principles like SOLID, DRY, separation of concerns]
+
+## 3. Getting Started
+- **Prerequisites**: [Required software, tools, versions]
+- **Installation**:
+  ```bash
+  # Installation commands
+  ```
+- **Configuration**: [Environment setup, config files]
+- **Running the Project**:
+  ```bash
+  # Startup commands
+  ```
+
+## 4. Development Workflow
+- **Branching Strategy**: [e.g., GitFlow, trunk-based]
+- **Coding Standards**: [Style guide, linting rules]
+- **Testing**:
+  ```bash
+  # Test commands
+  ```
+- **Build & Deployment**: [CI/CD pipeline overview]
+
+## 5. Project Structure
+```
+project-root/
+├── src/           # [Description]
+├── tests/         # [Description]
+├── docs/          # [Description]
+└── config/        # [Description]
+```
+
+## 6. Navigation
+- [Module Documentation](./modules/)
+- [API Reference](./api/)
+- [Architecture Details](./architecture/)
+- [Contributing Guidelines](./CONTRIBUTING.md)
+
+---
+**Last Updated**: [Auto-generated timestamp]
+**Documentation Version**: [Project version]

.claude/workflows/design-tokens-schema.md

@@ -0,0 +1,534 @@
+---
+name: design-tokens-schema
+description: Design tokens JSON schema specification for UI design workflow
+type: specification
+---
+
+# Design Tokens Schema Specification
+
+## Overview
+Standardized JSON schema for design tokens used in `/workflow:design/*` commands. Ensures consistency across style extraction, consolidation, and UI generation phases.
+
+## Core Principles
+
+1. **OKLCH Color Format**: All colors use OKLCH color space for perceptual uniformity
+2. **Semantic Naming**: User-centric token names (brand-primary, surface-elevated, not color-1, bg-2)
+3. **rem-Based Sizing**: All spacing and typography use rem units for scalability
+4. **Comprehensive Coverage**: Complete token set for production-ready design systems
+5. **Accessibility First**: WCAG AA compliance validated and documented
+
+## Full Schema
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Design Tokens",
+  "description": "Design token definitions for UI design workflow",
+  "type": "object",
+  "required": ["colors", "typography", "spacing", "border_radius", "shadow"],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "properties": {
+        "version": {"type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$"},
+        "generated_at": {"type": "string", "format": "date-time"},
+        "session_id": {"type": "string", "pattern": "^WFS-"},
+        "description": {"type": "string"}
+      }
+    },
+    "colors": {
+      "type": "object",
+      "required": ["brand", "surface", "semantic", "text"],
+      "properties": {
+        "brand": {
+          "type": "object",
+          "description": "Brand identity colors",
+          "required": ["primary", "secondary"],
+          "properties": {
+            "primary": {"$ref": "#/definitions/color"},
+            "secondary": {"$ref": "#/definitions/color"},
+            "accent": {"$ref": "#/definitions/color"}
+          }
+        },
+        "surface": {
+          "type": "object",
+          "description": "Surface and background colors",
+          "required": ["background", "elevated"],
+          "properties": {
+            "background": {"$ref": "#/definitions/color"},
+            "elevated": {"$ref": "#/definitions/color"},
+            "sunken": {"$ref": "#/definitions/color"},
+            "overlay": {"$ref": "#/definitions/color"}
+          }
+        },
+        "semantic": {
+          "type": "object",
+          "description": "Semantic state colors",
+          "required": ["success", "warning", "error", "info"],
+          "properties": {
+            "success": {"$ref": "#/definitions/color"},
+            "warning": {"$ref": "#/definitions/color"},
+            "error": {"$ref": "#/definitions/color"},
+            "info": {"$ref": "#/definitions/color"}
+          }
+        },
+        "text": {
+          "type": "object",
+          "description": "Text colors with WCAG AA validated contrast",
+          "required": ["primary", "secondary"],
+          "properties": {
+            "primary": {"$ref": "#/definitions/color"},
+            "secondary": {"$ref": "#/definitions/color"},
+            "tertiary": {"$ref": "#/definitions/color"},
+            "inverse": {"$ref": "#/definitions/color"},
+            "disabled": {"$ref": "#/definitions/color"}
+          }
+        },
+        "border": {
+          "type": "object",
+          "description": "Border and divider colors",
+          "properties": {
+            "subtle": {"$ref": "#/definitions/color"},
+            "default": {"$ref": "#/definitions/color"},
+            "strong": {"$ref": "#/definitions/color"}
+          }
+        }
+      }
+    },
+    "typography": {
+      "type": "object",
+      "required": ["font_family", "font_size", "line_height", "font_weight"],
+      "properties": {
+        "font_family": {
+          "type": "object",
+          "required": ["heading", "body"],
+          "properties": {
+            "heading": {"type": "string"},
+            "body": {"type": "string"},
+            "mono": {"type": "string"}
+          }
+        },
+        "font_size": {
+          "type": "object",
+          "required": ["xs", "sm", "base", "lg", "xl", "2xl", "3xl", "4xl"],
+          "properties": {
+            "xs": {"$ref": "#/definitions/size_rem"},
+            "sm": {"$ref": "#/definitions/size_rem"},
+            "base": {"$ref": "#/definitions/size_rem"},
+            "lg": {"$ref": "#/definitions/size_rem"},
+            "xl": {"$ref": "#/definitions/size_rem"},
+            "2xl": {"$ref": "#/definitions/size_rem"},
+            "3xl": {"$ref": "#/definitions/size_rem"},
+            "4xl": {"$ref": "#/definitions/size_rem"},
+            "5xl": {"$ref": "#/definitions/size_rem"}
+          }
+        },
+        "line_height": {
+          "type": "object",
+          "required": ["tight", "normal", "relaxed"],
+          "properties": {
+            "tight": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"},
+            "normal": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"},
+            "relaxed": {"type": "string", "pattern": "^\\d+(\\.\\d+)?$"}
+          }
+        },
+        "font_weight": {
+          "type": "object",
+          "properties": {
+            "light": {"type": "integer", "enum": [300]},
+            "normal": {"type": "integer", "enum": [400]},
+            "medium": {"type": "integer", "enum": [500]},
+            "semibold": {"type": "integer", "enum": [600]},
+            "bold": {"type": "integer", "enum": [700]}
+          }
+        }
+      }
+    },
+    "spacing": {
+      "type": "object",
+      "description": "Spacing scale (rem-based)",
+      "required": ["0", "1", "2", "3", "4", "6", "8"],
+      "patternProperties": {
+        "^\\d+$": {"$ref": "#/definitions/size_rem"}
+      }
+    },
+    "border_radius": {
+      "type": "object",
+      "required": ["none", "sm", "md", "lg", "full"],
+      "properties": {
+        "none": {"type": "string", "const": "0"},
+        "sm": {"$ref": "#/definitions/size_rem"},
+        "md": {"$ref": "#/definitions/size_rem"},
+        "lg": {"$ref": "#/definitions/size_rem"},
+        "xl": {"$ref": "#/definitions/size_rem"},
+        "2xl": {"$ref": "#/definitions/size_rem"},
+        "full": {"type": "string", "const": "9999px"}
+      }
+    },
+    "shadow": {
+      "type": "object",
+      "required": ["sm", "md", "lg"],
+      "properties": {
+        "none": {"type": "string", "const": "none"},
+        "sm": {"type": "string"},
+        "md": {"type": "string"},
+        "lg": {"type": "string"},
+        "xl": {"type": "string"},
+        "2xl": {"type": "string"}
+      }
+    },
+    "breakpoint": {
+      "type": "object",
+      "description": "Responsive breakpoints",
+      "properties": {
+        "sm": {"type": "string", "pattern": "^\\d+px$"},
+        "md": {"type": "string", "pattern": "^\\d+px$"},
+        "lg": {"type": "string", "pattern": "^\\d+px$"},
+        "xl": {"type": "string", "pattern": "^\\d+px$"},
+        "2xl": {"type": "string", "pattern": "^\\d+px$"}
+      }
+    },
+    "accessibility": {
+      "type": "object",
+      "description": "WCAG AA compliance data",
+      "properties": {
+        "contrast_ratios": {
+          "type": "object",
+          "patternProperties": {
+            ".*": {
+              "type": "object",
+              "properties": {
+                "background": {"type": "string"},
+                "foreground": {"type": "string"},
+                "ratio": {"type": "number"},
+                "wcag_aa_pass": {"type": "boolean"},
+                "wcag_aaa_pass": {"type": "boolean"}
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "color": {
+      "type": "string",
+      "pattern": "^oklch\\(\\s*\\d+(\\.\\d+)?\\s+\\d+(\\.\\d+)?\\s+\\d+(\\.\\d+)?\\s*(\\/\\s*\\d+(\\.\\d+)?)?\\s*\\)$",
+      "description": "OKLCH color format: oklch(L C H / A)"
+    },
+    "size_rem": {
+      "type": "string",
+      "pattern": "^\\d+(\\.\\d+)?rem$",
+      "description": "rem-based size value"
+    }
+  }
+}
+```
+
+## Example: Complete Design Tokens
+
+```json
+{
+  "meta": {
+    "version": "1.0.0",
+    "generated_at": "2025-10-05T15:30:00Z",
+    "session_id": "WFS-auth-dashboard",
+    "description": "Modern minimalist design system with high contrast"
+  },
+  "colors": {
+    "brand": {
+      "primary": "oklch(0.45 0.20 270 / 1)",
+      "secondary": "oklch(0.60 0.15 200 / 1)",
+      "accent": "oklch(0.65 0.18 30 / 1)"
+    },
+    "surface": {
+      "background": "oklch(0.98 0.01 270 / 1)",
+      "elevated": "oklch(1.00 0.00 0 / 1)",
+      "sunken": "oklch(0.95 0.02 270 / 1)",
+      "overlay": "oklch(0.00 0.00 0 / 0.5)"
+    },
+    "semantic": {
+      "success": "oklch(0.55 0.15 150 / 1)",
+      "warning": "oklch(0.70 0.18 60 / 1)",
+      "error": "oklch(0.50 0.20 20 / 1)",
+      "info": "oklch(0.60 0.15 240 / 1)"
+    },
+    "text": {
+      "primary": "oklch(0.20 0.02 270 / 1)",
+      "secondary": "oklch(0.45 0.02 270 / 1)",
+      "tertiary": "oklch(0.60 0.02 270 / 1)",
+      "inverse": "oklch(0.98 0.01 270 / 1)",
+      "disabled": "oklch(0.70 0.01 270 / 0.5)"
+    },
+    "border": {
+      "subtle": "oklch(0.90 0.01 270 / 1)",
+      "default": "oklch(0.80 0.02 270 / 1)",
+      "strong": "oklch(0.60 0.05 270 / 1)"
+    }
+  },
+  "typography": {
+    "font_family": {
+      "heading": "Inter, system-ui, -apple-system, sans-serif",
+      "body": "Inter, system-ui, -apple-system, sans-serif",
+      "mono": "Fira Code, Consolas, monospace"
+    },
+    "font_size": {
+      "xs": "0.75rem",
+      "sm": "0.875rem",
+      "base": "1rem",
+      "lg": "1.125rem",
+      "xl": "1.25rem",
+      "2xl": "1.5rem",
+      "3xl": "1.875rem",
+      "4xl": "2.25rem",
+      "5xl": "3rem"
+    },
+    "line_height": {
+      "tight": "1.25",
+      "normal": "1.5",
+      "relaxed": "1.75"
+    },
+    "font_weight": {
+      "light": 300,
+      "normal": 400,
+      "medium": 500,
+      "semibold": 600,
+      "bold": 700
+    }
+  },
+  "spacing": {
+    "0": "0",
+    "1": "0.25rem",
+    "2": "0.5rem",
+    "3": "0.75rem",
+    "4": "1rem",
+    "5": "1.25rem",
+    "6": "1.5rem",
+    "8": "2rem",
+    "10": "2.5rem",
+    "12": "3rem",
+    "16": "4rem",
+    "20": "5rem",
+    "24": "6rem"
+  },
+  "border_radius": {
+    "none": "0",
+    "sm": "0.25rem",
+    "md": "0.5rem",
+    "lg": "0.75rem",
+    "xl": "1rem",
+    "2xl": "1.5rem",
+    "full": "9999px"
+  },
+  "shadow": {
+    "none": "none",
+    "sm": "0 1px 2px oklch(0.00 0.00 0 / 0.05)",
+    "md": "0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)",
+    "lg": "0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)",
+    "xl": "0 20px 25px oklch(0.00 0.00 0 / 0.15), 0 10px 10px oklch(0.00 0.00 0 / 0.04)",
+    "2xl": "0 25px 50px oklch(0.00 0.00 0 / 0.25)"
+  },
+  "breakpoint": {
+    "sm": "640px",
+    "md": "768px",
+    "lg": "1024px",
+    "xl": "1280px",
+    "2xl": "1536px"
+  },
+  "accessibility": {
+    "contrast_ratios": {
+      "text_primary_on_background": {
+        "background": "oklch(0.98 0.01 270 / 1)",
+        "foreground": "oklch(0.20 0.02 270 / 1)",
+        "ratio": 14.2,
+        "wcag_aa_pass": true,
+        "wcag_aaa_pass": true
+      },
+      "brand_primary_on_background": {
+        "background": "oklch(0.98 0.01 270 / 1)",
+        "foreground": "oklch(0.45 0.20 270 / 1)",
+        "ratio": 6.8,
+        "wcag_aa_pass": true,
+        "wcag_aaa_pass": false
+      }
+    }
+  }
+}
+```
+
+## CSS Custom Properties Generation
+
+Design tokens should be converted to CSS custom properties for use in generated UI:
+
+```css
+:root {
+  /* Brand Colors */
+  --color-brand-primary: oklch(0.45 0.20 270 / 1);
+  --color-brand-secondary: oklch(0.60 0.15 200 / 1);
+  --color-brand-accent: oklch(0.65 0.18 30 / 1);
+
+  /* Surface Colors */
+  --color-surface-background: oklch(0.98 0.01 270 / 1);
+  --color-surface-elevated: oklch(1.00 0.00 0 / 1);
+  --color-surface-sunken: oklch(0.95 0.02 270 / 1);
+
+  /* Semantic Colors */
+  --color-semantic-success: oklch(0.55 0.15 150 / 1);
+  --color-semantic-warning: oklch(0.70 0.18 60 / 1);
+  --color-semantic-error: oklch(0.50 0.20 20 / 1);
+  --color-semantic-info: oklch(0.60 0.15 240 / 1);
+
+  /* Text Colors */
+  --color-text-primary: oklch(0.20 0.02 270 / 1);
+  --color-text-secondary: oklch(0.45 0.02 270 / 1);
+  --color-text-tertiary: oklch(0.60 0.02 270 / 1);
+
+  /* Typography */
+  --font-family-heading: Inter, system-ui, sans-serif;
+  --font-family-body: Inter, system-ui, sans-serif;
+  --font-family-mono: Fira Code, Consolas, monospace;
+
+  --font-size-xs: 0.75rem;
+  --font-size-sm: 0.875rem;
+  --font-size-base: 1rem;
+  --font-size-lg: 1.125rem;
+  --font-size-xl: 1.25rem;
+  --font-size-2xl: 1.5rem;
+  --font-size-3xl: 1.875rem;
+  --font-size-4xl: 2.25rem;
+
+  --line-height-tight: 1.25;
+  --line-height-normal: 1.5;
+  --line-height-relaxed: 1.75;
+
+  /* Spacing */
+  --spacing-0: 0;
+  --spacing-1: 0.25rem;
+  --spacing-2: 0.5rem;
+  --spacing-3: 0.75rem;
+  --spacing-4: 1rem;
+  --spacing-6: 1.5rem;
+  --spacing-8: 2rem;
+  --spacing-12: 3rem;
+  --spacing-16: 4rem;
+
+  /* Border Radius */
+  --border-radius-none: 0;
+  --border-radius-sm: 0.25rem;
+  --border-radius-md: 0.5rem;
+  --border-radius-lg: 0.75rem;
+  --border-radius-xl: 1rem;
+  --border-radius-full: 9999px;
+
+  /* Shadows */
+  --shadow-sm: 0 1px 2px oklch(0.00 0.00 0 / 0.05);
+  --shadow-md: 0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06);
+  --shadow-lg: 0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05);
+}
+```
+
+## Tailwind Configuration Generation
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: {
+          primary: 'oklch(0.45 0.20 270 / <alpha-value>)',
+          secondary: 'oklch(0.60 0.15 200 / <alpha-value>)',
+          accent: 'oklch(0.65 0.18 30 / <alpha-value>)'
+        },
+        surface: {
+          background: 'oklch(0.98 0.01 270 / <alpha-value>)',
+          elevated: 'oklch(1.00 0.00 0 / <alpha-value>)',
+          sunken: 'oklch(0.95 0.02 270 / <alpha-value>)'
+        },
+        semantic: {
+          success: 'oklch(0.55 0.15 150 / <alpha-value>)',
+          warning: 'oklch(0.70 0.18 60 / <alpha-value>)',
+          error: 'oklch(0.50 0.20 20 / <alpha-value>)',
+          info: 'oklch(0.60 0.15 240 / <alpha-value>)'
+        }
+      },
+      fontFamily: {
+        heading: ['Inter', 'system-ui', 'sans-serif'],
+        body: ['Inter', 'system-ui', 'sans-serif'],
+        mono: ['Fira Code', 'Consolas', 'monospace']
+      },
+      fontSize: {
+        'xs': '0.75rem',
+        'sm': '0.875rem',
+        'base': '1rem',
+        'lg': '1.125rem',
+        'xl': '1.25rem',
+        '2xl': '1.5rem',
+        '3xl': '1.875rem',
+        '4xl': '2.25rem'
+      },
+      spacing: {
+        '1': '0.25rem',
+        '2': '0.5rem',
+        '3': '0.75rem',
+        '4': '1rem',
+        '6': '1.5rem',
+        '8': '2rem',
+        '12': '3rem',
+        '16': '4rem'
+      },
+      borderRadius: {
+        'sm': '0.25rem',
+        'md': '0.5rem',
+        'lg': '0.75rem',
+        'xl': '1rem',
+        '2xl': '1.5rem'
+      },
+      boxShadow: {
+        'sm': '0 1px 2px oklch(0.00 0.00 0 / 0.05)',
+        'md': '0 4px 6px oklch(0.00 0.00 0 / 0.07), 0 2px 4px oklch(0.00 0.00 0 / 0.06)',
+        'lg': '0 10px 15px oklch(0.00 0.00 0 / 0.1), 0 4px 6px oklch(0.00 0.00 0 / 0.05)'
+      }
+    }
+  }
+}
+```
+
+## Validation Requirements
+
+### Color Validation
+- All colors MUST use OKLCH format
+- Alpha channel optional (defaults to 1)
+- Lightness: 0-1 (0% to 100%)
+- Chroma: 0-0.4 (typical range, can exceed for vibrant colors)
+- Hue: 0-360 (degrees)
+
+### Accessibility Validation
+- Text on background: minimum 4.5:1 contrast (WCAG AA)
+- Large text (18pt+ or 14pt+ bold): minimum 3:1 contrast
+- UI components: minimum 3:1 contrast
+- Non-text focus indicators: minimum 3:1 contrast
+
+### Consistency Validation
+- Spacing scale maintains consistent ratio (e.g., 1.5x or 2x progression)
+- Typography scale follows modular scale principles
+- Border radius values progress logically
+- Shadow layers increase in offset and blur systematically
+
+## Usage in Commands
+
+### style-extract Output
+Generates initial `design-tokens.json` from visual analysis
+
+### style-consolidate Output
+Finalizes validated `design-tokens.json` with accessibility data
+
+### ui-generate Input
+Reads `design-tokens.json` to generate CSS custom properties
+
+### design-update Integration
+References `design-tokens.json` path in synthesis-specification.md
+
+## Version History
+
+- **1.0.0**: Initial schema with OKLCH colors, semantic naming, WCAG AA validation

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

@@ -6,11 +6,22 @@ type: strategic-guideline
 
 # Intelligent Tools Selection Strategy
 
+## 📋 Table of Contents
+1. [Core Framework](#-core-framework)
+2. [Tool Specifications](#-tool-specifications)
+3. [Command Templates](#-command-templates)
+4. [Tool Selection Guide](#-tool-selection-guide)
+5. [Usage Patterns](#-usage-patterns)
+6. [Best Practices](#-best-practices)
+
+---
+
 ## ⚡ Core Framework
 
-**Gemini**: Analysis, understanding, exploration & documentation
-**Qwen**: Architecture analysis, code generation & implementation
-**Codex**: Development, implementation & automation
+### Tool Overview
+- **Gemini**: Analysis, understanding, exploration & documentation
+- **Qwen**: Architecture analysis, code generation & implementation
+- **Codex**: Development, implementation & automation
 
 ### Decision Principles
 - **Use tools early and often** - Tools are faster, more thorough, and reliable than manual approaches
@@ -27,40 +38,118 @@ type: strategic-guideline
 4. **Not sure?** → Use multiple tools in parallel
 5. **Small task?** → Still use tools - they're faster than manual work
 
-### Core Execution Rules
-- **Dynamic Timeout (20-120min)**: Allocate execution time based on task complexity
-  - Simple tasks (analysis, search): 20-40min (1200000-2400000ms)
-  - Medium tasks (refactoring, documentation): 40-60min (2400000-3600000ms)
-  - Complex tasks (implementation, migration): 60-120min (3600000-7200000ms)
-- **Codex Multiplier**: Codex commands use 1.5x of allocated time
-- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions
-- **Command Examples**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
-- **Auto-detect**: Analyze PURPOSE and TASK fields to determine appropriate timeout
+---
 
-### Permission Framework
-- **⚠️ WRITE PROTECTION**: Local codebase write/modify requires EXPLICIT user confirmation
-  - **Analysis Mode (default)**: Read-only, safe for auto-execution
-  - **Write Mode**: Requires user explicitly states MODE=write or MODE=auto in prompt
-  - **Exception**: User provides clear instructions like "modify", "create", "implement"
-- **Gemini/Qwen Write Access**: Use `--approval-mode yolo` ONLY when MODE=write explicitly specified
-- **Codex Write Access**: Use `-s danger-full-access` and `--skip-git-repo-check` ONLY when MODE=auto explicitly specified
-- **Default Behavior**: All tools default to analysis/read-only mode without explicit write permission
+## 🎯 Tool Specifications
 
-## 🎯 Universal Command Template
+### Gemini
+- **Command**: `~/.claude/scripts/gemini-wrapper`
+- **Strengths**: Large context window, pattern recognition
+- **Best For**: Analysis, documentation generation, code exploration
+- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
+- **Default MODE**: `analysis` (read-only)
+- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
 
-### Standard Format (REQUIRED)
+#### MODE Options
+- `analysis` (default) - Read-only analysis and documentation generation
+- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
+
+### Qwen
+- **Command**: `~/.claude/scripts/qwen-wrapper`
+- **Strengths**: Architecture analysis, pattern recognition
+- **Best For**: System design analysis, architectural review
+- **Permissions**: Architecture analysis only, no automatic code generation
+- **Default MODE**: `analysis` (read-only)
+- **⚠️ Write Trigger**: Explicitly prohibited from auto-calling write mode
+
+#### MODE Options
+- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
+- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
+
+### Codex
+- **Command**: `codex --full-auto exec`
+- **Strengths**: Autonomous development, mathematical reasoning
+- **Best For**: Implementation, testing, automation
+- **Permissions**: Requires explicit MODE=auto or MODE=write specification
+- **Default MODE**: No default, must be explicitly specified
+- **⚠️ Write Trigger**: Only when user explicitly requests "implement", "modify", "generate code" AND specifies MODE
+
+#### MODE Options
+- `auto` - ⚠️ Autonomous development with full file operations (requires explicit specification, enables -s danger-full-access)
+- `write` - ⚠️ Test generation and file modification (requires explicit specification)
+- **Default**: No default mode, MODE must be explicitly specified
+
+#### Session Management
+- `codex resume` - Resume previous interactive session (picker by default)
+- `codex exec "task" resume --last` - Continue most recent session with new task (maintains context)
+- `codex -i <image_file>` - Attach image(s) to initial prompt (useful for UI/design references)
+- **Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
+  - **Parameter Position**: `resume --last` must be placed AFTER the prompt string at command END
+  - **Example**:
+    ```bash
+    # First task - establish session
+    codex -C project --full-auto exec "Implement auth module" --skip-git-repo-check -s danger-full-access
+
+    # Subsequent tasks - continue same session
+    codex --full-auto exec "Add JWT validation" resume --last --skip-git-repo-check -s danger-full-access
+    codex --full-auto exec "Write auth tests" resume --last --skip-git-repo-check -s danger-full-access
+    ```
+
+#### Auto-Resume Decision Rules
+**When to use `resume --last`**:
+- Current task is related to/extends previous Codex task in conversation memory
+- Current task requires context from previous implementation
+- Current task is part of multi-step workflow (e.g., implement → enhance → test)
+- Session memory indicates recent Codex execution on same module/feature
+
+**When NOT to use `resume --last`**:
+- First Codex task in conversation
+- New independent task unrelated to previous work
+- Switching to different module/feature area
+- No recent Codex task in conversation memory
+
+---
+
+## 🎯 Command Templates
+
+### Universal Template Structure
+Every command MUST follow this structure:
+- [ ] **PURPOSE** - Clear goal and intent
+- [ ] **TASK** - Specific execution task
+- [ ] **MODE** - Execution mode and permission level
+- [ ] **CONTEXT** - File references and memory context from previous sessions
+- [ ] **EXPECTED** - Clear expected results
+- [ ] **RULES** - Template reference and constraints
+
+### Standard Command Formats
+
+#### Gemini Commands
 ```bash
-# Gemini Analysis (read/write capable)
+# Gemini Analysis (read-only, default)
 cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: [clear analysis goal]
 TASK: [specific analysis task]
-MODE: [analysis|write]
+MODE: analysis
 CONTEXT: [file references and memory context]
 EXPECTED: [expected output]
 RULES: [template reference and constraints]
 "
 
-# Qwen Architecture Analysis (read-only analysis)
+# Gemini Write Mode (requires explicit MODE=write)
+# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
+cd [directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+PURPOSE: [clear goal]
+TASK: [specific task]
+MODE: write
+CONTEXT: [file references and memory context]
+EXPECTED: [expected output]
+RULES: [template reference and constraints]
+"
+```
+
+#### Qwen Commands
+```bash
+# Qwen Architecture Analysis (read-only, default)
 cd [directory] && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: [clear architecture goal]
 TASK: [specific analysis task]
@@ -70,43 +159,44 @@ EXPECTED: [expected deliverables]
 RULES: [template reference and constraints]
 "
 
-# Codex Development
+# Qwen Write Mode (requires explicit MODE=write)
+# NOTE: --approval-mode yolo must be placed AFTER wrapper command, BEFORE -p
+cd [directory] && ~/.claude/scripts/qwen-wrapper --approval-mode yolo -p "
+PURPOSE: [clear goal]
+TASK: [specific task]
+MODE: write
+CONTEXT: [file references and memory context]
+EXPECTED: [expected deliverables]
+RULES: [template reference and constraints]
+"
+```
+
+#### Codex Commands
+```bash
+# Codex Development (requires explicit MODE=auto)
+# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
 codex -C [directory] --full-auto exec "
 PURPOSE: [clear development goal]
 TASK: [specific development task]
-MODE: [auto|write]
+MODE: auto
+CONTEXT: [file references and memory context]
+EXPECTED: [expected deliverables]
+RULES: [template reference and constraints]
+" --skip-git-repo-check -s danger-full-access
+
+# Codex Test/Write Mode (requires explicit MODE=write)
+# NOTE: --skip-git-repo-check and -s danger-full-access must be placed at command END
+codex -C [directory] --full-auto exec "
+PURPOSE: [clear goal]
+TASK: [specific task]
+MODE: write
 CONTEXT: [file references and memory context]
 EXPECTED: [expected deliverables]
 RULES: [template reference and constraints]
 " --skip-git-repo-check -s danger-full-access
 ```
 
-### Template Structure
-- [ ] **PURPOSE** - Clear goal and intent
-- [ ] **TASK** - Specific execution task
-- [ ] **MODE** - Execution mode and permission level
-- [ ] **CONTEXT** - File references and memory context from previous sessions
-- [ ] **EXPECTED** - Clear expected results
-- [ ] **RULES** - Template reference and constraints
-
-### MODE Field Definition
-
-The MODE field controls execution behavior and file permissions:
-
-**For Gemini**:
-- `analysis` (default) - Read-only analysis and documentation generation
-- `write` - ⚠️ Create/modify codebase files (requires explicit specification, auto-enables --approval-mode yolo)
-
-**For Qwen**:
-- `analysis` (default) - Architecture analysis only, no code generation/modification (read-only)
-- `write` - ⚠️ Code generation (requires explicit specification, disabled by default)
-
-**For Codex**:
-- `auto` - ⚠️ Autonomous development with full file operations (requires explicit specification, enables -s danger-full-access)
-- `write` - ⚠️ Test generation and file modification (requires explicit specification)
-- **Default**: No default mode, MODE must be explicitly specified
-
-### Directory Context
+### Directory Context Configuration
 Tools execute in current working directory:
 - **Gemini**: `cd path/to/project && ~/.claude/scripts/gemini-wrapper -p "prompt"`
 - **Qwen**: `cd path/to/project && ~/.claude/scripts/qwen-wrapper -p "prompt"`
@@ -114,7 +204,7 @@ Tools execute in current working directory:
 - **Path types**: Supports both relative (`../project`) and absolute (`/full/path`) paths
 - **Token analysis**: For gemini-wrapper and qwen-wrapper, token counting happens in current directory
 
-### Rules Field Format
+### RULES Field Format
 ```bash
 RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].txt") | [constraints]
 ```
@@ -125,7 +215,44 @@ RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].tx
 - No template: `Focus on security patterns, include dependency analysis`
 - File patterns: `@{src/**/*.ts,CLAUDE.md} - Stay within scope`
 
-## 📊 Tool Selection Matrix
+### File Pattern Reference
+- All files: `@{**/*}`
+- Source files: `@{src/**/*}`
+- TypeScript: `@{*.ts,*.tsx}`
+- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
+- Tests: `@{src/**/*.test.*}`
+
+**Complex Pattern Discovery**:
+For complex file pattern requirements, use semantic discovery tools BEFORE CLI execution:
+- **rg (ripgrep)**: Content-based file discovery with regex patterns
+- **Code Index MCP**: Semantic file search based on task requirements
+- **Workflow**: Discover → Extract precise paths → Build CONTEXT field
+
+**Example**:
+```bash
+# Step 1: Discover files semantically
+rg "export.*Component" --files-with-matches --type ts  # Find component files
+mcp__code-index__search_code_advanced(pattern="interface.*Props", file_pattern="*.tsx")  # Find interface files
+
+# Step 2: Build precise CONTEXT from discovery results
+CONTEXT: @{src/components/Auth.tsx,src/types/auth.d.ts,src/hooks/useAuth.ts}
+
+# Step 3: Execute CLI with precise file references
+cd src && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: Analyze authentication components
+TASK: Review auth component patterns and props interfaces
+MODE: analysis
+CONTEXT: @{components/Auth.tsx,types/auth.d.ts,hooks/useAuth.ts}
+EXPECTED: Pattern analysis and improvement suggestions
+RULES: Focus on type safety and component composition
+"
+```
+
+---
+
+## 📊 Tool Selection Guide
+
+### Selection Matrix
 
 | Task Type | Tool | Use Case | Template |
 |-----------|------|----------|-----------|
@@ -138,11 +265,11 @@ RULES: $(cat "~/.claude/workflows/cli-templates/prompts/[category]/[template].tx
 | **Security** | Codex | Vulnerability assessment, fixes | `analysis/security.txt` |
 | **Refactoring** | Multiple | Gemini for analysis, Qwen/Codex for execution | `development/refactor.txt` |
 
-## 📁 Template System
+### Template System
 
 **Base Structure**: `~/.claude/workflows/cli-templates/`
 
-### Available Templates
+#### Available Templates
 ```
 prompts/
 ├── analysis/
@@ -168,6 +295,8 @@ tech-stacks/
 └── react-dev.md         - React architecture
 ```
 
+---
+
 ## 🚀 Usage Patterns
 
 ### Workflow Integration (REQUIRED)
@@ -179,8 +308,9 @@ When planning any coding task, **ALWAYS** integrate CLI tools:
 4. **Quality Phase**: Use Codex for testing and validation
 
 ### Common Scenarios
+
+#### Code Analysis
 ```bash
-# Gemini - Code Analysis
 ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: Understand codebase architecture
 TASK: Analyze project structure and identify patterns
@@ -189,8 +319,10 @@ CONTEXT: @{src/**/*.ts,CLAUDE.md} Previous analysis of auth system
 EXPECTED: Architecture overview and integration points
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on integration points
 "
+```
 
-# Gemini - Generate Documentation
+#### Documentation Generation
+```bash
 ~/.claude/scripts/gemini-wrapper -p "
 PURPOSE: Generate API documentation
 TASK: Create comprehensive API reference from code
@@ -199,8 +331,10 @@ CONTEXT: @{src/api/**/*}
 EXPECTED: API.md with all endpoints documented
 RULES: Follow project documentation standards
 "
+```
 
-# Qwen - Architecture Analysis
+#### Architecture Analysis
+```bash
 cd src/auth && ~/.claude/scripts/qwen-wrapper -p "
 PURPOSE: Analyze authentication system architecture
 TASK: Review JWT-based auth system design
@@ -209,8 +343,11 @@ CONTEXT: @{src/auth/**/*} Existing patterns and requirements
 EXPECTED: Architecture analysis report with recommendations
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt') | Focus on security
 "
+```
 
-# Codex - Feature Development
+#### Feature Development (Multi-task with Resume)
+```bash
+# First task - establish session
 codex -C path/to/project --full-auto exec "
 PURPOSE: Implement user authentication
 TASK: Create JWT-based authentication system
@@ -220,74 +357,46 @@ EXPECTED: Complete auth module with tests
 RULES: $(cat '~/.claude/workflows/cli-templates/prompts/development/feature.txt') | Follow security best practices
 " --skip-git-repo-check -s danger-full-access
 
-# Codex - Test Generation
-codex -C src/auth --full-auto exec "
+# Continue in same session - Add JWT validation
+codex --full-auto exec "
+PURPOSE: Enhance authentication security
+TASK: Add JWT token validation and refresh logic
+MODE: auto
+CONTEXT: Previous auth implementation from current session
+EXPECTED: JWT validation middleware and token refresh endpoints
+RULES: Follow JWT best practices, maintain session context
+" resume --last --skip-git-repo-check -s danger-full-access
+
+# Continue in same session - Add tests
+codex --full-auto exec "
 PURPOSE: Increase test coverage
 TASK: Generate comprehensive tests for auth module
 MODE: write
-CONTEXT: @{**/*.ts} Exclude existing tests
+CONTEXT: Auth implementation from current session
 EXPECTED: Complete test suite with 80%+ coverage
 RULES: Use Jest, follow existing patterns
-" --skip-git-repo-check -s danger-full-access
+" resume --last --skip-git-repo-check -s danger-full-access
 ```
 
-## 📋 Planning Checklist
+#### Interactive Session Resume
+```bash
+# Resume previous session with picker
+codex resume
 
-For every development task:
-- [ ] **Purpose defined** - Clear goal and intent
-- [ ] **Mode selected** - Execution mode and permission level determined
-- [ ] **Context gathered** - File references and session memory documented
-- [ ] **Gemini analysis** completed for understanding
-- [ ] **Template selected** - Appropriate template chosen
-- [ ] **Constraints specified** - File patterns, scope, requirements
-- [ ] **Implementation approach** - Tool selection and workflow
-- [ ] **Quality measures** - Testing and validation plan
-- [ ] **Tool configuration** - Review `.gemini/CLAUDE.md` or `.codex/Agent.md` if needed
+# Or resume most recent session directly
+codex resume --last
+```
 
-## 🎯 Key Features
-
-### Gemini
-- **Command**: `~/.claude/scripts/gemini-wrapper`
-- **Strengths**: Large context window, pattern recognition
-- **Best For**: Analysis, documentation generation, code exploration
-- **Permissions**: Default read-only analysis, MODE=write requires explicit specification (auto-enables --approval-mode yolo)
-- **Default MODE**: `analysis` (read-only)
-- **⚠️ Write Trigger**: Only when user explicitly requests "generate documentation", "modify code", or specifies MODE=write
-
-### Qwen
-- **Command**: `~/.claude/scripts/qwen-wrapper`
-- **Strengths**: Architecture analysis, pattern recognition
-- **Best For**: System design analysis, architectural review
-- **Permissions**: Architecture analysis only, no automatic code generation
-- **Default MODE**: `analysis` (read-only)
-- **⚠️ Write Trigger**: Explicitly prohibited from auto-calling write mode
-
-### Codex
-- **Command**: `codex --full-auto exec`
-- **Strengths**: Autonomous development, mathematical reasoning
-- **Best For**: Implementation, testing, automation
-- **Permissions**: Requires explicit MODE=auto or MODE=write specification
-- **Default MODE**: No default, must be explicitly specified
-- **⚠️ Write Trigger**: Only when user explicitly requests "implement", "modify", "generate code" AND specifies MODE
-- **Session Management**:
-  - `codex resume` - Resume previous interactive session (picker by default)
-  - `codex exec "task" resume --last` - Continue most recent session with new task (maintains context)
-  - `codex -i <image_file>` - Attach image(s) to initial prompt (useful for UI/design references)
-  - **Multi-task Pattern**: First task uses `exec`, subsequent tasks use `exec "..." resume --last` for context continuity
-
-### File Patterns
-- All files: `@{**/*}`
-- Source files: `@{src/**/*}`
-- TypeScript: `@{*.ts,*.tsx}`
-- With docs: `@{CLAUDE.md,**/*CLAUDE.md}`
-- Tests: `@{src/**/*.test.*}`
+---
 
 ## 🔧 Best Practices
 
+### General Guidelines
 - **Start with templates** - Use predefined templates for consistency
 - **Be specific** - Clear PURPOSE, TASK, and EXPECTED fields
 - **Include constraints** - File patterns, scope, requirements in RULES
-- **Test patterns first** - Validate file patterns with `ls`
+- **Discover patterns first** - Use rg/MCP for complex file discovery before CLI execution
+- **Build precise CONTEXT** - Convert discovery results to explicit file references
 - **Document context** - Always reference CLAUDE.md for context
 
 ### Context Optimization Strategy
@@ -329,4 +438,42 @@ CONTEXT: @{**/*.ts}
 EXPECTED: Code improvements and fixes
 RULES: Maintain backward compatibility
 " --skip-git-repo-check -s danger-full-access
-```
+```
+
+### Planning Checklist
+
+For every development task:
+- [ ] **Purpose defined** - Clear goal and intent
+- [ ] **Mode selected** - Execution mode and permission level determined
+- [ ] **Context gathered** - File references and session memory documented
+- [ ] **Gemini analysis** completed for understanding
+- [ ] **Template selected** - Appropriate template chosen
+- [ ] **Constraints specified** - File patterns, scope, requirements
+- [ ] **Implementation approach** - Tool selection and workflow
+- [ ] **Quality measures** - Testing and validation plan
+- [ ] **Tool configuration** - Review `.gemini/CLAUDE.md` or `.codex/Agent.md` if needed
+
+---
+
+## ⚙️ Execution Configuration
+
+### Core Execution Rules
+- **Dynamic Timeout (20-120min)**: Allocate execution time based on task complexity
+  - Simple tasks (analysis, search): 20-40min (1200000-2400000ms)
+  - Medium tasks (refactoring, documentation): 40-60min (2400000-3600000ms)
+  - Complex tasks (implementation, migration): 60-120min (3600000-7200000ms)
+- **Codex Multiplier**: Codex commands use 1.5x of allocated time
+- **Apply to All Tools**: All bash() wrapped commands including Gemini, Qwen wrapper and Codex executions
+- **Command Examples**: `bash(~/.claude/scripts/gemini-wrapper -p "prompt")`, `bash(codex -C directory --full-auto exec "task")`
+- **Auto-detect**: Analyze PURPOSE and TASK fields to determine appropriate timeout
+
+### Permission Framework
+- **⚠️ WRITE PROTECTION**: Local codebase write/modify requires EXPLICIT user confirmation
+  - **Analysis Mode (default)**: Read-only, safe for auto-execution
+  - **Write Mode**: Requires user explicitly states MODE=write or MODE=auto in prompt
+  - **Exception**: User provides clear instructions like "modify", "create", "implement"
+- **Gemini/Qwen Write Access**: Use `--approval-mode yolo` ONLY when MODE=write explicitly specified
+  - **Parameter Position**: Place AFTER the wrapper command: `gemini-wrapper --approval-mode yolo -p "..."`
+- **Codex Write Access**: Use `-s danger-full-access` and `--skip-git-repo-check` ONLY when MODE=auto explicitly specified
+  - **Parameter Position**: Place AFTER the prompt string at command END: `codex ... exec "..." --skip-git-repo-check -s danger-full-access`
+- **Default Behavior**: All tools default to analysis/read-only mode without explicit write permission

.claude/workflows/workflow-architecture.md

@@ -266,28 +266,73 @@ All workflows use the same file structure definition regardless of complexity. *
 
 #### Complete Structure Reference
 ```
-.workflow/WFS-[topic-slug]/
-├── workflow-session.json        # Session metadata and state (REQUIRED)
-├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
-├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
-│   ├── chat-*.md              # Saved chat sessions
-│   └── analysis-*.md          # Analysis results
-├── [.process/]                 # Planning analysis results (created by /workflow:plan)
-│   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
-├── IMPL_PLAN.md                # Planning document (REQUIRED)
-├── TODO_LIST.md                # Progress tracking (REQUIRED)
-├── [.summaries/]               # Task completion summaries (created when tasks complete)
-│   ├── IMPL-*-summary.md      # Main task summaries
-│   └── IMPL-*.*-summary.md    # Subtask summaries
-└── .task/                      # Task definitions (REQUIRED)
-    ├── IMPL-*.json             # Main task definitions
-    └── IMPL-*.*.json           # Subtask definitions (created dynamically)
+.workflow/
+├── [.scratchpad/]              # Non-session-specific outputs (created when needed)
+│   ├── analyze-*-[timestamp].md        # One-off analysis results
+│   ├── chat-*-[timestamp].md           # Standalone chat sessions
+│   ├── plan-*-[timestamp].md           # Ad-hoc planning notes
+│   ├── bug-index-*-[timestamp].md      # Quick bug analyses
+│   ├── code-analysis-*-[timestamp].md  # Standalone code analysis
+│   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
+│   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
+│
+└── WFS-[topic-slug]/
+    ├── workflow-session.json        # Session metadata and state (REQUIRED)
+    ├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
+    ├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
+    │   ├── chat-*.md              # Saved chat sessions
+    │   └── analysis-*.md          # Analysis results
+    ├── [.process/]                 # Planning analysis results (created by /workflow:plan)
+    │   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
+    ├── IMPL_PLAN.md                # Planning document (REQUIRED)
+    ├── TODO_LIST.md                # Progress tracking (REQUIRED)
+    ├── [.summaries/]               # Task completion summaries (created when tasks complete)
+    │   ├── IMPL-*-summary.md      # Main task summaries
+    │   └── IMPL-*.*-summary.md    # Subtask summaries
+    └── .task/                      # Task definitions (REQUIRED)
+        ├── IMPL-*.json             # Main task definitions
+        └── IMPL-*.*.json           # Subtask definitions (created dynamically)
 ```
 
 #### Creation Strategy
 - **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
 - **On-Demand Creation**: Other directories created when first needed
 - **Dynamic Files**: Subtask JSON files created during task decomposition
+- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
+
+#### Scratchpad Directory (.scratchpad/)
+**Purpose**: Centralized location for non-session-specific CLI outputs
+
+**When to Use**:
+1. **No Active Session**: CLI analysis/chat commands run without an active workflow session
+2. **Unrelated Analysis**: Quick analysis not related to current active session
+3. **Exploratory Work**: Ad-hoc investigation before creating formal workflow
+4. **One-Off Queries**: Standalone questions or debugging without workflow context
+
+**Output Routing Logic**:
+- **IF** active session exists AND command is session-relevant:
+  - Save to `.workflow/WFS-[id]/.chat/[command]-[timestamp].md`
+- **ELSE** (no session OR one-off analysis):
+  - Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md`
+
+**File Naming Pattern**: `[command-type]-[brief-description]-[timestamp].md`
+
+**Examples**:
+
+*Analysis Commands (read-only):*
+- `/cli:analyze "security"` (no session) → `.scratchpad/analyze-security-20250105-143022.md`
+- `/cli:chat "build process"` (unrelated to active session) → `.scratchpad/chat-build-process-20250105-143045.md`
+- `/cli:mode:plan "feature idea"` (exploratory) → `.scratchpad/plan-feature-idea-20250105-143110.md`
+- `/cli:mode:code-analysis "trace auth flow"` (no session) → `.scratchpad/code-analysis-auth-flow-20250105-143130.md`
+
+*Implementation Commands (⚠️ modifies code):*
+- `/cli:execute "implement JWT auth"` (no session) → `.scratchpad/execute-jwt-auth-20250105-143200.md`
+- `/cli:codex-execute "refactor API layer"` (no session) → `.scratchpad/codex-execute-api-refactor-20250105-143230.md`
+
+**Maintenance**:
+- Periodically review and clean up old scratchpad files
+- Promote useful analyses to formal workflow sessions if needed
+- No automatic cleanup - manual management recommended
 
 ### File Naming Conventions
 

.codex/AGENTS.md

@@ -46,6 +46,30 @@ RULES: Build on previous subtask, maintain consistency
 
 ## Execution Requirements
 
+### System Optimization
+
+**Hard Requirement**: Call binaries directly in `functions.shell`, always set `workdir`, and avoid shell wrappers such as `bash -lc`, `sh -lc`, `zsh -lc`, `cmd /c`, `pwsh.exe -NoLogo -NoProfile -Command`, and `powershell.exe -NoLogo -NoProfile -Command`.
+
+**Text Editing Priority**: Use the `apply_patch` tool for all routine text edits; fall back to `sed` for single-line substitutions only if `apply_patch` is unavailable, and avoid `python` editing scripts unless both options fail.
+
+**`apply_patch` Usage**: Invoke `apply_patch` with the patch payload as the second element in the command array (no shell-style flags). Provide `workdir` and, when helpful, a short `justification` alongside the command.
+
+**Example invocation**:
+```json
+{
+  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
+  "workdir": "<workdir>",
+  "justification": "Brief reason for the change"
+}
+```
+
+**Windows UTF-8 Encoding**: Before executing commands on Windows systems, ensure proper UTF-8 encoding by running:
+```powershell
+[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+chcp 65001 > $null
+```
+
 ### ALWAYS
 
 - **Parse all fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
@@ -58,6 +82,9 @@ RULES: Build on previous subtask, maintain consistency
 - **Match project style** - Follow existing patterns exactly
 - **Validate EXPECTED** - Ensure all deliverables are met
 - **Report context** (subtasks) - Summarize key info for next subtask
+- **Use direct binary calls** - Avoid shell wrappers for efficiency
+- **Prefer apply_patch** - Use for text edits over Python scripts
+- **Configure Windows encoding** - Set UTF-8 for Chinese character support
 
 ### NEVER
 
@@ -335,6 +362,10 @@ Subtask 3: Add authentication (resume --last)
 
 ---
 
-**Version**: 2.1.0
+**Version**: 2.2.0
 **Last Updated**: 2025-10-04
-**Changes**: Added multi-step task execution support with resume mechanism
+**Changes**:
+- Added system optimization requirements for direct binary calls
+- Added apply_patch tool priority for text editing
+- Added Windows UTF-8 encoding configuration for Chinese character support
+- Previous: Multi-step task execution support with resume mechanism

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

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

.gitignore

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

CHANGELOG.md

@@ -5,6 +5,549 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.1] - 2025-10-07
+
+### 🎯 Intelligent Page Inference
+
+**IMPROVEMENT**: `--pages` parameter is now **optional** with smart inference from prompt or session context.
+
+**Changes**:
+- `--pages` parameter: Now optional, intelligently inferred from:
+  1. Explicit `--pages` if provided
+  2. `--prompt` text analysis (e.g., "blog with home, article pages" → ["home", "article"])
+  3. `--session` synthesis-specification.md extraction
+  4. Default: ["home"]
+
+**New Examples**:
+```bash
+# Simplest - pages inferred from prompt
+/workflow:design:auto --prompt "Modern blog with home, article and author pages"
+
+# Explicit override if needed
+/workflow:design:auto --prompt "SaaS app" --pages "dashboard,settings,billing"
+```
+
+**Commands Updated**:
+- `/workflow:design:auto`: All parameters now optional
+- `/workflow:design:ui-generate`: `--pages` optional with smart inference
+
+## [4.0.0] - 2025-10-07
+
+### 🚀 UI Design Workflow V2 - Agent Mode & Flexible Inputs
+
+**BREAKING CHANGES**: Complete redesign of UI design workflow with mandatory new parameter structure. All old command formats are deprecated.
+
+This major release introduces agent-driven creative exploration, unified variant control, dual-mode support (standalone/integrated), and flexible input sources (images + text prompts).
+
+#### Breaking Changes
+
+**Required Migration**:
+- **Old format no longer supported**: Commands using old parameter structure will fail
+- **All parameters now optional**: Smart defaults and inference for all parameters
+- **`--session`**: Optional, omitting enables standalone mode
+- **`--images`**: Optional with default `design-refs/*`
+- **`--pages`**: Optional, inferred from prompt or session (as of v4.0.1)
+- **Removed `--style-overrides`**: Use `--prompt` instead
+
+**Migration Guide**:
+```bash
+# ❌ Old (v3.5.0 and earlier) - NO LONGER WORKS
+/workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+/workflow:design:ui-generate --session WFS-auth --pages "login,register"
+
+# ✅ New (v4.0.1) - All parameters optional
+/workflow:design:style-extract --images "design-refs/*.png" --variants 3
+/workflow:design:ui-generate --variants 2
+
+# ✅ Simplest form (pages inferred from prompt)
+/workflow:design:auto --prompt "Modern blog with home, article and author pages"
+
+# ✅ With agent mode and explicit pages
+/workflow:design:auto --prompt "Modern SaaS" --pages "dashboard,settings" --variants 3 --use-agent
+```
+
+**Deprecated Commands**:
+- Old `style-extract` format without `--variants`
+- Old `ui-generate` format without `--use-agent` support
+- `--style-overrides` parameter (replaced by `--prompt`)
+
+#### Added
+
+**Unified Variant Control**:
+- **`--variants <count>`**: Single parameter controls both style cards AND UI prototypes generation
+  - Default: 3 | Range: 1-5
+  - Data flow: `auto.md` → `style-extract` → `ui-generate`
+  - Example: `--variants 3` generates 3 style cards and 3 UI variants per page
+
+**Agent Creative Exploration Mode** (`--use-agent`):
+- **style-extract**: Parallel generation of distinctly different design directions
+  - Conventional mode: Subtle variations within same core style
+  - Agent mode: Dramatically different aesthetics (e.g., "Modern Minimalist" vs "Brutalist Tech" vs "Organic Warmth")
+  - Uses `conceptual-planning-agent` for creative exploration
+- **ui-generate**: Diverse layout strategies exploration
+  - Conventional mode: Minor layout differences
+  - Agent mode: Structural variations (F-Pattern, Asymmetric Grid, Card-Based Modular)
+  - Parallel execution for efficiency
+
+**Dual Mode Support**:
+- **Integrated Mode** (with `--session`): Works within existing workflow session
+  - Location: `.workflow/WFS-{session}/`
+  - Reads from `.brainstorming/` artifacts
+  - Phase 4 (design-update) updates synthesis-specification.md
+- **Standalone Mode** (without `--session`): Independent quick prototyping
+  - Auto-creates: `design-session-YYYYMMDD-HHMMSS/`
+  - No dependency on brainstorming phase
+  - Phase 4 (design-update) is skipped
+  - Outputs final summary instead
+
+**Dual Input Source Support**:
+- **`--images`**: Reference image paths (optional, default: `design-refs/*`)
+- **`--prompt`**: Text description of design style (NEW)
+- **Hybrid Mode**: Both combined - text guides image analysis
+- Input modes:
+  - Pure image: Existing triple vision analysis
+  - Pure text: Claude keywords → Gemini philosophy → Codex tokens
+  - Hybrid: Text as context for visual analysis
+
+#### Changed
+
+**New Command Interface** (v4.0.1):
+- **`/workflow:design:auto`**:
+  - All parameters optional with smart defaults
+  - `--prompt <desc>`: Design description (infers pages automatically)
+  - `--images <glob>`: Reference images (default: `design-refs/*`)
+  - `--pages <list>`: Explicit page override (auto-inferred if omitted)
+  - `--session <id>`, `--variants <count>`, `--use-agent`, `--batch-plan`
+  - Examples:
+    - Minimal: `/workflow:design:auto --prompt "Modern blog with home and article pages"`
+    - Agent Mode: `/workflow:design:auto --prompt "SaaS dashboard and settings" --variants 3 --use-agent`
+    - Hybrid: `/workflow:design:auto --images "refs/*.png" --prompt "E-commerce: home, product, cart"`
+
+- **`/workflow:design:style-extract`**:
+  - At least one of `--images` or `--prompt` recommended
+  - All other parameters optional
+  - Agent mode: Parallel generation of diverse design directions
+
+- **`/workflow:design:ui-generate`**:
+  - All parameters optional (pages inferred from session or defaults to ["home"])
+  - `--pages <list>`: Optional explicit page list
+  - Agent mode: Parallel layout exploration (F-Pattern, Grid, Asymmetric)
+
+#### Usage Examples
+
+**Standalone Quick Prototyping**:
+```bash
+# Pure text with page inference (simplest)
+/workflow:design:auto --prompt "Modern minimalist blog with home, article and author pages, dark theme" --use-agent
+
+# Pure image with inferred pages
+/workflow:design:auto --images "refs/*.png" --variants 2
+
+# Hybrid input with explicit page override
+/workflow:design:auto --images "current-app.png" --prompt "Modernize to Linear.app style" --pages "tasks,settings" --use-agent
+```
+
+**Integrated Workflow Enhancement**:
+```bash
+# Within existing workflow (pages inferred from synthesis)
+/workflow:design:auto --session WFS-app-refresh --images "refs/*.png" --variants 3 --use-agent
+```
+
+#### Technical Details
+
+**Agent Mode Architecture**:
+- Uses `conceptual-planning-agent` for both style-extract and ui-generate phases
+- Parallel task execution: N variants × M pages run concurrently
+- Theme diversity strategies:
+  - style-extract: Creative theme generation (Minimalist, Brutalist, Organic)
+  - ui-generate: Layout strategy assignment (F-Pattern, Grid, Asymmetric)
+- Quality assurance: All variants maintain strict token adherence and WCAG AA compliance
+
+**Mode Detection Logic**:
+```bash
+# Session mode
+IF --session provided: mode = "integrated"
+ELSE: mode = "standalone", auto-create design-session-YYYYMMDD-HHMMSS/
+
+# Execution mode
+IF --use-agent: mode = "agent" (creative exploration)
+ELSE: mode = "conventional" (triple vision)
+
+# Input mode
+IF --images AND --prompt: mode = "hybrid"
+ELSE IF --images: mode = "image"
+ELSE IF --prompt: mode = "text"
+```
+
+#### Upgrade Benefits
+
+**Simplified Workflow**:
+- Fewer required parameters (only `--pages` mandatory)
+- Smart defaults reduce boilerplate
+- Standalone mode for quick prototyping without workflow setup
+
+**Enhanced Capabilities**:
+- Agent-driven creative exploration produces diverse designs
+- Parallel execution improves performance
+- Text prompts enable design without reference images
+
+**Quality Improvements**:
+- All variants maintain strict token adherence
+- WCAG AA compliance validated automatically
+- Better separation of concerns (style vs layout)
+
+## [3.5.0] - 2025-10-06
+
+### 🎨 UI Design Workflow with Triple Vision Analysis & Interactive Preview
+
+This release introduces a comprehensive UI design workflow system with triple vision analysis capabilities, interactive user checkpoints, zero agent overhead, and enhanced preview tools for real-time prototype comparison.
+
+#### Added
+
+**New UI Design Workflow System**:
+- **`/workflow:design:auto`**: Semi-autonomous UI design workflow orchestrator
+  - Interactive checkpoints for user style selection and prototype confirmation
+  - Optional batch task generation with `--batch-plan` flag
+  - Pause-and-continue pattern at critical decision points
+  - Automatic progression between phases after user input
+  - Support for multiple UI variants per page (`--variants` parameter)
+
+**Triple Vision Analysis Architecture**:
+- **Phase 1: Claude Code Vision Analysis**: Quick initial visual analysis using native Read tool
+- **Phase 2: Gemini Vision Analysis**: Deep semantic understanding of design intent
+- **Phase 3: Codex Vision Analysis**: Structured pattern recognition with `-i` parameter
+- **Phase 4: Consensus Synthesis**: Weighted combination by main Claude agent
+- **Synthesis Strategy**:
+  - Color system: Consensus with Codex precision preference
+  - Typography: Gemini semantic + Codex measurements
+  - Spacing: Cross-validation across all three sources
+  - Design philosophy: Weighted with Gemini highest priority
+  - Conflict resolution: Majority vote or synthesis-specification.md context
+
+**Individual Design Commands**:
+
+**`/workflow:design:style-extract`** - Extract design styles from reference images
+- **Usage**: `/workflow:design:style-extract --session <session_id> --images "<glob_pattern>"`
+- **Examples**:
+  ```bash
+  /workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+  /workflow:design:style-extract --session WFS-dashboard --images "refs/dashboard-*.jpg"
+  ```
+- **Features**:
+  - Triple vision analysis (Claude Code + Gemini + Codex)
+  - Generates `semantic_style_analysis.json`, `design-tokens.json`, `style-cards.json`
+  - Outputs multiple style variant cards for user selection
+  - Direct bash execution (no agent wrappers)
+  - Supports PNG, JPG, WebP image formats
+- **Output**: `.design/style-extraction/` with analysis files and 2-3 style variant cards
+
+**`/workflow:design:style-consolidate`** - Consolidate selected style variants
+- **Usage**: `/workflow:design:style-consolidate --session <session_id> --variants "<variant_ids>"`
+- **Examples**:
+  ```bash
+  /workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+  /workflow:design:style-consolidate --session WFS-dashboard --variants "variant-2"
+  ```
+- **Features**:
+  - Validates and merges design tokens from selected variants
+  - Generates finalized `design-tokens.json`, `style-guide.md`, `tailwind.config.js`
+  - WCAG AA compliance validation (contrast ≥4.5:1 for text)
+  - Token coverage ≥90% requirement
+  - OKLCH color format with fallback
+- **Output**: `.design/style-consolidation/` with validated design system files
+
+**`/workflow:design:ui-generate`** - Generate production-ready UI prototypes *(NEW: with preview enhancement)*
+- **Usage**: `/workflow:design:ui-generate --session <session_id> --pages "<page_list>" [--variants <count>] [--style-overrides "<path_or_json>"]`
+- **Examples**:
+  ```bash
+  /workflow:design:ui-generate --session WFS-auth --pages "login,register"
+  /workflow:design:ui-generate --session WFS-dashboard --pages "dashboard" --variants 3
+  /workflow:design:ui-generate --session WFS-auth --pages "login" --style-overrides "overrides.json"
+  ```
+- **Features**:
+  - Token-driven HTML/CSS generation with Codex
+  - Support for `--style-overrides` parameter for runtime customization
+  - Generates `{page}-variant-{n}.html`, `{page}-variant-{n}.css` per page
+  - **🆕 Auto-generates preview files**: `index.html`, `compare.html`, `PREVIEW.md`
+  - Semantic HTML5 with ARIA attributes
+  - Responsive design with token-based breakpoints
+  - Complete standalone prototypes (no external dependencies)
+- **Output**: `.design/prototypes/` with HTML/CSS files and preview tools
+- **Preview**: Open `index.html` in browser or start local server for interactive preview
+
+**`/workflow:design:design-update`** - Integrate design system into brainstorming
+- **Usage**: `/workflow:design:design-update --session <session_id> [--selected-prototypes "<prototype_ids>"]`
+- **Examples**:
+  ```bash
+  /workflow:design:design-update --session WFS-auth
+  /workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+  ```
+- **Features**:
+  - Updates `synthesis-specification.md` with UI/UX guidelines section
+  - Creates/updates `ui-designer/style-guide.md`
+  - Makes design tokens available for task generation phase
+  - Merges selected prototype recommendations into brainstorming artifacts
+- **Output**: Updated brainstorming files with design system integration
+
+**`/workflow:design:auto`** - Semi-autonomous orchestrator with interactive checkpoints
+- **Usage**: `/workflow:design:auto --session <session_id> --images "<glob>" --pages "<list>" [--variants <count>] [--batch-plan]`
+- **Examples**:
+  ```bash
+  /workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register"
+  /workflow:design:auto --session WFS-dashboard --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
+  ```
+- **Features**:
+  - Orchestrates entire design workflow with pause-and-continue checkpoints
+  - Checkpoint 1: User selects style variants after extraction
+  - Checkpoint 2: User confirms prototypes before design-update
+  - Optional `--batch-plan` for automatic task generation after design-update
+  - Progress tracking with TodoWrite integration
+- **Workflow**: style-extract → [USER SELECTS] → style-consolidate → ui-generate → [USER CONFIRMS] → design-update → [optional batch-plan]
+
+**Interactive Checkpoint System**:
+- **Checkpoint 1 (After style-extract)**: User selects preferred style variants
+  - Command: `/workflow:design:style-consolidate --session WFS-xxx --variants "variant-1,variant-3"`
+  - Workflow pauses until user runs consolidation command
+
+- **Checkpoint 2 (After ui-generate)**: User confirms selected prototypes
+  - Command: `/workflow:design:design-update --session WFS-xxx --selected-prototypes "page-variant-1,page-variant-2"`
+  - Workflow pauses until user runs design-update command
+
+**Design System Features**:
+- **OKLCH Color Format**: Perceptually uniform color space for design tokens
+- **W3C Design Tokens Compatibility**: Standard-compliant token format
+- **Style Override Mechanism**: Runtime token merging using jq
+- **Batch Task Generation**: Automatic `/workflow:plan` invocation for each page
+- **Accessibility Validation**: WCAG 2.1 AA compliance checks
+
+**Preview Enhancement System** *(NEW)*:
+- **`index.html`**: Master preview navigation page
+  - Grid layout of all generated prototypes
+  - Quick links to individual variants
+  - Metadata display (session ID, timestamps, page info)
+  - Direct access to implementation notes
+
+- **`compare.html`**: Interactive side-by-side comparison
+  - Iframe-based comparison for multiple variants
+  - Responsive viewport toggles (Desktop 100%, Tablet 768px, Mobile 375px)
+  - Synchronized scrolling option
+  - Dynamic page switching dropdown
+  - Real-time variant comparison
+
+- **`PREVIEW.md`**: Comprehensive preview instructions
+  - Direct browser opening guide
+  - Local server setup (Python, Node.js, PHP, VS Code Live Server)
+  - Browser compatibility notes
+  - Troubleshooting guide
+  - File structure overview
+
+**Preview Workflow**:
+```bash
+# After ui-generate completes:
+cd .workflow/WFS-{session}/.design/prototypes
+
+# Option 1: Direct browser (simplest)
+open index.html  # or double-click
+
+# Option 2: Local server (recommended)
+python -m http.server 8080  # Visit http://localhost:8080
+
+# Features:
+- index.html: Browse all prototypes
+- compare.html: Side-by-side comparison with viewport controls
+- Responsive preview: Test mobile, tablet, desktop views
+- Synchronized scrolling: Compare layouts in sync
+```
+
+#### Changed
+
+**Agent Architecture Simplification**:
+- **Removed agent wrappers** from `style-extract` and `ui-generate` commands
+  - Previously used `Task(conceptual-planning-agent)` for simple bash execution
+  - Now executes `gemini-wrapper` and `codex` commands directly via Bash tool
+  - Reduced execution overhead and complexity
+  - Preserved all functionality while improving performance
+
+**Command Execution Pattern**:
+- **Direct Bash Execution**: All CLI tools now use direct bash commands
+  - Gemini Vision: `bash(gemini-wrapper --approval-mode yolo -p "...")`
+  - Codex Vision: `bash(codex -i {images} --full-auto exec "..." -s danger-full-access)`
+  - Codex Token Generation: `bash(codex --full-auto exec "..." -s danger-full-access)`
+  - No intermediate agent layers
+
+**Workflow Integration**:
+- Design phase now optional but recommended for UI-heavy projects
+- Seamless integration with existing brainstorming → planning → execution flow
+- Design artifacts automatically discovered by `task-generate` if present
+- UI tasks automatically include `load_design_tokens` in flow_control
+
+**Updated Documentation**:
+- **README.md**: Added UI Design Workflow section in Getting Started
+- **README_CN.md**: Chinese documentation updated with design workflow
+- **Command Reference**: Added 5 new `/workflow:design:*` commands
+- **Phase Renumbering**: Shifted phases to accommodate new Phase 2 (UI Design)
+
+#### Benefits
+
+**User Experience**:
+- 🎨 **Visual Validation**: Users confirm design before implementation starts
+- ⏸️ **Interactive Control**: Critical design decisions require explicit user approval
+- 👁️ **Comprehensive Analysis**: Three AI vision sources provide robust style extraction
+- 🎯 **Zero Waiting**: Direct bash execution eliminates agent overhead
+- 📦 **Automation Ready**: Optional batch task generation accelerates workflow
+
+**Code Quality**:
+- 🔒 **Token Enforcement**: 100% CSS values use custom properties (verified)
+- ♿ **Accessibility**: WCAG AA validated at design phase
+- 🎨 **Consistency**: Single source of truth for visual design (design-tokens.json)
+- 🧪 **Production Ready**: Semantic HTML5, responsive, accessible prototypes
+
+**Development Workflow**:
+- 🔄 **Seamless Integration**: Optional design phase fits between brainstorming and planning
+- 🚀 **Backward Compatible**: Existing workflows unaffected if design phase skipped
+- 📊 **Better Planning**: Design system context improves task generation quality
+- 🎯 **Focused Implementation**: Developers work from validated prototypes and tokens
+
+#### Technical Details
+
+**Triple Vision Analysis Flow**:
+```
+Reference Images
+  ↓
+Phase 2: Claude Code (Read tool) → claude_vision_analysis.json
+Phase 3: Gemini Vision (gemini-wrapper) → gemini_vision_analysis.json
+Phase 4: Codex Vision (codex -i) → codex_vision_analysis.json
+  ↓
+Phase 5: Main Claude Synthesis → semantic_style_analysis.json
+  ↓
+Phase 6: Codex Token Generation → design-tokens.json, style-cards.json
+```
+
+**Checkpoint Workflow Pattern**:
+```
+User: /workflow:design:auto --session WFS-xxx --images "refs/*.png" --pages "dashboard,auth"
+  ↓
+Phase 1: style-extract (automatic)
+  ↓ [CHECKPOINT 1: User selects style variants]
+User: /workflow:design:style-consolidate --session WFS-xxx --variants "variant-1,variant-3"
+  ↓
+Phase 3: ui-generate (automatic after Phase 2)
+  ↓ [CHECKPOINT 2: User confirms prototypes]
+User: /workflow:design:design-update --session WFS-xxx --selected-prototypes "dashboard-variant-1,auth-variant-2"
+  ↓
+Phase 5: batch-plan (optional, automatic if --batch-plan flag)
+```
+
+**Output Structure**:
+```
+.workflow/WFS-{session}/.design/
+├── style-extraction/
+│   ├── claude_vision_analysis.json
+│   ├── gemini_vision_analysis.json
+│   ├── codex_vision_analysis.json
+│   ├── semantic_style_analysis.json (synthesis)
+│   ├── design-tokens.json (preliminary)
+│   └── style-cards.json (variants for selection)
+├── style-consolidation/
+│   ├── style-philosophy.md
+│   ├── design-tokens.json (final, validated)
+│   ├── style-guide.md
+│   ├── tailwind.config.js
+│   └── validation-report.json
+└── prototypes/
+    ├── {page}-variant-{n}.html (per page, per variant)
+    ├── {page}-variant-{n}.css (token-driven styles)
+    ├── {page}-variant-{n}-notes.md (implementation notes)
+    └── design-tokens.css (CSS custom properties)
+```
+
+**New Agent Documentation**:
+- **`ui-design-agent.md`**: Specialized agent for UI/UX design workflows
+  - Vision analysis, token generation, prototype creation capabilities
+  - Multi-modal vision provider strategy (Gemini primary, Codex fallback)
+  - Quality gates: WCAG AA, token coverage ≥90%, component mapping ≥95%
+  - Flow control specification for 3 design phases
+
+#### Use Cases
+
+**When to Use Design Workflow**:
+- User-facing applications with visual design requirements
+- Design system creation and maintenance
+- Brand-critical user interfaces
+- Projects requiring accessibility compliance
+- Multi-page applications with consistent styling
+
+**When to Skip Design Workflow**:
+- Backend APIs without UI components
+- CLI tools and command-line applications
+- Quick prototypes and MVPs
+- Projects with existing design systems
+
+---
+
+## [3.4.2] - 2025-10-05
+
+### 📚 CLI Documentation Refactoring
+
+This release focuses on eliminating redundant documentation by establishing a single source of truth (SSOT) pattern for CLI command references.
+
+#### Changed
+
+**CLI Command Documentation Refactoring**:
+- Refactored 7 CLI command documentation files to eliminate redundancy
+- Removed **681 total lines** of duplicate content across all files
+- Established implicit reference pattern to `intelligent-tools-strategy.md` (loaded in memory)
+- Preserved all unique command-specific content and capabilities
+
+**Specific File Reductions**:
+- `analyze.md`: 117→61 lines (48% reduction)
+- `chat.md`: 118→62 lines (47% reduction)
+- `execute.md`: 180→100 lines (44% reduction)
+- `codex-execute.md`: 481→473 lines (2% - preserved unique workflow content)
+- `mode/bug-index.md`: 144→75 lines (48% reduction)
+- `mode/code-analysis.md`: 188→76 lines (60% reduction)
+- `mode/plan.md`: 100→76 lines (24% reduction)
+
+**Removed Duplicate Sections**:
+- Universal Command Template (now only in `intelligent-tools-strategy.md`)
+- File Pattern Reference (centralized in strategy guide)
+- Complex Pattern Discovery (centralized in strategy guide)
+- MODE Field Definition (centralized in strategy guide)
+- Enhancement Integration details (referenced implicitly)
+- Session Persistence details (referenced implicitly)
+
+**Preserved Unique Content**:
+- Command-specific purpose and parameters
+- Unique execution flows and capabilities
+- Specialized features (YOLO permissions, task decomposition, resume patterns)
+- Command-specific examples and workflows
+- File pattern auto-detection logic for analyze command
+- Group-based execution workflow for codex-execute command
+
+#### Added
+
+**Documentation Enhancement** (prior to refactoring):
+- Enhanced file pattern examples and complex pattern discovery documentation
+- Added semantic discovery workflow integration examples
+
+#### Technical Details
+
+**Single Source of Truth Pattern**:
+All CLI commands now reference `intelligent-tools-strategy.md` for:
+- Universal command template structure
+- File pattern syntax and examples
+- Complex pattern discovery workflows
+- MODE field definitions and permissions
+- Tool-specific features and capabilities
+
+**Reference Pattern**:
+```markdown
+## Notes
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+```
+
+This approach reduces maintenance overhead while ensuring documentation consistency across all CLI commands.
+
 ## [3.4.1] - 2025-10-04
 
 ### 🎯 Multi-Tool Support for Documentation Updates

Install-Claude.ps1

@@ -63,7 +63,9 @@ param(
 
     [string]$SourceVersion = "",
 
-    [string]$SourceBranch = ""
+    [string]$SourceBranch = "",
+
+    [string]$SourceCommit = ""
 )
 
 # Set encoding for proper Unicode support
@@ -78,7 +80,10 @@ if ($PSVersionTable.PSVersion.Major -ge 6) {
 
 # Script metadata
 $ScriptName = "Claude Code Workflow System Installer"
-$Version = "2.1.0"
+$ScriptVersion = "2.2.0"  # Installer script version
+
+# Default version (will be overridden by -SourceVersion from install-remote.ps1)
+$DefaultVersion = "unknown"
 
 # Initialize backup behavior - backup is enabled by default unless NoBackup is specified
 if (-not $BackupAll -and -not $NoBackup) {
@@ -141,8 +146,15 @@ function Show-Banner {
 }
 
 function Show-Header {
+    param(
+        [string]$InstallVersion = $DefaultVersion
+    )
+
     Show-Banner
-    Write-ColorOutput "    $ScriptName v$Version" $ColorInfo
+    Write-ColorOutput "    $ScriptName v$ScriptVersion" $ColorInfo
+    if ($InstallVersion -ne "unknown") {
+        Write-ColorOutput "    Installing Claude Code Workflow v$InstallVersion" $ColorInfo
+    }
     Write-ColorOutput "    Unified workflow system with comprehensive coordination" $ColorInfo
     Write-ColorOutput "========================================================================" $ColorInfo
     if ($NoBackup) {
@@ -638,24 +650,27 @@ function Create-VersionJson {
         [string]$InstallationMode
     )
 
-    # Determine version from source or default
-    $versionNumber = if ($SourceVersion) { $SourceVersion } else { $Version }
+    # Determine version from source parameter (passed from install-remote.ps1)
+    $versionNumber = if ($SourceVersion) { $SourceVersion } else { $DefaultVersion }
     $sourceBranch = if ($SourceBranch) { $SourceBranch } else { "unknown" }
+    $commitSha = if ($SourceCommit) { $SourceCommit } else { "unknown" }
 
     # Create version.json content
     $versionInfo = @{
         version = $versionNumber
+        commit_sha = $commitSha
         installation_mode = $InstallationMode
         installation_path = $TargetClaudeDir
         installation_date_utc = (Get-Date).ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
         source_branch = $sourceBranch
+        installer_version = $ScriptVersion
     }
 
     $versionJsonPath = Join-Path $TargetClaudeDir "version.json"
 
     try {
         $versionInfo | ConvertTo-Json | Out-File -FilePath $versionJsonPath -Encoding utf8 -Force
-        Write-ColorOutput "Created version.json: $versionNumber ($InstallationMode)" $ColorSuccess
+        Write-ColorOutput "Created version.json: $versionNumber ($commitSha) - $InstallationMode" $ColorSuccess
         return $true
     } catch {
         Write-ColorOutput "WARNING: Failed to create version.json: $($_.Exception.Message)" $ColorWarning
@@ -1024,7 +1039,10 @@ function Show-Summary {
 }
 
 function Main {
-    Show-Header
+    # Use SourceVersion parameter if provided, otherwise use default
+    $installVersion = if ($SourceVersion) { $SourceVersion } else { $DefaultVersion }
+
+    Show-Header -InstallVersion $installVersion
 
     # Test prerequisites
     Write-ColorOutput "Checking system requirements..." $ColorInfo

Install-Claude.sh

@@ -24,6 +24,9 @@ FORCE=false
 NON_INTERACTIVE=false
 BACKUP_ALL=true  # Enabled by default
 NO_BACKUP=false
+SOURCE_VERSION=""  # Version from remote installer
+SOURCE_BRANCH=""   # Branch from remote installer
+SOURCE_COMMIT=""   # Commit SHA from remote installer
 
 # Functions
 function write_color() {
@@ -99,6 +102,7 @@ function test_prerequisites() {
     local claude_md="$script_dir/CLAUDE.md"
     local codex_dir="$script_dir/.codex"
     local gemini_dir="$script_dir/.gemini"
+    local qwen_dir="$script_dir/.qwen"
 
     if [ ! -d "$claude_dir" ]; then
         write_color "ERROR: .claude directory not found in $script_dir" "$COLOR_ERROR"
@@ -120,6 +124,11 @@ function test_prerequisites() {
         return 1
     fi
 
+    if [ ! -d "$qwen_dir" ]; then
+        write_color "ERROR: .qwen directory not found in $script_dir" "$COLOR_ERROR"
+        return 1
+    fi
+
     write_color "✓ Prerequisites check passed" "$COLOR_SUCCESS"
     return 0
 }
@@ -403,6 +412,7 @@ function install_global() {
     local global_claude_md="${global_claude_dir}/CLAUDE.md"
     local global_codex_dir="${user_home}/.codex"
     local global_gemini_dir="${user_home}/.gemini"
+    local global_qwen_dir="${user_home}/.qwen"
 
     write_color "Global installation path: $user_home" "$COLOR_INFO"
 
@@ -412,6 +422,7 @@ function install_global() {
     local source_claude_md="${script_dir}/CLAUDE.md"
     local source_codex_dir="${script_dir}/.codex"
     local source_gemini_dir="${script_dir}/.gemini"
+    local source_qwen_dir="${script_dir}/.qwen"
 
     # Create backup folder if needed
     local backup_folder=""
@@ -424,6 +435,8 @@ function install_global() {
             has_existing_files=true
         elif [ -d "$global_gemini_dir" ] && [ "$(ls -A "$global_gemini_dir" 2>/dev/null)" ]; then
             has_existing_files=true
+        elif [ -d "$global_qwen_dir" ] && [ "$(ls -A "$global_qwen_dir" 2>/dev/null)" ]; then
+            has_existing_files=true
         elif [ -f "$global_claude_md" ]; then
             has_existing_files=true
         fi
@@ -450,6 +463,10 @@ function install_global() {
     write_color "Merging .gemini directory contents..." "$COLOR_INFO"
     merge_directory_contents "$source_gemini_dir" "$global_gemini_dir" ".gemini directory contents" "$backup_folder"
 
+    # Merge .qwen directory contents
+    write_color "Merging .qwen directory contents..." "$COLOR_INFO"
+    merge_directory_contents "$source_qwen_dir" "$global_qwen_dir" ".qwen directory contents" "$backup_folder"
+
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then
         if [ -z "$(ls -A "$backup_folder" 2>/dev/null)" ]; then
@@ -458,6 +475,10 @@ function install_global() {
         fi
     fi
 
+    # Create version.json in global .claude directory
+    write_color "Creating version.json..." "$COLOR_INFO"
+    create_version_json "$global_claude_dir" "Global"
+
     return 0
 }
 
@@ -477,16 +498,18 @@ function install_path() {
     local source_claude_md="${script_dir}/CLAUDE.md"
     local source_codex_dir="${script_dir}/.codex"
     local source_gemini_dir="${script_dir}/.gemini"
+    local source_qwen_dir="${script_dir}/.qwen"
 
     # Local paths
     local local_claude_dir="${target_dir}/.claude"
     local local_codex_dir="${target_dir}/.codex"
     local local_gemini_dir="${target_dir}/.gemini"
+    local local_qwen_dir="${target_dir}/.qwen"
 
     # Create backup folder if needed
     local backup_folder=""
     if [ "$NO_BACKUP" = false ]; then
-        if [ -d "$local_claude_dir" ] || [ -d "$local_codex_dir" ] || [ -d "$local_gemini_dir" ] || [ -d "$global_claude_dir" ]; then
+        if [ -d "$local_claude_dir" ] || [ -d "$local_codex_dir" ] || [ -d "$local_gemini_dir" ] || [ -d "$local_qwen_dir" ] || [ -d "$global_claude_dir" ]; then
             backup_folder=$(get_backup_directory "$target_dir")
             write_color "Backup folder created: $backup_folder" "$COLOR_INFO"
         fi
@@ -575,6 +598,10 @@ function install_path() {
     write_color "Merging .gemini directory contents to local location..." "$COLOR_INFO"
     merge_directory_contents "$source_gemini_dir" "$local_gemini_dir" ".gemini directory contents" "$backup_folder"
 
+    # Merge .qwen directory contents to local location
+    write_color "Merging .qwen directory contents to local location..." "$COLOR_INFO"
+    merge_directory_contents "$source_qwen_dir" "$local_qwen_dir" ".qwen directory contents" "$backup_folder"
+
     # Remove empty backup folder
     if [ -n "$backup_folder" ] && [ -d "$backup_folder" ]; then
         if [ -z "$(ls -A "$backup_folder" 2>/dev/null)" ]; then
@@ -583,12 +610,20 @@ function install_path() {
         fi
     fi
 
+    # Create version.json in local .claude directory
+    write_color "Creating version.json in local directory..." "$COLOR_INFO"
+    create_version_json "$local_claude_dir" "Path"
+
+    # Also create version.json in global .claude directory
+    write_color "Creating version.json in global directory..." "$COLOR_INFO"
+    create_version_json "$global_claude_dir" "Global"
+
     return 0
 }
 
 function get_installation_mode() {
     if [ -n "$INSTALL_MODE" ]; then
-        write_color "Installation mode: $INSTALL_MODE" "$COLOR_INFO"
+        write_color "Installation mode: $INSTALL_MODE" "$COLOR_INFO" >&2
         echo "$INSTALL_MODE"
         return
     fi
@@ -658,6 +693,42 @@ function get_installation_path() {
     done
 }
 
+function create_version_json() {
+    local target_claude_dir="$1"
+    local installation_mode="$2"
+
+    # Determine version from source parameter (passed from install-remote.sh)
+    local version_number="${SOURCE_VERSION:-unknown}"
+    local source_branch="${SOURCE_BRANCH:-unknown}"
+    local commit_sha="${SOURCE_COMMIT:-unknown}"
+
+    # Get current UTC timestamp
+    local installation_date_utc=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+    # Create version.json content
+    local version_json_path="${target_claude_dir}/version.json"
+
+    cat > "$version_json_path" << EOF
+{
+  "version": "$version_number",
+  "commit_sha": "$commit_sha",
+  "installation_mode": "$installation_mode",
+  "installation_path": "$target_claude_dir",
+  "installation_date_utc": "$installation_date_utc",
+  "source_branch": "$source_branch",
+  "installer_version": "$VERSION"
+}
+EOF
+
+    if [ -f "$version_json_path" ]; then
+        write_color "Created version.json: $version_number ($commit_sha) - $installation_mode" "$COLOR_SUCCESS"
+        return 0
+    else
+        write_color "WARNING: Failed to create version.json" "$COLOR_WARNING"
+        return 1
+    fi
+}
+
 function show_summary() {
     local mode="$1"
     local path="$2"
@@ -676,11 +747,11 @@ function show_summary() {
     if [ "$mode" = "Path" ]; then
         echo "  Local Path: $path"
         echo "  Global Path: $HOME"
-        echo "  Local Components: agents, commands, output-styles, .codex, .gemini"
+        echo "  Local Components: agents, commands, output-styles, .codex, .gemini, .qwen"
         echo "  Global Components: workflows, scripts, python_script, etc."
     else
         echo "  Path: $path"
-        echo "  Global Components: .claude, .codex, .gemini"
+        echo "  Global Components: .claude, .codex, .gemini, .qwen"
     fi
 
     if [ "$NO_BACKUP" = true ]; then
@@ -696,10 +767,11 @@ function show_summary() {
     echo "1. Review CLAUDE.md - Customize guidelines for your project"
     echo "2. Review .codex/Agent.md - Codex agent execution protocol"
     echo "3. Review .gemini/CLAUDE.md - Gemini agent execution protocol"
-    echo "4. Configure settings - Edit .claude/settings.local.json as needed"
-    echo "5. Start using Claude Code with Agent workflow coordination!"
-    echo "6. Use /workflow commands for task execution"
-    echo "7. Use /update-memory commands for memory system management"
+    echo "4. Review .qwen/QWEN.md - Qwen agent execution protocol"
+    echo "5. Configure settings - Edit .claude/settings.local.json as needed"
+    echo "6. Start using Claude Code with Agent workflow coordination!"
+    echo "7. Use /workflow commands for task execution"
+    echo "8. Use /update-memory commands for memory system management"
 
     echo ""
     write_color "Documentation: https://github.com/catlog22/Claude-Code-Workflow" "$COLOR_INFO"
@@ -735,6 +807,18 @@ function parse_arguments() {
                 BACKUP_ALL=false
                 shift
                 ;;
+            -SourceVersion)
+                SOURCE_VERSION="$2"
+                shift 2
+                ;;
+            -SourceBranch)
+                SOURCE_BRANCH="$2"
+                shift 2
+                ;;
+            -SourceCommit)
+                SOURCE_COMMIT="$2"
+                shift 2
+                ;;
             --help|-h)
                 show_help
                 exit 0
@@ -761,6 +845,9 @@ Options:
     -NonInteractive       Run in non-interactive mode with default options
     -BackupAll            Automatically backup all existing files (default)
     -NoBackup             Disable automatic backup functionality
+    -SourceVersion <ver>  Source version (passed from install-remote.sh)
+    -SourceBranch <name>  Source branch (passed from install-remote.sh)
+    -SourceCommit <sha>   Source commit SHA (passed from install-remote.sh)
     --help, -h            Show this help message
 
 Examples:
@@ -776,6 +863,9 @@ Examples:
     # Installation without backup
     $0 -NoBackup
 
+    # With version info (typically called by install-remote.sh)
+    $0 -InstallMode Global -Force -SourceVersion "3.4.2" -SourceBranch "main" -SourceCommit "abc1234"
+
 EOF
 }
 

README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v3.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v3.5.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP Tools](https://img.shields.io/badge/🔧_MCP_Tools-Experimental-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,15 +15,16 @@
 
 **Claude Code Workflow (CCW)** is a next-generation multi-agent automation framework that orchestrates complex software development tasks through intelligent workflow management and autonomous execution.
 
-> **🎉 Latest: v3.4.0** - TDD workflow optimization & test generation enhancements. See [CHANGELOG.md](CHANGELOG.md) for details.
+> **🎉 Latest: v3.5.0** - UI Design Workflow with Triple Vision Analysis. See [CHANGELOG.md](CHANGELOG.md) for details.
 >
-> **What's New in v3.4.0**:
-> - 🧪 **TDD Workflow Streamlining**: Unified IMPL_PLAN.md structure, 33% reduction in redundant files
-> - 🔄 **Test Coverage Analysis**: TDD workflow upgraded to 6 phases with Phase 3 test context gathering
-> - 🔁 **Iterative Green Phase**: Built-in test-fix-cycle in IMPL tasks with Gemini auto-diagnosis
-> - 🛠️ **Manual-First Fixes**: Gemini + bug-fix template diagnosis by default, optional `--use-codex` automation
-> - ✅ **Test-Gen Workflow Enhancement**: Added 3 supporting tool commands for complete test generation flow
-> - ⏱️ **Dynamic Timeout Allocation**: CLI tools default to 20-120min for large-scale analysis
+> **What's New in v3.5.0**:
+> - 🎨 **UI Design Workflow**: Complete design refinement workflow from style extraction to prototype generation
+> - 👁️ **Triple Vision Analysis**: Combines Claude Code + Gemini + Codex vision capabilities for comprehensive style extraction
+> - ⏸️ **Interactive Checkpoints**: User selection points for style variants and prototype confirmation
+> - 🎯 **Zero Agent Overhead**: Direct bash execution for CLI tools, removing unnecessary agent wrappers
+> - 🎨 **Style Customization**: Runtime override support with `--style-overrides` parameter
+> - 📦 **Batch Task Generation**: Optional automatic task creation for selected prototypes with `--batch-plan`
+> - 🔄 **Semi-Autonomous Workflow**: User-driven continuation at critical design decision points
 
 ---
 
@@ -250,7 +251,26 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:brainstorm:synthesis  # Generate consolidated specification
 ```
 
-**Phase 2: Action Planning**
+**Phase 2: UI Design Refinement** *(Optional for UI-heavy projects)*
+```bash
+# Extract design styles from reference images and generate prototypes
+/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
+
+# Or run individual design phases
+/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
+/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+
+# Preview generated prototypes (NEW!)
+# Option 1: Open .workflow/WFS-auth/.design/prototypes/index.html in browser
+# Option 2: Start local server
+cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
+# Visit http://localhost:8080 for interactive preview with comparison tools
+
+/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+```
+
+**Phase 3: Action Planning**
 ```bash
 # Create executable implementation plan
 /workflow:plan "Implement JWT-based authentication system"
@@ -259,7 +279,7 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:tdd-plan "Implement authentication with test-first development"
 ```
 
-**Phase 3: Execution**
+**Phase 4: Execution**
 ```bash
 # Execute tasks with AI agents
 /workflow:execute
@@ -268,7 +288,7 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 /workflow:status
 ```
 
-**Phase 4: Testing & Quality Assurance**
+**Phase 5: Testing & Quality Assurance**
 ```bash
 # Generate independent test-fix workflow (v3.2.2+)
 /workflow:test-gen WFS-auth  # Creates WFS-test-auth session
@@ -341,6 +361,11 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 |---|---|
 | `/workflow:session:*` | Manage development sessions (`start`, `pause`, `resume`, `list`, `switch`, `complete`). |
 | `/workflow:brainstorm:*` | Use role-based agents for multi-perspective planning. |
+| `/workflow:design:auto` | **NEW** Semi-autonomous UI design workflow with interactive checkpoints for style and prototype selection. |
+| `/workflow:design:style-extract` | **NEW** Extract design styles from reference images using triple vision analysis (Claude + Gemini + Codex). |
+| `/workflow:design:style-consolidate` | **NEW** Consolidate selected style variants into validated design tokens and style guide. |
+| `/workflow:design:ui-generate` | **NEW** Generate token-driven HTML/CSS prototypes with optional style overrides. |
+| `/workflow:design:design-update` | **NEW** Integrate finalized design system into brainstorming artifacts. |
 | `/workflow:plan` | Create a detailed, executable plan from a description. |
 | `/workflow:tdd-plan` | Create TDD workflow (6 phases) with test coverage analysis and Red-Green-Refactor cycles. |
 | `/workflow:execute` | Execute the current workflow plan autonomously. |
@@ -352,6 +377,87 @@ MCP (Model Context Protocol) tools provide advanced codebase analysis. **Recomme
 | `/workflow:tools:test-concept-enhanced` | Generate test strategy and requirements analysis using Gemini. |
 | `/workflow:tools:test-task-generate` | Generate test task JSON with test-fix-cycle specification. |
 
+### **UI Design Workflow Commands (`/workflow:design:*`)** *(v3.5.0+)*
+
+The design workflow system provides complete UI design refinement from style extraction to prototype generation with interactive preview tools.
+
+#### Core Commands
+
+**`/workflow:design:auto`** - Complete workflow orchestrator
+```bash
+# Semi-autonomous workflow with user checkpoints
+/workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
+/workflow:design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
+```
+- **Checkpoints**: User selects style variants (Phase 1) and confirms prototypes (Phase 3)
+- **Optional**: `--batch-plan` for automatic task generation
+
+**`/workflow:design:style-extract`** - Triple vision style analysis
+```bash
+# Extract design from reference images
+/workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+```
+- **Vision Sources**: Claude Code + Gemini + Codex
+- **Output**: Style variant cards for user selection
+
+**`/workflow:design:style-consolidate`** - Validate and merge tokens
+```bash
+# Consolidate selected style variants
+/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+```
+- **Features**: WCAG AA validation, OKLCH colors, W3C token format
+- **Output**: `design-tokens.json`, `style-guide.md`, `tailwind.config.js`
+
+**`/workflow:design:ui-generate`** - Generate HTML/CSS prototypes
+```bash
+# Generate prototypes with preview tools
+/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+/workflow:design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"
+```
+- **🆕 Preview Files**: `index.html` (navigation), `compare.html` (side-by-side), `PREVIEW.md` (instructions)
+- **Features**: Token-driven CSS, semantic HTML5, ARIA attributes, responsive design
+
+**`/workflow:design:design-update`** - Integrate design system
+```bash
+# Update brainstorming artifacts with design system
+/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+```
+- **Updates**: `synthesis-specification.md`, `ui-designer/style-guide.md`
+- **Makes design tokens available for task generation**
+
+#### Preview System
+
+After running `ui-generate`, you get interactive preview tools:
+
+**Quick Preview** (Direct Browser):
+```bash
+# Navigate to prototypes directory
+cd .workflow/WFS-auth/.design/prototypes
+# Open index.html in browser (double-click or):
+open index.html  # macOS
+start index.html  # Windows
+xdg-open index.html  # Linux
+```
+
+**Full Preview** (Local Server - Recommended):
+```bash
+cd .workflow/WFS-auth/.design/prototypes
+# Choose one:
+python -m http.server 8080      # Python
+npx http-server -p 8080         # Node.js
+php -S localhost:8080           # PHP
+# Visit: http://localhost:8080
+```
+
+**Preview Features**:
+- `index.html`: Master navigation with all prototypes
+- `compare.html`: Side-by-side comparison with viewport controls (Desktop/Tablet/Mobile)
+- Synchronized scrolling for layout comparison
+- Dynamic page switching
+- Real-time responsive testing
+
+---
+
 ### **Task & Memory Commands**
 
 | Command | Description |

README_CN.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/version-v3.4.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
+[![Version](https://img.shields.io/badge/version-v3.5.0-blue.svg)](https://github.com/catlog22/Claude-Code-Workflow/releases)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg)]()
 [![MCP工具](https://img.shields.io/badge/🔧_MCP工具-实验性-orange.svg)](https://github.com/modelcontextprotocol)
@@ -15,15 +15,16 @@
 
 **Claude Code Workflow (CCW)** 是一个新一代的多智能体自动化开发框架，通过智能工作流管理和自主执行来协调复杂的软件开发任务。
 
-> **🎉 最新版本: v3.4.0** - TDD 工作流优化与测试生成增强。详见 [CHANGELOG.md](CHANGELOG.md)。
+> **🎉 最新版本: v3.5.0** - UI 设计工作流与三重视觉分析。详见 [CHANGELOG.md](CHANGELOG.md)。
 >
-> **v3.4.0 版本新特性**:
-> - 🧪 **TDD 工作流优化**: 精简文件结构，统一使用 IMPL_PLAN.md，减少 33% 冗余文件
-> - 🔄 **测试覆盖分析**: TDD 工作流升级至 6 阶段，新增 Phase 3 测试上下文收集
-> - 🔁 **迭代 Green Phase**: IMPL 任务内置 test-fix-cycle，支持 Gemini 自动诊断和修复
-> - 🛠️ **手动优先修复**: 默认使用 Gemini + bug-fix 模板诊断，可选 `--use-codex` 自动化
-> - ✅ **test-gen 工作流增强**: 新增 3 个配套工具命令，完整测试生成和修复流程
-> - ⏱️ **动态超时分配**: CLI 工具默认 20-120 分钟超时，适应大型项目分析
+> **v3.5.0 版本新特性**:
+> - 🎨 **UI 设计工作流**: 从风格提取到原型生成的完整设计精炼工作流
+> - 👁️ **三重视觉分析**: 融合 Claude Code + Gemini + Codex 视觉能力进行综合风格提取
+> - ⏸️ **交互式检查点**: 用户选择风格变体和原型确认的决策点
+> - 🎯 **零智能体开销**: CLI 工具直接 bash 执行，移除不必要的智能体包装
+> - 🎨 **风格自定义**: 通过 `--style-overrides` 参数支持运行时样式覆盖
+> - 📦 **批量任务生成**: 使用 `--batch-plan` 为选定原型自动创建实现任务
+> - 🔄 **半自主工作流**: 在关键设计决策点由用户驱动继续
 
 ---
 
@@ -250,7 +251,26 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:brainstorm:synthesis  # 生成综合规范
 ```
 
-**阶段 2：行动规划**
+**阶段 2：UI 设计精炼** *(UI 密集型项目可选)*
+```bash
+# 从参考图像中提取设计风格并生成原型
+/workflow:design:auto --session WFS-auth --images "design-refs/*.png" --pages "login,register" --batch-plan
+
+# 或者运行单独的设计阶段
+/workflow:design:style-extract --session WFS-auth --images "refs/*.png"
+/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+
+# 预览生成的原型（新功能！）
+# 选项1：在浏览器中打开 .workflow/WFS-auth/.design/prototypes/index.html
+# 选项2：启动本地服务器
+cd .workflow/WFS-auth/.design/prototypes && python -m http.server 8080
+# 访问 http://localhost:8080 获取交互式预览和对比工具
+
+/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+```
+
+**阶段 3：行动规划**
 ```bash
 # 创建可执行的实现计划
 /workflow:plan "实现基于 JWT 的认证系统"
@@ -259,7 +279,7 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:tdd-plan "使用测试优先开发实现认证"
 ```
 
-**阶段 3：执行**
+**阶段 4：执行**
 ```bash
 # 使用 AI 智能体执行任务
 /workflow:execute
@@ -268,7 +288,7 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 /workflow:status
 ```
 
-**阶段 4：测试与质量保证**
+**阶段 5：测试与质量保证**
 ```bash
 # 生成独立测试修复工作流（v3.2.2+）
 /workflow:test-gen WFS-auth  # 创建 WFS-test-auth 会话
@@ -341,6 +361,11 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 |---|---|
 | `/workflow:session:*` | 管理开发会话（`start`, `pause`, `resume`, `list`, `switch`, `complete`）。 |
 | `/workflow:brainstorm:*` | 使用基于角色的智能体进行多视角规划。 |
+| `/workflow:design:auto` | **新增** 带交互式检查点的半自主 UI 设计工作流，用于风格和原型选择。 |
+| `/workflow:design:style-extract` | **新增** 使用三重视觉分析（Claude + Gemini + Codex）从参考图像提取设计风格。 |
+| `/workflow:design:style-consolidate` | **新增** 将选定的风格变体整合为经过验证的设计令牌和风格指南。 |
+| `/workflow:design:ui-generate` | **新增** 生成基于令牌的 HTML/CSS 原型，支持可选的风格覆盖。 |
+| `/workflow:design:design-update` | **新增** 将最终确定的设计系统集成到头脑风暴产物中。 |
 | `/workflow:plan` | 从描述创建详细、可执行的计划。 |
 | `/workflow:tdd-plan` | 创建 TDD 工作流（6 阶段），包含测试覆盖分析和 Red-Green-Refactor 循环。 |
 | `/workflow:execute` | 自主执行当前的工作流计划。 |
@@ -352,6 +377,87 @@ MCP (模型上下文协议) 工具提供高级代码库分析。**推荐安装**
 | `/workflow:tools:test-concept-enhanced` | 使用 Gemini 生成测试策略和需求分析。 |
 | `/workflow:tools:test-task-generate` | 生成测试任务 JSON，包含 test-fix-cycle 规范。 |
 
+### **UI 设计工作流命令 (`/workflow:design:*`)** *(v3.5.0+)*
+
+设计工作流系统提供从风格提取到原型生成的完整 UI 设计精炼，配备交互式预览工具。
+
+#### 核心命令
+
+**`/workflow:design:auto`** - 完整工作流编排器
+```bash
+# 带用户检查点的半自主工作流
+/workflow:design:auto --session WFS-auth --images "refs/*.png" --pages "login,register"
+/workflow:design:auto --session WFS-dash --images "refs/*.jpg" --pages "dashboard" --variants 3 --batch-plan
+```
+- **检查点**: 用户选择风格变体（阶段1）和确认原型（阶段3）
+- **可选**: `--batch-plan` 用于自动任务生成
+
+**`/workflow:design:style-extract`** - 三重视觉风格分析
+```bash
+# 从参考图像提取设计
+/workflow:design:style-extract --session WFS-auth --images "design-refs/*.png"
+```
+- **视觉来源**: Claude Code + Gemini + Codex
+- **输出**: 用于用户选择的风格变体卡片
+
+**`/workflow:design:style-consolidate`** - 验证和合并令牌
+```bash
+# 整合选定的风格变体
+/workflow:design:style-consolidate --session WFS-auth --variants "variant-1,variant-3"
+```
+- **功能**: WCAG AA 验证、OKLCH 颜色、W3C 令牌格式
+- **输出**: `design-tokens.json`、`style-guide.md`、`tailwind.config.js`
+
+**`/workflow:design:ui-generate`** - 生成 HTML/CSS 原型
+```bash
+# 生成带预览工具的原型
+/workflow:design:ui-generate --session WFS-auth --pages "login,register" --variants 2
+/workflow:design:ui-generate --session WFS-auth --pages "dashboard" --style-overrides "custom.json"
+```
+- **🆕 预览文件**: `index.html`（导航）、`compare.html`（并排对比）、`PREVIEW.md`（说明）
+- **功能**: 令牌驱动的 CSS、语义化 HTML5、ARIA 属性、响应式设计
+
+**`/workflow:design:design-update`** - 集成设计系统
+```bash
+# 使用设计系统更新头脑风暴产物
+/workflow:design:design-update --session WFS-auth --selected-prototypes "login-variant-1,register-variant-2"
+```
+- **更新**: `synthesis-specification.md`、`ui-designer/style-guide.md`
+- **使设计令牌可用于任务生成**
+
+#### 预览系统
+
+运行 `ui-generate` 后，您将获得交互式预览工具：
+
+**快速预览**（直接浏览器）:
+```bash
+# 导航到原型目录
+cd .workflow/WFS-auth/.design/prototypes
+# 在浏览器中打开 index.html（双击或执行）:
+open index.html  # macOS
+start index.html  # Windows
+xdg-open index.html  # Linux
+```
+
+**完整预览**（本地服务器 - 推荐）:
+```bash
+cd .workflow/WFS-auth/.design/prototypes
+# 选择一个:
+python -m http.server 8080      # Python
+npx http-server -p 8080         # Node.js
+php -S localhost:8080           # PHP
+# 访问: http://localhost:8080
+```
+
+**预览功能**:
+- `index.html`: 包含所有原型的主导航
+- `compare.html`: 带视口控制的并排对比（桌面/平板/移动）
+- 同步滚动用于布局对比
+- 动态页面切换
+- 实时响应式测试
+
+---
+
 ### **任务与内存命令**
 
 | 命令 | 描述 |

install-remote.ps1

@@ -260,7 +260,8 @@ function Invoke-LocalInstaller {
     param(
         [string]$RepoDir,
         [string]$VersionInfo = "",
-        [string]$BranchInfo = ""
+        [string]$BranchInfo = "",
+        [string]$CommitSha = ""
     )
 
     $installerPath = Join-Path $RepoDir "Install-Claude.ps1"
@@ -285,9 +286,10 @@ function Invoke-LocalInstaller {
     if ($NonInteractive) { $params["NonInteractive"] = $NonInteractive }
     if ($BackupAll) { $params["BackupAll"] = $BackupAll }
 
-    # Pass version and branch information
+    # Pass version, branch, and commit information
     if ($VersionInfo) { $params["SourceVersion"] = $VersionInfo }
     if ($BranchInfo) { $params["SourceBranch"] = $BranchInfo }
+    if ($CommitSha) { $params["SourceCommit"] = $CommitSha }
 
     try {
         # Change to repo directory and run installer
@@ -562,14 +564,51 @@ function Main {
             throw "Extraction failed"
         }
 
+        # Get commit SHA from the downloaded repository first
+        $commitSha = ""
+        try {
+            Push-Location $repoDir
+            $commitSha = (git rev-parse --short HEAD 2>$null)
+            if (-not $commitSha) {
+                # Fallback: try to get from GitHub API
+                $commitUrl = "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/$Branch"
+                $commitResponse = Invoke-RestMethod -Uri $commitUrl -UseBasicParsing -TimeoutSec 5 -ErrorAction SilentlyContinue
+                if ($commitResponse.sha) {
+                    $commitSha = $commitResponse.sha.Substring(0, 7)
+                }
+            }
+            Pop-Location
+        } catch {
+            Pop-Location
+            $commitSha = "unknown"
+        }
+
         # Determine version and branch information to pass
-        $versionToPass = if ($Tag) { $Tag } else { "latest" }
+        $versionToPass = ""
+
+        if ($Tag) {
+            # Specific tag version
+            $versionToPass = $Tag -replace '^v', ''  # Remove 'v' prefix
+        } elseif ($Version -eq "stable") {
+            # Auto-detected latest stable
+            $latestTag = Get-LatestRelease
+            if ($latestTag) {
+                $versionToPass = $latestTag -replace '^v', ''
+            } else {
+                # Fallback: use commit SHA as version
+                $versionToPass = "dev-$commitSha"
+            }
+        } else {
+            # Latest development or branch - use commit SHA as version
+            $versionToPass = "dev-$commitSha"
+        }
+
         $branchToPass = if ($Version -eq "branch") { $Branch } elseif ($Version -eq "latest") { "main" } elseif ($Tag) { $Tag } else { "main" }
 
-        Write-ColorOutput "Version info: $versionToPass (branch: $branchToPass)" $ColorInfo
+        Write-ColorOutput "Version info: $versionToPass (branch: $branchToPass, commit: $commitSha)" $ColorInfo
 
         # Run local installer with version information
-        $success = Invoke-LocalInstaller -RepoDir $repoDir -VersionInfo $versionToPass -BranchInfo $branchToPass
+        $success = Invoke-LocalInstaller -RepoDir $repoDir -VersionInfo $versionToPass -BranchInfo $branchToPass -CommitSha $commitSha
         if (-not $success) {
             throw "Installation script failed"
         }

install-remote.sh

@@ -209,6 +209,9 @@ function extract_repository() {
 
 function invoke_local_installer() {
     local repo_dir="$1"
+    local version_info="$2"
+    local branch_info="$3"
+    local commit_sha="$4"
     local installer_path="${repo_dir}/Install-Claude.sh"
 
     # Make installer executable
@@ -249,6 +252,19 @@ function invoke_local_installer() {
         params+=("-BackupAll")
     fi
 
+    # Pass version, branch, and commit information
+    if [ -n "$version_info" ]; then
+        params+=("-SourceVersion" "$version_info")
+    fi
+
+    if [ -n "$branch_info" ]; then
+        params+=("-SourceBranch" "$branch_info")
+    fi
+
+    if [ -n "$commit_sha" ]; then
+        params+=("-SourceCommit" "$commit_sha")
+    fi
+
     # Execute installer
     if (cd "$repo_dir" && "$installer_path" "${params[@]}"); then
         return 0
@@ -632,8 +648,54 @@ function main() {
         if [ $extract_status -eq 0 ] && [ -n "$repo_dir" ] && [ -d "$repo_dir" ]; then
             write_color "Extraction successful: $repo_dir" "$COLOR_SUCCESS"
 
-            # Run local installer
-            if invoke_local_installer "$repo_dir"; then
+            # Get commit SHA from the downloaded repository first
+            local commit_sha=""
+            if command -v git &> /dev/null && [ -d "$repo_dir/.git" ]; then
+                commit_sha=$(cd "$repo_dir" && git rev-parse --short HEAD 2>/dev/null || echo "unknown")
+            else
+                # Fallback: try to get from GitHub API
+                local temp_branch="main"
+                [ "$VERSION_TYPE" = "branch" ] && temp_branch="$BRANCH"
+                commit_sha=$(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/$temp_branch" 2>/dev/null | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4 | cut -c1-7)
+                [ -z "$commit_sha" ] && commit_sha="unknown"
+            fi
+
+            # Determine version and branch information to pass
+            local version_to_pass=""
+            local branch_to_pass=""
+
+            if [ -n "$TAG_VERSION" ]; then
+                # Specific tag version - remove 'v' prefix
+                version_to_pass="${TAG_VERSION#v}"
+            elif [ "$VERSION_TYPE" = "stable" ]; then
+                # Auto-detected latest stable
+                local latest_tag
+                latest_tag=$(get_latest_release)
+                if [ -n "$latest_tag" ]; then
+                    version_to_pass="${latest_tag#v}"
+                else
+                    # Fallback: use commit SHA as version
+                    version_to_pass="dev-$commit_sha"
+                fi
+            else
+                # Latest development or branch - use commit SHA as version
+                version_to_pass="dev-$commit_sha"
+            fi
+
+            if [ "$VERSION_TYPE" = "branch" ]; then
+                branch_to_pass="$BRANCH"
+            elif [ "$VERSION_TYPE" = "latest" ]; then
+                branch_to_pass="main"
+            elif [ -n "$TAG_VERSION" ]; then
+                branch_to_pass="$TAG_VERSION"
+            else
+                branch_to_pass="main"
+            fi
+
+            write_color "Version info: $version_to_pass (branch: $branch_to_pass, commit: $commit_sha)" "$COLOR_INFO"
+
+            # Run local installer with version information
+            if invoke_local_installer "$repo_dir" "$version_to_pass" "$branch_to_pass" "$commit_sha"; then
                 success=true
                 echo ""
                 write_color "✓ Remote installation completed successfully!" "$COLOR_SUCCESS"