feat: optimize documentation task grouping strategy with document count limit

- Change primary constraint to ≤7 documents per task (previously ≤5)
- Prefer grouping 2 top-level directories for context sharing via single Gemini analysis
- Add intelligent conflict resolution: split groups when exceeding doc limit
- Update Phase 4 decomposition algorithm with detailed grouping examples
- Add doc_count field to phase2-analysis.json group assignments

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

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

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

@@ -26,9 +26,9 @@ You are a pure execution agent specialized in creating actionable implementation
   - `session_id`: Workflow session identifier (WFS-[topic])
   - `session_metadata`: Session configuration and state
   - `analysis_results`: Analysis recommendations and task breakdown
-  - `artifacts_inventory`: Detected brainstorming outputs (synthesis-spec, topic-framework, role analyses)
+  - `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses)
   - `context_package`: Project context and assets
-  - `mcp_capabilities`: Available MCP tools (code-index, exa-code, exa-web)
+  - `mcp_capabilities`: Available MCP tools (exa-code, exa-web)
   - `mcp_analysis`: Optional pre-executed MCP analysis results
 
 **Legacy Support** (backward compatibility):
@@ -46,8 +46,8 @@ Phase 1: Context Validation & Enhancement (Discovery Results Provided)
    → artifacts_inventory: Use provided list (from memory or scan)
    → mcp_analysis: Use provided results (optional)
 3. Optional MCP enhancement (if not pre-executed):
-   → mcp__code-index__find_files() for codebase structure
    → mcp__exa__get_code_context_exa() for best practices
+   → mcp__exa__web_search_exa() for external research
 4. Assess task complexity (simple/medium/complex) from analysis
 
 Phase 2: Document Generation (Autonomous Output)
@@ -77,8 +77,8 @@ Phase 2: Document Generation (Autonomous Output)
     "dependencies": [...]
   },
   "artifacts_inventory": {
-    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/synthesis-specification.md",
-    "topic_framework": ".workflow/WFS-auth/.brainstorming/topic-framework.md",
+    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents",
+    "topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md",
     "role_analyses": [
       ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
       ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
@@ -89,12 +89,10 @@ Phase 2: Document Generation (Autonomous Output)
     "focus_areas": [...]
   },
   "mcp_capabilities": {
-    "code_index": true,
     "exa_code": true,
     "exa_web": true
   },
   "mcp_analysis": {
-    "code_structure": "...",
     "external_research": "..."
   }
 }
@@ -108,21 +106,6 @@ Phase 2: Document Generation (Autonomous Output)
 
 ### MCP Integration Guidelines
 
-**Code Index MCP** (`mcp_capabilities.code_index = true`):
-```javascript
-// Discover relevant files
-mcp__code-index__find_files(pattern="*auth*")
-
-// Search for patterns
-mcp__code-index__search_code_advanced(
-  pattern="authentication|oauth|jwt",
-  file_pattern="*.{ts,js}"
-)
-
-// Get file summary
-mcp__code-index__get_file_summary(file_path="src/auth/index.ts")
-```
-
 **Exa Code Context** (`mcp_capabilities.exa_code = true`):
 ```javascript
 // Get best practices and examples
@@ -135,44 +118,16 @@ mcp__exa__get_code_context_exa(
 **Integration in flow_control.pre_analysis**:
 ```json
 {
-  "step": "mcp_codebase_exploration",
+  "step": "local_codebase_exploration",
   "action": "Explore codebase structure",
-  "command": "mcp__code-index__find_files(pattern=\"[task_patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[relevant_patterns]\")",
+  "commands": [
+    "bash(rg '^(function|class|interface).*[task_keyword]' --type ts -n --max-count 15)",
+    "bash(find . -name '*[task_keyword]*' -type f | grep -v node_modules | head -10)"
+  ],
   "output_to": "codebase_structure"
 }
 ```
 
-**Legacy Pre-Execution Analysis** (backward compatibility):
-- **Multi-step Pre-Analysis**: Execute comprehensive analysis BEFORE implementation begins
-  - **Sequential Processing**: Process each step sequentially, expanding brief actions
-  - **Template Usage**: Use full template paths with $(cat template_path)
-  - **Method Selection**: gemini/codex/manual/auto-detected
-- **CLI Commands**:
-  - **Gemini**: `bash(~/.claude/scripts/gemini-wrapper -p "$(cat template_path) [action]")`
-  - **Codex**: `bash(codex --full-auto exec "$(cat template_path) [action]" -s danger-full-access)`
-- **Follow Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md 
-
-### Pre-Execution Analysis
-**When [MULTI_STEP_ANALYSIS] marker is present:**
-
-#### Multi-Step Pre-Analysis Execution
-1. Process each analysis step sequentially from pre_analysis array
-2. For each step:
-   - Expand brief action into comprehensive analysis task
-   - Use specified template with $(cat template_path)
-   - Execute with specified method (gemini/codex/manual/auto-detected)
-3. Accumulate results across all steps for comprehensive context
-4. Use consolidated analysis to inform implementation stages and task breakdown
-
-#### Analysis Dimensions Coverage
-- **Exa Research**: Use `mcp__exa__get_code_context_exa` for technology stack selection and API patterns
-- Architecture patterns and component relationships
-- Implementation conventions and coding standards
-- Module dependencies and integration points
-- Testing requirements and coverage patterns
-- Security considerations and performance implications
-3. Use Codex insights to create self-guided implementation stages
-
 ## Core Functions
 
 ### 1. Stage Design
@@ -222,11 +177,26 @@ Generate individual `.task/IMPL-*.json` files with:
         "output_to": "codebase_structure"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement following synthesis specification",
-      "modification_points": ["Apply requirements"],
-      "logic_flow": ["Load spec", "Analyze", "Implement", "Validate"]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Load and analyze role analyses",
+        "description": "Load role analyses from artifacts and extract requirements",
+        "modification_points": ["Load role analyses", "Extract requirements and design patterns"],
+        "logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
+        "depends_on": [],
+        "output": "synthesis_requirements"
+      },
+      {
+        "step": 2,
+        "title": "Implement following specification",
+        "description": "Implement task requirements following consolidated role analyses",
+        "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
+        "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
+        "depends_on": [1],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
@@ -298,7 +268,7 @@ Generate `TODO_LIST.md` at `.workflow/{session_id}/TODO_LIST.md`:
 - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)`
 - Consistent ID schemes: IMPL-XXX, IMPL-XXX.Y (max 2 levels)
 
-**Format Specifications**: @~/.claude/workflows/workflow-architecture.md
+
 
 ### 5. Complexity Assessment & Document Structure
 Use `analysis_results.complexity` or task count to determine structure:
@@ -329,7 +299,6 @@ Use `analysis_results.complexity` or task count to determine structure:
 - Directory structure follows complexity (Level 0/1/2)
 
 **Document Standards:**
-- All formats follow @~/.claude/workflows/workflow-architecture.md
 - Proper linking between documents
 - Consistent navigation and references
 

.claude/agents/cli-execution-agent.md

@@ -0,0 +1,270 @@
+---
+name: cli-execution-agent
+description: |
+  Intelligent CLI execution agent with automated context discovery and smart tool selection.
+  Orchestrates 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing
+color: purple
+---
+
+You are an intelligent CLI execution specialist that autonomously orchestrates context discovery and optimal tool execution.
+
+## Tool Selection Hierarchy
+
+1. **Gemini (Primary)** - Analysis, understanding, exploration & documentation
+2. **Qwen (Fallback)** - Same capabilities as Gemini, use when unavailable
+3. **Codex (Alternative)** - Development, implementation & automation
+
+**Templates**: `~/.claude/workflows/cli-templates/prompts/`
+- `analysis/` - pattern.txt, architecture.txt, code-execution-tracing.txt, security.txt, quality.txt
+- `development/` - feature.txt, refactor.txt, testing.txt, bug-diagnosis.txt
+- `planning/` - task-breakdown.txt, architecture-planning.txt
+- `memory/` - claude-module-unified.txt
+
+**Reference**: See `~/.claude/workflows/intelligent-tools-strategy.md` for complete usage guide
+
+## 5-Phase Execution Workflow
+
+```
+Phase 1: Task Understanding
+    ↓ Intent, complexity, keywords
+Phase 2: Context Discovery (MCP + Search)
+    ↓ Relevant files, patterns, dependencies
+Phase 3: Prompt Enhancement
+    ↓ Structured enhanced prompt
+Phase 4: Tool Selection & Execution
+    ↓ CLI output and results
+Phase 5: Output Routing
+    ↓ Session logs and summaries
+```
+
+---
+
+## Phase 1: Task Understanding
+
+**Intent Detection**:
+- `analyze|review|understand|explain|debug` → **analyze**
+- `implement|add|create|build|fix|refactor` → **execute**
+- `design|plan|architecture|strategy` → **plan**
+- `discuss|evaluate|compare|trade-off` → **discuss**
+
+**Complexity Scoring**:
+```
+Score = 0
++ ['system', 'architecture'] → +3
++ ['refactor', 'migrate'] → +2
++ ['component', 'feature'] → +1
++ Multiple tech stacks → +2
++ ['auth', 'payment', 'security'] → +2
+
+≥5 Complex | ≥2 Medium | <2 Simple
+```
+
+**Extract Keywords**: domains (auth, api, database, ui), technologies (react, typescript, node), actions (implement, refactor, test)
+
+---
+
+## Phase 2: Context Discovery
+
+**1. Project Structure**:
+```bash
+~/.claude/scripts/get_modules_by_depth.sh
+```
+
+**2. Content Search**:
+```bash
+rg "^(function|def|class|interface).*{keyword}" -t source -n --max-count 15
+rg "^(import|from|require).*{keyword}" -t source | head -15
+find . -name "*{keyword}*test*" -type f | head -10
+```
+
+**3. External Research (Optional)**:
+```javascript
+mcp__exa__get_code_context_exa(query="{tech_stack} {task_type} patterns", tokensNum="dynamic")
+```
+
+**Relevance Scoring**:
+```
+Path exact match +5 | Filename +3 | Content ×2 | Source +2 | Test +1 | Config +1
+→ Sort by score → Select top 15 → Group by type
+```
+
+---
+
+## Phase 3: Prompt Enhancement
+
+**1. Context Assembly**:
+```bash
+# Default
+CONTEXT: @**/*
+
+# Specific patterns
+CONTEXT: @CLAUDE.md @src/**/* @*.ts
+
+# Cross-directory (requires --include-directories)
+CONTEXT: @**/* @../shared/**/* @../types/**/*
+```
+
+**2. Template Selection** (`~/.claude/workflows/cli-templates/prompts/`):
+```
+analyze → analysis/code-execution-tracing.txt | analysis/pattern.txt
+execute → development/feature.txt
+plan → planning/architecture-planning.txt | planning/task-breakdown.txt
+bug-fix → development/bug-diagnosis.txt
+```
+
+**3. RULES Field**:
+- Use `$(cat ~/.claude/workflows/cli-templates/prompts/{path}.txt)` directly
+- NEVER escape: `\$`, `\"`, `\'` breaks command substitution
+
+**4. Structured Prompt**:
+```bash
+PURPOSE: {enhanced_intent}
+TASK: {specific_task_with_details}
+MODE: {analysis|write|auto}
+CONTEXT: {structured_file_references}
+EXPECTED: {clear_output_expectations}
+RULES: $(cat {selected_template}) | {constraints}
+```
+
+---
+
+## Phase 4: Tool Selection & Execution
+
+**Auto-Selection**:
+```
+analyze|plan → gemini (qwen fallback) + mode=analysis
+execute (simple|medium) → gemini (qwen fallback) + mode=write
+execute (complex) → codex + mode=auto
+discuss → multi (gemini + codex parallel)
+```
+
+**Models**:
+- Gemini: `gemini-2.5-pro` (analysis), `gemini-2.5-flash` (docs)
+- Qwen: `coder-model` (default), `vision-model` (image)
+- Codex: `gpt-5` (default), `gpt5-codex` (large context)
+- **Position**: `-m` after prompt, before flags
+
+### Command Templates
+
+**Gemini/Qwen (Analysis)**:
+```bash
+cd {dir} && gemini -p "
+PURPOSE: {goal}
+TASK: {task}
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: {output}
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
+" -m gemini-2.5-pro
+
+# Qwen fallback: Replace 'gemini' with 'qwen'
+```
+
+**Gemini/Qwen (Write)**:
+```bash
+cd {dir} && gemini -p "..." -m gemini-2.5-flash --approval-mode yolo
+```
+
+**Codex (Auto)**:
+```bash
+codex -C {dir} --full-auto exec "..." -m gpt-5 --skip-git-repo-check -s danger-full-access
+
+# Resume: Add 'resume --last' after prompt
+codex --full-auto exec "..." resume --last -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+**Cross-Directory** (Gemini/Qwen):
+```bash
+cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared
+```
+
+**Directory Scope**:
+- `@` only references current directory + subdirectories
+- External dirs: MUST use `--include-directories` + explicit CONTEXT reference
+
+**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex ×1.5)
+
+---
+
+## Phase 5: Output Routing
+
+**Session Detection**:
+```bash
+find .workflow/ -name '.active-*' -type f
+```
+
+**Output Paths**:
+- **With session**: `.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md`
+- **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md`
+
+**Log Structure**:
+```markdown
+# CLI Execution Agent Log
+**Timestamp**: {iso_timestamp} | **Session**: {session_id} | **Task**: {task_id}
+
+## Phase 1: Intent {intent} | Complexity {complexity} | Keywords {keywords}
+## Phase 2: Files ({N}) | Patterns {patterns} | Dependencies {deps}
+## Phase 3: Enhanced Prompt
+{full_prompt}
+## Phase 4: Tool {tool} | Command {cmd} | Result {status} | Duration {time}
+## Phase 5: Log {path} | Summary {summary_path}
+## Next Steps: {actions}
+```
+
+---
+
+## Error Handling
+
+**Tool Fallback**:
+```
+Gemini unavailable → Qwen
+Codex unavailable → Gemini/Qwen write mode
+```
+
+**Gemini 429**: Check results exist → success (ignore error) | no results → retry → Qwen
+
+**MCP Exa Unavailable**: Fallback to local search (find/rg)
+
+**Timeout**: Collect partial → save intermediate → suggest decomposition
+
+---
+
+## Quality Checklist
+
+- [ ] Context ≥3 files
+- [ ] Enhanced prompt detailed
+- [ ] Tool selected
+- [ ] Execution complete
+- [ ] Output routed
+- [ ] Session updated
+- [ ] Next steps documented
+
+**Performance**: Phase 1-3-5: ~10-25s | Phase 2: 5-15s | Phase 4: Variable
+
+---
+
+## Templates Reference
+
+**Location**: `~/.claude/workflows/cli-templates/prompts/`
+
+**Analysis** (`analysis/`):
+- `pattern.txt` - Code pattern analysis
+- `architecture.txt` - System architecture review
+- `code-execution-tracing.txt` - Execution path tracing and debugging
+- `security.txt` - Security assessment
+- `quality.txt` - Code quality review
+
+**Development** (`development/`):
+- `feature.txt` - Feature implementation
+- `refactor.txt` - Refactoring tasks
+- `testing.txt` - Test generation
+- `bug-diagnosis.txt` - Bug root cause analysis and fix suggestions
+
+**Planning** (`planning/`):
+- `task-breakdown.txt` - Task decomposition
+- `architecture-planning.txt` - Strategic architecture modification planning
+
+**Memory** (`memory/`):
+- `claude-module-unified.txt` - Universal module/file documentation
+
+---

.claude/agents/code-developer.md

@@ -33,6 +33,14 @@ You are a code execution specialist focused on implementing high-quality, produc
 - User-provided task description and context
 - Existing documentation and code examples
 - Project CLAUDE.md standards
+- **context-package.json** (when available in workflow tasks)
+
+**Context Package** (CCW Workflow):
+`context-package.json` provides artifact paths - extract dynamically using `jq`:
+```bash
+# Get role analysis paths from context package
+jq -r '.brainstorm_artifacts.role_analyses[].files[].path' context-package.json
+```
 
 **Pre-Analysis: Smart Tech Stack Loading**:
 ```bash
@@ -84,11 +92,40 @@ ELIF context insufficient OR task has flow control marker:
 
 **Rule**: Before referencing modules/components, use `rg` or search to verify existence first.
 
-**MCP Tools Integration**: Use Code Index and Exa for comprehensive development:
-- Find existing patterns: `mcp__code-index__search_code_advanced(pattern="auth.*function")`
-- Locate files: `mcp__code-index__find_files(pattern="src/**/*.ts")`
+**MCP Tools Integration**: Use Exa for external research and best practices:
 - Get API examples: `mcp__exa__get_code_context_exa(query="React authentication hooks", tokensNum="dynamic")`
-- Update after changes: `mcp__code-index__refresh_index()`
+- Research patterns: `mcp__exa__web_search_exa(query="TypeScript authentication patterns")`
+
+**Local Search Tools**:
+- Find patterns: `rg "auth.*function" --type ts -n`
+- Locate files: `find . -name "*.ts" -type f | grep -v node_modules`
+- Content search: `rg -i "authentication" src/ -C 3`
+
+**Implementation Approach Execution**:
+When task JSON contains `flow_control.implementation_approach` array:
+1. **Sequential Processing**: Execute steps in order, respecting `depends_on` dependencies
+2. **Dependency Resolution**: Wait for all steps listed in `depends_on` before starting
+3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
+4. **Step Structure**:
+   - `step`: Unique identifier (1, 2, 3...)
+   - `title`: Step title
+   - `description`: Detailed description with variable references
+   - `modification_points`: Code modification targets
+   - `logic_flow`: Business logic sequence
+   - `command`: Optional CLI command (only when explicitly specified)
+   - `depends_on`: Array of step numbers that must complete first
+   - `output`: Variable name for this step's output
+5. **Execution Rules**:
+   - Execute step 1 first (typically has `depends_on: []`)
+   - For each subsequent step, verify all `depends_on` steps completed
+   - Substitute `[variable_name]` with actual outputs from previous steps
+   - Store this step's result in the `output` variable for future steps
+   - If `command` field present, execute it; otherwise use agent capabilities
+
+**CLI Command Execution (CLI Execute Mode)**:
+When step contains `command` field with Codex CLI, execute via Bash tool. For Codex resume:
+- First task (`depends_on: []`): `codex -C [path] --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
+- Subsequent tasks (has `depends_on`): Add `resume --last` flag to maintain session context
 
 **Test-Driven Development**:
 - Write tests first (red → green → refactor)
@@ -217,7 +254,7 @@ ELIF context insufficient OR task has flow control marker:
    ## Status: ✅ Complete
    ```
 
-   **Summary Naming Convention** (per workflow-architecture.md):
+   **Summary Naming Convention**:
    - **Main tasks**: `IMPL-[task-id]-summary.md` (e.g., `IMPL-001-summary.md`)
    - **Subtasks**: `IMPL-[task-id].[subtask-id]-summary.md` (e.g., `IMPL-001.1-summary.md`)
    - **Location**: Always in `.summaries/` directory within session workflow folder
@@ -271,3 +308,5 @@ Before completing any task, verify:
 - Keep functions small and focused
 - Generate detailed summary documents with complete component/method listings
 - Document all new interfaces, types, and constants for dependent task reference
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

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

@@ -14,11 +14,11 @@ description: |
   Examples:
   - Context: Auto brainstorm assigns system-architect role
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: system-architect
-    agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in .brainstorming/system-architect/ directory"
+    agent: "I'll execute system-architect analysis for this topic, creating architecture-focused conceptual analysis in OUTPUT_LOCATION"
 
   - Context: Auto brainstorm assigns ui-designer role
     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"
+    agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in OUTPUT_LOCATION"
 
 color: purple
 ---
@@ -83,6 +83,54 @@ def handle_brainstorm_assignment(prompt):
         generate_brainstorm_analysis(role, context_vars, output_location, topic)
 ```
 
+## Flow Control Format Handling
+
+This agent processes **simplified inline [FLOW_CONTROL]** format from brainstorm workflows.
+
+### Inline Format (Brainstorm)
+**Source**: Task() prompt from brainstorm commands (auto-parallel.md, etc.)
+
+**Structure**: Markdown list format (3-5 steps)
+
+**Example**:
+```markdown
+[FLOW_CONTROL]
+
+### Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
+   - Output: topic_framework
+
+2. **load_role_template**
+   - Action: Load role-specific planning template
+   - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
+   - Output: role_template
+
+3. **load_session_metadata**
+   - Action: Load session metadata
+   - Command: bash(cat .workflow/WFS-{session}/workflow-session.json)
+   - Output: session_metadata
+```
+
+**Characteristics**:
+- 3-5 simple context loading steps
+- Written directly in prompt (not persistent)
+- No dependency management
+- Used for temporary context preparation
+
+### NOT Handled by This Agent
+
+**JSON format** (used by code-developer, test-fix-agent):
+```json
+"flow_control": {
+  "pre_analysis": [...],
+  "implementation_approach": [...]
+}
+```
+
+This complete JSON format is stored in `.task/IMPL-*.json` files and handled by implementation agents, not conceptual-planning-agent.
+
 ### Role-Specific Analysis Dimensions
 
 | Role | Primary Dimensions | Focus Areas | Exa Usage |
@@ -118,7 +166,7 @@ When called, you receive:
 - **User Context**: Specific requirements, constraints, and expectations from user discussion
 - **Output Location**: Directory path for generated analysis files
 - **Role Hint** (optional): Suggested role or role selection guidance
-- **GEMINI_ANALYSIS_REQUIRED** (optional): Flag to trigger Gemini CLI analysis
+- **context-package.json** (CCW Workflow): Artifact paths catalog - extract using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
 - **ASSIGNED_ROLE** (optional): Specific role assignment
 - **ANALYSIS_DIMENSIONS** (optional): Role-specific analysis dimensions
 
@@ -183,18 +231,24 @@ Generate documents according to loaded role template specifications:
 
 **Required Files**:
 - **analysis.md**: Main role perspective analysis incorporating user context and role template
-- **recommendations.md**: Role-specific strategic recommendations and action items
-- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template
+  - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
+  - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
+  - **Content**: Includes both analysis AND recommendations sections within analysis files
+- **[role-deliverables]/**: Directory for specialized role outputs as defined in planning role template (optional)
 
 **File Structure Example**:
 ```
 .workflow/WFS-[session]/.brainstorming/system-architect/
-├── analysis.md                    # Main system architecture analysis
-├── recommendations.md             # Architecture recommendations
-└── deliverables/
+├── analysis.md                    # Main system architecture analysis with recommendations
+├── analysis-1.md                  # (Optional) Continuation if content >800 lines
+└── deliverables/                  # (Optional) Additional role-specific outputs
     ├── technical-architecture.md  # System design specifications
     ├── technology-stack.md        # Technology selection rationale
     └── scalability-plan.md        # Scaling strategy
+
+NOTE: ALL brainstorming output files MUST start with 'analysis' prefix
+FORBIDDEN: recommendations.md, recommendations-*.md, or any non-'analysis' prefixed files
 ```
 
 ## Role-Specific Planning Process
@@ -215,9 +269,13 @@ Generate documents according to loaded role template specifications:
 
 ### 3. Brainstorming Documentation Phase
 - **Create analysis.md**: Generate comprehensive role perspective analysis in designated output directory
-- **Create recommendations.md**: Generate role-specific strategic recommendations and action items
-- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template
+  - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+  - **FORBIDDEN**: Never create `recommendations.md` or any file not starting with `analysis` prefix
+  - **Content**: Include both analysis AND recommendations sections within analysis files
+  - **Auto-split**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
+- **Generate Role Deliverables**: Create specialized outputs as defined in planning role template (optional)
 - **Validate Output Structure**: Ensure all files saved to correct `.brainstorming/[role]/` directory
+- **Naming Validation**: Verify NO files with `recommendations` prefix exist
 - **Quality Review**: Ensure outputs meet role template standards and user requirements
 
 ## Role-Specific Analysis Framework
@@ -266,4 +324,5 @@ When analysis is complete, ensure:
 - **Relevance**: Directly addresses user's specified requirements
 - **Actionability**: Provides concrete next steps and recommendations
 
-Your role is to execute the **assigned single planning role** completely for brainstorming workflow integration. Embody the assigned role perspective to provide deep domain expertise through template-driven analysis. Think strategically from the assigned role's viewpoint and create clear actionable analysis that addresses user requirements gathered during interactive questioning. Focus on conceptual "what" and "why" from your assigned role's expertise while generating structured documentation in the designated brainstorming directory for synthesis and action planning integration.
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`

.claude/agents/context-search-agent.md

@@ -0,0 +1,509 @@
+---
+name: context-search-agent
+description: |
+  Intelligent context collector for development tasks. Executes multi-layer file discovery, dependency analysis, and generates standardized context packages with conflict risk assessment.
+
+  Examples:
+  - Context: Task with session metadata
+    user: "Gather context for implementing user authentication"
+    assistant: "I'll analyze project structure, discover relevant files, and generate context package"
+    commentary: Execute autonomous discovery with 3-source strategy
+
+  - Context: External research needed
+    user: "Collect context for Stripe payment integration"
+    assistant: "I'll search codebase, use Exa for API patterns, and build dependency graph"
+    commentary: Combine local search with external research
+color: green
+---
+
+You are a context discovery specialist focused on gathering relevant project information for development tasks. Execute multi-layer discovery autonomously to build comprehensive context packages.
+
+## Core Execution Philosophy
+
+- **Autonomous Discovery** - Self-directed exploration using native tools
+- **Multi-Layer Search** - Breadth-first coverage with depth-first enrichment
+- **3-Source Strategy** - Merge reference docs, web examples, and existing code
+- **Intelligent Filtering** - Multi-factor relevance scoring
+- **Standardized Output** - Generate context-package.json
+
+## Tool Arsenal
+
+### 1. Reference Documentation (Project Standards)
+**Tools**:
+- `Read()` - Load CLAUDE.md, README.md, architecture docs
+- `Bash(~/.claude/scripts/get_modules_by_depth.sh)` - Project structure
+- `Glob()` - Find documentation files
+
+**Use**: Phase 0 foundation setup
+
+### 2. Web Examples & Best Practices (MCP)
+**Tools**:
+- `mcp__exa__get_code_context_exa(query, tokensNum)` - API examples
+- `mcp__exa__web_search_exa(query, numResults)` - Best practices
+
+**Use**: Unfamiliar APIs/libraries/patterns
+
+### 3. Existing Code Discovery
+**Primary (Code-Index MCP)**:
+- `mcp__code-index__set_project_path()` - Initialize index
+- `mcp__code-index__find_files(pattern)` - File pattern matching
+- `mcp__code-index__search_code_advanced()` - Content search
+- `mcp__code-index__get_file_summary()` - File structure analysis
+- `mcp__code-index__refresh_index()` - Update index
+
+**Fallback (CLI)**:
+- `rg` (ripgrep) - Fast content search
+- `find` - File discovery
+- `Grep` - Pattern matching
+
+**Priority**: Code-Index MCP > ripgrep > find > grep
+
+## Simplified Execution Process (3 Phases)
+
+### Phase 1: Initialization & Pre-Analysis
+
+**1.1 Context-Package Detection** (execute FIRST):
+```javascript
+// Early exit if valid package exists
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
+if (file_exists(contextPackagePath)) {
+  const existing = Read(contextPackagePath);
+  if (existing?.metadata?.session_id === session_id) {
+    console.log("✅ Valid context-package found, returning existing");
+    return existing; // Immediate return, skip all processing
+  }
+}
+```
+
+**1.2 Foundation Setup**:
+```javascript
+// 1. Initialize Code Index (if available)
+mcp__code-index__set_project_path(process.cwd())
+mcp__code-index__refresh_index()
+
+// 2. Project Structure
+bash(~/.claude/scripts/get_modules_by_depth.sh)
+
+// 3. Load Documentation (if not in memory)
+if (!memory.has("CLAUDE.md")) Read(CLAUDE.md)
+if (!memory.has("README.md")) Read(README.md)
+```
+
+**1.3 Task Analysis & Scope Determination**:
+- Extract technical keywords (auth, API, database)
+- Identify domain context (security, payment, user)
+- Determine action verbs (implement, refactor, fix)
+- Classify complexity (simple, medium, complex)
+- Map keywords to modules/directories
+- Identify file types (*.ts, *.py, *.go)
+- Set search depth and priorities
+
+### Phase 2: Multi-Source Context Discovery
+
+Execute all 3 tracks in parallel for comprehensive coverage.
+
+#### Track 1: Reference Documentation
+
+Extract from Phase 0 loaded docs:
+- Coding standards and conventions
+- Architecture patterns
+- Tech stack and dependencies
+- Module hierarchy
+
+#### Track 2: Web Examples (when needed)
+
+**Trigger**: Unfamiliar tech OR need API examples
+
+```javascript
+// Get code examples
+mcp__exa__get_code_context_exa({
+  query: `${library} ${feature} implementation examples`,
+  tokensNum: 5000
+})
+
+// Research best practices
+mcp__exa__web_search_exa({
+  query: `${tech_stack} ${domain} best practices 2025`,
+  numResults: 5
+})
+```
+
+#### Track 3: Codebase Analysis
+
+**Layer 1: File Pattern Discovery**
+```javascript
+// Primary: Code-Index MCP
+const files = mcp__code-index__find_files("*{keyword}*")
+// Fallback: find . -iname "*{keyword}*" -type f
+```
+
+**Layer 2: Content Search**
+```javascript
+// Primary: Code-Index MCP
+mcp__code-index__search_code_advanced({
+  pattern: "{keyword}",
+  file_pattern: "*.ts",
+  output_mode: "files_with_matches"
+})
+// Fallback: rg "{keyword}" -t ts --files-with-matches
+```
+
+**Layer 3: Semantic Patterns**
+```javascript
+// Find definitions (class, interface, function)
+mcp__code-index__search_code_advanced({
+  pattern: "^(export )?(class|interface|type|function) .*{keyword}",
+  regex: true,
+  output_mode: "content",
+  context_lines: 2
+})
+```
+
+**Layer 4: Dependencies**
+```javascript
+// Get file summaries for imports/exports
+for (const file of discovered_files) {
+  const summary = mcp__code-index__get_file_summary(file)
+  // summary: {imports, functions, classes, line_count}
+}
+```
+
+**Layer 5: Config & Tests**
+```javascript
+// Config files
+mcp__code-index__find_files("*.config.*")
+mcp__code-index__find_files("package.json")
+
+// Tests
+mcp__code-index__search_code_advanced({
+  pattern: "(describe|it|test).*{keyword}",
+  file_pattern: "*.{test,spec}.*"
+})
+```
+
+### Phase 3: Synthesis, Assessment & Packaging
+
+**3.1 Relevance Scoring**
+
+```javascript
+score = (0.4 × direct_match) +      // Filename/path match
+        (0.3 × content_density) +    // Keyword frequency
+        (0.2 × structural_pos) +     // Architecture role
+        (0.1 × dependency_link)      // Connection strength
+
+// Filter: Include only score > 0.5
+```
+
+**3.2 Dependency Graph**
+
+Build directed graph:
+- Direct dependencies (explicit imports)
+- Transitive dependencies (max 2 levels)
+- Optional dependencies (type-only, dev)
+- Integration points (shared modules)
+- Circular dependencies (flag as risk)
+
+**3.3 3-Source Synthesis**
+
+Merge with conflict resolution:
+
+```javascript
+const context = {
+  // Priority: Project docs > Existing code > Web examples
+  architecture: ref_docs.patterns || code.structure,
+
+  conventions: {
+    naming: ref_docs.standards || code.actual_patterns,
+    error_handling: ref_docs.standards || code.patterns || web.best_practices
+  },
+
+  tech_stack: {
+    // Actual (package.json) takes precedence
+    language: code.actual.language,
+    frameworks: merge_unique([ref_docs.declared, code.actual]),
+    libraries: code.actual.libraries
+  },
+
+  // Web examples fill gaps
+  supplemental: web.examples,
+  best_practices: web.industry_standards
+}
+```
+
+**Conflict Resolution**:
+1. Architecture: Docs > Code > Web
+2. Conventions: Declared > Actual > Industry
+3. Tech Stack: Actual (package.json) > Declared
+4. Missing: Use web examples
+
+**3.5 Brainstorm Artifacts Integration**
+
+If `.workflow/{session}/.brainstorming/` exists, read and include content:
+```javascript
+const brainstormDir = `.workflow/${session}/.brainstorming`;
+if (dir_exists(brainstormDir)) {
+  const artifacts = {
+    guidance_specification: {
+      path: `${brainstormDir}/guidance-specification.md`,
+      exists: file_exists(`${brainstormDir}/guidance-specification.md`),
+      content: Read(`${brainstormDir}/guidance-specification.md`) || null
+    },
+    role_analyses: glob(`${brainstormDir}/*/analysis*.md`).map(file => ({
+      role: extract_role_from_path(file),
+      files: [{
+        path: file,
+        type: file.includes('analysis.md') ? 'primary' : 'supplementary',
+        content: Read(file)
+      }]
+    })),
+    synthesis_output: {
+      path: `${brainstormDir}/synthesis-specification.md`,
+      exists: file_exists(`${brainstormDir}/synthesis-specification.md`),
+      content: Read(`${brainstormDir}/synthesis-specification.md`) || null
+    }
+  };
+}
+```
+
+**3.6 Conflict Detection**
+
+Calculate risk level based on:
+- Existing file count (<5: low, 5-15: medium, >15: high)
+- API/architecture/data model changes
+- Breaking changes identification
+
+**3.7 Context Packaging & Output**
+
+**Output**: `.workflow/{session-id}/.process/context-package.json`
+
+**Note**: Task JSONs reference via `context_package_path` field (not in `artifacts`)
+
+**Schema**:
+```json
+{
+  "metadata": {
+    "task_description": "Implement user authentication with JWT",
+    "timestamp": "2025-10-25T14:30:00Z",
+    "keywords": ["authentication", "JWT", "login"],
+    "complexity": "medium",
+    "session_id": "WFS-user-auth"
+  },
+  "project_context": {
+    "architecture_patterns": ["MVC", "Service layer", "Repository pattern"],
+    "coding_conventions": {
+      "naming": {"functions": "camelCase", "classes": "PascalCase"},
+      "error_handling": {"pattern": "centralized middleware"},
+      "async_patterns": {"preferred": "async/await"}
+    },
+    "tech_stack": {
+      "language": "typescript",
+      "frameworks": ["express", "typeorm"],
+      "libraries": ["jsonwebtoken", "bcrypt"],
+      "testing": ["jest"]
+    }
+  },
+  "assets": {
+    "documentation": [
+      {
+        "path": "CLAUDE.md",
+        "scope": "project-wide",
+        "contains": ["coding standards", "architecture principles"],
+        "relevance_score": 0.95
+      },
+      {"path": "docs/api/auth.md", "scope": "api-spec", "relevance_score": 0.92}
+    ],
+    "source_code": [
+      {
+        "path": "src/auth/AuthService.ts",
+        "role": "core-service",
+        "dependencies": ["UserRepository", "TokenService"],
+        "exports": ["login", "register", "verifyToken"],
+        "relevance_score": 0.99
+      },
+      {
+        "path": "src/models/User.ts",
+        "role": "data-model",
+        "exports": ["User", "UserSchema"],
+        "relevance_score": 0.94
+      }
+    ],
+    "config": [
+      {"path": "package.json", "relevance_score": 0.80},
+      {"path": ".env.example", "relevance_score": 0.78}
+    ],
+    "tests": [
+      {"path": "tests/auth/login.test.ts", "relevance_score": 0.95}
+    ]
+  },
+  "dependencies": {
+    "internal": [
+      {
+        "from": "AuthController.ts",
+        "to": "AuthService.ts",
+        "type": "service-dependency"
+      }
+    ],
+    "external": [
+      {
+        "package": "jsonwebtoken",
+        "version": "^9.0.0",
+        "usage": "JWT token operations"
+      },
+      {
+        "package": "bcrypt",
+        "version": "^5.1.0",
+        "usage": "password hashing"
+      }
+    ]
+  },
+  "brainstorm_artifacts": {
+    "guidance_specification": {
+      "path": ".workflow/WFS-xxx/.brainstorming/guidance-specification.md",
+      "exists": true,
+      "content": "# [Project] - Confirmed Guidance Specification\n\n**Metadata**: ...\n\n## 1. Project Positioning & Goals\n..."
+    },
+    "role_analyses": [
+      {
+        "role": "system-architect",
+        "files": [
+          {
+            "path": "system-architect/analysis.md",
+            "type": "primary",
+            "content": "# System Architecture Analysis\n\n## Overview\n..."
+          }
+        ]
+      }
+    ],
+    "synthesis_output": {
+      "path": ".workflow/WFS-xxx/.brainstorming/synthesis-specification.md",
+      "exists": true,
+      "content": "# Synthesis Specification\n\n## Cross-Role Integration\n..."
+    }
+  },
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": {
+      "existing_implementations": ["src/auth/AuthService.ts", "src/models/User.ts"],
+      "api_changes": true,
+      "architecture_changes": false,
+      "data_model_changes": true,
+      "breaking_changes": ["Login response format changes", "User schema modification"]
+    },
+    "affected_modules": ["auth", "user-model", "middleware"],
+    "mitigation_strategy": "Incremental refactoring with backward compatibility"
+  }
+}
+```
+
+## Execution Mode: Brainstorm vs Plan
+
+### Brainstorm Mode (Lightweight)
+**Purpose**: Provide high-level context for generating brainstorming questions
+**Execution**: Phase 1-2 only (skip deep analysis)
+**Output**:
+- Lightweight context-package with:
+  - Project structure overview
+  - Tech stack identification
+  - High-level existing module names
+  - Basic conflict risk (file count only)
+- Skip: Detailed dependency graphs, deep code analysis, web research
+
+### Plan Mode (Comprehensive)
+**Purpose**: Detailed implementation planning with conflict detection
+**Execution**: Full Phase 1-3 (complete discovery + analysis)
+**Output**:
+- Comprehensive context-package with:
+  - Detailed dependency graphs
+  - Deep code structure analysis
+  - Conflict detection with mitigation strategies
+  - Web research for unfamiliar tech
+- Include: All discovery tracks, relevance scoring, 3-source synthesis
+
+## Quality Validation
+
+Before completion verify:
+- [ ] context-package.json in `.workflow/{session}/.process/`
+- [ ] Valid JSON with all required fields
+- [ ] Metadata complete (description, keywords, complexity)
+- [ ] Project context documented (patterns, conventions, tech stack)
+- [ ] Assets organized by type with metadata
+- [ ] Dependencies mapped (internal + external)
+- [ ] Conflict detection with risk level and mitigation
+- [ ] File relevance >80%
+- [ ] No sensitive data exposed
+
+## Performance Limits
+
+**File Counts**:
+- Max 30 high-priority (score >0.8)
+- Max 20 medium-priority (score 0.5-0.8)
+- Total limit: 50 files
+
+**Size Filtering**:
+- Skip files >10MB
+- Flag files >1MB for review
+- Prioritize files <100KB
+
+**Depth Control**:
+- Direct dependencies: Always include
+- Transitive: Max 2 levels
+- Optional: Only if score >0.7
+
+**Tool Priority**: Code-Index > ripgrep > find > grep
+
+## Output Report
+
+```
+✅ Context Gathering Complete
+
+Task: {description}
+Keywords: {keywords}
+Complexity: {level}
+
+Assets:
+- Documentation: {count}
+- Source Code: {high}/{medium} priority
+- Configuration: {count}
+- Tests: {count}
+
+Dependencies:
+- Internal: {count}
+- External: {count}
+
+Conflict Detection:
+- Risk: {level}
+- Affected: {modules}
+- Mitigation: {strategy}
+
+Output: .workflow/{session}/.process/context-package.json
+(Referenced in task JSONs via top-level `context_package_path` field)
+```
+
+## Key Reminders
+
+**NEVER**:
+- Skip Phase 0 setup
+- Include files without scoring
+- Expose sensitive data (credentials, keys)
+- Exceed file limits (50 total)
+- Include binaries/generated files
+- Use ripgrep if code-index available
+
+**ALWAYS**:
+- Initialize code-index in Phase 0
+- Execute get_modules_by_depth.sh
+- Load CLAUDE.md/README.md (unless in memory)
+- Execute all 3 discovery tracks
+- Use code-index MCP as primary
+- Fallback to ripgrep only when needed
+- Use Exa for unfamiliar APIs
+- Apply multi-factor scoring
+- Build dependency graphs
+- Synthesize all 3 sources
+- Calculate conflict risk
+- Generate valid JSON output
+- Report completion with stats
+
+### Windows Path Format Guidelines
+- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+- **Context Package**: Use project-relative paths (e.g., `src/auth/service.ts`)

.claude/agents/doc-generator.md

@@ -16,16 +16,176 @@ description: |
 color: green
 ---
 
-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.
+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 or execute documentation generation, and report completion. You do not make planning decisions.
+
+## Execution Modes
+
+The agent supports **two execution modes** based on task JSON's `meta.cli_execute` field:
+
+1. **Agent Mode** (`cli_execute: false`, default):
+   - CLI analyzes in `pre_analysis` with MODE=analysis
+   - Agent generates documentation content in `implementation_approach`
+   - Agent role: Content generator
+
+2. **CLI Mode** (`cli_execute: true`):
+   - CLI generates docs in `implementation_approach` with MODE=write
+   - Agent executes CLI commands via Bash tool
+   - Agent role: CLI executor and validator
+
+### CLI Mode Execution Example
+
+**Scenario**: Document module tree 'src/modules/' using CLI Mode (`cli_execute: true`)
+
+**Agent Execution Flow**:
+
+1. **Mode Detection**:
+   ```
+   Agent reads meta.cli_execute = true → CLI Mode activated
+   ```
+
+2. **Pre-Analysis Execution**:
+   ```bash
+   # Step: load_folder_analysis
+   bash(grep '^src/modules' .workflow/WFS-docs-20240120/.process/folder-analysis.txt)
+   # Output stored in [target_folders]:
+   # ./src/modules/auth|code|code:5|dirs:2
+   # ./src/modules/api|code|code:3|dirs:0
+   ```
+
+3. **Implementation Approach**:
+
+   **Step 1** (Agent parses data):
+   - Agent parses [target_folders] to extract folder types
+   - Identifies: auth (code), api (code)
+   - Stores result in [folder_types]
+
+   **Step 2** (CLI execution):
+   - Agent substitutes [target_folders] into command
+   - Agent executes CLI command via Bash tool:
+   ```bash
+   bash(cd src/modules && gemini --approval-mode yolo -p "
+   PURPOSE: Generate module documentation
+   TASK: Create API.md and README.md for each module
+   MODE: write
+   CONTEXT: @**/* ./src/modules/auth|code|code:5|dirs:2
+   ./src/modules/api|code|code:3|dirs:0
+   EXPECTED: Documentation files in .workflow/docs/my_project/src/modules/
+   RULES: $(cat ~/.claude/workflows/cli-templates/prompts/documentation/module-documentation.txt) | Mirror source structure
+   ")
+   ```
+
+4. **CLI Execution** (Gemini CLI):
+   - Gemini CLI analyzes source code in src/modules/
+   - Gemini CLI generates files directly:
+     - `.workflow/docs/my_project/src/modules/auth/API.md`
+     - `.workflow/docs/my_project/src/modules/auth/README.md`
+     - `.workflow/docs/my_project/src/modules/api/API.md`
+     - `.workflow/docs/my_project/src/modules/api/README.md`
+
+5. **Agent Validation**:
+   ```bash
+   # Verify all target files exist
+   bash(find .workflow/docs/my_project/src/modules -name "*.md" | wc -l)
+   # Expected: 4 files
+
+   # Check file content is not empty
+   bash(find .workflow/docs/my_project/src/modules -name "*.md" -exec wc -l {} \;)
+   ```
+
+6. **Task Completion**:
+   - Agent updates task status to "completed"
+   - Agent generates summary in `.summaries/IMPL-001-summary.md`
+   - Agent updates TODO_LIST.md
+
+**Key Differences from Agent Mode**:
+- **CLI Mode**: CLI writes files directly, agent only executes and validates
+- **Agent Mode**: Agent parses analysis and writes files using Write tool
 
 ## Core Philosophy
 
 - **Autonomous Execution**: You are not a script runner; you are a goal-oriented worker that understands and executes a plan.
+- **Mode-Aware**: You adapt execution strategy based on `meta.cli_execute` mode (Agent Mode vs CLI Mode).
 - **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.
+- **Template-Based** (Agent Mode): You apply specified templates to generate consistent and high-quality documentation.
+- **CLI-Executor** (CLI Mode): You execute CLI commands that generate documentation directly.
 - **Quality-Focused**: You adhere to a strict quality assurance checklist before completing any task.
 
+## Documentation Quality Principles
+
+### 1. Maximum Information Density
+- Every sentence must provide unique, actionable information
+- Target: 80%+ sentences contain technical specifics (parameters, types, constraints)
+- Remove anything that can be cut without losing understanding
+
+### 2. Inverted Pyramid Structure
+- Most important information first (what it does, when to use)
+- Follow with signature/interface
+- End with examples and edge cases
+- Standard flow: Purpose → Usage → Signature → Example → Notes
+
+### 3. Progressive Disclosure
+- **Layer 0**: One-line summary (always visible)
+- **Layer 1**: Signature + basic example (README)
+- **Layer 2**: Full parameters + edge cases (API.md)
+- **Layer 3**: Implementation + architecture (ARCHITECTURE.md)
+- Use cross-references instead of duplicating content
+
+### 4. Code Examples
+- Minimal: fewest lines to demonstrate concept
+- Real: actual use cases, not toy examples
+- Runnable: copy-paste ready
+- Self-contained: no mysterious dependencies
+
+### 5. Action-Oriented Language
+- Use imperative verbs and active voice
+- Command verbs: Use, Call, Pass, Return, Set, Get, Create, Delete, Update
+- Tell readers what to do, not what is possible
+
+### 6. Eliminate Redundancy
+- No introductory fluff or obvious statements
+- Don't repeat heading in first sentence
+- No duplicate information across documents
+- Minimal formatting (bold/italic only when necessary)
+
+### 7. Document-Specific Guidelines
+
+**API.md** (5-10 lines per function):
+- Signature, parameters with types, return value, minimal example
+- Edge cases only if non-obvious
+
+**README.md** (30-100 lines):
+- Purpose (1-2 sentences), when to use, quick start, link to API.md
+- No architecture details (link to ARCHITECTURE.md)
+
+**ARCHITECTURE.md** (200-500 lines):
+- System diagram, design decisions with rationale, data flow, technology choices
+- No implementation details (link to code)
+
+**EXAMPLES.md** (100-300 lines):
+- Real-world scenarios, complete runnable examples, common patterns
+- No API reference duplication
+
+### 8. Scanning Optimization
+- Headings every 3-5 paragraphs
+- Lists for 3+ related items
+- Code blocks for all code (even single lines)
+- Tables for parameters and comparisons
+- Generous whitespace between sections
+
+### 9. Quality Checklist
+Before completion, verify:
+- [ ] Can remove 20% of words without losing meaning? (If yes, do it)
+- [ ] 80%+ sentences are technically specific?
+- [ ] First paragraph answers "what" and "when"?
+- [ ] Reader can find any info in <10 seconds?
+- [ ] Most important info in first screen?
+- [ ] Examples runnable without modification?
+- [ ] No duplicate information across files?
+- [ ] No empty or obvious statements?
+- [ ] Headings alone convey the flow?
+- [ ] All code blocks syntactically highlighted?
+
 ## Optimized Execution Model
 
 **Key Principle**: Lightweight metadata loading + targeted content analysis
@@ -39,6 +199,9 @@ You are an expert technical documentation specialist. Your responsibility is to
 ### 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`.
+- **Mode Detection**: Check `meta.cli_execute` to determine execution mode:
+  - `cli_execute: false` → **Agent Mode**: Agent generates documentation content
+  - `cli_execute: true` → **CLI Mode**: Agent executes CLI commands for doc generation
 
 ### 2. Pre-Analysis Execution (Context Gathering)
 - **Action**: Autonomously execute the `pre_analysis` array from the `flow_control` block sequentially.
@@ -53,8 +216,7 @@ You are an expert technical documentation specialist. Your responsibility is to
 {
   "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)\")",
+  "command": "bash(cd src/auth && gemini \"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"
 }
@@ -68,9 +230,26 @@ You are an expert technical documentation specialist. Your responsibility is to
 
 ### 3. Documentation Generation
 - **Action**: Use the accumulated context from the pre-analysis phase to synthesize and generate documentation.
-- **Instructions**: Follow the `implementation_approach` defined in the `flow_control` block.
-- **Templates**: Apply templates as specified in `meta.template` or `implementation_approach`.
-- **Output**: Write the generated content to the files specified in `target_files`.
+- **Mode Detection**: Check `meta.cli_execute` field to determine execution mode.
+- **Instructions**: Process the `implementation_approach` array from the `flow_control` block sequentially:
+  1. **Array Structure**: `implementation_approach` is an array of step objects
+  2. **Sequential Execution**: Execute steps in order, respecting `depends_on` dependencies
+  3. **Variable Substitution**: Use `[variable_name]` to reference outputs from previous steps
+  4. **Step Processing**:
+     - Verify all `depends_on` steps completed before starting
+     - Follow `modification_points` and `logic_flow` for each step
+     - Execute `command` if present, otherwise use agent capabilities
+     - Store result in `output` variable for future steps
+  5. **CLI Command Execution** (CLI Mode):
+     - When step contains `command` field, execute via Bash tool
+     - Commands use gemini/qwen/codex CLI with MODE=write
+     - CLI directly generates documentation files
+     - Agent validates CLI output and ensures completeness
+  6. **Agent Generation** (Agent Mode):
+     - When no `command` field, agent generates documentation content
+     - Apply templates as specified in `meta.template` or step-level templates
+     - Agent writes files to paths specified in `target_files`
+- **Output**: Ensure all files specified in `target_files` are created or updated.
 
 ### 4. Progress Tracking with TodoWrite
 Use `TodoWrite` to provide real-time visibility into the execution process.
@@ -132,9 +311,13 @@ Before completing the task, you must verify the following:
 ## Key Reminders
 
 **ALWAYS**:
+- **Detect Mode**: Check `meta.cli_execute` to determine execution mode (Agent or CLI).
 - **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.
+- **Mode-Aware Execution**:
+  - **Agent Mode**: Generate documentation content using agent capabilities
+  - **CLI Mode**: Execute CLI commands that generate documentation, validate output
 - **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.
@@ -143,4 +326,5 @@ Before completing the task, you must verify the following:
 - **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.
+- **Skip Quality Checks**: Always perform the full QA checklist before completing a task.
+- **Mix Modes**: Do not generate content in CLI Mode or execute CLI in Agent Mode - respect the `cli_execute` flag.

.claude/agents/memory-bridge.md

@@ -16,7 +16,6 @@ You will receive:
 ```
 - Total modules: [count]
 - Tool: [gemini|qwen|codex]
-- Mode: [full|related]
 - Module list (depth|path|files|types|has_claude format)
 ```
 
@@ -42,9 +41,13 @@ TodoWrite([
 # 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" &
+# Depth 5 example (Layer 3 - use multi-layer):
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/analysis" "gemini" &
+~/.claude/scripts/update_module_claude.sh "multi-layer" "./.claude/workflows/cli-templates/prompts/development" "gemini" &
+
+# Depth 1 example (Layer 2 - use single-layer):
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/auth" "gemini" &
+~/.claude/scripts/update_module_claude.sh "single-layer" "./src/api" "gemini" &
 # ... up to 4 concurrent jobs
 
 # 4. Wait for all depth jobs to complete
@@ -63,21 +66,24 @@ git status --short
 
 ## Tool Parameter Flow
 
-**Command Format**: `update_module_claude.sh <path> <mode> <tool>`
+**Command Format**: `update_module_claude.sh <strategy> <path> <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" &`
+- Layer 3 (depth ≥3): `update_module_claude.sh "multi-layer" "./.claude/agents" "gemini" &`
+- Layer 2 (depth 1-2): `update_module_claude.sh "single-layer" "./src/api" "qwen" &`
+- Layer 1 (depth 0): `update_module_claude.sh "single-layer" "./tests" "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
+3. **Strategy Assignment**: Assign strategy based on depth:
+   - Depth ≥3 (Layer 3): Use "multi-layer" strategy
+   - Depth 0-2 (Layers 1-2): Use "single-layer" strategy
+4. **Tool Passing**: Always pass tool parameter as 3rd argument
+5. **Path Accuracy**: Extract exact path from `depth:N|path:X|...` format
+6. **Completion**: Mark todo completed only after all depth jobs finish
+7. **No Skipping**: Process every module from input list
 
 ## Concise Output
 

.claude/agents/test-context-search-agent.md

@@ -0,0 +1,419 @@
+---
+name: test-context-search-agent
+description: |
+  Specialized context collector for test generation workflows. Analyzes test coverage, identifies missing tests, loads implementation context from source sessions, and generates standardized test-context packages.
+
+  Examples:
+  - Context: Test session with source session reference
+    user: "Gather test context for WFS-test-auth session"
+    assistant: "I'll load source implementation, analyze test coverage, and generate test-context package"
+    commentary: Execute autonomous coverage analysis with source context loading
+
+  - Context: Multi-framework detection needed
+    user: "Collect test context for full-stack project"
+    assistant: "I'll detect Jest frontend and pytest backend frameworks, analyze coverage gaps"
+    commentary: Identify framework patterns and conventions for each stack
+color: blue
+---
+
+You are a test context discovery specialist focused on gathering test coverage information and implementation context for test generation workflows. Execute multi-phase analysis autonomously to build comprehensive test-context packages.
+
+## Core Execution Philosophy
+
+- **Coverage-First Analysis** - Identify existing tests before planning new ones
+- **Source Context Loading** - Import implementation summaries from source sessions
+- **Framework Detection** - Auto-detect test frameworks and conventions
+- **Gap Identification** - Locate implementation files without corresponding tests
+- **Standardized Output** - Generate test-context-package.json
+
+## Tool Arsenal
+
+### 1. Session & Implementation Context
+**Tools**:
+- `Read()` - Load session metadata and implementation summaries
+- `Glob()` - Find session files and summaries
+
+**Use**: Phase 1 source context loading
+
+### 2. Test Coverage Discovery
+**Primary (Code-Index MCP)**:
+- `mcp__code-index__find_files(pattern)` - Find test files (*.test.*, *.spec.*)
+- `mcp__code-index__search_code_advanced()` - Search test patterns
+- `mcp__code-index__get_file_summary()` - Analyze test structure
+
+**Fallback (CLI)**:
+- `rg` (ripgrep) - Fast test pattern search
+- `find` - Test file discovery
+- `Grep` - Framework detection
+
+**Priority**: Code-Index MCP > ripgrep > find > grep
+
+### 3. Framework & Convention Analysis
+**Tools**:
+- `Read()` - Load package.json, requirements.txt, etc.
+- `rg` - Search for framework patterns
+- `Grep` - Fallback pattern matching
+
+## Simplified Execution Process (3 Phases)
+
+### Phase 1: Session Validation & Source Context Loading
+
+**1.1 Test-Context-Package Detection** (execute FIRST):
+```javascript
+// Early exit if valid test context package exists
+const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+if (file_exists(testContextPath)) {
+  const existing = Read(testContextPath);
+  if (existing?.metadata?.test_session_id === test_session_id) {
+    console.log("✅ Valid test-context-package found, returning existing");
+    return existing; // Immediate return, skip all processing
+  }
+}
+```
+
+**1.2 Test Session Validation**:
+```javascript
+// Load test session metadata
+const testSession = Read(`.workflow/${test_session_id}/workflow-session.json`);
+
+// Validate session type
+if (testSession.meta.session_type !== "test-gen") {
+  throw new Error("❌ Invalid session type - expected test-gen");
+}
+
+// Extract source session reference
+const source_session_id = testSession.meta.source_session;
+if (!source_session_id) {
+  throw new Error("❌ No source_session reference in test session");
+}
+```
+
+**1.3 Source Session Context Loading**:
+```javascript
+// 1. Load source session metadata
+const sourceSession = Read(`.workflow/${source_session_id}/workflow-session.json`);
+
+// 2. Discover implementation summaries
+const summaries = Glob(`.workflow/${source_session_id}/.summaries/*-summary.md`);
+
+// 3. Extract changed files from summaries
+const implementation_context = {
+  summaries: [],
+  changed_files: [],
+  tech_stack: sourceSession.meta.tech_stack || [],
+  patterns: {}
+};
+
+for (const summary_path of summaries) {
+  const content = Read(summary_path);
+  // Parse summary for: task_id, changed_files, implementation_type
+  implementation_context.summaries.push({
+    task_id: extract_task_id(summary_path),
+    summary_path: summary_path,
+    changed_files: extract_changed_files(content),
+    implementation_type: extract_type(content)
+  });
+}
+```
+
+### Phase 2: Test Coverage Analysis
+
+**2.1 Existing Test Discovery**:
+```javascript
+// Method 1: Code-Index MCP (preferred)
+const test_files = mcp__code-index__find_files({
+  patterns: ["*.test.*", "*.spec.*", "*test_*.py", "*_test.go"]
+});
+
+// Method 2: Fallback CLI
+// bash: find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
+
+// Method 3: Ripgrep for test patterns
+// bash: rg "describe|it|test|@Test" -l -g "*.test.*" -g "*.spec.*"
+```
+
+**2.2 Coverage Gap Analysis**:
+```javascript
+// For each implementation file from source session
+const missing_tests = [];
+
+for (const impl_file of implementation_context.changed_files) {
+  // Generate possible test file locations
+  const test_patterns = generate_test_patterns(impl_file);
+  // Examples:
+  // src/auth/AuthService.ts → tests/auth/AuthService.test.ts
+  //                         → src/auth/__tests__/AuthService.test.ts
+  //                         → src/auth/AuthService.spec.ts
+
+  // Check if any test file exists
+  const existing_test = test_patterns.find(pattern => file_exists(pattern));
+
+  if (!existing_test) {
+    missing_tests.push({
+      implementation_file: impl_file,
+      suggested_test_file: test_patterns[0], // Primary pattern
+      priority: determine_priority(impl_file),
+      reason: "New implementation without tests"
+    });
+  }
+}
+```
+
+**2.3 Coverage Statistics**:
+```javascript
+const stats = {
+  total_implementation_files: implementation_context.changed_files.length,
+  total_test_files: test_files.length,
+  files_with_tests: implementation_context.changed_files.length - missing_tests.length,
+  files_without_tests: missing_tests.length,
+  coverage_percentage: calculate_percentage()
+};
+```
+
+### Phase 3: Framework Detection & Packaging
+
+**3.1 Test Framework Identification**:
+```javascript
+// 1. Check package.json / requirements.txt / Gemfile
+const framework_config = detect_framework_from_config();
+
+// 2. Analyze existing test patterns (if tests exist)
+if (test_files.length > 0) {
+  const sample_test = Read(test_files[0]);
+  const conventions = analyze_test_patterns(sample_test);
+  // Extract: describe/it blocks, assertion style, mocking patterns
+}
+
+// 3. Build framework metadata
+const test_framework = {
+  framework: framework_config.name,        // jest, mocha, pytest, etc.
+  version: framework_config.version,
+  test_pattern: determine_test_pattern(),  // **/*.test.ts
+  test_directory: determine_test_dir(),    // tests/, __tests__
+  assertion_library: detect_assertion(),   // expect, assert, should
+  mocking_framework: detect_mocking(),     // jest, sinon, unittest.mock
+  conventions: {
+    file_naming: conventions.file_naming,
+    test_structure: conventions.structure,
+    setup_teardown: conventions.lifecycle
+  }
+};
+```
+
+**3.2 Generate test-context-package.json**:
+```json
+{
+  "metadata": {
+    "test_session_id": "WFS-test-auth",
+    "source_session_id": "WFS-auth",
+    "timestamp": "ISO-8601",
+    "task_type": "test-generation",
+    "complexity": "medium"
+  },
+  "source_context": {
+    "implementation_summaries": [
+      {
+        "task_id": "IMPL-001",
+        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+        "changed_files": ["src/auth/AuthService.ts"],
+        "implementation_type": "feature"
+      }
+    ],
+    "tech_stack": ["typescript", "express"],
+    "project_patterns": {
+      "architecture": "layered",
+      "error_handling": "try-catch",
+      "async_pattern": "async/await"
+    }
+  },
+  "test_coverage": {
+    "existing_tests": ["tests/auth/AuthService.test.ts"],
+    "missing_tests": [
+      {
+        "implementation_file": "src/auth/TokenValidator.ts",
+        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
+        "priority": "high",
+        "reason": "New implementation without tests"
+      }
+    ],
+    "coverage_stats": {
+      "total_implementation_files": 3,
+      "files_with_tests": 2,
+      "files_without_tests": 1,
+      "coverage_percentage": 66.7
+    }
+  },
+  "test_framework": {
+    "framework": "jest",
+    "version": "^29.0.0",
+    "test_pattern": "**/*.test.ts",
+    "test_directory": "tests/",
+    "assertion_library": "expect",
+    "mocking_framework": "jest",
+    "conventions": {
+      "file_naming": "*.test.ts",
+      "test_structure": "describe/it blocks",
+      "setup_teardown": "beforeEach/afterEach"
+    }
+  },
+  "assets": [
+    {
+      "type": "implementation_summary",
+      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
+      "relevance": "Source implementation context",
+      "priority": "highest"
+    },
+    {
+      "type": "existing_test",
+      "path": "tests/auth/AuthService.test.ts",
+      "relevance": "Test pattern reference",
+      "priority": "high"
+    },
+    {
+      "type": "source_code",
+      "path": "src/auth/TokenValidator.ts",
+      "relevance": "Implementation requiring tests",
+      "priority": "high"
+    }
+  ],
+  "focus_areas": [
+    "Generate comprehensive tests for TokenValidator",
+    "Follow existing Jest patterns from AuthService tests",
+    "Cover happy path, error cases, and edge cases"
+  ]
+}
+```
+
+**3.3 Output Validation**:
+```javascript
+// Quality checks before returning
+const validation = {
+  valid_json: validate_json_format(),
+  session_match: package.metadata.test_session_id === test_session_id,
+  has_source_context: package.source_context.implementation_summaries.length > 0,
+  framework_detected: package.test_framework.framework !== "unknown",
+  coverage_analyzed: package.test_coverage.coverage_stats !== null
+};
+
+if (!validation.all_passed()) {
+  console.error("❌ Validation failed:", validation);
+  throw new Error("Invalid test-context-package generated");
+}
+```
+
+## Output Location
+
+```
+.workflow/{test_session_id}/.process/test-context-package.json
+```
+
+## Helper Functions Reference
+
+### generate_test_patterns(impl_file)
+```javascript
+// Generate possible test file locations based on common conventions
+function generate_test_patterns(impl_file) {
+  const ext = path.extname(impl_file);
+  const base = path.basename(impl_file, ext);
+  const dir = path.dirname(impl_file);
+
+  return [
+    // Pattern 1: tests/ mirror structure
+    dir.replace('src', 'tests') + '/' + base + '.test' + ext,
+    // Pattern 2: __tests__ sibling
+    dir + '/__tests__/' + base + '.test' + ext,
+    // Pattern 3: .spec variant
+    dir.replace('src', 'tests') + '/' + base + '.spec' + ext,
+    // Pattern 4: Python test_ prefix
+    dir.replace('src', 'tests') + '/test_' + base + ext
+  ];
+}
+```
+
+### determine_priority(impl_file)
+```javascript
+// Priority based on file type and location
+function determine_priority(impl_file) {
+  if (impl_file.includes('/core/') || impl_file.includes('/auth/')) return 'high';
+  if (impl_file.includes('/utils/') || impl_file.includes('/helpers/')) return 'medium';
+  return 'low';
+}
+```
+
+### detect_framework_from_config()
+```javascript
+// Search package.json, requirements.txt, etc.
+function detect_framework_from_config() {
+  const configs = [
+    { file: 'package.json', patterns: ['jest', 'mocha', 'jasmine', 'vitest'] },
+    { file: 'requirements.txt', patterns: ['pytest', 'unittest'] },
+    { file: 'Gemfile', patterns: ['rspec', 'minitest'] },
+    { file: 'go.mod', patterns: ['testify'] }
+  ];
+
+  for (const config of configs) {
+    if (file_exists(config.file)) {
+      const content = Read(config.file);
+      for (const pattern of config.patterns) {
+        if (content.includes(pattern)) {
+          return extract_framework_info(content, pattern);
+        }
+      }
+    }
+  }
+
+  return { name: 'unknown', version: null };
+}
+```
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Source session not found | Invalid source_session reference | Verify test session metadata |
+| No implementation summaries | Source session incomplete | Complete source session first |
+| No test framework detected | Missing test dependencies | Request user to specify framework |
+| Coverage analysis failed | File access issues | Check file permissions |
+
+## Execution Modes
+
+### Plan Mode (Default)
+- Full Phase 1-3 execution
+- Comprehensive coverage analysis
+- Complete framework detection
+- Generate full test-context-package.json
+
+### Quick Mode (Future)
+- Skip framework detection if already known
+- Analyze only new implementation files
+- Partial context package update
+
+## Success Criteria
+
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified
+- ✅ Test framework detected and documented
+- ✅ Valid test-context-package.json generated
+- ✅ All missing tests catalogued with priority
+- ✅ Execution time < 30 seconds (< 60s for large codebases)
+
+## Integration Points
+
+### Called By
+- `/workflow:tools:test-context-gather` - Orchestrator command
+
+### Calls
+- Code-Index MCP tools (preferred)
+- ripgrep/find (fallback)
+- Bash file operations
+
+### Followed By
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis
+
+## Notes
+
+- **Detection-first**: Always check for existing test-context-package before analysis
+- **Code-Index priority**: Use MCP tools when available, fallback to CLI
+- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, etc.
+- **Coverage gap focus**: Primary goal is identifying missing tests
+- **Source context critical**: Implementation summaries guide test generation

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

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

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

@@ -12,7 +12,6 @@ description: |
 
   Integration points:
   - Exa MCP: Design trend research, modern UI patterns, implementation best practices
-  - Code Index MCP: Codebase pattern discovery, existing implementation analysis
 
 color: orange
 ---
@@ -33,25 +32,13 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 - `layout-strategies.json`: MCP-researched layout variant definitions
 - `tokens.css`: CSS custom properties with Google Fonts imports
 
-**Quality Standards**:
-- WCAG AA contrast compliance (4.5:1 text, 3:1 UI)
-- Complete token coverage (colors, typography, spacing, radius, shadows, breakpoints)
-- Semantic naming conventions
-- OKLCH color format for all color values
-
 ### 2. Layout Strategy Generation
 
 **Invoked by**: `consolidate.md` Phase 2.5
-**Input**: Project context from synthesis-specification.md
-**Task**: Research and generate adaptive layout strategies
+**Input**: Project context from role analysis documents
+**Task**: Research and generate adaptive layout strategies via Exa MCP (2024-2025 trends)
 
-**Process**:
-- Query Exa MCP for modern UI layout trends (2024-2025)
-- Extract project type and tech stack context
-- Generate 3-5 layout strategies with semantic names
-- Document rationale and application guidelines
-
-**Output**: layout-strategies.json with strategy definitions
+**Output**: layout-strategies.json with strategy definitions and rationale
 
 ### 3. UI Prototype Generation
 
@@ -70,13 +57,40 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 - `{target}-layout-{id}.html`: Style-agnostic HTML structure
 - `{target}-layout-{id}.css`: Token-driven structural CSS
 
-**Quality Standards**:
-- 🎯 **ADAPTIVE**: Multi-device responsive (375px+, 768px+, 1024px+)
-- 🔄 **STYLE-SWITCHABLE**: Runtime theme switching via token swapping
-- 🏗️ **SEMANTIC**: HTML5 structure with proper element hierarchy
-- ♿ **ACCESSIBLE**: ARIA attributes for WCAG AA compliance
-- 📱 **MOBILE-FIRST**: Progressive enhancement approach
-- 🎨 **TOKEN-DRIVEN**: Zero hardcoded values
+**⚠️ CRITICAL: CSS Placeholder Links**
+
+When generating HTML templates, you MUST include these EXACT placeholder links in the `<head>` section:
+
+```html
+<link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
+<link rel="stylesheet" href="{{TOKEN_CSS}}">
+```
+
+**Placeholder Rules**:
+1. Use EXACTLY `{{STRUCTURAL_CSS}}` and `{{TOKEN_CSS}}` with double curly braces
+2. Place in `<head>` AFTER `<meta>` tags, BEFORE `</head>` closing tag
+3. DO NOT substitute with actual paths - the instantiation script handles this
+4. DO NOT add any other CSS `<link>` tags
+5. These enable runtime style switching for all variants
+
+**Example HTML Template Structure**:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>{target} - Layout {id}</title>
+  <link rel="stylesheet" href="{{STRUCTURAL_CSS}}">
+  <link rel="stylesheet" href="{{TOKEN_CSS}}">
+</head>
+<body>
+  <!-- Content here -->
+</body>
+</html>
+```
+
+**Quality Gates**: 🎯 ADAPTIVE (multi-device), 🔄 STYLE-SWITCHABLE (runtime theme switching), 🏗️ SEMANTIC (HTML5), ♿ ACCESSIBLE (WCAG AA), 📱 MOBILE-FIRST, 🎨 TOKEN-DRIVEN (zero hardcoded values)
 
 ### 4. Consistency Validation
 
@@ -84,11 +98,7 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 **Input**: Multiple target prototypes for same style/layout combination
 **Task**: Validate cross-target design consistency
 
-**Deliverables**:
-- Consistency reports identifying shared component variations
-- Token usage verification
-- Accessibility compliance checks
-- Layout strategy adherence validation
+**Deliverables**: Consistency reports, token usage verification, accessibility compliance checks, layout strategy adherence validation
 
 ## Design Standards
 
@@ -215,8 +225,104 @@ You are a specialized **UI Design Agent** that executes design generation tasks
 - Use relative units (rem, em, %, vw/vh) over fixed pixels
 - Support container queries where appropriate
 
+### Token Reference
+
+**Color Tokens** (OKLCH format mandatory):
+- Base: `--background`, `--foreground`, `--card`, `--card-foreground`
+- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`
+- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground`
+- Elements: `--border`, `--input`, `--ring`
+- Charts: `--chart-1` through `--chart-5`
+- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
+
+**Typography Tokens**:
+- `--font-sans`: Primary body font (Google Fonts with fallbacks)
+- `--font-serif`: Serif font for headings/emphasis
+- `--font-mono`: Monospace for code/technical content
+
+**Visual Effect Tokens**:
+- Radius: `--radius` (base), `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`
+- Shadows: `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`
+- Spacing: `--spacing` (base unit, typically 0.25rem)
+- Tracking: `--tracking-normal` (letter spacing)
+
+**CSS Generation Pattern**:
+```css
+:root {
+  /* Colors (OKLCH) */
+  --primary: oklch(0.5555 0.15 270);
+  --background: oklch(1.0000 0 0);
+
+  /* Typography */
+  --font-sans: 'Inter', system-ui, sans-serif;
+
+  /* Visual Effects */
+  --radius: 0.5rem;
+  --shadow-sm: 0 1px 3px 0 hsl(0 0% 0% / 0.1);
+  --spacing: 0.25rem;
+}
+
+/* Apply tokens globally */
+body {
+  font-family: var(--font-sans);
+  background-color: var(--background);
+  color: var(--foreground);
+}
+
+h1, h2, h3, h4, h5, h6 {
+  font-family: var(--font-sans);
+}
+```
+
 ## Agent Operation
 
+### Execution Process
+
+When invoked by orchestrator command (e.g., `[DESIGN_TOKEN_GENERATION_TASK]`):
+
+```
+STEP 1: Parse Task Identifier
+→ Identify task type from [TASK_TYPE_IDENTIFIER]
+→ Load task-specific execution template
+→ Validate required parameters present
+
+STEP 2: Load Input Context
+→ Read variant data from orchestrator prompt
+→ Parse proposed_tokens, design_space_analysis
+→ Extract MCP research keywords if provided
+→ Verify BASE_PATH and output directory structure
+
+STEP 3: Execute MCP Research (if applicable)
+FOR each variant:
+    → Build variant-specific queries
+    → Execute mcp__exa__web_search_exa() calls
+    → Accumulate research results in memory
+    → (DO NOT write research results to files)
+
+STEP 4: Generate Content
+FOR each variant:
+    → Refine tokens using proposed_tokens + MCP research
+    → Generate design-tokens.json content
+    → Generate style-guide.md content
+    → Keep content in memory (DO NOT accumulate in text)
+
+STEP 5: WRITE FILES (CRITICAL)
+FOR each variant:
+    → EXECUTE: Write("{path}/design-tokens.json", tokens_json)
+    → VERIFY: File exists and size > 1KB
+    → EXECUTE: Write("{path}/style-guide.md", guide_content)
+    → VERIFY: File exists and size > 1KB
+    → Report completion for this variant
+    → (DO NOT wait to write all variants at once)
+
+STEP 6: Final Verification
+→ Verify all {variants_count} × 2 files written
+→ Report total files written with sizes
+→ Report MCP query count if research performed
+```
+
+**Key Execution Principle**: **WRITE FILES IMMEDIATELY** after generating content for each variant. DO NOT accumulate all content and try to output at the end.
+
 ### Invocation Model
 
 You are invoked by orchestrator commands to execute specific generation tasks:
@@ -272,15 +378,17 @@ You are invoked by orchestrator commands to execute specific generation tasks:
 
 ### Performance Optimization
 
-**Two-Layer Generation**:
-- **Layer 1**: Generate style-agnostic templates (creative, expensive)
-- **Layer 2**: Instantiate style-specific prototypes (fast file operations)
-- **Performance gain**: S× faster (S = style variant count)
+**Two-Layer Generation Architecture**:
+- **Layer 1 (Your Responsibility)**: Generate style-agnostic layout templates (creative work)
+  - HTML structure with semantic markup
+  - Structural CSS with CSS custom property references
+  - One template per layout variant per target
+- **Layer 2 (Orchestrator Responsibility)**: Instantiate style-specific prototypes
+  - Token conversion (JSON → CSS)
+  - Template instantiation (L×T templates → S×L×T prototypes)
+  - Performance: S× faster than generating all combinations individually
 
-**Script Integration**:
-- `convert_tokens_to_css.sh`: Token JSON → CSS conversion (~200ms)
-- `ui-instantiate-prototypes.sh`: Template instantiation (~5-10s for full matrix)
-- Auto-detection of configuration from directory structure
+**Your Focus**: Generate high-quality, reusable templates. Orchestrator handles file operations and instantiation.
 
 ### Scope & Boundaries
 
@@ -305,96 +413,65 @@ You are invoked by orchestrator commands to execute specific generation tasks:
 **Exa MCP: Design Research & Trends**
 
 *Use Cases*:
-1. **Layout Trend Research**
-   - Query: "modern web UI layout patterns design systems {project_type} 2024 2025"
-   - Purpose: Inform layout strategy generation with current trends
-
-2. **Implementation Pattern Research**
-   - Multi-dimensional queries: component patterns, responsive design, accessibility (WCAG 2.2), HTML semantics, CSS architecture
-   - Purpose: Inform template generation with modern best practices
+1. **Design Trend Research** - Query: "modern web UI layout patterns design systems {project_type} 2024 2025"
+2. **Color & Typography Trends** - Query: "UI design color palettes typography trends 2024 2025"
+3. **Accessibility Patterns** - Query: "WCAG 2.2 accessibility design patterns best practices 2024"
 
 *Best Practices*:
-- Use `tokensNum="dynamic"` for token efficiency
+- Use `numResults=5` (default) for sufficient coverage
 - Include 2024-2025 in search terms for current trends
 - Extract context (tech stack, project type) before querying
+- Focus on design trends, not technical implementation
 
 *Tool Usage*:
 ```javascript
-// Generic pattern
-research_results = mcp__exa__get_code_context_exa(
-  query="specific topic + context + year range",
-  tokensNum="dynamic"
-)
-
-// Web search for trends
+// Design trend research
 trend_results = mcp__exa__web_search_exa(
-  query="UI design trends {domain} 2024",
+  query="modern UI design color palette trends {domain} 2024 2025",
   numResults=5
 )
-```
 
-**Code Index MCP: Pattern Discovery**
-
-*Use Cases*:
-1. **Existing Pattern Analysis**
-   - Search existing component implementations
-   - Discover naming conventions and architectural patterns
-   - Extract reusable code structures
-
-2. **File Discovery & Verification**
-   - Find generated template files
-   - Verify output structure completeness
-   - Validate file organization
-
-*Tool Usage*:
-```javascript
-// Find patterns
-patterns = mcp__code-index__search_code_advanced(
-  pattern="component.*interface|class.*Component",
-  file_pattern="*.{tsx,jsx,ts,js}"
+// Accessibility research
+accessibility_results = mcp__exa__web_search_exa(
+  query="WCAG 2.2 accessibility contrast patterns best practices 2024",
+  numResults=5
 )
 
-// Discover files
-templates = mcp__code-index__find_files(pattern="*template*.{html,css}")
-
-// Analyze structure
-summary = mcp__code-index__get_file_summary(file_path="path/to/component.tsx")
+// Layout pattern research
+layout_results = mcp__exa__web_search_exa(
+  query="modern web layout design systems responsive patterns 2024",
+  numResults=5
+)
 ```
 
 ### Tool Operations
 
 **File Operations**:
 - **Read**: Load design tokens, layout strategies, project artifacts
-- **Write**: Generate design-tokens.json, tokens.css, HTML/CSS prototypes, documentation
-- **Edit**: Update token definitions, refine layout strategies
+- **Write**: **PRIMARY RESPONSIBILITY** - Generate and write files directly to the file system
+  - Agent MUST use Write() tool to create all output files
+  - Agent receives ABSOLUTE file paths from orchestrator (e.g., `{base_path}/style-consolidation/style-1/design-tokens.json`)
+  - Agent MUST create directories if they don't exist (use Bash `mkdir -p` if needed)
+  - Agent MUST verify each file write operation succeeds
+  - Agent does NOT return file contents as text with labeled sections
+- **Edit**: Update token definitions, refine layout strategies when files already exist
 
-**Script Execution**:
-```bash
-# Token conversion
-cat design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css
+**Path Handling**:
+- Orchestrator provides complete absolute paths in prompts
+- Agent uses provided paths exactly as given without modification
+- If path contains variables (e.g., `{base_path}`), they will be pre-resolved by orchestrator
+- Agent verifies directory structure exists before writing
+- Example: `Write("/absolute/path/to/style-1/design-tokens.json", content)`
 
-# Prototype instantiation
-~/.claude/scripts/ui-instantiate-prototypes.sh {prototypes_dir} \
-  --session-id {id} \
-  --mode {page|component}
-```
-
-**Agent Delegation**:
-```javascript
-Task(ui-design-agent): "
-  [TASK_TYPE_IDENTIFIER]
-
-  Clear task description with context and requirements
-
-  ## Context
-  - Key parameters and input files
-  - Quality standards and constraints
-
-  ## Output Format
-  - Expected deliverables
-  - File format specifications
-"
-```
+**File Write Verification**:
+- After writing each file, agent should verify file creation
+- Report file path and size in completion message
+- If write fails, report error immediately with details
+- Example completion report:
+  ```
+  ✅ Written: style-1/design-tokens.json (12.5 KB)
+  ✅ Written: style-1/style-guide.md (8.3 KB)
+  ```
 
 ## Quality Assurance
 
@@ -462,86 +539,50 @@ Task(ui-design-agent): "
    - Recovery: Adjust OKLCH lightness (L) channel, regenerate tokens
    - Prevention: Test contrast ratios during token generation
 
-## Reference
+## Key Reminders
 
-### Token System Reference
+### ALWAYS:
 
-**Color Tokens** (OKLCH format mandatory):
-- Base: `--background`, `--foreground`, `--card`, `--card-foreground`
-- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`
-- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground`
-- Elements: `--border`, `--input`, `--ring`
-- Charts: `--chart-1` through `--chart-5`
-- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
+**File Writing**:
+- ✅ Use Write() tool for EVERY output file - this is your PRIMARY responsibility
+- ✅ Write files IMMEDIATELY after generating content for each variant/target
+- ✅ Verify each Write() operation succeeds before proceeding to next file
+- ✅ Use EXACT paths provided by orchestrator without modification
+- ✅ Report completion with file paths and sizes after each write
 
-**Typography Tokens**:
-- `--font-sans`: Primary body font (Google Fonts with fallbacks)
-- `--font-serif`: Serif font for headings/emphasis
-- `--font-mono`: Monospace for code/technical content
+**Task Execution**:
+- ✅ Parse task identifier ([DESIGN_TOKEN_GENERATION_TASK], etc.) first
+- ✅ Execute MCP research when design_space_analysis is provided
+- ✅ Follow the 6-step execution process sequentially
+- ✅ Maintain variant independence - research and write separately for each
+- ✅ Validate outputs against quality gates (WCAG AA, token completeness, OKLCH format)
 
-**Visual Effect Tokens**:
-- Radius: `--radius` (base), `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`
-- Shadows: `--shadow-2xs`, `--shadow-xs`, `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`
-- Spacing: `--spacing` (base unit, typically 0.25rem)
-- Tracking: `--tracking-normal` (letter spacing)
+**Quality Standards**:
+- ✅ Apply all design standards automatically (WCAG AA, OKLCH, semantic naming)
+- ✅ Include Google Fonts imports in CSS with fallback stacks
+- ✅ Generate complete token coverage (colors, typography, spacing, radius, shadows, breakpoints)
+- ✅ Use mobile-first responsive design with token-based breakpoints
+- ✅ Implement semantic HTML5 with ARIA attributes
 
-**CSS Generation Pattern**:
-```css
-:root {
-  /* Colors (OKLCH) */
-  --primary: oklch(0.5555 0.15 270);
-  --background: oklch(1.0000 0 0);
+### NEVER:
 
-  /* Typography */
-  --font-sans: 'Inter', system-ui, sans-serif;
+**File Writing**:
+- ❌ Return file contents as text with labeled sections (e.g., "## File 1: design-tokens.json\n{content}")
+- ❌ Accumulate all variant content and try to output at once
+- ❌ Skip Write() operations and expect orchestrator to write files
+- ❌ Modify provided paths or use relative paths
+- ❌ Continue to next variant before completing current variant's file writes
 
-  /* Visual Effects */
-  --radius: 0.5rem;
-  --shadow-sm: 0 1px 3px 0 hsl(0 0% 0% / 0.1);
-  --spacing: 0.25rem;
-}
+**Task Execution**:
+- ❌ Mix multiple targets into a single template (respect target independence)
+- ❌ Skip MCP research when design_space_analysis is provided
+- ❌ Generate variant N+1 before variant N's files are written
+- ❌ Return research results as files (keep in memory for token refinement)
+- ❌ Assume default values without checking orchestrator prompt
 
-/* Apply tokens globally */
-body {
-  font-family: var(--font-sans);
-  background-color: var(--background);
-  color: var(--foreground);
-}
-
-h1, h2, h3, h4, h5, h6 {
-  font-family: var(--font-sans);
-}
-```
-
-### Version & Changelog
-
-**Version**: 4.2.0
-**Last Updated**: 2025-10-09
-
-**Changelog**:
-- **4.2.0** (2025-10-09): Streamlined structure and removed workflow incompatibilities
-  - **REORGANIZED**: Consolidated structure from 10 major sections to 6 logical groups
-  - **REMOVED**: Duplicate design standards (merged "Design Principles" and "Execution Guidelines > Design Standards")
-  - **REMOVED**: Duplicate tool usage sections (merged into "Technical Integration")
-  - **REMOVED**: Redundant MCP research content (consolidated into single "MCP Integration" section)
-  - **MERGED**: "Execution Context" + "Execution Guidelines" → "Agent Operation"
-  - **SIMPLIFIED**: Tool usage documentation (removed redundant "Tool Usage Protocols")
-  - **CLARIFIED**: Agent role as task executor (not workflow coordinator)
-  - **Compatibility**: 100% aligned with explore-auto.md and generate.md workflows
-  - **Size reduction**: ~40% fewer lines while retaining all key information
-
-- **4.1.0** (2025-10-09): Integrated design.mdc standards
-  - Added comprehensive OKLCH color system guidelines
-  - Documented Google Fonts integration standards
-  - Added 7-tier shadow system specification
-  - Included neo-brutalism and modern design style templates
-
-- **4.0.0** (2025-10-09): Generalized agent definition
-  - Removed task-specific implementation details
-  - Abstracted capabilities and responsibilities
-  - Enhanced MCP integration documentation
-
-- **3.0.0** (2025-10-09): Task-focused architecture
-  - Added consolidate.md and generate.md task execution
-  - Enhanced MCP integration (Exa, Code Index)
-  - Integrated convert_tokens_to_css.sh and ui-instantiate-prototypes.sh
+**Quality Violations**:
+- ❌ Use hardcoded colors/fonts/spacing instead of tokens
+- ❌ Generate tokens without OKLCH format for colors
+- ❌ Skip WCAG AA contrast validation
+- ❌ Omit Google Fonts imports or fallback stacks
+- ❌ Create incomplete token categories

.claude/agents/universal-executor.md

@@ -1,5 +1,5 @@
 ---
-name: general-purpose
+name: universal-executor
 description: |
   Versatile execution agent for implementing any task efficiently. Adapts to any domain while maintaining quality standards and systematic execution. Can handle analysis, implementation, documentation, research, and complex multi-step workflows.
 

.claude/commands/cli/analyze.md

@@ -1,116 +1,136 @@
 ---
 name: analyze
 description: Quick codebase analysis using CLI tools (codex/gemini/qwen)
-usage: /cli:analyze [--tool <codex|gemini|qwen>] [--enhance] <analysis-target>
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] analysis target"
-examples:
-  - /cli:analyze "authentication patterns"
-  - /cli:analyze --tool qwen "API security"
-  - /cli:analyze --tool codex --enhance "performance bottlenecks"
-allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] analysis target"
+allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*), Task(*)
 ---
 
 # CLI Analyze Command (/cli:analyze)
 
 ## Purpose
 
-Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
+Quick codebase analysis using CLI tools. **Read-only - does NOT modify code**.
 
-**Intent**: Understand code patterns, architecture, and provide insights/recommendations
-**Supported Tools**: codex, gemini (default), qwen
-
-## Core Behavior
-
-1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
-2. **No Code Modification**: Results are recommendations and analysis reports
-3. **Template-Based**: Automatically selects appropriate analysis template
-4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+**Tool Selection**:
+- **gemini** (default) - Best for code analysis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for deep analysis
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Use `/enhance-prompt` for context-aware enhancement
 - `<analysis-target>` - Description of what to analyze
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
 ## Execution Flow
 
+### Standard Mode
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
-3. Auto-detect analysis type from keywords → select template
-4. Build command with auto-detected file patterns and `MODE: analysis`
-5. Execute analysis (read-only, no code changes)
-6. Return analysis report with insights and recommendations
+2. Optional: enhance with `/enhance-prompt`
+3. Auto-detect file patterns from keywords
+4. Build command with analysis template
+5. Execute analysis (read-only)
+6. Save results
+
+### Agent Mode (`--agent`)
+
+Delegates to agent for intelligent analysis:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Codebase analysis",
+  prompt=`
+    Task: ${analysis_target}
+    Mode: analyze
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Enhance: ${enhance_flag || false}
+
+    Agent responsibilities:
+    1. Context Discovery:
+       - Discover relevant files/patterns
+       - Identify analysis scope
+       - Build file context
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Apply analysis template
+       - Include discovered files
+
+    3. Execution & Output:
+       - Execute analysis
+       - Generate insights report
+       - Save to .workflow/.chat/ or .scratchpad/
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Analyzes code, does NOT modify files
+- **Auto-pattern**: Detects file patterns from keywords
+- **Template-based**: Auto-selects analysis template
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
 
 ## File Pattern Auto-Detection
 
-Keywords trigger specific file patterns:
-- "auth" → `@{**/*auth*,**/*user*}`
-- "component" → `@{src/components/**/*,**/*.component.*}`
-- "API" → `@{**/api/**/*,**/routes/**/*}`
-- "test" → `@{**/*.test.*,**/*.spec.*}`
-- "config" → `@{*.config.*,**/config/**/*}`
-- Generic → `@{src/**/*}`
+Keywords → file patterns:
+- "auth" → `@**/*auth* @**/*user*`
+- "component" → `@src/components/**/*`
+- "API" → `@**/api/**/* @**/routes/**/*`
+- "test" → `@**/*.test.* @**/*.spec.*`
+- Generic → `@src/**/*`
 
-For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
-
-## Command Template
+## CLI Command Templates
 
+**Gemini/Qwen**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [analysis goal from target]
-TASK: [auto-detected analysis type]
+cd . && gemini -p "
+PURPOSE: [goal]
+TASK: [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]
+CONTEXT: @CLAUDE.md [auto-detected patterns]
+EXPECTED: Insights, recommendations
+RULES: [auto-selected template]
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Analysis**:
+**Codex**:
 ```bash
-/cli:analyze "authentication patterns"
-# Executes: Gemini analysis with auth file patterns
-# Returns: Pattern analysis, architecture insights, recommendations
+codex -C . --full-auto exec "
+PURPOSE: [goal]
+TASK: [analysis type]
+MODE: analysis
+CONTEXT: @CLAUDE.md [patterns]
+EXPECTED: Deep insights
+RULES: [template]
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Architecture Analysis**:
-```bash
-/cli:analyze --tool qwen "component architecture"
-# Executes: Qwen with component file patterns
-# Returns: Architecture review, design patterns, improvement suggestions
-```
+## Output
 
-**Performance Analysis**:
-```bash
-/cli:analyze --tool codex "performance bottlenecks"
-# Executes: Codex deep analysis with performance focus
-# Returns: Bottleneck identification, optimization recommendations
-```
-
-**Enhanced Analysis**:
-```bash
-/cli:analyze --enhance "fix auth issues"
-# Step 1: Enhance prompt to expand context
-# Step 2: Analysis with expanded context
-# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
-- **No active session OR one-off analysis**:
-  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
-- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/analyze-[desc]-[timestamp].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
+- See `intelligent-tools-strategy.md` for detailed tool usage and templates

.claude/commands/cli/chat.md

@@ -1,121 +1,125 @@
 ---
 name: chat
 description: Simple CLI interaction command for direct codebase analysis
-usage: /cli:chat [--tool <codex|gemini|qwen>] [--enhance] "inquiry"
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
-examples:
-  - /cli:chat "analyze the authentication flow"
-  - /cli:chat --tool qwen --enhance "optimize React component"
-  - /cli:chat --tool codex "review security vulnerabilities"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Chat Command (/cli:chat)
 
 ## Purpose
 
-Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
+Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does NOT modify code**.
 
-**Intent**: Ask questions, get explanations, understand codebase structure
-**Supported Tools**: codex, gemini (default), qwen
-
-## Core Behavior
-
-1. **Conversational Analysis**: Direct question-answer interaction about codebase
-2. **Read-Only**: This command ONLY provides information and analysis
-3. **No Code Modification**: Results are explanations and insights
-4. **Flexible Context**: Choose specific files or entire codebase
+**Tool Selection**:
+- **gemini** (default) - Best for Q&A and explanations
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for technical deep-dives
 
 ## Parameters
 
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance inquiry with `/enhance-prompt`
 - `<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
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
+### Standard Mode
 1. Parse tool selection (default: gemini)
-2. If `--enhance`: Execute `/enhance-prompt` to expand user intent
-3. Assemble context: `@{CLAUDE.md}` + user-specified files or `--all-files`
-4. Execute CLI tool with assembled context (read-only, analysis mode)
-5. Return explanations and insights (NO code changes)
-6. Optionally save to workflow session
+2. Optional: enhance with `/enhance-prompt`
+3. Assemble context: `@CLAUDE.md` + inferred files
+4. Execute Q&A (read-only)
+5. Return answer
 
-## Context Assembly
+### Agent Mode (`--agent`)
 
-**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
+Delegates to agent for intelligent Q&A:
 
-**Optional**:
-- User-explicit files from inquiry keywords
-- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Codebase Q&A",
+  prompt=`
+    Task: ${inquiry}
+    Mode: chat (Q&A)
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Enhance: ${enhance_flag || false}
 
-For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
+    Agent responsibilities:
+    1. Context Discovery:
+       - Discover files relevant to question
+       - Identify key code sections
+       - Build precise context
 
-## Command Template
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include discovered context
+       - Apply Q&A template
 
+    3. Execution & Output:
+       - Execute Q&A analysis
+       - Generate detailed answer
+       - Save to .workflow/.chat/ or .scratchpad/
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Provides answers, does NOT modify code
+- **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/` or `.scratchpad/`
+
+## CLI Command Templates
+
+**Gemini/Qwen**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-INQUIRY: [user question]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+cd . && gemini -p "
+PURPOSE: Answer question
+TASK: [inquiry]
 MODE: analysis
-RESPONSE: Direct answer, explanation, insights (NO code modification)
+CONTEXT: @CLAUDE.md [inferred or @**/*]
+EXPECTED: Clear answer
+RULES: Focus on accuracy
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Question**:
+**Codex**:
 ```bash
-/cli:chat "analyze the authentication flow"
-# Executes: Gemini analysis
-# Returns: Explanation of auth flow, components involved, data flow
+codex -C . --full-auto exec "
+PURPOSE: Answer question
+TASK: [inquiry]
+MODE: analysis
+CONTEXT: @CLAUDE.md [inferred or @**/*]
+EXPECTED: Detailed answer
+RULES: Technical depth
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**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
-```
+## Output
 
-**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`
+- **With session**: `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/chat-[desc]-[timestamp].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
+- See `intelligent-tools-strategy.md` for detailed tool usage and templates

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

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

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

@@ -1,12 +1,7 @@
 ---
 name: codex-execute
 description: Automated task decomposition and execution with Codex using resume mechanism
-usage: /cli:codex-execute [--verify-git] <task-description|task-id>
 argument-hint: "[--verify-git] task description or task-id"
-examples:
-  - /cli:codex-execute "implement user authentication system"
-  - /cli:codex-execute --verify-git "refactor API layer"
-  - /cli:codex-execute IMPL-001
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
 
@@ -135,7 +130,7 @@ git status --short
 codex -C [dir] --full-auto exec "
 PURPOSE: [group goal]
 TASK: [subtask description - first in group]
-CONTEXT: @{relevant_files} @{CLAUDE.md}
+CONTEXT: @{relevant_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [X]: [group name] - Subtask 1 of N in this group
@@ -169,7 +164,7 @@ git add -A
 codex -C [dir] --full-auto exec "
 PURPOSE: [new group goal]
 TASK: [subtask description - first in new group]
-CONTEXT: @{different_files} @{CLAUDE.md}
+CONTEXT: @{different_files} @CLAUDE.md
 EXPECTED: [specific deliverables]
 RULES: [constraints]
 Group [Y]: [new group name] - Subtask 1 of N in this group
@@ -289,10 +284,22 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 1. Mark subtask as blocked in TodoWrite
 2. Report error details to user
 3. Pause execution for manual intervention
-4. User can choose to:
-   - Retry current subtask
-   - Continue to next subtask
-   - Abort entire task
+4. Use AskUserQuestion for recovery decision:
+
+```typescript
+AskUserQuestion({
+  questions: [{
+    question: "Codex execution failed for the subtask. How should the workflow proceed?",
+    header: "Recovery",
+    options: [
+      { label: "Retry Subtask", description: "Attempt to execute the same subtask again." },
+      { label: "Skip Subtask", description: "Continue to the next subtask in the plan." },
+      { label: "Abort Workflow", description: "Stop the entire execution." }
+    ],
+    multiSelect: false
+  }]
+})
+```
 
 **Git Verification Failure** (if --verify-git):
 1. Show unexpected changes
@@ -508,6 +515,5 @@ codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -
 **Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
 
 **Output Details**:
-- Output routing and scratchpad details: see workflow-architecture.md
 - Session management: see intelligent-tools-strategy.md
 - **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

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

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

.claude/commands/cli/execute.md

@@ -1,14 +1,8 @@
 ---
 name: execute
 description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
-usage: /cli:execute [--tool <codex|gemini|qwen>] [--enhance] <description|task-id>
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
-examples:
-  - /cli:execute "implement user authentication system"
-  - /cli:execute --tool qwen --enhance "optimize React component"
-  - /cli:execute --tool codex IMPL-001
-  - /cli:execute --enhance "fix API performance issues"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Execute Command (/cli:execute)
@@ -45,13 +39,17 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar
 - Input: Workflow task identifier (e.g., `IMPL-001`)
 - Process: Task JSON parsing → Scope analysis → Execute
 
+**3. Agent Mode** (`--agent` flag):
+- Input: Description or task-id
+- Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
+
 ### Context Inference
 
-Auto-selects files based on keywords and technology:
-- "auth" → `@{**/*auth*,**/*user*}`
-- "React" → `@{src/**/*.{jsx,tsx}}`
-- "api" → `@{**/api/**/*,**/routes/**/*}`
-- Always includes: `@{CLAUDE.md,**/*CLAUDE.md}`
+Auto-selects files based on keywords and technology (each @ references one pattern):
+- "auth" → `@**/*auth* @**/*user*`
+- "React" → `@src/**/*.jsx @src/**/*.tsx`
+- "api" → `@**/api/**/* @**/routes/**/*`
+- Always includes: `@CLAUDE.md @**/*CLAUDE.md`
 
 For precise file targeting, use `rg` or MCP tools to discover files first.
 
@@ -70,7 +68,8 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode unless specified)
 - `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
 - `<description|task-id>` - Natural language description or task identifier
 - `--debug` - Verbose logging
@@ -107,15 +106,16 @@ Use `resume --last` when current task extends/relates to previous execution. See
 - No session, ad-hoc implementation:
   - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
 
-## Command Template
+## Execution Modes
 
+### Standard Mode (Default)
 ```bash
 # Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
+cd . && gemini --approval-mode yolo "
 PURPOSE: [implementation goal]
 TASK: [specific implementation]
 MODE: write
-CONTEXT: @{CLAUDE.md} [auto-detected files]
+CONTEXT: @CLAUDE.md [auto-detected files]
 EXPECTED: Working implementation with code changes
 RULES: [constraints] | Auto-approve all changes
 "
@@ -130,15 +130,52 @@ EXPECTED: Complete implementation with tests
 " --skip-git-repo-check -s danger-full-access
 ```
 
+### Agent Mode (`--agent` flag)
+
+Delegate implementation to `cli-execution-agent` for intelligent execution with automated context discovery.
+
+**Agent invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Implement with automated context discovery and optimal tool selection",
+  prompt=`
+    Task: ${description_or_task_id}
+    Mode: execute
+    Tool Preference: ${tool_flag || 'auto-select'}
+    ${enhance_flag ? 'Enhance: true' : ''}
+
+    Agent will autonomously:
+    - Discover implementation files and dependencies
+    - Assess complexity and select optimal tool
+    - Execute with YOLO permissions (auto-approve)
+    - Generate task summary if task-id provided
+  `
+)
+```
+
+The agent handles all phases internally, including complexity-based tool selection.
+
 ## Examples
 
-**Basic Implementation** (⚠️ modifies code):
+**Basic Implementation (Standard Mode)** (⚠️ modifies code):
 ```bash
 /cli:execute "implement JWT authentication with middleware"
 # Executes: Creates auth middleware, updates routes, modifies config
 # Result: NEW/MODIFIED code files with JWT implementation
 ```
 
+**Intelligent Implementation (Agent Mode)** (⚠️ modifies code):
+```bash
+/cli:execute --agent "implement OAuth2 authentication with token refresh"
+# Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
+# Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
+# Phase 3: Enhances prompt with discovered patterns and best practices
+# Phase 4: Selects Codex (complex task), executes with comprehensive context
+# Phase 5: Saves execution log + generates implementation summary
+# Result: Complete OAuth2 implementation + detailed execution log
+```
+
 **Enhanced Implementation** (⚠️ modifies code):
 ```bash
 /cli:execute --enhance "implement JWT authentication"
@@ -181,5 +218,4 @@ EXPECTED: Complete implementation with tests
 ## Notes
 
 - 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-diagnosis.md

@@ -0,0 +1,130 @@
+---
+name: bug-diagnosis
+description: Bug diagnosis and fix suggestions using CLI tools with specialized template
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
+---
+
+# CLI Mode: Bug Diagnosis (/cli:mode:bug-diagnosis)
+
+## Purpose
+
+Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows/cli-templates/prompts/development/bug-diagnosis.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for bug diagnosis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex bug analysis
+
+## Parameters
+
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance bug description with `/enhance-prompt`
+- `--cd "path"` - Target directory for focused diagnosis
+- `<bug-description>` (Required) - Bug description or error details
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+# Uses gemini by default, or specify explicitly
+--tool gemini
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
+## Execution Flow
+
+### Standard Mode
+1. Parse tool selection (default: gemini)
+2. Optional: enhance with `/enhance-prompt`
+3. Detect directory from `--cd` or auto-infer
+4. Build command with bug-diagnosis template
+5. Execute diagnosis (read-only)
+6. Save to `.workflow/WFS-[id]/.chat/`
+
+### Agent Mode (`--agent`)
+
+Delegates to agent for intelligent diagnosis:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Bug root cause diagnosis",
+  prompt=`
+    Task: ${bug_description}
+    Mode: bug-diagnosis
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: bug-diagnosis
+
+    Agent responsibilities:
+    1. Context Discovery:
+       - Locate error traces and logs
+       - Find related code sections
+       - Identify data flow paths
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include diagnostic context
+       - Apply bug-diagnosis.txt template
+
+    3. Execution & Output:
+       - Execute root cause analysis
+       - Generate fix suggestions
+       - Save to .workflow/.chat/
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Diagnoses bugs, does NOT modify code
+- **Template**: Uses `bug-diagnosis.txt` for root cause analysis
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
+
+## CLI Command Templates
+
+**Gemini/Qwen** (default, diagnosis only):
+```bash
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Root cause analysis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Diagnosis, fix plan
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/bug-diagnosis.txt)
+"
+# Qwen: Replace 'gemini' with 'qwen'
+```
+
+**Codex** (diagnosis + potential fixes):
+```bash
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Bug diagnosis
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: Diagnosis, fix suggestions
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/bug-diagnosis.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
+```
+
+## Output
+
+- **With session**: `.workflow/WFS-[id]/.chat/bug-diagnosis-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/bug-diagnosis-[desc]-[timestamp].md`
+
+## Notes
+
+- Template: `~/.claude/workflows/cli-templates/prompts/development/bug-diagnosis.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

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

@@ -1,121 +0,0 @@
----
-name: bug-index
-description: Bug analysis and fix suggestions using CLI tools
-usage: /cli:mode:bug-index [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "bug description"
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
-examples:
-  - /cli:mode:bug-index "authentication null pointer error"
-  - /cli:mode:bug-index --tool qwen --enhance "login not working"
-  - /cli:mode:bug-index --tool codex --cd "src/auth" "token validation fails"
-allowed-tools: SlashCommand(*), Bash(*)
----
-
-# CLI Mode: Bug Index (/cli:mode:bug-index)
-
-## Purpose
-
-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
-
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[bug-description]"` first
-3. Parse bug description (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with bug-fix template
-6. Execute analysis (read-only, provides fix recommendations)
-7. Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
-
-## Core Rules
-
-1. **Analysis Only**: This command analyzes bugs and suggests fixes - it does NOT modify code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use bug-fix template
-5. **Session Output**: Save analysis results and fix recommendations to session chat
-
-## Analysis Focus (via Template)
-
-- Root cause investigation and diagnosis
-- Code path tracing to locate issues
-- Targeted minimal fix recommendations
-- Impact assessment of proposed changes
-
-## Command Template
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [bug analysis goal]
-TASK: Systematic bug analysis and fix recommendations
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Root cause analysis, code path tracing, targeted fix suggestions
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [description]
-"
-```
-
-## Examples
-
-**Basic Bug Analysis**:
-```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Debug authentication null pointer error
-TASK: Identify root cause and provide fix recommendations
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Root cause, code path, minimal fix suggestion, impact assessment
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: null pointer in login flow
-"
-```
-
-**Directory-Specific**:
-```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Fix token validation failure
-TASK: Analyze token validation bug in auth module
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation logic analysis, fix recommendation with minimal changes
-RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: token validation fails intermittently
-"
-```
-
-## Bug Investigation Workflow
-
-```bash
-# 1. Find bug-related files
-rg "error_keyword" --files-with-matches
-mcp__code-index__search_code_advanced(pattern="error|exception", file_pattern="*.ts")
-
-# 2. Execute bug analysis with focused context (analysis only, no code changes)
-/cli:mode:bug-index --cd "src/module" "specific error description"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND bug is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/bug-index-[timestamp].md`
-- **No active session OR quick debugging**:
-  - Save to `.workflow/.scratchpad/bug-index-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-payment-fix`, analyzing payment bug → `.chat/bug-index-20250105-143022.md`
-- No session, quick null pointer investigation → `.scratchpad/bug-index-null-pointer-20250105-143045.md`
-
-## Notes
-
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Template path: `~/.claude/prompt-templates/bug-fix.md`
-- Always uses `--all-files` for comprehensive codebase context

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

@@ -1,127 +1,137 @@
 ---
 name: code-analysis
 description: Deep code analysis and debugging using CLI tools with specialized template
-usage: /cli:mode:code-analysis [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "analysis target"
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
-examples:
-  - /cli:mode:code-analysis "analyze authentication flow logic"
-  - /cli:mode:code-analysis --tool qwen --enhance "explain data transformation pipeline"
-  - /cli:mode:code-analysis --tool codex --cd "src/core" "trace execution path for user registration"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Code Analysis (/cli:mode:code-analysis)
 
 ## Purpose
 
-Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`).
+Systematic code analysis with execution path tracing template (`~/.claude/workflows/cli-templates/prompts/analysis/code-execution-tracing.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for code analysis and tracing
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex analysis tasks
 
-**Supported Tools**: codex, gemini (default), qwen
 **Key Feature**: `--cd` flag for directory-scoped analysis
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
 - `--enhance` - Enhance analysis target with `/enhance-prompt` first
 - `--cd "path"` - Target directory for focused analysis
 - `<analysis-target>` (Required) - Code analysis target or question
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+/cli:mode:code-analysis --tool gemini "trace auth flow"
+# OR (default)
+/cli:mode:code-analysis "trace auth flow"
+```
+
+**Qwen** (Fallback):
+```bash
+/cli:mode:code-analysis --tool qwen "trace auth flow"
+```
+
+**Codex** (Alternative):
+```bash
+/cli:mode:code-analysis --tool codex "trace auth flow"
+```
+
 ## Execution Flow
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first
-3. Parse analysis target (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with code-analysis template
-6. Execute deep analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+### Standard Mode (Default)
+
+1. Parse tool selection (default: gemini)
+2. Optional: enhance analysis target with `/enhance-prompt`
+3. Detect target directory from `--cd` or auto-infer
+4. Build command with execution-tracing template
+5. Execute analysis (read-only)
+6. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+
+### Agent Mode (`--agent` flag)
+
+Delegates to `cli-execution-agent` for intelligent context discovery and analysis.
 
 ## Core Rules
 
-1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
-2. **Tool Selection**: Use `--tool` value or default to gemini
-3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-5. **Template Required**: Always use code-analysis template
-6. **Session Output**: Save analysis results to session chat
+- **Read-only**: Analyzes code, does NOT modify files
+- **Template**: Uses `code-execution-tracing.txt` for systematic analysis
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
 
-## Analysis Capabilities (via Template)
-
-- **Systematic Code Analysis**: Break down complex code into manageable parts
-- **Execution Path Tracing**: Track variable states and call stacks
-- **Control & Data Flow**: Understand code logic and data transformations
-- **Call Flow Visualization**: Diagram function calling sequences
-- **Logical Reasoning**: Explain "why" behind code behavior
-- **Debugging Insights**: Identify potential bugs or inefficiencies
-
-## Command Template
+## CLI Command Templates
 
+**Gemini/Qwen** (default, read-only analysis):
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [analysis goal]
-TASK: Systematic code analysis and execution path tracing
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Execution path tracing
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Execution trace, call flow diagram, debugging insights
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
+CONTEXT: @**/*
+EXPECTED: Trace, call diagram
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/code-execution-tracing.txt)
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Code Analysis**:
+**Codex** (analysis + optimization suggestions):
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Trace authentication execution flow
-TASK: Analyze complete auth flow from request to response
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Path analysis
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Step-by-step execution trace with call diagram, variable states
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
-"
+CONTEXT: @**/*
+EXPECTED: Trace, optimization
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/code-execution-tracing.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Directory-Specific Analysis**:
-```bash
-cd src/auth && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Understand JWT token validation logic
-TASK: Trace JWT validation from middleware to service layer
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Validation flow diagram, token lifecycle analysis
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
-"
+## Agent Execution Context
+
+When `--agent` flag is used, delegate to agent:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Code execution path analysis",
+  prompt=`
+    Task: ${analysis_target}
+    Mode: code-analysis
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: code-execution-tracing
+
+    Agent responsibilities:
+    1. Context Discovery:
+       - Identify entry points and call chains
+       - Discover related files (MCP/ripgrep)
+       - Map execution flow paths
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include discovered context
+       - Apply code-execution-tracing.txt template
+
+    3. Execution & Output:
+       - Execute analysis with selected tool
+       - Save to .workflow/WFS-[id]/.chat/
+  `
+)
 ```
 
-## Code Tracing Workflow
+## Output
 
-```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"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-- **No active session OR standalone analysis**:
-  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
-- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/code-analysis-[desc]-[timestamp].md`
 
 ## Notes
 
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad directory details: see workflow-architecture.md
-- Template path: `~/.claude/prompt-templates/code-analysis.md`
-- Always uses `--all-files` for comprehensive code context
+- Template: `~/.claude/workflows/cli-templates/prompts/analysis/code-execution-tracing.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

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

@@ -1,125 +1,129 @@
 ---
 name: plan
 description: Project planning and architecture analysis using CLI tools
-usage: /cli:mode:plan [--tool <codex|gemini|qwen>] [--enhance] [--cd "path"] "topic"
-argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
-examples:
-  - /cli:mode:plan "design user dashboard"
-  - /cli:mode:plan --tool qwen --enhance "plan microservices migration"
-  - /cli:mode:plan --tool codex --cd "src/auth" "authentication system"
-allowed-tools: SlashCommand(*), Bash(*)
+argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
 # CLI Mode: Plan (/cli:mode:plan)
 
 ## Purpose
 
-Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`).
+Strategic software architecture planning template (`~/.claude/workflows/cli-templates/prompts/planning/architecture-planning.txt`).
 
-**Supported Tools**: codex, gemini (default), qwen
-**Key Feature**: `--cd` flag for directory-scoped planning
+**Tool Selection**:
+- **gemini** (default) - Best for architecture planning
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for implementation planning
 
 ## Parameters
 
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
-- `--enhance` - Enhance topic with `/enhance-prompt` first
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--agent` - Use cli-execution-agent for automated context discovery
+- `--enhance` - Enhance task with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused planning
-- `<topic>` (Required) - Planning topic or architectural question
+- `<planning-task>` (Required) - Architecture planning task or modification requirements
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[topic]"` first
-3. Parse topic (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with planning template
-6. Execute analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+### Standard Mode
+1. Parse tool selection (default: gemini)
+2. Optional: enhance with `/enhance-prompt`
+3. Detect directory from `--cd` or auto-infer
+4. Build command with architecture-planning template
+5. Execute planning (read-only, no code generation)
+6. Save to `.workflow/WFS-[id]/.chat/`
+
+### Agent Mode (`--agent`)
+
+Delegates to agent for intelligent planning:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Architecture modification planning",
+  prompt=`
+    Task: ${planning_task}
+    Mode: architecture-planning
+    Tool: ${tool_flag || 'auto-select'}  // gemini|qwen|codex
+    Directory: ${cd_path || 'auto-detect'}
+    Template: architecture-planning
+
+    Agent responsibilities:
+    1. Context Discovery:
+       - Analyze current architecture
+       - Identify affected components
+       - Map dependencies and impacts
+
+    2. CLI Command Generation:
+       - Build Gemini/Qwen/Codex command
+       - Include architecture context
+       - Apply architecture-planning.txt template
+
+    3. Execution & Output:
+       - Execute strategic planning
+       - Generate modification plan
+       - Save to .workflow/.chat/
+  `
+)
+```
 
 ## Core Rules
 
-1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use planning template
-5. **Session Output**: Save analysis results to session chat
+- **Planning only**: Creates modification plans, does NOT generate code
+- **Template**: Uses `architecture-planning.txt` for strategic planning
+- **Output**: Saves to `.workflow/WFS-[id]/.chat/`
 
-## Planning Capabilities (via Template)
-
-- Strategic architecture insights and recommendations
-- Implementation roadmaps and suggestions
-- Key technical decisions analysis
-- Risk assessment
-- Resource planning
-
-## Command Template
+## CLI Command Templates
 
+**Gemini/Qwen** (default, planning only):
 ```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [planning goal from topic]
-TASK: Comprehensive planning and architecture analysis
+cd [dir] && gemini -p "
+PURPOSE: [goal]
+TASK: Architecture planning
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase in directory]
-EXPECTED: Strategic insights, implementation recommendations, key decisions
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
+CONTEXT: @**/*
+EXPECTED: Modification plan, impact analysis
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/architecture-planning.txt)
 "
+# Qwen: Replace 'gemini' with 'qwen'
 ```
 
-## Examples
-
-**Basic Planning Analysis**:
+**Codex** (planning + implementation guidance):
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Design user dashboard architecture
-TASK: Plan dashboard component structure and data flow
+codex -C [dir] --full-auto exec "
+PURPOSE: [goal]
+TASK: Architecture planning
 MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Architecture recommendations, component design, data flow diagram
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
-"
+CONTEXT: @**/*
+EXPECTED: Plan, implementation roadmap
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/architecture-planning.txt)
+" -m gpt-5 --skip-git-repo-check -s danger-full-access
 ```
 
-**Directory-Specific Planning**:
-```bash
-cd src/api && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: Plan API refactoring strategy
-TASK: Analyze current API structure and recommend improvements
-MODE: analysis
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
-"
-```
+## Output
 
-## Planning Workflow
-
-```bash
-# 1. Discover project structure
-~/.claude/scripts/get_modules_by_depth.sh
-mcp__code-index__find_files(pattern="*.ts")
-
-# 2. Gather existing architecture info
-rg "architecture|design" --files-with-matches
-
-# 3. Execute planning analysis (analysis only, no code changes)
-/cli:mode:plan "topic for strategic planning"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND planning is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-- **No active session OR exploratory planning**:
-  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
-- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
+- **With session**: `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
+- **No session**: `.workflow/.scratchpad/plan-[desc]-[timestamp].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
+- Template: `~/.claude/workflows/cli-templates/prompts/planning/architecture-planning.txt`
+- See `intelligent-tools-strategy.md` for detailed tool usage

.claude/commands/enhance-prompt.md

@@ -1,12 +1,7 @@
 ---
 name: enhance-prompt
 description: Context-aware prompt enhancement using session memory and codebase analysis
-usage: /enhance-prompt <user_input>
 argument-hint: "user input to enhance"
-examples:
-  - /enhance-prompt "add user profile editing"
-  - /enhance-prompt "fix login button"
-  - /enhance-prompt "clean up the payment code"
 ---
 
 ## Overview
@@ -36,7 +31,7 @@ FUNCTION should_use_gemini(user_prompt):
 END
 ```
 
-**Gemini Integration:** @~/.claude/workflows/intelligent-tools-strategy.md
+**Gemini Integration:** ~/.claude/workflows/intelligent-tools-strategy.md
 
 ## Enhancement Rules
 

.claude/commands/memory/docs.md

@@ -0,0 +1,609 @@
+---
+name: docs
+description: Documentation planning and orchestration - creates structured documentation tasks for execution
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]"
+---
+
+# Documentation Workflow (/memory:docs)
+
+## Overview
+Lightweight planner that analyzes project structure, decomposes documentation work into tasks, and generates execution plans. Does NOT generate documentation content itself - delegates to doc-generator agent.
+
+**Execution Strategy**:
+- **Dynamic Task Grouping**: Level 1 tasks grouped by top-level directories with document count limit
+  - **Primary constraint**: Each task generates ≤7 documents (API.md + README.md count)
+  - **Optimization goal**: Prefer grouping 2 top-level directories per task for context sharing
+  - **Conflict resolution**: If 2 dirs exceed 7 docs, reduce to 1 dir/task; if 1 dir exceeds 7 docs, split by subdirectories
+  - **Context benefit**: Same-task directories analyzed together via single Gemini call
+- **Parallel Execution**: Multiple Level 1 tasks execute concurrently for faster completion
+- **Pre-computed Analysis**: Phase 2 performs unified analysis once, stored in `.process/` for reuse
+- **Efficient Data Loading**: All existing docs loaded once in Phase 2, shared across tasks
+
+**Path Mirroring**: Documentation structure mirrors source code under `.workflow/docs/{project_name}/`
+- Example: `my_app/src/core/` → `.workflow/docs/my_app/src/core/API.md`
+
+**Two Execution Modes**:
+- **Default (Agent Mode)**: CLI analyzes in `pre_analysis` (MODE=analysis), agent writes docs
+- **--cli-execute (CLI Mode)**: CLI generates docs in `implementation_approach` (MODE=write), agent executes CLI commands
+
+## Path Mirroring Strategy
+
+**Principle**: Documentation structure **mirrors** source code structure under project-specific directory.
+
+| Source Path | Project Name | Documentation Path |
+|------------|--------------|-------------------|
+| `my_app/src/core/` | `my_app` | `.workflow/docs/my_app/src/core/API.md` |
+| `my_app/src/modules/auth/` | `my_app` | `.workflow/docs/my_app/src/modules/auth/API.md` |
+| `another_project/lib/utils/` | `another_project` | `.workflow/docs/another_project/lib/utils/API.md` |
+
+**Benefits**: Easy to locate documentation, maintains logical organization, clear 1:1 mapping, supports any project structure.
+
+## Parameters
+
+```bash
+/memory:docs [path] [--tool <gemini|qwen|codex>] [--mode <full|partial>] [--cli-execute]
+```
+
+- **path**: Target directory (default: current directory)
+- **--mode**: Documentation generation mode (default: full)
+  - `full`: Complete documentation (modules + README + ARCHITECTURE + EXAMPLES + HTTP API)
+  - `partial`: Module documentation only (API.md + README.md)
+- **--tool**: CLI tool selection (default: gemini)
+  - `gemini`: Comprehensive documentation, pattern recognition
+  - `qwen`: Architecture analysis, system design focus
+  - `codex`: Implementation validation, code quality
+- **--cli-execute**: Enable CLI-based documentation generation (optional)
+
+## Planning Workflow
+
+### Phase 1: Initialize Session
+
+```bash
+# Get target path, project name, and root
+bash(pwd && basename "$(pwd)" && git rev-parse --show-toplevel 2>/dev/null || pwd && date +%Y%m%d-%H%M%S)
+
+# Create session directories (replace timestamp)
+bash(mkdir -p .workflow/WFS-docs-{timestamp}/.{task,process,summaries} && touch .workflow/.active-WFS-docs-{timestamp})
+
+# Create workflow-session.json (replace values)
+bash(echo '{"session_id":"WFS-docs-{timestamp}","project":"{project} documentation","status":"planning","timestamp":"2024-01-20T14:30:22+08:00","path":".","target_path":"{target_path}","project_root":"{project_root}","project_name":"{project_name}","mode":"full","tool":"gemini","cli_execute":false}' | jq '.' > .workflow/WFS-docs-{timestamp}/workflow-session.json)
+```
+
+### Phase 2: Analyze Structure
+
+**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack.
+
+**Commands** (collect data with simple bash):
+
+```bash
+# 1. Run folder analysis
+bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh)
+
+# 2. Get top-level directories (first 2 path levels)
+bash(~/.claude/scripts/get_modules_by_depth.sh | ~/.claude/scripts/classify-folders.sh | awk -F'|' '{print $1}' | sed 's|^\./||' | awk -F'/' '{if(NF>=2) print $1"/"$2; else if(NF==1) print $1}' | sort -u)
+
+# 3. Find existing docs (if directory exists)
+bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null; fi)
+
+# 4. Read existing docs content (if files exist)
+bash(if [ -d .workflow/docs/\${project_name} ]; then find .workflow/docs/\${project_name} -type f -name "*.md" ! -path "*/README.md" ! -path "*/ARCHITECTURE.md" ! -path "*/EXAMPLES.md" ! -path "*/api/*" 2>/dev/null | xargs cat 2>/dev/null; fi)
+```
+
+**Data Processing**: Parse bash outputs, calculate statistics, use **Write tool** to create `${session_dir}/.process/phase2-analysis.json` with structure:
+
+```json
+{
+  "metadata": {
+    "generated_at": "2025-11-03T16:57:30.469669",
+    "project_name": "project_name",
+    "project_root": "/path/to/project"
+  },
+  "folder_analysis": [
+    {"path": "./src/core", "type": "code", "code_count": 5, "dirs_count": 2}
+  ],
+  "top_level_dirs": ["src/modules", "lib/core"],
+  "existing_docs": {
+    "file_list": [".workflow/docs/project/src/core/API.md"],
+    "content": "... existing docs content ..."
+  },
+  "unified_analysis": [],
+  "statistics": {
+    "total": 15,
+    "code": 8,
+    "navigation": 7,
+    "top_level": 3
+  }
+}
+```
+
+**Then** use **Edit tool** to update `workflow-session.json` adding analysis field.
+
+**Output**: Single `phase2-analysis.json` with all analysis data (no temp files or Python scripts).
+
+**Auto-skipped**: Tests (`**/test/**`, `**/*.test.*`), Build (`**/node_modules/**`, `**/dist/**`), Config (root-level files), Vendor directories.
+
+### Phase 3: Detect Update Mode
+
+**Commands**:
+
+```bash
+# Count existing docs from phase2-analysis.json
+bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq '.existing_docs.file_list | length')
+```
+
+**Data Processing**: Use count result, then use **Edit tool** to update `workflow-session.json`:
+- Add `"update_mode": "update"` if count > 0, else `"create"`
+- Add `"existing_docs": <count>`
+
+### Phase 4: Decompose Tasks
+
+**Task Hierarchy** (Dynamic based on document count):
+
+```
+Small Projects (total ≤7 docs):
+  Level 1: IMPL-001 (all directories in single task, shared context)
+  Level 2: IMPL-002 (README, full mode only)
+  Level 3: IMPL-003 (ARCHITECTURE+EXAMPLES), IMPL-004 (HTTP API, optional)
+
+Medium Projects (Example: 7 top-level dirs, 12 total docs):
+  Step 1: Count docs per top-level dir
+    ├─ dir1: 2 docs, dir2: 3 docs → Group 1 (5 docs)
+    ├─ dir3: 4 docs, dir4: 2 docs → Group 2 (6 docs)
+    ├─ dir5: 1 doc → Group 3 (1 doc, can add more)
+
+  Step 2: Create tasks with ≤7 docs constraint
+  Level 1: IMPL-001 to IMPL-003 (parallel groups)
+    ├─ IMPL-001: Group 1 (dir1 + dir2, 5 docs, shared context)
+    ├─ IMPL-002: Group 2 (dir3 + dir4, 6 docs, shared context)
+    └─ IMPL-003: Group 3 (remaining dirs, ≤7 docs)
+  Level 2: IMPL-004 (README, depends on Level 1, full mode only)
+  Level 3: IMPL-005 (ARCHITECTURE+EXAMPLES), IMPL-006 (HTTP API, optional)
+
+Large Projects (single dir >7 docs):
+  Step 1: Detect oversized directory
+    └─ src/modules/: 12 subdirs → 24 docs (exceeds limit)
+
+  Step 2: Split by subdirectories
+  Level 1: IMPL-001 to IMPL-004 (split oversized dir)
+    ├─ IMPL-001: src/modules/ subdirs 1-3 (6 docs)
+    ├─ IMPL-002: src/modules/ subdirs 4-6 (6 docs)
+    └─ IMPL-003: src/modules/ subdirs 7-12 (12 docs) → further split
+```
+
+**Grouping Algorithm**:
+1. Count total docs for each top-level directory
+2. Try grouping 2 directories (optimization for context sharing)
+3. If group exceeds 7 docs, split to 1 dir/task
+4. If single dir exceeds 7 docs, split by subdirectories
+5. Create parallel Level 1 tasks with ≤7 docs each
+
+**Benefits**: Parallel execution, failure isolation, progress visibility, context sharing, document count control.
+
+**Commands**:
+
+```bash
+# 1. Get top-level directories from phase2-analysis.json
+bash(cat .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json | jq -r '.top_level_dirs[]')
+
+# 2. Get mode from workflow-session.json
+bash(cat .workflow/WFS-docs-{timestamp}/workflow-session.json | jq -r '.mode // "full"')
+
+# 3. Check for HTTP API
+bash(grep -r "router\.|@Get\|@Post" src/ 2>/dev/null && echo "API_FOUND" || echo "NO_API")
+```
+
+**Data Processing**:
+1. Count documents for each top-level directory (from folder_analysis):
+   - Code folders: 2 docs each (API.md + README.md)
+   - Navigation folders: 1 doc each (README.md only)
+2. Apply grouping algorithm with ≤7 docs constraint:
+   - Try grouping 2 directories, calculate total docs
+   - If total ≤7 docs: create group
+   - If total >7 docs: split to 1 dir/group or subdivide
+   - If single dir >7 docs: split by subdirectories
+3. Use **Edit tool** to update `phase2-analysis.json` adding groups field:
+   ```json
+   "groups": {
+     "count": 3,
+     "assignments": [
+       {"group_id": "001", "directories": ["src/modules", "src/utils"], "doc_count": 5},
+       {"group_id": "002", "directories": ["lib/core"], "doc_count": 6},
+       {"group_id": "003", "directories": ["lib/helpers"], "doc_count": 3}
+     ]
+   }
+   ```
+
+**Task ID Calculation**:
+```bash
+group_count=$(jq '.groups.count' .workflow/WFS-docs-{timestamp}/.process/phase2-analysis.json)
+readme_id=$((group_count + 1))   # Next ID after groups
+arch_id=$((group_count + 2))
+api_id=$((group_count + 3))
+```
+
+### Phase 5: Generate Task JSONs
+
+**CLI Strategy**:
+
+| Mode | cli_execute | Placement | CLI MODE | Approval Flag | Agent Role |
+|------|-------------|-----------|----------|---------------|------------|
+| **Agent** | false | pre_analysis | analysis | (none) | Generate docs in implementation_approach |
+| **CLI** | true | implementation_approach | write | --approval-mode yolo | Execute CLI commands, validate output |
+
+**Command Patterns**:
+- Gemini/Qwen: `cd dir && gemini -p "..."`
+- CLI Mode: `cd dir && gemini --approval-mode yolo -p "..."`
+- Codex: `codex -C dir --full-auto exec "..." --skip-git-repo-check -s danger-full-access`
+
+**Generation Process**:
+1. Read configuration values (tool, cli_execute, mode) from workflow-session.json
+2. Read group assignments from phase2-analysis.json
+3. Generate Level 1 tasks (IMPL-001 to IMPL-N, one per group)
+4. Generate Level 2+ tasks if mode=full (README, ARCHITECTURE, HTTP API)
+
+## Task Templates
+
+### Level 1: Module Trees Group Task (Unified)
+
+**Execution Model**: Each task processes assigned directory group (max 2 directories) using pre-analyzed data from Phase 2.
+
+```json
+{
+  "id": "IMPL-${group_number}",
+  "title": "Document Module Trees Group ${group_number}",
+  "status": "pending",
+  "meta": {
+    "type": "docs-tree-group",
+    "agent": "@doc-generator",
+    "tool": "gemini",
+    "cli_execute": false,
+    "group_number": "${group_number}",
+    "total_groups": "${total_groups}"
+  },
+  "context": {
+    "requirements": [
+      "Process directories from group ${group_number} in phase2-analysis.json",
+      "Generate docs to .workflow/docs/${project_name}/ (mirrored structure)",
+      "Code folders: API.md + README.md; Navigation folders: README.md only",
+      "Use pre-analyzed data from Phase 2 (no redundant analysis)"
+    ],
+    "focus_paths": ["${group_dirs_from_json}"],
+    "precomputed_data": {
+      "phase2_analysis": "${session_dir}/.process/phase2-analysis.json"
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_precomputed_data",
+        "action": "Load Phase 2 analysis and extract group directories",
+        "commands": [
+          "bash(cat ${session_dir}/.process/phase2-analysis.json)",
+          "bash(jq '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories' ${session_dir}/.process/phase2-analysis.json)"
+        ],
+        "output_to": "phase2_context",
+        "note": "Single JSON file contains all Phase 2 analysis results"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate documentation for assigned directory group",
+        "description": "Process directories in Group ${group_number} using pre-analyzed data",
+        "modification_points": [
+          "Read group directories from [phase2_context].groups.assignments[${group_number}].directories",
+          "For each directory: parse folder types from folder_analysis, parse structure from unified_analysis",
+          "Map source_path to .workflow/docs/${project_name}/{path}",
+          "Generate API.md for code folders, README.md for all folders",
+          "Preserve user modifications from [phase2_context].existing_docs.content"
+        ],
+        "logic_flow": [
+          "phase2 = parse([phase2_context])",
+          "dirs = phase2.groups.assignments[${group_number}].directories",
+          "for dir in dirs:",
+          "  folder_info = find(dir, phase2.folder_analysis)",
+          "  outline = find(dir, phase2.unified_analysis)",
+          "  if folder_info.type == 'code': generate API.md + README.md",
+          "  elif folder_info.type == 'navigation': generate README.md only",
+          "  write to .workflow/docs/${project_name}/{dir}/"
+        ],
+        "depends_on": [],
+        "output": "group_module_docs"
+      }
+    ],
+    "target_files": [
+      ".workflow/docs/${project_name}/*/API.md",
+      ".workflow/docs/${project_name}/*/README.md"
+    ]
+  }
+}
+```
+
+**CLI Execute Mode Note**: When `cli_execute=true`, add Step 2 in `implementation_approach`:
+```json
+{
+  "step": 2,
+  "title": "Batch generate documentation via CLI",
+  "command": "bash(dirs=$(jq -r '.groups.assignments[] | select(.group_id == \"${group_number}\") | .directories[]' ${session_dir}/.process/phase2-analysis.json); for dir in $dirs; do cd \"$dir\" && gemini --approval-mode yolo -p \"PURPOSE: Generate module docs\\nTASK: Create documentation\\nMODE: write\\nCONTEXT: @**/* [phase2_context]\\nEXPECTED: API.md and README.md\\nRULES: Mirror structure\" || echo \"Failed: $dir\"; cd -; done)",
+  "depends_on": [1],
+  "output": "generated_docs"
+}
+```
+
+### Level 2: Project README Task
+
+**Task ID**: `IMPL-${readme_id}` (where `readme_id = group_count + 1`)
+**Dependencies**: Depends on all Level 1 tasks completing.
+
+```json
+{
+  "id": "IMPL-${readme_id}",
+  "title": "Generate Project README",
+  "status": "pending",
+  "depends_on": ["IMPL-001", "...", "IMPL-${group_count}"],
+  "meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false},
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_existing_readme",
+        "command": "bash(cat .workflow/docs/${project_name}/README.md 2>/dev/null || echo 'No existing README')",
+        "output_to": "existing_readme"
+      },
+      {
+        "step": "load_module_docs",
+        "command": "bash(find .workflow/docs/${project_name} -type f -name '*.md' ! -path '.workflow/docs/${project_name}/README.md' ! -path '.workflow/docs/${project_name}/ARCHITECTURE.md' ! -path '.workflow/docs/${project_name}/EXAMPLES.md' ! -path '.workflow/docs/${project_name}/api/*' | xargs cat)",
+        "output_to": "all_module_docs"
+      },
+      {
+        "step": "analyze_project",
+        "command": "bash(gemini \"PURPOSE: Analyze project structure\\nTASK: Extract overview from modules\\nMODE: analysis\\nCONTEXT: [all_module_docs]\\nEXPECTED: Project outline\")",
+        "output_to": "project_outline"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate project README",
+        "description": "Generate project README with navigation links while preserving user modifications",
+        "modification_points": [
+          "Parse [project_outline] and [all_module_docs]",
+          "Generate README structure with navigation links",
+          "Preserve [existing_readme] user modifications"
+        ],
+        "logic_flow": ["Parse data", "Generate README with navigation", "Preserve modifications"],
+        "depends_on": [],
+        "output": "project_readme"
+      }
+    ],
+    "target_files": [".workflow/docs/${project_name}/README.md"]
+  }
+}
+```
+
+### Level 3: Architecture & Examples Documentation Task
+
+**Task ID**: `IMPL-${arch_id}` (where `arch_id = group_count + 2`)
+**Dependencies**: Depends on Level 2 (Project README).
+
+```json
+{
+  "id": "IMPL-${arch_id}",
+  "title": "Generate Architecture & Examples Documentation",
+  "status": "pending",
+  "depends_on": ["IMPL-${readme_id}"],
+  "meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false},
+  "flow_control": {
+    "pre_analysis": [
+      {"step": "load_existing_docs", "command": "bash(cat .workflow/docs/${project_name}/{ARCHITECTURE,EXAMPLES}.md 2>/dev/null || echo 'No existing docs')", "output_to": "existing_arch_examples"},
+      {"step": "load_all_docs", "command": "bash(cat .workflow/docs/${project_name}/README.md && find .workflow/docs/${project_name} -type f -name '*.md' ! -path '*/README.md' ! -path '*/ARCHITECTURE.md' ! -path '*/EXAMPLES.md' ! -path '*/api/*' | xargs cat)", "output_to": "all_docs"},
+      {"step": "analyze_architecture", "command": "bash(gemini \"PURPOSE: Analyze system architecture\\nTASK: Synthesize architectural overview and examples\\nMODE: analysis\\nCONTEXT: [all_docs]\\nEXPECTED: Architecture + Examples outline\")", "output_to": "arch_examples_outline"}
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate architecture and examples documentation",
+        "modification_points": [
+          "Parse [arch_examples_outline] and [all_docs]",
+          "Generate ARCHITECTURE.md (system design, patterns)",
+          "Generate EXAMPLES.md (code snippets, usage)",
+          "Preserve [existing_arch_examples] modifications"
+        ],
+        "depends_on": [],
+        "output": "arch_examples_docs"
+      }
+    ],
+    "target_files": [".workflow/docs/${project_name}/ARCHITECTURE.md", ".workflow/docs/${project_name}/EXAMPLES.md"]
+  }
+}
+```
+
+### Level 4: HTTP API Documentation Task (Optional)
+
+**Task ID**: `IMPL-${api_id}` (where `api_id = group_count + 3`)
+**Dependencies**: Depends on Level 3.
+
+```json
+{
+  "id": "IMPL-${api_id}",
+  "title": "Generate HTTP API Documentation",
+  "status": "pending",
+  "depends_on": ["IMPL-${arch_id}"],
+  "meta": {"type": "docs", "agent": "@doc-generator", "tool": "gemini", "cli_execute": false},
+  "flow_control": {
+    "pre_analysis": [
+      {"step": "discover_api", "command": "bash(rg 'router\\.| @(Get|Post)' -g '*.{ts,js}')", "output_to": "endpoint_discovery"},
+      {"step": "load_existing_api", "command": "bash(cat .workflow/docs/${project_name}/api/README.md 2>/dev/null || echo 'No existing API docs')", "output_to": "existing_api_docs"},
+      {"step": "analyze_api", "command": "bash(gemini \"PURPOSE: Document HTTP API\\nTASK: Analyze endpoints\\nMODE: analysis\\nCONTEXT: @src/api/**/* [endpoint_discovery]\\nEXPECTED: API outline\")", "output_to": "api_outline"}
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate HTTP API documentation",
+        "modification_points": [
+          "Parse [api_outline] and [endpoint_discovery]",
+          "Document endpoints, request/response formats",
+          "Preserve [existing_api_docs] modifications"
+        ],
+        "depends_on": [],
+        "output": "api_docs"
+      }
+    ],
+    "target_files": [".workflow/docs/${project_name}/api/README.md"]
+  }
+}
+```
+
+## Session Structure
+
+**Unified Structure** (single JSON replaces multiple text files):
+
+```
+.workflow/
+├── .active-WFS-docs-{timestamp}
+└── WFS-docs-{timestamp}/
+    ├── workflow-session.json            # Session metadata
+    ├── IMPL_PLAN.md
+    ├── TODO_LIST.md
+    ├── .process/
+    │   └── phase2-analysis.json         # All Phase 2 analysis data (replaces 7+ files)
+    └── .task/
+        ├── IMPL-001.json                # Small: all modules | Large: group 1
+        ├── IMPL-00N.json                # (Large only: groups 2-N)
+        ├── IMPL-{N+1}.json              # README (full mode)
+        ├── IMPL-{N+2}.json              # ARCHITECTURE+EXAMPLES (full mode)
+        └── IMPL-{N+3}.json              # HTTP API (optional)
+```
+
+**phase2-analysis.json Structure**:
+```json
+{
+  "metadata": {
+    "generated_at": "2025-11-03T16:41:06+08:00",
+    "project_name": "Claude_dms3",
+    "project_root": "/d/Claude_dms3"
+  },
+  "folder_analysis": [
+    {"path": "./src/core", "type": "code", "code_count": 5, "dirs_count": 2},
+    {"path": "./src/utils", "type": "navigation", "code_count": 0, "dirs_count": 4}
+  ],
+  "top_level_dirs": ["src/modules", "src/utils", "lib/core"],
+  "existing_docs": {
+    "file_list": [".workflow/docs/project/src/core/API.md"],
+    "content": "... concatenated existing docs ..."
+  },
+  "unified_analysis": [
+    {"module_path": "./src/core", "outline_summary": "Core functionality"}
+  ],
+  "groups": {
+    "count": 4,
+    "assignments": [
+      {"group_id": "001", "directories": ["src/modules", "src/utils"], "doc_count": 6},
+      {"group_id": "002", "directories": ["lib/core", "lib/helpers"], "doc_count": 7}
+    ]
+  },
+  "statistics": {
+    "total": 15,
+    "code": 8,
+    "navigation": 7,
+    "top_level": 3
+  }
+}
+```
+
+**Workflow Session Structure** (workflow-session.json):
+```json
+{
+  "session_id": "WFS-docs-{timestamp}",
+  "project": "{project_name} documentation",
+  "status": "planning",
+  "timestamp": "2024-01-20T14:30:22+08:00",
+  "path": ".",
+  "target_path": "/path/to/project",
+  "project_root": "/path/to/project",
+  "project_name": "{project_name}",
+  "mode": "full",
+  "tool": "gemini",
+  "cli_execute": false,
+  "update_mode": "update",
+  "existing_docs": 5,
+  "analysis": {
+    "total": "15",
+    "code": "8",
+    "navigation": "7",
+    "top_level": "3"
+  }
+}
+```
+
+## Generated Documentation
+
+**Structure mirrors project source directories under project-specific folder**:
+
+```
+.workflow/docs/
+└── {project_name}/                    # Project-specific root
+    ├── src/                           # Mirrors src/ directory
+    │   ├── modules/
+    │   │   ├── README.md              # Navigation
+    │   │   ├── auth/
+    │   │   │   ├── API.md             # API signatures
+    │   │   │   ├── README.md          # Module docs
+    │   │   │   └── middleware/
+    │   │   │       ├── API.md
+    │   │   │       └── README.md
+    │   │   └── api/
+    │   │       ├── API.md
+    │   │       └── README.md
+    │   └── utils/
+    │       └── README.md
+    ├── lib/                           # Mirrors lib/ directory
+    │   └── core/
+    │       ├── API.md
+    │       └── README.md
+    ├── README.md                      # Project root
+    ├── ARCHITECTURE.md                # System design
+    ├── EXAMPLES.md                    # Usage examples
+    └── api/                           # Optional
+        └── README.md                  # HTTP API reference
+```
+
+## Execution Commands
+
+```bash
+# Execute entire workflow (auto-discovers active session)
+/workflow:execute
+
+# Or specify session
+/workflow:execute --resume-session="WFS-docs-yyyymmdd-hhmmss"
+
+# Individual task execution
+/task:execute IMPL-001
+```
+
+## Template Reference
+
+**Available Templates** (`~/.claude/workflows/cli-templates/prompts/documentation/`):
+- `api.txt`: Code API (Part A) + HTTP API (Part B)
+- `module-readme.txt`: Module purpose, usage, dependencies
+- `folder-navigation.txt`: Navigation README for folders with subdirectories
+- `project-readme.txt`: Project overview, getting started, navigation
+- `project-architecture.txt`: System structure, module map, design patterns
+- `project-examples.txt`: End-to-end usage examples
+
+## Execution Mode Summary
+
+| Mode | CLI Placement | CLI MODE | Approval Flag | Agent Role |
+|------|---------------|----------|---------------|------------|
+| **Agent (default)** | pre_analysis | analysis | (none) | Generates documentation content |
+| **CLI (--cli-execute)** | implementation_approach | write | --approval-mode yolo | Executes CLI commands, validates output |
+
+**Execution Flow**:
+- **Phase 2**: Unified analysis once, results in `.process/`
+- **Phase 4**: Dynamic grouping (max 2 dirs per group)
+- **Level 1**: Parallel processing for module tree groups
+- **Level 2+**: Sequential execution for project-level docs
+
+## Related Commands
+- `/workflow:execute` - Execute documentation tasks
+- `/workflow:status` - View task progress
+- `/workflow:session:complete` - Mark session complete

.claude/commands/memory/load.md

@@ -0,0 +1,240 @@
+---
+name: load
+description: Load project memory by delegating to agent, returns structured core content package for subsequent operations
+argument-hint: "[--tool gemini|qwen] \"task context description\""
+allowed-tools: Task(*), Bash(*)
+examples:
+  - /memory:load "在当前前端基础上开发用户认证功能"
+  - /memory:load --tool qwen -p "重构支付模块API"
+---
+
+# Memory Load Command (/memory:load)
+
+## 1. Overview
+
+The `memory:load` command **delegates to a universal-executor agent** to analyze the project and return a structured "Core Content Pack". This pack is loaded into the main thread's memory, providing essential context for subsequent agent operations while minimizing token consumption.
+
+**Core Philosophy**:
+- **Agent-Driven**: Fully delegates execution to universal-executor agent
+- **Read-Only Analysis**: Does not modify code, only extracts context
+- **Structured Output**: Returns standardized JSON content package
+- **Memory Optimization**: Package loaded directly into main thread memory
+- **Token Efficiency**: CLI analysis executed within agent to save tokens
+
+## 2. Parameters
+
+- `"task context description"` (Required): Task description to guide context extraction
+  - Example: "在当前前端基础上开发用户认证功能"
+  - Example: "重构支付模块API"
+  - Example: "修复数据库查询性能问题"
+
+- `--tool <gemini|qwen>` (Optional): Specify CLI tool for agent to use (default: gemini)
+  - gemini: Large context window, suitable for complex project analysis
+  - qwen: Alternative to Gemini with similar capabilities
+
+## 3. Agent-Driven Execution Flow
+
+The command fully delegates to **universal-executor agent**, which autonomously:
+
+1. **Analyzes Project Structure**: Executes `get_modules_by_depth.sh` to understand architecture
+2. **Loads Documentation**: Reads CLAUDE.md, README.md and other key docs
+3. **Extracts Keywords**: Derives core keywords from task description
+4. **Discovers Files**: Uses MCP code-index or rg/find to locate relevant files
+5. **CLI Deep Analysis**: Executes Gemini/Qwen CLI for deep context analysis
+6. **Generates Content Package**: Returns structured JSON core content package
+
+## 4. Core Content Package Structure
+
+**Output Format** - Loaded into main thread memory for subsequent use:
+
+```json
+{
+  "task_context": "在当前前端基础上开发用户认证功能",
+  "keywords": ["前端", "用户", "认证", "auth", "login"],
+  "project_summary": {
+    "architecture": "TypeScript + React frontend with Vite build system",
+    "tech_stack": ["React", "TypeScript", "Vite", "TailwindCSS"],
+    "key_patterns": [
+      "State management via Context API",
+      "Functional components with Hooks pattern",
+      "API calls encapsulated in custom hooks"
+    ]
+  },
+  "relevant_files": [
+    {
+      "path": "src/components/Auth/LoginForm.tsx",
+      "relevance": "Existing login form component",
+      "priority": "high"
+    },
+    {
+      "path": "src/contexts/AuthContext.tsx",
+      "relevance": "Authentication state management context",
+      "priority": "high"
+    },
+    {
+      "path": "CLAUDE.md",
+      "relevance": "Project development standards",
+      "priority": "high"
+    }
+  ],
+  "integration_points": [
+    "Must integrate with existing AuthContext",
+    "Follow component organization pattern: src/components/[Feature]/",
+    "API calls should use src/hooks/useApi.ts wrapper"
+  ],
+  "constraints": [
+    "Maintain backward compatibility",
+    "Follow TypeScript strict mode",
+    "Use existing UI component library"
+  ]
+}
+```
+
+## 5. Agent Invocation
+
+```javascript
+Task(
+  subagent_type="universal-executor",
+  description="Load project memory: ${task_description}",
+  prompt=`
+## Mission: Load Project Memory Context
+
+**Task**: Load project memory context for: "${task_description}"
+**Mode**: analysis
+**Tool Preference**: ${tool || 'gemini'}
+
+## Execution Steps
+
+### Step 1: Foundation Analysis
+
+1. **Project Structure**
+   \`\`\`bash
+   bash(~/.claude/scripts/get_modules_by_depth.sh)
+   \`\`\`
+
+2. **Core Documentation**
+   \`\`\`javascript
+   Read(CLAUDE.md)
+   Read(README.md)
+   \`\`\`
+
+### Step 2: Keyword Extraction & File Discovery
+
+1. Extract core keywords from task description
+2. Discover relevant files using ripgrep and find:
+   \`\`\`bash
+   # Find files by name
+   find . -name "*{keyword}*" -type f
+
+   # Search content with ripgrep
+   rg "{keyword}" --type ts --type md -C 2
+   rg -l "{keyword}" --type ts --type md  # List files only
+   \`\`\`
+
+### Step 3: Deep Analysis via CLI
+
+Execute Gemini/Qwen CLI for deep analysis (saves main thread tokens):
+
+\`\`\`bash
+cd . && ${tool} -p "
+PURPOSE: Extract project core context for task: ${task_description}
+TASK: Analyze project architecture, tech stack, key patterns, relevant files
+MODE: analysis
+CONTEXT: @CLAUDE.md,README.md @${discovered_files}
+EXPECTED: Structured project summary and integration point analysis
+RULES:
+- Focus on task-relevant core information
+- Identify key architecture patterns and technical constraints
+- Extract integration points and development standards
+- Output concise, structured format
+"
+\`\`\`
+
+### Step 4: Generate Core Content Package
+
+Generate structured JSON content package (format shown above)
+
+**Required Fields**:
+- task_context: Original task description
+- keywords: Extracted keyword array
+- project_summary: Architecture, tech stack, key patterns
+- relevant_files: File list with path, relevance, priority
+- integration_points: Integration guidance
+- constraints: Development constraints
+
+### Step 5: Return Content Package
+
+Return JSON content package as final output for main thread to load into memory.
+
+## Quality Checklist
+
+Before returning:
+- [ ] Valid JSON format
+- [ ] All required fields complete
+- [ ] relevant_files contains 3-10 files minimum
+- [ ] project_summary accurately reflects architecture
+- [ ] integration_points clearly specify integration paths
+- [ ] keywords accurately extracted (3-8 keywords)
+- [ ] Content concise, avoiding redundancy (< 5KB total)
+
+  `
+)
+```
+
+## 6. Usage Examples
+
+### Example 1: Load Context for New Feature
+
+```bash
+/memory:load "在当前前端基础上开发用户认证功能"
+```
+
+**Agent Execution**:
+1. Analyzes project structure (`get_modules_by_depth.sh`)
+2. Reads CLAUDE.md, README.md
+3. Extracts keywords: ["前端", "用户", "认证", "auth"]
+4. Uses MCP to search relevant files
+5. Executes Gemini CLI for deep analysis
+6. Returns core content package
+
+**Returned Package** (loaded into memory):
+```json
+{
+  "task_context": "在当前前端基础上开发用户认证功能",
+  "keywords": ["前端", "认证", "auth", "login"],
+  "project_summary": { ... },
+  "relevant_files": [ ... ],
+  "integration_points": [ ... ],
+  "constraints": [ ... ]
+}
+```
+
+### Example 2: Using Qwen Tool
+
+```bash
+/memory:load --tool qwen -p "重构支付模块API"
+```
+
+Agent uses Qwen CLI for analysis, returns same structured package.
+
+### Example 3: Bug Fix Context
+
+```bash
+/memory:load "修复登录验证错误"
+```
+
+Returns core context related to login validation, including test files and validation logic.
+
+### Memory Persistence
+
+- **Session-Scoped**: Content package valid for current session
+- **Subsequent Reference**: All subsequent agents/commands can access
+- **Reload Required**: New sessions need to re-execute /memory:load
+
+## 8. Notes
+
+- **Read-Only**: Does not modify any code, pure analysis
+- **Token Optimization**: CLI analysis executed within agent, saves main thread tokens
+- **Memory Loading**: Returned JSON loaded directly into main thread memory
+- **Subsequent Use**: Other commands/agents can reference this package for development
+- **Session-Level**: Content package valid for current session

.claude/commands/memory/skill-memory.md

@@ -0,0 +1,361 @@
+---
+name: skill-memory
+description: Generate SKILL package index from project documentation
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Memory SKILL Package Generator
+
+## Orchestrator Role
+
+**This command is a pure orchestrator**: Execute documentation generation workflow, then generate SKILL.md index. Does NOT create task JSON files.
+
+**Execution Model - 4-Phase Workflow**:
+
+1. **User triggers**: `/memory:skill-memory [path] [options]`
+2. **Phase 1**: Parse arguments and prepare → Auto-continues
+3. **Phase 2**: Call `/memory:docs` to plan documentation → Auto-continues
+4. **Phase 3**: Call `/workflow:execute` to generate docs → Auto-continues
+5. **Phase 4**: Generate SKILL.md index → Reports completion
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status
+- After each phase completion, automatically executes next phase
+- All phases run autonomously without user interaction
+- Progress updates shown at each phase
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - delegates to /memory:docs
+3. **Parse Every Output**: Extract required data from each command output
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
+6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool
+
+## 4-Phase Execution
+
+### Phase 1: Prepare Arguments
+
+**Goal**: Parse command arguments and check existing documentation
+
+**Step 1: Get Target Path and Project Name**
+```bash
+# Get current directory (or use provided path)
+bash(pwd)
+
+# Get project name from directory
+bash(basename "$(pwd)")
+
+# Get project root
+bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+**Output**:
+- `target_path`: `/d/my_project`
+- `project_name`: `my_project`
+- `project_root`: `/d/my_project`
+
+**Step 2: Set Default Parameters**
+```bash
+# Default values (use these unless user specifies otherwise):
+# - tool: "gemini"
+# - mode: "full"
+# - regenerate: false (no --regenerate flag)
+# - cli_execute: false (no --cli-execute flag)
+```
+
+**Step 3: Check Existing Documentation**
+```bash
+# Check if docs directory exists (replace project_name with actual value)
+bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists")
+
+# Count existing documentation files
+bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Output**:
+- `docs_exists`: `exists` or `not_exists`
+- `existing_docs`: `5` (or `0` if no docs)
+
+**Step 4: Handle --regenerate Flag (If Specified)**
+```bash
+# If user specified --regenerate, delete existing docs directory
+bash(rm -rf .workflow/docs/my_project 2>/dev/null || true)
+
+# Verify deletion
+bash(test -d .workflow/docs/my_project && echo "still_exists" || echo "deleted")
+```
+
+**Summary**:
+- `PROJECT_NAME`: `my_project`
+- `TARGET_PATH`: `/d/my_project`
+- `DOCS_PATH`: `.workflow/docs/my_project`
+- `TOOL`: `gemini` (default) or user-specified
+- `MODE`: `full` (default) or user-specified
+- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag
+- `REGENERATE`: `false` (default) or `true` if --regenerate flag
+- `EXISTING_DOCS`: `0` (after regenerate) or actual count
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+**After Phase 1**: Display preparation results, auto-continue to Phase 2
+
+---
+
+### Phase 2: Call /memory:docs
+
+**Goal**: Trigger documentation generation workflow
+
+**Command**:
+```bash
+SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]")
+```
+
+**Example**:
+```bash
+/memory:docs /d/my_app --tool gemini --mode full
+/memory:docs /d/my_app --tool gemini --mode full --cli-execute
+```
+
+**Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection.
+
+**Input**:
+- `targetPath` from Phase 1
+- `tool` from Phase 1
+- `mode` from Phase 1
+- `cli_execute` from Phase 1 (optional)
+
+**Parse Output**:
+- Extract session ID pattern: `WFS-docs-[timestamp]` (store as `docsSessionId`)
+- Extract task count (store as `taskCount`)
+
+**Validation**:
+- Session ID extracted successfully
+- Task files created in `.workflow/[docsSessionId]/.task/`
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**After Phase 2**: Display docs planning results, auto-continue to Phase 3
+
+---
+
+### Phase 3: Execute Documentation Generation
+
+**Goal**: Execute documentation generation tasks
+
+**Command**:
+```bash
+SlashCommand(command="/workflow:execute")
+```
+
+**Note**: `/workflow:execute` automatically discovers active session from Phase 2
+
+**Validation**:
+- Documentation files generated in `.workflow/docs/[projectName]/`
+- All tasks completed successfully
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+**After Phase 3**: Display execution results, auto-continue to Phase 4
+
+---
+
+### Phase 4: Generate SKILL.md Index
+
+**Step 1: Read Key Files** (Use Read tool)
+- `.workflow/docs/{project_name}/README.md` (required)
+- `.workflow/docs/{project_name}/ARCHITECTURE.md` (optional)
+
+**Step 2: Discover Structure**
+```bash
+bash(find .workflow/docs/{project_name} -name "*.md" | sed 's|.workflow/docs/{project_name}/||' | awk -F'/' '{if(NF>=2) print $1"/"$2}' | sort -u)
+```
+
+**Step 3: Generate Intelligent Description**
+
+Extract from README + structure: Function (capabilities), Modules (names), Keywords (API/CLI/auth/etc.)
+
+**Format**: `{Function}. Use when {trigger conditions}.`
+**Example**: "Workflow management with CLI tools. Use when working with workflow orchestration or docs generation."
+
+**Step 4: Write SKILL.md** (Use Write tool)
+```bash
+bash(mkdir -p .claude/skills/{project_name})
+```
+
+`.claude/skills/{project_name}/SKILL.md`:
+```yaml
+---
+name: {project_name}
+description: {intelligent description from Step 3}
+version: 1.0.0
+---
+# {Project Name} SKILL Package
+
+## Documentation: `../../.workflow/docs/{project_name}/`
+
+## Progressive Loading
+### Level 0: Quick Start (~2K)
+- [README](../../.workflow/docs/{project_name}/README.md)
+### Level 1: Core Modules (~8K)
+{Module READMEs}
+### Level 2: Complete (~25K)
+All modules + [Architecture](../../.workflow/docs/{project_name}/ARCHITECTURE.md)
+### Level 3: Deep Dive (~40K)
+Everything + [Examples](../../.workflow/docs/{project_name}/EXAMPLES.md)
+```
+
+**TodoWrite**: Mark phase 4 completed
+
+**Return to User**:
+```
+✅ SKILL Package Generation Complete
+
+Project: {project_name}
+Documentation: .workflow/docs/{project_name}/ ({doc_count} files)
+SKILL Index: .claude/skills/{project_name}/SKILL.md
+
+Generated:
+- {task_count} documentation tasks completed
+- SKILL.md with progressive loading (4 levels)
+- Module index with {module_count} modules
+
+Usage:
+- Load Level 0: Quick project overview (~2K tokens)
+- Load Level 1: Core modules (~8K tokens)
+- Load Level 2: Complete docs (~25K tokens)
+- Load Level 3: Everything (~40K tokens)
+```
+
+---
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "in_progress", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "pending", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "in_progress", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "in_progress", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+```
+
+## Parameters
+
+```bash
+/memory:skill-memory [path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]
+```
+
+- **path**: Target directory (default: current directory)
+- **--tool**: CLI tool for documentation (default: gemini)
+  - `gemini`: Comprehensive documentation
+  - `qwen`: Architecture analysis
+  - `codex`: Implementation validation
+- **--regenerate**: Force regenerate all documentation
+  - When enabled: Deletes existing `.workflow/docs/{project_name}/` before regeneration
+  - Ensures fresh documentation from source code
+- **--mode**: Documentation mode (default: full)
+  - `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES)
+  - `partial`: Module docs only
+- **--cli-execute**: Enable CLI-based documentation generation (optional)
+  - When enabled: CLI generates docs directly in implementation_approach
+  - When disabled (default): Agent generates documentation content
+
+## Examples
+
+### Example 1: Generate SKILL Package (Default)
+
+```bash
+/memory:skill-memory
+```
+
+**Workflow**:
+1. Phase 1: Detects current directory, checks existing docs
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode)
+3. Phase 3: Executes documentation generation via `/workflow:execute`
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 2: Regenerate with Qwen
+
+```bash
+/memory:skill-memory /d/my_app --tool qwen --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Parses target path, detects regenerate flag
+2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full` (regenerate handled in Phase 1)
+3. Phase 3: Executes documentation regeneration
+4. Phase 4: Generates updated SKILL.md
+
+### Example 3: Partial Mode (Modules Only)
+
+```bash
+/memory:skill-memory --mode partial
+```
+
+**Workflow**:
+1. Phase 1: Detects partial mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode)
+3. Phase 3: Executes module documentation only
+4. Phase 4: Generates SKILL.md with module-only index
+
+### Example 4: CLI Execute Mode
+
+```bash
+/memory:skill-memory --cli-execute
+```
+
+**Workflow**:
+1. Phase 1: Detects CLI execute mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode)
+3. Phase 3: Executes CLI-based documentation generation
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+## Benefits
+
+- ✅ **Pure Orchestrator**: No task JSON generation, delegates to /memory:docs
+- ✅ **Auto-Continue**: Autonomous 4-phase execution
+- ✅ **Simplified**: ~70% less code than previous version
+- ✅ **Maintainable**: Changes to /memory:docs automatically apply
+- ✅ **Direct Generation**: Phase 4 directly writes SKILL.md
+- ✅ **Flexible**: Supports all /memory:docs options
+
+## Architecture
+
+```
+skill-memory (orchestrator)
+  ├─ Phase 1: Prepare (bash commands)
+  ├─ Phase 2: /memory:docs (task planning)
+  ├─ Phase 3: /workflow:execute (task execution)
+  └─ Phase 4: Write SKILL.md (direct file generation)
+
+No task JSON created by this command
+All documentation tasks managed by /memory:docs
+```

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

@@ -0,0 +1,333 @@
+---
+name: update-full
+description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback
+argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
+---
+
+# Full Documentation Update (/memory:update-full)
+
+## Overview
+
+Orchestrates project-wide CLAUDE.md updates using batched agent execution with automatic tool fallback and 3-layer architecture support.
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+- `--path <directory>`: Target specific directory (default: entire project)
+
+**Execution Flow**: Discovery → Plan Presentation → Execution → Safety Verification
+
+## 3-Layer Architecture & Auto-Strategy Selection
+
+### Layer Definition & Strategy Assignment
+
+| Layer | Depth | Strategy | Purpose | Context Pattern |
+|-------|-------|----------|---------|----------------|
+| **Layer 3** (Deepest) | ≥3 | `multi-layer` | Handle unstructured files, generate docs for all subdirectories | `@**/*` (all files) |
+| **Layer 2** (Middle) | 1-2 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+| **Layer 1** (Top) | 0 | `single-layer` | Aggregate from children + current code | `@*/CLAUDE.md @*.{ts,tsx,js,...}` |
+
+**Update Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
+
+**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
+
+### Strategy Details
+
+#### Multi-Layer Strategy (Layer 3 Only)
+- **Use Case**: Deepest directories with unstructured file layouts
+- **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
+- **Context**: All files in current directory tree (`@**/*`)
+- **Benefits**: Creates foundation documentation for upper layers to reference
+
+#### Single-Layer Strategy (Layers 1-2)
+- **Use Case**: Upper layers that aggregate from existing documentation
+- **Behavior**: Generates CLAUDE.md only for current directory
+- **Context**: Direct children CLAUDE.md files + current directory code files
+- **Benefits**: Minimal context consumption, clear layer separation
+
+### Example Flow
+```
+src/auth/handlers/ (depth 3) → MULTI-LAYER STRATEGY
+  CONTEXT: @**/* (all files in handlers/ and subdirs)
+  GENERATES: ./CLAUDE.md + CLAUDE.md in each subdir with files
+  ↓
+src/auth/ (depth 2) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md @*.ts (handlers/CLAUDE.md + current code)
+  GENERATES: ./CLAUDE.md only
+  ↓
+src/ (depth 1) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (auth/CLAUDE.md, utils/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+  ↓
+./ (depth 0) → SINGLE-LAYER STRATEGY
+  CONTEXT: @*/CLAUDE.md (src/CLAUDE.md, tests/CLAUDE.md)
+  GENERATES: ./CLAUDE.md only
+```
+
+## Core Execution Rules
+
+1. **Analyze First**: Git cache + module discovery before updates
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
+   - **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
+6. **Safety Check**: Verify only CLAUDE.md files modified
+7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Execution Phases
+
+### Phase 1: Discovery & Analysis
+
+```bash
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+
+# Get module structure
+bash(~/.claude/scripts/get_modules_by_depth.sh list)
+# OR with --path
+bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
+```
+
+**Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack.
+
+### Phase 2: Plan Presentation
+
+**For <20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 7 modules
+  Execution: Direct parallel (< 20 modules threshold)
+
+  Will update:
+  - ./core/interfaces (12 files) - depth 2 [Layer 2] - single-layer strategy
+  - ./core (22 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./models (9 files) - depth 1 [Layer 2] - single-layer strategy
+  - ./utils (12 files) - depth 1 [Layer 2] - single-layer strategy
+  - . (5 files) - depth 0 [Layer 1] - single-layer strategy
+
+  Context Strategy (Auto-Selected):
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Confirm execution? (y/n)
+```
+
+**For ≥20 modules**:
+```
+Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 31 modules
+  Execution: Agent batch processing (4 modules/agent)
+
+  Will update:
+  - ./src/features/auth (12 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./.claude/commands/cli (6 files) - depth 3 [Layer 3] - multi-layer strategy
+  - ./src/utils (8 files) - depth 2 [Layer 2] - single-layer strategy
+  ...
+
+  Context Strategy (Auto-Selected):
+  - Layer 3 (depth ≥3): @**/* (all files)
+  - Layer 2 (depth 1-2): @*/CLAUDE.md + current code files
+  - Layer 1 (depth 0): @*/CLAUDE.md + current code files
+  
+  Auto-skipped: ./tests, __pycache__, setup.py (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Agent allocation (by LAYER):
+  - Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
+  - Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
+  - Layer 1 (2 modules, depth 0): 1 agent [2]
+
+  Estimated time: ~15-25 minutes
+
+  Confirm execution? (y/n)
+```
+
+### Phase 3A: Direct Execution (<20 modules)
+
+**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
+
+```javascript
+// Group modules by LAYER (not depth)
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+// Process by LAYER (3 → 2 → 1), not by depth
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+
+  for (let batch of batches) {
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        // Auto-determine strategy based on depth
+        let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
+
+        for (let tool of tool_order) {
+          let exit_code = bash(`cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`);
+          if (exit_code === 0) {
+            report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
+            return true;
+          }
+        }
+        report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
+        return false;
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));
+  }
+}
+```
+
+### Phase 3B: Agent Batch Execution (≥20 modules)
+
+**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
+
+```javascript
+// Group modules by LAYER and batch within each layer
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules in Layer ${layer}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, layer)
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);
+}
+```
+
+**Batch Worker Prompt Template**:
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback
+
+TASK: Update documentation for assigned modules using specified strategies.
+
+MODULES:
+{{module_path_1}} (strategy: {{strategy_1}})
+{{module_path_2}} (strategy: {{strategy_2}})
+...
+
+TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
+
+EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
+  - Accepts strategy parameter: multi-layer | single-layer
+  - Tool execution via direct CLI commands (gemini/qwen/codex)
+
+EXECUTION FLOW (for each module):
+  1. Tool fallback loop (exit on first success):
+     for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
+       bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}")
+       exit_code=$?
+
+       if [ $exit_code -eq 0 ]; then
+         report "✅ {{module_path}} updated with $tool"
+         break
+       else
+         report "⚠️  {{module_path}} failed with $tool, trying next..."
+         continue
+       fi
+     done
+
+  2. Handle complete failure (all tools failed):
+     if [ $exit_code -ne 0 ]; then
+       report "❌ FAILED: {{module_path}} - all tools exhausted"
+       # Continue to next module (do not abort batch)
+     fi
+
+FAILURE HANDLING:
+  - Module-level isolation: One module's failure does not affect others
+  - Exit code detection: Non-zero exit code triggers next tool
+  - Exhaustion reporting: Log modules where all tools failed
+  - Batch continuation: Always process remaining modules
+
+REPORTING FORMAT:
+  Per-module status:
+    ✅ path/to/module updated with {tool}
+    ⚠️  path/to/module failed with {tool}, trying next...
+    ❌ FAILED: path/to/module - all tools exhausted
+```
+### Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display status
+bash(git status --short)
+```
+
+**Result Summary**:
+```
+Update Summary:
+  Total: 31 | Success: 29 | Failed: 2
+  Tool usage: gemini: 25, qwen: 4, codex: 0
+  Failed: path1, path2
+```
+
+## Error Handling
+
+**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
+**Coordinator**: Invalid path abort, user decline handling, safety check with auto-revert
+**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
+
+## Usage Examples
+
+```bash
+# Full project update (auto-strategy selection)
+/memory:update-full
+
+# Target specific directory
+/memory:update-full --path .claude
+/memory:update-full --path src/features/auth
+
+# Use specific tool
+/memory:update-full --tool qwen
+/memory:update-full --path .claude --tool qwen
+```
+
+## Key Advantages
+
+- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
+- **Resilience**: 3-tier tool fallback per module
+- **Performance**: Parallel batches, no concurrency limits
+- **Observability**: Per-module tool usage, batch-level metrics
+- **Automation**: Zero configuration - strategy auto-selected by directory depth

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

@@ -0,0 +1,349 @@
+---
+name: update-related
+description: Context-aware CLAUDE.md documentation updates based on recent changes with agent-based execution and tool fallback
+argument-hint: "[--tool gemini|qwen|codex]"
+---
+
+# Related Documentation Update (/memory:update-related)
+
+## Overview
+
+Orchestrates context-aware CLAUDE.md updates for changed modules using batched agent execution with automatic tool fallback (gemini→qwen→codex).
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+
+**Execution Flow**:
+1. Change Detection → 2. Plan Presentation → 3. Batched Agent Execution → 4. Safety Verification
+
+## Core Rules
+
+1. **Detect Changes First**: Use git diff to identify affected modules
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - <15 modules: Direct parallel execution (max 4 concurrent per depth, no agent overhead)
+   - ≥15 modules: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
+6. **Related Mode**: Update only changed modules and their parent contexts
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from update script
+
+## Phase 1: Change Detection & Analysis
+
+```bash
+# Detect changed modules (no index refresh needed)
+bash(~/.claude/scripts/detect_changed_modules.sh list)
+
+# Cache git changes
+bash(git add -A 2>/dev/null || true)
+```
+
+**Parse output** `depth:N|path:<PATH>|change:<TYPE>` to extract affected modules.
+
+**Smart filter**: Auto-detect and skip tests/build/config/docs based on project tech stack (Node.js/Python/Go/Rust/etc).
+
+**Fallback**: If no changes detected, use recent modules (first 10 by depth).
+
+## Phase 2: Plan Presentation
+
+**Present filtered plan**:
+```
+Related Update Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Changed: 4 modules | Batching: 4 modules/agent
+
+  Will update:
+  - ./src/api/auth (5 files) [new module]
+  - ./src/api (12 files) [parent of changed auth/]
+  - ./src (8 files) [parent context]
+  - . (14 files) [root level]
+
+  Auto-skipped (12 paths):
+  - Tests: ./src/api/auth.test.ts (8 paths)
+  - Config: tsconfig.json (3 paths)
+  - Other: node_modules (1 path)
+
+  Agent allocation:
+  - Depth 3 (1 module): 1 agent [1]
+  - Depth 2 (1 module): 1 agent [1]
+  - Depth 1 (1 module): 1 agent [1]
+  - Depth 0 (1 module): 1 agent [1]
+
+  Confirm execution? (y/n)
+```
+
+**Decision logic**:
+- User confirms "y": Proceed with execution
+- User declines "n": Abort, no changes
+- <15 modules: Direct execution
+- ≥15 modules: Agent batch execution
+
+## Phase 3A: Direct Execution (<15 modules)
+
+**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let modules = modules_by_depth[depth];
+  let batches = batch_modules(modules, 4);  // Split into groups of 4
+
+  for (let batch of batches) {
+    // Execute batch in parallel (max 4 concurrent)
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        let success = false;
+        for (let tool of tool_order) {
+          let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
+          if (exit_code === 0) {
+            report("${module.path} updated with ${tool}");
+            success = true;
+            break;
+          }
+        }
+        if (!success) {
+          report("FAILED: ${module.path} failed all tools");
+        }
+      };
+    });
+
+    await Promise.all(parallel_tasks.map(task => task()));  // Run batch in parallel
+  }
+}
+```
+
+**Benefits**:
+- No agent startup overhead
+- Parallel execution within depth (max 4 concurrent)
+- Tool fallback still applies per module
+- Faster for small changesets (<15 modules)
+- Same batching strategy as Phase 3B but without agent layer
+
+---
+
+## Phase 3B: Agent Batch Execution (≥15 modules)
+
+### Batching Strategy
+
+```javascript
+// Batch modules into groups of 4
+function batch_modules(modules, batch_size = 4) {
+  let batches = [];
+  for (let i = 0; i < modules.length; i += batch_size) {
+    batches.push(modules.slice(i, i + batch_size));
+  }
+  return batches;
+}
+// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
+```
+
+### Coordinator Orchestration
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let batches = batch_modules(modules_by_depth[depth], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Update ${batch.length} modules at depth ${depth}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, "related")
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);  // Batches run in parallel
+}
+```
+
+### Batch Worker Prompt Template
+
+```
+PURPOSE: Update CLAUDE.md for assigned modules with tool fallback (related mode)
+
+TASK:
+Update documentation for the following modules based on recent changes. For each module, try tools in order until success.
+
+MODULES:
+{{module_path_1}}
+{{module_path_2}}
+{{module_path_3}}
+{{module_path_4}}
+
+TOOLS (try in order):
+1. {{tool_1}}
+2. {{tool_2}}
+3. {{tool_3}}
+
+EXECUTION:
+For each module above:
+  1. cd "{{module_path}}"
+  2. Try tool 1:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
+     → Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
+     → Failure: Try tool 2
+  3. Try tool 2:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
+     → Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
+     → Failure: Try tool 3
+  4. Try tool 3:
+     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
+     → Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
+     → Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module
+
+REPORTING:
+Report final summary with:
+- Total processed: X modules
+- Successful: Y modules
+- Failed: Z modules
+- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
+- Detailed results for each module
+```
+
+### Example Execution
+
+**Depth 3 (new module)**:
+```javascript
+Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related")
+```
+
+**Benefits**:
+- 4 modules → 1 agent (75% reduction)
+- Parallel batches, sequential within batch
+- Each module gets full fallback chain
+- Context-aware updates based on git changes
+
+## Phase 4: Safety Verification
+
+```bash
+# Check only CLAUDE.md modified
+bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+
+# Display statistics
+bash(git diff --stat)
+```
+
+**Aggregate results**:
+```
+Update Summary:
+  Total: 4 | Success: 4 | Failed: 0
+
+  Tool usage:
+  - gemini: 4 modules
+  - qwen: 0 modules (fallback)
+  - codex: 0 modules
+
+  Changes:
+  src/api/auth/CLAUDE.md  | 45 +++++++++++++++++++++
+  src/api/CLAUDE.md       | 23 +++++++++--
+  src/CLAUDE.md           | 12 ++++--
+  CLAUDE.md               | 8 ++--
+  4 files changed, 82 insertions(+), 6 deletions(-)
+```
+
+## Execution Summary
+
+**Module Count Threshold**:
+- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
+- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
+
+**Agent Hierarchy** (for ≥15 modules):
+- **Coordinator**: Handles batch division, spawns worker agents per depth
+- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
+
+## Error Handling
+
+**Batch Worker**:
+- Tool fallback per module (auto-retry)
+- Batch isolation (failures don't propagate)
+- Clear per-module status reporting
+
+**Coordinator**:
+- No changes: Use fallback (recent 10 modules)
+- User decline: No execution
+- Safety check fail: Auto-revert staging
+- Partial failures: Continue execution, report failed modules
+
+**Fallback Triggers**:
+- Non-zero exit code
+- Script timeout
+- Unexpected output
+
+## Tool Reference
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Usage Examples
+
+```bash
+# Daily development update
+/memory:update-related
+
+# After feature work with specific tool
+/memory:update-related --tool qwen
+
+# Code quality review after implementation
+/memory:update-related --tool codex
+```
+
+## Key Advantages
+
+**Efficiency**: 30 modules → 8 agents (73% reduction)
+**Resilience**: 3-tier fallback per module
+**Performance**: Parallel batches, no concurrency limits
+**Context-aware**: Updates based on actual git changes
+**Fast**: Only affected modules, not entire project
+
+## Coordinator Checklist
+
+- Parse `--tool` (default: gemini)
+- Refresh code index for accurate change detection
+- Detect changed modules via detect_changed_modules.sh
+- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/docs)
+- Cache git changes
+- Apply fallback if no changes (recent 10 modules)
+- Construct tool fallback order
+- **Present filtered plan** with skip reasons and change types
+- **Wait for y/n confirmation**
+- Determine execution mode:
+  - **<15 modules**: Direct execution (Phase 3A)
+    - For each depth (N→0): Sequential module updates with tool fallback
+  - **≥15 modules**: Agent batch execution (Phase 3B)
+    - For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
+- Wait for depth/batch completion
+- Aggregate results
+- Safety check (only CLAUDE.md modified)
+- Display git diff statistics + summary
+
+## Comparison with Full Update
+
+| Aspect | Related Update | Full Update |
+|--------|----------------|-------------|
+| **Scope** | Changed modules only | All project modules |
+| **Speed** | Fast (minutes) | Slower (10-30 min) |
+| **Use case** | Daily development | Major refactoring |
+| **Mode** | `"related"` | `"full"` |
+| **Trigger** | After commits | After major changes |
+| **Batching** | 4 modules/agent | 4 modules/agent |
+| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
+| **Complexity threshold** | ≤15 modules | ≤20 modules |

.claude/commands/task/breakdown.md

@@ -1,12 +1,7 @@
 ---
 name: breakdown
 description: Intelligent task decomposition with context-aware subtask generation
-usage: /task:breakdown <task-id>
-argument-hint: task-id
-examples:
-  - /task:breakdown IMPL-1
-  - /task:breakdown IMPL-1.1
-  - /task:breakdown impl-3
+argument-hint: "task-id"
 ---
 
 # Task Breakdown Command (/task:breakdown)
@@ -15,7 +10,6 @@ examples:
 Breaks down complex tasks into executable subtasks with context inheritance and agent assignment.
 
 ## Core Principles
-**Task System:** @~/.claude/workflows/workflow-architecture.md
 **File Cohesion:** Related files must stay in same task
 **10-Task Limit:** Total tasks cannot exceed 10 (triggers re-scoping)
 
@@ -73,7 +67,21 @@ Define subtasks manually (remaining capacity: 4 tasks):
    - "User authentication" and "OAuth integration" both handle auth
    - Consider combining into single task
 
-Proceed with breakdown? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "File conflicts and/or similar functionality detected. How do you want to proceed?",
+    header: "Confirm",
+    options: [
+      { label: "Proceed with breakdown", description: "Accept the risks and create the subtasks as defined." },
+      { label: "Restart breakdown", description: "Discard current subtasks and start over." },
+      { label: "Cancel breakdown", description: "Abort the operation and leave the parent task as is." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Proceed with breakdown"
 
 ✅ Task IMPL-1 broken down:
 ▸ IMPL-1: Build authentication module (container)
@@ -90,7 +98,7 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 - **Implementation** → `@code-developer`
 - **Testing** → `@code-developer` (type: "test-gen")
 - **Test Validation** → `@test-fix-agent` (type: "test-fix")
-- **Review** → `@general-purpose` (optional)
+- **Review** → `@universal-executor` (optional)
 
 ### Context Inheritance
 - Subtasks inherit parent requirements
@@ -129,7 +137,6 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 
 ## Implementation Details
 
-See @~/.claude/workflows/workflow-architecture.md for:
 - Complete task JSON schema
 - Implementation field structure
 - Context inheritance rules

.claude/commands/task/create.md

@@ -1,12 +1,7 @@
 ---
 name: create
 description: Create implementation tasks with automatic context awareness
-usage: /task:create "title"
-argument-hint: "task title"
-examples:
-  - /task:create "Implement user authentication"
-  - /task:create "Build REST API endpoints"
-  - /task:create "Fix login validation bug"
+argument-hint: "\"task title\""
 ---
 
 # Task Create Command (/task:create)
@@ -109,7 +104,7 @@ Based on task type and title keywords:
 - **Design/Plan** → @planning-agent
 - **Test Generation** → @code-developer (type: "test-gen")
 - **Test Execution/Fix** → @test-fix-agent (type: "test-fix")
-- **Review/Audit** → @general-purpose (optional, only when explicitly requested)
+- **Review/Audit** → @universal-executor (optional, only when explicitly requested)
 
 ## Validation Rules
 

.claude/commands/task/execute.md

@@ -1,18 +1,13 @@
 ---
 name: execute
 description: Execute tasks with appropriate agents and context-aware orchestration
-usage: /task:execute <task-id>
-argument-hint: task-id
-examples:
-  - /task:execute IMPL-1
-  - /task:execute IMPL-1.2
-  - /task:execute IMPL-3
+argument-hint: "task-id"
 ---
 
 ### 🚀 **Command Overview: `/task:execute`**
 
 -   **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
--   **Core Principles**: @~/.claude/workflows/workflow-architecture.md
+
 
 ### ⚙️ **Execution Modes**
 
@@ -24,7 +19,7 @@ examples:
     -   Executes step-by-step, requiring user confirmation at each checkpoint.
     -   Allows for dynamic adjustments and manual review during the process.
 -   **review**
-    -   Optional manual review using `@general-purpose`.
+    -   Optional manual review using `@universal-executor`.
     -   Used only when explicitly requested by user.
 
 ### 🤖 **Agent Selection Logic**
@@ -50,7 +45,7 @@ FUNCTION select_agent(task, agent_override):
             WHEN CONTAINS "Execute tests", "Fix tests", "Validate":
                 RETURN "@test-fix-agent" // type: test-fix
             WHEN CONTAINS "Review code":
-                RETURN "@general-purpose" // Optional manual review
+                RETURN "@universal-executor" // Optional manual review
             DEFAULT:
                 RETURN "@code-developer" // Default agent
         END CASE
@@ -241,7 +236,7 @@ Different agents receive context tailored to their function, including implement
 - Error conditions to validate from implementation.context_notes.error_handling
 - Performance requirements from implementation.context_notes.performance_considerations
 
-**`@general-purpose`**:
+**`@universal-executor`**:
 - Used for optional manual reviews when explicitly requested
 - Code quality standards and implementation patterns
 - Security considerations from implementation.context_notes.risks

.claude/commands/task/replan.md

@@ -1,68 +1,95 @@
 ---
 name: replan
 description: Replan individual tasks with detailed user input and change tracking
-usage: /task:replan <task-id> [input]
-argument-hint: task-id ["text"|file.md|ISS-001]
-examples:
-  - /task:replan IMPL-1 "Add OAuth2 authentication support"
-  - /task:replan IMPL-1 updated-specs.md
-  - /task:replan IMPL-1 ISS-001
+argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Task Replan Command (/task:replan)
 
 ## Overview
-Replans individual tasks with multiple input options, change tracking, and version management.
+Replans individual tasks or batch processes multiple tasks with change tracking and backup management.
+
+**Modes**:
+- **Single Task Mode**: Replan one task with specific changes
+- **Batch Mode**: Process multiple tasks from action-plan verification report
 
 ## Core Principles
 **Task System:** @~/.claude/workflows/task-core.md
 
 ## Key Features
-- **Single-Task Focus**: Operates on individual tasks only
-- **Multiple Input Sources**: Text, files, or issue references
-- **Version Tracking**: Backup previous versions
+- **Single/Batch Operations**: Single task or multiple tasks from verification report
+- **Multiple Input Sources**: Text, files, or verification report
+- **Backup Management**: Automatic backup of previous versions
 - **Change Documentation**: Track all modifications
+- **Progress Tracking**: TodoWrite integration for batch operations
 
 ⚠️ **CRITICAL**: Validates active session before replanning
 
-## Input Sources
+## Operation Modes
 
-### Direct Text (Default)
+### Single Task Mode
+
+#### Direct Text (Default)
 ```bash
 /task:replan IMPL-1 "Add OAuth2 authentication support"
 ```
 
-### File-based Input
+#### File-based Input
 ```bash
 /task:replan IMPL-1 updated-specs.md
 ```
 Supports: .md, .txt, .json, .yaml
 
-### Issue Reference
-```bash
-/task:replan IMPL-1 ISS-001
-```
-Loads issue description and requirements
-
-### Interactive Mode
+#### Interactive Mode
 ```bash
 /task:replan IMPL-1 --interactive
 ```
 Guided step-by-step modification process with validation
 
+### Batch Mode
+
+#### From Verification Report
+```bash
+/task:replan --batch ACTION_PLAN_VERIFICATION.md
+```
+
+**Workflow**:
+1. Parse verification report to extract replan recommendations
+2. Create TodoWrite task list for all modifications
+3. Process each task sequentially with confirmation
+4. Track progress and generate summary report
+
+**Auto-detection**: If input file contains "Action Plan Verification Report" header, automatically enters batch mode
+
 ## Replanning Process
 
+### Single Task Process
+
 1. **Load & Validate**: Read task JSON and validate session
 2. **Parse Input**: Process changes from input source
-3. **Backup Version**: Create previous version backup
+3. **Create Backup**: Save previous version to backup folder
 4. **Update Task**: Modify JSON structure and relationships
 5. **Save Changes**: Write updated task and increment version
 6. **Update Session**: Reflect changes in workflow stats
 
-## Version Management
+### Batch Process
 
-### Version Tracking
-Tasks maintain version history:
+1. **Parse Verification Report**: Extract all replan recommendations
+2. **Initialize TodoWrite**: Create task list for tracking
+3. **For Each Task**:
+   - Mark todo as in_progress
+   - Load and validate task JSON
+   - Create backup
+   - Apply recommended changes
+   - Save updated task
+   - Mark todo as completed
+4. **Generate Summary**: Report all changes and backup locations
+
+## Backup Management
+
+### Backup Tracking
+Tasks maintain backup history:
 ```json
 {
   "id": "IMPL-1",
@@ -72,7 +99,8 @@ Tasks maintain version history:
       "version": "1.2",
       "reason": "Add OAuth2 support",
       "input_source": "direct_text",
-      "backup_location": ".task/versions/IMPL-1-v1.1.json"
+      "backup_location": ".task/backup/IMPL-1-v1.1.json",
+      "timestamp": "2025-10-17T10:30:00Z"
     }
   ]
 }
@@ -84,11 +112,15 @@ Tasks maintain version history:
 ```
 .task/
 ├── IMPL-1.json                    # Current version
-├── versions/
-│   └── IMPL-1-v1.1.json          # Previous backup
+├── backup/
+│   ├── IMPL-1-v1.0.json          # Original version
+│   ├── IMPL-1-v1.1.json          # Previous backup
+│   └── IMPL-1-v1.2.json          # Latest backup
 └── [new subtasks as needed]
 ```
 
+**Backup Naming**: `{task-id}-v{version}.json`
+
 ## Implementation Updates
 
 ### Change Detection
@@ -138,18 +170,68 @@ Updates workflow-session.json with:
 /task:replan IMPL-1 --rollback v1.1
 
 Rollback to version 1.1:
-- Restore task from backup
+- Restore task from backup/.../IMPL-1-v1.1.json
 - Remove new subtasks if any
 - Update session stats
 
-Confirm rollback? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "Are you sure you want to roll back this task to a previous version?",
+    header: "Confirm",
+    options: [
+      { label: "Yes, rollback", description: "Restore the task from the selected backup." },
+      { label: "No, cancel", description: "Keep the current version of the task." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Yes, rollback"
 
 ✅ Task rolled back to version 1.1
 ```
 
+## Batch Processing with TodoWrite
+
+### Progress Tracking
+When processing multiple tasks, automatically creates TodoWrite task list:
+
+```markdown
+**Batch Replan Progress**:
+- [x] IMPL-002: Add FR-12 draft saving acceptance criteria
+- [x] IMPL-003: Add FR-14 history tracking acceptance criteria
+- [⧗] IMPL-004: Add FR-09 response surface explicit coverage
+- [ ] IMPL-008: Add NFR performance validation steps
+```
+
+### Batch Report
+After completion, generates summary:
+```markdown
+## Batch Replan Summary
+
+**Total Tasks**: 4
+**Successful**: 3
+**Failed**: 1
+**Skipped**: 0
+
+### Changes Made
+- IMPL-002 v1.0 → v1.1: Added FR-12 acceptance criteria
+- IMPL-003 v1.0 → v1.1: Added FR-14 acceptance criteria
+- IMPL-004 v1.0 → v1.1: Added FR-09 explicit coverage
+
+### Backups Created
+- .task/backup/IMPL-002-v1.0.json
+- .task/backup/IMPL-003-v1.0.json
+- .task/backup/IMPL-004-v1.0.json
+
+### Errors
+- IMPL-008: File not found (task may have been renamed)
+```
+
 ## Examples
 
-### Text Input
+### Single Task - Text Input
 ```bash
 /task:replan IMPL-1 "Add OAuth2 authentication support"
 
@@ -158,14 +240,27 @@ Proposed updates:
 + Add OAuth2 integration
 + Update authentication flow
 
-Apply changes? (y/n): y
+# Use AskUserQuestion for confirmation
+AskUserQuestion({
+  questions: [{
+    question: "Do you want to apply these changes to the task?",
+    header: "Apply",
+    options: [
+      { label: "Yes, apply", description: "Create new version with these changes." },
+      { label: "No, cancel", description: "Discard changes and keep current version." }
+    ],
+    multiSelect: false
+  }]
+})
+
+User selected: "Yes, apply"
 
 ✓ Version 1.2 created
 ✓ Context updated
-✓ Backup saved
+✓ Backup saved to .task/backup/IMPL-1-v1.1.json
 ```
 
-### File Input
+### Single Task - File Input
 ```bash
 /task:replan IMPL-2 requirements.md
 
@@ -174,14 +269,59 @@ Applying specification changes...
 
 ✓ Task updated with new requirements
 ✓ Version 1.1 created
+✓ Backup saved to .task/backup/IMPL-2-v1.0.json
+```
+
+### Batch Mode - From Verification Report
+```bash
+/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+
+Parsing verification report...
+Found 4 tasks requiring replanning:
+- IMPL-002: Add FR-12 draft saving acceptance criteria
+- IMPL-003: Add FR-14 history tracking acceptance criteria
+- IMPL-004: Add FR-09 response surface explicit coverage
+- IMPL-008: Add NFR performance validation steps
+
+Creating task tracking list...
+
+Processing IMPL-002...
+✓ Backup created: .task/backup/IMPL-002-v1.0.json
+✓ Updated to v1.1
+
+Processing IMPL-003...
+✓ Backup created: .task/backup/IMPL-003-v1.0.json
+✓ Updated to v1.1
+
+Processing IMPL-004...
+✓ Backup created: .task/backup/IMPL-004-v1.0.json
+✓ Updated to v1.1
+
+Processing IMPL-008...
+✓ Backup created: .task/backup/IMPL-008-v1.0.json
+✓ Updated to v1.1
+
+✅ Batch replan completed: 4/4 successful
+📋 Summary report saved
+```
+
+### Batch Mode - Auto-detection
+```bash
+# If file contains "Action Plan Verification Report", auto-enters batch mode
+/task:replan ACTION_PLAN_VERIFICATION.md
+
+Detected verification report format
+Entering batch mode...
+[same as above]
 ```
 
 ## Error Handling
 
+### Single Task Errors
 ```bash
 # Task not found
 ❌ Task IMPL-5 not found
-→ Check task ID with /context
+→ Check task ID with /workflow:status
 
 # Task completed
 ⚠️ Task IMPL-1 is completed (cannot replan)
@@ -193,12 +333,112 @@ Applying specification changes...
 
 # No input provided
 ❌ Please specify changes needed
-→ Provide text, file, or issue reference
+→ Provide text, file, or verification report
+```
+
+### Batch Mode Errors
+```bash
+# Invalid verification report
+❌ File does not contain valid verification report format
+→ Check report structure or use single task mode
+
+# Partial failures
+⚠️ Batch completed with errors: 3/4 successful
+→ Review error details in summary report
+
+# No replan recommendations found
+❌ Verification report contains no replan recommendations
+→ Check report content or use /workflow:action-plan-verify first
+```
+
+## Batch Mode Integration
+
+### Input Format Expectations
+Batch mode parses verification reports looking for:
+
+1. **Required Actions Section**: Commands like `/task:replan IMPL-X "changes"`
+2. **Findings Table**: Task IDs with recommendations
+3. **Next Actions Section**: Specific replan commands
+
+**Example Patterns**:
+```markdown
+#### 1. HIGH Priority - Address FR Coverage Gaps
+/task:replan IMPL-004 "
+Add explicit acceptance criteria:
+- FR-09: Response surface 3D visualization
+"
+
+#### 2. MEDIUM Priority - Enhance NFR Coverage
+/task:replan IMPL-008 "
+Add performance testing:
+- NFR-01: Load test API endpoints
+"
+```
+
+### Extraction Logic
+1. Scan for `/task:replan` commands in report
+2. Extract task ID and change description
+3. Group by priority (HIGH, MEDIUM, LOW)
+4. Process in priority order with TodoWrite tracking
+
+### Confirmation Behavior
+- **Default**: Confirm each task before applying
+- **With `--auto-confirm`**: Apply all changes without prompting
+  ```bash
+  /task:replan --batch report.md --auto-confirm
+  ```
+
+## Implementation Details
+
+### Backup Management
+```typescript
+// Backup file naming convention
+const backupPath = `.task/backup/${taskId}-v${previousVersion}.json`;
+
+// Backup metadata in task JSON
+{
+  "replan_history": [
+    {
+      "version": "1.2",
+      "timestamp": "2025-10-17T10:30:00Z",
+      "reason": "Add FR-09 explicit coverage",
+      "input_source": "batch_verification_report",
+      "backup_location": ".task/backup/IMPL-004-v1.1.json"
+    }
+  ]
+}
+```
+
+### TodoWrite Integration
+```typescript
+// Initialize tracking for batch mode
+TodoWrite({
+  todos: taskList.map(task => ({
+    content: `${task.id}: ${task.changeDescription}`,
+    status: "pending",
+    activeForm: `Replanning ${task.id}`
+  }))
+});
+
+// Update progress during processing
+TodoWrite({
+  todos: updateTaskStatus(taskId, "in_progress")
+});
+
+// Mark completed
+TodoWrite({
+  todos: updateTaskStatus(taskId, "completed")
+});
 ```
 
 ## Related Commands
 
-- `/context` - View updated task structure
+- `/workflow:status` - View task structure and versions
+- `/workflow:action-plan-verify` - Generate verification report for batch mode
 - `/task:execute` - Execute replanned task
 - `/task:create` - Create new tasks
-- `/workflow:action-plan` - For workflow-wide changes
+- `/task:breakdown` - Break down complex tasks
+
+## Context
+
+$ARGUMENTS

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

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

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

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

.claude/commands/version.md

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

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

@@ -1,11 +1,7 @@
 ---
 name: action-plan-verify
 description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
-usage: /workflow:action-plan-verify [--session <session-id>]
-argument-hint: "optional: --session <session-id>"
-examples:
-  - /workflow:action-plan-verify
-  - /workflow:action-plan-verify --session WFS-auth
+argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
@@ -19,13 +15,13 @@ 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.
+Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) 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.
+**Synthesis Authority**: The `role analysis documents` 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
 
@@ -49,13 +45,13 @@ brainstorm_dir = session_dir/.brainstorming
 task_dir = session_dir/.task
 
 # Validate required artifacts
-SYNTHESIS = brainstorm_dir/synthesis-specification.md
+SYNTHESIS = brainstorm_dir/role analysis documents
 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"
+    ERROR: "role analysis documents not found. Run /workflow:brainstorm:synthesis first"
     EXIT
 
 IF NOT EXISTS(IMPL_PLAN):
@@ -71,7 +67,12 @@ IF TASK_FILES.count == 0:
 
 Load only minimal necessary context from each artifact:
 
-**From synthesis-specification.md**:
+**From workflow-session.json** (NEW - PRIMARY REFERENCE):
+- Original user prompt/intent (project or description field)
+- User's stated goals and objectives
+- User's scope definition
+
+**From role analysis documents**:
 - Functional Requirements (IDs, descriptions, acceptance criteria)
 - Non-Functional Requirements (IDs, targets)
 - Business Requirements (IDs, success metrics)
@@ -121,7 +122,14 @@ Create internal representations (do not include raw artifacts in output):
 
 Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
 
-#### A. Requirements Coverage Analysis
+#### A. User Intent Alignment (NEW - CRITICAL)
+
+- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
+- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
+- **Success Criteria Match**: Plan's success criteria reflect user's expectations
+- **Intent Conflicts**: Tasks contradicting user's original objectives
+
+#### B. Requirements Coverage Analysis
 
 - **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
 - **Unmapped Tasks**: Tasks with no clear requirement linkage
@@ -171,6 +179,7 @@ Focus on high-signal findings. Limit to 50 findings total; aggregate remainder i
 Use this heuristic to prioritize findings:
 
 - **CRITICAL**:
+  - Violates user's original intent (goal misalignment, scope drift)
   - Violates synthesis authority (requirement conflict)
   - Core requirement with zero coverage
   - Circular dependencies
@@ -201,7 +210,7 @@ Output a Markdown report (no file writes) with the following structure:
 
 **Session**: WFS-{session-id}
 **Generated**: {timestamp}
-**Artifacts Analyzed**: synthesis-specification.md, IMPL_PLAN.md, {N} task files
+**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files
 
 ---
 
@@ -311,111 +320,98 @@ Output a Markdown report (no file writes) with the following structure:
 
 ### Next Actions
 
-#### If CRITICAL Issues Exist (Current Status: 2 CRITICAL)
-**Recommendation**: ❌ **BLOCK EXECUTION** - Resolve CRITICAL issues before proceeding
+#### Action Recommendations
 
-**Required Actions**:
-1. **CRITICAL**: Add authentication implementation tasks to cover FR-03
-2. **CRITICAL**: Add performance optimization tasks to cover NFR-01
+**If CRITICAL Issues Exist**:
+- ❌ **BLOCK EXECUTION** - Resolve critical issues before proceeding
+- Use TodoWrite to track all required fixes
+- Fix broken dependencies and circular references
 
-#### If Only HIGH/MEDIUM/LOW Issues
-**Recommendation**: ⚠️ **PROCEED WITH CAUTION** - Issues are non-blocking but should be addressed
+**If Only HIGH/MEDIUM/LOW Issues**:
+- ⚠️ **PROCEED WITH CAUTION** - Fix high-priority issues first
+- Use TodoWrite to systematically track and complete all improvements
 
-**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
+#### TodoWrite-Based Remediation Workflow
 
-#### Command Suggestions
+**Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
+
+**Recommended Workflow**:
+1. **Create TodoWrite Task List**: Extract all findings from report
+2. **Process by Priority**: CRITICAL → HIGH → MEDIUM → LOW
+3. **Complete Each Fix**: Mark tasks as in_progress/completed as you work
+4. **Validate Changes**: Verify each modification against requirements
+
+**TodoWrite Task Structure Example**:
+```markdown
+Priority Order:
+1. Fix coverage gaps (CRITICAL)
+2. Resolve consistency conflicts (CRITICAL/HIGH)
+3. Add missing specifications (MEDIUM)
+4. Improve task quality (LOW)
+```
+
+**Notes**:
+- TodoWrite provides real-time progress tracking
+- Each finding becomes a trackable todo item
+- User can monitor progress throughout remediation
+- Architecture drift in IMPL_PLAN requires manual editing
+```
+
+### 7. Save Report and Execute TodoWrite-Based Remediation
+
+**Save Analysis Report**:
 ```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)
-```
+report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
+Write(report_path, full_report_content)
 ```
 
-### 7. Provide Remediation Options
+**After Report Generation**:
 
-At end of report, ask the user:
+1. **Extract Findings**: Parse all issues by severity
+2. **Create TodoWrite Task List**: Convert findings to actionable todos
+3. **Execute Fixes**: Process each todo systematically
+4. **Update Task Files**: Apply modifications directly to task JSON files
+5. **Update IMPL_PLAN**: Apply strategic changes if needed
+
+At end of report, provide remediation guidance:
 
 ```markdown
-### 🔧 Remediation Options
+### 🔧 Remediation Workflow
 
-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
+**Recommended Approach**:
+1. **Initialize TodoWrite**: Create comprehensive task list from all findings
+2. **Process by Severity**: Start with CRITICAL, then HIGH, MEDIUM, LOW
+3. **Apply Fixes Directly**: Modify task.json files and IMPL_PLAN.md as needed
+4. **Track Progress**: Mark todos as completed after each fix
 
-(Do NOT apply fixes automatically - this is read-only analysis)
+**TodoWrite Execution Pattern**:
+```bash
+# Step 1: Create task list from verification report
+TodoWrite([
+  { content: "Fix FR-03 coverage gap - add authentication task", status: "pending", activeForm: "Fixing FR-03 coverage gap" },
+  { content: "Fix IMPL-1.2 consistency - align with ADR-02", status: "pending", activeForm: "Fixing IMPL-1.2 consistency" },
+  { content: "Add context.artifacts to IMPL-1.2", status: "pending", activeForm: "Adding context.artifacts to IMPL-1.2" },
+  # ... additional todos for each finding
+])
+
+# Step 2: Process each todo systematically
+# Mark as in_progress when starting
+# Apply fix using Read/Edit tools
+# Mark as completed when done
+# Move to next priority item
 ```
 
-### 8. Update Session Metadata
+**File Modification Workflow**:
+```bash
+# For task JSON modifications:
+1. Read(.workflow/WFS-{session}/.task/IMPL-X.Y.json)
+2. Edit() to apply fixes
+3. Mark todo as completed
 
-```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"
-      }
-    }
-  }
-}
+# For IMPL_PLAN modifications:
+1. Read(.workflow/WFS-{session}/IMPL_PLAN.md)
+2. Edit() to apply strategic changes
+3. Mark todo as completed
 ```
 
-## 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}
+**Note**: All fixes execute immediately after user confirmation without additional commands.

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

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

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

@@ -1,371 +1,605 @@
 ---
 name: artifacts
-description: Generate role-specific topic-framework.md dynamically based on selected roles
-usage: /workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
-argument-hint: "topic or challenge description for framework generation"
-examples:
-  - /workflow:brainstorm:artifacts "Build real-time collaboration feature"
-  - /workflow:brainstorm:artifacts "Optimize database performance" --roles "system-architect,data-architect,subject-matter-expert"
-  - /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,ux-expert,subject-matter-expert"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
+description: Interactive clarification generating confirmed guidance specification
+argument-hint: "topic or challenge description [--count N]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---
 
-# Topic Framework Generator Command
+## Overview
 
-## Usage
-```bash
-/workflow:brainstorm:artifacts "<topic>" [--roles "role1,role2,role3"]
+Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only).
+
+**Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
+**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
+**Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates
+
+**Parameters**:
+- `topic` (required): Topic or challenge description (structured format recommended)
+- `--count N` (optional): Number of roles user WANTS to select (system will recommend N+2 options for user to choose from, default: 3)
+
+## Task Tracking
+
+**⚠️ TodoWrite Rule**: EXTEND auto-parallel's task list (NOT replace/overwrite)
+
+**When called from auto-parallel**:
+- Find the artifacts parent task: "Execute artifacts command for interactive framework generation"
+- Mark parent task as "in_progress"
+- APPEND artifacts sub-tasks AFTER the parent task (Phase 0-5)
+- Mark each sub-task as it completes
+- When Phase 5 completes, mark parent task as "completed"
+- **PRESERVE all other auto-parallel tasks** (role agents, synthesis)
+
+**Standalone Mode**:
+```json
+[
+  {"content": "Initialize session (.workflow/.active-* check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
+  {"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"},
+  {"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"},
+  {"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"},
+  {"content": "Phase 3: Generate 3-4 questions per role, output and wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 3 role questions"},
+  {"content": "Phase 4: Detect conflicts, output clarifications, wait for answers (max 10 per round)", "status": "pending", "activeForm": "Phase 4 conflict resolution"},
+  {"content": "Phase 5: Transform Q&A to declarative statements, write guidance-specification.md", "status": "pending", "activeForm": "Phase 5 document generation"}
+]
 ```
 
-## Purpose
-**Generate dynamic topic-framework.md tailored to selected roles**. Creates role-specific discussion frameworks that address relevant perspectives. If no roles specified, generates comprehensive framework covering common analysis areas.
+## User Interaction Protocol
 
-## Role-Based Framework Generation
+### Question Output Format
 
-**Dynamic Generation**: Framework content adapts based on selected roles
-- **With roles**: Generate targeted discussion points for specified roles only
-- **Without roles**: Generate comprehensive framework covering all common areas
+All questions output as structured text (detailed format with descriptions):
 
-## Core Workflow
-
-### Topic Framework Generation Process
-
-**Phase 1: Session Management** ⚠️ FIRST STEP
-- **Active session detection**: Check `.workflow/.active-*` markers
-- **Session selection**: Prompt user if multiple active sessions found
-- **Auto-creation**: Create `WFS-[topic-slug]` only if no active session exists
-- **Framework check**: Check if `topic-framework.md` exists (update vs create mode)
-
-**Phase 2: Role Analysis** ⚠️ NEW
-- **Parse roles parameter**: Extract roles from `--roles "role1,role2,role3"` if provided
-- **Role validation**: Verify each role is valid (matches available role commands)
-- **Store role list**: Save selected roles to session metadata for reference
-- **Default behavior**: If no roles specified, use comprehensive coverage
-
-**Phase 3: Dynamic Topic Analysis**
-- **Scope definition**: Define topic boundaries and objectives
-- **Stakeholder identification**: Identify key users and stakeholders based on selected roles
-- **Requirements gathering**: Extract requirements relevant to selected roles
-- **Context collection**: Gather context appropriate for role perspectives
-
-**Phase 4: Role-Specific Framework Generation**
-- **Discussion points creation**: Generate 3-5 discussion areas **tailored to selected roles**
-- **Role-targeted questions**: Create questions specifically for chosen roles
-- **Framework document**: Generate `topic-framework.md` with role-specific sections
-- **Validation check**: Ensure framework addresses all selected role perspectives
-
-**Phase 5: Metadata Storage**
-- **Save role assignment**: Store selected roles in session metadata
-- **Framework versioning**: Track which roles framework addresses
-- **Update tracking**: Maintain role evolution if framework updated
-
-## Implementation Standards
-
-### Discussion-Driven Analysis
-**Interactive Approach**: Direct conversation and exploration without predefined role constraints
-
-**Process Flow**:
-1. **Topic introduction**: Understanding scope and context
-2. **Exploratory questioning**: Open-ended investigation
-3. **Component identification**: Breaking down into manageable pieces
-4. **Relationship analysis**: Understanding connections and dependencies
-5. **Documentation generation**: Structured capture of insights
-
-**Key Areas of Investigation**:
-- **Functional aspects**: What the topic needs to accomplish
-- **Technical considerations**: Implementation constraints and requirements
-- **User perspectives**: How different stakeholders are affected
-- **Business implications**: Cost, timeline, and strategic considerations
-- **Risk assessment**: Potential challenges and mitigation strategies
-
-### Document Generation Standards
-
-**Always Created**:
-- **discussion-summary.md**: Main conversation points and key insights
-- **component-analysis.md**: Detailed breakdown of topic components
-
-## Document Generation
-
-**Primary Output**: Single structured `topic-framework.md` document
-
-**Document Structure**:
-```
-.workflow/WFS-[topic]/.brainstorming/
-└── topic-framework.md          # ★ STRUCTURED FRAMEWORK DOCUMENT
-```
-
-**Note**: `workflow-session.json` is located at `.workflow/WFS-[topic]/workflow-session.json` (session root), not inside `.brainstorming/`.
-
-## Framework Template Structures
-
-### Dynamic Role-Based Framework
-
-Framework content adapts based on `--roles` parameter:
-
-#### Option 1: Specific Roles Provided
 ```markdown
-# [Topic] - Discussion Framework
+【问题{N} - {短标签}】{问题文本}
+a) {选项标签}
+   说明：{选项说明和影响}
+b) {选项标签}
+   说明：{选项说明和影响}
+c) {选项标签}
+   说明：{选项说明和影响}
 
-## Topic Overview
-- **Scope**: [Topic boundaries relevant to selected roles]
-- **Objectives**: [Goals from perspective of selected roles]
-- **Context**: [Background focusing on role-specific concerns]
-- **Target Roles**: ui-designer, system-architect, subject-matter-expert
-
-## Role-Specific Discussion Points
-
-### For UI Designer
-1. **User Interface Requirements**
-   - What interface components are needed?
-   - What user interactions must be supported?
-   - What visual design considerations apply?
-
-2. **User Experience Challenges**
-   - What are the key user journeys?
-   - What accessibility requirements exist?
-   - How to balance aesthetics with functionality?
-
-### For System Architect
-1. **Architecture Decisions**
-   - What architectural patterns fit this solution?
-   - What scalability requirements exist?
-   - How does this integrate with existing systems?
-
-2. **Technical Implementation**
-   - What technology stack is appropriate?
-   - What are the performance requirements?
-   - What dependencies must be managed?
-
-### For Subject Matter Expert
-1. **Domain Expertise & Standards**
-   - What industry standards and best practices apply?
-   - What regulatory compliance requirements exist?
-   - What domain-specific patterns should be followed?
-
-2. **Technical Quality & Risk**
-   - What technical debt considerations exist?
-   - What scalability and maintenance implications apply?
-   - What knowledge transfer and documentation is needed?
-
-## Cross-Role Integration Points
-- How do UI decisions impact architecture?
-- How does architecture constrain UI possibilities?
-- What domain standards affect both UI and architecture?
-
-## Framework Usage
-**For Role Agents**: Address your specific section + integration points
-**Reference Format**: @../topic-framework.md in your analysis.md
-**Update Process**: Use /workflow:brainstorm:artifacts to update
-
----
-*Generated for roles: ui-designer, system-architect, subject-matter-expert*
-*Last updated: [timestamp]*
+请回答：{N}a 或 {N}b 或 {N}c
 ```
 
-#### Option 2: No Roles Specified (Comprehensive)
+**Multi-select format** (Phase 2 role selection):
 ```markdown
-# [Topic] - Discussion Framework
+【角色选择】请选择 {count} 个角色参与头脑风暴分析
 
-## Topic Overview
-- **Scope**: [Comprehensive topic boundaries]
-- **Objectives**: [All-encompassing goals]
-- **Context**: [Full background and constraints]
-- **Stakeholders**: [All relevant parties]
+a) {role-name} ({中文名})
+   推荐理由：{基于topic的相关性说明}
+b) {role-name} ({中文名})
+   推荐理由：{基于topic的相关性说明}
+...
 
-## Core Discussion Areas
+支持格式：
+- 分别选择：2a 2c 2d (选择第2题的a、c、d选项)
+- 合并语法：2acd (选择a、c、d)
+- 逗号分隔：2a,c,d
 
-### 1. Requirements & Objectives
-- What are the fundamental requirements?
-- What are the critical success factors?
-- What constraints must be considered?
-
-### 2. Technical & Architecture
-- What are the technical challenges?
-- What architectural decisions are needed?
-- What integration points exist?
-
-### 3. User Experience & Design
-- Who are the primary users?
-- What are the key user journeys?
-- What usability requirements exist?
-
-### 4. Security & Compliance
-- What security requirements exist?
-- What compliance considerations apply?
-- What data protection is needed?
-
-### 5. Implementation & Operations
-- What are the implementation risks?
-- What resources are required?
-- How will this be maintained?
-
-## Available Role Perspectives
-Framework supports analysis from any of these roles:
-- **Technical**: system-architect, data-architect, subject-matter-expert
-- **Product & Design**: ui-designer, ux-expert, product-manager, product-owner
-- **Agile & Quality**: scrum-master, test-strategist
-
----
-*Comprehensive framework - adaptable to any role*
-*Last updated: [timestamp]*
+请输入选择：
 ```
 
-## Role-Specific Content Generation
+### Input Parsing Rules
 
-### Available Roles and Their Focus Areas
+**Supported formats** (intelligent parsing):
 
-**Technical Roles**:
-- `system-architect`: Architecture patterns, scalability, technology stack, integration
-- `data-architect`: Data modeling, processing workflows, analytics, storage
-- `subject-matter-expert`: Domain expertise, industry standards, compliance, best practices
+1. **Space-separated**: `1a 2b 3c` → Q1:a, Q2:b, Q3:c
+2. **Comma-separated**: `1a,2b,3c` → Q1:a, Q2:b, Q3:c
+3. **Multi-select combined**: `2abc` → Q2: options a,b,c
+4. **Multi-select spaces**: `2 a b c` → Q2: options a,b,c
+5. **Multi-select comma**: `2a,b,c` → Q2: options a,b,c
+6. **Natural language**: `问题1选a` → 1a (fallback parsing)
 
-**Product & Design Roles**:
-- `ui-designer`: User interface, visual design, interaction patterns, accessibility
-- `ux-expert`: User experience optimization, usability testing, interaction design, design systems
-- `product-manager`: Business value, feature prioritization, market positioning, roadmap
-- `product-owner`: Backlog management, user stories, acceptance criteria, stakeholder alignment
+**Parsing algorithm**:
+- Extract question numbers and option letters
+- Validate question numbers match output
+- Validate option letters exist for each question
+- If ambiguous/invalid, output example format and request re-input
 
-**Agile & Quality Roles**:
-- `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management
-- `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches
+**Error handling** (lenient):
+- Recognize common variations automatically
+- If parsing fails, show example and wait for clarification
+- Support re-input without penalty
 
-### Dynamic Discussion Point Generation
+### Batching Strategy
 
-**For each selected role, generate**:
-1. **2-3 core discussion areas** specific to that role's perspective
-2. **3-5 targeted questions** per discussion area
-3. **Cross-role integration points** showing how roles interact
+**Batch limits**:
+- **Default**: Maximum 10 questions per round
+- **Phase 2 (role selection)**: Display all recommended roles at once (count+2 roles)
+- **Auto-split**: If questions > 10, split into multiple rounds with clear round indicators
 
-**Example mapping**:
+**Round indicators**:
+```markdown
+===== 第 1 轮问题 (共2轮) =====
+【问题1 - ...】...
+【问题2 - ...】...
+...
+【问题10 - ...】...
+
+请回答 (格式: 1a 2b ... 10c)：
+```
+
+### Interaction Flow
+
+**Standard flow**:
+1. Output questions in formatted text
+2. Output expected input format example
+3. Wait for user input
+4. Parse input with intelligent matching
+5. If parsing succeeds → Store answers and continue
+6. If parsing fails → Show error, example, and wait for re-input
+
+**No question/option limits**: Text-based interaction removes previous 4-question and 4-option restrictions
+
+## Execution Phases
+
+### Session Management
+- Check `.workflow/.active-*` markers first
+- Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
+- Parse `--count N` parameter from user input (default: 3 if not specified)
+- Store decisions in `workflow-session.json` including count parameter
+
+### Phase 0: Automatic Project Context Collection
+
+**Goal**: Gather project architecture, documentation, and relevant code context BEFORE user interaction
+
+**Detection Mechanism** (execute first):
 ```javascript
-// If roles = ["ui-designer", "system-architect"]
-Generate:
-- UI Designer section: UI Requirements, UX Challenges
-- System Architect section: Architecture Decisions, Technical Implementation
-- Integration Points: UI↔Architecture dependencies
+// Check if context-package already exists
+const contextPackagePath = `.workflow/WFS-{session-id}/.process/context-package.json`;
+
+if (file_exists(contextPackagePath)) {
+  // Validate package
+  const package = Read(contextPackagePath);
+  if (package.metadata.session_id === session_id) {
+    console.log("✅ Valid context-package found, skipping Phase 0");
+    return; // Skip to Phase 1
+  }
+}
 ```
 
-### Framework Generation Examples
+**Implementation**: Invoke `context-search-agent` only if package doesn't exist
 
-#### Example 1: Architecture-Heavy Topic
-```bash
-/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,subject-matter-expert"
+```javascript
+Task(
+  subagent_type="context-search-agent",
+  description="Gather project context for brainstorm",
+  prompt=`
+You are executing as context-search-agent (.claude/agents/context-search-agent.md).
+
+## Execution Mode
+**BRAINSTORM MODE** (Lightweight) - Phase 1-2 only (skip deep analysis)
+
+## Session Information
+- **Session ID**: ${session_id}
+- **Task Description**: ${task_description}
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
+
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
+
+### Phase 1: Initialization & Pre-Analysis
+1. **Detection**: Check for existing context-package (early exit if valid)
+2. **Foundation**: Initialize code-index, get project structure, load docs
+3. **Analysis**: Extract keywords, determine scope, classify complexity
+
+### Phase 2: Multi-Source Context Discovery
+Execute all 3 discovery tracks:
+- **Track 1**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. Synthesize 3-source data (docs > code > web)
+3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+4. Perform conflict detection with risk assessment
+5. Generate and validate context-package.json
+
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy}
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] File relevance accuracy >80%
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files ≤50 (prioritize high-relevance)
+
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
+)
 ```
-**Generated framework focuses on**:
-- Service architecture and communication patterns
-- Data flow and storage strategies
-- Domain standards and best practices
 
-#### Example 2: User-Focused Topic
-```bash
-/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,ux-expert,product-manager"
+**Graceful Degradation**:
+- If agent fails: Log warning, continue to Phase 1 without project context
+- If package invalid: Re-run context-search-agent
+
+### Phase 1: Topic Analysis & Intent Classification
+
+**Goal**: Extract keywords/challenges to drive all subsequent question generation, **enriched by Phase 0 project context**
+
+**Steps**:
+1. **Load Phase 0 context** (if available):
+   - Read `.workflow/WFS-{session-id}/.process/context-package.json`
+   - Extract: tech_stack, existing modules, conflict_risk, relevant files
+
+2. **Deep topic analysis** (context-aware):
+   - Extract technical entities from topic + existing codebase
+   - Identify core challenges considering existing architecture
+   - Consider constraints (timeline/budget/compliance)
+   - Define success metrics based on current project state
+
+3. **Generate 2-4 context-aware probing questions**:
+   - Reference existing tech stack in questions
+   - Consider integration with existing modules
+   - Address identified conflict risks from Phase 0
+   - Target root challenges and trade-off priorities
+
+4. **User interaction**: Output questions using text format (see User Interaction Protocol), wait for user input
+
+5. **Parse user answers**: Use intelligent parsing to extract answers from user input (support multiple formats)
+
+6. **Storage**: Store answers to `session.intent_context` with `{extracted_keywords, identified_challenges, user_answers, project_context_used}`
+
+**Example Output**:
+```markdown
+===== Phase 1: 项目意图分析 =====
+
+【问题1 - 核心挑战】实时协作平台的主要技术挑战？
+a) 实时数据同步
+   说明：100+用户同时在线，状态同步复杂度高
+b) 可扩展性架构
+   说明：用户规模增长时的系统扩展能力
+c) 冲突解决机制
+   说明：多用户同时编辑的冲突处理策略
+
+【问题2 - 优先级】MVP阶段最关注的指标？
+a) 功能完整性
+   说明：实现所有核心功能
+b) 用户体验
+   说明：流畅的交互体验和响应速度
+c) 系统稳定性
+   说明：高可用性和数据一致性
+
+请回答 (格式: 1a 2b)：
 ```
-**Generated framework focuses on**:
-- Onboarding flow and UI components
-- User experience optimization and usability
-- Business value and success metrics
 
-#### Example 3: Agile Delivery Topic
-```bash
-/workflow:brainstorm:artifacts "Optimize sprint delivery process" --roles "scrum-master,product-owner,test-strategist"
+**User input examples**:
+- `1a 2c` → Q1:a, Q2:c
+- `1a,2c` → Q1:a, Q2:c
+
+**⚠️ CRITICAL**: Questions MUST reference topic keywords. Generic "Project type?" violates dynamic generation.
+
+### Phase 2: Role Selection
+
+**⚠️ CRITICAL**: User MUST interact to select roles. NEVER auto-select without user confirmation.
+
+**Available Roles**:
+- data-architect (数据架构师)
+- product-manager (产品经理)
+- product-owner (产品负责人)
+- scrum-master (敏捷教练)
+- subject-matter-expert (领域专家)
+- system-architect (系统架构师)
+- test-strategist (测试策略师)
+- ui-designer (UI 设计师)
+- ux-expert (UX 专家)
+
+**Steps**:
+1. **Intelligent role recommendation** (AI analysis):
+   - Analyze Phase 1 extracted keywords and challenges
+   - Use AI reasoning to determine most relevant roles for the specific topic
+   - Recommend count+2 roles (e.g., if user wants 3 roles, recommend 5 options)
+   - Provide clear rationale for each recommended role based on topic context
+
+2. **User selection** (text interaction):
+   - Output all recommended roles at once (no batching needed for count+2 roles)
+   - Display roles with labels and relevance rationale
+   - Wait for user input in multi-select format
+   - Parse user input (support multiple formats)
+   - **Storage**: Store selections to `session.selected_roles`
+
+**Example Output**:
+```markdown
+===== Phase 2: 角色选择 =====
+
+【角色选择】请选择 3 个角色参与头脑风暴分析
+
+a) system-architect (系统架构师)
+   推荐理由：实时同步架构设计和技术选型的核心角色
+b) ui-designer (UI设计师)
+   推荐理由：协作界面用户体验和实时状态展示
+c) product-manager (产品经理)
+   推荐理由：功能优先级和MVP范围决策
+d) data-architect (数据架构师)
+   推荐理由：数据同步模型和存储方案设计
+e) ux-expert (UX专家)
+   推荐理由：多用户协作交互流程优化
+
+支持格式：
+- 分别选择：2a 2c 2d (选择a、c、d)
+- 合并语法：2acd (选择a、c、d)
+- 逗号分隔：2a,c,d (选择a、c、d)
+
+请输入选择：
 ```
-**Generated framework focuses on**:
-- Sprint planning and team collaboration
-- Backlog management and prioritization
-- Quality assurance and testing strategies
 
-#### Example 4: Comprehensive Analysis
-```bash
-/workflow:brainstorm:artifacts "Build real-time collaboration feature"
+**User input examples**:
+- `2acd` → Roles: a, c, d (system-architect, product-manager, data-architect)
+- `2a 2c 2d` → Same result
+- `2a,c,d` → Same result
+
+**Role Recommendation Rules**:
+- NO hardcoded keyword-to-role mappings
+- Use intelligent analysis of topic, challenges, and requirements
+- Consider role synergies and coverage gaps
+- Explain WHY each role is relevant to THIS specific topic
+- Default recommendation: count+2 roles for user to choose from
+
+### Phase 3: Role-Specific Questions (Dynamic Generation)
+
+**Goal**: Generate deep questions mapping role expertise to Phase 1 challenges
+
+**Algorithm**:
 ```
-**Generated framework covers** all aspects (no roles specified)
+FOR each selected role:
+  1. Map Phase 1 challenges to role domain:
+     - "real-time sync" + system-architect → State management pattern
+     - "100 users" + system-architect → Communication protocol
+     - "low latency" + system-architect → Conflict resolution
 
-## Session Management ⚠️ CRITICAL
-- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before processing
-- **Multiple sessions support**: Different Claude instances can have different active sessions
-- **User selection**: If multiple active sessions found, prompt user to select which one to work with
-- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
-- **Session continuity**: MUST use selected active session for all processing
-- **Context preservation**: All discussion and analysis stored in session directory
-- **Session isolation**: Each session maintains independent state
+  2. Generate 3-4 questions per role probing implementation depth, trade-offs, edge cases:
+     Q: "How handle real-time state sync for 100+ users?" (explores approach)
+     Q: "How resolve conflicts when 2 users edit simultaneously?" (explores edge case)
+     Options: [Event Sourcing/Centralized/CRDT] (concrete, explain trade-offs for THIS use case)
 
-## Discussion Areas
+  3. Output questions in text format per role:
+     - Display all questions for current role (3-4 questions, no 10-question limit)
+     - Questions in Chinese (用中文提问)
+     - Wait for user input
+     - Parse answers using intelligent parsing
+     - Store answers to session.role_decisions[role]
+```
 
-### Core Investigation Topics
-- **Purpose & Goals**: What are we trying to achieve?
-- **Scope & Boundaries**: What's included and excluded?
-- **Success Criteria**: How do we measure success?
-- **Constraints**: What limitations exist?
-- **Stakeholders**: Who is affected or involved?
+**Batching Strategy**:
+- Each role outputs all its questions at once (typically 3-4 questions)
+- No need to split per role (within 10-question batch limit)
+- Multiple roles processed sequentially (one role at a time for clarity)
 
-### Technical Considerations
-- **Requirements**: What must the solution provide?
-- **Dependencies**: What does it rely on?
-- **Integration**: How does it connect to existing systems?
-- **Performance**: What are the speed/scale requirements?
-- **Security**: What protection is needed?
+**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format)
 
-### Implementation Factors
-- **Timeline**: When is it needed?
-- **Resources**: What people/budget/tools are available?
-- **Risks**: What could go wrong?
-- **Alternatives**: What other approaches exist?
-- **Migration**: How do we transition from current state?
+**Example Topic-Specific Questions** (system-architect role for "real-time collaboration platform"):
+- "100+ 用户实时状态同步方案?" → Options: Event Sourcing / 集中式状态管理 / CRDT
+- "两个用户同时编辑冲突如何解决?" → Options: 自动合并 / 手动解决 / 版本控制
+- "低延迟通信协议选择?" → Options: WebSocket / SSE / 轮询
+- "系统扩展性架构方案?" → Options: 微服务 / 单体+缓存 / Serverless
 
-## Update Mechanism ⚠️ SMART UPDATES
+**Quality Requirements**: See "Question Generation Guidelines" section for detailed rules
 
-### Framework Update Logic
-```bash
-# Check existing framework
-IF topic-framework.md EXISTS:
-    SHOW current framework to user
-    ASK: "Framework exists. Do you want to:"
-    OPTIONS:
-      1. "Replace completely" → Generate new framework
-      2. "Add discussion points" → Append to existing
-      3. "Refine existing points" → Interactive editing
-      4. "Cancel" → Exit without changes
+### Phase 4: Cross-Role Clarification (Conflict Detection)
+
+**Goal**: Resolve ACTUAL conflicts from Phase 3 answers, not pre-defined relationships
+
+**Algorithm**:
+```
+1. Analyze Phase 3 answers for conflicts:
+   - Contradictory choices: product-manager "fast iteration" vs system-architect "complex Event Sourcing"
+   - Missing integration: ui-designer "Optimistic updates" but system-architect didn't address conflict handling
+   - Implicit dependencies: ui-designer "Live cursors" but no auth approach defined
+
+2. FOR each detected conflict:
+   Generate clarification questions referencing SPECIFIC Phase 3 choices
+
+3. Output clarification questions in text format:
+   - Batch conflicts into rounds (max 10 questions per round)
+   - Display questions with context from Phase 3 answers
+   - Questions in Chinese (用中文提问)
+   - Wait for user input
+   - Parse answers using intelligent parsing
+   - Store answers to session.cross_role_decisions
+
+4. If NO conflicts: Skip Phase 4 (inform user: "未检测到跨角色冲突，跳过Phase 4")
+```
+
+**Batching Strategy**:
+- Maximum 10 clarification questions per round
+- If conflicts > 10, split into multiple rounds
+- Prioritize most critical conflicts first
+
+**Output Format**: Follow standard format from "User Interaction Protocol" section (single-choice question format with background context)
+
+**Example Conflict Detection** (from Phase 3 answers):
+- **Architecture Conflict**: "CRDT 与 UI 回滚期望冲突，如何解决?"
+  - Background: system-architect chose CRDT, ui-designer expects rollback UI
+  - Options: 采用 CRDT / 显示合并界面 / 切换到 OT
+- **Integration Gap**: "实时光标功能缺少身份认证方案"
+  - Background: ui-designer chose live cursors, no auth defined
+  - Options: OAuth 2.0 / JWT Token / Session-based
+
+**Quality Requirements**: See "Question Generation Guidelines" section for conflict-specific rules
+
+### Phase 5: Generate Guidance Specification
+
+**Steps**:
+1. Load all decisions: `intent_context` + `selected_roles` + `role_decisions` + `cross_role_decisions`
+2. Transform Q&A pairs to declarative: Questions → Headers, Answers → CONFIRMED/SELECTED statements
+3. Generate guidance-specification.md (template below) - **PRIMARY OUTPUT FILE**
+4. Update workflow-session.json with **METADATA ONLY**:
+   - session_id (e.g., "WFS-topic-slug")
+   - selected_roles[] (array of role names, e.g., ["system-architect", "ui-designer", "product-manager"])
+   - topic (original user input string)
+   - timestamp (ISO-8601 format)
+   - phase_completed: "artifacts"
+   - count_parameter (number from --count flag)
+5. Validate: No interrogative sentences in .md file, all decisions traceable, no content duplication in .json
+
+**⚠️ CRITICAL OUTPUT SEPARATION**:
+- **guidance-specification.md**: Full guidance content (decisions, rationale, integration points)
+- **workflow-session.json**: Session metadata ONLY (no guidance content, no decisions, no Q&A pairs)
+- **NO content duplication**: Guidance stays in .md, metadata stays in .json
+
+## Output Document Template
+
+**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
+
+```markdown
+# [Project] - Confirmed Guidance Specification
+
+**Metadata**: [timestamp, type, focus, roles]
+
+## 1. Project Positioning & Goals
+**CONFIRMED Objectives**: [from topic + Phase 1]
+**CONFIRMED Success Criteria**: [from Phase 1 answers]
+
+## 2-N. [Role] Decisions
+### SELECTED Choices
+**[Question topic]**: [User's answer]
+- **Rationale**: [From option description]
+- **Impact**: [Implications]
+
+### Cross-Role Considerations
+**[Conflict resolved]**: [Resolution from Phase 4]
+- **Affected Roles**: [Roles involved]
+
+## Cross-Role Integration
+**CONFIRMED Integration Points**: [API/Data/Auth from multiple roles]
+
+## Risks & Constraints
+**Identified Risks**: [From answers] → Mitigation: [Approach]
+
+## Next Steps
+**⚠️ Automatic Continuation** (when called from auto-parallel):
+- auto-parallel will assign agents to generate role-specific analysis documents
+- Each selected role gets dedicated conceptual-planning-agent
+- Agents read this guidance-specification.md for framework context
+
+## Appendix: Decision Tracking
+| Decision ID | Category | Question | Selected | Phase | Rationale |
+|-------------|----------|----------|----------|-------|-----------|
+| D-001 | Intent | [Q] | [A] | 1 | [Why] |
+| D-002 | Roles | [Selected] | [Roles] | 2 | [Why] |
+| D-003+ | [Role] | [Q] | [A] | 3 | [Why] |
+```
+
+## Question Generation Guidelines
+
+### Core Principle: Developer-Facing Questions with User Context
+
+**Target Audience**: 开发者（理解技术但需要从用户需求出发）
+
+**Generation Philosophy**:
+1. **Phase 1**: 用户场景、业务约束、优先级（建立上下文）
+2. **Phase 2**: 基于话题分析的智能角色推荐（非关键词映射）
+3. **Phase 3**: 业务需求 + 技术选型（需求驱动的技术决策）
+4. **Phase 4**: 技术冲突的业务权衡（帮助开发者理解影响）
+
+### Universal Quality Rules
+
+**Question Structure** (all phases):
+```
+[业务场景/需求前提] + [技术关注点]
+```
+
+**Option Structure** (all phases):
+```
+标签：[技术方案简称] + (业务特征)
+说明：[业务影响] + [技术权衡]
+```
+
+**MUST Include** (all phases):
+- ✅ All questions in Chinese (用中文提问)
+- ✅ 业务场景作为问题前提
+- ✅ 技术选项的业务影响说明
+- ✅ 量化指标和约束条件
+
+**MUST Avoid** (all phases):
+- ❌ 纯技术选型无业务上下文
+- ❌ 过度抽象的用户体验问题
+- ❌ 脱离话题的通用架构问题
+
+### Phase-Specific Requirements
+
+**Phase 1 Requirements**:
+- Questions MUST reference topic keywords (NOT generic "Project type?")
+- Focus: 用户使用场景（谁用？怎么用？多频繁？）、业务约束（预算、时间、团队、合规）
+- Success metrics: 性能指标、用户体验目标
+- Priority ranking: MVP vs 长期规划
+
+**Phase 3 Requirements**:
+- Questions MUST reference Phase 1 keywords (e.g., "real-time", "100 users")
+- Options MUST be concrete approaches with relevance to topic
+- Each option includes trade-offs specific to this use case
+- Include 业务需求驱动的技术问题、量化指标（并发数、延迟、可用性）
+
+**Phase 4 Requirements**:
+- Questions MUST reference SPECIFIC Phase 3 choices in background context
+- Options address the detected conflict directly
+- Each option explains impact on both conflicting roles
+- NEVER use static "Cross-Role Matrix" - ALWAYS analyze actual Phase 3 answers
+- Focus: 技术冲突的业务权衡、帮助开发者理解不同选择的影响
+
+## Validation Checklist
+
+Generated guidance-specification.md MUST:
+- ✅ No interrogative sentences (use CONFIRMED/SELECTED)
+- ✅ Every decision traceable to user answer
+- ✅ Cross-role conflicts resolved or documented
+- ✅ Next steps concrete and specific
+- ✅ All Phase 1-4 decisions in session metadata
+
+## Update Mechanism
+
+```
+IF guidance-specification.md EXISTS:
+  Prompt: "Regenerate completely / Update sections / Cancel"
 ELSE:
-    CREATE new framework
+  Run full Phase 1-5 flow
 ```
 
-### Update Strategies
+## Governance Rules
 
-**1. Complete Replacement**
-- Backup existing framework as `topic-framework-[timestamp].md.backup`
-- Generate completely new framework
-- Preserve role-specific analysis points from previous version
+**Output Requirements**:
+- All decisions MUST use CONFIRMED/SELECTED (NO "?" in decision sections)
+- Every decision MUST trace to user answer
+- Conflicts MUST be resolved (not marked "TBD")
+- Next steps MUST be actionable
+- Topic preserved as authoritative reference in session
 
-**2. Incremental Addition**
-- Load existing framework
-- Identify new discussion areas through user interaction
-- Add new sections while preserving existing structure
-- Update framework usage instructions
+**CRITICAL**: Guidance is single source of truth for downstream phases. Ambiguity violates governance.
 
-**3. Refinement Mode**
-- Interactive editing of existing discussion points
-- Allow modification of scope, objectives, and questions
-- Preserve framework structure and role assignments
-- Update timestamp and version info
+## Storage Validation
 
-### Version Control
-- **Backup Creation**: Always backup before major changes
-- **Change Tracking**: Include change summary in framework footer
-- **Rollback Support**: Keep previous version accessible
+**workflow-session.json** (metadata only):
+```json
+{
+  "session_id": "WFS-{topic-slug}",
+  "type": "brainstorming",
+  "topic": "{original user input}",
+  "selected_roles": ["system-architect", "ui-designer", "product-manager"],
+  "phase_completed": "artifacts",
+  "timestamp": "2025-10-24T10:30:00Z",
+  "count_parameter": 3
+}
+```
 
-## Error Handling
-- **Session creation failure**: Provide clear error message and retry option
-- **Discussion stalling**: Offer structured prompts to continue exploration
-- **Documentation issues**: Graceful handling of file creation problems
-- **Missing context**: Prompt for additional information when needed
+**⚠️ Rule**: Session JSON stores ONLY metadata (session_id, selected_roles[], topic, timestamps). All guidance content goes to guidance-specification.md.
 
-## Reference Information
+## File Structure
 
-### File Structure Reference
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
-**Session Management**: Standard workflow session protocols
+```
+.workflow/WFS-[topic]/
+├── .active-brainstorming
+├── workflow-session.json              # Session metadata ONLY
+└── .brainstorming/
+    └── guidance-specification.md      # Full guidance content
+```
 
-### Integration Points
-- **Compatible with**: Other brainstorming commands in the same session
-- **Builds foundation for**: More detailed planning and implementation phases
-- **Outputs used by**: `/workflow:brainstorm:synthesis` command for cross-analysis integration

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

@@ -1,330 +1,340 @@
 ---
 name: auto-parallel
 description: Parallel brainstorming automation with dynamic role selection and concurrent execution
-usage: /workflow:brainstorm:auto-parallel "<topic>"
-argument-hint: "topic or challenge description"
-examples:
-  - /workflow:brainstorm:auto-parallel "Build real-time collaboration feature"
-  - /workflow:brainstorm:auto-parallel "Optimize database performance for millions of users"
-  - /workflow:brainstorm:auto-parallel "Implement secure authentication system"
+argument-hint: "topic or challenge description" [--count N]
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
 # Workflow Brainstorm Parallel Auto Command
 
+## Coordinator Role
+
+**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
+
+**Execution Model - Auto-Continue Workflow**:
+
+This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
+
+1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
+2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
+3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
+4. **Phase 3 executes** → Synthesis command → Reports final summary
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status
+- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
+- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
+- Progress updates shown at each phase for visibility
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
+2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
+3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
+6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
+
 ## Usage
-```bash
-/workflow:brainstorm:auto-parallel "<topic>"
-```
-
-## Role Selection Logic
-- **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert, subject-matter-expert
-- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, user-researcher, product-manager, ux-expert, product-owner
-- **Business & Process**: `business|process|workflow|cost|innovation|testing` → business-analyst, innovation-lead, test-strategist
-- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
-- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Multi-role**: Complex topics automatically select 2-3 complementary roles
-- **Default**: `product-manager` if no clear match
-
-**Template Loading**: `bash($(cat "~/.claude/workflows/cli-templates/planning-roles/<role-name>.md"))`
-**Template Source**: `.claude/workflows/cli-templates/planning-roles/`
-**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
-
-**Example**:
-```bash
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/system-architect.md"))
-bash($(cat "~/.claude/workflows/cli-templates/planning-roles/ui-designer.md"))
-```
-
-## Core Workflow
-
-### Structured Topic Processing → Role Analysis → Synthesis
-The command follows a structured three-phase approach with dedicated document types:
-
-**Phase 1: Framework Generation** ⚠️ COMMAND EXECUTION
-- **Role selection**: Auto-select 2-3 roles based on topic keywords (see Role Selection Logic)
-- **Call artifacts command**: Execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"` using SlashCommand tool
-- **Role-specific framework**: Generate framework with sections tailored to selected roles
-
-**Phase 2: Role Analysis Execution** ⚠️ PARALLEL AGENT ANALYSIS
-- **Parallel execution**: Multiple roles execute simultaneously for faster completion
-- **Independent agents**: Each role gets dedicated conceptual-planning-agent running in parallel
-- **Shared framework**: All roles reference the same topic framework for consistency
-- **Concurrent generation**: Role-specific analysis documents generated simultaneously
-- **Progress tracking**: Parallel agents update progress independently
-
-**Phase 3: Synthesis Generation** ⚠️ COMMAND EXECUTION
-- **Call synthesis command**: Execute `/workflow:brainstorm:synthesis` using SlashCommand tool
-
-## Implementation Standards
-
-### Simplified Command Orchestration ⚠️ STREAMLINED
-Auto command coordinates independent specialized commands:
-
-**Command Sequence**:
-1. **Role Selection**: Auto-select 2-3 relevant roles based on topic keywords
-2. **Generate Role-Specific Framework**: Use SlashCommand to execute `/workflow:brainstorm:artifacts "{topic}" --roles "{role1,role2,role3}"`
-3. **Parallel Role Analysis**: Execute selected role agents in parallel, each reading their specific framework section
-4. **Generate Synthesis**: Use SlashCommand to execute `/workflow:brainstorm:synthesis`
-
-**SlashCommand Integration**:
-1. **artifacts command**: Called via SlashCommand tool with `--roles` parameter for role-specific framework generation
-2. **role agents**: Each agent reads its dedicated section in the role-specific framework
-3. **synthesis command**: Called via SlashCommand tool for final integration with role-targeted insights
-4. **Command coordination**: SlashCommand handles execution and validation
-
-**Role Selection Logic**:
-- **Technical**: `architecture|system|performance|database` → system-architect, data-architect, subject-matter-expert
-- **Product & UX**: `user|ui|ux|interface|design|product|feature|experience` → ui-designer, ux-expert, product-manager, product-owner
-- **Agile & Delivery**: `agile|sprint|scrum|team|collaboration|delivery` → scrum-master, product-owner
-- **Domain Expertise**: `domain|standard|compliance|expertise|regulation` → subject-matter-expert
-- **Auto-select**: 2-3 most relevant roles based on topic analysis
-
-### Simplified Processing Standards
-
-**Core Principles**:
-1. **Minimal preprocessing** - Only workflow-session.json and basic role selection
-2. **Agent autonomy** - Agents handle their own context and validation
-3. **Parallel execution** - Multiple agents can work simultaneously
-4. **Post-processing synthesis** - Integration happens after agent completion
-5. **TodoWrite control** - Progress tracking throughout all phases
-
-**Implementation Rules**:
-- **Maximum 3 roles**: Auto-selected based on simple keyword mapping
-- **No upfront validation**: Agents handle their own context requirements
-- **Parallel execution**: Each agent operates concurrently without dependencies
-- **Synthesis at end**: Integration only after all agents complete
-
-**Agent Self-Management** (Agents decide their own approach):
-- **Context gathering**: Agents determine what questions to ask
-- **Template usage**: Agents load and apply their own role templates
-- **Analysis depth**: Agents determine appropriate level of detail
-- **Documentation**: Agents create their own file structure and content
-
-### Session Management ⚠️ CRITICAL
-- **⚡ FIRST ACTION**: Check for all `.workflow/.active-*` markers before role processing
-- **Multiple sessions support**: Different Claude instances can have different active brainstorming sessions
-- **User selection**: If multiple active sessions found, prompt user to select which one to work with
-- **Auto-session creation**: `WFS-[topic-slug]` only if no active session exists
-- **Session continuity**: MUST use selected active session for all role processing
-- **Context preservation**: Each role's context and agent output stored in session directory
-- **Session isolation**: Each session maintains independent brainstorming state and role assignments
-
-## Document Generation
-
-**Command Coordination Workflow**: artifacts → parallel role analysis → synthesis
-
-**Output Structure**: Coordinated commands generate framework, role analyses, and synthesis documents as defined in their respective command specifications.
-
-
-## Agent Prompt Templates
-
-### Task Agent Invocation Template
-
 
 ```bash
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: {role-name} perspective for {topic}
-
-     ## Role Assignment
-     **ASSIGNED_ROLE**: {role-name}
-     **TOPIC**: {user-provided-topic}
-     **OUTPUT_LOCATION**: .workflow/WFS-{topic}/.brainstorming/{role}/
-
-     ## Execution Instructions
-     [FLOW_CONTROL]
-
-     ### Flow Control Steps
-     **AGENT RESPONSIBILITY**: Execute these pre_analysis steps sequentially with context accumulation:
-
-     1. **load_topic_framework**
-        - Action: Load structured topic discussion framework
-        - Command: bash(cat .workflow/WFS-{topic}/.brainstorming/topic-framework.md 2>/dev/null || echo 'Topic framework not found')
-        - Output: topic_framework
-
-     2. **load_role_template**
-        - Action: Load {role-name} planning template
-        - Command: bash($(cat "~/.claude/workflows/cli-templates/planning-roles/{role}.md"))
-        - Output: role_template
-
-     3. **load_session_metadata**
-        - Action: Load session metadata and topic description
-        - Command: bash(cat .workflow/WFS-{topic}/workflow-session.json 2>/dev/null || echo '{}')
-        - Output: session_metadata
-
-     ### Implementation Context
-     **Topic Framework**: Use loaded topic-framework.md for structured analysis
-     **Role Focus**: {role-name} domain expertise and perspective
-     **Analysis Type**: Address framework discussion points from role perspective
-     **Template Framework**: Combine role template with topic framework structure
-     **Structured Approach**: Create analysis.md addressing all topic framework points
-
-     ### Session Context
-     **Workflow Directory**: .workflow/WFS-{topic}/.brainstorming/
-     **Output Directory**: .workflow/WFS-{topic}/.brainstorming/{role}/
-     **Session JSON**: .workflow/WFS-{topic}/workflow-session.json
-
-     ### Dependencies & Context
-     **Topic**: {user-provided-topic}
-     **Role Template**: "~/.claude/workflows/cli-templates/planning-roles/{role}.md"
-     **User Requirements**: To be gathered through interactive questioning
-
-     ## Completion Requirements
-     1. Execute all flow control steps in sequence (load topic framework, role template, session metadata)
-     2. **Address Topic Framework**: Respond to all discussion points in topic-framework.md from role perspective
-     3. Apply role template guidelines within topic framework structure
-     4. Generate structured role analysis addressing framework points
-     5. Create single comprehensive deliverable in OUTPUT_LOCATION:
-        - analysis.md (structured analysis addressing all topic framework points with role-specific insights)
-     6. Include framework reference: @../topic-framework.md in analysis.md
-     7. Update workflow-session.json with completion status",
-     description="Execute {role-name} brainstorming analysis")
+/workflow:brainstorm:auto-parallel "<topic>" [--count N]
 ```
 
-### Parallel Role Agent调用示例
+**Recommended Structured Format**:
 ```bash
-# Execute multiple roles in parallel using single message with multiple Task calls
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: system-architect perspective for {topic}...",
-     description="Execute system-architect brainstorming analysis")
-
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: ui-designer perspective for {topic}...",
-     description="Execute ui-designer brainstorming analysis")
-
-Task(subagent_type="conceptual-planning-agent",
-     prompt="Execute brainstorming analysis: security-expert perspective for {topic}...",
-     description="Execute security-expert brainstorming analysis")
+/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
 ```
 
-### Direct Synthesis Process (Command-Driven)
-**Synthesis execution**: Use SlashCommand to execute `/workflow:brainstorm:synthesis` after role completion
+**Parameters**:
+- `topic` (required): Topic or challenge description (structured format recommended)
+- `--count N` (optional): Number of roles to select (default: 3, max: 9)
 
+## 3-Phase Execution
 
-## TodoWrite Control Flow ⚠️ CRITICAL
+### Phase 1: Interactive Framework Generation
 
-### Workflow Progress Tracking
-**MANDATORY**: Use Claude Code's built-in TodoWrite tool throughout entire brainstorming workflow:
+**Command**: `SlashCommand(command="/workflow:brainstorm:artifacts \"{topic}\" --count {N}")`
+
+**What It Does**:
+- Topic analysis: Extract challenges, generate task-specific questions
+- Role selection: Recommend count+2 roles, user selects via AskUserQuestion
+- Role questions: Generate 3-4 questions per role, collect user decisions
+- Conflict resolution: Detect and resolve cross-role conflicts
+- Guidance generation: Transform Q&A to declarative guidance-specification.md
+
+**Parse Output**:
+- **⚠️ Memory Check**: If `selected_roles[]` already in conversation memory from previous load, skip file read
+- Extract: `selected_roles[]` from workflow-session.json (if not in memory)
+- Extract: `session_id` from workflow-session.json (if not in memory)
+- Verify: guidance-specification.md exists
+
+**Validation**:
+- guidance-specification.md created with confirmed decisions
+- workflow-session.json contains selected_roles[] (metadata only, no content duplication)
+- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
+
+**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
+- Marking parent task "Execute artifacts..." as in_progress
+- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
+- PRESERVING all other auto-parallel tasks (role agents, synthesis)
+- When artifacts Phase 5 completes, marking parent task as completed
+
+---
+
+### Phase 2: Parallel Role Analysis Execution
+
+**For Each Selected Role**:
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute {role-name} analysis for existing topic framework
+
+## Context Loading
+ASSIGNED_ROLE: {role-name}
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/{role}/
+TOPIC: {user-provided-topic}
+
+## Flow Control Steps
+1. **load_topic_framework**
+   - Action: Load structured topic discussion framework
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
+   - Output: topic_framework_content
+
+2. **load_role_template**
+   - Action: Load {role-name} planning template
+   - Command: Read(~/.claude/workflows/cli-templates/planning-roles/{role}.md)
+   - Output: role_template_guidelines
+
+3. **load_session_metadata**
+   - Action: Load session metadata and original user intent
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Output: session_context (contains original user prompt as PRIMARY reference)
+
+## Analysis Requirements
+**Primary Reference**: Original user prompt from workflow-session.json is authoritative
+**Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
+**Role Focus**: {role-name} domain expertise aligned with user intent
+**Structured Approach**: Create analysis.md addressing framework discussion points
+**Template Integration**: Apply role template guidelines within framework structure
+
+## Expected Deliverables
+1. **analysis.md**: Comprehensive {role-name} analysis addressing all framework discussion points
+   - **File Naming**: MUST start with `analysis` prefix (e.g., `analysis.md`, `analysis-1.md`, `analysis-2.md`)
+   - **FORBIDDEN**: Never use `recommendations.md` or any filename not starting with `analysis`
+   - **Auto-split if large**: If content >800 lines, split to `analysis-1.md`, `analysis-2.md` (max 3 files: analysis.md, analysis-1.md, analysis-2.md)
+   - **Content**: Includes both analysis AND recommendations sections within analysis files
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
+3. **User Intent Alignment**: Validate analysis aligns with original user objectives from session_context
+
+## Completion Criteria
+- Address each discussion point from guidance-specification.md with {role-name} expertise
+- Provide actionable recommendations from {role-name} perspective within analysis files
+- All output files MUST start with `analysis` prefix (no recommendations.md or other naming)
+- Reference framework document using @ notation for integration
+- Update workflow-session.json with completion status
+"
+```
+
+**Parallel Execution**:
+- Launch N agents simultaneously (one message with multiple Task calls)
+- Each agent operates independently reading same guidance-specification.md
+- All agents update progress concurrently
+
+**Input**:
+- `selected_roles[]` from Phase 1
+- `session_id` from Phase 1
+- guidance-specification.md path
+
+**Validation**:
+- Each role creates `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
+- If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
+- **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing)
+- **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
+- All N role analyses completed
+
+**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
+
+**After Phase 2**: Auto-continue to Phase 3 (synthesis)
+
+---
+
+### Phase 3: Synthesis Generation
+
+**Command**: `SlashCommand(command="/workflow:brainstorm:synthesis --session {sessionId}")`
+
+**What It Does**:
+- Load original user intent from workflow-session.json
+- Read all role analysis.md files
+- Integrate role insights into synthesis-specification.md
+- Validate alignment with user's original objectives
+
+**Input**: `sessionId` from Phase 1
+
+**Validation**:
+- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
+- Synthesis references all role analyses
+
+**TodoWrite**: Mark phase 3 completed
+
+**Return to User**:
+```
+Brainstorming complete for session: {sessionId}
+Roles analyzed: {count}
+Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
+
+✅ Next Steps:
+1. /workflow:concept-clarify --session {sessionId}  # Optional refinement
+2. /workflow:plan --session {sessionId}  # Generate implementation plan
+```
+
+## TodoWrite Pattern
 
 ```javascript
-// Phase 1: Create initial todo list for command-coordinated brainstorming workflow
-TodoWrite({
-  todos: [
-    {
-      content: "Initialize brainstorming session and detect active sessions",
-      status: "pending",
-      activeForm: "Initializing brainstorming session"
-    },
-    {
-      content: "Select roles based on topic keyword analysis",
-      status: "pending",
-      activeForm: "Selecting roles for brainstorming analysis"
-    },
-    {
-      content: "Execute artifacts command with selected roles for role-specific framework",
-      status: "pending",
-      activeForm: "Generating role-specific topic framework"
-    },
-    {
-      content: "Execute [role-1] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      status: "pending",
-      activeForm: "Executing [role-1] structured framework analysis"
-    },
-    {
-      content: "Execute [role-2] analysis [conceptual-planning-agent] [FLOW_CONTROL] addressing framework",
-      status: "pending",
-      activeForm: "Executing [role-2] structured framework analysis"
-    },
-    {
-      content: "Execute synthesis command using SlashCommand for final integration",
-      status: "pending",
-      activeForm: "Executing synthesis command for integrated analysis"
-    }
-  ]
-});
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
+  // Role agent tasks added dynamically after Phase 1 based on selected_roles count
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
 
-// Phase 2: Update status as workflow progresses - ONLY ONE task should be in_progress at a time
-TodoWrite({
-  todos: [
-    {
-      content: "Initialize brainstorming session and detect active sessions",
-      status: "completed",  // Mark completed preprocessing
-      activeForm: "Initializing brainstorming session"
-    },
-    {
-      content: "Select roles for topic analysis and create workflow-session.json",
-      status: "in_progress",  // Mark current task as in_progress
-      activeForm: "Selecting roles and creating session metadata"
-    },
-    // ... other tasks remain pending
-  ]
-});
+// After Phase 1 (artifacts completes, roles loaded)
+// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
+TodoWrite({todos: [
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
+  // ... (N role tasks based on --count parameter)
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
 
-// Phase 3: Parallel agent execution tracking
-TodoWrite({
-  todos: [
-    // ... previous completed tasks
-    {
-      content: "Execute system-architect analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing system-architect brainstorming analysis"
-    },
-    {
-      content: "Execute ui-designer analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing ui-designer brainstorming analysis"
-    },
-    {
-      content: "Execute security-expert analysis [conceptual-planning-agent] [FLOW_CONTROL]",
-      status: "in_progress",  // Executing in parallel
-      activeForm: "Executing security-expert brainstorming analysis"
-    }
-  ]
-});
+// After Phase 2 (all agents launched in parallel)
+TodoWrite({todos: [
+  // ... previous completed tasks
+  {"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  // ... (all N agents in_progress simultaneously)
+  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]})
+
+// After Phase 2 (all agents complete)
+TodoWrite({todos: [
+  // ... previous completed tasks
+  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
+  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
+  {"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
+]})
 ```
 
-**TodoWrite Integration Rules**:
-1. **Create initial todos**: All workflow phases at start
-2. **Mark in_progress**: Multiple parallel tasks can be in_progress simultaneously
-3. **Update immediately**: After each task completion
-4. **Track agent execution**: Include [agent-type] and [FLOW_CONTROL] markers for parallel agents
-5. **Final synthesis**: Mark synthesis as in_progress only after all parallel agents complete
+## Input Processing
+
+**Count Parameter Parsing**:
+```javascript
+// Extract --count from user input
+IF user_input CONTAINS "--count":
+    EXTRACT count_value FROM "--count N" pattern
+    IF count_value > 9:
+        count_value = 9  // Cap at maximum 9 roles
+ELSE:
+    count_value = 3  // Default to 3 roles
+
+// Pass to artifacts command
+EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
+```
+
+**Topic Structuring**:
+1. **Already Structured** → Pass directly to artifacts
+   ```
+   User: "GOAL: Build platform SCOPE: 100 users CONTEXT: Real-time"
+   → Pass as-is to artifacts
+   ```
+
+2. **Simple Text** → Pass directly (artifacts handles structuring)
+   ```
+   User: "Build collaboration platform"
+   → artifacts will analyze and structure
+   ```
+
+## Session Management
+
+**⚡ FIRST ACTION**: Check for `.workflow/.active-*` markers before Phase 1
+
+**Multiple Sessions Support**:
+- Different Claude instances can have different active brainstorming sessions
+- If multiple active sessions found, prompt user to select
+- If single active session found, use it
+- If no active session exists, create `WFS-[topic-slug]`
+
+**Session Continuity**:
+- MUST use selected active session for all phases
+- Each role's context stored in session directory
+- Session isolation: Each session maintains independent state
+
+## Output Structure
+
+**Phase 1 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
+- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
+
+**Phase 2 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
+
+**Phase 3 Output**:
+- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
+
+**⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
+
+## Available Roles
+
+- data-architect (数据架构师)
+- product-manager (产品经理)
+- product-owner (产品负责人)
+- scrum-master (敏捷教练)
+- subject-matter-expert (领域专家)
+- system-architect (系统架构师)
+- test-strategist (测试策略师)
+- ui-designer (UI 设计师)
+- ux-expert (UX 专家)
+
+**Role Selection**: Handled by artifacts command (intelligent recommendation + user selection)
+
+## Error Handling
+
+- **Role selection failure**: artifacts defaults to product-manager with explanation
+- **Agent execution failure**: Agent-specific retry with minimal dependencies
+- **Template loading issues**: Agent handles graceful degradation
+- **Synthesis conflicts**: Synthesis highlights disagreements without resolution
 
 ## Reference Information
 
-### Structured Processing Schema
-Each role processing follows structured framework pattern:
-- **topic_framework**: Structured discussion framework document
-- **role**: Selected planning role name with framework reference
-- **agent**: Dedicated conceptual-planning-agent instance
-- **structured_analysis**: Agent addresses all framework discussion points
-- **output**: Role-specific analysis.md addressing topic framework structure
+**File Structure**:
+```
+.workflow/WFS-[topic]/
+├── .active-brainstorming
+├── workflow-session.json              # Session metadata ONLY
+└── .brainstorming/
+    ├── guidance-specification.md      # Framework (Phase 1)
+    ├── {role-1}/
+    │   └── analysis.md                # Role analysis (Phase 2)
+    ├── {role-2}/
+    │   └── analysis.md
+    ├── {role-N}/
+    │   └── analysis.md
+    └── synthesis-specification.md     # Integration (Phase 3)
+```
 
-### File Structure Reference
-**Architecture**: @~/.claude/workflows/workflow-architecture.md
-**Role Templates**: @~/.claude/workflows/cli-templates/planning-roles/
+**Template Source**: `~/.claude/workflows/cli-templates/planning-roles/`
 
-### Execution Integration
-Command coordination model: artifacts command → parallel role analysis → synthesis command
-
-
-## Error Handling
-- **Role selection failure**: Default to `product-manager` with explanation
-- **Agent execution failure**: Agent-specific retry with minimal dependencies
-- **Template loading issues**: Agent handles graceful degradation
-- **Synthesis conflicts**: Synthesis agent highlights disagreements without resolution
-
-## Quality Standards
-
-### Agent Autonomy Excellence
-- **Single role focus**: Each agent handles exactly one role independently
-- **Self-contained execution**: Agent manages own context, validation, and output
-- **Parallel processing**: Multiple agents can execute simultaneously
-- **Complete ownership**: Agent produces entire role-specific analysis package
-
-### Minimal Coordination Excellence
-- **Lightweight handoff**: Only topic and role assignment provided
-- **Agent self-management**: Agents handle their own workflow and validation
-- **Concurrent operation**: No inter-agent dependencies enabling parallel execution
-- **Reference-based synthesis**: Post-processing integration without content duplication
-- **TodoWrite orchestration**: Progress tracking and workflow control throughout entire process

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

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

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

@@ -1,22 +1,17 @@
 ---
 name: data-architect
-description: Generate or update data-architect/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:data-architect [topic]
+description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:data-architect
-  - /workflow:brainstorm:data-architect "user analytics data pipeline"
-  - /workflow:brainstorm:data-architect "real-time data processing system"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 📊 **Data Architect Analysis Generator**
 
 ### Purpose
-**Specialized command for generating data-architect/analysis.md** that addresses topic-framework.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating data-architect/analysis.md** that addresses guidance-specification.md discussion points from data architecture perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Data Architecture Focus**: Data models, pipelines, governance, and analytics perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -27,6 +22,26 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Data Quality Management**: Data accuracy, completeness, and consistency
 - **Analytics and Insights**: Data analysis and business intelligence solutions
 
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Canonical Data Model - Source of Truth)**
+- **Canonical Data Model**: The authoritative, system-wide data schema representing domain entities and relationships
+- **Entity-Relationship Design**: Defining entities, attributes, relationships, and constraints
+- **Data Normalization & Optimization**: Ensuring data integrity, reducing redundancy, and optimizing storage
+- **Database Schema Design**: Physical database structures, indexes, partitioning strategies
+- **Data Pipeline Architecture**: ETL/ELT processes, data warehousing, and analytics pipelines
+- **Data Governance**: Data quality standards, retention policies, and compliance requirements
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **API Data Contracts**: Public-facing request/response schemas exposed by APIs → Defers to **API Designer**
+- **System Integration Patterns**: How services communicate at the macro level → Defers to **System Architect**
+- **UI Data Presentation**: How data is displayed to users → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **TO API Designer**: Provides canonical data model that API Designer translates into public API data contracts (as projection/view)
+- **TO System Architect**: Provides data flow requirements and storage constraints to inform system design
+- **FROM System Architect**: Receives system-level integration requirements and scalability constraints
+
 ## ⚙️ **Execution Protocol**
 
 ### Phase 1: Session & Framework Detection
@@ -37,7 +52,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +93,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +107,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from data architecture perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from data architecture perspective
 **Role Focus**: Data models, pipelines, governance, analytics platforms
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive data architecture analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with data architecture expertise
+- Address each discussion point from guidance-specification.md with data architecture expertise
 - Provide data model designs, pipeline architectures, and governance strategies
 - Include scalability, performance, and quality considerations
 - Reference framework document using @ notation for integration
@@ -121,7 +136,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +164,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/data-architect/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +172,11 @@ TodoWrite({
 # Data Architect Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Data Architecture perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with data architecture expertise]
+[Address each point from guidance-specification.md with data architecture expertise]
 
 ### Core Requirements (from framework)
 [Data architecture perspective on requirements]
@@ -194,12 +209,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Data architecture insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,22 +1,17 @@
 ---
 name: product-manager
-description: Generate or update product-manager/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:product-manager [topic]
+description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:product-manager
-  - /workflow:brainstorm:product-manager "user authentication redesign"
-  - /workflow:brainstorm:product-manager "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🎯 **Product Manager Analysis Generator**
 
 ### Purpose
-**Specialized command for generating product-manager/analysis.md** that addresses topic-framework.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating product-manager/analysis.md** that addresses guidance-specification.md discussion points from product strategy perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Product Strategy Focus**: User needs, business value, and market positioning
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -37,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from product strategy perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from product strategy perspective
 **Role Focus**: User value, business impact, market positioning, product strategy
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive product strategy analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with product management expertise
+- Address each discussion point from guidance-specification.md with product management expertise
 - Provide actionable business strategies and user value propositions
 - Include market analysis and competitive positioning insights
 - Reference framework document using @ notation for integration
@@ -121,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/product-manager/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +152,11 @@ TodoWrite({
 # Product Manager Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Product Strategy perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with product management expertise]
+[Address each point from guidance-specification.md with product management expertise]
 
 ### Core Requirements (from framework)
 [Product strategy perspective on user needs and requirements]
@@ -194,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Product strategy insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,22 +1,17 @@
 ---
 name: product-owner
-description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:product-owner [topic]
+description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:product-owner
-  - /workflow:brainstorm:product-owner "user authentication redesign"
-  - /workflow:brainstorm:product-owner "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🎯 **Product Owner Analysis Generator**
 
 ### Purpose
-**Specialized command for generating product-owner/analysis.md** that addresses topic-framework.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating product-owner/analysis.md** that addresses guidance-specification.md discussion points from product backlog and feature prioritization perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Product Backlog Focus**: Feature prioritization, user stories, and acceptance criteria
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -37,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from product backlog and feature prioritization perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from product backlog and feature prioritization perspective
 **Role Focus**: Backlog management, stakeholder alignment, feature prioritization, acceptance criteria
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with product ownership expertise
+- Address each discussion point from guidance-specification.md with product ownership expertise
 - Provide actionable user stories and acceptance criteria definitions
 - Include feature prioritization and stakeholder alignment strategies
 - Reference framework document using @ notation for integration
@@ -121,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/product-owner/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +152,11 @@ TodoWrite({
 # Product Owner Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Product Backlog & Feature Prioritization perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with product ownership expertise]
+[Address each point from guidance-specification.md with product ownership expertise]
 
 ### Core Requirements (from framework)
 [User story formulation and backlog refinement perspective]
@@ -194,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Product ownership insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,22 +1,17 @@
 ---
 name: scrum-master
-description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:scrum-master [topic]
+description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:scrum-master
-  - /workflow:brainstorm:scrum-master "user authentication redesign"
-  - /workflow:brainstorm:scrum-master "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🎯 **Scrum Master Analysis Generator**
 
 ### Purpose
-**Specialized command for generating scrum-master/analysis.md** that addresses topic-framework.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating scrum-master/analysis.md** that addresses guidance-specification.md discussion points from agile process and team collaboration perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Agile Process Focus**: Sprint planning, team dynamics, and delivery optimization
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -37,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from agile process and team collaboration perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from agile process and team collaboration perspective
 **Role Focus**: Sprint planning, team dynamics, process optimization, delivery management
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with scrum mastery expertise
+- Address each discussion point from guidance-specification.md with scrum mastery expertise
 - Provide actionable sprint planning and team facilitation strategies
 - Include process optimization and impediment removal insights
 - Reference framework document using @ notation for integration
@@ -121,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/scrum-master/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +152,11 @@ TodoWrite({
 # Scrum Master Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Agile Process & Team Collaboration perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with scrum mastery expertise]
+[Address each point from guidance-specification.md with scrum mastery expertise]
 
 ### Core Requirements (from framework)
 [Sprint planning and iteration breakdown perspective]
@@ -194,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Agile process insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,22 +1,17 @@
 ---
 name: subject-matter-expert
-description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:subject-matter-expert [topic]
+description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:subject-matter-expert
-  - /workflow:brainstorm:subject-matter-expert "user authentication redesign"
-  - /workflow:brainstorm:subject-matter-expert "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🎯 **Subject Matter Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating subject-matter-expert/analysis.md** that addresses topic-framework.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating subject-matter-expert/analysis.md** that addresses guidance-specification.md discussion points from domain knowledge and technical expertise perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Domain Expertise Focus**: Deep technical knowledge, industry standards, and best practices
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -37,7 +32,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +73,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +87,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from domain expertise and technical standards perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from domain expertise and technical standards perspective
 **Role Focus**: Domain knowledge, technical standards, risk assessment, knowledge transfer
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive domain expertise analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with subject matter expertise
+- Address each discussion point from guidance-specification.md with subject matter expertise
 - Provide actionable technical standards and best practices recommendations
 - Include risk assessment and compliance considerations
 - Reference framework document using @ notation for integration
@@ -121,7 +116,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +144,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/subject-matter-expert/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +152,11 @@ TodoWrite({
 # Subject Matter Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: Domain Expertise & Technical Standards perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with subject matter expertise]
+[Address each point from guidance-specification.md with subject matter expertise]
 
 ### Core Requirements (from framework)
 [Domain-specific requirements and industry standards perspective]
@@ -194,12 +189,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: Domain expertise insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,500 +1,438 @@
 ---
 name: synthesis
-description: Generate synthesis-specification.md from topic-framework and role analyses with @ references
-usage: /workflow:brainstorm:synthesis
-argument-hint: "no arguments required - synthesizes existing framework and role analyses"
-examples:
-  - /workflow:brainstorm:synthesis
-allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
+description: Clarify and refine role analyses through intelligent Q&A and targeted updates
+argument-hint: "[optional: --session session-id]"
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*)
 ---
 
-## 🧩 **Synthesis Document Generator**
+## Overview
 
-### Core Function
-**Specialized command for generating synthesis-specification.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive implementation specification with cross-role insights.
+Three-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:
 
-**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
+**Phase 1-2 (Main Flow)**: Session detection → File discovery → Path preparation
 
-### Primary Capabilities
-- **Dynamic Role Discovery**: Automatically identifies participating roles at runtime
-- **Framework Integration**: Reference topic-framework.md discussion points across all discovered roles
-- **Role Analysis Integration**: Consolidate all discovered role/analysis.md files using @ references
-- **Cross-Framework Comparison**: Compare how each participating role addressed framework discussion points
-- **@ Reference System**: Create structured references to source documents
-- **Update Detection**: Smart updates when new role analyses are added
-- **Flexible Participation**: Supports any subset of available roles (1 to 9+)
+**Phase 3A (Analysis Agent)**: Cross-role analysis → Generate recommendations
 
-### Document Integration Model
-**Three-Document Reference System**:
-1. **topic-framework.md** → Structured discussion framework (input)
-2. **[role]/analysis.md** → Role-specific analyses addressing framework (input)
-3. **synthesis-specification.md** → Complete integrated specification (output)
+**Phase 4 (Main Flow)**: User selects enhancements → User answers clarifications → Build update plan
 
-## ⚙️ **Execution Protocol**
+**Phase 5 (Parallel Update Agents)**: Each agent updates ONE role document → Parallel execution
 
-### ⚠️ Direct Execution by Main Claude
-**Execution Model**: Main Claude directly executes this command without delegating to sub-agents.
+**Phase 6 (Main Flow)**: Metadata update → Completion report
 
-**Rationale**:
-- **Full Context Access**: Avoids context transmission loss that occurs with Task tool delegation
-- **Complex Cognitive Analysis**: Leverages main Claude's complete reasoning capabilities for cross-role synthesis
-- **Tool Usage**: Combines Read/Write/Glob tools with main Claude's analytical intelligence
+**Key Features**:
+- Multi-agent architecture (analysis agent + parallel update agents)
+- Clear separation: Agent analysis vs Main flow interaction
+- Parallel document updates (one agent per role)
+- User intent alignment validation
 
-**DO NOT use Task tool** - Main Claude performs intelligent analysis directly while reading/writing files, ensuring no information loss from context passing.
+**Document Flow**:
+- Input: `[role]/analysis*.md`, `guidance-specification.md`, session metadata
+- Output: Updated `[role]/analysis*.md` with Enhancements + Clarifications sections
 
-### Phase 1: Document Discovery & Validation
-```bash
-# Detect active brainstorming session
-CHECK: .workflow/.active-* marker files
-IF active_session EXISTS:
-    session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
-ELSE:
-    ERROR: "No active brainstorming session found"
-    EXIT
+## Task Tracking
 
-# Validate required documents
-CHECK: brainstorm_dir/topic-framework.md
-IF NOT EXISTS:
-    ERROR: "topic-framework.md not found. Run /workflow:brainstorm:artifacts first"
-    EXIT
-```
-
-### Phase 2: Role Analysis Discovery
-```bash
-# Dynamically discover available role analyses
-SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/
-FIND_ANALYSES: [
-    Scan all subdirectories for */analysis.md files
-    Extract role names from directory names
-]
-
-# Available roles (for reference, actual participation is dynamic):
-# - product-manager
-# - product-owner
-# - scrum-master
-# - system-architect
-# - ui-designer
-# - ux-expert
-# - data-architect
-# - subject-matter-expert
-# - test-strategist
-
-LOAD_DOCUMENTS: {
-    "topic_framework": topic-framework.md,
-    "role_analyses": [dynamically discovered analysis.md files],
-    "participating_roles": [extract role names from discovered directories],
-    "existing_synthesis": synthesis-specification.md (if exists)
-}
-
-# Note: Not all roles participate in every brainstorming session
-# Only synthesize roles that actually produced analysis.md files
-```
-
-### Phase 3: Update Mechanism Check
-```bash
-# Check for existing synthesis
-IF synthesis-specification.md EXISTS:
-    SHOW current synthesis summary to user
-    ASK: "Synthesis exists. Do you want to:"
-    OPTIONS:
-      1. "Regenerate completely" → Create new synthesis
-      2. "Update with new analyses" → Integrate new role analyses
-      3. "Preserve existing" → Exit without changes
-ELSE:
-    CREATE new synthesis
-```
-
-### Phase 4: Synthesis Generation Process
-Initialize synthesis task tracking:
 ```json
 [
-  {"content": "Validate topic-framework.md and role analyses availability", "status": "in_progress", "activeForm": "Validating source documents"},
-  {"content": "Load topic framework discussion points structure", "status": "pending", "activeForm": "Loading framework structure"},
-  {"content": "Cross-analyze role responses to each framework point", "status": "pending", "activeForm": "Cross-analyzing framework responses"},
-  {"content": "Generate synthesis-specification.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"},
-  {"content": "Update session metadata with synthesis completion", "status": "pending", "activeForm": "Updating session metadata"}
+  {"content": "Detect session and validate analyses", "status": "in_progress", "activeForm": "Detecting session"},
+  {"content": "Discover role analysis file paths", "status": "pending", "activeForm": "Discovering paths"},
+  {"content": "Execute analysis agent (cross-role analysis)", "status": "pending", "activeForm": "Executing analysis agent"},
+  {"content": "Present enhancements for user selection", "status": "pending", "activeForm": "Presenting enhancements"},
+  {"content": "Generate and present clarification questions", "status": "pending", "activeForm": "Clarifying with user"},
+  {"content": "Build update plan from user input", "status": "pending", "activeForm": "Building update plan"},
+  {"content": "Execute parallel update agents (one per role)", "status": "pending", "activeForm": "Updating documents in parallel"},
+  {"content": "Update session metadata and generate report", "status": "pending", "activeForm": "Finalizing session"}
 ]
 ```
 
-### Phase 5: Cross-Role Analysis Execution
+## Execution Phases
 
-**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2.
+### Phase 1: Discovery & Validation
 
-#### 5.1 Data Collection and Preprocessing
-```pseudo
-# Iterate over dynamically discovered role analyses
-FOR each discovered_role IN participating_roles:
-    role_directory = brainstorm_dir + "/" + discovered_role
+1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker
+2. **Validate Files**:
+   - `guidance-specification.md` (optional, warn if missing)
+   - `*/analysis*.md` (required, error if empty)
+3. **Load User Intent**: Extract from `workflow-session.json` (project/description field)
 
-    # Load role analysis (required)
-    role_analysis = Read(role_directory + "/analysis.md")
+### Phase 2: Role Discovery & Path Preparation
 
-    # Load optional artifacts if present
-    IF EXISTS(role_directory + "/recommendations.md"):
-        role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md")
-    END IF
+**Main flow prepares file paths for Agent**:
 
-    # Extract insights from analysis
-    role_insights[discovered_role] = extract_key_insights(role_analysis)
-    role_recommendations[discovered_role] = extract_recommendations(role_analysis)
-    role_concerns[discovered_role] = extract_concerns_risks(role_analysis)
-    role_diagrams[discovered_role] = identify_diagrams_and_visuals(role_analysis)
-END FOR
+1. **Discover Analysis Files**:
+   - Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)
+   - Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md
+   - Validate: At least one file exists (error if empty)
 
-# Log participating roles for metadata
-participating_role_count = COUNT(participating_roles)
-participating_role_names = participating_roles
+2. **Extract Role Information**:
+   - `role_analysis_paths`: Relative paths from brainstorm_dir
+   - `participating_roles`: Role names extracted from directory paths
+
+3. **Pass to Agent** (Phase 3):
+   - `session_id`
+   - `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/
+   - `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...]
+   - `participating_roles`: ["product-manager", "system-architect", ...]
+
+**Main Flow Responsibility**: File discovery and path preparation only (NO file content reading)
+
+### Phase 3A: Analysis & Enhancement Agent
+
+**First agent call**: Cross-role analysis and generate enhancement recommendations
+
+```bash
+Task(conceptual-planning-agent): "
+## Agent Mission
+Analyze role documents, identify conflicts/gaps, and generate enhancement recommendations
+
+## Input from Main Flow
+- brainstorm_dir: {brainstorm_dir}
+- role_analysis_paths: {role_analysis_paths}
+- participating_roles: {participating_roles}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these analysis steps sequentially with context accumulation:
+
+1. **load_session_metadata**
+   - Action: Load original user intent as primary reference
+   - Command: Read({brainstorm_dir}/../workflow-session.json)
+   - Output: original_user_intent (from project/description field)
+
+2. **load_role_analyses**
+   - Action: Load all role analysis documents
+   - Command: For each path in role_analysis_paths: Read({brainstorm_dir}/{path})
+   - Output: role_analyses_content_map = {role_name: content}
+
+3. **cross_role_analysis**
+   - Action: Identify consensus themes, conflicts, gaps, underspecified areas
+   - Output: consensus_themes, conflicting_views, gaps_list, ambiguities
+
+4. **generate_recommendations**
+   - Action: Convert cross-role analysis findings into structured enhancement recommendations
+   - Format: EP-001, EP-002, ... (sequential numbering)
+   - Fields: id, title, affected_roles, category, current_state, enhancement, rationale, priority
+   - Taxonomy: Map to 9 categories (User Intent, Requirements, Architecture, UX, Feasibility, Risk, Process, Decisions, Terminology)
+   - Output: enhancement_recommendations (JSON array)
+
+### Output to Main Flow
+Return JSON array:
+[
+  {
+    \"id\": \"EP-001\",
+    \"title\": \"API Contract Specification\",
+    \"affected_roles\": [\"system-architect\", \"api-designer\"],
+    \"category\": \"Architecture\",
+    \"current_state\": \"High-level API descriptions\",
+    \"enhancement\": \"Add detailed contract definitions with request/response schemas\",
+    \"rationale\": \"Enables precise implementation and testing\",
+    \"priority\": \"High\"
+  },
+  ...
+]
+
+"
 ```
 
-#### 5.2 Cross-Role Insight Analysis
-```pseudo
-# Consensus identification (across all participating roles)
-consensus_areas = identify_common_themes(role_insights)
-agreement_matrix = create_agreement_matrix(role_recommendations)
+### Phase 4: Main Flow User Interaction
 
-# Disagreement analysis (track which specific roles disagree)
-disagreement_areas = identify_conflicting_views(role_insights)
-tension_points = analyze_role_conflicts(role_recommendations)
-FOR each conflict IN disagreement_areas:
-    conflict.dissenting_roles = identify_dissenting_roles(conflict)
-END FOR
+**Main flow handles all user interaction via text output**:
 
-# Innovation opportunity extraction
-innovation_opportunities = extract_breakthrough_ideas(role_insights)
-synergy_opportunities = identify_cross_role_synergies(role_insights)
-```
-
-#### 5.3 Priority and Decision Matrix Generation
-```pseudo
-# Create comprehensive evaluation matrix
-FOR each recommendation:
-    impact_score = calculate_business_impact(recommendation, role_insights)
-    feasibility_score = calculate_technical_feasibility(recommendation, role_insights)
-    effort_score = calculate_implementation_effort(recommendation, role_insights)
-    risk_score = calculate_associated_risks(recommendation, role_insights)
-    
-    priority_score = weighted_score(impact_score, feasibility_score, effort_score, risk_score)
-END FOR
-
-SORT recommendations BY priority_score DESC
-```
-
-## 📊 **Output Specification**
-
-### Output Location
-The synthesis process creates **one consolidated document** that integrates all role perspectives:
-
-```
-.workflow/WFS-{topic-slug}/.brainstorming/
-├── topic-framework.md          # Input: Framework structure
-├── [role]/analysis.md          # Input: Role analyses (multiple)
-└── synthesis-specification.md  # ★ OUTPUT: Complete integrated specification
-```
-
-#### synthesis-specification.md Structure (Complete Specification)
-
-**Document Purpose**: Defines **"WHAT"** to build - comprehensive requirements and design blueprint.
-**Scope**: High-level features, requirements, and design specifications. Does NOT include executable task breakdown (that's IMPL_PLAN.md's responsibility).
+**⚠️ CRITICAL**: ALL questions MUST use Chinese (所有问题必须用中文) for better user understanding
 
+1. **Present Enhancement Options** (multi-select):
 ```markdown
-# [Topic] - Integrated Implementation Specification
+===== Enhancement 选择 =====
 
-**Framework Reference**: @topic-framework.md | **Generated**: [timestamp] | **Session**: WFS-[topic-slug]
-**Source Integration**: All brainstorming role perspectives consolidated
-**Document Type**: Requirements & Design Specification (WHAT to build)
+请选择要应用的改进建议（可多选）：
 
-## Executive Summary
-Strategic overview with key insights, breakthrough opportunities, and implementation priorities.
+a) EP-001: API Contract Specification
+   影响角色：system-architect, api-designer
+   说明：添加详细的请求/响应 schema 定义
 
-## Key Designs & Decisions
-### Core Architecture Diagram
-```mermaid
-graph TD
-    A[Component A] --> B[Component B]
-    B --> C[Component C]
-```
-*Reference: @system-architect/analysis.md#architecture-diagram*
+b) EP-002: User Intent Validation
+   影响角色：product-manager, ux-expert
+   说明：明确用户需求优先级和验收标准
 
-### User Journey Map
-![User Journey](./assets/user-journey.png)
-*Reference: @ux-expert/analysis.md#user-journey*
+c) EP-003: Error Handling Strategy
+   影响角色：system-architect
+   说明：统一异常处理和降级方案
 
-### Data Model Overview
-```mermaid
-erDiagram
-    USER ||--o{ ORDER : places
-    ORDER ||--|{ LINE-ITEM : contains
-```
-*Reference: @data-architect/analysis.md#data-model*
-
-### Architecture Decision Records (ADRs)
-**ADR-01: [Decision Title]**
-- **Context**: Background and problem statement
-- **Decision**: Chosen approach
-- **Rationale**: Why this approach was selected
-- **Reference**: @system-architect/analysis.md#adr-01
-
-## Controversial Points & Alternatives
-| Point | Adopted Solution | Alternative Solution(s) | Decision Rationale | Dissenting Roles |
-|-------|------------------|-------------------------|--------------------| -----------------|
-| Authentication | JWT Token (@security-expert) | Session-Cookie (@system-architect) | Stateless API support for multi-platform | System Architect noted session performance benefits |
-| UI Framework | React (@ui-designer) | Vue.js (@subject-matter-expert) | Team expertise and ecosystem maturity | Subject Matter Expert preferred Vue for learning curve |
-
-*This section preserves decision context and rejected alternatives for future reference.*
-
-## Requirements & Acceptance Criteria
-### Functional Requirements
-| ID | Description | Rationale Summary | Source | Priority | Acceptance | Dependencies |
-|----|-------------|-------------------|--------|----------|------------|--------------|
-| FR-01 | User authentication | Enable secure multi-platform access | @product-manager/analysis.md | High | User can login via email/password | None |
-| FR-02 | Data export | User-requested analytics feature | @product-owner/analysis.md | Medium | Export to CSV/JSON | FR-01 |
-
-### Non-Functional Requirements
-| ID | Description | Rationale Summary | Target | Validation | Source |
-|----|-------------|-------------------|--------|------------|--------|
-| NFR-01 | Response time | UX research shows <200ms critical | <200ms | Load testing | @ux-expert/analysis.md |
-| NFR-02 | Data encryption | Compliance requirement | AES-256 | Security audit | @security-expert/analysis.md |
-
-### Business Requirements
-| ID | Description | Rationale Summary | Value | Success Metric | Source |
-|----|-------------|-------------------|-------|----------------|--------|
-| BR-01 | User retention | Market analysis shows engagement gap | High | 80% 30-day retention | @product-manager/analysis.md |
-| BR-02 | Revenue growth | Business case justification | High | 25% MRR increase | @product-owner/analysis.md |
-
-## Design Specifications
-### UI/UX Guidelines
-**Consolidated from**: @ui-designer/analysis.md, @ux-expert/analysis.md
-- Component specifications and interaction patterns
-- Visual design system and accessibility requirements
-- User flow and interface specifications
-
-### Architecture Design
-**Consolidated from**: @system-architect/analysis.md, @data-architect/analysis.md
-- System architecture and component interactions
-- Data flow and storage strategy
-- Technology stack decisions
-
-### Domain Expertise & Standards
-**Consolidated from**: @subject-matter-expert/analysis.md
-- Industry standards and best practices
-- Compliance requirements and regulations
-- Technical quality and domain-specific patterns
-
-## Process & Collaboration Concerns
-**Consolidated from**: @scrum-master/analysis.md, @product-owner/analysis.md
-
-### Team Capability Assessment
-| Required Skill | Current Level | Gap Analysis | Mitigation Strategy | Reference |
-|----------------|---------------|--------------|---------------------|-----------|
-| Kubernetes | Intermediate | Need advanced knowledge | Training + external consultant | @scrum-master/analysis.md |
-| React Hooks | Advanced | Team ready | None | @scrum-master/analysis.md |
-
-### Process Risks
-| Risk | Impact | Probability | Mitigation | Owner |
-|------|--------|-------------|------------|-------|
-| Cross-team API dependency | High | Medium | Early API contract definition | @scrum-master/analysis.md |
-| UX-Dev alignment gap | Medium | High | Weekly design sync meetings | @ux-expert/analysis.md |
-
-### Collaboration Patterns
-- **Design-Dev Pairing**: UI Designer and Frontend Dev pair programming for complex interactions
-- **Architecture Reviews**: Weekly arch review for system-level decisions
-- **User Testing Cadence**: Bi-weekly UX testing sessions with real users
-- **Reference**: @scrum-master/analysis.md#collaboration
-
-### Timeline Constraints
-- **Blocking Dependencies**: Project-X API must complete before Phase 2
-- **Resource Constraints**: Only 2 backend developers available in Q1
-- **External Dependencies**: Third-party OAuth provider integration timeline
-- **Reference**: @scrum-master/analysis.md#constraints
-
-## Implementation Roadmap (High-Level)
-### Development Phases
-**Phase 1** (0-3 months): Foundation and core features
-**Phase 2** (3-6 months): Advanced features and integrations
-**Phase 3** (6+ months): Optimization and innovation
-
-### Technical Guidelines
-- Development standards and code organization
-- Testing strategy and quality assurance
-- Deployment and monitoring approach
-
-### Feature Grouping (Epic-Level)
-- High-level feature grouping and prioritization
-- Epic-level dependencies and sequencing
-- Strategic milestones and release planning
-
-**Note**: Detailed task breakdown into executable work items is handled by `/workflow:plan` → `IMPL_PLAN.md`
-
-## Risk Assessment & Mitigation
-### Critical Risks Identified
-1. **Risk**: Description | **Mitigation**: Strategy
-2. **Risk**: Description | **Mitigation**: Strategy
-
-### Success Factors
-- Key factors for implementation success
-- Continuous monitoring requirements
-- Quality gates and validation checkpoints
-
----
-*Complete implementation specification consolidating all role perspectives into actionable guidance*
+支持格式：1abc 或 1a 1b 1c 或 1a,b,c
+请输入选择（可跳过输入 skip）：
 ```
 
-## 🔄 **Session Integration**
+2. **Generate Clarification Questions** (based on analysis agent output):
+   - ✅ **ALL questions in Chinese (所有问题必须用中文)**
+   - Use 9-category taxonomy scan results
+   - Prioritize most critical questions (no hard limit)
+   - Each with 2-4 options + descriptions
 
-### Streamlined Status Synchronization
-Upon completion, update `workflow-session.json`:
+3. **Interactive Clarification Loop** (max 10 questions per round):
+```markdown
+===== Clarification 问题 (第 1/2 轮) =====
 
-**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
+【问题1 - 用户意图】MVP 阶段的核心目标是什么？
+a) 快速验证市场需求
+   说明：最小功能集，快速上线获取反馈
+b) 建立技术壁垒
+   说明：完善架构，为长期发展打基础
+c) 实现功能完整性
+   说明：覆盖所有规划功能，延迟上线
 
+【问题2 - 架构决策】技术栈选择的优先考虑因素？
+a) 团队熟悉度
+   说明：使用现有技术栈，降低学习成本
+b) 技术先进性
+   说明：采用新技术，提升竞争力
+c) 生态成熟度
+   说明：选择成熟方案，保证稳定性
+
+...（最多10个问题）
+
+请回答 (格式: 1a 2b 3c...)：
+```
+
+Wait for user input → Parse all answers in batch → Continue to next round if needed
+
+4. **Build Update Plan**:
+```
+update_plan = {
+  "role1": {
+    "enhancements": [EP-001, EP-003],
+    "clarifications": [
+      {"question": "...", "answer": "...", "category": "..."},
+      ...
+    ]
+  },
+  "role2": {
+    "enhancements": [EP-002],
+    "clarifications": [...]
+  },
+  ...
+}
+```
+
+### Phase 5: Parallel Document Update Agents
+
+**Parallel agent calls** (one per role needing updates):
+
+```bash
+# Execute in parallel using single message with multiple Task calls
+
+Task(conceptual-planning-agent): "
+## Agent Mission
+Apply user-confirmed enhancements and clarifications to {role1} analysis document
+
+## Agent Intent
+- **Goal**: Integrate synthesis results into role-specific analysis
+- **Scope**: Update ONLY {role1}/analysis.md (isolated, no cross-role dependencies)
+- **Constraints**: Preserve original insights, add refinements without deletion
+
+## Input from Main Flow
+- role: {role1}
+- analysis_path: {brainstorm_dir}/{role1}/analysis.md
+- enhancements: [EP-001, EP-003] (user-selected improvements)
+- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
+- original_user_intent: {from session metadata}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute these update steps sequentially:
+
+1. **load_current_analysis**
+   - Action: Load existing role analysis document
+   - Command: Read({brainstorm_dir}/{role1}/analysis.md)
+   - Output: current_analysis_content
+
+2. **add_clarifications_section**
+   - Action: Insert Clarifications section with Q&A
+   - Format: \"## Clarifications\\n### Session {date}\\n- **Q**: {question} (Category: {category})\\n  **A**: {answer}\"
+   - Output: analysis_with_clarifications
+
+3. **apply_enhancements**
+   - Action: Integrate EP-001, EP-003 into relevant sections
+   - Strategy: Locate section by category (Architecture → Architecture section, UX → User Experience section)
+   - Output: analysis_with_enhancements
+
+4. **resolve_contradictions**
+   - Action: Remove conflicts between original content and clarifications/enhancements
+   - Output: contradiction_free_analysis
+
+5. **enforce_terminology_consistency**
+   - Action: Align all terminology with user-confirmed choices from clarifications
+   - Output: terminology_consistent_analysis
+
+6. **validate_user_intent_alignment**
+   - Action: Verify all updates support original_user_intent
+   - Output: validated_analysis
+
+7. **write_updated_file**
+   - Action: Save final analysis document
+   - Command: Write({brainstorm_dir}/{role1}/analysis.md, validated_analysis)
+   - Output: File update confirmation
+
+### Output
+Updated {role1}/analysis.md with Clarifications section + enhanced content
+")
+
+Task(conceptual-planning-agent): "
+## Agent Mission
+Apply user-confirmed enhancements and clarifications to {role2} analysis document
+
+## Agent Intent
+- **Goal**: Integrate synthesis results into role-specific analysis
+- **Scope**: Update ONLY {role2}/analysis.md (isolated, no cross-role dependencies)
+- **Constraints**: Preserve original insights, add refinements without deletion
+
+## Input from Main Flow
+- role: {role2}
+- analysis_path: {brainstorm_dir}/{role2}/analysis.md
+- enhancements: [EP-002] (user-selected improvements)
+- clarifications: [{question, answer, category}, ...] (user-confirmed answers)
+- original_user_intent: {from session metadata}
+
+## Execution Instructions
+[FLOW_CONTROL]
+
+### Flow Control Steps
+**AGENT RESPONSIBILITY**: Execute same 7 update steps as {role1} agent (load → clarifications → enhancements → contradictions → terminology → validation → write)
+
+### Output
+Updated {role2}/analysis.md with Clarifications section + enhanced content
+")
+
+# ... repeat for each role in update_plan
+```
+
+**Agent Characteristics**:
+- **Intent**: Integrate user-confirmed synthesis results (NOT generate new analysis)
+- **Isolation**: Each agent updates exactly ONE role (parallel execution safe)
+- **Context**: Minimal - receives only role-specific enhancements + clarifications
+- **Dependencies**: Zero cross-agent dependencies (full parallelism)
+- **Validation**: All updates must align with original_user_intent
+
+### Phase 6: Completion & Metadata Update
+
+**Main flow finalizes**:
+
+1. Wait for all parallel agents to complete
+2. Update workflow-session.json:
 ```json
 {
   "phases": {
     "BRAINSTORM": {
-      "status": "completed",
-      "synthesis_completed": true,
+      "status": "clarification_completed",
+      "clarification_completed": true,
       "completed_at": "timestamp",
-      "participating_roles": ["<dynamically-discovered-role-1>", "<dynamically-discovered-role-2>", "..."],
-      "available_roles": ["product-manager", "product-owner", "scrum-master", "system-architect", "ui-designer", "ux-expert", "data-architect", "subject-matter-expert", "test-strategist"],
-      "consolidated_output": {
-        "synthesis_specification": ".workflow/WFS-{topic}/.brainstorming/synthesis-specification.md"
+      "participating_roles": [...],
+      "clarification_results": {
+        "enhancements_applied": ["EP-001", "EP-002", ...],
+        "questions_asked": 3,
+        "categories_clarified": ["Architecture", "UX", ...],
+        "roles_updated": ["role1", "role2", ...],
+        "outstanding_items": []
       },
-      "synthesis_quality": {
-        "role_integration": "complete",
+      "quality_metrics": {
+        "user_intent_alignment": "validated",
         "requirement_coverage": "comprehensive",
-        "decision_transparency": "alternatives_documented",
-        "process_risks_identified": true,
-        "implementation_readiness": "ready"
-      },
-      "content_metrics": {
-        "roles_synthesized": "<COUNT(participating_roles)>",
-        "functional_requirements": "<dynamic-count>",
-        "non_functional_requirements": "<dynamic-count>",
-        "business_requirements": "<dynamic-count>",
-        "architecture_decisions": "<dynamic-count>",
-        "controversial_points": "<dynamic-count>",
-        "diagrams_included": "<dynamic-count>",
-        "process_risks": "<dynamic-count>",
-        "team_skill_gaps": "<dynamic-count>",
-        "implementation_phases": "<dynamic-count>",
-        "risk_factors_identified": "<dynamic-count>"
+        "ambiguity_resolution": "complete",
+        "terminology_consistency": "enforced"
       }
     }
   }
 }
 ```
 
-**Example with actual values**:
+3. Generate completion report (show to user):
+```markdown
+## ✅ Clarification Complete
+
+**Enhancements Applied**: EP-001, EP-002, EP-003
+**Questions Answered**: 3/5
+**Roles Updated**: role1, role2, role3
+
+### Next Steps
+✅ PROCEED: `/workflow:plan --session WFS-{session-id}`
+```
+
+## Output
+
+**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
+
+**Updated Structure**:
+```markdown
+## Clarifications
+### Session {date}
+- **Q**: {question} (Category: {category})
+  **A**: {answer}
+
+## {Existing Sections}
+{Refined content based on clarifications}
+```
+
+**Changes**:
+- User intent validated/corrected
+- Requirements more specific/measurable
+- Architecture with rationale
+- Ambiguities resolved, placeholders removed
+- Consistent terminology
+
+## Session Metadata
+
+Update `workflow-session.json`:
+
 ```json
 {
   "phases": {
     "BRAINSTORM": {
-      "status": "completed",
-      "participating_roles": ["product-manager", "system-architect", "ui-designer", "ux-expert", "scrum-master"],
-      "content_metrics": {
-        "roles_synthesized": 5,
-        "functional_requirements": 18,
-        "controversial_points": 2
+      "status": "clarification_completed",
+      "clarification_completed": true,
+      "completed_at": "timestamp",
+      "participating_roles": ["product-manager", "system-architect", ...],
+      "clarification_results": {
+        "questions_asked": 3,
+        "categories_clarified": ["Architecture & Design", ...],
+        "roles_updated": ["system-architect", "ui-designer", ...],
+        "outstanding_items": []
+      },
+      "quality_metrics": {
+        "user_intent_alignment": "validated",
+        "requirement_coverage": "comprehensive",
+        "ambiguity_resolution": "complete",
+        "terminology_consistency": "enforced",
+        "decision_transparency": "documented"
       }
     }
   }
 }
 ```
 
-## ✅ **Quality Assurance**
+## Quality Checklist
 
-### Required Synthesis Elements
-- [ ] Integration of all available role analyses with comprehensive coverage
-- [ ] **Key Designs & Decisions**: Architecture diagrams, user journey maps, ADRs documented
-- [ ] **Controversial Points**: Disagreement points, alternatives, and decision rationale captured
-- [ ] **Process Concerns**: Team capability gaps, process risks, collaboration patterns identified
-- [ ] Quantified priority recommendation matrix with evaluation criteria
-- [ ] Actionable implementation plan with phased approach
-- [ ] Comprehensive risk assessment with mitigation strategies
+**Content**:
+- All role analyses loaded/analyzed
+- Cross-role analysis (consensus, conflicts, gaps)
+- 9-category ambiguity scan
+- Questions prioritized
+- Clarifications documented
 
-### Synthesis Analysis Quality Standards
-- [ ] **Completeness**: Integrates all available role analyses without gaps
-- [ ] **Visual Clarity**: Key diagrams (architecture, data model, user journey) included via Mermaid or images
-- [ ] **Decision Transparency**: Documents not just decisions, but alternatives and why they were rejected
-- [ ] **Insight Generation**: Identifies cross-role patterns and deep insights
-- [ ] **Actionability**: Provides specific, executable recommendations with rationale
-- [ ] **Balance**: Considers all role perspectives, including process-oriented roles (Scrum Master)
-- [ ] **Forward-Looking**: Includes long-term strategic and innovation considerations
+**Analysis**:
+- User intent validated
+- Cross-role synthesis complete
+- Ambiguities resolved
+- Correct roles updated
+- Terminology consistent
+- Contradictions removed
 
-### Output Validation Criteria
-- [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation
-- [ ] **Context-Rich**: Each requirement includes rationale summary for immediate understanding
-- [ ] **Resource-Aware**: Team skill gaps and constraints explicitly documented
-- [ ] **Risk-Managed**: Both technical and process risks captured with mitigation strategies
-- [ ] **Measurable Success**: Clear success metrics and monitoring frameworks
-- [ ] **Clear Actions**: Specific next steps with assigned responsibilities and timelines
+**Documents**:
+- Clarifications section formatted
+- Sections reflect answers
+- No placeholders (TODO/TBD)
+- Valid Markdown
+- Cross-references maintained
 
-### Integration Excellence Standards
-- [ ] **Cross-Role Synthesis**: Successfully identifies and documents role perspective conflicts
-- [ ] **No Role Marginalization**: Process, UX, and compliance concerns equally visible as functional requirements
-- [ ] **Strategic Coherence**: Recommendations form coherent strategic direction
-- [ ] **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
 
-## 🚀 **Recommended Next Steps**
-
-After synthesis completion, follow this recommended workflow:
-
-### Option 1: Standard Planning Workflow (Recommended)
-```bash
-# Step 1: Verify conceptual clarity (Quality Gate)
-/workflow:concept-verify --session WFS-{session-id}
-# → Interactive Q&A (up to 5 questions) to clarify ambiguities in synthesis
-
-# Step 2: Proceed to action planning (after concept verification)
-/workflow:plan --session WFS-{session-id}
-# → Generates IMPL_PLAN.md and task.json files
-
-# Step 3: Verify action plan quality (Quality Gate)
-/workflow:action-plan-verify --session WFS-{session-id}
-# → Read-only analysis to catch issues before execution
-
-# Step 4: Start implementation
-/workflow:execute --session WFS-{session-id}
-```
-
-### Option 2: TDD Workflow
-```bash
-# Step 1: Verify conceptual clarity
-/workflow:concept-verify --session WFS-{session-id}
-
-# Step 2: Generate TDD task chains (RED-GREEN-REFACTOR)
-/workflow:tdd-plan --session WFS-{session-id} "Feature description"
-
-# Step 3: Verify TDD plan quality
-/workflow:action-plan-verify --session WFS-{session-id}
-
-# Step 4: Execute TDD workflow
-/workflow:execute --session WFS-{session-id}
-```
-
-### Quality Gates Explained
-
-**`/workflow:concept-verify`** (Phase 2 - After Brainstorming):
-- **Purpose**: Detect and resolve conceptual ambiguities before detailed planning
-- **Time**: 10-20 minutes (interactive)
-- **Value**: Reduces downstream rework by 40-60%
-- **Output**: Updated synthesis-specification.md with clarifications
-
-**`/workflow:action-plan-verify`** (Phase 4 - After Planning):
-- **Purpose**: Validate IMPL_PLAN.md and task.json consistency and completeness
-- **Time**: 5-10 minutes (read-only analysis)
-- **Value**: Prevents execution of flawed plans, saves 2-5 days
-- **Output**: Verification report with actionable recommendations
-
-### Skip Verification? (Not Recommended)
-
-If you want to skip verification and proceed directly:
-```bash
-/workflow:plan --session WFS-{session-id}
-/workflow:execute --session WFS-{session-id}
-```
-
-⚠️ **Warning**: Skipping verification increases risk of late-stage issues and rework.

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

@@ -1,21 +1,17 @@
 ---
 name: system-architect
-description: Generate or update system-architect/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:system-architect [topic]
+description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:system-architect
-  - /workflow:brainstorm:system-architect "user authentication redesign"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🏗️ **System Architect Analysis Generator**
 
 ### Purpose
-**Specialized command for generating system-architect/analysis.md** that addresses topic-framework.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating system-architect/analysis.md** that addresses guidance-specification.md discussion points from system architecture perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **Architecture Focus**: Technical architecture, scalability, and system design perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
@@ -26,6 +22,25 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 - **Performance & Scalability**: Capacity planning and optimization strategies
 - **Integration Patterns**: System communication and data flow design
 
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Macro-Architecture)**
+- **System-Level Architecture**: Service boundaries, deployment topology, and system composition
+- **Cross-Service Communication Patterns**: Choosing between microservices/monolithic, event-driven/request-response, sync/async patterns
+- **Technology Stack Decisions**: Language, framework, database, and infrastructure choices
+- **Non-Functional Requirements**: Scalability, performance, availability, disaster recovery, and monitoring strategies
+- **Integration Planning**: How systems and services connect at the macro level (not specific API contracts)
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **API Contract Details**: Specific endpoint definitions, URL structures, HTTP methods → Defers to **API Designer**
+- **Data Schemas**: Detailed data model design and entity relationships → Defers to **Data Architect**
+- **UI/UX Design**: Interface design and user experience → Defers to **UX Expert** and **UI Designer**
+
+#### **Handoff Points**
+- **TO API Designer**: Provides architectural constraints (REST vs GraphQL, sync vs async) that define the API design space
+- **TO Data Architect**: Provides system-level data flow requirements and integration patterns
+- **FROM Data Architect**: Receives canonical data model to inform system integration design
+
 ## ⚙️ **Execution Protocol**
 
 ### Phase 1: Session & Framework Detection
@@ -36,7 +51,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -63,20 +78,20 @@ ELSE:
 ```
 
 ### Phase 3: Agent Task Generation
-**Framework-Based Analysis** (when topic-framework.md exists):
+**Framework-Based Analysis** (when guidance-specification.md exists):
 ```bash
 Task(subagent_type="conceptual-planning-agent",
      prompt="Generate system architect analysis addressing topic framework
 
      ## Framework Integration Required
-     **MANDATORY**: Load and address topic-framework.md discussion points
-     **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+     **MANDATORY**: Load and address guidance-specification.md discussion points
+     **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
      **Output Location**: {session.brainstorm_dir}/system-architect/analysis.md
 
      ## Analysis Requirements
-     1. **Load Topic Framework**: Read topic-framework.md completely
+     1. **Load Topic Framework**: Read guidance-specification.md completely
      2. **Address Each Discussion Point**: Respond to all 5 framework sections from system architecture perspective
-     3. **Include Framework Reference**: Start analysis.md with @../topic-framework.md
+     3. **Include Framework Reference**: Start analysis.md with @../guidance-specification.md
      4. **Technical Focus**: Emphasize scalability, architecture patterns, technology decisions
      5. **Structured Response**: Use framework structure for analysis organization
 
@@ -91,7 +106,7 @@ Task(subagent_type="conceptual-planning-agent",
      ```markdown
      # System Architect Analysis: [Topic]
 
-     **Framework Reference**: @../topic-framework.md
+     **Framework Reference**: @../guidance-specification.md
      **Role Focus**: System Architecture and Technical Design
 
      ## Core Requirements Analysis
@@ -125,14 +140,14 @@ IF update_mode = "incremental":
 
          ## Current Analysis Context
          **Existing Analysis**: @{session.brainstorm_dir}/system-architect/analysis.md
-         **Framework Reference**: @{session.brainstorm_dir}/topic-framework.md
+         **Framework Reference**: @{session.brainstorm_dir}/guidance-specification.md
 
          ## Update Requirements
          1. **Preserve Structure**: Maintain existing analysis structure
          2. **Add New Insights**: Integrate new technical insights and recommendations
          3. **Framework Alignment**: Ensure continued alignment with topic framework
          4. **Technical Updates**: Add new architecture patterns, technology considerations
-         5. **Maintain References**: Keep @../topic-framework.md reference
+         5. **Maintain References**: Keep @../guidance-specification.md reference
 
          ## Update Instructions
          - Read existing analysis completely
@@ -148,14 +163,14 @@ IF update_mode = "incremental":
 ### Output Files
 ```
 .workflow/WFS-[topic]/.brainstorming/
-├── topic-framework.md          # Input: Framework (if exists)
+├── guidance-specification.md          # Input: Framework (if exists)
 └── system-architect/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
 ```
 
 ### Analysis Structure
 **Required Elements**:
-- **Framework Reference**: @../topic-framework.md (if framework exists)
+- **Framework Reference**: @../guidance-specification.md (if framework exists)
 - **Role Focus**: System Architecture and Technical Design perspective
 - **5 Framework Sections**: Address each framework discussion point
 - **Technical Recommendations**: Architecture-specific insights and solutions
@@ -369,4 +384,4 @@ System architect perspective provides:
 - [ ] **Resource Planning**: Resource requirements clearly defined and realistic
 - [ ] **Risk Management**: Technical risks identified with mitigation plans
 - [ ] **Performance Validation**: Architecture can meet performance requirements
-- [ ] **Evolution Strategy**: Design allows for future growth and changes
+- [ ] **Evolution Strategy**: Design allows for future growth and changes

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

@@ -1,31 +1,47 @@
 ---
 name: ui-designer
-description: Generate or update ui-designer/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:ui-designer [topic]
+description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:ui-designer
-  - /workflow:brainstorm:ui-designer "user authentication redesign"
-  - /workflow:brainstorm:ui-designer "mobile app navigation improvement"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🎨 **UI Designer Analysis Generator**
 
 ### Purpose
-**Specialized command for generating ui-designer/analysis.md** that addresses topic-framework.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating ui-designer/analysis.md** that addresses guidance-specification.md discussion points from UI/UX design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **UI/UX Focus**: User experience, interface design, and accessibility perspective
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
 
 ### Analysis Scope
-- **User Experience Design**: Intuitive and efficient user experiences
-- **Interface Design**: Beautiful and functional user interfaces
-- **Interaction Design**: Smooth user interaction flows and micro-interactions
-- **Accessibility Design**: Inclusive design meeting WCAG compliance
+- **Visual Design**: Color palettes, typography, spacing, and visual hierarchy implementation
+- **High-Fidelity Mockups**: Polished, pixel-perfect interface designs
+- **Design System Implementation**: Component libraries, design tokens, and style guides
+- **Micro-Interactions & Animations**: Transition effects, loading states, and interactive feedback
+- **Responsive Design**: Layout adaptations for different screen sizes and devices
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Concrete Visual Interface Implementation)**
+- **Visual Design Language**: Colors, typography, iconography, spacing, and overall aesthetic
+- **High-Fidelity Mockups**: Polished designs showing exactly how the interface will look
+- **Design System Components**: Building and documenting reusable UI components (buttons, inputs, cards, etc.)
+- **Design Tokens**: Defining variables for colors, spacing, typography that can be used in code
+- **Micro-Interactions**: Hover states, transitions, animations, and interactive feedback details
+- **Responsive Layouts**: Adapting designs for mobile, tablet, and desktop breakpoints
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **User Research & Personas**: User behavior analysis and needs assessment → Defers to **UX Expert**
+- **Information Architecture**: Content structure and navigation strategy → Defers to **UX Expert**
+- **Low-Fidelity Wireframes**: Structural layouts without visual design → Defers to **UX Expert**
+
+#### **Handoff Points**
+- **FROM UX Expert**: Receives wireframes, user flows, and information architecture as the foundation for visual design
+- **TO Frontend Developers**: Provides design specifications, component libraries, and design tokens for implementation
+- **WITH API Designer**: Coordinates on data presentation and form validation feedback (visual aspects only)
 
 ## ⚙️ **Execution Protocol**
 
@@ -37,7 +53,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from UI/UX perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from UI/UX perspective
 **Role Focus**: User experience design, interface optimization, accessibility compliance
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive UI/UX analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with UI/UX design expertise
+- Address each discussion point from guidance-specification.md with UI/UX design expertise
 - Provide actionable design recommendations and interface solutions
 - Include accessibility considerations and WCAG compliance planning
 - Reference framework document using @ notation for integration
@@ -121,7 +137,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +165,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/ui-designer/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +173,11 @@ TodoWrite({
 # UI Designer Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: UI/UX Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with UI/UX expertise]
+[Address each point from guidance-specification.md with UI/UX expertise]
 
 ### Core Requirements (from framework)
 [UI/UX perspective on requirements]
@@ -194,12 +210,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: UI/UX insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,31 +1,47 @@
 ---
 name: ux-expert
-description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:ux-expert [topic]
+description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points
 argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:ux-expert
-  - /workflow:brainstorm:ux-expert "user authentication redesign"
-  - /workflow:brainstorm:ux-expert "mobile app performance optimization"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
 
 ## 🎯 **UX Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating ux-expert/analysis.md** that addresses topic-framework.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
+**Specialized command for generating ux-expert/analysis.md** that addresses guidance-specification.md discussion points from user experience and interface design perspective. Creates or updates role-specific analysis with framework references.
 
 ### Core Function
-- **Framework-based Analysis**: Address each discussion point in topic-framework.md
+- **Framework-based Analysis**: Address each discussion point in guidance-specification.md
 - **UX Design Focus**: User interface, interaction patterns, and usability optimization
 - **Update Mechanism**: Create new or update existing analysis.md
 - **Agent Delegation**: Use conceptual-planning-agent for analysis generation
 
 ### Analysis Scope
-- **User Interface Design**: Visual hierarchy, layout patterns, and component design
-- **Interaction Patterns**: User flows, navigation, and microinteractions
-- **Usability Optimization**: Accessibility, cognitive load, and user testing strategies
-- **Design Systems**: Component libraries, design tokens, and consistency frameworks
+- **User Research**: User personas, behavioral analysis, and needs assessment
+- **Information Architecture**: Content structure, navigation hierarchy, and mental models
+- **User Journey Mapping**: User flows, task analysis, and interaction models
+- **Usability Strategy**: Accessibility planning, cognitive load reduction, and user testing frameworks
+- **Wireframing**: Low-fidelity layouts and structural prototypes (not visual design)
+
+### Role Boundaries & Responsibilities
+
+#### **What This Role OWNS (Abstract User Experience & Research)**
+- **User Research & Personas**: Understanding target users, their goals, pain points, and behaviors
+- **Information Architecture**: Organizing content and defining navigation structures at a conceptual level
+- **User Journey Mapping**: Defining user flows, task sequences, and interaction models
+- **Wireframes & Low-Fidelity Prototypes**: Structural layouts showing information hierarchy (boxes and arrows, not colors/fonts)
+- **Usability Testing Strategy**: Planning user testing, A/B tests, and validation methods
+- **Accessibility Planning**: WCAG compliance strategy and inclusive design principles
+
+#### **What This Role DOES NOT Own (Defers to Other Roles)**
+- **Visual Design**: Colors, typography, spacing, visual style → Defers to **UI Designer**
+- **High-Fidelity Mockups**: Polished, pixel-perfect designs → Defers to **UI Designer**
+- **Component Implementation**: Design system components, CSS, animations → Defers to **UI Designer**
+
+#### **Handoff Points**
+- **TO UI Designer**: Provides wireframes, user flows, and information architecture that UI Designer will transform into high-fidelity visual designs
+- **FROM User Research**: May receive external research data to inform UX decisions
+- **TO Product Owner**: Provides user insights and validation results to inform feature prioritization
 
 ## ⚙️ **Execution Protocol**
 
@@ -37,7 +53,7 @@ IF active_session EXISTS:
     session_id = get_active_session()
     brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
 
-    CHECK: brainstorm_dir/topic-framework.md
+    CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
         framework_mode = true
         load_framework = true
@@ -78,7 +94,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/topic-framework.md)
+   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -92,17 +108,17 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from user experience and interface design perspective
+**Framework Reference**: Address all discussion points in guidance-specification.md from user experience and interface design perspective
 **Role Focus**: UI design, interaction patterns, usability optimization, design systems
 **Structured Approach**: Create analysis.md addressing framework discussion points
 **Template Integration**: Apply role template guidelines within framework structure
 
 ## Expected Deliverables
 1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points
-2. **Framework Reference**: Include @../topic-framework.md reference in analysis
+2. **Framework Reference**: Include @../guidance-specification.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with UX design expertise
+- Address each discussion point from guidance-specification.md with UX design expertise
 - Provide actionable interface design and usability optimization strategies
 - Include accessibility considerations and interaction pattern recommendations
 - Reference framework document using @ notation for integration
@@ -121,7 +137,7 @@ TodoWrite({
       activeForm: "Detecting session and framework"
     },
     {
-      content: "Load topic-framework.md and session metadata for context",
+      content: "Load guidance-specification.md and session metadata for context",
       status: "pending",
       activeForm: "Loading framework and session context"
     },
@@ -149,7 +165,7 @@ TodoWrite({
 ### Framework-Based Analysis
 ```
 .workflow/WFS-{session}/.brainstorming/ux-expert/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+└── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
 ### Analysis Document Structure
@@ -157,11 +173,11 @@ TodoWrite({
 # UX Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
-**Topic Framework**: @../topic-framework.md
+**Topic Framework**: @../guidance-specification.md
 **Role Focus**: User Experience & Interface Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with UX design expertise]
+[Address each point from guidance-specification.md with UX design expertise]
 
 ### Core Requirements (from framework)
 [User interface and interaction design requirements perspective]
@@ -194,12 +210,12 @@ TodoWrite({
     "status": "completed",
     "framework_addressed": true,
     "output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
-    "framework_reference": "@../topic-framework.md"
+    "framework_reference": "@../guidance-specification.md"
   }
 }
 ```
 
 ### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
+- **Framework Reference**: @../guidance-specification.md for structured discussion points
 - **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration
 - **Agent Autonomy**: Independent execution with framework guidance

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

@@ -1,311 +0,0 @@
----
-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/execute.md

@@ -1,11 +1,7 @@
 ---
 name: execute
 description: Coordinate agents for existing workflow tasks with automatic discovery
-usage: /workflow:execute [--resume-session="session-id"]
-argument-hint: [--resume-session="session-id"]
-examples:
-  - /workflow:execute
-  - /workflow:execute --resume-session="WFS-user-auth"
+argument-hint: "[--resume-session=\"session-id\"]"
 ---
 
 # Workflow Execute Command
@@ -15,6 +11,17 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
 
+## Performance Optimization Strategy
+
+**Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| **Initial Load** | All task JSONs (~2,300 lines) | TODO_LIST.md only (~650 lines) | **72% reduction** |
+| **Startup Time** | Seconds | Milliseconds | **~90% faster** |
+| **Memory** | All tasks | 1-2 tasks | **90% less** |
+| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
+
 ## Core Rules
 **Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
 **Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
@@ -39,28 +46,21 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 - **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
 
 ## Flow Control Execution
-**[FLOW_CONTROL]** marker indicates sequential step execution required for context gathering and preparation. **These steps are executed BY THE AGENT, not by the workflow:execute command.**
+**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
 
-### Flow Control Rules
-1. **Auto-trigger**: When `task.flow_control.pre_analysis` array exists in task JSON, agents execute these steps
-2. **Sequential Processing**: Agents execute steps in order, accumulating context including artifacts
-3. **Variable Passing**: Agents use `[variable_name]` syntax to reference step outputs including artifact content
-4. **Error Handling**: Agents follow step-specific error strategies (`fail`, `skip_optional`, `retry_once`)
-5. **Artifacts Priority**: When artifacts exist in task.context.artifacts, load synthesis specifications first
+### Orchestrator Responsibility
+- Pass complete task JSON to agent (including `flow_control` block)
+- Provide session paths for artifact access
+- Monitor agent completion
 
-### Execution Pattern
-```
-Step 1: load_dependencies → dependency_context
-Step 2: analyze_patterns [dependency_context] → pattern_analysis
-Step 3: implement_solution [pattern_analysis] [dependency_context] → implementation
-```
+### Agent Responsibility
+- Parse `flow_control.pre_analysis` array from JSON
+- Execute steps sequentially with variable substitution
+- Accumulate context from artifacts and dependencies
+- Follow error handling per `step.on_error`
+- Complete implementation using accumulated context
 
-### Context Accumulation Process (Executed by Agents)
-- **Load Artifacts**: Agents retrieve synthesis specifications and brainstorming outputs from `context.artifacts`
-- **Load Dependencies**: Agents retrieve summaries from `context.depends_on` tasks
-- **Execute Analysis**: Agents run CLI tools with accumulated context including artifacts
-- **Prepare Implementation**: Agents build comprehensive context for implementation
-- **Continue Implementation**: Agents use all accumulated context including artifacts for task execution
+**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
 
 ## Execution Lifecycle
 
@@ -74,40 +74,69 @@ Step 3: implement_solution [pattern_analysis] [dependency_context] → implement
 ### Phase 1: Discovery (Normal Mode Only)
 1. **Check Active Sessions**: Find `.workflow/.active-*` markers
 2. **Select Session**: If multiple found, prompt user selection
-3. **Load Session State**: Read `workflow-session.json` and `IMPL_PLAN.md`
-4. **Scan Tasks**: Analyze `.task/*.json` files for ready tasks
+3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
+4. **DO NOT read task JSONs yet** - defer until execution phase
 
 **Note**: In resume mode, this phase is completely skipped.
 
-### Phase 2: Analysis (Normal Mode Only)
-1. **Dependency Resolution**: Build execution order based on `depends_on`
-2. **Status Validation**: Filter tasks with `status: "pending"` and met dependencies
-3. **Agent Assignment**: Determine agent type from `meta.agent` or `meta.type`
-4. **Context Preparation**: Load dependency summaries and inherited context
+### Phase 2: Planning Document Analysis (Normal Mode Only)
+**Optimized to avoid reading all task JSONs upfront**
+
+1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
+2. **Read TODO_LIST.md**: Get current task statuses and execution progress
+3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
+4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
+
+**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
 
 **Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
 
-### Phase 3: Planning (Resume Mode Entry Point)
+### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
 **This is where resume mode directly enters after skipping Phases 1 & 2**
 
-1. **Create TodoWrite List**: Generate task list with status markers from session state
-2. **Mark Initial Status**: Set first pending task as `in_progress`
+1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
+   - Parse TODO_LIST.md to extract all tasks with current statuses
+   - Identify first pending task with met dependencies
+   - Generate comprehensive TodoWrite covering entire workflow
+2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
 3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
-4. **Prepare Complete Task JSON**: Include pre_analysis and flow control steps for agent consumption
-5. **Validate Prerequisites**: Ensure all required context is available from existing session
+4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
 
 **Resume Mode Behavior**:
-- Load existing session state directly from `.workflow/{session-id}/`
-- Use session's task files and summaries without discovery
-- Generate TodoWrite from current session progress
-- Proceed immediately to agent execution
+- Load existing TODO_LIST.md directly from `.workflow/{session-id}/`
+- Extract current progress from TODO_LIST.md
+- Generate TodoWrite from TODO_LIST.md state
+- Proceed immediately to agent execution (Phase 4)
 
-### Phase 4: Execution
-1. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
-2. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
-3. **Monitor Progress**: Track agent execution and handle errors without user interruption
-4. **Collect Results**: Gather implementation results and outputs
-5. **Continue Workflow**: Automatically proceed to next pending task until completion
+### Phase 4: Execution (Lazy Task Loading)
+**Key Optimization**: Read task JSON **only when needed** for execution
+
+1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
+2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
+3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
+4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
+5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
+6. **Monitor Progress**: Track agent execution and handle errors without user interruption
+7. **Collect Results**: Gather implementation results and outputs
+8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
+9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
+
+**Execution Loop Pattern**:
+```
+while (TODO_LIST.md has pending tasks) {
+  next_task_id = getTodoWriteInProgressTask()
+  task_json = Read(.workflow/{session}/.task/{next_task_id}.json)  // Lazy load
+  executeTaskWithAgent(task_json)
+  updateTodoListMarkCompleted(next_task_id)
+  advanceTodoWriteToNextTask()
+}
+```
+
+**Benefits**:
+- Reduces initial context loading by ~90%
+- Only reads task JSON when actually executing
+- Scales better for workflows with many tasks
+- Faster startup time for workflow execution
 
 ### Phase 5: Completion
 1. **Update Task Status**: Mark completed tasks in JSON files
@@ -119,27 +148,33 @@ Step 3: implement_solution [pattern_analysis] [dependency_context] → implement
 
 ## Task Discovery & Queue Building
 
-### Session Discovery Process (Normal Mode)
+### Session Discovery Process (Normal Mode - Optimized)
 ```
 ├── Check for .active-* markers in .workflow/
 ├── If multiple active sessions found → Prompt user to select
 ├── Locate selected session's workflow folder
-├── Load selected session's workflow-session.json and IMPL_PLAN.md
-├── Scan selected session's .task/ directory for task JSON files
-├── Analyze task statuses and dependencies for selected session only
-└── Build execution queue of ready tasks from selected session
+├── Load session metadata: workflow-session.json (minimal context)
+├── Read IMPL_PLAN.md (strategy overview and task summary)
+├── Read TODO_LIST.md (current task statuses and dependencies)
+├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
+├── Build execution queue from TODO_LIST.md
+└── Generate TodoWrite from TODO_LIST.md state
 ```
 
-### Resume Mode Process (--resume-session flag)
+**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
+
+### Resume Mode Process (--resume-session flag - Optimized)
 ```
 ├── Use provided session-id directly (skip discovery)
 ├── Validate .workflow/{session-id}/ directory exists
-├── Load session's workflow-session.json and IMPL_PLAN.md directly
-├── Scan session's .task/ directory for task JSON files
-├── Use existing task statuses and dependencies (no re-analysis needed)
-└── Build execution queue from session state (prioritize pending/in-progress tasks)
+├── Read TODO_LIST.md for current progress
+├── Parse TODO_LIST.md to extract task IDs and statuses
+├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
+└── Enter Phase 4 (Execution) with lazy task JSON loading
 ```
 
+**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
+
 ### Task Status Logic
 ```
 pending + dependencies_met → executable
@@ -147,6 +182,122 @@ completed → skip
 blocked → skip until dependencies clear
 ```
 
+## Batch Execution with Dependency Graph
+
+### Parallel Execution Algorithm
+**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
+
+#### Algorithm Steps (Optimized with Lazy Loading)
+```javascript
+function executeBatchWorkflow(sessionId) {
+  // 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
+  const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
+
+  // 2. Process batches until graph is empty
+  while (!graph.isEmpty()) {
+    // 3. Identify current batch (tasks with in-degree = 0)
+    const batch = graph.getNodesWithInDegreeZero();
+
+    // 4. Load task JSONs ONLY for current batch (lazy loading)
+    const batchTaskJsons = batch.map(taskId =>
+      Read(`.workflow/${sessionId}/.task/${taskId}.json`)
+    );
+
+    // 5. Check for parallel execution opportunities
+    const parallelGroups = groupByExecutionGroup(batchTaskJsons);
+
+    // 6. Execute batch concurrently
+    await Promise.all(
+      parallelGroups.map(group => executeBatch(group))
+    );
+
+    // 7. Update graph: remove completed tasks and their edges
+    graph.removeNodes(batch);
+
+    // 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
+    updateTodoListAfterBatch(batch);
+    updateTodoWriteAfterBatch(batch);
+  }
+
+  // 9. All tasks complete - auto-complete session
+  SlashCommand("/workflow:session:complete");
+}
+
+function buildDependencyGraphFromTodoList(todoListPath) {
+  const todoContent = Read(todoListPath);
+  const tasks = parseTodoListTasks(todoContent);
+  const graph = new DirectedGraph();
+
+  tasks.forEach(task => {
+    graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
+    task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
+  });
+
+  return graph;
+}
+
+function parseTodoListTasks(todoContent) {
+  // Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
+  const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
+  const tasks = [];
+  let match;
+
+  while ((match = taskPattern.exec(todoContent)) !== null) {
+    tasks.push({
+      status: match[1] === 'x' ? 'completed' : 'pending',
+      id: match[2],
+      title: match[3]
+    });
+  }
+
+  return tasks;
+}
+
+function groupByExecutionGroup(tasks) {
+  const groups = {};
+
+  tasks.forEach(task => {
+    const groupId = task.meta.execution_group || task.id;
+    if (!groups[groupId]) groups[groupId] = [];
+    groups[groupId].push(task);
+  });
+
+  return Object.values(groups);
+}
+
+async function executeBatch(tasks) {
+  // Execute all tasks in batch concurrently
+  return Promise.all(
+    tasks.map(task => executeTask(task))
+  );
+}
+```
+
+#### Execution Group Rules
+1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
+2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
+3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
+4. **Same `context_signature`** → Should have been merged (warning if not)
+
+#### Parallel Execution Example
+```
+Batch 1 (no dependencies):
+  - IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
+  - IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
+  - IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
+
+Wait for Batch 1 completion...
+
+Batch 2 (depends on Batch 1):
+  - IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
+
+Wait for Batch 2 completion...
+
+Batch 3 (independent of Batch 2):
+  - IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
+  - IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
+```
+
 ## TodoWrite Coordination
 **Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
 
@@ -154,8 +305,11 @@ blocked → skip until dependencies clear
 1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
    - **Normal Mode**: Create from discovery results
    - **Resume Mode**: Create from existing session state and current progress
-2. **Single In-Progress**: Mark ONLY ONE task as `in_progress` at a time
-3. **Immediate Updates**: Update status after each task completion without user interruption
+2. **Parallel Task Support**:
+   - **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
+   - **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
+   - **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
+3. **Immediate Updates**: Update status after each task/batch completion without user interruption
 4. **Status Synchronization**: Sync with JSON task files after updates
 5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
 
@@ -171,36 +325,71 @@ blocked → skip until dependencies clear
 **Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
 
 ```javascript
-// Create initial todo list from discovered pending tasks
+// Example 1: Sequential execution (traditional)
 TodoWrite({
   todos: [
     {
       content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
-      status: "pending",
+      status: "in_progress",  // Single task in progress
       activeForm: "Executing IMPL-1.1: Design auth schema"
     },
     {
       content: "Execute IMPL-1.2: Implement auth logic [code-developer] [FLOW_CONTROL]",
       status: "pending",
       activeForm: "Executing IMPL-1.2: Implement auth logic"
-    },
-    {
-      content: "Execute TEST-FIX-1: Validate implementation tests [test-fix-agent]",
-      status: "pending",
-      activeForm: "Executing TEST-FIX-1: Validate implementation tests"
     }
   ]
 });
 
-// Update status as tasks progress - ONLY ONE task should be in_progress at a time
+// Example 2: Batch execution (parallel tasks with execution_group)
 TodoWrite({
   todos: [
     {
-      content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
-      status: "in_progress",  // Mark current task as in_progress
-      activeForm: "Executing IMPL-1.1: Design auth schema"
+      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
+      status: "in_progress",  // Batch task 1
+      activeForm: "Executing IMPL-1.1: Build Auth API"
     },
-    // ... other tasks remain pending
+    {
+      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
+      status: "in_progress",  // Batch task 2 (running concurrently)
+      activeForm: "Executing IMPL-1.2: Build User UI"
+    },
+    {
+      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
+      status: "in_progress",  // Batch task 3 (running concurrently)
+      activeForm: "Executing IMPL-1.3: Setup Database"
+    },
+    {
+      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent] [depends_on: IMPL-1.1, IMPL-1.2, IMPL-1.3]",
+      status: "pending",  // Next batch (waits for current batch completion)
+      activeForm: "Executing IMPL-2.1: Integration Tests"
+    }
+  ]
+});
+
+// Example 3: After batch completion
+TodoWrite({
+  todos: [
+    {
+      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.1: Build Auth API"
+    },
+    {
+      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.2: Build User UI"
+    },
+    {
+      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
+      status: "completed",  // Batch completed
+      activeForm: "Executing IMPL-1.3: Setup Database"
+    },
+    {
+      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
+      status: "in_progress",  // Next batch started
+      activeForm: "Executing IMPL-2.1: Integration Tests"
+    }
   ]
 });
 ```
@@ -215,18 +404,19 @@ TodoWrite({
 - **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
 
 #### TODO_LIST.md Update Timing
-- **Before Agent Launch**: Update TODO_LIST.md to mark task as `in_progress` (⚠️)
-- **After Task Complete**: Update TODO_LIST.md to mark as `completed` (✅), advance to next
-- **On Error**: Keep as `in_progress` in TODO_LIST.md, add error note
-- **Workflow Complete**: When all tasks completed, call `/workflow:session:complete`
-- **Session End**: Sync all TODO_LIST.md statuses with JSON task files
+**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
+
+- **Before Agent Launch**: Mark task as `in_progress` (⚠️)
+- **After Task Complete**: Mark as `completed` (✅), advance to next
+- **On Error**: Keep as `in_progress`, add error note
+- **Workflow Complete**: Call `/workflow:session:complete`
 
 ### 3. Agent Context Management
 **Comprehensive context preparation** for autonomous agent execution:
 
 #### Context Sources (Priority Order)
 1. **Complete Task JSON**: Full task definition including all fields and artifacts
-2. **Artifacts Context**: Brainstorming outputs and synthesis specifications from task.context.artifacts
+2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
 3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
 4. **Dependency Summaries**: Previous task completion summaries
 5. **Session Context**: Workflow paths and session metadata
@@ -247,10 +437,10 @@ TodoWrite({
 {
   "task": { /* Complete task JSON with artifacts array */ },
   "artifacts": {
-    "synthesis_specification": { "path": ".workflow/WFS-session/.brainstorming/synthesis-specification.md", "priority": "highest" },
-    "topic_framework": { "path": ".workflow/WFS-session/.brainstorming/topic-framework.md", "priority": "medium" },
-    "role_analyses": [ /* Individual role analysis files */ ],
-    "available_artifacts": [ /* All detected brainstorming artifacts */ ]
+    "synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
+    "guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
+    "role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
+    "conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
   },
   "flow_context": {
     "step_outputs": {
@@ -262,7 +452,7 @@ TodoWrite({
   },
   "session": {
     "workflow_dir": ".workflow/WFS-session/",
-    "brainstorming_dir": ".workflow/WFS-session/.brainstorming/",
+    "context_package_path": ".workflow/WFS-session/.process/context-package.json",
     "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
     "summaries_dir": ".workflow/WFS-session/.summaries/",
     "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
@@ -274,10 +464,10 @@ TodoWrite({
 
 #### Context Validation Rules
 - **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
-- **Artifacts Available**: Synthesis specifications and brainstorming outputs accessible
+- **Artifacts Available**: All artifacts loaded from context-package.json
 - **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
 - **Dependencies Loaded**: All depends_on summaries available
-- **Session Paths Valid**: All workflow paths exist and accessible, including .brainstorming directory
+- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
 - **Agent Assignment**: Valid agent type specified in meta.agent
 
 ### 4. Agent Execution Pattern
@@ -286,82 +476,40 @@ TodoWrite({
 #### Agent Prompt Template
 ```bash
 Task(subagent_type="{meta.agent}",
-     prompt="**TASK EXECUTION WITH FULL JSON LOADING**
+     prompt="**EXECUTE TASK FROM JSON**
 
-     ## STEP 1: Load Complete Task JSON
-     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+     ## Task JSON Location
+     {session.task_json_path}
 
-     cat {session.task_json_path}
+     ## Instructions
+     1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control)
+     2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially:
+        - Load artifacts (role analysis documents, role analyses) using commands in each step
+        - Accumulate context from step outputs using variable substitution [variable_name]
+        - Handle errors per step.on_error (skip_optional | fail | retry_once)
+     3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context
+     4. **Complete Task**:
+        - Update task status: `jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}`
+        - Update TODO_LIST.md: Mark task as [x] completed in {session.todo_list_path}
+        - Generate summary: {session.summaries_dir}/{task.id}-summary.md
+        - Check workflow completion and call `/workflow:session:complete` if all tasks done
 
-     **CRITICAL**: Validate all 5 required fields are present:
-     - id, title, status, meta, context, flow_control
+     ## Context Sources (All from JSON)
+     - Requirements: `context.requirements`
+     - Focus Paths: `context.focus_paths`
+     - Acceptance: `context.acceptance`
+     - Artifacts: `context.artifacts` (synthesis specs, brainstorming outputs)
+     - Dependencies: `context.depends_on`
+     - Target Files: `flow_control.target_files`
 
-     ## STEP 2: Task Definition (From Loaded JSON)
-     **ID**: Use id field from JSON
-     **Title**: Use title field from JSON
-     **Type**: Use meta.type field from JSON
-     **Agent**: Use meta.agent field from JSON
-     **Status**: Verify status is pending or active
+     ## Session Paths
+     - Workflow Dir: {session.workflow_dir}
+     - TODO List: {session.todo_list_path}
+     - Summaries: {session.summaries_dir}
+     - Flow Context: {flow_context.step_outputs}
 
-     ## STEP 3: Flow Control Execution (if flow_control.pre_analysis exists)
-     **AGENT RESPONSIBILITY**: Execute pre_analysis steps sequentially from loaded JSON:
-
-     **PRIORITY: Artifact Loading Steps First**
-     1. **Load Synthesis Specification** (if present): Priority artifact loading for consolidated design
-     2. **Load Individual Artifacts** (fallback): Load role-specific brainstorming outputs if synthesis unavailable
-     3. **Execute Remaining Steps**: Continue with other pre_analysis steps
-
-     For each step in flow_control.pre_analysis array:
-     1. Execute step.command/commands with variable substitution (support both single command and commands array)
-     2. Store output to step.output_to variable
-     3. Handle errors per step.on_error strategy (skip_optional, fail, retry_once)
-     4. Pass accumulated variables to next step including artifact context
-
-     **Special Artifact Loading Commands**:
-     - Use `bash(ls path 2>/dev/null || echo 'file not found')` for artifact existence checks
-     - Use `Read(path)` for loading artifact content
-     - Use `find` commands for discovering multiple artifact files
-     - Reference artifacts in subsequent steps using output variables: [synthesis_specification], [individual_artifacts]
-
-     ## STEP 4: Implementation Context (From JSON context field)
-     **Requirements**: Use context.requirements array from JSON
-     **Focus Paths**: Use context.focus_paths array from JSON
-     **Acceptance Criteria**: Use context.acceptance array from JSON
-     **Dependencies**: Use context.depends_on array from JSON
-     **Parent Context**: Use context.inherited object from JSON
-     **Artifacts**: Use context.artifacts array from JSON (synthesis specifications, brainstorming outputs)
-     **Target Files**: Use flow_control.target_files array from JSON
-     **Implementation Approach**: Use flow_control.implementation_approach object from JSON (with artifact integration)
-
-     ## STEP 5: Session Context (Provided by workflow:execute)
-     **Workflow Directory**: {session.workflow_dir}
-     **TODO List Path**: {session.todo_list_path}
-     **Summaries Directory**: {session.summaries_dir}
-     **Task JSON Path**: {session.task_json_path}
-     **Flow Context**: {flow_context.step_outputs}
-
-     ## STEP 6: Agent Completion Requirements
-     1. **Load Task JSON**: Read and validate complete task structure
-     2. **Execute Flow Control**: Run all pre_analysis steps if present
-     3. **Implement Solution**: Follow implementation_approach from JSON
-     4. **Update Progress**: Mark task status in JSON as completed
-     5. **Update TODO List**: Update TODO_LIST.md at provided path
-     6. **Generate Summary**: Create completion summary in summaries directory
-     7. **Check Workflow Complete**: After task completion, check if all workflow tasks done
-     8. **Auto-Complete Session**: If all tasks completed, call SlashCommand(\"/workflow:session:complete\")
-
-     **JSON UPDATE COMMAND**:
-     Update task status to completed using jq:
-     jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}
-
-     **WORKFLOW COMPLETION CHECK**:
-     After updating task status, check if workflow is complete:
-     total_tasks=\$(find .workflow/*/\.task/ -name "*.json" -type f 2>/dev/null | wc -l)
-     completed_tasks=\$(find .workflow/*/\.summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-     if [ \$total_tasks -eq \$completed_tasks ]; then
-       SlashCommand(command=\"/workflow:session:complete\")
-     fi"),
-     description="Execute task with full JSON loading and validation")
+     **Complete JSON structure is authoritative - load and follow it exactly.**"),
+     description="Execute task: {task.id}")
 ```
 
 #### Agent JSON Loading Specification
@@ -385,7 +533,7 @@ Task(subagent_type="{meta.agent}",
   "status": "pending|active|completed|blocked",
   "meta": {
     "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
+    "agent": "@code-developer|@test-fix-agent|@universal-executor"
   },
   "context": {
     "requirements": ["req1", "req2"],
@@ -396,15 +544,16 @@ Task(subagent_type="{meta.agent}",
     "artifacts": [
       {
         "type": "synthesis_specification",
-        "source": "brainstorm_synthesis",
-        "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
+        "source": "context-package.json → brainstorm_artifacts.synthesis_output",
+        "path": "{{loaded dynamically from context-package.json}}",
         "priority": "highest",
         "contains": "complete_integrated_specification"
       },
       {
         "type": "individual_role_analysis",
-        "source": "brainstorm_roles",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md",
+        "source": "context-package.json → brainstorm_artifacts.role_analyses[]",
+        "path": "{{loaded dynamically from context-package.json}}",
+        "note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
         "priority": "low",
         "contains": "role_specific_analysis_fallback"
       }
@@ -414,10 +563,11 @@ Task(subagent_type="{meta.agent}",
     "pre_analysis": [
       {
         "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification from brainstorming",
+        "action": "Load synthesis specification from context-package.json",
         "commands": [
-          "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'synthesis specification not found')",
-          "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
+          "Read(.workflow/WFS-[session]/.process/context-package.json)",
+          "Extract(brainstorm_artifacts.synthesis_output.path)",
+          "Read(extracted path)"
         ],
         "output_to": "synthesis_specification",
         "on_error": "skip_optional"
@@ -429,10 +579,28 @@ Task(subagent_type="{meta.agent}",
         "on_error": "skip_optional|fail|retry_once"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement following consolidated synthesis specification...",
-      "modification_points": ["Apply synthesis specification requirements..."]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following role analyses",
+        "description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
+        "modification_points": [
+          "Apply consolidated requirements from role analysis documents",
+          "Follow technical guidelines from synthesis",
+          "Consult artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load role analyses",
+          "Parse architecture and requirements",
+          "Implement following specification",
+          "Consult artifacts for technical details when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
@@ -453,7 +621,7 @@ meta.agent missing → Infer from meta.type:
   - "feature" → @code-developer
   - "test-gen" → @code-developer
   - "test-fix" → @test-fix-agent
-  - "review" → @general-purpose
+  - "review" → @universal-executor
   - "docs" → @doc-generator
 ```
 

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

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

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

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

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

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

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

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

.claude/commands/workflow/plan.md

@@ -1,13 +1,7 @@
 ---
 name: plan
-description: Orchestrate 4-phase planning workflow by executing commands and passing context between phases
-usage: /workflow:plan [--agent] <input>
-argument-hint: "[--agent] \"text description\"|file.md|ISS-001"
-examples:
-  - /workflow:plan "Build authentication system"
-  - /workflow:plan --agent "Build authentication system"
-  - /workflow:plan requirements.md
-  - /workflow:plan ISS-001
+description: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
+argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -15,37 +9,40 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 4 slash commands in sequence, parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
+**This command is a pure orchestrator**: Execute 5 slash commands in sequence (including a quality gate), parse their outputs, pass context between them, and ensure complete execution through **automatic continuation**.
 
-**Execution Model - Auto-Continue Workflow**:
+**Execution Model - Auto-Continue Workflow with Quality Gate**:
+
+This workflow runs **fully autonomously** once triggered. Phase 3 (conflict resolution) and Phase 4 (task generation) are delegated to specialized agents.
 
-This workflow runs **fully autonomously** once triggered. Each phase completes, reports its output to you, then **immediately and automatically** proceeds to the next phase without requiring any user intervention.
 
 1. **User triggers**: `/workflow:plan "task"`
-2. **Phase 1 executes** → Reports output to user → Auto-continues
-3. **Phase 2 executes** → Reports output to user → Auto-continues
-4. **Phase 3 executes** → Reports output to user → Auto-continues
-5. **Phase 4 executes** → Reports final summary
+2. **Phase 1 executes** → Session discovery → Auto-continues
+3. **Phase 2 executes** → Context gathering → Auto-continues
+4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
+5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
 
 **Auto-Continue Mechanism**:
 - TodoList tracks current phase status
 - After each phase completion, automatically executes next pending phase
-- **No user action required** - workflow runs end-to-end autonomously
+- All phases run autonomously without user interaction (clarification handled in brainstorm phase)
 - Progress updates shown at each phase for visibility
 
 **Execution Modes**:
 - **Manual Mode** (default): Use `/workflow:tools:task-generate`
 - **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
+- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
 
 ## Core Rules
 
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 command execution
 2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1
-3. **Parse Every Output**: Extract required data from each command's output for next phase
+3. **Parse Every Output**: Extract required data from each command/agent output for next phase
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
 5. **Track Progress**: Update TodoWrite after every phase completion
+6. **Agent Delegation**: Phase 3 uses cli-execution-agent for autonomous intelligent analysis
 
-## 4-Phase Execution
+## 5-Phase Execution
 
 ### Phase 1: Session Discovery
 **Command**: `SlashCommand(command="/workflow:session:start --auto \"[structured-task-description]\"")`
@@ -86,7 +83,7 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **Parse Output**:
 - Extract: context-package.json path (store as `contextPath`)
-- Typical pattern: `.workflow/[sessionId]/.context/context-package.json`
+- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
 
 **Validation**:
 - Context package path extracted
@@ -98,35 +95,87 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 ---
 
-### Phase 3: Intelligent Analysis
-**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")`
+### Phase 3: Conflict Resolution (Optional - auto-triggered by conflict risk)
 
-**Input**: `sessionId` from Phase 1, `contextPath` from Phase 2
+**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
+
+**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
+
+**Input**:
+- sessionId from Phase 1
+- contextPath from Phase 2
+- conflict_risk from context-package.json
 
 **Parse Output**:
-- Verify ANALYSIS_RESULTS.md created
+- Extract: Execution status (success/skipped/failed)
+- Verify: CONFLICT_RESOLUTION.md file path (if executed)
 
 **Validation**:
-- File `.workflow/[sessionId]/ANALYSIS_RESULTS.md` exists
-- Contains task recommendations section
+- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+**Skip Behavior**:
+- If conflict_risk is "none" or "low", skip directly to Phase 3.5
+- Display: "No significant conflicts detected, proceeding to clarification"
 
-**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 4
+**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
+
+**After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
+
+**Memory State Check**:
+- Evaluate current context window usage and memory state
+- If memory usage is high (>110K tokens or approaching context limits):
+  - **Command**: `SlashCommand(command="/compact")`
+  - This optimizes memory before proceeding to Phase 3.5
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
+---
+
+### Phase 3.5: Pre-Task Generation Validation (Optional Quality Gate)
+
+**Purpose**: Optional quality gate before task generation - primarily handled by brainstorm synthesis phase
+
+
+**Current Behavior**: Auto-skip to Phase 4 (Task Generation)
+
+**Future Enhancement**: Could add additional validation steps like:
+- Cross-reference checks between conflict resolution and brainstorm analyses
+- Final sanity checks before task generation
+- User confirmation prompt for proceeding
+
+**TodoWrite**: Mark phase 3.5 completed (auto-skip), phase 4 in_progress
+
+**After Phase 3.5**: Auto-continue to Phase 4 immediately
 
 ---
 
 ### Phase 4: Task Generation
 
 **Relationship with Brainstorm Phase**:
-- If brainstorm synthesis exists (synthesis-specification.md), Phase 3 analysis incorporates it as input
-- **synthesis-specification.md defines "WHAT"**: Requirements, design specs, high-level features
+- If brainstorm role analyses exist ([role]/analysis.md files), Phase 3 analysis incorporates them as input
+- **⚠️ User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations
+- **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights
 - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
-- Task generation translates high-level specifications into concrete, actionable work items
+- Task generation translates high-level role analyses into concrete, actionable work items
+- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
 
-**Command**:
+**Command Selection**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
 - Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
+- CLI Execute: Add `--cli-execute` flag to either command
+
+**Flag Combination**:
+- `--cli-execute` alone: Manual task generation with CLI execution
+- `--agent --cli-execute`: Agent task generation with CLI execution
+
+**Command Examples**:
+```bash
+# Manual with CLI execution
+/workflow:tools:task-generate --session WFS-auth --cli-execute
+
+# Agent with CLI execution
+/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+```
 
 **Input**: `sessionId` from Phase 1
 
@@ -155,22 +204,36 @@ Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
 ```javascript
 // Initialize (before Phase 1)
+// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
 TodoWrite({todos: [
   {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
   {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
+  // Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// After Phase 1
+// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
 TodoWrite({todos: [
   {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "in_progress", "activeForm": "Executing context gathering"},
-  {"content": "Execute intelligent analysis", "status": "pending", "activeForm": "Executing intelligent analysis"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
   {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
 ]})
 
-// Continue pattern for Phase 2, 3, 4...
+// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
+]})
+
+// After Phase 3 (if executed), continue to Phase 4
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
+]})
 ```
 
 ## Input Processing
@@ -202,12 +265,6 @@ TodoWrite({todos: [
    - Extract goal, scope, requirements
    - Format into structured description
 
-4. **Issue Reference** (e.g., `ISS-001`) → Read and structure:
-   - Read issue file
-   - Extract title as goal
-   - Extract description as scope/context
-   - Format into structured description
-
 ## Data Flow
 
 ```
@@ -225,14 +282,22 @@ Phase 1: session:start --auto "structured-description"
     ↓
 Phase 2: context-gather --session sessionId "structured-description"
     ↓ Input: sessionId + session memory + structured description
-    ↓ Output: contextPath (context-package.json)
+    ↓ Output: contextPath (context-package.json) + conflict_risk
     ↓
-Phase 3: concept-enhanced --session sessionId --context contextPath
-    ↓ Input: sessionId + contextPath + session memory
-    ↓ Output: ANALYSIS_RESULTS.md
+Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
+    ↓ Input: sessionId + contextPath + conflict_risk
+    ↓ CLI-powered conflict detection (JSON output)
+    ↓ AskUserQuestion: Present conflicts + resolution strategies
+    ↓ User selects strategies (or skip)
+    ↓ Apply modifications via Edit tool:
+    ↓   - Update guidance-specification.md
+    ↓   - Update role analyses (*.md)
+    ↓   - Mark context-package.json as "resolved"
+    ↓ Output: Modified brainstorm artifacts (NO report file)
+    ↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
     ↓
 Phase 4: task-generate[--agent] --session sessionId
-    ↓ Input: sessionId + ANALYSIS_RESULTS.md + session memory
+    ↓ Input: sessionId + resolved brainstorm artifacts + session memory
     ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
     ↓
 Return summary to user
@@ -241,7 +306,7 @@ Return summary to user
 **Session Memory Flow**: Each phase receives session ID, which provides access to:
 - Previous task summaries
 - Existing context and analysis
-- Brainstorming artifacts
+- Brainstorming artifacts (potentially modified by Phase 3)
 - Session-specific configuration
 
 **Structured Description Benefits**:
@@ -259,17 +324,22 @@ Return summary to user
 ## Coordinator Checklist
 
 ✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
-✅ Initialize TodoWrite before any command
+✅ Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
 ✅ Execute Phase 1 immediately with structured description
 ✅ Parse session ID from Phase 1 output, store in memory
 ✅ Pass session ID and structured description to Phase 2 command
 ✅ Parse context path from Phase 2 output, store in memory
-✅ Pass session ID and context path to Phase 3 command
-✅ Verify ANALYSIS_RESULTS.md after Phase 3
-✅ Select correct Phase 4 command based on --agent flag
+✅ **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
+✅ **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
+✅ Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
+✅ **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
+✅ **Build Phase 4 command** based on flags:
+  - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
+  - Add `--session [sessionId]`
+  - Add `--cli-execute` if flag present
 ✅ Pass session ID to Phase 4 command
 ✅ Verify all Phase 4 outputs
-✅ Update TodoWrite after each phase
+✅ Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
 ✅ After each phase, automatically continue to next phase based on TodoList status
 
 ## Structure Template Reference
@@ -297,4 +367,4 @@ CONSTRAINTS: [Limitations or boundaries]
 
 # Phase 2
 /workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
-```
+```

.claude/commands/workflow/resume.md

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

.claude/commands/workflow/review.md

@@ -1,13 +1,7 @@
 ---
 name: review
 description: Optional specialized review (security, architecture, docs) for completed implementation
-usage: /workflow:review [--type=<type>] [session-id]
-argument-hint: "[--type=security|architecture|action-items|quality] [session-id]"
-examples:
-  - /workflow:review                           # Quality review of active session
-  - /workflow:review --type=security           # Security audit of active session
-  - /workflow:review --type=architecture WFS-user-auth  # Architecture review of specific session
-  - /workflow:review --type=action-items       # Pre-deployment verification
+argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
 ---
 
 ### 🚀 Command Overview: `/workflow:review`
@@ -98,17 +92,17 @@ After bash validation, the model takes control to:
 2. **Perform Specialized Review**: Based on `review_type`
 
    **Security Review** (`--type=security`):
-   - Use MCP code search for security patterns:
+   - Use ripgrep for security patterns:
      ```bash
-     mcp__code-index__search_code_advanced(pattern="password|token|secret|auth", file_pattern="*.{ts,js,py}")
-     mcp__code-index__search_code_advanced(pattern="eval|exec|innerHTML|dangerouslySetInnerHTML", file_pattern="*.{ts,js,tsx}")
+     rg "password|token|secret|auth" -g "*.{ts,js,py}"
+     rg "eval|exec|innerHTML|dangerouslySetInnerHTML" -g "*.{ts,js,tsx}"
      ```
    - Use Gemini for security analysis:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Security audit of completed implementation
      TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Security findings report with severity levels
      RULES: Focus on OWASP Top 10, authentication, authorization, data validation, injection risks
      " --approval-mode yolo
@@ -117,10 +111,10 @@ After bash validation, the model takes control to:
    **Architecture Review** (`--type=architecture`):
    - Use Qwen for architecture analysis:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/qwen-wrapper -p "
+     cd .workflow/${sessionId} && qwen -p "
      PURPOSE: Architecture compliance review
      TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Architecture assessment with recommendations
      RULES: Check for patterns, separation of concerns, modularity, scalability
      " --approval-mode yolo
@@ -129,10 +123,10 @@ After bash validation, the model takes control to:
    **Quality Review** (`--type=quality`):
    - Use Gemini for code quality:
      ```bash
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Code quality and best practices review
      TASK: Assess code readability, maintainability, adherence to best practices
-     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED: Quality assessment with improvement suggestions
      RULES: Check for code smells, duplication, complexity, naming conventions
      " --approval-mode yolo
@@ -149,10 +143,10 @@ After bash validation, the model takes control to:
      ' {} \;
 
      # Check implementation summaries against requirements
-     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     cd .workflow/${sessionId} && gemini -p "
      PURPOSE: Verify all requirements and acceptance criteria are met
      TASK: Cross-check implementation summaries against original requirements
-     CONTEXT: @{.task/IMPL-*.json,.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
      EXPECTED:
      - Requirements coverage matrix
      - Acceptance criteria verification

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

@@ -1,7 +1,6 @@
 ---
 name: complete
-description: Mark the active workflow session as complete and remove active flag
-usage: /workflow:session:complete
+description: Mark the active workflow session as complete, archive it with lessons learned, and remove active flag
 examples:
   - /workflow:session:complete
   - /workflow:session:complete --detailed
@@ -10,7 +9,7 @@ examples:
 # Complete Workflow Session (/workflow:session:complete)
 
 ## Overview
-Mark the currently active workflow session as complete, update its status, and remove the active flag marker.
+Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
 
 ## Usage
 ```bash
@@ -20,87 +19,129 @@ Mark the currently active workflow session as complete, update its status, and r
 
 ## Implementation Flow
 
-### Step 1: Find Active Session
+### Phase 1: Prepare for Archival (Minimal Manual Operations)
+
+**Purpose**: Find active session, move to archive location, pass control to agent. Minimal operations.
+
+#### Step 1.1: Find Active Session and Get Name
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-```
+# Find active marker
+bash(find .workflow/ -name ".active-*" -type f | head -1)
 
-### Step 2: Get Session Name
+# Extract session name from marker path
+bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+```
+**Output**: Session name `WFS-session-name`
+
+#### Step 1.2: Move Session to Archive
 ```bash
-basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
+# Create archive directory if needed
+bash(mkdir -p .workflow/.archives/)
+
+# Move session to archive location
+bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+```
+**Result**: Session now at `.workflow/.archives/WFS-session-name/`
+
+### Phase 2: Agent-Orchestrated Completion (All Data Processing)
+
+**Purpose**: Agent analyzes archived session, generates metadata, updates manifest, and removes active marker.
+
+#### Agent Invocation
+
+Invoke `universal-executor` agent to complete the archival process.
+
+**Agent Task**:
+```
+Task(
+  subagent_type="universal-executor",
+  description="Complete session archival",
+  prompt=`
+Complete workflow session archival. Session already moved to archive location.
+
+## Context
+- Session: .workflow/.archives/WFS-session-name/
+- Active marker: .workflow/.active-WFS-session-name
+
+## Tasks
+
+1. **Extract session data** from workflow-session.json (session_id, description/topic, started_at/timestamp, completed_at, status)
+   - If status != "completed", update it with timestamp
+
+2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
+
+3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt (fallback: analyze files directly)
+   - Return: {successes, challenges, watch_patterns}
+
+4. **Build archive entry**:
+   - Calculate: duration_hours, success_rate, tags (3-5 keywords)
+   - Construct complete JSON with session_id, description, archived_at, archive_path, metrics, tags, lessons
+
+5. **Update manifest**: Initialize .workflow/.archives/manifest.json if needed, append entry
+
+6. **Remove active marker**
+
+7. **Return result**: {"status": "success", "session_id": "...", "archived_at": "...", "metrics": {...}, "lessons_summary": {...}}
+
+## Error Handling
+- On failure: return {"status": "error", "task": "...", "message": "..."}
+- Do NOT remove marker if failed
+  `
+)
 ```
 
-### Step 3: Update Session Status
+**Expected Output**:
+- Agent returns JSON result confirming successful archival
+- Display completion summary to user based on agent response
+
+## Workflow Execution Strategy
+
+### Two-Phase Approach (Optimized)
+
+**Phase 1: Minimal Manual Setup** (2 simple operations)
+- Find active session and extract name
+- Move session to archive location
+- **No data extraction** - agent handles all data processing
+- **No counting** - agent does this from archive location
+- **Total**: 2 bash commands (find + move)
+
+**Phase 2: Agent-Driven Completion** (1 agent invocation)
+- Extract all session data from archived location
+- Count tasks and summaries
+- Generate lessons learned analysis
+- Build complete archive metadata
+- Update manifest
+- Remove active marker
+- Return success/error result
+
+## Quick Commands
+
 ```bash
-jq '.status = "completed"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+# Phase 1: Find and move
+bash(find .workflow/ -name ".active-*" -type f | head -1)
+bash(basename .workflow/.active-WFS-session-name | sed 's/^\.active-//')
+bash(mkdir -p .workflow/.archives/)
+bash(mv .workflow/WFS-session-name .workflow/.archives/WFS-session-name)
+
+# Phase 2: Agent completes archival
+Task(subagent_type="universal-executor", description="Complete session archival", prompt=`...`)
 ```
 
-### Step 4: Add Completion Timestamp
+## Archive Query Commands
+
+After archival, you can query the manifest:
+
 ```bash
-jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+# List all archived sessions
+jq '.archives[].session_id' .workflow/.archives/manifest.json
+
+# Find sessions by keyword
+jq '.archives[] | select(.description | test("auth"; "i"))' .workflow/.archives/manifest.json
+
+# Get specific session details
+jq '.archives[] | select(.session_id == "WFS-user-auth")' .workflow/.archives/manifest.json
+
+# List all watch patterns across sessions
+jq '.archives[].lessons.watch_patterns[]' .workflow/.archives/manifest.json
 ```
 
-### Step 5: Count Final Statistics
-```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
-```
-
-### Step 6: Remove Active Marker
-```bash
-rm .workflow/.active-WFS-session-name
-```
-
-## Simple Bash Commands
-
-### Basic Operations
-- **Find active session**: `find .workflow/ -name ".active-*" -type f`
-- **Get session name**: `basename marker | sed 's/^\.active-//'`
-- **Update status**: `jq '.status = "completed"' session.json > temp.json`
-- **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
-- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
-- **Remove marker**: `rm .workflow/.active-session`
-
-### Completion Result
-```
-Session WFS-user-auth completed
-- Status: completed
-- Started: 2025-09-15T10:00:00Z
-- Completed: 2025-09-15T16:30:00Z
-- Duration: 6h 30m
-- Total tasks: 8
-- Completed tasks: 8
-- Success rate: 100%
-```
-
-### Detailed Summary (--detailed flag)
-```
-Session Completion Summary:
-├── Session: WFS-user-auth
-├── Project: User authentication system
-├── Total time: 6h 30m
-├── Tasks completed: 8/8 (100%)
-├── Files generated: 24 files
-├── Summaries created: 8 summaries
-├── Status: All tasks completed successfully
-└── Location: .workflow/WFS-user-auth/
-```
-
-### Error Handling
-```bash
-# No active session
-find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
-
-# Incomplete tasks
-task_count=$(find .task/ -name "*.json" -type f | wc -l)
-summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
-```
-
-## Related Commands
-- `/workflow:session:list` - View all sessions including completed
-- `/workflow:session:start` - Start new session
-- `/workflow:status` - Check completion status before completing

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

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

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

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

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

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

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

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

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

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

.claude/commands/workflow/status.md

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

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

@@ -1,12 +1,7 @@
 ---
 name: tdd-plan
 description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
-usage: /workflow:tdd-plan [--agent] <input>
-argument-hint: "[--agent] \"feature description\"|file.md|ISS-001"
-examples:
-  - /workflow:tdd-plan "Implement user authentication"
-  - /workflow:tdd-plan --agent requirements.md
-  - /workflow:tdd-plan ISS-001
+argument-hint: "[--agent] \"feature description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -25,12 +20,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
 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 7 completes (with concept verification)
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
 6. **TDD Context**: All descriptions include "TDD:" prefix
-7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
+7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
 
-## 7-Phase Execution (with Concept Verification)
+## 6-Phase Execution (with Conflict Resolution)
 
 ### Phase 1: Session Discovery
 **Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
@@ -46,10 +41,32 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse**: Extract sessionId
 
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+**After Phase 1**: Return to user showing Phase 1 results, then auto-continue to Phase 2
+
+---
+
 ### Phase 2: Context Gathering
 **Command**: `/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"`
 
-**Parse**: Extract contextPath
+**Use Same Structured Description**: Pass the same structured format from Phase 1
+
+**Input**: `sessionId` from Phase 1
+
+**Parse Output**:
+- Extract: context-package.json path (store as `contextPath`)
+- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
+
+**Validation**:
+- Context package path extracted
+- File exists and is valid JSON
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+
+---
 
 ### Phase 3: Test Coverage Analysis
 **Command**: `/workflow:tools:test-context-gather --session [sessionId]`
@@ -68,96 +85,162 @@ TEST_FOCUS: [Test scenarios]
 - Prevents duplicate test creation
 - Enables integration with existing tests
 
-### Phase 4: TDD Analysis
-**Command**: `/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]`
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
-**Note**: Generates ANALYSIS_RESULTS.md with TDD-specific structure:
-- Feature list with testable requirements
-- Test cases for Red phase
-- Implementation requirements for Green phase
-- Refactoring opportunities
-- Task dependencies and execution order
+**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
 
-**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
+---
 
-### Phase 5: Concept Verification (NEW QUALITY GATE)
-**Command**: `/workflow:concept-verify --session [sessionId]`
+### Phase 4: Conflict Resolution (Optional - auto-triggered by conflict risk)
 
-**Purpose**: Verify conceptual clarity before TDD task generation
-- Clarify test requirements and acceptance criteria
-- Resolve ambiguities in expected behavior
-- Validate TDD approach is appropriate
+**Trigger**: Only execute when context-package.json indicates conflict_risk is "medium" or "high"
 
-**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
+**Command**: `SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")`
 
-**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+**Input**:
+- sessionId from Phase 1
+- contextPath from Phase 2
+- conflict_risk from context-package.json
 
-### Phase 6: TDD Task Generation
+**Parse Output**:
+- Extract: Execution status (success/skipped/failed)
+- Verify: CONFLICT_RESOLUTION.md file path (if executed)
+
+**Validation**:
+- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
+
+**Skip Behavior**:
+- If conflict_risk is "none" or "low", skip directly to Phase 5
+- Display: "No significant conflicts detected, proceeding to TDD task generation"
+
+**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
+
+**After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
+
+**Memory State Check**:
+- Evaluate current context window usage and memory state
+- If memory usage is high (>110K tokens or approaching context limits):
+  - **Command**: `SlashCommand(command="/compact")`
+  - This optimizes memory before proceeding to Phase 5
+- Memory compaction is particularly important after analysis phase which may generate extensive documentation
+- Ensures optimal performance and prevents context overflow
+
+---
+
+### Phase 5: TDD Task Generation
 **Command**:
 - Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
 - Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
 
-**Parse**: Extract feature count, chain count, task count
+**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
 
 **Validate**:
-- IMPL_PLAN.md exists (unified plan with TDD Task Chains section)
-- TEST-*.json, IMPL-*.json, REFACTOR-*.json exist
-- TODO_LIST.md exists
-- IMPL tasks include test-fix-cycle configuration
+- IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
+- IMPL-*.json files exist (one per feature, or container + subtasks for complex features)
+- TODO_LIST.md exists with internal TDD phase indicators
+- Each IMPL task includes:
+  - `meta.tdd_workflow: true`
+  - `flow_control.implementation_approach` with 3 steps (red/green/refactor)
+  - Green phase includes test-fix-cycle configuration
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
+- Task count ≤10 (compliance with task limit)
 
-### Phase 7: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
+### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
 **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")
-4. Agents: TEST uses @code-review-test-agent, IMPL/REFACTOR use @code-developer
-5. IMPL tasks contain test-fix-cycle in flow_control for iterative Green phase
+1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
+2. Task structure validation:
+   - `meta.tdd_workflow: true` in all IMPL tasks
+   - `flow_control.implementation_approach` has exactly 3 steps
+   - Each step has correct `tdd_phase`: "red", "green", "refactor"
+3. Dependency validation:
+   - Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
+   - Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
+4. Agent assignment: All IMPL tasks use @code-developer
+5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
+6. Task count: Total tasks ≤10 (simple + subtasks)
 
 **Return Summary**:
 ```
 TDD Planning complete for session: [sessionId]
 
 Features analyzed: [N]
-TDD chains generated: [N]
-Total tasks: [3N]
+Total tasks: [M] (1 task per simple feature + subtasks for complex features)
+
+Task breakdown:
+- Simple features: [K] tasks (IMPL-1 to IMPL-K)
+- Complex features: [L] features with [P] subtasks
+- Total task count: [M] (within 10-task limit ✅)
 
 Structure:
-- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
+- IMPL-1: {Feature 1 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-2: {Feature 2 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-3: {Complex Feature} (Container)
+  - IMPL-3.1: {Sub-feature A} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+  - IMPL-3.2: {Sub-feature B} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
 [...]
 
-Plan:
+Plans generated:
 - Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
-  (includes TDD Task Chains section with workflow_type: "tdd")
+  (includes TDD Implementation Tasks section with workflow_type: "tdd")
+- Task List: .workflow/[sessionId]/TODO_LIST.md
+  (with internal TDD phase indicators)
+
+TDD Configuration:
+- Each task contains complete Red-Green-Refactor cycle
+- Green phase includes test-fix cycle (max 3 iterations)
+- Auto-revert on max iterations reached
 
 ✅ Recommended Next Steps:
-1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
 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
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
 ```
 
 ## TodoWrite Pattern
 
 ```javascript
-// 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 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"}
-]
+// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
+TodoWrite({todos: [
+  {"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"},
+  // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
 
-// Update after each phase: mark current "completed", next "in_progress"
+// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
+
+// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
+
+// After Phase 4 (if executed), continue to Phase 5
+TodoWrite({todos: [
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]})
 ```
 
 ## Input Processing
@@ -237,14 +320,18 @@ Supports action-planning-agent for more autonomous TDD planning with:
 
 ### Workflow Comparison
 
-| Aspect | Previous | Current |
-|--------|----------|---------|
-| **Phases** | 5 | 6 (test coverage analysis) |
+| Aspect | Previous | Current (Optimized) |
+|--------|----------|---------------------|
+| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
 | **Context** | Greenfield assumption | Existing codebase aware |
+| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
+| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
 | **Green Phase** | Single implementation | Iterative with fix cycle |
 | **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
 | **Test Analysis** | None | Deep coverage analysis |
 | **Feedback Loop** | Post-execution | During Green phase |
+| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
+| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
 
 ### Migration Notes
 
@@ -256,19 +343,26 @@ Supports action-planning-agent for more autonomous TDD planning with:
 **Session Structure**:
 ```
 .workflow/WFS-xxx/
-├── IMPL_PLAN.md (unified plan with TDD Task Chains section)
-├── TODO_LIST.md
+├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
+├── TODO_LIST.md (with internal TDD phase indicators)
 ├── .process/
 │   ├── context-package.json
 │   ├── test-context-package.json
 │   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
-│   └── green-fix-iteration-*.md (fix logs)
+│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
 └── .task/
-    ├── TEST-*.json (Red phase)
-    ├── IMPL-*.json (Green phase with test-fix-cycle)
-    └── REFACTOR-*.json (Refactor phase)
+    ├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
+    ├── IMPL-2.json (Complete TDD task)
+    ├── IMPL-3.json (Complex feature container, if needed)
+    ├── IMPL-3.1.json (Complex feature subtask, if needed)
+    └── IMPL-3.2.json (Complex feature subtask, if needed)
 ```
 
+**File Count Comparison**:
+- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
+- **New structure**: 5 features = 5 task files (IMPL-N × 5)
+- **Complex features**: Add container + subtasks only when necessary
+
 **Configuration Options** (in IMPL tasks):
 - `meta.max_iterations`: Fix attempts (default: 3)
 - `meta.use_codex`: Auto-fix mode (default: false)

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

@@ -1,12 +1,9 @@
 ---
 name: tdd-verify
 description: Verify TDD workflow compliance and generate quality report
-usage: /workflow:tdd-verify [session-id]
-argument-hint: "[WFS-session-id]"
-examples:
-  - /workflow:tdd-verify
-  - /workflow:tdd-verify WFS-auth
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini-wrapper:*)
+
+argument-hint: "[optional: WFS-session-id]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
 ---
 
 # TDD Verification Command (/workflow:tdd-verify)
@@ -97,7 +94,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 **Gemini analysis for comprehensive TDD compliance report**
 
 ```bash
-cd project-root && ~/.claude/scripts/gemini-wrapper -p "
+cd project-root && gemini -p "
 PURPOSE: Generate TDD compliance report
 TASK: Analyze TDD workflow execution and generate quality report
 CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
@@ -240,7 +237,7 @@ Final Score: Max(0, Base Score - Deductions)
 
 ### Command Chain
 - **Called After**: `/workflow:execute` (when TDD tasks completed)
-- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini wrapper
+- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini CLI
 - **Related**: `/workflow:tdd-plan`, `/workflow:status`
 
 ### Basic Usage

.claude/commands/workflow/test-cycle-execute.md

@@ -0,0 +1,662 @@
+---
+name: test-cycle-execute
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles
+argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
+---
+
+# Workflow Test-Cycle-Execute Command
+
+## Overview
+Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
+
+**⚠️ CRITICAL - Orchestrator Boundary**:
+- This command is the **ONLY place** where test failures are handled
+- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
+- Agents (@test-fix-agent) only execute single tasks and return results
+- **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
+
+**Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
+
+## Core Philosophy
+
+### Dynamic vs Static Execution
+**Standard Execute**: Pre-defined task queue → Sequential execution → Complete
+**Test Execute**: Initial tasks → Test → Analyze → Generate fix tasks → Execute → Re-test → Repeat
+
+### Iteration Loop Pattern
+```
+1. Execute current task (test/implement)
+2. Run tests and collect results
+3. If failures: CLI analysis → Generate fix tasks → Execute → Back to 2
+4. If success: Mark complete → Next task
+5. Repeat until all tests pass or max iterations reached
+```
+
+### Agent Coordination
+- **@code-developer**: Understands requirements, generates implementations
+- **@test-fix-agent**: Executes tests, applies fixes, validates results
+- **CLI Tools (Gemini/Qwen)**: Analyzes failures, suggests fix strategies
+
+## Core Rules
+1. **Dynamic Task Generation**: Create intermediate fix tasks based on test failures
+2. **Iterative Execution**: Repeat test-fix cycles until success or max iterations
+3. **CLI-Driven Analysis**: Use Gemini/Qwen to analyze failures and plan fixes
+4. **Agent Delegation**: All execution delegated to specialized agents
+5. **Context Accumulation**: Each iteration builds on previous attempt context
+6. **Autonomous Completion**: Continue until all tests pass without user interruption
+
+## Core Responsibilities
+- **Session Discovery**: Identify test-fix workflow sessions
+- **Task Queue Management**: Maintain dynamic task queue with runtime additions
+- **Test Execution**: Run tests through @test-fix-agent
+- **Failure Analysis**: Use CLI tools to diagnose test failures
+- **Fix Task Generation**: Create intermediate fix tasks dynamically
+- **Iteration Control**: Manage fix cycles with max iteration limits
+- **Context Propagation**: Pass failure context and fix history between iterations
+- **Progress Tracking**: TodoWrite updates for entire iteration cycle
+- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
+
+## Responsibility Matrix
+
+**⚠️ CRITICAL - Clear division of labor between orchestrator and agents:**
+
+| Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
+|----------------|----------------------------|---------------------------|
+| Manage iteration loop | ✅ Controls loop flow | ❌ Executes single task |
+| Run CLI analysis (Gemini/Qwen) | ✅ Runs between agent tasks | ❌ Not involved |
+| Generate IMPL-fix-N.json | ✅ Creates task files | ❌ Not involved |
+| Run tests | ❌ Delegates to agent | ✅ Executes test command |
+| Apply fixes | ❌ Delegates to agent | ✅ Modifies code |
+| Detect test failures | ✅ Analyzes results and decides next action | ✅ Executes tests and reports outcomes |
+| Add tasks to queue | ✅ Manages queue | ❌ Not involved |
+| Update iteration state | ✅ Maintains overall iteration state | ✅ Updates individual task status only |
+
+**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
+
+**⚠️ ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
+
+## Execution Lifecycle
+
+### Phase 1: Discovery & Initialization
+1. **Detect Session Type**: Identify test-fix session from `workflow_type: "test_session"`
+2. **Load Session State**: Read `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`
+3. **Scan Initial Tasks**: Analyze `.task/*.json` files
+4. **Initialize TodoWrite**: Create task list including initial tasks
+5. **Prepare Iteration Context**: Setup iteration counter and max limits
+
+**Resume Mode**: Load existing iteration context from `.process/iteration-state.json`
+
+### Phase 2: Task Execution Loop
+**Main execution loop with dynamic task generation (executed by test-cycle-execute orchestrator):**
+
+**Execution Order**: The workflow begins by executing IMPL-001 (test generation) first. Upon successful completion, IMPL-002 (test-fix cycle) is initiated, starting the iterative test-fix loop.
+
+```
+For each task in queue:
+  1. [Orchestrator] Load task JSON and context
+  2. [Orchestrator] Determine task type (test-gen, test-fix, fix-iteration)
+  3. [Orchestrator] Execute task through appropriate agent
+  4. [Orchestrator] Collect agent results and check exit conditions
+  5. If test failures detected:
+     a. [Orchestrator] Run CLI analysis (Gemini/Qwen)
+     b. [Orchestrator] Generate fix task JSON (IMPL-fix-N.json)
+     c. [Orchestrator] Insert fix task at front of queue
+     d. [Orchestrator] Continue loop
+  6. If test success:
+     a. [Orchestrator] Mark task complete
+     b. [Orchestrator] Update TodoWrite
+     c. [Orchestrator] Continue to next task
+  7. [Orchestrator] Check max iterations limit
+```
+
+**Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
+
+### Phase 3: Iteration Cycle (Test-Fix Loop)
+
+**Orchestrator-controlled iteration with agent delegation:**
+
+#### Iteration Structure
+```
+Iteration N (managed by test-cycle-execute orchestrator):
+├── 1. Test Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with test task
+│   ├── [Agent] Run test suite
+│   ├── [Agent] Collect failures and report back
+│   └── [Orchestrator] Receive failure report
+├── 2. Failure Analysis
+│   ├── [Orchestrator] Run CLI tool (Gemini/Qwen)
+│   ├── [CLI Tool] Analyze error messages and failure context
+│   ├── [CLI Tool] Identify root causes
+│   └── [CLI Tool] Generate fix strategy → saved to iteration-N-analysis.md
+├── 3. Fix Task Generation
+│   ├── [Orchestrator] Parse CLI analysis results
+│   ├── [Orchestrator] Create IMPL-fix-N.json with:
+│   │   ├── meta.agent: "@test-fix-agent"
+│   │   ├── Failure context (content, not just path)
+│   │   └── Fix strategy from CLI analysis
+│   └── [Orchestrator] Insert into task queue (front position)
+├── 4. Fix Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with fix task
+│   ├── [Agent] Load fix strategy from task context
+│   ├── [Agent] Apply fixes to code/tests
+│   └── [Agent] Report completion
+└── 5. Re-test
+    └── [Orchestrator] Return to step 1 with updated code
+```
+
+**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
+
+#### Iteration Task JSON Template
+```json
+{
+  "id": "IMPL-fix-{iteration}",
+  "title": "Fix test failures - Iteration {N}",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix-iteration",
+    "agent": "@test-fix-agent",
+    "iteration": N,
+    "parent_task": "IMPL-002",
+    "max_iterations": 5
+  },
+  "context": {
+    "requirements": [
+      "Fix identified test failures",
+      "Address root causes from analysis"
+    ],
+    "failure_context": {
+      "failed_tests": ["test1", "test2"],
+      "error_messages": ["error1", "error2"],
+      "failure_analysis": "Raw test output and error messages",
+      "previous_attempts": ["iteration-1 context"]
+    },
+    "fix_strategy": {
+      "approach": "Generated by CLI tool (Gemini/Qwen) analysis",
+      "modification_points": ["file1:func1", "file2:func2"],
+      "expected_outcome": "All tests pass"
+    },
+    "depends_on": ["IMPL-fix-{N-1}"],
+    "inherited": {
+      "iteration_history": [...]
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_failure_context",
+        "command": "Read(.workflow/{session}/.process/iteration-{N-1}-failures.json)",
+        "output_to": "previous_failures",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "load_fix_strategy",
+        "command": "Read(.workflow/{session}/.process/iteration-{N}-strategy.md)",
+        "output_to": "fix_strategy",
+        "on_error": "fail"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Apply fixes from strategy",
+        "description": "Implement fixes identified by CLI analysis",
+        "modification_points": "From fix_strategy",
+        "logic_flow": [
+          "Load failure context and strategy",
+          "Apply surgical fixes",
+          "Run tests",
+          "Validate fixes"
+        ]
+      }
+    ],
+    "target_files": ["from fix_strategy"],
+    "exit_conditions": {
+      "success": "all_tests_pass",
+      "failure": "max_iterations_reached",
+      "max_iterations": 5
+    }
+  }
+}
+```
+
+### Phase 4: CLI Analysis Integration
+
+**Orchestrator executes CLI analysis between agent tasks:**
+
+#### When Test Failures Occur
+1. **[Orchestrator]** Detects failures from agent test execution output
+2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
+3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
+4. **[Orchestrator]** Interprets CLI tool output to extract fix strategy
+5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
+6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
+
+**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
+
+#### CLI Analysis Command (executed by orchestrator)
+```bash
+cd {project_root} && gemini -p "
+PURPOSE: Analyze test failures and generate fix strategy
+TASK: Review test failures and identify root causes
+MODE: analysis
+CONTEXT: @test files @ implementation files
+
+[Test failure context and requirements...]
+
+EXPECTED: Detailed fix strategy in markdown format
+RULES: Focus on minimal changes, avoid over-engineering
+"
+```
+
+#### Analysis Output Structure
+```markdown
+# Test Failure Analysis - Iteration {N}
+
+## Root Cause Analysis
+1. **Test: test_auth_flow**
+   - Error: `Expected 200, got 401`
+   - Root Cause: Missing authentication token in request headers
+   - Affected Code: `src/auth/client.ts:45`
+
+2. **Test: test_data_validation**
+   - Error: `TypeError: Cannot read property 'name' of undefined`
+   - Root Cause: Null check missing before property access
+   - Affected Code: `src/validators/user.ts:23`
+
+## Fix Strategy
+
+### Priority 1: Authentication Issue
+- **File**: src/auth/client.ts
+- **Function**: sendRequest (line 45)
+- **Change**: Add token header: `headers['Authorization'] = 'Bearer ' + token`
+- **Verification**: Run test_auth_flow
+
+### Priority 2: Null Check
+- **File**: src/validators/user.ts
+- **Function**: validateUser (line 23)
+- **Change**: Add check: `if (!user?.name) return false`
+- **Verification**: Run test_data_validation
+
+## Verification Plan
+1. Apply fixes in order
+2. Run test suite after each fix
+3. Check for regressions
+4. Validate all tests pass
+
+## Risk Assessment
+- Low risk: Changes are surgical and isolated
+- No breaking changes expected
+- Existing tests should remain green
+```
+
+### Phase 5: Task Queue Management
+
+**Orchestrator maintains dynamic task queue with runtime insertions:**
+
+#### Dynamic Queue Operations
+```
+Initial Queue: [IMPL-001, IMPL-002]
+
+After IMPL-002 execution (test failures detected by orchestrator):
+  [Orchestrator] Generates IMPL-fix-1.json
+  [Orchestrator] Inserts at front: [IMPL-fix-1, IMPL-002-retest, ...]
+
+After IMPL-fix-1 execution (still failures):
+  [Orchestrator] Generates IMPL-fix-2.json
+  [Orchestrator] Inserts at front: [IMPL-fix-2, IMPL-002-retest, ...]
+
+After IMPL-fix-2 execution (success):
+  [Orchestrator] Continues to: [IMPL-002-complete, ...]
+```
+
+#### Queue Priority Rules (orchestrator-managed)
+1. **Fix tasks**: Inserted at queue front for immediate execution
+2. **Retest tasks**: Automatically scheduled after fix tasks
+3. **Regular tasks**: Standard dependency order preserved
+4. **Iteration limit**: Max 5 fix iterations per test task (orchestrator enforces)
+
+### Phase 6: Completion & Session Management
+
+#### Success Conditions
+- All initial tasks completed
+- All generated fix tasks completed
+- All tests passing
+- No pending tasks in queue
+
+#### Completion Steps
+1. **Final Validation**: Run full test suite one more time
+2. **Update Session State**: Mark all tasks completed
+3. **Generate Summary**: Create session completion summary
+4. **Update TodoWrite**: Mark all items completed
+5. **Auto-Complete**: Call `/workflow:session:complete`
+
+#### Failure Conditions
+- Max iterations reached without success
+- Unrecoverable test failures
+- Agent execution errors
+
+#### Failure Handling
+1. **Document State**: Save current iteration context
+2. **Generate Report**: Create failure analysis report
+3. **Preserve Context**: Keep all iteration logs
+4. **Mark Blocked**: Update task status to blocked
+5. **Return Control**: Return to user with detailed report
+
+## TodoWrite Coordination
+
+### TodoWrite Structure for Test-Execute
+```javascript
+TodoWrite({
+  todos: [
+    {
+      content: "Execute IMPL-001: Generate tests [code-developer]",
+      status: "completed",
+      activeForm: "Executing test generation"
+    },
+    {
+      content: "Execute IMPL-002: Test & Fix Cycle [test-fix-agent] [ITERATION]",
+      status: "in_progress",
+      activeForm: "Running test-fix iteration cycle"
+    },
+    {
+      content: "  → Iteration 1: Initial test run",
+      status: "completed",
+      activeForm: "Running initial tests"
+    },
+    {
+      content: "  → Iteration 2: Fix auth issues",
+      status: "in_progress",
+      activeForm: "Fixing authentication issues"
+    },
+    {
+      content: "  → Iteration 3: Re-test and validate",
+      status: "pending",
+      activeForm: "Re-testing after fixes"
+    }
+  ]
+});
+```
+
+### TodoWrite Update Rules
+1. **Initial Tasks**: Standard task list
+2. **Iteration Start**: Add nested iteration item
+3. **Fix Task Added**: Add fix task as nested item
+4. **Iteration Complete**: Mark iteration item completed
+5. **All Complete**: Mark parent task completed
+
+## Agent Context Package
+
+**Generated by test-cycle-execute orchestrator before launching agents.**
+
+The orchestrator assembles this context package from:
+- Task JSON file (IMPL-*.json)
+- Iteration state files
+- Test results and failure context
+- Session metadata
+
+This package is passed to agents via the Task tool's prompt context.
+
+### Enhanced Context for Test-Fix Agent
+```json
+{
+  "task": { /* IMPL-fix-N.json */ },
+  "iteration_context": {
+    "current_iteration": N,
+    "max_iterations": 5,
+    "previous_attempts": [
+      {
+        "iteration": N-1,
+        "failures": ["test1", "test2"],
+        "fixes_attempted": ["fix1", "fix2"],
+        "result": "partial_success"
+      }
+    ],
+    "failure_analysis": {
+      "source": "gemini_cli",
+      "analysis_file": ".process/iteration-N-analysis.md",
+      "fix_strategy": { /* from CLI */ }
+    }
+  },
+  "test_context": {
+    "test_framework": "jest|pytest|...",
+    "test_files": ["path/to/test1.test.ts"],
+    "test_command": "npm test",
+    "coverage_target": 80
+  },
+  "session": {
+    "workflow_dir": ".workflow/WFS-test-{session}/",
+    "iteration_state_file": ".process/iteration-state.json",
+    "test_results_file": ".process/test-results.json",
+    "fix_history_file": ".process/fix-history.json"
+  }
+}
+```
+
+## File Structure
+
+### Test-Fix Session Files
+```
+.workflow/WFS-test-{session}/
+├── workflow-session.json          # Session metadata with workflow_type
+├── IMPL_PLAN.md                   # Test plan
+├── TODO_LIST.md                   # Progress tracking
+├── .task/
+│   ├── IMPL-001.json              # Test generation task
+│   ├── IMPL-002.json              # Initial test-fix task
+│   ├── IMPL-fix-1.json            # Generated: Iteration 1 fix
+│   ├── IMPL-fix-2.json            # Generated: Iteration 2 fix
+│   └── ...
+├── .summaries/
+│   ├── IMPL-001-summary.md
+│   ├── IMPL-002-summary.md
+│   └── iteration-summaries/
+│       ├── iteration-1.md
+│       ├── iteration-2.md
+│       └── ...
+└── .process/
+    ├── TEST_ANALYSIS_RESULTS.md   # From planning phase
+    ├── iteration-state.json       # Current iteration state
+    ├── test-results.json          # Latest test results
+    ├── test-output.log            # Full test output
+    ├── fix-history.json           # All fix attempts
+    ├── iteration-1-analysis.md    # CLI analysis for iteration 1
+    ├── iteration-1-failures.json  # Failures from iteration 1
+    ├── iteration-1-strategy.md    # Fix strategy for iteration 1
+    ├── iteration-2-analysis.md
+    └── ...
+```
+
+### Iteration State JSON
+```json
+{
+  "session_id": "WFS-test-user-auth",
+  "current_task": "IMPL-002",
+  "current_iteration": 2,
+  "max_iterations": 5,
+  "started_at": "2025-10-17T10:00:00Z",
+  "iterations": [
+    {
+      "iteration": 1,
+      "started_at": "2025-10-17T10:05:00Z",
+      "completed_at": "2025-10-17T10:15:00Z",
+      "test_results": {
+        "total": 10,
+        "passed": 7,
+        "failed": 3,
+        "failures": ["test1", "test2", "test3"]
+      },
+      "analysis_file": ".process/iteration-1-analysis.md",
+      "fix_task": "IMPL-fix-1",
+      "result": "partial_success"
+    }
+  ],
+  "status": "active",
+  "next_action": "execute_fix_task"
+}
+```
+
+## Agent Prompt Template
+
+**Unified template for all agent tasks (orchestrator invokes with Task tool):**
+
+```bash
+Task(subagent_type="{meta.agent}",
+     prompt="**TASK EXECUTION: {task.title}**
+
+     ## STEP 1: Load Complete Task JSON
+     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+
+     cat {session.task_json_path}
+
+     **CRITICAL**: Validate all required fields present
+
+     ## STEP 2: Task Context (From Loaded JSON)
+     **ID**: {task.id}
+     **Type**: {task.meta.type}
+     **Agent**: {task.meta.agent}
+
+     ## STEP 3: Execute Task Based on Type
+
+     ### For test-gen (IMPL-001):
+     - Generate tests based on TEST_ANALYSIS_RESULTS.md
+     - Follow test framework conventions
+     - Create test files in target_files
+
+     ### For test-fix (IMPL-002):
+     - Run test suite: {test_command}
+     - Collect results to .process/test-results.json
+     - Report results to orchestrator (do NOT analyze failures)
+     - Orchestrator will handle failure detection and iteration decisions
+     - If success: Mark complete
+
+     ### For test-fix-iteration (IMPL-fix-N):
+     - Load fix strategy from context.fix_strategy (CONTENT, not path)
+     - Apply surgical fixes to identified files
+     - Return results to orchestrator
+     - Do NOT run tests independently - orchestrator manages all test execution
+     - Do NOT handle failures - orchestrator analyzes and decides next iteration
+
+     ## STEP 4: Implementation Context (From JSON)
+     **Requirements**: {context.requirements}
+     **Fix Strategy**: {context.fix_strategy} (full content provided in task JSON)
+     **Failure Context**: {context.failure_context}
+     **Iteration History**: {context.inherited.iteration_history}
+
+     ## STEP 5: Flow Control Execution
+     If flow_control.pre_analysis exists, execute steps sequentially
+
+     ## STEP 6: Agent Completion
+     1. Execute task following implementation_approach
+     2. Update task status in JSON
+     3. Update TODO_LIST.md
+     4. Generate summary in .summaries/
+     5. **CRITICAL**: Save results for orchestrator to analyze
+
+     **Output Requirements**:
+     - test-results.json: Structured test results
+     - test-output.log: Full test output
+     - iteration-state.json: Current iteration state (if applicable)
+     - task-summary.md: Completion summary
+
+     **Return to Orchestrator**: Agent completes and returns. Orchestrator decides next action.
+     "),
+     description="Execute {task.type} task with JSON validation")
+```
+
+**Key Points**:
+- Agent executes single task and returns
+- Orchestrator analyzes results and decides next step
+- Fix strategy content (not path) embedded in task JSON by orchestrator
+- Agent does not manage iteration loop
+
+## Error Handling & Recovery
+
+### Iteration Failure Scenarios
+| Scenario | Handling | Recovery |
+|----------|----------|----------|
+| Test execution error | Log error, save context | Retry with error context |
+| CLI analysis failure | Fallback to Qwen, or manual analysis | Retry analysis with different tool |
+| Agent execution error | Save iteration state | Retry agent with simplified context |
+| Max iterations reached | Generate failure report | Mark blocked, return to user |
+| Unexpected test regression | Rollback last fix | Analyze regression, add to fix strategy |
+
+### Recovery Procedures
+
+#### Resume from Interruption
+```bash
+# Load iteration state
+iteration_state=$(cat .workflow/{session}/.process/iteration-state.json)
+current_iteration=$(jq -r '.current_iteration' <<< "$iteration_state")
+
+# Determine resume point
+if [[ "$(jq -r '.next_action' <<< "$iteration_state")" == "execute_fix_task" ]]; then
+  # Resume fix task execution
+  task_id="IMPL-fix-${current_iteration}"
+else
+  # Resume test execution
+  task_id="IMPL-002"
+fi
+```
+
+#### Rollback Failed Fix
+```bash
+# Revert last commit (if fixes were committed)
+git revert HEAD
+
+# Remove failed fix task
+rm .workflow/{session}/.task/IMPL-fix-{N}.json
+
+# Restore iteration state
+jq '.current_iteration -= 1' iteration-state.json > temp.json
+mv temp.json iteration-state.json
+
+# Re-run analysis with additional context
+# Include failure reason in next analysis
+```
+
+## Usage Examples
+
+### Basic Usage
+```bash
+# Execute test-fix workflow
+/workflow:test-cycle-execute
+
+# Resume interrupted session
+/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
+
+# Set custom iteration limit
+/workflow:test-cycle-execute --max-iterations=10
+```
+
+### Integration with Planning
+```bash
+# 1. Plan test workflow
+/workflow:test-fix-gen WFS-user-auth
+
+# 2. Execute with dynamic iteration
+/workflow:test-cycle-execute
+
+# 3. Monitor progress
+/workflow:status
+
+# 4. Resume if interrupted
+/workflow:test-cycle-execute --resume-session="WFS-test-user-auth"
+```
+
+## Best Practices
+
+1. **Set Realistic Iteration Limits**: Default 5, increase for complex fixes
+2. **Commit Between Iterations**: Easier rollback if needed
+3. **Monitor Iteration Logs**: Review CLI analysis for insights
+4. **Incremental Fixes**: Prefer multiple small iterations over large changes
+5. **Verify No Regressions**: Check all tests pass, not just previously failing ones
+6. **Preserve Context**: All iteration artifacts saved for debugging
+
+## Related Commands
+
+- `/workflow:test-fix-gen` - Planning phase (creates initial tasks)
+- `/workflow:execute` - Standard workflow execution (no dynamic iteration)
+- `/workflow:status` - Check progress and iteration state
+- `/workflow:session:complete` - Mark session complete (auto-called on success)
+- `/task:create` - Manually create additional tasks if needed

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

@@ -0,0 +1,486 @@
+---
+name: test-fix-gen
+description: Create independent test-fix workflow session from existing implementation (session or prompt-based)
+argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
+---
+
+# Workflow Test-Fix Generation Command (/workflow:test-fix-gen)
+
+## Overview
+
+### What It Does
+
+This command creates an independent test-fix workflow session for existing code. It orchestrates a 5-phase process to analyze implementation, generate test requirements, and create executable test generation and fix tasks.
+
+**⚠️ CRITICAL - Command Scope**:
+- **This command ONLY generates task JSON files** (IMPL-001.json, IMPL-002.json)
+- **Does NOT execute tests or apply fixes** - all execution happens in separate orchestrator
+- **Must call `/workflow:test-cycle-execute`** after this command to actually run tests and fixes
+- **Test failure handling happens in test-cycle-execute**, not here
+
+### Dual-Mode Support
+
+**Automatic mode detection** based on input pattern:
+
+| Mode | Input Pattern | Context Source | Use Case |
+|------|--------------|----------------|----------|
+| **Session Mode** | `WFS-xxx` | Source session summaries | Test validation for completed workflow |
+| **Prompt Mode** | Text or file path | Direct codebase analysis | Test generation from description |
+
+**Detection Logic**:
+```bash
+if [[ "$input" == WFS-* ]]; then
+  MODE="session"  # Use test-context-gather
+else
+  MODE="prompt"   # Use context-gather
+fi
+```
+
+### Core Principles
+
+- **Dual Input Support**: Accepts session ID (WFS-xxx) or feature description/file path
+- **Session Isolation**: Creates independent `WFS-test-[slug]` session
+- **Context-First**: Gathers implementation context via appropriate method
+- **Format Reuse**: Creates standard `IMPL-*.json` tasks with `meta.type: "test-fix"`
+- **Manual First**: Default to manual fixes, use `--use-codex` for automation
+- **Automatic Detection**: Input pattern determines execution mode
+
+### Coordinator Role
+
+This command is a **pure planning coordinator**:
+- Does NOT analyze code directly
+- Does NOT generate tests or documentation
+- Does NOT execute tests or apply fixes
+- Does NOT handle test failures or iterations
+- ONLY coordinates slash commands to generate task JSON files
+- Parses outputs to pass data between phases
+- Creates independent test workflow session
+- **All execution delegated to `/workflow:test-cycle-execute`**
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+# Basic syntax
+/workflow:test-fix-gen [FLAGS] <INPUT>
+
+# Flags (optional)
+--use-codex        # Enable Codex automated fixes in IMPL-002
+--cli-execute      # Enable CLI execution in IMPL-001
+
+# Input
+<INPUT>            # Session ID, description, or file path
+```
+
+### Usage Examples
+
+#### Session Mode
+```bash
+# Test validation for completed implementation
+/workflow:test-fix-gen WFS-user-auth-v2
+
+# With automated fixes
+/workflow:test-fix-gen --use-codex WFS-api-endpoints
+
+# With CLI execution
+/workflow:test-fix-gen --cli-execute --use-codex WFS-payment-flow
+```
+
+#### Prompt Mode - Text Description
+```bash
+# Generate tests from feature description
+/workflow:test-fix-gen "Test the user authentication API endpoints in src/auth/api.ts"
+
+# With automated fixes
+/workflow:test-fix-gen --use-codex "Test user registration and login flows"
+```
+
+#### Prompt Mode - File Reference
+```bash
+# Generate tests from requirements file
+/workflow:test-fix-gen ./docs/api-requirements.md
+
+# With flags
+/workflow:test-fix-gen --use-codex --cli-execute ./specs/feature.md
+```
+
+### Mode Comparison
+
+| Aspect | Session Mode | Prompt Mode |
+|--------|-------------|-------------|
+| **Phase 1** | Create `WFS-test-[source]` with `source_session_id` | Create `WFS-test-[slug]` without `source_session_id` |
+| **Phase 2** | `/workflow:tools:test-context-gather` | `/workflow:tools:context-gather` |
+| **Phase 3-5** | Identical | Identical |
+| **Context** | Source session summaries + artifacts | Direct codebase analysis |
+
+---
+
+## Execution Flow
+
+### Core Execution Rules
+
+1. **Start Immediately**: First action is TodoWrite, second is Phase 1 session creation
+2. **No Preliminary Analysis**: Do not read files before Phase 1
+3. **Parse Every Output**: Extract required data from each phase for next phase
+4. **Sequential Execution**: Each phase depends on previous phase's output
+5. **Complete All Phases**: Do not return until Phase 5 completes
+6. **Track Progress**: Update TodoWrite after every phase
+7. **Automatic Detection**: Mode auto-detected from input pattern
+8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+
+### 5-Phase Execution
+
+#### Phase 1: Create Test Session
+
+**Command**:
+- **Session Mode**: `SlashCommand("/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
+- **Prompt Mode**: `SlashCommand("/workflow:session:start --new \"Test generation for: [description]\"")`
+
+**Input**: User argument (session ID, description, or file path)
+
+**Expected Behavior**:
+- Creates new session: `WFS-test-[slug]`
+- Writes `workflow-session.json` metadata:
+  - **Session Mode**: Includes `workflow_type: "test_session"`, `source_session_id: "[sourceId]"`
+  - **Prompt Mode**: Includes `workflow_type: "test_session"` only
+- Returns new session ID
+
+**Parse Output**:
+- Extract: `testSessionId` (pattern: `WFS-test-[slug]`)
+
+**Validation**:
+- **Session Mode**: Source session exists with completed IMPL tasks
+- **Both Modes**: New test session directory created with metadata
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+#### Phase 2: Gather Test Context
+
+**Command**:
+- **Session Mode**: `SlashCommand("/workflow:tools:test-context-gather --session [testSessionId]")`
+- **Prompt Mode**: `SlashCommand("/workflow:tools:context-gather --session [testSessionId] \"[task_description]\"")`
+
+**Input**: `testSessionId` from Phase 1
+
+**Expected Behavior**:
+- **Session Mode**:
+  - Load source session implementation context and summaries
+  - Analyze test coverage using MCP tools
+  - Identify files requiring tests
+- **Prompt Mode**:
+  - Analyze codebase based on description
+  - Identify relevant files and dependencies
+- Detect test framework and conventions
+- Generate context package JSON
+
+**Parse Output**:
+- Extract: `contextPath` (pattern: `.workflow/[testSessionId]/.process/[test-]context-package.json`)
+
+**Validation**:
+- Context package created with coverage analysis
+- Test framework detected
+- Test conventions documented
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+#### Phase 3: Test Generation Analysis
+
+**Command**: `SlashCommand("/workflow:tools:test-concept-enhanced --session [testSessionId] --context [contextPath]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `contextPath` from Phase 2
+
+**Expected Behavior**:
+- Use Gemini to analyze coverage gaps and implementation
+- Study existing test patterns and conventions
+- Generate test requirements for missing test files
+- Design test generation strategy
+- Generate `TEST_ANALYSIS_RESULTS.md`
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
+
+**Validation**:
+- TEST_ANALYSIS_RESULTS.md exists with complete sections:
+  - Coverage Assessment
+  - Test Framework & Conventions
+  - Test Requirements by File
+  - Test Generation Strategy
+  - Implementation Targets
+  - Success Criteria
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+---
+
+#### Phase 4: Generate Test Tasks
+
+**Command**: `SlashCommand("/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `--use-codex` flag (if present) - Controls IMPL-002 fix mode
+- `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
+
+**Expected Behavior**:
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
+- Generate **minimum 2 task JSON files** (expandable based on complexity):
+  - **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
+  - **IMPL-002.json**: Test Execution & Fix Cycle (`@test-fix-agent`)
+  - **IMPL-003+**: Additional tasks if needed for complex projects
+- Generate `IMPL_PLAN.md` with test strategy
+- Generate `TODO_LIST.md` with task checklist
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
+- Verify additional `.task/IMPL-*.json` if applicable
+- Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
+
+**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
+
+---
+
+#### Phase 5: Return Summary
+
+**Return to User**:
+```
+Independent test-fix workflow created successfully!
+
+Input: [original input]
+Mode: [Session|Prompt]
+Test Session: [testSessionId]
+
+Tasks Created:
+- IMPL-001: Test Understanding & Generation (@code-developer)
+- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+[- IMPL-003+: Additional tasks if applicable]
+
+Test Framework: [detected framework]
+Test Files to Generate: [count]
+Max Fix Iterations: 5
+Fix Mode: [Manual|Codex Automated]
+
+Review artifacts:
+- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
+- Task list: .workflow/[testSessionId]/TODO_LIST.md
+
+⚠️ CRITICAL - Next Steps:
+1. Review IMPL_PLAN.md
+2. **MUST execute: /workflow:test-cycle-execute**
+   - This command only generated task JSON files
+   - Test execution and fix iterations happen in test-cycle-execute
+   - Do NOT attempt to run tests or fixes in main workflow
+```
+
+**TodoWrite**: Mark phase 5 completed
+
+**⚠️ BOUNDARY NOTE**:
+- Command completes here - only task JSON files generated
+- All test execution, failure detection, CLI analysis, fix generation happens in `/workflow:test-cycle-execute`
+- This command does NOT handle test failures or apply fixes
+
+---
+
+### TodoWrite Progress Tracking
+
+Track all 5 phases:
+
+```javascript
+TodoWrite({todos: [
+  {"content": "Create independent test session", "status": "in_progress|completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "pending|in_progress|completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending|in_progress|completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending|in_progress|completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending|in_progress|completed", "activeForm": "Returning workflow summary"}
+]})
+```
+
+Update status to `in_progress` when starting each phase, `completed` when done.
+
+---
+
+## Task Specifications
+
+Generates minimum 2 tasks (expandable for complex projects):
+
+### IMPL-001: Test Understanding & Generation
+
+**Agent**: `@code-developer`
+
+**Purpose**: Understand source implementation and generate test files
+
+**Task Configuration**:
+- Task ID: `IMPL-001`
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Understand source implementation and generate tests
+- `flow_control.target_files`: Test files to create from TEST_ANALYSIS_RESULTS.md section 5
+
+**Execution Flow**:
+1. **Understand Phase**:
+   - Load TEST_ANALYSIS_RESULTS.md and test context
+   - Understand source code implementation patterns
+   - Analyze test requirements and conventions
+   - Identify test scenarios and edge cases
+2. **Generation Phase**:
+   - Generate test files following existing patterns
+   - Ensure test coverage aligns with requirements
+3. **Verification Phase**:
+   - Verify test completeness and correctness
+
+### IMPL-002: Test Execution & Fix Cycle
+
+**Agent**: `@test-fix-agent`
+
+**Purpose**: Execute initial tests and trigger orchestrator-managed fix cycles
+
+**Note**: This task executes tests and reports results. The test-cycle-execute orchestrator manages all fix iterations, CLI analysis, and fix task generation.
+
+**Task Configuration**:
+- Task ID: `IMPL-002`
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex: true|false` (based on `--use-codex` flag)
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Execute and fix tests
+
+**Test-Fix Cycle Specification**:
+**Note**: This specification describes what test-cycle-execute orchestrator will do. The agent only executes single tasks.
+- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → manual_fix (or codex) → retest
+- **Tools Configuration** (orchestrator-controlled):
+  - Gemini for analysis with bug-fix template → surgical fix suggestions
+  - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
+- **Exit Conditions** (orchestrator-enforced):
+  - Success: All tests pass
+  - Failure: Max iterations reached (5)
+
+**Execution Flow**:
+1. **Phase 1**: Initial test execution
+2. **Phase 2**: Iterative Gemini diagnosis + manual/Codex fixes
+3. **Phase 3**: Final validation and certification
+
+### IMPL-003+: Additional Tasks (Optional)
+
+**Scenarios for Multiple Tasks**:
+- Large projects requiring per-module test generation
+- Separate integration vs unit test tasks
+- Specialized test types (performance, security, etc.)
+
+**Agent**: `@code-developer` or specialized agents based on requirements
+
+---
+
+## Artifacts & Output
+
+### Output Files Structure
+
+Created in `.workflow/WFS-test-[session]/`:
+
+```
+WFS-test-[session]/
+├── workflow-session.json          # Session metadata
+├── IMPL_PLAN.md                   # Test generation and execution strategy
+├── TODO_LIST.md                   # Task checklist
+├── .task/
+│   ├── IMPL-001.json              # Test understanding & generation
+│   ├── IMPL-002.json              # Test execution & fix cycle
+│   └── IMPL-*.json                # Additional tasks (if applicable)
+└── .process/
+    ├── [test-]context-package.json # Context and coverage analysis
+    └── TEST_ANALYSIS_RESULTS.md    # Test requirements and strategy
+```
+
+### Session Metadata
+
+**File**: `workflow-session.json`
+
+**Session Mode** includes:
+- `workflow_type: "test_session"`
+- `source_session_id: "[sourceSessionId]"` (enables automatic cross-session context)
+
+**Prompt Mode** includes:
+- `workflow_type: "test_session"`
+- No `source_session_id` field
+
+### Complete Data Flow
+
+**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
+
+**Phase Execution Chain**:
+1. Phase 1: `session-start` → `WFS-test-user-auth`
+2. Phase 2: `test-context-gather` → `test-context-package.json`
+3. Phase 3: `test-concept-enhanced` → `TEST_ANALYSIS_RESULTS.md`
+4. Phase 4: `test-task-generate` → `IMPL-001.json` + `IMPL-002.json` (+ additional if needed)
+5. Phase 5: Return summary
+
+**Command completes after Phase 5**
+
+---
+
+## Reference
+
+### Error Handling
+
+| Phase | Error Condition | Action |
+|-------|----------------|--------|
+| 1 | Source session not found (session mode) | Return error with source session ID |
+| 1 | No completed IMPL tasks (session mode) | Return error, source incomplete |
+| 2 | Context gathering failed | Return error, check source artifacts |
+| 3 | Gemini analysis failed | Return error, check context package |
+| 4 | Task generation failed | Retry once, then return error with details |
+
+### Best Practices
+
+1. **Before Running**:
+   - Ensure implementation is complete (session mode: check summaries exist)
+   - Commit all implementation changes
+   - Review source code quality
+
+2. **After Running**:
+   - Review generated `IMPL_PLAN.md` before execution
+   - Check `TEST_ANALYSIS_RESULTS.md` for completeness
+   - Verify task dependencies in `TODO_LIST.md`
+
+3. **During Execution**:
+   - Monitor iteration logs in `.process/fix-iteration-*`
+   - Track progress with `/workflow:status`
+   - Review Gemini diagnostic outputs
+
+4. **Mode Selection**:
+   - Use **Session Mode** for completed workflow validation
+   - Use **Prompt Mode** for ad-hoc test generation
+   - Use `--use-codex` for autonomous fix application
+   - Use `--cli-execute` for enhanced generation capabilities
+
+### Related Commands
+
+**Planning Phase**:
+- `/workflow:plan` - Create implementation workflow
+- `/workflow:session:start` - Initialize workflow session
+
+**Context Gathering**:
+- `/workflow:tools:test-context-gather` - Session-based context (Phase 2 for session mode)
+- `/workflow:tools:context-gather` - Prompt-based context (Phase 2 for prompt mode)
+
+**Analysis & Task Generation**:
+- `/workflow:tools:test-concept-enhanced` - Gemini test analysis (Phase 3)
+- `/workflow:tools:test-task-generate` - Generate test tasks (Phase 4)
+
+**Execution**:
+- `/workflow:test-cycle-execute` - Execute test-fix workflow (recommended for IMPL-002)
+- `/workflow:execute` - Execute standard workflow tasks
+- `/workflow:status` - Check task progress
+
+**Review & Management**:
+- `/workflow:review` - Review workflow results
+- `/workflow:session:complete` - Mark session complete

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

@@ -1,11 +1,7 @@
 ---
 name: test-gen
 description: Create independent test-fix workflow session by analyzing completed implementation
-usage: /workflow:test-gen [--use-codex] <source-session-id>
-argument-hint: "[--use-codex] <source-session-id>"
-examples:
-  - /workflow:test-gen WFS-user-auth
-  - /workflow:test-gen --use-codex WFS-api-refactor
+argument-hint: "[--use-codex] [--cli-execute] source-session-id"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -28,16 +24,19 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
 4. Generate test task from analysis → Return summary
 
+**⚠️ Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
+
 ## Core Rules
 
 1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 test session creation
 2. **No Preliminary Analysis**: Do not read files or analyze before Phase 1
 3. **Parse Every Output**: Extract required data from each phase for next phase
 4. **Sequential Execution**: Each phase depends on previous phase's output
-5. **Complete All Phases**: Do not return to user until Phase 4 completes (execution triggered separately)
+5. **Complete All Phases**: Do not return to user until Phase 5 completes (summary returned)
 6. **Track Progress**: Update TodoWrite after every phase completion
 7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
 8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
+9. **⚠️ Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
 
 ## 5-Phase Execution
 
@@ -127,11 +126,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
 ### Phase 4: Generate Test Tasks
-**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] --session [testSessionId]")`
+**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")`
 
 **Input**:
 - `testSessionId` from Phase 1
-- `--use-codex` flag (if present in original command)
+- `--use-codex` flag (if present in original command) - Controls IMPL-002 fix mode
+- `--cli-execute` flag (if present in original command) - Controls IMPL-001 generation mode
 
 **Expected Behavior**:
 - Parse TEST_ANALYSIS_RESULTS.md from Phase 3
@@ -177,32 +177,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ---
 
-### Phase 5: Return Summary to User
+### Phase 5: Return Summary (⚠️ Command Ends Here)
+
+**⚠️ Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
 
 **Return to User**:
 ```
-Independent test-fix workflow created successfully!
+✅ Test workflow preparation complete!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
 
-Tasks Created:
-- IMPL-001: Test Generation (@code-developer)
-- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+Artifacts Created:
+- Test context analysis
+- Test generation strategy
+- Task definitions (IMPL-001, IMPL-002)
+- Implementation plan
 
 Test Framework: [detected framework]
 Test Files to Generate: [count]
-Max Fix Iterations: 5
 Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
-Next Steps:
-1. Review test plan: .workflow/[testSessionId]/IMPL_PLAN.md
-2. Execute workflow: /workflow:execute
-3. Monitor progress: /workflow:status
+📋 Review Generated Artifacts:
+- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
+- Task list: .workflow/[testSessionId]/TODO_LIST.md
+- Analysis: .workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
+
+⚠️ Ready for execution. Use appropriate workflow commands to proceed.
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
+**⚠️ Command Boundary**: After this phase, the command terminates and returns to user prompt.
+
 ---
 
 ## TodoWrite Pattern
@@ -224,19 +231,32 @@ Update status to `in_progress` when starting each phase, mark `completed` when d
 ## Data Flow
 
 ```
-/workflow:test-gen WFS-user-auth
-  ↓
-Phase 1: session-start → WFS-test-user-auth
-  ↓
-Phase 2: test-context-gather → test-context-package.json
-  ↓
-Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md
-  ↓
-Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json
-  ↓
-Phase 5: Return summary
-  ↓
-/workflow:execute → IMPL-001 (@code-developer) → IMPL-002 (@test-fix-agent)
+┌─────────────────────────────────────────────────────────┐
+│ /workflow:test-gen WFS-user-auth                        │
+├─────────────────────────────────────────────────────────┤
+│ Phase 1: session-start → WFS-test-user-auth            │
+│   ↓                                                     │
+│ Phase 2: test-context-gather → test-context-package.json│
+│   ↓                                                     │
+│ Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md│
+│   ↓                                                     │
+│ Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json│
+│   ↓                                                     │
+│ Phase 5: Return summary                                │
+└─────────────────────────────────────────────────────────┘
+         ⚠️ COMMAND ENDS - Control returns to user
+
+Artifacts Created:
+├── .workflow/WFS-test-[session]/
+│   ├── workflow-session.json
+│   ├── IMPL_PLAN.md
+│   ├── TODO_LIST.md
+│   ├── .task/
+│   │   ├── IMPL-001.json (test generation task)
+│   │   └── IMPL-002.json (test execution task)
+│   └── .process/
+│       ├── test-context-package.json
+│       └── TEST_ANALYSIS_RESULTS.md
 ```
 
 ## Session Metadata
@@ -245,9 +265,16 @@ Test session includes `workflow_type: "test_session"` and `source_session_id` fo
 
 ## Task Output
 
-Generates two tasks:
-- **IMPL-001** (@code-developer): Test generation from TEST_ANALYSIS_RESULTS.md
-- **IMPL-002** (@test-fix-agent): Test execution with iterative fix cycle (max 5 iterations)
+Generates two task definition files:
+- **IMPL-001.json**: Test generation task specification
+  - Agent: @code-developer
+  - Input: TEST_ANALYSIS_RESULTS.md
+  - Output: Test files based on analysis
+- **IMPL-002.json**: Test execution and fix cycle specification
+  - Agent: @test-fix-agent
+  - Dependency: IMPL-001 must complete first
+  - Max iterations: 5
+  - Fix mode: Manual or Codex (based on --use-codex flag)
 
 See `/workflow:tools:test-task-generate` for complete task JSON schemas.
 
@@ -272,28 +299,34 @@ Created in `.workflow/WFS-test-[session]/`:
 - `IMPL_PLAN.md` - Test plan
 - `TODO_LIST.md` - Task checklist
 
-## Agent Execution
+## Task Specifications
 
-**IMPL-001** (@code-developer):
-- Generates test files based on TEST_ANALYSIS_RESULTS.md
-- Follows existing test patterns and conventions
+**IMPL-001.json Structure**:
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
+- `flow_control.target_files`: Test files to create
+- `flow_control.implementation_approach`: Test generation strategy
 
-**IMPL-002** (@test-fix-agent):
-1. Run test suite
-2. Iterative fix cycle (max 5):
-   - Gemini diagnosis with bug-fix template → surgical fix suggestions
-   - Manual fix application (default) OR Codex applies fixes if --use-codex flag (resume mechanism)
-   - Retest and check regressions
-3. Final validation and certification
+**IMPL-002.json Structure**:
+- `meta.type: "test-fix"`
+- `meta.agent: "@test-fix-agent"`
+- `meta.use_codex`: true/false (based on --use-codex flag)
+- `context.depends_on: ["IMPL-001"]`
+- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
+  - Gemini diagnosis template
+  - Fix application mode (manual/codex)
+  - Max iterations: 5
+- `flow_control.implementation_approach.modification_points`: 3-phase flow
 
-See `/workflow:tools:test-task-generate` for detailed specifications.
+See `/workflow:tools:test-task-generate` for complete JSON schemas.
 
 ## Best Practices
 
-1. Run after implementation complete (ensure source session has summaries)
-2. Commit implementation changes before test-gen
-3. Monitor execution with `/workflow:status`
-4. Review iteration logs in `.process/fix-iteration-*`
+1. **Prerequisites**: Ensure source session has completed IMPL tasks with summaries
+2. **Clean State**: Commit implementation changes before running test-gen
+3. **Review Artifacts**: Check generated IMPL_PLAN.md and TODO_LIST.md before proceeding
+4. **Understand Scope**: This command only prepares artifacts; it does not execute tests
 
 ## Related Commands
 

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

@@ -1,533 +0,0 @@
----
-name: concept-enhanced
-description: Enhanced intelligent analysis with parallel CLI execution and design blueprint generation
-usage: /workflow:tools:concept-enhanced --session <session_id> --context <context_package_path>
-argument-hint: "--session WFS-session-id --context path/to/context-package.json"
-examples:
-  - /workflow:tools:concept-enhanced --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
-  - /workflow:tools:concept-enhanced --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
----
-
-# Enhanced Analysis Command (/workflow:tools:concept-enhanced)
-
-## Overview
-Advanced solution design and feasibility analysis engine with parallel CLI execution that processes standardized context packages and produces comprehensive technical analysis focused on solution improvements, key design decisions, and critical insights.
-
-**Analysis Focus**: Produces ANALYSIS_RESULTS.md with solution design, architectural rationale, feasibility assessment, and optimization strategies. Does NOT generate task breakdowns or implementation plans.
-
-**Independent Usage**: This command can be called directly by users or as part of the `/workflow:plan` command. It accepts context packages and provides solution-focused technical analysis.
-
-## Core Philosophy
-- **Solution-Focused**: Emphasize design decisions, architectural rationale, and critical insights
-- **Context-Driven**: Precise analysis based on comprehensive context packages
-- **Intelligent Tool Selection**: Choose optimal tools based on task complexity (Gemini for design, Codex for validation)
-- **Parallel Execution**: Execute multiple CLI tools simultaneously for efficiency
-- **No Task Planning**: Exclude implementation steps, task breakdowns, and project planning
-- **Single Output**: Generate only ANALYSIS_RESULTS.md with technical analysis
-
-## Core Responsibilities
-- **Context Package Parsing**: Read and validate context-package.json
-- **Parallel CLI Orchestration**: Execute Gemini (solution design) and optionally Codex (feasibility validation)
-- **Solution Design Analysis**: Evaluate architecture, identify key design decisions with rationale
-- **Feasibility Assessment**: Analyze technical complexity, risks, and implementation readiness
-- **Optimization Recommendations**: Propose performance, security, and code quality improvements
-- **Perspective Synthesis**: Integrate Gemini and Codex insights into unified solution assessment
-- **Technical Analysis Report**: Generate ANALYSIS_RESULTS.md focused on design decisions and critical insights (NO task planning)
-
-## Analysis Strategy Selection
-
-### Tool Selection by Task Complexity
-
-**Simple Tasks (≤3 modules)**:
-- **Primary Tool**: Gemini (rapid understanding and pattern recognition)
-- **Support Tool**: Code-index (structural analysis)
-- **Execution Mode**: Single-round analysis, focus on existing patterns
-
-**Medium Tasks (4-6 modules)**:
-- **Primary Tool**: Gemini (comprehensive single-round analysis and architecture design)
-- **Support Tools**: Code-index + Exa (external best practices)
-- **Execution Mode**: Single comprehensive analysis covering understanding + architecture design
-
-**Complex Tasks (>6 modules)**:
-- **Primary Tools**: Gemini (single comprehensive analysis) + Codex (implementation validation)
-- **Analysis Strategy**: Gemini handles understanding + architecture in one round, Codex validates implementation
-- **Execution Mode**: Parallel execution - Gemini comprehensive analysis + Codex validation
-
-### Tool Preferences by Tech Stack
-
-```json
-{
-  "frontend": {
-    "primary": "gemini",
-    "secondary": "codex",
-    "focus": ["component_design", "state_management", "ui_patterns"]
-  },
-  "backend": {
-    "primary": "codex",
-    "secondary": "gemini",
-    "focus": ["api_design", "data_flow", "security", "performance"]
-  },
-  "fullstack": {
-    "primary": "gemini",
-    "secondary": "codex",
-    "focus": ["system_architecture", "integration", "data_consistency"]
-  }
-}
-```
-
-## Execution Lifecycle
-
-### Phase 1: Validation & Preparation
-1. **Session Validation**
-   - Verify session directory exists: `.workflow/{session_id}/`
-   - Load session metadata from `workflow-session.json`
-   - Validate session state and task context
-
-2. **Context Package Validation**
-   - Verify context package exists at specified path
-   - Validate JSON format and structure
-   - Assess context package size and complexity
-
-3. **Task Analysis & Classification**
-   - Parse task description and extract keywords
-   - Identify technical domain and complexity level
-   - Determine required analysis depth and scope
-   - Load existing session context and task summaries
-
-4. **Tool Selection Strategy**
-   - **Simple/Medium Tasks**: Single Gemini comprehensive analysis
-   - **Complex Tasks**: Gemini comprehensive + Codex validation
-   - Load appropriate prompt templates and configurations
-
-### Phase 2: Analysis Preparation
-1. **Workspace Setup**
-   - Create analysis output directory: `.workflow/{session_id}/.process/`
-   - Initialize log files and monitoring structures
-   - Set process limits and resource management
-
-2. **Context Optimization**
-   - Filter high-priority assets from context package
-   - Organize project structure and dependencies
-   - Prepare template references and rule configurations
-
-3. **Execution Environment**
-   - Configure CLI tools with write permissions
-   - Set timeout parameters and monitoring intervals
-   - Prepare error handling and recovery mechanisms
-
-### Phase 3: Parallel Analysis Execution
-1. **Gemini Solution Design & Architecture Analysis**
-   - **Tool Configuration**:
-     ```bash
-     ~/.claude/scripts/gemini-wrapper -p "
-     PURPOSE: Analyze and design optimal solution for {task_description}
-     TASK: Evaluate current architecture, propose solution design, and identify key design decisions
-     CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
-
-     **MANDATORY FIRST STEP**: Read and analyze .workflow/{session_id}/.process/context-package.json to understand:
-     - Task requirements from metadata.task_description
-     - Relevant source files from assets[] array
-     - Tech stack from tech_stack section
-     - Project structure from statistics section
-
-     **ANALYSIS PRIORITY - Use ALL source documents from context-package assets[]**:
-     1. PRIMARY SOURCES (Highest Priority): Individual role analysis.md files (system-architect, ui-designer, product-manager, etc.)
-        - These contain complete technical details, design rationale, ADRs, and decision context
-        - Extract: Technical specs, API schemas, design tokens, caching configs, performance metrics
-     2. SYNTHESIS REFERENCE (Medium Priority): synthesis-specification.md
-        - Use for integrated requirements and cross-role alignment
-        - Validate decisions and identify integration points
-     3. TOPIC FRAMEWORK (Low Priority): topic-framework.md for discussion context
-
-     EXPECTED:
-     1. CURRENT STATE ANALYSIS: Existing patterns, code structure, integration points, technical debt
-     2. SOLUTION DESIGN: Core architecture principles, system design, key design decisions with rationale
-     3. CRITICAL INSIGHTS: What works well, identified gaps, technical risks, architectural tradeoffs
-     4. OPTIMIZATION STRATEGIES: Performance improvements, security enhancements, code quality recommendations
-     5. FEASIBILITY ASSESSMENT: Complexity analysis, compatibility evaluation, implementation readiness
-     6. **OUTPUT FILE**: Write complete analysis to .workflow/{session_id}/.process/gemini-solution-design.md
-
-     RULES:
-     - Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, NOT task planning
-     - Provide architectural rationale, evaluate alternatives, assess tradeoffs
-     - **CRITICAL**: Identify code targets - existing files as "file:function:lines", new files as "file"
-     - For modifications: specify exact files/functions/line ranges
-     - For new files: specify file path only (no function or lines)
-     - Do NOT create task lists, implementation steps, or code examples
-     - Do NOT generate any code snippets or implementation details
-     - **MUST write output to .workflow/{session_id}/.process/gemini-solution-design.md**
-     - Output ONLY architectural analysis and design recommendations
-     " --approval-mode yolo
-     ```
-   - **Output Location**: `.workflow/{session_id}/.process/gemini-solution-design.md`
-
-2. **Codex Technical Feasibility Validation** (Complex Tasks Only)
-   - **Tool Configuration**:
-     ```bash
-     codex --full-auto exec "
-     PURPOSE: Validate technical feasibility and identify implementation risks for {task_description}
-     TASK: Assess implementation complexity, validate technology choices, evaluate performance and security implications
-     CONTEXT: @{.workflow/{session_id}/.process/context-package.json,.workflow/{session_id}/.process/gemini-solution-design.md,.workflow/{session_id}/workflow-session.json,CLAUDE.md}
-
-     **MANDATORY FIRST STEP**: Read and analyze:
-     - .workflow/{session_id}/.process/context-package.json for task context
-     - .workflow/{session_id}/.process/gemini-solution-design.md for proposed solution design
-     - Relevant source files listed in context-package.json assets[]
-
-     EXPECTED:
-     1. FEASIBILITY ASSESSMENT: Technical complexity rating, resource requirements, technology compatibility
-     2. RISK ANALYSIS: Implementation risks, integration challenges, performance concerns, security vulnerabilities
-     3. TECHNICAL VALIDATION: Development approach validation, quality standards assessment, maintenance implications
-     4. CRITICAL RECOMMENDATIONS: Must-have requirements, optimization opportunities, security controls
-     5. **OUTPUT FILE**: Write validation results to .workflow/{session_id}/.process/codex-feasibility-validation.md
-
-     RULES:
-     - Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, NOT implementation planning
-     - Validate architectural decisions, identify potential issues, recommend optimizations
-     - **CRITICAL**: Verify code targets - existing files "file:function:lines", new files "file"
-     - Confirm exact locations for modifications, identify additional new files if needed
-     - Do NOT create task breakdowns, step-by-step guides, or code examples
-     - Do NOT generate any code snippets or implementation details
-     - **MUST write output to .workflow/{session_id}/.process/codex-feasibility-validation.md**
-     - Output ONLY feasibility analysis and risk assessment
-     " --skip-git-repo-check -s danger-full-access
-     ```
-   - **Output Location**: `.workflow/{session_id}/.process/codex-feasibility-validation.md`
-
-3. **Parallel Execution Management**
-   - Launch both tools simultaneously for complex tasks
-   - Monitor execution progress with timeout controls
-   - Handle process completion and error scenarios
-   - Maintain execution logs for debugging and recovery
-
-### Phase 4: Results Collection & Synthesis
-1. **Output Validation & Collection**
-   - **Gemini Results**: Validate `gemini-solution-design.md` contains complete solution analysis
-   - **Codex Results**: For complex tasks, validate `codex-feasibility-validation.md` with technical assessment
-   - **Fallback Processing**: Use execution logs if primary outputs are incomplete
-   - **Status Classification**: Mark each tool as completed, partial, failed, or skipped
-
-2. **Quality Assessment**
-   - **Design Quality**: Verify architectural decisions have clear rationale and alternatives analysis
-   - **Insight Depth**: Assess quality of critical insights and risk identification
-   - **Feasibility Rigor**: Validate completeness of technical feasibility assessment
-   - **Optimization Value**: Check actionability of optimization recommendations
-
-3. **Analysis Synthesis Strategy**
-   - **Simple/Medium Tasks**: Direct integration of Gemini solution design
-   - **Complex Tasks**: Synthesis of Gemini design with Codex feasibility validation
-   - **Conflict Resolution**: Identify architectural disagreements and provide balanced resolution
-   - **Confidence Scoring**: Assess overall solution confidence based on multi-tool consensus
-
-### Phase 5: ANALYSIS_RESULTS.md Generation
-1. **Structured Report Assembly**
-   - **Executive Summary**: Analysis focus, overall assessment, recommendation status
-   - **Current State Analysis**: Architecture overview, compatibility, critical findings
-   - **Proposed Solution Design**: Core principles, system design, key design decisions with rationale
-   - **Implementation Strategy**: Development approach, feasibility assessment, risk mitigation
-   - **Solution Optimization**: Performance, security, code quality recommendations
-   - **Critical Success Factors**: Technical requirements, quality metrics, success validation
-   - **Confidence & Recommendations**: Assessment scores, final recommendation with rationale
-
-2. **Report Generation Guidelines**
-   - **Focus**: Solution improvements, key design decisions, critical insights
-   - **Exclude**: Task breakdowns, implementation steps, project planning
-   - **Emphasize**: Architectural rationale, tradeoff analysis, risk assessment
-   - **Structure**: Clear sections with decision justification and feasibility scoring
-
-3. **Final Output**
-   - **Primary Output**: `ANALYSIS_RESULTS.md` - comprehensive solution design and technical analysis
-   - **Single File Policy**: Only generate ANALYSIS_RESULTS.md, no supplementary files
-   - **Report Location**: `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
-   - **Content Focus**: Technical insights, design decisions, optimization strategies
-
-## Analysis Results Format
-
-Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design decisions, and critical insights** (NOT task planning):
-
-```markdown
-# Technical Analysis & Solution Design
-
-## Executive Summary
-- **Analysis Focus**: {core_problem_or_improvement_area}
-- **Analysis Timestamp**: {timestamp}
-- **Tools Used**: {analysis_tools}
-- **Overall Assessment**: {feasibility_score}/5 - {recommendation_status}
-
----
-
-## 1. Current State Analysis
-
-### Architecture Overview
-- **Existing Patterns**: {key_architectural_patterns}
-- **Code Structure**: {current_codebase_organization}
-- **Integration Points**: {system_integration_touchpoints}
-- **Technical Debt Areas**: {identified_debt_with_impact}
-
-### Compatibility & Dependencies
-- **Framework Alignment**: {framework_compatibility_assessment}
-- **Dependency Analysis**: {critical_dependencies_and_risks}
-- **Migration Considerations**: {backward_compatibility_concerns}
-
-### Critical Findings
-- **Strengths**: {what_works_well}
-- **Gaps**: {missing_capabilities_or_issues}
-- **Risks**: {identified_technical_and_business_risks}
-
----
-
-## 2. Proposed Solution Design
-
-### Core Architecture Principles
-- **Design Philosophy**: {key_design_principles}
-- **Architectural Approach**: {chosen_architectural_pattern_with_rationale}
-- **Scalability Strategy**: {how_solution_scales}
-
-### System Design
-- **Component Architecture**: {high_level_component_design}
-- **Data Flow**: {data_flow_patterns_and_state_management}
-- **API Design**: {interface_contracts_and_specifications}
-- **Integration Strategy**: {how_components_integrate}
-
-### Key Design Decisions
-1. **Decision**: {critical_design_choice}
-   - **Rationale**: {why_this_approach}
-   - **Alternatives Considered**: {other_options_and_tradeoffs}
-   - **Impact**: {implications_on_architecture}
-
-2. **Decision**: {another_critical_choice}
-   - **Rationale**: {reasoning}
-   - **Alternatives Considered**: {tradeoffs}
-   - **Impact**: {consequences}
-
-### Technical Specifications
-- **Technology Stack**: {chosen_technologies_with_justification}
-- **Code Organization**: {module_structure_and_patterns}
-- **Testing Strategy**: {testing_approach_and_coverage}
-- **Performance Targets**: {performance_requirements_and_benchmarks}
-
----
-
-## 3. Implementation Strategy
-
-### Development Approach
-- **Core Implementation Pattern**: {primary_implementation_strategy}
-- **Module Dependencies**: {dependency_graph_and_order}
-- **Quality Assurance**: {qa_approach_and_validation}
-
-### Code Modification Targets
-**Purpose**: Specific code locations for modification AND new files to create
-
-**Format**:
-- Existing files: `file:function:lines` (with line numbers)
-- New files: `file` (no function or lines)
-
-**Identified Targets**:
-1. **Target**: `src/auth/AuthService.ts:login:45-52`
-   - **Type**: Modify existing
-   - **Modification**: Enhance error handling
-   - **Rationale**: Current logic lacks validation for edge cases
-
-2. **Target**: `src/auth/PasswordReset.ts`
-   - **Type**: Create new file
-   - **Purpose**: Password reset functionality
-   - **Rationale**: New feature requirement
-
-3. **Target**: `src/middleware/auth.ts:validateToken:30-45`
-   - **Type**: Modify existing
-   - **Modification**: Add token expiry check
-   - **Rationale**: Security requirement for JWT validation
-
-4. **Target**: `tests/auth/PasswordReset.test.ts`
-   - **Type**: Create new file
-   - **Purpose**: Test coverage for password reset
-   - **Rationale**: Test requirement for new feature
-
-**Note**:
-- For new files, only specify the file path (no function or lines)
-- For existing files without line numbers, use `file:function:*` format
-- Task generation will refine these during the `analyze_task_patterns` step
-
-### Feasibility Assessment
-- **Technical Complexity**: {complexity_rating_and_analysis}
-- **Performance Impact**: {expected_performance_characteristics}
-- **Resource Requirements**: {development_resources_needed}
-- **Maintenance Burden**: {ongoing_maintenance_considerations}
-
-### Risk Mitigation
-- **Technical Risks**: {implementation_risks_and_mitigation}
-- **Integration Risks**: {compatibility_challenges_and_solutions}
-- **Performance Risks**: {performance_concerns_and_strategies}
-- **Security Risks**: {security_vulnerabilities_and_controls}
-
----
-
-## 4. Solution Optimization
-
-### Performance Optimization
-- **Optimization Strategies**: {key_performance_improvements}
-- **Caching Strategy**: {caching_approach_and_invalidation}
-- **Resource Management**: {resource_utilization_optimization}
-- **Bottleneck Mitigation**: {identified_bottlenecks_and_solutions}
-
-### Security Enhancements
-- **Security Model**: {authentication_authorization_approach}
-- **Data Protection**: {data_security_and_encryption}
-- **Vulnerability Mitigation**: {known_vulnerabilities_and_controls}
-- **Compliance**: {regulatory_and_compliance_considerations}
-
-### Code Quality
-- **Code Standards**: {coding_conventions_and_patterns}
-- **Testing Coverage**: {test_strategy_and_coverage_goals}
-- **Documentation**: {documentation_requirements}
-- **Maintainability**: {maintainability_practices}
-
----
-
-## 5. Critical Success Factors
-
-### Technical Requirements
-- **Must Have**: {essential_technical_capabilities}
-- **Should Have**: {important_but_not_critical_features}
-- **Nice to Have**: {optional_enhancements}
-
-### Quality Metrics
-- **Performance Benchmarks**: {measurable_performance_targets}
-- **Code Quality Standards**: {quality_metrics_and_thresholds}
-- **Test Coverage Goals**: {testing_coverage_requirements}
-- **Security Standards**: {security_compliance_requirements}
-
-### Success Validation
-- **Acceptance Criteria**: {how_to_validate_success}
-- **Testing Strategy**: {validation_testing_approach}
-- **Monitoring Plan**: {production_monitoring_strategy}
-- **Rollback Plan**: {failure_recovery_strategy}
-
----
-
-## 6. Analysis Confidence & Recommendations
-
-### Assessment Scores
-- **Conceptual Integrity**: {score}/5 - {brief_assessment}
-- **Architectural Soundness**: {score}/5 - {brief_assessment}
-- **Technical Feasibility**: {score}/5 - {brief_assessment}
-- **Implementation Readiness**: {score}/5 - {brief_assessment}
-- **Overall Confidence**: {overall_score}/5
-
-### Final Recommendation
-**Status**: {PROCEED|PROCEED_WITH_MODIFICATIONS|RECONSIDER|REJECT}
-
-**Rationale**: {clear_explanation_of_recommendation}
-
-**Critical Prerequisites**: {what_must_be_resolved_before_proceeding}
-
----
-
-## 7. Reference Information
-
-### Tool Analysis Summary
-- **Gemini Insights**: {key_architectural_and_pattern_insights}
-- **Codex Validation**: {technical_feasibility_and_implementation_notes}
-- **Consensus Points**: {agreements_between_tools}
-- **Conflicting Views**: {disagreements_and_resolution}
-
-### Context & Resources
-- **Analysis Context**: {context_package_reference}
-- **Documentation References**: {relevant_documentation}
-- **Related Patterns**: {similar_implementations_in_codebase}
-- **External Resources**: {external_references_and_best_practices}
-```
-
-## Error Handling & Fallbacks
-
-### Error Handling & Recovery Strategies
-
-1. **Pre-execution Validation**
-   - **Session Verification**: Ensure session directory and metadata exist
-   - **Context Package Validation**: Verify JSON format and content structure
-   - **Tool Availability**: Confirm CLI tools are accessible and configured
-   - **Prerequisite Checks**: Validate all required dependencies and permissions
-
-2. **Execution Monitoring & Timeout Management**
-   - **Progress Monitoring**: Track analysis execution with regular status checks
-   - **Timeout Controls**: 30-minute execution limit with graceful termination
-   - **Process Management**: Handle parallel tool execution and resource limits
-   - **Status Tracking**: Maintain real-time execution state and completion status
-
-3. **Partial Results Recovery**
-   - **Fallback Strategy**: Generate analysis results even with incomplete outputs
-   - **Log Integration**: Use execution logs when primary outputs are unavailable
-   - **Recovery Mode**: Create partial analysis reports with available data
-   - **Guidance Generation**: Provide next steps and retry recommendations
-
-4. **Resource Management**
-   - **Disk Space Monitoring**: Check available storage and cleanup temporary files
-   - **Process Limits**: Set CPU and memory constraints for analysis execution
-   - **Performance Optimization**: Manage resource utilization and system load
-   - **Cleanup Procedures**: Remove outdated logs and temporary files
-
-5. **Comprehensive Error Recovery**
-   - **Error Detection**: Automatic error identification and classification
-   - **Recovery Workflows**: Structured approach to handling different failure modes
-   - **Status Reporting**: Clear communication of issues and resolution attempts
-   - **Graceful Degradation**: Provide useful outputs even with partial failures
-
-## Performance Optimization
-
-### Analysis Optimization Strategies
-- **Parallel Analysis**: Execute multiple tools in parallel to reduce total time
-- **Context Sharding**: Analyze large projects by module shards
-- **Caching Mechanism**: Reuse analysis results for similar contexts
-- **Incremental Analysis**: Perform incremental analysis based on changes
-
-### Resource Management
-```bash
-# Set analysis timeout
-timeout 600s analysis_command || {
-  echo "⚠️ Analysis timeout, generating partial results"
-  # Generate partial results
-}
-
-# Memory usage monitoring
-memory_usage=$(ps -o pid,vsz,rss,comm -p $$)
-if [ "$memory_usage" -gt "$memory_limit" ]; then
-  echo "⚠️ High memory usage detected, optimizing..."
-fi
-```
-
-## Integration Points
-
-### Input Interface
-- **Required**: `--session` parameter specifying session ID (e.g., WFS-auth)
-- **Required**: `--context` parameter specifying context package path
-- **Optional**: `--depth` specify analysis depth (quick|full|deep)
-- **Optional**: `--focus` specify analysis focus areas
-
-### Output Interface
-- **Primary**: ANALYSIS_RESULTS.md - solution design and technical analysis
-- **Location**: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
-- **Single Output Policy**: Only ANALYSIS_RESULTS.md is generated
-- **No Supplementary Files**: No additional JSON, roadmap, or template files
-
-## Quality Assurance
-
-### Analysis Quality Checks
-- **Completeness Check**: Ensure all required analysis sections are completed
-- **Consistency Check**: Verify consistency of multi-tool analysis results
-- **Feasibility Validation**: Ensure recommended implementation plans are feasible
-
-### Success Criteria
-- ✅ **Solution-Focused Analysis**: ANALYSIS_RESULTS.md emphasizes solution improvements, design decisions, and critical insights
-- ✅ **Single Output File**: Only ANALYSIS_RESULTS.md generated, no supplementary files
-- ✅ **Design Decision Depth**: Clear rationale for architectural choices with alternatives and tradeoffs
-- ✅ **Feasibility Assessment**: Technical complexity, risk analysis, and implementation readiness evaluation
-- ✅ **Optimization Strategies**: Performance, security, and code quality recommendations
-- ✅ **Parallel Execution**: Efficient concurrent tool execution (Gemini + Codex for complex tasks)
-- ✅ **Robust Error Handling**: Comprehensive validation, timeout management, and partial result recovery
-- ✅ **Confidence Scoring**: Multi-dimensional assessment with clear recommendation status
-- ✅ **No Task Planning**: Exclude task breakdowns, implementation steps, and project planning details
-
-## Related Commands
-- `/context:gather` - Generate context packages required by this command
-- `/workflow:plan` - Call this command for analysis
-- `/task:create` - Create specific tasks based on analysis results

.claude/commands/workflow/tools/conflict-resolution.md

@@ -0,0 +1,471 @@
+---
+name: conflict-resolution
+description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis
+argument-hint: "--session WFS-session-id --context path/to/context-package.json"
+examples:
+  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
+---
+
+# Conflict Resolution Command
+
+## Purpose
+Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
+
+**Scope**: Detection and strategy generation only - NO code modification or task creation.
+
+**Trigger**: Auto-executes in `/workflow:plan` Phase 3 when `conflict_risk ≥ medium`.
+
+## Core Responsibilities
+
+| Responsibility | Description |
+|---------------|-------------|
+| **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
+| **Generate Strategies** | Provide 2-4 resolution options per conflict |
+| **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
+| **User Decision** | Present options, never auto-apply |
+| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
+
+## Conflict Categories
+
+### 1. Architecture Conflicts
+- Incompatible design patterns
+- Module structure changes
+- Pattern migration requirements
+
+### 2. API Conflicts
+- Breaking contract changes
+- Signature modifications
+- Public interface impacts
+
+### 3. Data Model Conflicts
+- Schema modifications
+- Type breaking changes
+- Data migration needs
+
+### 4. Dependency Conflicts
+- Version incompatibilities
+- Setup conflicts
+- Breaking updates
+
+## Execution Flow
+
+### Phase 1: Validation
+```
+1. Verify session directory exists
+2. Load context-package.json
+3. Check conflict_risk (skip if none/low)
+4. Prepare agent task prompt
+```
+
+### Phase 2: CLI-Powered Analysis
+
+**Agent Delegation**:
+```javascript
+Task(subagent_type="cli-execution-agent", prompt=`
+  ## Context
+  - Session: {session_id}
+  - Risk: {conflict_risk}
+  - Files: {existing_files_list}
+
+  ## Analysis Steps
+
+  ### 1. Load Context
+  - Read existing files from conflict_detection.existing_files
+  - Load plan from .workflow/{session_id}/.process/context-package.json
+  - Extract role analyses and requirements
+
+  ### 2. Execute CLI Analysis
+
+  Primary (Gemini):
+  cd {project_root} && gemini -p "
+  PURPOSE: Detect conflicts between plan and codebase
+  TASK:
+  • Compare architectures
+  • Identify breaking API changes
+  • Detect data model incompatibilities
+  • Assess dependency conflicts
+  MODE: analysis
+  CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
+  EXPECTED: Conflict list with severity ratings
+  RULES: Focus on breaking changes and migration needs
+  "
+
+  Fallback: Qwen (same prompt) → Claude (manual analysis)
+
+  ### 3. Generate Strategies (2-4 per conflict)
+
+  Template per conflict:
+  - Severity: Critical/High/Medium
+  - Category: Architecture/API/Data/Dependency
+  - Affected files + impact
+  - Options with pros/cons, effort, risk
+  - Recommended strategy + rationale
+
+  ### 4. Return Structured Conflict Data
+
+  ⚠️ DO NOT generate CONFLICT_RESOLUTION.md file
+
+  Return JSON format for programmatic processing:
+
+  \`\`\`json
+  {
+    "conflicts": [
+      {
+        "id": "CON-001",
+        "brief": "一行中文冲突摘要",
+        "severity": "Critical|High|Medium",
+        "category": "Architecture|API|Data|Dependency",
+        "affected_files": [
+          ".workflow/{session}/.brainstorm/guidance-specification.md",
+          ".workflow/{session}/.brainstorm/system-architect/analysis.md"
+        ],
+        "description": "详细描述冲突 - 什么不兼容",
+        "impact": {
+          "scope": "影响的模块/组件",
+          "compatibility": "Yes|No|Partial",
+          "migration_required": true|false,
+          "estimated_effort": "人天估计"
+        },
+        "strategies": [
+          {
+            "name": "策略名称（中文）",
+            "approach": "实现方法简述",
+            "complexity": "Low|Medium|High",
+            "risk": "Low|Medium|High",
+            "effort": "时间估计",
+            "pros": ["优点1", "优点2"],
+            "cons": ["缺点1", "缺点2"],
+            "modifications": [
+              {
+                "file": ".workflow/{session}/.brainstorm/guidance-specification.md",
+                "section": "## 2. System Architect Decisions",
+                "change_type": "update",
+                "old_content": "原始内容片段（用于定位）",
+                "new_content": "修改后的内容",
+                "rationale": "为什么这样改"
+              },
+              {
+                "file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
+                "section": "## Design Decisions",
+                "change_type": "update",
+                "old_content": "原始内容片段",
+                "new_content": "修改后的内容",
+                "rationale": "修改理由"
+              }
+            ]
+          },
+          {
+            "name": "策略2名称",
+            "approach": "...",
+            "complexity": "Medium",
+            "risk": "Low",
+            "effort": "1-2天",
+            "pros": ["优点"],
+            "cons": ["缺点"],
+            "modifications": [...]
+          }
+        ],
+        "recommended": 0,
+        "modification_suggestions": [
+          "建议1：具体的修改方向或注意事项",
+          "建议2：可能需要考虑的边界情况",
+          "建议3：相关的最佳实践或模式"
+        ]
+      }
+    ],
+    "summary": {
+      "total": 2,
+      "critical": 1,
+      "high": 1,
+      "medium": 0
+    }
+  }
+  \`\`\`
+
+  ⚠️ CRITICAL Requirements for modifications field:
+  - old_content: Must be exact text from target file (20-100 chars for unique match)
+  - new_content: Complete replacement text (maintains formatting)
+  - change_type: "update" (replace), "add" (insert), "remove" (delete)
+  - file: Full path relative to project root
+  - section: Markdown heading for context (helps locate position)
+  - Minimum 2 strategies per conflict, max 4
+  - All text in Chinese for user-facing fields (brief, name, pros, cons)
+  - modification_suggestions: 2-5 actionable suggestions for custom handling (Chinese)
+
+  Quality Standards:
+  - Each strategy must have actionable modifications
+  - old_content must be precise enough for Edit tool matching
+  - new_content preserves markdown formatting and structure
+  - Recommended strategy (index) based on lowest complexity + risk
+  - modification_suggestions must be specific, actionable, and context-aware
+  - Each suggestion should address a specific aspect (compatibility, migration, testing, etc.)
+`)
+```
+
+**Agent Internal Flow**:
+```
+1. Load context package
+2. Check conflict_risk (exit if none/low)
+3. Read existing files + plan artifacts
+4. Run CLI analysis (Gemini→Qwen→Claude)
+5. Parse conflict findings
+6. Generate 2-4 strategies per conflict with modifications
+7. Return JSON to stdout (NOT file write)
+8. Return execution log path
+```
+
+### Phase 3: User Confirmation via Text Interaction
+
+**Command parses agent JSON output and presents conflicts to user via text**:
+
+```javascript
+// 1. Parse agent JSON output
+const conflictData = JSON.parse(agentOutput);
+const conflicts = conflictData.conflicts; // No 4-conflict limit
+
+// 2. Format conflicts as text output (max 10 per round)
+const batchSize = 10;
+const batches = chunkArray(conflicts, batchSize);
+
+for (const [batchIdx, batch] of batches.entries()) {
+  const totalBatches = batches.length;
+
+  // Output batch header
+  console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
+
+  // Output each conflict in batch
+  batch.forEach((conflict, idx) => {
+    const questionNum = batchIdx * batchSize + idx + 1;
+    console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
+
+    conflict.strategies.forEach((strategy, sIdx) => {
+      const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
+      console.log(`${optionLetter}) ${strategy.name}`);
+      console.log(`   说明：${strategy.approach}`);
+      console.log(`   复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
+    });
+
+    // Add custom option
+    const customLetter = String.fromCharCode(97 + conflict.strategies.length);
+    console.log(`${customLetter}) 自定义修改`);
+    console.log(`   说明：根据修改建议自行处理，不应用预设策略`);
+
+    // Show modification suggestions
+    if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
+      console.log(`   修改建议：`);
+      conflict.modification_suggestions.forEach(suggestion => {
+        console.log(`   - ${suggestion}`);
+      });
+    }
+    console.log();
+  });
+
+  console.log(`请回答 (格式: 1a 2b 3c...)：`);
+
+  // Wait for user input
+  const userInput = await readUserInput();
+
+  // Parse answers
+  const answers = parseUserAnswers(userInput, batch);
+}
+
+// 3. Build selected strategies (exclude custom selections)
+const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
+const customConflicts = answers.filter(a => a.isCustom).map(a => ({
+  id: a.conflict.id,
+  brief: a.conflict.brief,
+  suggestions: a.conflict.modification_suggestions
+}));
+```
+
+**Text Output Example**:
+```markdown
+===== 冲突解决 (第 1/1 轮) =====
+
+【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
+a) 渐进式迁移
+   说明：保留现有系统，逐步迁移到新方案
+   复杂度: Medium | 风险: Low | 工作量: 3-5天
+b) 完全重写
+   说明：废弃旧系统，从零实现新认证
+   复杂度: High | 风险: Medium | 工作量: 7-10天
+c) 自定义修改
+   说明：根据修改建议自行处理，不应用预设策略
+   修改建议：
+   - 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
+   - 检查JWT token格式和验证逻辑是否需要调整
+   - 确保用户会话管理与新架构保持一致
+
+【问题2 - Data】CON-002: 数据库 schema 冲突
+a) 添加迁移脚本
+   说明：创建数据库迁移脚本处理 schema 变更
+   复杂度: Low | 风险: Low | 工作量: 1-2天
+b) 自定义修改
+   说明：根据修改建议自行处理，不应用预设策略
+   修改建议：
+   - 检查现有表结构是否支持新增字段，避免破坏性变更
+   - 考虑使用数据库版本控制工具（如Flyway或Liquibase）
+   - 准备数据迁移和回滚策略
+
+请回答 (格式: 1a 2b)：
+```
+
+**User Input Examples**:
+- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
+- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
+- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
+
+### Phase 4: Apply Modifications
+
+```javascript
+// 1. Extract modifications from selected strategies
+const modifications = [];
+selectedStrategies.forEach(strategy => {
+  if (strategy !== "skip") {
+    modifications.push(...strategy.modifications);
+  }
+});
+
+// 2. Apply each modification using Edit tool
+modifications.forEach(mod => {
+  if (mod.change_type === "update") {
+    Edit({
+      file_path: mod.file,
+      old_string: mod.old_content,
+      new_string: mod.new_content
+    });
+  }
+  // Handle "add" and "remove" similarly
+});
+
+// 3. Update context-package.json
+const contextPackage = JSON.parse(Read(contextPath));
+contextPackage.conflict_detection.conflict_risk = "resolved";
+contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
+contextPackage.conflict_detection.resolved_at = new Date().toISOString();
+Write(contextPath, JSON.stringify(contextPackage, null, 2));
+
+// 4. Output custom conflict summary (if any)
+if (customConflicts.length > 0) {
+  console.log("\n===== 需要自定义处理的冲突 =====\n");
+  customConflicts.forEach(conflict => {
+    console.log(`【${conflict.id}】${conflict.brief}`);
+    console.log("修改建议：");
+    conflict.suggestions.forEach(suggestion => {
+      console.log(`  - ${suggestion}`);
+    });
+    console.log();
+  });
+}
+
+// 5. Return summary
+return {
+  resolved: modifications.length,
+  custom: customConflicts.length,
+  modified_files: [...new Set(modifications.map(m => m.file))],
+  custom_conflicts: customConflicts
+};
+```
+
+**Validation**:
+```
+✓ Agent returns valid JSON structure
+✓ Text output displays all conflicts (max 10 per round)
+✓ User selections captured correctly
+✓ Edit tool successfully applies modifications
+✓ guidance-specification.md updated
+✓ Role analyses (*.md) updated
+✓ context-package.json marked as resolved
+✓ Agent log saved to .workflow/{session_id}/.chat/
+```
+
+## Output Format: Agent JSON Response
+
+**Focus**: Structured conflict data with actionable modifications for programmatic processing.
+
+**Format**: JSON to stdout (NO file generation)
+
+**Structure**: Defined in Phase 2, Step 4 (agent prompt)
+
+### Key Requirements
+| Requirement | Details |
+|------------|---------|
+| **Conflict batching** | Max 10 conflicts per round (no total limit) |
+| **Strategy count** | 2-4 strategies per conflict |
+| **Modifications** | Each strategy includes file paths, old_content, new_content |
+| **User-facing text** | Chinese (brief, strategy names, pros/cons) |
+| **Technical fields** | English (severity, category, complexity, risk) |
+| **old_content precision** | 20-100 chars for unique Edit tool matching |
+| **File targets** | guidance-specification.md, role analyses (*.md) |
+
+## Error Handling
+
+### Recovery Strategy
+```
+1. Pre-check: Verify conflict_risk ≥ medium
+2. Monitor: Track agent via Task tool
+3. Validate: Parse agent JSON output
+4. Recover:
+   - Agent failure → check logs + report error
+   - Invalid JSON → retry once with Claude fallback
+   - CLI failure → fallback to Claude analysis
+   - Edit tool failure → report affected files + rollback option
+   - User cancels → mark as "unresolved", continue to task-generate
+5. Degrade: If all fail, generate minimal conflict report and skip modifications
+```
+
+### Rollback Handling
+```
+If Edit tool fails mid-application:
+1. Log all successfully applied modifications
+2. Output rollback option via text interaction
+3. If rollback selected: restore files from git or backups
+4. If continue: mark partial resolution in context-package.json
+```
+
+## Integration
+
+### Interface
+**Input**:
+- `--session` (required): WFS-{session-id}
+- `--context` (required): context-package.json path
+- Requires: `conflict_risk ≥ medium`
+
+**Output**:
+- Modified files:
+  - `.workflow/{session_id}/.brainstorm/guidance-specification.md`
+  - `.workflow/{session_id}/.brainstorm/{role}/analysis.md`
+  - `.workflow/{session_id}/.process/context-package.json` (conflict_risk → resolved)
+- NO report file generation
+
+**User Interaction**:
+- Text-based strategy selection (max 10 conflicts per round)
+- Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
+
+### Success Criteria
+```
+✓ CLI analysis returns valid JSON structure
+✓ Conflicts presented in batches (max 10 per round)
+✓ Min 2 strategies per conflict with modifications
+✓ Each conflict includes 2-5 modification_suggestions
+✓ Text output displays all conflicts correctly with suggestions
+✓ User selections captured and processed
+✓ Edit tool applies modifications successfully
+✓ Custom conflicts displayed with suggestions for manual handling
+✓ guidance-specification.md updated with resolved conflicts
+✓ Role analyses (*.md) updated with resolved conflicts
+✓ context-package.json marked as "resolved"
+✓ No CONFLICT_RESOLUTION.md file generated
+✓ Modification summary includes custom conflict count
+✓ Agent log saved to .workflow/{session_id}/.chat/
+✓ Error handling robust (validate/retry/degrade)
+```
+
+## Related Commands
+| Command | Relationship |
+|---------|--------------|
+| `/workflow:tools:context-gather` | Generates input conflict_detection data |
+| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
+| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
+| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

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

@@ -1,301 +1,282 @@
 ---
 name: gather
-description: Intelligently collect project context based on task description and package into standardized JSON
-usage: /workflow:tools:context-gather --session <session_id> "<task_description>"
+description: Intelligently collect project context using context-search-agent based on task description and package into standardized JSON
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
   - /workflow:tools:context-gather --session WFS-payment "Refactor payment module API"
   - /workflow:tools:context-gather --session WFS-bugfix "Fix login validation error"
+allowed-tools: Task(*), Read(*), Glob(*)
 ---
 
 # Context Gather Command (/workflow:tools:context-gather)
 
 ## Overview
-Intelligent context collector that gathers relevant information from project codebase, documentation, and dependencies based on task descriptions, generating standardized context packages.
+
+Orchestrator command that invokes `context-search-agent` to gather comprehensive project context for implementation planning. Generates standardized `context-package.json` with codebase analysis, dependencies, and conflict detection.
+
+**Agent**: `context-search-agent` (`.claude/agents/context-search-agent.md`)
 
 ## Core Philosophy
-- **Intelligent Collection**: Auto-identify relevant resources based on keyword analysis
-- **Comprehensive Coverage**: Collect code, documentation, configurations, and dependencies
-- **Standardized Output**: Generate unified format context-package.json
-- **Efficient Execution**: Optimize collection strategies to avoid irrelevant information
 
-## Core Responsibilities
-- **Keyword Extraction**: Extract core keywords from task descriptions
-- **Smart Documentation Loading**: Load relevant project documentation based on keywords
-- **Code Structure Analysis**: Analyze project structure to locate relevant code files
-- **Dependency Discovery**: Identify tech stack and dependency relationships
-- **MCP Tools Integration**: Leverage code-index tools for enhanced collection
-- **Context Packaging**: Generate standardized JSON context packages
+- **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
+- **Detection-First**: Check for existing context-package before executing
+- **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
+- **Standardized Output**: Generate `.workflow/{session}/.process/context-package.json`
 
-## Execution Process
+## Execution Flow
 
-### Phase 1: Task Analysis
-1. **Keyword Extraction**
-   - Parse task description to extract core keywords
-   - Identify technical domain (auth, API, frontend, backend, etc.)
-   - Determine complexity level (simple, medium, complex)
+### Step 1: Context-Package Detection
 
-2. **Scope Determination**
-   - Define collection scope based on keywords
-   - Identify potentially involved modules and components
-   - Set file type filters
+**Execute First** - Check if valid package already exists:
 
-### Phase 2: Project Structure Exploration
-1. **Architecture Analysis**
-   - Use `~/.claude/scripts/get_modules_by_depth.sh` for comprehensive project structure
-   - Analyze project layout and module organization
-   - Identify key directories and components
+```javascript
+const contextPackagePath = `.workflow/${session_id}/.process/context-package.json`;
 
-2. **Code File Location**
-   - Use MCP tools for precise search: `mcp__code-index__find_files()` and `mcp__code-index__search_code_advanced()`
-   - Search for relevant source code files based on keywords
-   - Locate implementation files, interfaces, and modules
+if (file_exists(contextPackagePath)) {
+  const existing = Read(contextPackagePath);
 
-3. **Documentation Collection**
-   - Load CLAUDE.md and README.md
-   - Load relevant documentation from .workflow/docs/ based on keywords
-   - Collect configuration files (package.json, requirements.txt, etc.)
-
-### Phase 3: Intelligent Filtering & Association
-1. **Relevance Scoring**
-   - Score based on keyword match degree
-   - Score based on file path relevance
-   - Score based on code content relevance
-
-2. **Dependency Analysis**
-   - Analyze import/require statements
-   - Identify inter-module dependencies
-   - Determine core and optional dependencies
-
-### Phase 4: Context Packaging
-1. **Standardized Output**
-   - Generate context-package.json
-   - Organize resources by type and importance
-   - Add relevance descriptions and usage recommendations
-
-## Context Package Format
-
-Generated context package format:
-
-```json
-{
-  "metadata": {
-    "task_description": "Implement user authentication system",
-    "timestamp": "2025-09-29T10:30:00Z",
-    "keywords": ["user", "authentication", "JWT", "login"],
-    "complexity": "medium",
-    "tech_stack": ["typescript", "node.js", "express"],
-    "session_id": "WFS-user-auth"
-  },
-  "assets": [
-    {
-      "type": "documentation",
-      "path": "CLAUDE.md",
-      "relevance": "Project development standards and conventions",
-      "priority": "high"
-    },
-    {
-      "type": "documentation",
-      "path": ".workflow/docs/architecture/security.md",
-      "relevance": "Security architecture design guidance",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/auth/AuthService.ts",
-      "relevance": "Existing authentication service implementation",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/models/User.ts",
-      "relevance": "User data model definition",
-      "priority": "medium"
-    },
-    {
-      "type": "config",
-      "path": "package.json",
-      "relevance": "Project dependencies and tech stack",
-      "priority": "medium"
-    },
-    {
-      "type": "test",
-      "path": "tests/auth/*.test.ts",
-      "relevance": "Authentication related test cases",
-      "priority": "medium"
-    }
-  ],
-  "tech_stack": {
-    "frameworks": ["express", "typescript"],
-    "libraries": ["jsonwebtoken", "bcrypt"],
-    "testing": ["jest", "supertest"]
-  },
-  "statistics": {
-    "total_files": 15,
-    "source_files": 8,
-    "docs_files": 4,
-    "config_files": 2,
-    "test_files": 1
+  // Validate package belongs to current session
+  if (existing?.metadata?.session_id === session_id) {
+    console.log("✅ Valid context-package found for session:", session_id);
+    console.log("📊 Stats:", existing.statistics);
+    console.log("⚠️  Conflict Risk:", existing.conflict_detection.risk_level);
+    return existing; // Skip execution, return existing
+  } else {
+    console.warn("⚠️ Invalid session_id in existing package, re-generating...");
   }
 }
 ```
 
-## MCP Tools Integration
+### Step 2: Invoke Context-Search Agent
 
-### Code Index Integration
-```bash
-# Set project path
-mcp__code-index__set_project_path(path="{current_project_path}")
+**Only execute if Step 1 finds no valid package**
 
-# Refresh index to ensure latest
-mcp__code-index__refresh_index()
+```javascript
+Task(
+  subagent_type="context-search-agent",
+  description="Gather comprehensive context for plan",
+  prompt=`
+You are executing as context-search-agent (.claude/agents/context-search-agent.md).
 
-# Search relevant files
-mcp__code-index__find_files(pattern="*{keyword}*")
+## Execution Mode
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
 
-# Search code content
-mcp__code-index__search_code_advanced(
-  pattern="{keyword_patterns}",
-  file_pattern="*.{ts,js,py,go,md}",
-  context_lines=3
+## Session Information
+- **Session ID**: ${session_id}
+- **Task Description**: ${task_description}
+- **Output Path**: .workflow/${session_id}/.process/context-package.json
+
+## Mission
+Execute complete context-search-agent workflow for implementation planning:
+
+### Phase 1: Initialization & Pre-Analysis
+1. **Detection**: Check for existing context-package (early exit if valid)
+2. **Foundation**: Initialize code-index, get project structure, load docs
+3. **Analysis**: Extract keywords, determine scope, classify complexity
+
+### Phase 2: Multi-Source Context Discovery
+Execute all 4 discovery tracks:
+- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
+- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+
+### Phase 3: Synthesis, Assessment & Packaging
+1. Apply relevance scoring and build dependency graph
+2. Synthesize 4-source data (archive > docs > code > web)
+3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+4. Perform conflict detection with risk assessment
+5. **Inject historical conflicts** from archive analysis into conflict_detection
+6. Generate and validate context-package.json
+
+## Output Requirements
+Complete context-package.json with:
+- **metadata**: task_description, keywords, complexity, tech_stack, session_id
+- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
+- **dependencies**: {internal[], external[]} with dependency graph
+- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] File relevance accuracy >80%
+- [ ] Dependency graph complete (max 2 transitive levels)
+- [ ] Conflict risk level calculated correctly
+- [ ] No sensitive data exposed
+- [ ] Total files ≤50 (prioritize high-relevance)
+
+Execute autonomously following agent documentation.
+Report completion with statistics.
+`
 )
 ```
 
+### Step 3: Output Verification
 
-## Session ID Integration
+After agent completes, verify output:
 
-### Session ID Usage
-- **Required Parameter**: `--session WFS-session-id`
-- **Session Context Loading**: Load existing session state and task summaries
-- **Session Continuity**: Maintain context across pipeline phases
+```javascript
+// Verify file was created
+const outputPath = `.workflow/${session_id}/.process/context-package.json`;
+if (!file_exists(outputPath)) {
+  throw new Error("❌ Agent failed to generate context-package.json");
+}
+```
 
-### Session State Management
+## Parameter Reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | ✅ | Workflow session ID (e.g., WFS-user-auth) |
+| `task_description` | string | ✅ | Detailed task description for context extraction |
+
+## Output Schema
+
+Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json` schema.
+
+**Key Sections**:
+- **metadata**: Session info, keywords, complexity, tech stack
+- **project_context**: Architecture patterns, conventions, tech stack
+- **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
+- **dependencies**: Internal and external dependency graphs
+- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
+- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
+
+## Historical Archive Analysis
+
+### Track 1: Query Archive Manifest
+
+The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
+
+**Step 1: Check for Archive Manifest**
 ```bash
-# Validate session exists
-if [ ! -d ".workflow/${session_id}" ]; then
-  echo "❌ Session ${session_id} not found"
-  exit 1
+# Check if archive manifest exists
+if [[ -f .workflow/.archives/manifest.json ]]; then
+  # Manifest available for querying
 fi
-
-# Load session metadata
-session_metadata=".workflow/${session_id}/workflow-session.json"
 ```
 
-## Output Location
+**Step 2: Extract Task Keywords**
+```javascript
+// From current task description, extract key entities and operations
+const keywords = extractKeywords(task_description);
+// Examples: ["User", "model", "authentication", "JWT", "reporting"]
+```
 
-Context package output location:
+**Step 3: Search Archive for Relevant Sessions**
+```javascript
+// Query manifest for sessions with matching tags or descriptions
+const relevantArchives = archives.filter(archive => {
+  return archive.tags.some(tag => keywords.includes(tag)) ||
+         keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
+});
 ```
-.workflow/{session_id}/.process/context-package.json
+
+**Step 4: Extract Watch Patterns**
+```javascript
+// For each relevant archive, check watch_patterns for applicability
+const historicalConflicts = [];
+
+relevantArchives.forEach(archive => {
+  archive.lessons.watch_patterns?.forEach(pattern => {
+    // Check if pattern trigger matches current task
+    if (isPatternRelevant(pattern.pattern, task_description)) {
+      historicalConflicts.push({
+        source_session: archive.session_id,
+        pattern: pattern.pattern,
+        action: pattern.action,
+        files_to_check: pattern.related_files,
+        archived_at: archive.archived_at
+      });
+    }
+  });
+});
 ```
 
+**Step 5: Inject into Context Package**
+```json
+{
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": ["..."],
+    "affected_modules": ["..."],
+    "mitigation_strategy": "...",
+    "historical_conflicts": [
+      {
+        "source_session": "WFS-auth-feature",
+        "pattern": "When modifying User model",
+        "action": "Check reporting-service and auditing-service dependencies",
+        "files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
+        "archived_at": "2025-09-16T09:00:00Z"
+      }
+    ]
+  }
+}
+```
+
+### Risk Level Escalation
+
+If `historical_conflicts` array is not empty, minimum risk level should be "medium":
+
+```javascript
+if (historicalConflicts.length > 0 && currentRisk === "low") {
+  conflict_detection.risk_level = "medium";
+  conflict_detection.risk_factors.push(
+    `${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
+  );
+}
+```
+
+### Archive Query Algorithm
+
+```markdown
+1. IF .workflow/.archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
+2. IF manifest exists:
+   a. Load manifest.json
+   b. Extract keywords from task_description (nouns, verbs, technical terms)
+   c. Filter archives where:
+      - ANY tag matches keywords (case-insensitive) OR
+      - description contains keywords (case-insensitive substring match)
+   d. For each relevant archive:
+      - Read lessons.watch_patterns array
+      - Check if pattern.pattern keywords overlap with task_description
+      - If relevant: Add to historical_conflicts array
+   e. IF historical_conflicts.length > 0:
+      - Set risk_level = max(current_risk, "medium")
+      - Add to risk_factors
+3. Continue to Track 2 (reference documentation)
+```
+
+## Usage Examples
+
+### Basic Usage
+```bash
+/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
+```
+## Success Criteria
+
+- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
+- ✅ Contains >80% relevant files based on task keywords
+- ✅ Execution completes within 2 minutes
+- ✅ All required schema fields present and valid
+- ✅ Conflict risk accurately assessed
+- ✅ Agent reports completion with statistics
+
 ## Error Handling
 
-### Common Error Handling
-1. **No Active Session**: Create temporary session directory
-2. **MCP Tools Unavailable**: Fallback to traditional bash commands
-3. **Permission Errors**: Prompt user to check file permissions
-4. **Large Project Optimization**: Limit file count, prioritize high-relevance files
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
+| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
+| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
+| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
 
-### Graceful Degradation Strategy
-```bash
-# Fallback when MCP unavailable
-if ! command -v mcp__code-index__find_files; then
-  # Use find command for file discovery
-  find . -name "*{keyword}*" -type f -not -path "*/node_modules/*" -not -path "*/.git/*"
+## Notes
 
-  # Alternative pattern matching
-  find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" \) -exec grep -l "{keyword}" {} \;
-fi
-
-# Use ripgrep instead of MCP search
-rg "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 30
-
-# Content-based search with context
-rg -A 3 -B 3 "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source
-
-# Quick relevance check
-grep -r --include="*.{ts,js,py,go}" -l "{keywords}" . | head -15
-
-# Test files discovery
-find . -name "*test*" -o -name "*spec*" | grep -E "\.(ts|js|py|go)$" | head -10
-
-# Import/dependency analysis
-rg "^(import|from|require|#include)" --type-add 'source:*.{ts,js,py,go}' -t source | head -20
-```
-
-## Performance Optimization
-
-### Large Project Optimization Strategy
-- **File Count Limit**: Maximum 50 files per type
-- **Size Filtering**: Skip oversized files (>10MB)
-- **Depth Limit**: Maximum search depth of 3 levels
-- **Caching Strategy**: Cache project structure analysis results
-
-### Parallel Processing
-- Documentation collection and code search in parallel
-- MCP tool calls and traditional commands in parallel
-- Reduce I/O wait time
-
-## Essential Bash Commands (Max 10)
-
-### 1. Project Structure Analysis
-```bash
-~/.claude/scripts/get_modules_by_depth.sh
-```
-
-### 2. File Discovery by Keywords
-```bash
-find . -name "*{keyword}*" -type f -not -path "*/node_modules/*" -not -path "*/.git/*"
-```
-
-### 3. Content Search in Code Files
-```bash
-rg "{keyword}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 20
-```
-
-### 4. Configuration Files Discovery
-```bash
-find . -maxdepth 3 \( -name "*.json" -o -name "package.json" -o -name "requirements.txt" -o -name "Cargo.toml" \) -not -path "*/node_modules/*"
-```
-
-### 5. Documentation Files Collection
-```bash
-find . -name "*.md" -o -name "README*" -o -name "CLAUDE.md" | grep -v node_modules | head -10
-```
-
-### 6. Test Files Location
-```bash
-find . \( -name "*test*" -o -name "*spec*" \) -type f | grep -E "\.(js|ts|py|go)$" | head -10
-```
-
-### 7. Function/Class Definitions Search
-```bash
-rg "^(function|def|func|class|interface)" --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
-```
-
-### 8. Import/Dependency Analysis
-```bash
-rg "^(import|from|require|#include)" --type-add 'source:*.{ts,js,py,go}' -t source | head -15
-```
-
-### 9. Workflow Session Information
-```bash
-find .workflow/ -name "*.json" -path "*/${session_id}/*" -o -name "workflow-session.json" | head -5
-```
-
-### 10. Context-Aware Content Search
-```bash
-rg -A 2 -B 2 "{keywords}" --type-add 'source:*.{ts,js,py,go}' -t source --max-count 10
-```
-
-## Success Criteria
-- Generate valid context-package.json file
-- Contains sufficient relevant information for subsequent analysis
-- Execution time controlled within 30 seconds
-- File relevance accuracy rate >80%
-
-## Related Commands
-- `/workflow:tools:concept-enhanced` - Consumes output of this command for analysis
-- `/workflow:plan` - Calls this command to gather context
-- `/workflow:status` - Can display context collection status
+- **Detection-first**: Always check for existing package before invoking agent
+- **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
+- **No redundancy**: This command is a thin orchestrator, all logic in agent
+- **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call

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

@@ -1,590 +0,0 @@
----
-name: docs
-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                          # 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> [--tool <gemini|qwen|codex>] [--scope <path>]
-```
-
-### Parameters
-
-- **type**: `architecture` | `api` | `all` (required)
-  - `architecture`: System design, module interactions, patterns
-  - `api`: Endpoint documentation, API specifications
-  - `all`: Complete documentation suite
-
-- **--tool**: `gemini` | `qwen` | `codex` (optional, default: gemini)
-  - `gemini`: Comprehensive documentation, pattern recognition
-  - `qwen`: Architecture analysis, system design focus
-  - `codex`: Implementation validation, code quality
-
-- **--scope**: Directory path filter (optional)
-
-## Planning Workflow
-
-### Complete Execution Flow
-
-```
-/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
-```
-
-### 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                     # 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
-└── api/                         # IMPL-005: API docs
-    ├── README.md
-    └── openapi.yaml
-```
-
-## Next Steps
-
-### 1. Review Planning Output
-```bash
-cat .workflow/WFS-docs-*/IMPL_PLAN.md
-cat .workflow/WFS-docs-*/TODO_LIST.md
-```
-
-### 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
-
-# Parallel (module docs only)
-/workflow:execute IMPL-002 &
-/workflow:execute IMPL-003 &
-wait
-```
-
-### 3. Review Generated Documentation
-```bash
-ls -lah .workflow/docs/
-cat .workflow/docs/README.md
-```
-
-### 4. TodoWrite Progress
-- Planning: All tasks `pending`
-- Execution: `pending` → `in_progress` → `completed`
-- Real-time status updates via TodoWrite
-
-## Error Handling
-
-- **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
-
-### Clear Separation of Concerns
-- **Planning**: Session creation, task decomposition (this command)
-- **Execution**: Content generation, quality assurance (doc-generator agent)
-
-### Scalable Task Management
-- Independent, self-contained tasks
-- Parallelizable module documentation
-- Clear dependencies (architecture needs modules)
-
-### Template-Driven Consistency
-- All documentation follows standard templates
-- Reusable and maintainable
-- Easy to update standards
-
-### Full Context for Execution
-- Each task JSON contains complete instructions
-- flow_control defines exact analysis steps
-- Tool selection for flexibility

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

@@ -1,22 +1,24 @@
 ---
 name: task-generate-agent
 description: Autonomous task generation using action-planning-agent with discovery and output phases
-usage: /workflow:tools:task-generate-agent --session <session_id>
-argument-hint: "--session WFS-session-id"
+argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
+  - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
 ---
 
 # Autonomous Task Generation Command
 
 ## Overview
-Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation.
+Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
 
 ## Core Philosophy
 - **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
 - **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
 - **Memory-First**: Reuse loaded documents from conversation memory
 - **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
+- **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
+- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
 
 ## Execution Lifecycle
 
@@ -27,21 +29,27 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 ```javascript
 {
   "session_id": "WFS-[session-id]",
+  "execution_mode": "agent-mode" | "cli-execute-mode",  // Determined by flag
+  "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
+                           | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
+  // Path selected by command based on --cli-execute flag, agent reads it
   "session_metadata": {
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/workflow-session.json
   },
-  "analysis_results": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
-  },
-  "artifacts_inventory": {
-    // If in memory: use cached list
-    // Else: Scan .workflow/{session-id}/.brainstorming/ directory
-    "synthesis_specification": "path or null",
-    "topic_framework": "path or null",
-    "role_analyses": ["paths"]
+  "brainstorm_artifacts": {
+    // Loaded from context-package.json → brainstorm_artifacts section
+    "role_analyses": [
+      {
+        "role": "system-architect",
+        "files": [{"path": "...", "type": "primary|supplementary"}]
+      }
+    ],
+    "guidance_specification": {"path": "...", "exists": true},
+    "synthesis_output": {"path": "...", "exists": true},
+    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
   },
+  "context_package_path": ".workflow/{session-id}/.process/context-package.json",
   "context_package": {
     // If in memory: use cached content
     // Else: Load from .workflow/{session-id}/.process/context-package.json
@@ -62,31 +70,38 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
    }
    ```
 
-2. **Load Analysis Results** (if not in memory)
+2. **Load Context Package** (if not in memory)
    ```javascript
-   if (!memory.has("ANALYSIS_RESULTS.md")) {
-     Read(.workflow/{session-id}/.process/ANALYSIS_RESULTS.md)
+   if (!memory.has("context-package.json")) {
+     Read(.workflow/{session-id}/.process/context-package.json)
    }
    ```
 
-3. **Discover Artifacts** (if not in memory)
+3. **Extract & Load Role Analyses** (from context-package.json)
    ```javascript
-   if (!memory.has("artifacts_inventory")) {
-     bash(find .workflow/{session-id}/.brainstorming/ -name "*.md" -type f)
+   // Extract role analysis paths from context package
+   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
+     .flatMap(role => role.files.map(f => f.path));
+
+   // Load each role analysis file
+   roleAnalysisPaths.forEach(path => Read(path));
+   ```
+
+4. **Load Conflict Resolution** (from context-package.json, if exists)
+   ```javascript
+   if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
+     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
    }
    ```
 
-4. **MCP Code Analysis** (optional - enhance understanding)
-   ```javascript
-   // Find relevant files for task context
-   mcp__code-index__find_files(pattern="*auth*")
-   mcp__code-index__search_code_advanced(
-     pattern="authentication|oauth",
-     file_pattern="*.ts"
-   )
+5. **Code Analysis with Native Tools** (optional - enhance understanding)
+   ```bash
+   # Find relevant files for task context
+   find . -name "*auth*" -type f
+   rg "authentication|oauth" -g "*.ts"
    ```
 
-5. **MCP External Research** (optional - gather best practices)
+6. **MCP External Research** (optional - gather best practices)
    ```javascript
    // Get external examples for implementation
    mcp__exa__get_code_context_exa(
@@ -97,6 +112,14 @@ Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent wit
 
 ### Phase 2: Agent Execution (Document Generation)
 
+**Pre-Agent Template Selection** (Command decides path before invoking agent):
+```javascript
+// Command checks flag and selects template PATH (not content)
+const templatePath = hasCliExecuteFlag
+  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
+  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
+```
+
 **Agent Invocation**:
 ```javascript
 Task(
@@ -106,23 +129,32 @@ Task(
 ## Execution Context
 
 **Session ID**: WFS-{session-id}
-**Mode**: Two-Phase Autonomous Task Generation
+**Execution Mode**: {agent-mode | cli-execute-mode}
+**Task JSON Template Path**: {template_path}
 
 ## Phase 1: Discovery Results (Provided Context)
 
 ### Session Metadata
 {session_metadata_content}
 
-### Analysis Results
-{analysis_results_content}
+### Role Analyses (Enhanced by Synthesis)
+{role_analyses_content}
+- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
 
 ### Artifacts Inventory
-- **Synthesis Specification**: {synthesis_spec_path}
-- **Topic Framework**: {topic_framework_path}
+- **Guidance Specification**: {guidance_spec_path}
 - **Role Analyses**: {role_analyses_list}
 
 ### Context Package
 {context_package_summary}
+- Includes conflict_risk assessment
+
+### Conflict Resolution (Conditional)
+If conflict_risk was medium/high, modifications have been applied to:
+- **guidance-specification.md**: Design decisions updated to resolve conflicts
+- **Role analyses (*.md)**: Recommendations adjusted for compatibility
+- **context-package.json**: Marked as "resolved" with conflict IDs
+- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
 
 ### MCP Analysis Results (Optional)
 **Code Structure**: {mcp_code_index_results}
@@ -148,322 +180,35 @@ Task(
 
 #### 1. Task JSON Files (.task/IMPL-*.json)
 **Location**: .workflow/{session-id}/.task/
-**Schema**: 5-field enhanced schema with artifacts
+**Template**: Read from the template path provided above
 
-**Required Fields**:
-\`\`\`json
-{
-  "id": "IMPL-N[.M]",
-  "title": "Descriptive task name",
-  "status": "pending",
-  "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
-  },
-  "context": {
-    "requirements": ["extracted from analysis"],
-    "focus_paths": ["src/paths"],
-    "acceptance": ["measurable criteria"],
-    "depends_on": ["IMPL-N"],
-    "artifacts": [
-      {
-        "type": "synthesis_specification",
-        "path": "{synthesis_spec_path}",
-        "priority": "highest",
-        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
-      },
-      {
-        "type": "role_analysis",
-        "path": "{role_analysis_path}",
-        "priority": "high",
-        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
-        "note": "Dynamically discovered - multiple role analysis files included based on brainstorming results"
-      },
-      {
-        "type": "topic_framework",
-        "path": "{topic_framework_path}",
-        "priority": "low",
-        "usage": "Discussion context and framework structure"
-      }
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
-        "commands": [
-          "bash(ls {synthesis_spec_path} 2>/dev/null || echo 'not found')",
-          "Read({synthesis_spec_path})"
-        ],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "mcp_codebase_exploration",
-        "action": "Explore codebase using MCP",
-        "command": "mcp__code-index__find_files(pattern=\\"[patterns]\\") && mcp__code-index__search_code_advanced(pattern=\\"[patterns]\\")",
-        "output_to": "codebase_structure"
-      },
-      {
-        "step": "analyze_task_patterns",
-        "action": "Analyze existing code patterns",
-        "commands": [
-          "bash(cd \\"[focus_paths]\\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \\"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\\")"
-        ],
-        "output_to": "task_context",
-        "on_error": "fail"
-      }
-    ],
-    "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-      "modification_points": ["Apply requirements from synthesis"],
-      "logic_flow": [
-        "Load synthesis specification",
-        "Analyze existing patterns",
-        "Implement following specification",
-        "Consult artifacts for technical details when needed",
-        "Validate against acceptance criteria"
-      ]
-    },
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
-  }
-}
+**Task JSON Template Loading**:
 \`\`\`
+Read({template_path})
+\`\`\`
+
+**Important**:
+- Read the template from the path provided in context
+- Use the template structure exactly as written
+- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
+- Include MCP tool integration in pre_analysis steps
+- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
 
 #### 2. IMPL_PLAN.md
 **Location**: .workflow/{session-id}/IMPL_PLAN.md
-**Structure**:
-\`\`\`markdown
----
-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}
-
-## 1. Summary
-Core requirements, objectives, technical approach summary (2-3 paragraphs max).
-
-**Core Objectives**:
-- [Key objective 1]
-- [Key objective 2]
-
-**Technical Approach**:
-- [High-level approach]
-
-## 2. Context Analysis
-
-### 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
+**IMPL_PLAN Template**:
 \`\`\`
-[Directory tree showing key modules]
+$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
 \`\`\`
 
-### 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]
-\`\`\`
+**Important**:
+- Use the template above for IMPL_PLAN.md generation
+- Replace all {placeholder} variables with actual session-specific values
+- Populate CCW Workflow Context based on actual phase progression
+- Extract content from role analyses and context-package.json
+- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
+- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
 
 #### 3. TODO_LIST.md
 **Location**: .workflow/{session-id}/TODO_LIST.md
@@ -484,52 +229,58 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - \`- [x]\` = Completed leaf task
 \`\`\`
 
-### Execution Instructions
+### Execution Instructions for Agent
 
-**Step 1: Extract Task Definitions**
-- Parse analysis results for task recommendations
-- Extract task ID, title, requirements, complexity
-- Map artifacts to relevant tasks based on type
+**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
 
-**Step 2: Generate Task JSON Files**
-- Create individual .task/IMPL-*.json files
-- Embed artifacts array with detected brainstorming outputs
-- Generate flow_control with artifact loading steps
-- Add MCP tool integration for codebase exploration
+**Note**: The correct task JSON template path has been pre-selected by the command based on the `--cli-execute` flag and is provided in the context as `{template_path}`.
 
-**Step 3: Create IMPL_PLAN.md**
-- Summarize requirements and technical approach
-- List detected artifacts with priorities
-- Document task breakdown and dependencies
-- Define execution strategy and success criteria
+**Step 1: Load Task JSON Template**
+- Read template from the provided path: `Read({template_path})`
+- This template is already the correct one based on execution mode
 
-**Step 4: Generate TODO_LIST.md**
-- List all tasks with container/leaf structure
-- Link to task JSON files
+**Step 2: Extract and Decompose Tasks**
+- Parse role analysis.md files for requirements, design specs, and task recommendations
+- Review synthesis enhancements and clarifications in role analyses
+- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
+- Apply task merging rules (merge when possible, decompose only when necessary)
+- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
+- Ensure task count ≤10
+
+**Step 3: Generate Task JSON Files**
+- Use the template structure from Step 1
+- Create .task/IMPL-*.json files with proper structure
+- Replace all {placeholder} variables with actual session paths
+- Embed artifacts array with brainstorming outputs
+- Include MCP tool integration in pre_analysis steps
+
+**Step 4: Create IMPL_PLAN.md**
+- Use IMPL_PLAN template
+- Populate all sections with session-specific content
+- List artifacts with priorities and usage guidelines
+- Document execution strategy and dependencies
+
+**Step 5: Generate TODO_LIST.md**
+- Create task progress checklist matching generated JSONs
 - Use proper status indicators (▸, [ ], [x])
+- Link to task JSON files
 
-**Step 5: Update Session State**
-- Update .workflow/{session-id}/workflow-session.json
-- Mark session as ready for execution
-- Record task count and artifact inventory
+**Step 6: Update Session State**
+- Update workflow-session.json with task count and artifact inventory
+- Mark session ready for execution
 
 ### MCP Enhancement Examples
 
 **Code Index Usage**:
 \`\`\`javascript
 // Discover authentication-related files
-mcp__code-index__find_files(pattern="*auth*")
+bash(find . -name "*auth*" -type f)
 
 // Search for OAuth patterns
-mcp__code-index__search_code_advanced(
-  pattern="oauth|jwt|authentication",
-  file_pattern="*.{ts,js}"
-)
+bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
 
 // Get file summary for key components
-mcp__code-index__get_file_summary(
-  file_path="src/auth/index.ts"
-)
+bash(rg "^(class|function|export|interface)" src/auth/index.ts)
 \`\`\`
 
 **Exa Research Usage**:
@@ -565,23 +316,13 @@ Before completion, verify:
 
 Generate all three documents and report completion status:
 - Task JSON files created: N files
-- Artifacts integrated: synthesis-spec, topic-framework, N role analyses
+- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
 - MCP enhancements: code-index, exa-research
 - Session ready for execution: /workflow:execute
 `
 )
 ```
 
-## Command Integration
-
-### Usage
-```bash
-# Basic usage
-/workflow:tools:task-generate-agent --session WFS-auth
-
-# Called by /workflow:plan
-SlashCommand(command="/workflow:tools:task-generate-agent --session WFS-[id]")
-```
 
 ### Agent Context Passing
 
@@ -596,36 +337,26 @@ const agentContext = {
     ? memory.get("workflow-session.json")
     : Read(.workflow/WFS-[id]/workflow-session.json),
 
-  analysis_results: memory.has("ANALYSIS_RESULTS.md")
-    ? memory.get("ANALYSIS_RESULTS.md")
-    : Read(.workflow/WFS-[id]/.process/ANALYSIS_RESULTS.md),
-
-  artifacts_inventory: memory.has("artifacts_inventory")
-    ? memory.get("artifacts_inventory")
-    : discoverArtifacts(),
+  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
 
   context_package: memory.has("context-package.json")
     ? memory.get("context-package.json")
-    : Read(.workflow/WFS-[id]/.process/context-package.json),
+    : Read(".workflow/WFS-[id]/.process/context-package.json"),
+
+  // Extract brainstorm artifacts from context package
+  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
+
+  // Load role analyses using paths from context package
+  role_analyses: brainstorm_artifacts.role_analyses
+    .flatMap(role => role.files)
+    .map(file => Read(file.path)),
+
+  // Load conflict resolution if exists (from context package)
+  conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
+    ? Read(brainstorm_artifacts.conflict_resolution.path)
+    : null,
 
   // Optional MCP enhancements
   mcp_analysis: executeMcpDiscovery()
 }
 ```
-
-## Related Commands
-- `/workflow:plan` - Orchestrates planning and calls this command
-- `/workflow:tools:task-generate` - Manual version without agent
-- `/workflow:tools:context-gather` - Provides context package
-- `/workflow:tools:concept-enhanced` - Provides analysis results
-- `/workflow:execute` - Executes generated tasks
-
-## Key Differences from task-generate
-
-| Feature | task-generate | task-generate-agent |
-|---------|--------------|-------------------|
-| Execution | Manual/scripted | Agent-driven |
-| Phases | 6 phases | 2 phases (discovery + output) |
-| MCP Integration | Optional | Enhanced with examples |
-| Decision Logic | Command-driven | Agent-autonomous |
-| Complexity | Higher control | Simpler delegation |

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

@@ -1,74 +1,184 @@
----
+--- 
 name: task-generate
 description: Generate task JSON files and IMPL_PLAN.md from analysis results with artifacts integration
-usage: /workflow:tools:task-generate --session <session_id>
-argument-hint: "--session WFS-session-id"
+argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate --session WFS-auth
+  - /workflow:tools:task-generate --session WFS-auth --cli-execute
 ---
 
 # Task Generation Command
 
-## Overview
-Generate task JSON files and IMPL_PLAN.md from analysis results with automatic artifact detection and integration.
+## 1. Overview
+This command generates task JSON files and an `IMPL_PLAN.md` from brainstorming role analyses. It automatically detects and integrates all brainstorming artifacts (role-specific `analysis.md` files and `guidance-specification.md`), creating a structured and context-rich plan for implementation. The command supports two primary execution modes: a default agent-based mode for seamless context handling and a `--cli-execute` mode that leverages the Codex CLI for complex, autonomous development tasks. Its core function is to translate requirements and design specifications from role analyses into actionable, executable tasks, ensuring all necessary context, dependencies, and implementation steps are defined upfront.
 
-## Core Philosophy
-- **Analysis-Driven**: Generate from ANALYSIS_RESULTS.md
-- **Artifact-Aware**: Auto-detect brainstorming outputs
-- **Context-Rich**: Embed comprehensive context in task JSON
-- **Flow-Control Ready**: Pre-define implementation steps
-- **Memory-First**: Reuse loaded documents from memory
+## 2. Execution Modes
 
-## Core Responsibilities
-- Parse analysis results and extract tasks
-- Detect and integrate brainstorming artifacts
-- Generate enhanced task JSON files (5-field schema)
-- Create IMPL_PLAN.md and TODO_LIST.md
-- Update session state for execution
+This command offers two distinct modes for task execution, providing flexibility for different implementation complexities.
 
-## Execution Lifecycle
+### Agent Mode (Default)
+In the default mode, each step in `implementation_approach` **omits the `command` field**. The agent interprets the step's `modification_points` and `logic_flow` to execute the task autonomously.
+- **Step Structure**: Contains `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, and `output` fields
+- **Execution**: Agent reads these fields and performs the implementation autonomously
+- **Context Loading**: Agent loads context via `pre_analysis` steps
+- **Validation**: Agent validates against acceptance criteria in `context.acceptance`
+- **Benefit**: Direct agent execution with full context awareness, no external tool overhead
+- **Use Case**: Standard implementation tasks where agent capability is sufficient
 
-### Phase 1: Input Validation & Discovery
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+### CLI Execute Mode (`--cli-execute`)
+When the `--cli-execute` flag is used, each step in `implementation_approach` **includes a `command` field** that specifies the exact execution command. This mode is designed for complex implementations requiring specialized CLI tools.
+- **Step Structure**: Includes all default fields PLUS a `command` field
+- **Execution**: The specified command executes the step directly (e.g., `bash(codex ...)`)
+- **Context Packages**: Each command receives context via the CONTEXT field in the prompt
+- **Multi-Step Support**: Complex tasks can have multiple sequential codex steps with `resume --last`
+- **Benefit**: Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning and autonomous execution
+- **Use Case**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
 
-1. **Session Validation**
-   - If session metadata in memory → Skip loading
-   - Else: Load `.workflow/{session_id}/workflow-session.json`
+## 3. Core Principles
+This command is built on a set of core principles to ensure efficient and reliable task generation.
 
-2. **Analysis Results Loading**
-   - If ANALYSIS_RESULTS.md in memory → Skip loading
-   - Else: Read `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
+- **Role Analysis-Driven**: All generated tasks originate from role-specific `analysis.md` files (enhanced in synthesis phase), ensuring direct link between requirements/design and implementation
+- **Artifact-Aware**: Automatically detects and integrates all brainstorming outputs (role analyses, guidance-specification.md, enhancements) to enrich task context
+- **Context-Rich**: Embeds comprehensive context (requirements, focus paths, acceptance criteria, artifact references) directly into each task JSON
+- **Flow-Control Ready**: Pre-defines clear execution sequence (`pre_analysis`, `implementation_approach`) within each task
+- **Memory-First**: Prioritizes using documents already loaded in conversation memory to avoid redundant file operations
+- **Mode-Flexible**: Supports both agent-driven execution (default) and CLI tool execution (with `--cli-execute` flag)
+- **Multi-Step Support**: Complex tasks can use multiple sequential steps in `implementation_approach` with codex resume mechanism
+- **Responsibility**: Parses analysis, detects artifacts, generates enhanced task JSONs, creates `IMPL_PLAN.md` and `TODO_LIST.md`, updates session state
 
-3. **Artifact Discovery**
-   - If artifact inventory in memory → Skip scanning
-   - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
-   - Detect: synthesis-specification.md, topic-framework.md, role analyses
+## 4. Execution Flow
+The command follows a streamlined, three-step process to convert analysis into executable tasks.
 
-### Phase 2: Task JSON Generation
+### Step 1: Input & Discovery
+The process begins by gathering all necessary inputs. It follows a **Memory-First Rule**, skipping file reads if documents are already in the conversation memory.
+1.  **Session Validation**: Loads and validates the session from `.workflow/{session_id}/workflow-session.json`.
+2.  **Context Package Loading** (primary source): Reads `.workflow/{session_id}/.process/context-package.json` for smart context and artifact catalog.
+3.  **Brainstorm Artifacts Extraction**: Extracts role analysis paths from `context-package.json` → `brainstorm_artifacts.role_analyses[]` (supports `analysis*.md` automatically).
+4.  **Document Loading**: Reads role analyses, guidance specification, synthesis output, and conflict resolution (if exists) using paths from context package.
 
-#### Task Decomposition Standards
-**Core Principle: Task Merging Over Decomposition**
-- **Merge Rule**: Execute together when possible
-- **Decompose Only When**:
-  - Excessive workload (>2500 lines or >6 files)
-  - Different tech stacks or domains
-  - Sequential dependency blocking
-  - Parallel execution needed
+### Step 2: Task Decomposition & Grouping
+Once all inputs are loaded, the command analyzes the tasks defined in the analysis results and groups them based on shared context.
+1.  **Task Definition Parsing**: Extracts task definitions, requirements, and dependencies.
+2.  **Context Signature Analysis**: Computes a unique hash (`context_signature`) for each task based on its `focus_paths` and referenced `artifacts`.
+3.  **Task Grouping**:
+    *   Tasks with the **same signature** are candidates for merging, as they operate on the same context.
+    *   Tasks with **different signatures** and no dependencies are grouped for parallel execution.
+    *   Tasks with `depends_on` relationships are marked for sequential execution.
+4.  **Modification Target Determination**: Extracts specific code locations (`file:function:lines`) from the analysis to populate the `target_files` field.
 
+### Step 3: Output Generation
+Finally, the command generates all the necessary output files.
+1.  **Task JSON Creation**: Creates individual `.task/IMPL-*.json` files, embedding all context, artifacts, and flow control steps. If `--cli-execute` is active, it generates the appropriate `codex exec` commands.
+2.  **IMPL_PLAN.md Generation**: Creates the main implementation plan document, summarizing the strategy, tasks, and dependencies.
+3.  **TODO_LIST.md Generation**: Creates a simple checklist for tracking task progress.
+4.  **Session State Update**: Updates `workflow-session.json` with the final task count and artifact inventory, marking the session as ready for execution.
+
+## 5. Task Decomposition Strategy
+The command employs a sophisticated strategy to group and decompose tasks, optimizing for context reuse and parallel execution.
+
+### Core Principles
+- **Primary Rule: Shared Context → Merge Tasks**: Tasks that operate on the same files, use the same artifacts, and share the same tech stack are merged. This avoids redundant context loading and recognizes inherent relationships between the tasks.
+- **Secondary Rule: Different Contexts + No Dependencies → Decompose for Parallel Execution**: Tasks that are fully independent (different files, different artifacts, no shared dependencies) are decomposed into separate parallel execution groups.
+
+### Context Analysis for Task Grouping
+The decision to merge or decompose is based on analyzing context indicators:
+
+1.  **Shared Context Indicators (→ Merge)**:
+    *   Identical `focus_paths` (working on the same modules/files).
+    *   Same tech stack and dependencies.
+    *   Identical `context.artifacts` references.
+    *   A sequential logic flow within the same feature.
+    *   Shared test fixtures or setup.
+
+2.  **Independent Context Indicators (→ Decompose)**:
+    *   Different `focus_paths` (separate modules).
+    *   Different tech stacks (e.g., frontend vs. backend).
+    *   Different `context.artifacts` (using different brainstorming outputs).
+    *   No shared dependencies.
+    *   Can be tested independently.
+
+**Decomposition is only performed when**:
+- Tasks have different contexts and no shared dependencies (enabling parallel execution).
+- A single task represents an excessive workload (e.g., >2500 lines of code or >6 files to modify).
+- A sequential dependency creates a necessary block (e.g., IMPL-1 must complete before IMPL-2 can start).
+
+### Context Signature Algorithm
+To automate grouping, a `context_signature` is computed for each task.
+
+```javascript
+// Compute context signature for task grouping
+function computeContextSignature(task) {
+  const focusPathsStr = task.context.focus_paths.sort().join('|');
+  const artifactsStr = task.context.artifacts.map(a => a.path).sort().join('|');
+  const techStack = task.context.shared_context?.tech_stack?.sort().join('|') || '';
+
+  return hash(`${focusPathsStr}:${artifactsStr}:${techStack}`);
+}
+```
+
+### Execution Group Assignment
+Tasks are assigned to execution groups based on their signatures and dependencies.
+
+```javascript
+// Group tasks by context signature
+function groupTasksByContext(tasks) {
+  const groups = {};
+
+  tasks.forEach(task => {
+    const signature = computeContextSignature(task);
+    if (!groups[signature]) {
+      groups[signature] = [];
+    }
+    groups[signature].push(task);
+  });
+
+  return groups;
+}
+
+// Assign execution groups for parallel tasks
+function assignExecutionGroups(tasks) {
+  const contextGroups = groupTasksByContext(tasks);
+
+  Object.entries(contextGroups).forEach(([signature, groupTasks]) => {
+    if (groupTasks.length === 1) {
+      const task = groupTasks[0];
+      // Single task with unique context
+      if (!task.context.depends_on || task.context.depends_on.length === 0) {
+        task.meta.execution_group = `parallel-${signature.slice(0, 8)}`;
+      } else {
+        task.meta.execution_group = null; // Sequential task
+      }
+    } else {
+      // Multiple tasks with same context → Should be merged
+      console.warn(`Tasks ${groupTasks.map(t => t.id).join(', ')} share context and should be merged`);
+      // Merge tasks into single task
+      return mergeTasks(groupTasks);
+    }
+  });
+}
+```
 **Task Limits**:
-- **Maximum 10 tasks** (hard limit)
-- **Function-based**: Complete units (logic + UI + tests + config)
-- **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
+- **Maximum 10 tasks** (hard limit).
+- **Hierarchy**: Flat (≤5 tasks) or two-level (6-10 tasks). If >10, the scope should be re-evaluated.
+- **Parallel Groups**: Tasks with the same `execution_group` ID are independent and can run concurrently.
+
+## 6. Generated Outputs
+The command produces three key documents and a directory of task files.
+
+### 6.1. Task JSON Schema (`.task/IMPL-*.json`)
+This enhanced 5-field schema embeds all necessary context, artifacts, and execution steps.
 
-#### Enhanced Task JSON Schema (5-Field + Artifacts)
 ```json
 {
   "id": "IMPL-N[.M]",
   "title": "Descriptive task name",
   "status": "pending|active|completed|blocked|container",
+  "context_package_path": ".workflow/WFS-[session]/.process/context-package.json",
   "meta": {
     "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@general-purpose"
+    "agent": "@code-developer|@test-fix-agent|@universal-executor",
+    "execution_group": "group-id|null",
+    "context_signature": "hash-of-focus_paths-and-artifacts"
   },
   "context": {
     "requirements": ["Clear requirement from analysis"],
@@ -80,67 +190,60 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
     "shared_context": {"tech_stack": [], "conventions": []},
     "artifacts": [
       {
-        "type": "synthesis_specification",
-        "source": "brainstorm_synthesis",
-        "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
+        "path": "{{from context-package.json → brainstorm_artifacts.role_analyses[].files[].path}}",
         "priority": "highest",
-        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+        "usage": "Role-specific requirements, design specs, enhanced by synthesis. Paths loaded dynamically from context-package.json (supports multiple files per role: analysis.md, analysis-01.md, analysis-api.md, etc.). Common roles: product-manager, system-architect, ui-designer, data-architect, ux-expert."
       },
       {
-        "type": "role_analysis",
-        "source": "brainstorm_roles",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis.md",
+        "path": ".workflow/WFS-[session]/.brainstorming/guidance-specification.md",
         "priority": "high",
-        "usage": "Technical/design/business details from specific roles. Common roles: system-architect (ADRs, APIs, caching), ui-designer (design tokens, layouts), product-manager (user stories, metrics)",
-        "note": "Dynamically discovered - multiple role analysis files may be included based on brainstorming results"
-      },
-      {
-        "type": "topic_framework",
-        "source": "brainstorm_framework",
-        "path": ".workflow/WFS-[session]/.brainstorming/topic-framework.md",
-        "priority": "low",
-        "usage": "Discussion context and framework structure"
+        "usage": "Finalized design decisions (potentially modified by conflict resolution if conflict_risk was medium/high). Use for: understanding resolved requirements, design choices, conflict resolutions applied in-place"
       }
     ]
   },
   "flow_control": {
     "pre_analysis": [
       {
-        "step": "load_synthesis_specification",
-        "action": "Load consolidated synthesis specification",
+        "step": "load_context_package",
+        "action": "Load context package for artifact paths",
+        "note": "Context package path is now at top-level field: context_package_path",
         "commands": [
-          "bash(ls .workflow/WFS-[session]/.brainstorming/synthesis-specification.md 2>/dev/null || echo 'not found')",
-          "Read(.workflow/WFS-[session]/.brainstorming/synthesis-specification.md)"
+          "Read({{context_package_path}})"
         ],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
+        "output_to": "context_package",
+        "on_error": "fail"
       },
       {
         "step": "load_role_analysis_artifacts",
-        "action": "Load role-specific analysis documents for technical details",
-        "note": "These artifacts contain implementation details not in synthesis. Consult when needing: API schemas, caching configs, design tokens, ADRs, performance metrics.",
+        "action": "Load role analyses from context-package.json (supports multiple files per role)",
+        "note": "Paths loaded from context-package.json → brainstorm_artifacts.role_analyses[]. Supports analysis*.md automatically.",
         "commands": [
-          "bash(find .workflow/WFS-[session]/.brainstorming/ -name 'analysis.md' 2>/dev/null | head -8)",
-          "Read(.workflow/WFS-[session]/.brainstorming/system-architect/analysis.md)",
-          "Read(.workflow/WFS-[session]/.brainstorming/ui-designer/analysis.md)",
-          "Read(.workflow/WFS-[session]/.brainstorming/product-manager/analysis.md)"
+          "Read({{context_package_path}})",
+          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+          "Read(each extracted path)"
         ],
         "output_to": "role_analysis_artifacts",
         "on_error": "skip_optional"
       },
       {
         "step": "load_planning_context",
-        "action": "Load plan-generated analysis",
+        "action": "Load plan-generated context intelligence with resolved conflicts",
+        "note": "CRITICAL: context-package.json (from context_package_path) provides smart context (focus paths, dependencies, patterns) and conflict resolution status. If conflict_risk was medium/high, conflicts have been resolved in guidance-specification.md and role analyses.",
         "commands": [
-          "Read(.workflow/WFS-[session]/.process/ANALYSIS_RESULTS.md)",
-          "Read(.workflow/WFS-[session]/.process/context-package.json)"
+          "Read({{context_package_path}})",
+          "Read(.workflow/WFS-[session]/.brainstorming/guidance-specification.md)"
         ],
-        "output_to": "planning_context"
+        "output_to": "planning_context",
+        "on_error": "fail",
+        "usage_guidance": {
+          "context-package.json": "Use for focus_paths validation, dependency resolution, existing pattern discovery, module structure understanding, conflict_risk status (resolved/none/low)",
+          "guidance-specification.md": "Use for finalized design decisions (includes applied conflict resolutions if any)"
+        }
       },
       {
-        "step": "mcp_codebase_exploration",
-        "action": "Explore codebase using MCP tools",
-        "command": "mcp__code-index__find_files(pattern=\"[patterns]\") && mcp__code-index__search_code_advanced(pattern=\"[patterns]\")",
+        "step": "codebase_exploration",
+        "action": "Explore codebase using native tools",
+        "command": "bash(find . -name \"[patterns]\" -type f && rg \"[patterns]\")",
         "output_to": "codebase_structure"
       },
       {
@@ -148,105 +251,63 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "action": "Analyze existing code patterns and identify modification targets",
         "commands": [
           "bash(cd \"[focus_paths]\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
+          "bash(gemini \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [role_analyses] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Consult role analyses for requirements, identify exact modification points\")"
         ],
         "output_to": "task_context_with_targets",
         "on_error": "fail"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification. PRIORITY: Use synthesis-specification.md as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-      "modification_points": [
-        "Apply consolidated requirements from synthesis-specification.md",
-        "Follow technical guidelines from synthesis",
-        "Consult artifacts for implementation details when needed",
-        "Integrate with existing patterns"
-      ],
-      "logic_flow": [
-        "Load synthesis specification",
-        "Extract requirements and design",
-        "Analyze existing patterns",
-        "Implement following specification",
-        "Consult artifacts for technical details when needed",
-        "Validate against acceptance criteria"
-      ]
-    },
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement task following role analyses and context",
+        "description": "Implement '[title]' following this priority: 1) role analysis.md files (requirements, design specs, enhancements from synthesis), 2) guidance-specification.md (finalized decisions with resolved conflicts), 3) context-package.json (smart context, focus paths, patterns). Role analyses are enhanced by synthesis phase with concept improvements and clarifications. If conflict_risk was medium/high, conflict resolutions are already applied in-place.",
+        "modification_points": [
+          "Apply requirements and design specs from role analysis documents",
+          "Use enhancements and clarifications from synthesis phase",
+          "Use finalized decisions from guidance-specification.md (includes resolved conflicts)",
+          "Use context-package.json for focus paths and dependency resolution",
+          "Consult specific role artifacts for implementation details when needed",
+          "Integrate with existing patterns"
+        ],
+        "logic_flow": [
+          "Load role analyses (requirements, design, enhancements from synthesis)",
+          "Load guidance-specification.md (finalized decisions with resolved conflicts if any)",
+          "Load context-package.json (smart context: focus paths, dependencies, patterns, conflict_risk status)",
+          "Extract requirements and design decisions from role documents",
+          "Review synthesis enhancements and clarifications",
+          "Use finalized decisions (conflicts already resolved if applicable)",
+          "Identify modification targets using context package",
+          "Implement following role requirements and design specs",
+          "Consult role artifacts for detailed specifications when needed",
+          "Validate against acceptance criteria"
+        ],
+        "depends_on": [],
+        "output": "implementation"
+      }
+    ],
     "target_files": ["file:function:lines"]
   }
 }
 ```
 
-#### Task Generation Process
-1. Parse analysis results and extract task definitions
-2. Detect brainstorming artifacts with priority scoring
-3. Generate task context (requirements, focus_paths, acceptance)
-4. **Determine modification targets**: Extract specific code locations from analysis
-5. Build flow_control with artifact loading steps and target_files
-6. Create individual task JSON files in `.task/`
+### 6.2. IMPL_PLAN.md Structure
+This document provides a high-level overview of the entire implementation plan.
 
-#### Target Files Generation (Critical)
-**Purpose**: Identify specific code locations for modification AND new files to create
-
-**Source Data Priority**:
-1. **ANALYSIS_RESULTS.md** - Should contain identified code locations
-2. **Gemini/MCP Analysis** - From `analyze_task_patterns` step
-3. **Context Package** - File references from `focus_paths`
-
-**Format**: `["file:function:lines"]` or `["file"]` (for new files)
-- `file`: Relative path from project root (e.g., `src/auth/AuthService.ts`)
-- `function`: Function/method name to modify (e.g., `login`, `validateToken`) - **omit for new files**
-- `lines`: Approximate line range (e.g., `45-52`, `120-135`) - **omit for new files**
-
-**Examples**:
-```json
-"target_files": [
-  "src/auth/AuthService.ts:login:45-52",
-  "src/middleware/auth.ts:validateToken:30-45",
-  "src/auth/PasswordReset.ts",
-  "tests/auth/PasswordReset.test.ts",
-  "tests/auth.test.ts:testLogin:15-20"
-]
-```
-
-**Generation Strategy**:
-- **New files to create** → Use `["path/to/NewFile.ts"]` (no function or lines)
-- **Existing files with specific locations** → Use `["file:function:lines"]`
-- **Existing files with function only** → Search lines using MCP/grep `["file:function:*"]`
-- **Existing files (explore entire)** → Mark as `["file.ts:*:*"]`
-- **No specific targets** → Leave empty `[]` (agent explores focus_paths)
-
-### Phase 3: Artifact Detection & Integration
-
-#### Artifact Priority
-1. **synthesis-specification.md** (highest) - Complete integrated spec
-2. **topic-framework.md** (medium) - Discussion framework
-3. **role/analysis.md** (low) - Individual perspectives
-
-#### Artifact-Task Mapping
-- **synthesis-specification.md** → All tasks
-- **ui-designer/analysis.md** → UI/Frontend tasks
-- **ux-expert/analysis.md** → UX/Interaction tasks
-- **system-architect/analysis.md** → Architecture/Backend tasks
-- **subject-matter-expert/analysis.md** → Domain/Standards tasks
-- **data-architect/analysis.md** → Data/API tasks
-- **scrum-master/analysis.md** → Sprint/Process tasks
-- **product-owner/analysis.md** → Backlog/Story tasks
-
-### Phase 4: IMPL_PLAN.md Generation
-
-#### Document Structure
 ```markdown
 ---
 identifier: WFS-{session-id}
 source: "User requirements" | "File: path" | "Issue: ISS-001"
-analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+role_analyses: .workflow/{session-id}/.brainstorming/[role]/analysis*.md
 artifacts: .workflow/{session-id}/.brainstorming/
 context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+guidance_specification: .workflow/{session-id}/.brainstorming/guidance-specification.md  # Finalized decisions with resolved conflicts
 workflow_type: "standard | tdd | design"  # Indicates execution model
 verification_history:  # CCW quality gates
-  concept_verify: "passed | skipped | pending"
+  synthesis_clarify: "passed | skipped | pending"  # Brainstorm phase clarification
   action_plan_verify: "pending"
-phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
+  conflict_resolution: "resolved | none | low"  # Status from context-package.json
+phase_progression: "brainstorm → synthesis → context → conflict_resolution (if needed) → planning"  # CCW workflow phases
 ---
 
 # Implementation Plan: {Project Title}
@@ -265,14 +326,14 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 ### 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)
+- ✅ Phase 1: Brainstorming (role analyses generated by participating roles)
+- ✅ Phase 2: Synthesis (concept enhancement + clarification, {N} questions answered, role analyses refined)
+- ✅ Phase 3: Context Gathering (context-package.json: {N} files, {M} modules analyzed, conflict_risk: {level})
+- ✅ Phase 4: Conflict Resolution ({status}: {conflict_count} conflicts detected and resolved | skipped if no conflicts)
+- ⏳ Phase 5: Task Generation (current phase - generating IMPL_PLAN.md and task JSONs)
 
 **Quality Gates**:
-- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
+- synthesis-clarify: ✅ Passed ({N} ambiguities resolved, {M} enhancements applied)
 - action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
 
 **Context Package Summary**:
@@ -288,9 +349,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - **Timeline**: Duration and milestones
 
 ### Module Structure
-```
+'''
 [Directory tree showing key modules]
-```
+'''
 
 ### Dependencies
 **Primary**: [Core libraries and frameworks]
@@ -306,40 +367,42 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 ## 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
+**Primary Reference (Role Analyses)**:
+- **What**: Role-specific analyses from brainstorming phase providing multi-perspective insights
+- **When**: Every task references relevant role analyses for requirements and design decisions
+- **How**: Extract requirements, architecture decisions, UI/UX patterns from applicable role documents
+- **Priority**: Collective authoritative source - multiple role perspectives provide comprehensive coverage
+- **CCW Value**: Maintains role-specific expertise while enabling cross-role integration during planning
 
 **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
+- **Content**: Focus paths, dependency graph, existing patterns, module structure, tech stack, conflict_risk status
+- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup and conflict awareness
 - **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
+**Conflict Resolution Status**:
+- **What**: Conflict resolution applied in-place to brainstorm artifacts (if conflict_risk was >= medium)
+- **Location**: guidance-specification.md and role analyses (*.md) contain resolved conflicts
+- **Status**: Check context-package.json → conflict_detection.conflict_risk ("resolved" | "none" | "low")
+- **Usage**: Read finalized decisions from guidance-specification.md (includes applied resolutions)
+- **CCW Value**: Interactive conflict resolution with user confirmation, modifications applied automatically
 
-### Integrated Specifications (Highest Priority)
-- **synthesis-specification.md**: Comprehensive implementation blueprint
-  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+### Role Analysis Documents (Highest Priority)
+Role analyses provide specialized perspectives on the implementation:
+- **system-architect/analysis.md**: Architecture design, ADRs, API specifications, caching strategies
+- **ui-designer/analysis.md**: Design tokens, layout specifications, component patterns
+- **ux-expert/analysis.md**: User journeys, interaction flows, accessibility requirements
+- **guidance-specification/analysis.md**: Product vision, user stories, business requirements, success metrics
+- **data-architect/analysis.md**: Data models, schemas, database design, migration strategies
+- **api-designer/analysis.md**: API contracts, endpoint specifications, integration patterns
 
 ### 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)
+1. {context_package_path} (primary source: smart context AND brainstorm artifact catalog in `brainstorm_artifacts` + conflict_risk status)
+2. role/analysis*.md (paths from context-package.json: requirements, design specs, enhanced by synthesis, with resolved conflicts if any)
+3. guidance-specification.md (path from context-package.json: finalized decisions with resolved conflicts if any)
 
 ## 4. Implementation Strategy
 
@@ -356,7 +419,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 ### Architectural Approach
 **Key Architecture Decisions**:
-- [ADR references from synthesis]
+- [ADR references from role analyses]
 - [Justification for architecture patterns]
 
 **Integration Strategy**:
@@ -365,9 +428,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 ### Key Dependencies
 **Task Dependency Graph**:
-```
+'''
 [High-level dependency visualization]
-```
+'''
 
 **Critical Path**: [Identify bottleneck tasks]
 
@@ -448,7 +511,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 ## 8. Success Criteria
 
 **Functional Completeness**:
-- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All requirements from role analysis documents implemented
 - [ ] All acceptance criteria from task.json files met
 
 **Technical Quality**:
@@ -462,12 +525,12 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - [ ] Documentation complete
 
 **Business Metrics**:
-- [ ] [Key business metrics from synthesis]
+- [ ] [Key business metrics from role analyses]
 ```
 
-### Phase 5: TODO_LIST.md Generation
+### 6.3. TODO_LIST.md Structure
+A simple Markdown file for tracking the status of each task.
 
-#### Document Structure
 ```markdown
 # Tasks: [Session Topic]
 
@@ -485,12 +548,8 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 - Maximum 2 levels: Main tasks and subtasks only
 ```
 
-### Phase 6: Session State Update
-1. Update workflow-session.json with task count and artifacts
-2. Validate all output files (task JSONs, IMPL_PLAN.md, TODO_LIST.md)
-3. Generate completion report
-
-## Output Files Structure
+### 6.4. Output Files Diagram
+The command organizes outputs into a standard directory structure.
 ```
 .workflow/{session-id}/
 ├── IMPL_PLAN.md                     # Implementation plan
@@ -499,22 +558,226 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 │   ├── IMPL-1.json                  # Container task
 │   ├── IMPL-1.1.json                # Leaf task with flow_control
 │   └── IMPL-1.2.json                # Leaf task with flow_control
-├── .brainstorming/                  # Input artifacts
-│   ├── synthesis-specification.md
-│   ├── topic-framework.md
-│   └── {role}/analysis.md
+├── .brainstorming              # Input artifacts from brainstorm + synthesis
+│   ├── guidance-specification.md    # Finalized decisions (with resolved conflicts if any)
+│   └── {role}/analysis*.md          # Role analyses (enhanced by synthesis, with resolved conflicts if any)
 └── .process/
-    ├── ANALYSIS_RESULTS.md          # Input from concept-enhanced
-    └── context-package.json         # Input from context-gather
+    └── context-package.json         # Input from context-gather (smart context + conflict_risk status)
 ```
 
-## Error Handling
+## 7. Artifact Integration
+The command intelligently detects and integrates artifacts from the `.brainstorming/` directory.
+
+#### Artifact Priority
+1.  **context-package.json** (critical): Primary source - smart context AND all brainstorm artifact paths in `brainstorm_artifacts` section + conflict_risk status
+2.  **role/analysis*.md** (highest): Paths from context-package.json → role-specific requirements, design specs, enhanced by synthesis, with resolved conflicts applied in-place
+3.  **guidance-specification.md** (high): Path from context-package.json → finalized decisions with resolved conflicts (if conflict_risk was >= medium)
+
+#### Artifact-Task Mapping
+Artifacts are mapped to tasks based on their relevance to the task's domain.
+- **Role analysis.md files**: Primary requirements source - all relevant role analyses included based on task type
+- **ui-designer/analysis.md**: Mapped to UI/Frontend tasks for design tokens, layouts, components
+- **system-architect/analysis.md**: Mapped to Architecture/Backend tasks for ADRs, APIs, patterns
+- **subject-matter-expert/analysis.md**: Mapped to tasks related to domain logic or standards
+- **data-architect/analysis.md**: Mapped to tasks involving data models, schemas, or APIs
+- **product-manager/analysis.md**: Mapped to all tasks for business requirements and user stories
+
+This ensures that each task has access to the most relevant and detailed specifications from role-specific analyses.
+
+## 8. CLI Execute Mode Details
+When using `--cli-execute`, each step in `implementation_approach` includes a `command` field with the execution command.
+
+**Key Points**:
+- **Sequential Steps**: Steps execute in order defined in `implementation_approach` array
+    - **Context Delivery**: Each codex command receives context via CONTEXT field: `@{context_package_path}` (role analyses loaded dynamically from context package)- **Multi-Step Tasks**: First step provides full context, subsequent steps use `resume --last` to maintain session continuity
+- **Step Dependencies**: Later steps reference outputs from earlier steps via `depends_on` field
+
+### Example 1: Agent Mode - Simple Task (Default, No Command)
+```json
+{
+  "id": "IMPL-001",
+  "title": "Implement user authentication module",
+  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
+  "context": {
+    "depends_on": [],
+    "focus_paths": ["src/auth"],
+    "requirements": ["JWT-based authentication", "Login and registration endpoints"],
+    "acceptance": [
+      "JWT token generation working",
+      "Login and registration endpoints implemented",
+      "Tests passing with >70% coverage"
+    ]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_role_analyses",
+        "action": "Load role analyses from context-package.json",
+        "commands": [
+          "Read({{context_package_path}})",
+          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+          "Read(each extracted path)"
+        ],
+        "output_to": "role_analyses",
+        "on_error": "fail"
+      },
+      {
+        "step": "load_context",
+        "action": "Load context package for project structure",
+        "commands": ["Read({{context_package_path}})"],
+        "output_to": "context_pkg",
+        "on_error": "fail"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement JWT-based authentication",
+        "description": "Create authentication module using JWT following [role_analyses] requirements and [context_pkg] patterns",
+        "modification_points": [
+          "Create auth service with JWT generation",
+          "Implement login endpoint with credential validation",
+          "Implement registration endpoint with user creation",
+          "Add JWT middleware for route protection"
+        ],
+        "logic_flow": [
+          "User registers → validate input → hash password → create user",
+          "User logs in → validate credentials → generate JWT → return token",
+          "Protected routes → validate JWT → extract user → allow access"
+        ],
+        "depends_on": [],
+        "output": "auth_implementation"
+      }
+    ],
+    "target_files": ["src/auth/service.ts", "src/auth/middleware.ts", "src/routes/auth.ts"]
+  }
+}
+```
+
+### Example 2: CLI Execute Mode - Single Codex Step
+```json
+{
+  "id": "IMPL-002",
+  "title": "Implement user authentication module",
+  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
+  "context": {
+    "depends_on": [],
+    "focus_paths": ["src/auth"],
+    "requirements": ["JWT-based authentication", "Login and registration endpoints"],
+    "acceptance": ["JWT generation working", "Endpoints implemented", "Tests passing"]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_role_analyses",
+        "action": "Load role analyses from context-package.json",
+        "commands": [
+          "Read({{context_package_path}})",
+          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+          "Read(each extracted path)"
+        ],
+        "output_to": "role_analyses",
+        "on_error": "fail"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Implement authentication with Codex",
+        "description": "Create JWT-based authentication module",
+        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Implement user authentication TASK: JWT-based auth with login/registration MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Complete auth module with tests RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
+        "modification_points": ["Create auth service", "Implement endpoints", "Add JWT middleware"],
+        "logic_flow": ["Validate credentials", "Generate JWT", "Return token"],
+        "depends_on": [],
+        "output": "auth_implementation"
+      }
+    ],
+    "target_files": ["src/auth/service.ts", "src/auth/middleware.ts"]
+  }
+}
+```
+
+### Example 3: CLI Execute Mode - Multi-Step with Resume
+```json
+{
+  "id": "IMPL-003",
+  "title": "Implement role-based access control",
+  "context_package_path": ".workflow/WFS-session/.process/context-package.json",
+  "context": {
+    "depends_on": ["IMPL-002"],
+    "focus_paths": ["src/auth", "src/middleware"],
+    "requirements": ["User roles and permissions", "Route protection middleware"],
+    "acceptance": ["RBAC models created", "Middleware working", "Management API complete"]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_context",
+        "action": "Load context and role analyses from context-package.json",
+        "commands": [
+          "Read({{context_package_path}})",
+          "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+          "Read(each extracted path)"
+        ],
+        "output_to": "full_context",
+        "on_error": "fail"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Create RBAC models",
+        "description": "Define role and permission data models",
+        "command": "bash(codex -C src/auth --full-auto exec \"PURPOSE: Create RBAC models TASK: Role and permission models MODE: auto CONTEXT: @{{context_package_path}} EXPECTED: Models with migrations RULES: Load role analyses from context-package.json → brainstorm_artifacts\" --skip-git-repo-check -s danger-full-access)",
+        "modification_points": ["Define role model", "Define permission model", "Create migrations"],
+        "logic_flow": ["Design schema", "Implement models", "Generate migrations"],
+        "depends_on": [],
+        "output": "rbac_models"
+      },
+      {
+        "step": 2,
+        "title": "Implement RBAC middleware",
+        "description": "Create route protection middleware using models from step 1",
+        "command": "bash(codex --full-auto exec \"PURPOSE: Create RBAC middleware TASK: Route protection middleware MODE: auto CONTEXT: RBAC models from step 1 EXPECTED: Middleware for route protection RULES: Use session patterns\" resume --last --skip-git-repo-check -s danger-full-access)",
+        "modification_points": ["Create permission checker", "Add route decorators", "Integrate with auth"],
+        "logic_flow": ["Check user role", "Validate permissions", "Allow/deny access"],
+        "depends_on": [1],
+        "output": "rbac_middleware"
+      },
+      {
+        "step": 3,
+        "title": "Add role management API",
+        "description": "Create CRUD endpoints for roles and permissions",
+        "command": "bash(codex --full-auto exec \"PURPOSE: Role management API TASK: CRUD endpoints for roles/permissions MODE: auto CONTEXT: Models and middleware from previous steps EXPECTED: Complete API with validation RULES: Maintain consistency\" resume --last --skip-git-repo-check -s danger-full-access)",
+        "modification_points": ["Create role endpoints", "Create permission endpoints", "Add validation"],
+        "logic_flow": ["Define routes", "Implement controllers", "Add authorization"],
+        "depends_on": [2],
+        "output": "role_management_api"
+      }
+    ],
+    "target_files": [
+      "src/models/Role.ts",
+      "src/models/Permission.ts",
+      "src/middleware/rbac.ts",
+      "src/routes/roles.ts"
+    ]
+  }
+}
+```
+
+**Pattern Summary**:
+- **Agent Mode (Example 1)**: No `command` field - agent executes via `modification_points` and `logic_flow`
+- **CLI Mode Single-Step (Example 2)**: One `command` field with full context package
+- **CLI Mode Multi-Step (Example 3)**: First step uses full context, subsequent steps use `resume --last`
+- **Context Delivery**: Context package provided via `@{...}` references in CONTEXT field
+
+## 9. Error Handling
 
 ### Input Validation Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
 | Session not found | Invalid session ID | Verify session exists |
-| Analysis missing | Incomplete planning | Run concept-enhanced first |
+| Context missing | Incomplete planning | Run context-gather first |
 | Invalid format | Corrupted results | Regenerate analysis |
 
 ### Task Generation Errors
@@ -531,7 +794,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 | Invalid format | Corrupted file | Skip artifact loading |
 | Path invalid | Moved/deleted | Update references |
 
-## Integration & Usage
+## 10. Integration & Usage
 
 ### Command Chain
 - **Called By**: `/workflow:plan` (Phase 4)
@@ -543,8 +806,9 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 /workflow:tools:task-generate --session WFS-auth
 ```
 
-## Related Commands
+## 11. Related Commands
 - `/workflow:plan` - Orchestrates entire planning
+- `/workflow:plan --cli-execute` - Planning with CLI execution mode
 - `/workflow:tools:context-gather` - Provides context package
-- `/workflow:tools:concept-enhanced` - Provides analysis results
-- `/workflow:execute` - Executes generated tasks
+- `/workflow:tools:conflict-resolution` - Provides conflict resolution strategies (optional)
+- `/workflow:execute` - Executes generated tasks

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

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

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

@@ -1,7 +1,6 @@
 ---
 name: test-concept-enhanced
 description: Analyze test requirements and generate test generation strategy using Gemini
-usage: /workflow:tools:test-concept-enhanced --session <test_session_id> --context <test_context_package_path>
 argument-hint: "--session WFS-test-session-id --context path/to/test-context-package.json"
 examples:
   - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/WFS-test-auth/.process/test-context-package.json
@@ -49,7 +48,7 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
 
 **Tool Configuration**:
 ```bash
-cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -p "
+cd .workflow/{test_session_id}/.process && gemini -p "
 PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
 TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
 MODE: analysis

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

@@ -1,286 +1,188 @@
 ---
 name: test-context-gather
-description: Collect test coverage context and identify files requiring test generation
-usage: /workflow:tools:test-context-gather --session <test_session_id>
+description: Intelligently collect test coverage context using test-context-search-agent and package into standardized test-context JSON
 argument-hint: "--session WFS-test-session-id"
 examples:
   - /workflow:tools:test-context-gather --session WFS-test-auth
   - /workflow:tools:test-context-gather --session WFS-test-payment
+allowed-tools: Task(*), Read(*), Glob(*)
 ---
 
-# Test Context Gather Command
+# Test Context Gather Command (/workflow:tools:test-context-gather)
 
 ## Overview
-Specialized context collector for test generation workflows that analyzes test coverage, identifies missing tests, and packages implementation context from source sessions.
+
+Orchestrator command that invokes `test-context-search-agent` to gather comprehensive test coverage context for test generation workflows. Generates standardized `test-context-package.json` with coverage analysis, framework detection, and source implementation context.
+
+**Agent**: `test-context-search-agent` (`.claude/agents/test-context-search-agent.md`)
 
 ## Core Philosophy
-- **Coverage-First**: Analyze existing test coverage before planning
-- **Gap Identification**: Locate implementation files without corresponding tests
+
+- **Agent Delegation**: Delegate all test coverage analysis to `test-context-search-agent` for autonomous execution
+- **Detection-First**: Check for existing test-context-package before executing
+- **Coverage-First**: Analyze existing test coverage before planning new tests
 - **Source Context Loading**: Import implementation summaries from source session
-- **Framework Detection**: Auto-detect test framework and patterns
-- **MCP-Powered**: Leverage code-index tools for precise analysis
+- **Standardized Output**: Generate `.workflow/{test_session_id}/.process/test-context-package.json`
 
-## Core Responsibilities
-- Load source session implementation context
-- Analyze current test coverage using MCP tools
-- Identify files requiring test generation
-- Detect test framework and conventions
-- Package test context for analysis phase
+## Execution Flow
 
-## Execution Lifecycle
+### Step 1: Test-Context-Package Detection
 
-### Phase 1: Session Validation & Source Loading
+**Execute First** - Check if valid package already exists:
 
-1. **Test Session Validation**
-   - Load `.workflow/{test_session_id}/workflow-session.json`
-   - Extract `meta.source_session` reference
-   - Validate test session type is "test-gen"
+```javascript
+const testContextPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
 
-2. **Source Session Context Loading**
-   - Read `.workflow/{source_session_id}/workflow-session.json`
-   - Load implementation summaries from `.workflow/{source_session_id}/.summaries/`
-   - Extract changed files and implementation scope
-   - Identify implementation patterns and tech stack
+if (file_exists(testContextPath)) {
+  const existing = Read(testContextPath);
 
-### Phase 2: Test Coverage Analysis (MCP Tools)
-
-1. **Existing Test Discovery**
-   ```bash
-   # Find all test files
-   mcp__code-index__find_files(pattern="*.test.*")
-   mcp__code-index__find_files(pattern="*.spec.*")
-   mcp__code-index__find_files(pattern="*test_*.py")
-
-   # Search for test patterns
-   mcp__code-index__search_code_advanced(
-     pattern="describe|it|test|@Test",
-     file_pattern="*.test.*",
-     context_lines=0
-   )
-   ```
-
-2. **Coverage Gap Analysis**
-   ```bash
-   # For each implementation file from source session
-   # Check if corresponding test file exists
-
-   # Example: src/auth/AuthService.ts -> tests/auth/AuthService.test.ts
-   #          src/utils/validator.py -> tests/test_validator.py
-
-   # Output: List of files without tests
-   ```
-
-3. **Test Statistics**
-   - Count total test files
-   - Count implementation files from source session
-   - Calculate coverage percentage
-   - Identify coverage gaps by module
-
-### Phase 3: Test Framework Detection
-
-1. **Framework Identification**
-   ```bash
-   # Check package.json or requirements.txt
-   mcp__code-index__search_code_advanced(
-     pattern="jest|mocha|jasmine|pytest|unittest|rspec",
-     file_pattern="package.json|requirements.txt|Gemfile",
-     context_lines=2
-   )
-
-   # Analyze existing test patterns
-   mcp__code-index__search_code_advanced(
-     pattern="describe\\(|it\\(|test\\(|def test_",
-     file_pattern="*.test.*",
-     context_lines=3
-   )
-   ```
-
-2. **Convention Analysis**
-   - Test file naming patterns (*.test.ts vs *.spec.ts)
-   - Test directory structure (tests/ vs __tests__ vs src/**/*.test.*)
-   - Assertion library (expect, assert, should)
-   - Mocking framework (jest.fn, sinon, unittest.mock)
-
-### Phase 4: Context Packaging
-
-Generate `test-context-package.json`:
-
-```json
-{
-  "metadata": {
-    "test_session_id": "WFS-test-auth",
-    "source_session_id": "WFS-auth",
-    "timestamp": "2025-10-04T10:30:00Z",
-    "task_type": "test-generation",
-    "complexity": "medium"
-  },
-  "source_context": {
-    "implementation_summaries": [
-      {
-        "task_id": "IMPL-001",
-        "summary_path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
-        "changed_files": [
-          "src/auth/AuthService.ts",
-          "src/auth/TokenValidator.ts",
-          "src/middleware/auth.ts"
-        ],
-        "implementation_type": "feature"
-      }
-    ],
-    "tech_stack": ["typescript", "express", "jsonwebtoken"],
-    "project_patterns": {
-      "architecture": "layered",
-      "error_handling": "try-catch with custom errors",
-      "async_pattern": "async/await"
-    }
-  },
-  "test_coverage": {
-    "existing_tests": [
-      "tests/auth/AuthService.test.ts",
-      "tests/middleware/auth.test.ts"
-    ],
-    "missing_tests": [
-      {
-        "implementation_file": "src/auth/TokenValidator.ts",
-        "suggested_test_file": "tests/auth/TokenValidator.test.ts",
-        "priority": "high",
-        "reason": "New implementation without tests"
-      }
-    ],
-    "coverage_stats": {
-      "total_implementation_files": 3,
-      "files_with_tests": 2,
-      "files_without_tests": 1,
-      "coverage_percentage": 66.7
-    }
-  },
-  "test_framework": {
-    "framework": "jest",
-    "version": "^29.0.0",
-    "test_pattern": "**/*.test.ts",
-    "test_directory": "tests/",
-    "assertion_library": "expect",
-    "mocking_framework": "jest",
-    "conventions": {
-      "file_naming": "*.test.ts",
-      "test_structure": "describe/it blocks",
-      "setup_teardown": "beforeEach/afterEach"
-    }
-  },
-  "assets": [
-    {
-      "type": "implementation_summary",
-      "path": ".workflow/WFS-auth/.summaries/IMPL-001-summary.md",
-      "relevance": "Source implementation context",
-      "priority": "highest"
-    },
-    {
-      "type": "existing_test",
-      "path": "tests/auth/AuthService.test.ts",
-      "relevance": "Test pattern reference",
-      "priority": "high"
-    },
-    {
-      "type": "source_code",
-      "path": "src/auth/TokenValidator.ts",
-      "relevance": "Implementation requiring tests",
-      "priority": "high"
-    },
-    {
-      "type": "documentation",
-      "path": "CLAUDE.md",
-      "relevance": "Project conventions",
-      "priority": "medium"
-    }
-  ],
-  "focus_areas": [
-    "Generate comprehensive tests for TokenValidator",
-    "Follow existing Jest patterns from AuthService tests",
-    "Cover happy path, error cases, and edge cases",
-    "Include integration tests for middleware"
-  ]
+  // Validate package belongs to current test session
+  if (existing?.metadata?.test_session_id === test_session_id) {
+    console.log("✅ Valid test-context-package found for session:", test_session_id);
+    console.log("📊 Coverage Stats:", existing.test_coverage.coverage_stats);
+    console.log("🧪 Framework:", existing.test_framework.framework);
+    console.log("⚠️  Missing Tests:", existing.test_coverage.missing_tests.length);
+    return existing; // Skip execution, return existing
+  } else {
+    console.warn("⚠️ Invalid test_session_id in existing package, re-generating...");
+  }
 }
 ```
 
-## Output Location
+### Step 2: Invoke Test-Context-Search Agent
 
-```
-.workflow/{test_session_id}/.process/test-context-package.json
-```
+**Only execute if Step 1 finds no valid package**
 
-## MCP Tools Usage
+```javascript
+Task(
+  subagent_type="test-context-search-agent",
+  description="Gather test coverage context",
+  prompt=`
+You are executing as test-context-search-agent (.claude/agents/test-context-search-agent.md).
 
-### File Discovery
-```bash
-# Test files
-mcp__code-index__find_files(pattern="*.test.*")
-mcp__code-index__find_files(pattern="*.spec.*")
+## Execution Mode
+**PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
 
-# Implementation files
-mcp__code-index__find_files(pattern="*.ts")
-mcp__code-index__find_files(pattern="*.js")
-```
+## Session Information
+- **Test Session ID**: ${test_session_id}
+- **Output Path**: .workflow/${test_session_id}/.process/test-context-package.json
 
-### Content Search
-```bash
-# Test framework detection
-mcp__code-index__search_code_advanced(
-  pattern="jest|mocha|pytest",
-  file_pattern="package.json|requirements.txt"
-)
+## Mission
+Execute complete test-context-search-agent workflow for test generation planning:
 
-# Test pattern analysis
-mcp__code-index__search_code_advanced(
-  pattern="describe|it|test",
-  file_pattern="*.test.*",
-  context_lines=2
+### Phase 1: Session Validation & Source Context Loading
+1. **Detection**: Check for existing test-context-package (early exit if valid)
+2. **Test Session Validation**: Load test session metadata, extract source_session reference
+3. **Source Context Loading**: Load source session implementation summaries, changed files, tech stack
+
+### Phase 2: Test Coverage Analysis
+Execute coverage discovery:
+- **Track 1**: Existing test discovery (find *.test.*, *.spec.* files)
+- **Track 2**: Coverage gap analysis (match implementation files to test files)
+- **Track 3**: Coverage statistics (calculate percentages, identify gaps by module)
+
+### Phase 3: Framework Detection & Packaging
+1. Framework identification from package.json/requirements.txt
+2. Convention analysis from existing test patterns
+3. Generate and validate test-context-package.json
+
+## Output Requirements
+Complete test-context-package.json with:
+- **metadata**: test_session_id, source_session_id, task_type, complexity
+- **source_context**: implementation_summaries, tech_stack, project_patterns
+- **test_coverage**: existing_tests[], missing_tests[], coverage_stats
+- **test_framework**: framework, version, test_pattern, conventions
+- **assets**: implementation_summary[], existing_test[], source_code[] with priorities
+- **focus_areas**: Test generation guidance based on coverage gaps
+
+## Quality Validation
+Before completion verify:
+- [ ] Valid JSON format with all required fields
+- [ ] Source session context loaded successfully
+- [ ] Test coverage gaps identified
+- [ ] Test framework detected (or marked as 'unknown')
+- [ ] Coverage percentage calculated correctly
+- [ ] Missing tests catalogued with priority
+- [ ] Execution time < 30 seconds (< 60s for large codebases)
+
+Execute autonomously following agent documentation.
+Report completion with coverage statistics.
+`
 )
 ```
 
-### Coverage Analysis
-```bash
-# For each implementation file
-# Check if test exists
-implementation_file="src/auth/AuthService.ts"
-test_file_patterns=(
-  "tests/auth/AuthService.test.ts"
-  "src/auth/AuthService.test.ts"
-  "src/auth/__tests__/AuthService.test.ts"
-)
+### Step 3: Output Verification
 
-# Search for test file
-for pattern in "${test_file_patterns[@]}"; do
-  if mcp__code-index__find_files(pattern="$pattern") | grep -q .; then
-    echo "✅ Test exists: $pattern"
-    break
-  fi
-done
+After agent completes, verify output:
+
+```javascript
+// Verify file was created
+const outputPath = `.workflow/${test_session_id}/.process/test-context-package.json`;
+if (!file_exists(outputPath)) {
+  throw new Error("❌ Agent failed to generate test-context-package.json");
+}
+
+// Load and display summary
+const testContext = Read(outputPath);
+console.log("✅ Test context package generated successfully");
+console.log("📊 Coverage:", testContext.test_coverage.coverage_stats.coverage_percentage + "%");
+console.log("⚠️  Tests to generate:", testContext.test_coverage.missing_tests.length);
 ```
 
+## Parameter Reference
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `--session` | string | ✅ | Test workflow session ID (e.g., WFS-test-auth) |
+
+## Output Schema
+
+Refer to `test-context-search-agent.md` Phase 3.2 for complete `test-context-package.json` schema.
+
+**Key Sections**:
+- **metadata**: Test session info, source session reference, complexity
+- **source_context**: Implementation summaries with changed files and tech stack
+- **test_coverage**: Existing tests, missing tests with priorities, coverage statistics
+- **test_framework**: Framework name, version, patterns, conventions
+- **assets**: Categorized files with relevance (implementation_summary, existing_test, source_code)
+- **focus_areas**: Test generation guidance based on analysis
+
+## Usage Examples
+
+### Basic Usage
+```bash
+/workflow:tools:test-context-gather --session WFS-test-auth
+```
+
+### Expected Output
+```
+✅ Valid test-context-package found for session: WFS-test-auth
+📊 Coverage Stats: { total: 3, with_tests: 2, without_tests: 1, percentage: 66.7 }
+🧪 Framework: jest
+⚠️  Missing Tests: 1
+```
+
+## Success Criteria
+
+- ✅ Valid test-context-package.json generated in `.workflow/{test_session_id}/.process/`
+- ✅ Source session context loaded successfully
+- ✅ Test coverage gaps identified (>90% accuracy)
+- ✅ Test framework detected and documented
+- ✅ Execution completes within 30 seconds (60s for large codebases)
+- ✅ All required schema fields present and valid
+- ✅ Coverage statistics calculated correctly
+- ✅ Agent reports completion with statistics
+
 ## Error Handling
 
 | Error | Cause | Resolution |
 |-------|-------|------------|
+| Package validation failed | Invalid test_session_id in existing package | Re-run agent to regenerate |
 | Source session not found | Invalid source_session reference | Verify test session metadata |
 | No implementation summaries | Source session incomplete | Complete source session first |
-| MCP tools unavailable | MCP not configured | Fallback to bash find/grep |
-| No test framework detected | Missing test dependencies | Request user to specify framework |
-
-## Fallback Strategy (No MCP)
-
-```bash
-# File discovery
-find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules
-
-# Framework detection
-grep -r "jest\|mocha\|pytest" package.json requirements.txt 2>/dev/null
-
-# Coverage analysis
-for impl_file in $(cat changed_files.txt); do
-  test_file=$(echo $impl_file | sed 's/src/tests/' | sed 's/\(.*\)\.\(ts\|js\|py\)$/\1.test.\2/')
-  [ ! -f "$test_file" ] && echo "$impl_file → MISSING TEST"
-done
-```
+| Agent execution timeout | Large codebase or slow analysis | Increase timeout, check file access |
+| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
+| No test framework detected | Missing test dependencies | Agent marks as 'unknown', manual specification needed |
 
 ## Integration
 
@@ -288,20 +190,18 @@ done
 - `/workflow:test-gen` (Phase 3: Context Gathering)
 
 ### Calls
-- MCP code-index tools for analysis
-- Bash file operations for fallback
+- `test-context-search-agent` - Autonomous test coverage analysis
 
 ### Followed By
-- `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis and planning
 
-## Success Criteria
+## Notes
 
-- ✅ Source session context loaded successfully
-- ✅ Test coverage gaps identified with MCP tools
-- ✅ Test framework detected and documented
-- ✅ Valid test-context-package.json generated
-- ✅ All missing tests catalogued with priority
-- ✅ Execution time < 20 seconds
+- **Detection-first**: Always check for existing test-context-package before invoking agent
+- **Agent autonomy**: Agent handles all coverage analysis logic per `.claude/agents/test-context-search-agent.md`
+- **No redundancy**: This command is a thin orchestrator, all logic in agent
+- **Framework agnostic**: Supports Jest, Mocha, pytest, RSpec, Go testing, etc.
+- **Coverage focus**: Primary goal is identifying implementation files without tests
 
 ## Related Commands
 

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

@@ -1,11 +1,12 @@
 ---
 name: test-task-generate
 description: Generate test-fix task JSON with iterative test-fix-retest cycle specification
-usage: /workflow:tools:test-task-generate [--use-codex] --session <test-session-id>
-argument-hint: "[--use-codex] --session WFS-test-session-id"
+argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
 examples:
   - /workflow:tools:test-task-generate --session WFS-test-auth
   - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+  - /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
+  - /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ---
 
 # Test Task Generation Command
@@ -13,6 +14,16 @@ examples:
 ## Overview
 Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle specification, including Gemini diagnosis (using bug-fix template) and manual fix workflow (Codex automation only when explicitly requested).
 
+## Execution Modes
+
+### Test Generation (IMPL-001)
+- **Agent Mode (Default)**: @code-developer generates tests within agent context
+- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
+
+### Test Fix (IMPL-002)
+- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
+- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
+
 ## Core Philosophy
 - **Analysis-Driven Test Generation**: Use TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
 - **Agent-Based Test Creation**: Call @code-developer agent for comprehensive test generation
@@ -38,8 +49,9 @@ Generate specialized test-fix task JSON with comprehensive test-fix-retest cycle
 ### Phase 1: Input Validation & Discovery
 
 1. **Parameter Parsing**
-   - Parse `--use-codex` flag from command arguments
-   - Store flag value for IMPL-002.json generation
+   - Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
+   - Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
+   - Store flag values for task JSON generation
 
 2. **Test Session Validation**
    - Load `.workflow/{test-session-id}/workflow-session.json`
@@ -134,40 +146,62 @@ Generate **TWO task JSON files**:
         "step": "load_existing_test_patterns",
         "action": "Study existing tests for pattern reference",
         "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "bash(find . -name \"*.test.*\" -type f)",
           "bash(# Read first 2 existing test files as examples)",
-          "bash(test_files=$(mcp__code-index__find_files(pattern=\"*.test.*\") | head -2))",
+          "bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
           "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
         ],
         "output_to": "existing_test_patterns",
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
-      "generation_steps": [
-        "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
-        "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
-        "Study existing test patterns from test_context.test_framework.conventions",
-        "For each test file in section 5 (Implementation Targets):",
-        "  - Create test file with specified scenarios",
-        "  - Implement happy path tests",
-        "  - Implement error handling tests",
-        "  - Implement edge case tests",
-        "  - Implement integration tests (if specified)",
-        "  - Add required mocks and fixtures",
-        "Follow test framework conventions and project standards",
-        "Ensure all tests are executable and syntactically valid"
+    // Agent Mode (Default): Agent implements tests
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Generate comprehensive test suite",
+        "description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
+        "modification_points": [
+          "Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
+          "Study existing test patterns",
+          "Create test files with all required scenarios",
+          "Implement happy path, error handling, edge case, and integration tests",
+          "Add required mocks and fixtures"
+        ],
+        "logic_flow": [
+          "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
+          "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
+          "Study existing test patterns from test_context.test_framework.conventions",
+          "For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
+          "Follow test framework conventions and project standards",
+          "Ensure all tests are executable and syntactically valid"
+        ],
+        "depends_on": [],
+        "output": "test_suite"
+      }
+    ],
+
+    // CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
+    "implementation_approach": [{
+      "step": 1,
+      "title": "Generate tests using Codex",
+      "description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
+      "modification_points": [
+        "Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
+        "Codex generates all test files listed in analysis section 5",
+        "Codex ensures tests follow framework conventions"
       ],
-      "quality_criteria": [
-        "All test scenarios from analysis are implemented",
-        "Test structure matches existing patterns",
-        "Clear test descriptions and assertions",
-        "Proper setup/teardown and fixtures",
-        "Dependencies properly mocked",
-        "Tests follow project coding standards"
-      ]
-    },
+      "logic_flow": [
+        "Start new Codex session",
+        "Pass TEST_ANALYSIS_RESULTS.md to Codex",
+        "Codex studies existing test patterns",
+        "Codex generates comprehensive test suite",
+        "Codex validates test syntax and executability"
+      ],
+      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
+      "depends_on": [],
+      "output": "test_generation"
+    }],
     "target_files": [
       "{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
       "{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
@@ -248,11 +282,11 @@ Generate **TWO task JSON files**:
         "step": "analyze_test_coverage",
         "action": "Analyze test coverage and identify missing tests",
         "commands": [
-          "mcp__code-index__find_files(pattern=\"*.test.*\")",
-          "mcp__code-index__search_code_advanced(pattern=\"test|describe|it|def test_\", file_pattern=\"*.test.*\")",
+          "bash(find . -name \"*.test.*\" -type f)",
+          "bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
           "bash(# Count implementation files vs test files)",
           "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
-          "bash(test_count=$(mcp__code-index__find_files(pattern=\"*.test.*\") | wc -l))",
+          "bash(test_count=$(find . -name \"*.test.*\" -type f | wc -l))",
           "bash(echo \"Implementation files: $impl_count, Test files: $test_count\")"
         ],
         "output_to": "test_coverage_analysis",
@@ -279,24 +313,27 @@ Generate **TWO task JSON files**:
         "on_error": "skip_optional"
       }
     ],
-    "implementation_approach": {
-      "task_description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if explicitly needed)",
-      "test_fix_cycle": {
-        "max_iterations": 5,
-        "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
-        "tools": {
-          "test_execution": "bash(test_command)",
-          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
-          "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
-          "verification": "bash(test_command) + regression_check"
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Execute iterative test-fix-retest cycle",
+        "description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
+        "test_fix_cycle": {
+          "max_iterations": 5,
+          "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
+          "tools": {
+            "test_execution": "bash(test_command)",
+            "diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
+            "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
+            "verification": "bash(test_command) + regression_check"
+          },
+          "exit_conditions": {
+            "success": "all_tests_pass",
+            "failure": "max_iterations_reached",
+            "error": "test_command_not_found"
+          }
         },
-        "exit_conditions": {
-          "success": "all_tests_pass",
-          "failure": "max_iterations_reached",
-          "error": "test_command_not_found"
-        }
-      },
-      "modification_points": [
+        "modification_points": [
         "PHASE 1: Initial Test Execution",
         "  1.1. Discover test command from framework detection",
         "  1.2. Execute initial test run: bash([test_command])",
@@ -317,16 +354,16 @@ Generate **TWO task JSON files**:
         "      * Source files from focus_paths",
         "      * Implementation summaries from source session",
         "    - Execute Gemini analysis with bug-fix template:",
-        "      bash(cd .workflow/WFS-test-[session]/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+        "      bash(cd .workflow/WFS-test-[session]/.process && gemini \"",
         "      PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
         "      TASK: Systematic bug analysis and fix recommendations for test failure",
         "      MODE: analysis",
-        "      CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
+        "      CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
         "               Test output: [test_failures]",
         "               Source files: [focus_paths]",
         "               Implementation: [implementation_context]",
         "      EXPECTED: Root cause analysis, code path tracing, targeted fixes",
-        "      RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
+        "      RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/bug-diagnosis.txt) | Bug: [test_failure_description]",
         "             Minimal surgical fixes only - no refactoring",
         "      \" > fix-iteration-[N]-diagnosis.md)",
         "    - Parse diagnosis → extract fix_suggestion and target_files",
@@ -428,33 +465,36 @@ Generate **TWO task JSON files**:
         "  Generate summary (include test generation info)",
         "  Certify code APPROVED"
       ],
-      "error_handling": {
-        "max_iterations_reached": {
-          "action": "revert_all_changes",
-          "commands": [
-            "bash(git reset --hard HEAD)",
-            "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
-          ],
-          "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
+        "error_handling": {
+          "max_iterations_reached": {
+            "action": "revert_all_changes",
+            "commands": [
+              "bash(git reset --hard HEAD)",
+              "bash(jq '.status = \"blocked\"' .workflow/[session]/.task/IMPL-001.json > temp.json && mv temp.json .workflow/[session]/.task/IMPL-001.json)"
+            ],
+            "report": "Generate failure report with iteration logs in .summaries/IMPL-001-failure-report.md"
+          },
+          "test_command_fails": {
+            "action": "treat_as_test_failure",
+            "context": "Use stderr as failure context for Gemini diagnosis"
+          },
+          "codex_apply_fails": {
+            "action": "retry_once_then_skip",
+            "fallback": "Mark iteration as skipped, continue to next"
+          },
+          "gemini_diagnosis_fails": {
+            "action": "retry_with_simplified_context",
+            "fallback": "Use previous diagnosis, continue"
+          },
+          "regression_detected": {
+            "action": "log_warning_continue",
+            "context": "Include regression info in next Gemini diagnosis"
+          }
         },
-        "test_command_fails": {
-          "action": "treat_as_test_failure",
-          "context": "Use stderr as failure context for Gemini diagnosis"
-        },
-        "codex_apply_fails": {
-          "action": "retry_once_then_skip",
-          "fallback": "Mark iteration as skipped, continue to next"
-        },
-        "gemini_diagnosis_fails": {
-          "action": "retry_with_simplified_context",
-          "fallback": "Use previous diagnosis, continue"
-        },
-        "regression_detected": {
-          "action": "log_warning_continue",
-          "context": "Include regression info in next Gemini diagnosis"
-        }
+        "depends_on": [],
+        "output": "test_fix_results"
       }
-    },
+    ],
     "target_files": [
       "Auto-discovered from test failures",
       "Extracted from Gemini diagnosis each iteration",
@@ -650,6 +690,6 @@ The `@test-fix-agent` will execute the task by following the `flow_control.imple
 6. **Phase 3**: Generate summary and certify code
 7. **Error Recovery**: Revert changes if max iterations reached
 
-**Bug Diagnosis Template**: Uses bug-fix.md template as referenced in bug-index.md for systematic root cause analysis, code path tracing, and targeted fix recommendations.
+**Bug Diagnosis Template**: Uses `~/.claude/workflows/cli-templates/prompts/development/bug-diagnosis.txt` template for systematic root cause analysis, code path tracing, and targeted fix recommendations.
 
 **Codex Usage**: The agent uses `codex exec "..." resume --last` pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.

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

@@ -0,0 +1,677 @@
+---
+name: animation-extract
+description: Extract animation and transition patterns from URLs, CSS, or interactive questioning
+argument-hint: "[--base-path <path>] [--session <id>] [--urls "<list>"] [--mode <auto|interactive>] [--focus "<types>"]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+---
+
+# Animation Extraction Command
+
+## Overview
+
+Extract animation and transition patterns from web pages using CSS extraction, visual analysis, or interactive questioning. This command generates production-ready animation tokens and guidelines that integrate with design systems.
+
+**Strategy**: Hybrid Extraction with Interactive Fallback
+
+- **Auto Mode (Priority 1)**: Extract from CSS via Chrome DevTools when URLs provided
+- **Visual Mode (Priority 2)**: Analyze screenshots for motion cues (blur, position changes)
+- **Interactive Mode (Priority 3)**: Guided questioning when extraction insufficient
+- **Output**: `animation-tokens.json` + `animation-guide.md`
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input Mode & Base Path
+
+```bash
+# Detect input source
+# Priority: --urls → url mode | --mode interactive → question mode
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+    primary_url = url_list[0].url
+ELSE:
+    has_urls = false
+
+# Determine extraction mode
+extraction_mode = --mode OR (has_urls ? "auto" : "interactive")
+
+# Parse animation focus (if provided)
+IF --focus:
+    focus_types = split(--focus, ",")  # e.g., "transitions,hover,scroll"
+ELSE:
+    focus_types = ["all"]  # Extract all animation types
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Design Tokens Context
+
+```bash
+# Load existing design tokens for duration/easing alignment
+IF exists({base_path}/style-extraction/style-1/design-tokens.json):
+    design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
+    has_design_context = true
+ELSE:
+    has_design_context = false
+    WARN: "⚠️ No design tokens found - animation tokens will use standalone values"
+
+# Create output directory
+bash(mkdir -p {base_path}/animation-extraction)
+bash(mkdir -p {base_path}/.intermediates/animation-analysis)
+```
+
+---
+
+**Phase 0 Output**: `extraction_mode`, `base_path`, `has_urls`, `url_list[]`, `focus_types[]`, `has_design_context`
+
+## Phase 1: CSS Animation Extraction (Auto Mode - URL Required)
+
+### Step 1: Check Extraction Mode
+
+```bash
+# extraction_mode == "interactive" → skip to Phase 2
+# extraction_mode == "auto" AND has_urls → execute this phase
+```
+
+**If interactive mode**: Skip to Phase 2
+
+### Step 2: Extract Computed Animations (Auto-Trigger)
+
+```bash
+# AUTO-TRIGGER: If URLs are available, automatically extract CSS animations/transitions
+
+IF has_urls AND mcp_chrome_devtools_available:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting CSS animations and transitions"
+
+    # Read extraction script
+    script_content = Read(~/.claude/scripts/extract-animations.js)
+
+    # For each URL:
+    FOR url_info IN url_list:
+        target = url_info.target
+        url = url_info.url
+
+        REPORT: "   Processing: {target} ({url})"
+
+        # Open page in Chrome DevTools
+        mcp__chrome-devtools__navigate_page(url=url)
+
+        # Wait for page to fully load and animations to initialize
+        bash(sleep 2)
+
+        # Execute extraction script
+        result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+        # Save raw animation data
+        Write({base_path}/.intermediates/animation-analysis/animations-{target}.json, result)
+
+        REPORT: "   ✅ Extracted: {result.summary.total_animations} animations, {result.summary.total_transitions} transitions"
+
+    animations_extracted = true
+    REPORT: "   ✅ CSS animation extraction complete"
+ELSE IF has_urls AND NOT mcp_chrome_devtools_available:
+    animations_extracted = false
+    REPORT: "⚠️ Chrome DevTools MCP not available"
+    REPORT: "   Falling back to interactive mode for animation guidance"
+ELSE:
+    animations_extracted = false
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-animations.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `transitions`: Array of transition definitions (property, duration, easing, delay)
+- `animations`: Array of keyframe animations (name, duration, easing, keyframes)
+- `transforms`: Common transform patterns
+- `summary`: Statistics (total_animations, total_transitions, unique_easings)
+
+**Benefits**:
+- ✅ Real animation values from production sites
+- ✅ Captures all CSS transitions and @keyframes rules
+- ✅ Identifies common easing functions and durations
+- ✅ Maps animations to element selectors
+
+---
+
+**Phase 1 Output**: `animations-{target}.json` (intermediate files)
+
+## Phase 2: Interactive Animation Specification (Interactive/Fallback Mode)
+
+### Step 1: Check if Extraction Sufficient
+
+```bash
+# If animations extracted from CSS, check coverage
+IF animations_extracted:
+    total_animations = sum([data.summary.total_animations for data in all_extracted])
+    total_transitions = sum([data.summary.total_transitions for data in all_extracted])
+
+    # If sufficient data found, skip interactive mode
+    IF total_animations >= 3 OR total_transitions >= 5:
+        REPORT: "✅ Sufficient animation data extracted from CSS"
+        SKIP to Phase 3
+    ELSE:
+        REPORT: "⚠️ Limited animation data found - launching interactive mode"
+        extraction_insufficient = true
+ELSE:
+    extraction_insufficient = true
+```
+
+### Step 2: Interactive Question Workflow (Agent)
+
+```bash
+# If extraction failed or insufficient, use interactive questioning
+IF extraction_insufficient OR extraction_mode == "interactive":
+    REPORT: "🤔 Launching interactive animation specification mode"
+
+    # Launch ui-design-agent for interactive questioning
+    Task(ui-design-agent): `
+      [ANIMATION_SPECIFICATION_TASK]
+      Guide user through animation design decisions via structured questions
+
+      SESSION: {session_id} | MODE: interactive | BASE_PATH: {base_path}
+
+      ## Context
+      - Design tokens available: {has_design_context}
+      - Focus areas: {focus_types}
+      - Extracted data: {animations_extracted ? "Partial CSS data available" : "No CSS data"}
+
+      ## Interactive Workflow
+
+      For each animation category, ASK user and WAIT for response:
+
+      ### 1. Transition Duration Scale
+      QUESTION: "What timing scale feels right for your design?"
+      OPTIONS:
+        - "Fast & Snappy" (100-200ms transitions)
+        - "Balanced" (200-400ms transitions)
+        - "Smooth & Deliberate" (400-600ms transitions)
+        - "Custom" (specify values)
+
+      ### 2. Easing Philosophy
+      QUESTION: "What easing style matches your brand?"
+      OPTIONS:
+        - "Linear" (constant speed, technical feel)
+        - "Ease-Out" (fast start, natural feel)
+        - "Ease-In-Out" (balanced, polished feel)
+        - "Spring/Bounce" (playful, modern feel)
+        - "Custom" (specify cubic-bezier)
+
+      ### 3. Common Interactions (Ask for each)
+      FOR interaction IN ["button-hover", "link-hover", "card-hover", "modal-open", "dropdown-toggle"]:
+        QUESTION: "How should {interaction} animate?"
+        OPTIONS:
+          - "Subtle" (color/opacity change only)
+          - "Lift" (scale + shadow increase)
+          - "Slide" (transform translateY)
+          - "Fade" (opacity transition)
+          - "None" (no animation)
+          - "Custom" (describe behavior)
+
+      ### 4. Page Transitions
+      QUESTION: "Should page/route changes have animations?"
+      IF YES:
+        ASK: "What style?"
+        OPTIONS:
+          - "Fade" (crossfade between views)
+          - "Slide" (swipe left/right)
+          - "Zoom" (scale in/out)
+          - "None"
+
+      ### 5. Loading States
+      QUESTION: "What loading animation style?"
+      OPTIONS:
+        - "Spinner" (rotating circle)
+        - "Pulse" (opacity pulse)
+        - "Skeleton" (shimmer effect)
+        - "Progress Bar" (linear fill)
+        - "Custom" (describe)
+
+      ### 6. Micro-interactions
+      QUESTION: "Should form inputs have micro-interactions?"
+      IF YES:
+        ASK: "What interactions?"
+        OPTIONS:
+          - "Focus state animation" (border/shadow transition)
+          - "Error shake" (horizontal shake on error)
+          - "Success check" (checkmark animation)
+          - "All of the above"
+
+      ### 7. Scroll Animations
+      QUESTION: "Should elements animate on scroll?"
+      IF YES:
+        ASK: "What scroll animation style?"
+        OPTIONS:
+          - "Fade In" (opacity 0→1)
+          - "Slide Up" (translateY + fade)
+          - "Scale In" (scale 0.9→1 + fade)
+          - "Stagger" (sequential delays)
+          - "None"
+
+      ## Output Generation
+
+      Based on user responses, generate structured data:
+
+      1. Create animation-specification.json with user choices:
+         - timing_scale (fast/balanced/slow/custom)
+         - easing_philosophy (linear/ease-out/ease-in-out/spring)
+         - interactions: {interaction_name: {type, properties, timing}}
+         - page_transitions: {enabled, style, duration}
+         - loading_animations: {style, duration}
+         - scroll_animations: {enabled, style, stagger_delay}
+
+      2. Write to {base_path}/.intermediates/animation-analysis/animation-specification.json
+
+      ## Critical Requirements
+      - ✅ Use Write() tool immediately for specification file
+      - ✅ Wait for user response after EACH question before proceeding
+      - ✅ Validate responses and ask for clarification if needed
+      - ✅ Provide sensible defaults if user skips questions
+      - ❌ NO external research or MCP calls
+    `
+```
+
+---
+
+**Phase 2 Output**: `animation-specification.json` (user preferences)
+
+## Phase 3: Animation Token Synthesis (Agent)
+
+**Executor**: `Task(ui-design-agent)` for token generation
+
+### Step 1: Load All Input Sources
+
+```bash
+# Gather all available animation data
+extracted_animations = []
+IF animations_extracted:
+    FOR target IN target_list:
+        IF exists({base_path}/.intermediates/animation-analysis/animations-{target}.json):
+            extracted_animations.append(Read(file))
+
+user_specification = null
+IF exists({base_path}/.intermediates/animation-analysis/animation-specification.json):
+    user_specification = Read(file)
+
+design_tokens = null
+IF has_design_context:
+    design_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
+```
+
+### Step 2: Launch Token Generation Task
+
+```javascript
+Task(ui-design-agent): `
+  [ANIMATION_TOKEN_GENERATION_TASK]
+  Synthesize all animation data into production-ready animation tokens
+
+  SESSION: {session_id} | BASE_PATH: {base_path}
+
+  ## Input Sources
+  1. Extracted CSS Animations: {JSON.stringify(extracted_animations) OR "None"}
+  2. User Specification: {JSON.stringify(user_specification) OR "None"}
+  3. Design Tokens Context: {JSON.stringify(design_tokens) OR "None"}
+
+  ## Synthesis Rules
+
+  ### Priority System
+  1. User specification (highest priority)
+  2. Extracted CSS values (medium priority)
+  3. Industry best practices (fallback)
+
+  ### Duration Normalization
+  - Analyze all extracted durations
+  - Cluster into 3-5 semantic scales: instant, fast, normal, slow, very-slow
+  - Align with design token spacing scale if available
+
+  ### Easing Standardization
+  - Identify common easing functions from extracted data
+  - Map to semantic names: linear, ease-in, ease-out, ease-in-out, spring
+  - Convert all cubic-bezier values to standard format
+
+  ### Animation Categorization
+  Organize into:
+  - transitions: Property-specific transitions (color, transform, opacity)
+  - keyframe_animations: Named @keyframe animations
+  - interactions: Interaction-specific presets (hover, focus, active)
+  - micro_interactions: Small feedback animations
+  - page_transitions: Route/view change animations
+  - scroll_animations: Scroll-triggered animations
+
+  ## Generate Files
+
+  ### 1. animation-tokens.json
+  Complete animation token structure:
+
+  {
+    "duration": {
+      "instant": "0ms",
+      "fast": "150ms",
+      "normal": "300ms",
+      "slow": "500ms",
+      "very-slow": "800ms"
+    },
+    "easing": {
+      "linear": "linear",
+      "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+      "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+      "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+      "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+    },
+    "transitions": {
+      "color": {
+        "property": "color, background-color, border-color",
+        "duration": "var(--duration-fast)",
+        "easing": "var(--easing-ease-out)"
+      },
+      "transform": {
+        "property": "transform",
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-out)"
+      },
+      "opacity": {
+        "property": "opacity",
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-in-out)"
+      }
+    },
+    "keyframes": {
+      "fadeIn": {
+        "0%": {"opacity": "0"},
+        "100%": {"opacity": "1"}
+      },
+      "slideInUp": {
+        "0%": {"transform": "translateY(20px)", "opacity": "0"},
+        "100%": {"transform": "translateY(0)", "opacity": "1"}
+      },
+      "pulse": {
+        "0%, 100%": {"opacity": "1"},
+        "50%": {"opacity": "0.7"}
+      }
+    },
+    "interactions": {
+      "button-hover": {
+        "properties": ["background-color", "transform"],
+        "duration": "var(--duration-fast)",
+        "easing": "var(--easing-ease-out)",
+        "transform": "scale(1.02)"
+      },
+      "card-hover": {
+        "properties": ["box-shadow", "transform"],
+        "duration": "var(--duration-normal)",
+        "easing": "var(--easing-ease-out)",
+        "transform": "translateY(-4px)"
+      }
+    },
+    "page_transitions": {
+      "fade": {
+        "duration": "var(--duration-normal)",
+        "enter": "fadeIn",
+        "exit": "fadeOut"
+      }
+    },
+    "scroll_animations": {
+      "default": {
+        "animation": "fadeInUp",
+        "duration": "var(--duration-slow)",
+        "easing": "var(--easing-ease-out)",
+        "threshold": "0.1",
+        "stagger_delay": "100ms"
+      }
+    }
+  }
+
+  ### 2. animation-guide.md
+  Comprehensive usage guide:
+  - Animation philosophy and rationale
+  - Duration scale explanation
+  - Easing function usage guidelines
+  - Interaction animation patterns
+  - Implementation examples (CSS and JS)
+  - Accessibility considerations (prefers-reduced-motion)
+  - Performance best practices
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for both files
+  - ✅ Ensure all tokens use CSS Custom Property format: var(--duration-fast)
+  - ✅ Include prefers-reduced-motion media query guidance
+  - ✅ Validate all cubic-bezier values are valid
+  - ❌ NO external research or MCP calls
+`
+```
+
+---
+
+**Phase 3 Output**: `animation-tokens.json` + `animation-guide.md`
+
+## Phase 4: Verify Output
+
+### Step 1: Check Files Created
+
+```bash
+# Verify animation tokens created
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+bash(test -f {base_path}/animation-extraction/animation-guide.md && echo "exists")
+
+# Validate structure
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "easing" && echo "valid")
+```
+
+### Step 2: Verify File Sizes
+
+```bash
+bash(ls -lh {base_path}/animation-extraction/)
+```
+
+**Output**: 2 files verified (animation-tokens.json, animation-guide.md)
+
+## Completion
+
+### Todo Update
+
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "CSS animation extraction (auto mode)", status: "completed", activeForm: "Extracting from CSS"},
+  {content: "Interactive specification (fallback)", status: "completed", activeForm: "Collecting user input"},
+  {content: "Animation token synthesis (agent)", status: "completed", activeForm: "Generating tokens"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+### Output Message
+
+```
+✅ Animation extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (auto/interactive)
+- Input Sources:
+  {IF animations_extracted:
+  - ✅ CSS extracted from {len(url_list)} URL(s)
+  }
+  {IF user_specification:
+  - ✅ User specification via interactive mode
+  }
+  {IF has_design_context:
+  - ✅ Aligned with existing design tokens
+  }
+
+Generated Files:
+{base_path}/animation-extraction/
+├── animation-tokens.json      # Production-ready animation tokens
+└── animation-guide.md          # Usage guidelines and examples
+
+{IF animations_extracted:
+Intermediate Analysis:
+{base_path}/.intermediates/animation-analysis/
+├── animations-*.json           # Extracted CSS data ({len(url_list)} files)
+}
+{IF user_specification:
+└── animation-specification.json # User preferences
+}
+
+Extracted Data Summary:
+- Duration scales: {duration_count} values
+- Easing functions: {easing_count} types
+- Interaction presets: {interaction_count} patterns
+- Keyframe animations: {keyframe_count} animations
+
+Next: Animation tokens ready for integration
+  • style-extract/layout-extract can reference animation tokens
+  • generate command will include animation CSS
+  • Tokens use var() format for easy customization
+```
+
+## Simple Bash Commands
+
+### Path Operations
+
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create output directories
+bash(mkdir -p {base_path}/animation-extraction)
+bash(mkdir -p {base_path}/.intermediates/animation-analysis)
+```
+
+### Validation Commands
+
+```bash
+# Check if already extracted
+bash(test -f {base_path}/animation-extraction/animation-tokens.json && echo "exists")
+
+# Validate JSON structure
+bash(cat {base_path}/animation-extraction/animation-tokens.json | grep -q "duration" && echo "valid")
+
+# Count animation types
+bash(cat animation-tokens.json | grep -c "\"keyframes\":")
+```
+
+### File Operations
+
+```bash
+# Load design tokens context
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && cat it)
+
+# Verify output
+bash(ls {base_path}/animation-extraction/)
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                  # Intermediate analysis files
+│   └── animation-analysis/
+│       ├── animations-{target}.json      # Extracted CSS (auto mode)
+│       └── animation-specification.json  # User input (interactive mode)
+└── animation-extraction/            # Final animation tokens
+    ├── animation-tokens.json        # Production-ready animation tokens
+    └── animation-guide.md            # Usage guide and examples
+```
+
+## animation-tokens.json Format
+
+```json
+{
+  "duration": {
+    "instant": "0ms",
+    "fast": "150ms",
+    "normal": "300ms",
+    "slow": "500ms",
+    "very-slow": "800ms"
+  },
+  "easing": {
+    "linear": "linear",
+    "ease-in": "cubic-bezier(0.4, 0, 1, 1)",
+    "ease-out": "cubic-bezier(0, 0, 0.2, 1)",
+    "ease-in-out": "cubic-bezier(0.4, 0, 0.2, 1)",
+    "spring": "cubic-bezier(0.34, 1.56, 0.64, 1)"
+  },
+  "transitions": {
+    "color": {"property": "...", "duration": "var(--duration-fast)", "easing": "..."},
+    "transform": {"property": "...", "duration": "...", "easing": "..."}
+  },
+  "keyframes": {
+    "fadeIn": {"0%": {...}, "100%": {...}},
+    "slideInUp": {...}
+  },
+  "interactions": {
+    "button-hover": {"properties": [...], "duration": "...", "transform": "..."},
+    "card-hover": {...}
+  },
+  "page_transitions": {...},
+  "scroll_animations": {...}
+}
+```
+
+**Requirements**: CSS var() format, valid cubic-bezier values, prefers-reduced-motion support
+
+## Error Handling
+
+### Common Errors
+
+```
+ERROR: No URL or interactive mode specified
+→ Provide --urls for auto mode or use --mode interactive
+
+ERROR: Chrome DevTools unavailable
+→ Automatically falls back to interactive mode
+
+ERROR: Insufficient animation data extracted
+→ Launches interactive mode for supplemental input
+
+ERROR: Invalid cubic-bezier values
+→ Validates and corrects to nearest standard easing
+```
+
+### Recovery Strategies
+
+- **CSS extraction failure**: Falls back to interactive mode
+- **Partial extraction**: Supplements with interactive questioning
+- **Invalid data**: Validates and uses fallback values
+
+## Key Features
+
+- **Auto-Trigger CSS Extraction** - Automatically extracts animations when --urls provided
+- **Hybrid Strategy** - Combines CSS extraction with interactive specification
+- **Intelligent Fallback** - Gracefully handles extraction failures
+- **Context-Aware** - Aligns with existing design tokens
+- **Production-Ready** - CSS var() format, accessibility support
+- **Comprehensive Coverage** - Transitions, keyframes, interactions, scroll animations
+- **Agent-Driven** - Autonomous token generation with ui-design-agent
+
+## Integration
+
+**Workflow Position**: Between style extraction and layout extraction (or parallel)
+
+**New Workflow**:
+1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
+2. **`/workflow:ui-design:animation-extract`** → `animation-tokens.json` + `animation-guide.md` (NEW)
+3. `/workflow:ui-design:layout-extract` → `layout-templates.json`
+4. `/workflow:ui-design:generate`:
+   - Reads: design-tokens.json + animation-tokens.json + layout-templates.json
+   - Generates: Prototypes with animation CSS included
+
+**Input**: URLs (auto mode) or interactive questioning
+**Output**: `animation-tokens.json` + `animation-guide.md`
+**Next**: `/workflow:ui-design:layout-extract` OR `/workflow:ui-design:generate`
+
+**Note**: This command extracts motion design patterns (animations, transitions) to complement visual style tokens. Can run in parallel with layout-extract.

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

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

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

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

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

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

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

@@ -1,16 +1,7 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow - Generate and compare multiple style × layout combinations (3×3 matrix exploration)
-usage: /workflow:ui-design:explore-auto [--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]
-argument-hint: "[--prompt \"Modern SaaS with 3 styles\"] [--images \"refs/*.png\"] [--targets \"dashboard,auth,navbar,hero\"] [--target-type \"auto\"] [--session WFS-xxx] [--style-variants 3] [--layout-variants 3]"
-examples:
-  - /workflow:ui-design:explore-auto --prompt "Generate 3 style variants for modern blog: home, article, author"
-  - /workflow:ui-design:explore-auto --prompt "SaaS dashboard and settings with 2 layout options"
-  - /workflow:ui-design:explore-auto --images "refs/*.png" --prompt "E-commerce: home, product, cart" --style-variants 3 --layout-variants 3
-  - /workflow:ui-design:explore-auto --session WFS-auth --images "refs/*.png"
-  - /workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --prompt "Compare 3 navigation bar designs" --style-variants 3 --layout-variants 2
-  - /workflow:ui-design:explore-auto --targets "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
-  - /workflow:ui-design:explore-auto --targets "home,dashboard" --target-type "page"
+description: Exploratory UI design workflow with style-centric batch generation
+argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 
@@ -25,15 +16,23 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 - **Components** (isolated UI elements): navbar, card, hero, form, etc.
 - **Mixed**: Can combine both in a single workflow
 
-**Autonomous Flow**:
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 1. User triggers: `/workflow:ui-design:explore-auto [params]`
-2. Phase 1 (style-extract) → Auto-continues
-3. Phase 2 (style-consolidate) → Auto-continues
-4. Phase 3 (ui-generate) → Auto-continues with unified target list
-5. Phase 4 (design-update) → Auto-continues
-6. Phase 5 (batch-plan, optional) → Reports completion
+2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
+3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
+4. Phase 2.3 (animation-extract, optional) → **WAIT for completion** → Auto-continues
+5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
+6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
+7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
+8. Phase 5 (batch-plan, optional) → Reports completion
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon completion, coordinator constructs next command and executes immediately. No user intervention required.
+**Phase Transition Mechanism**:
+- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
+- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
+- Upon each phase completion: Automatically process output and execute next phase
+- No additional user interaction after Phase 0c confirmation
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
 
 **Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
 
@@ -44,12 +43,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 3. **Parse & Pass**: Extract data from each output for next phase
 4. **Default to All**: When selecting variants/prototypes, use ALL generated items
 5. **Track Progress**: Update TodoWrite after each phase
+6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
 
 ## Parameter Requirements
 
 **Optional Parameters** (all have smart defaults):
 - `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
 - `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
+- `--device-type "desktop|mobile|tablet|responsive|auto"`: Device type for layout optimization (default: `auto` - intelligent detection)
+  - **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+  - **Mobile**: 375×812px - Touch-friendly, compact layouts
+  - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+  - **Responsive**: 1920×1080px base with mobile-first breakpoints
 - `--session <id>`: Workflow session ID (standalone mode if omitted)
 - `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
 - `--prompt "<description>"`: Design style and target description
@@ -84,14 +89,18 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 ## Execution Modes
 
-**Matrix Mode** (unified):
+**Matrix Mode** (style-centric):
 - Generates `style_variants × layout_variants × targets` prototypes
-- **Phase 1**: `style_variants` style options
-- **Phase 2**: `style_variants` independent design systems
-- **Phase 3**: `style_variants × layout_variants × targets` prototypes
+- **Phase 1**: `style_variants` complete design systems (extract)
+- **Phase 2**: Layout templates extraction (layout-extract)
+- **Phase 3**: Style-centric batch generation (generate)
+  - Sub-phase 1: `targets × layout_variants` target-specific layout plans
+  - **Sub-phase 2**: `S` style-centric agents (each handles `L×T` combinations)
+  - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - Performance: Efficient parallel execution with S agents
+  - Quality: HTML structure adapts to design_attributes
   - Pages: Full-page layouts with complete structure
   - Components: Isolated elements with minimal wrapper
-  - Mixed: Combination based on intelligent detection
 
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
@@ -100,527 +109,386 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 ### Phase 0a: Intelligent Prompt Parsing
 ```bash
-# Extract variant counts from prompt if not explicitly provided
-IF --prompt provided AND (NOT --style-variants OR NOT --layout-variants):
-    # Parse: "3 style variants", "4 styles", "2 layout options", "3 layouts each"
-    style_match = regex_search(prompt_text, r"(\d+)\s*(style\s*variants?|styles?)")
-    layout_match = regex_search(prompt_text, r"(\d+)\s*(layout\s*(variants?|options?)|layouts?)")
-
-    style_variants = style_match ? int(match[1]) : (--style-variants OR 3)
-    layout_variants = layout_match ? int(match[1]) : (--layout-variants OR 3)
+# Parse variant counts from prompt or use explicit/default values
+IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
+    style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
+    layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
 ELSE:
     style_variants = --style-variants OR 3
     layout_variants = --layout-variants OR 3
 
 VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
-STORE: style_variants, layout_variants
 ```
 
+### Phase 0a-2: Device Type Inference
+```bash
+# Device type inference
+device_type = "auto"
+
+# Step 1: Explicit parameter (highest priority)
+IF --device-type AND --device-type != "auto":
+    device_type = --device-type
+    device_source = "explicit"
+ELSE:
+    # Step 2: Prompt analysis
+    IF --prompt:
+        device_keywords = {
+            "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
+            "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
+            "tablet": ["tablet", "ipad", "medium screen"],
+            "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
+        }
+        detected_device = detect_device_from_prompt(--prompt, device_keywords)
+        IF detected_device:
+            device_type = detected_device
+            device_source = "prompt_inference"
+
+    # Step 3: Target type inference
+    IF device_type == "auto":
+        # Components are typically desktop-first, pages can vary
+        device_type = target_type == "component" ? "desktop" : "responsive"
+        device_source = "target_type_inference"
+
+STORE: device_type, device_source
+```
+
+**Device Type Presets**:
+- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
+- **Mobile**: 375×812px - Touch-friendly, compact layouts
+- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
+- **Responsive**: 1920×1080px base with mobile-first breakpoints
+
+**Detection Keywords**:
+- Prompt contains "mobile", "phone", "smartphone" → mobile
+- Prompt contains "tablet", "ipad" → tablet
+- Prompt contains "desktop", "web", "laptop" → desktop
+- Prompt contains "responsive", "adaptive" → responsive
+- Otherwise: Inferred from target type (components→desktop, pages→responsive)
+
 ### Phase 0b: Run Initialization & Directory Setup
 ```bash
-# Generate run ID and determine base path
 run_id = "run-$(date +%Y%m%d-%H%M%S)"
+base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
 
-IF --session:
-    base_path = ".workflow/WFS-{session_id}/design-${run_id}"
-ELSE:
-    base_path = ".workflow/.design/${run_id}"
-
-# Create directories
 Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
 
-# Initialize metadata
 Write({base_path}/.run-metadata.json): {
-  "run_id": "${run_id}",
-  "session_id": "${session_id}",
-  "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
   "workflow": "ui-design:auto",
-  "parameters": {
-    "style_variants": ${style_variants},
-    "layout_variants": ${layout_variants},
-    "pages": "${inferred_page_list}",
-    "prompt": "${prompt_text}",
-    "images": "${images_pattern}"
-  },
-  "status": "in_progress"
+  "architecture": "style-centric-batch-generation",
+  "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
+                  "targets": "${inferred_target_list}", "target_type": "${target_type}",
+                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "device_type": "${device_type}", "device_source": "${device_source}" },
+  "status": "in_progress",
+  "performance_mode": "optimized"
 }
-
-STORE: run_id, base_path
 ```
 
 ### Phase 0c: Unified Target Inference with Intelligent Type Detection
 ```bash
-target_list = []
-target_type = "auto"  # auto, page, component
-target_source = "none"
+# Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
+target_list = []; target_type = "auto"; target_source = "none"
 
-# Step 1: Handle legacy parameters (backward compatibility)
-IF --pages provided:
-    target_list = split_and_clean(--pages, delimiters=[",", ";", "、"])
-    target_type = "page"
-    target_source = "explicit_legacy"
-    REPORT: "📋 Using explicitly provided pages (legacy): {', '.join(target_list)}"
-ELSE IF --components provided:
-    target_list = split_and_clean(--components, delimiters=[",", ";", "、"])
-    target_type = "component"
-    target_source = "explicit_legacy"
-    REPORT: "🧩 Using explicitly provided components (legacy): {', '.join(target_list)}"
+# Step 1-2: Explicit parameters (legacy or unified)
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets); target_source = "explicit"
+    target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
 
-# Step 2: Handle unified --targets parameter
-ELSE IF --targets provided:
-    target_list = split_and_clean(--targets, delimiters=[",", ";", "、"])
-    target_source = "explicit"
-
-    # Override type if explicitly set
-    IF --target-type provided AND --target-type != "auto":
-        target_type = --target-type
-        REPORT: "🎯 Using explicitly provided targets with type '{target_type}': {', '.join(target_list)}"
-    ELSE:
-        # Intelligent type detection
-        target_type = detect_target_type(target_list)
-        REPORT: "🎯 Using explicitly provided targets (detected type: {target_type}): {', '.join(target_list)}"
-
-# Step 3: Dynamic prompt analysis
-ELSE IF --prompt provided:
-    REPORT: "🔍 Analyzing prompt to identify targets..."
-
-    # Internal Claude analysis
-    analysis_prompt = """
-    Analyze the UI design request and identify targets (pages or components) with their types.
-
-    Request: "{prompt_text}"
-
-    Output JSON:
-    {
-      "targets": [
-        {"name": "normalized-name", "type": "page|component", "purpose": "description", "priority": "high|medium|low"}
-      ],
-      "primary_type": "page|component|mixed",
-      "shared_elements": ["header", "footer"],
-      "context": "application context description"
-    }
-
-    Rules:
-    - Normalize to URL-friendly (lowercase, hyphens, no spaces)
-    - Detect type: page (full layouts like home, dashboard) vs component (UI elements like navbar, card)
-    - Consolidate synonyms (homepage → home, navigation → navbar)
-    - Common pages: home, dashboard, settings, profile, login, signup
-    - Common components: navbar, header, hero, card, form, button, modal, footer
-    - If prompt mentions "page", "screen", "view" → type: page
-    - If prompt mentions "component", "element", "widget" → type: component
-    """
-
-    target_structure = analyze_prompt_structure(analysis_prompt, prompt_text)
-    target_list = extract_target_names_from_structure(target_structure)
-    target_type = target_structure.primary_type OR detect_target_type(target_list)
+# Step 3: Prompt analysis (Claude internal analysis)
+ELSE IF --prompt:
+    analysis_result = analyze_prompt("{prompt_text}")  # Extract targets, types, purpose
+    target_list = analysis_result.targets
+    target_type = analysis_result.primary_type OR detect_target_type(target_list)
     target_source = "prompt_analysis"
 
-    IF target_list:
-        REPORT: "🎯 Identified targets from prompt (type: {target_type}):"
-        FOR target IN target_structure.targets:
-            icon = "📄" IF target.type == "page" ELSE "🧩"
-            REPORT: "   {icon} {target.name}: {target.purpose} [{target.priority}]"
-        IF target_structure.shared_elements:
-            REPORT: "🔧 Shared elements: {', '.join(shared_elements)}"
+# Step 4: Session synthesis
+ELSE IF --session AND exists(role analysis documents):
+    target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
 
-# Step 4: Extract from synthesis-specification.md (for session mode)
-ELSE IF --session AND exists(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md):
-    synthesis = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-    target_list = extract_targets_from_synthesis(synthesis)  # Returns pages by default
-    target_type = "page"
-    target_source = "synthesis"
-    REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
+# Step 5: Fallback
+IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
 
-# Step 5: Fallback default
-IF NOT target_list:
-    target_list = ["home"]
-    target_type = "page"
-    target_source = "default"
-    REPORT: "⚠️ No targets identified, using default: 'home' (page)"
-
-# Validate and clean target names
-validated_targets = []
-invalid_targets = []
-FOR target IN target_list:
-    cleaned = target.strip().lower().replace(" ", "-")
-    IF regex_match(cleaned, r"^[a-z0-9][a-z0-9_-]*$"):
-        validated_targets.append(cleaned)
-    ELSE:
-        invalid_targets.append(target)
-
-IF invalid_targets:
-    REPORT: "⚠️ Skipped invalid: {', '.join(invalid_targets)}"
-
-IF NOT validated_targets:
-    validated_targets = ["home"]
-    target_type = "page"
-    REPORT: "⚠️ All invalid, using default: 'home'"
-
-# Override target type if explicitly set
-IF --target-type provided AND --target-type != "auto":
-    target_type = --target-type
-    REPORT: "🔧 Target type overridden to: {target_type}"
+# Validate and clean
+validated_targets = [normalize(t) for t in target_list if is_valid(t)]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+IF --target-type != "auto": target_type = --target-type
 
 # Interactive confirmation
-type_emoji = "📄" IF target_type == "page" ELSE ("🧩" IF target_type == "component" ELSE "🎯")
-type_label = "PAGES" IF target_type == "page" ELSE ("COMPONENTS" IF target_type == "component" ELSE "TARGETS")
-
-REPORT: ""
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "{type_emoji} {type_label} CONFIRMATION"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
-REPORT: "Type: {target_type}"
-REPORT: "Source: {target_source}"
-REPORT: "Targets ({len(validated_targets)}): {', '.join(validated_targets)}"
-REPORT: ""
-REPORT: "Options:"
-REPORT: "  • 'continue/yes' - proceed"
-REPORT: "  • 'targets: item1,item2' - replace list"
-REPORT: "  • 'skip: item-name' - remove targets"
-REPORT: "  • 'add: item-name' - add targets"
-REPORT: "  • 'type: page|component' - change type"
-REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets, device_type, device_source):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION (Style-Centric)"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Device: {device_type} | Source: {device_source}"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Performance: {style_variants} agent calls"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "Modification Options:"
+  "  • 'continue/yes/ok' - Proceed with current configuration"
+  "  • 'targets: a,b,c' - Replace target list"
+  "  • 'skip: x,y' - Remove specific targets"
+  "  • 'add: z' - Add new targets"
+  "  • 'type: page|component' - Change target type"
+  "  • 'device: desktop|mobile|tablet|responsive' - Change device type"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
 
 user_input = WAIT_FOR_USER_INPUT()
 
-# Process input
-IF user_input MATCHES r"^(continue|yes|ok|proceed)$":
-    REPORT: "✅ Proceeding with {len(validated_targets)} {target_type}(s): {', '.join(validated_targets)}"
-ELSE IF user_input MATCHES r"^targets:\s*(.+)$":
-    new_targets = split_and_clean(extract_after("targets:"), [",", ";"])
-    validated_targets = [t.strip().lower().replace(" ", "-") for t in new_targets if t.strip()]
-    REPORT: "✅ Updated: {', '.join(validated_targets)}"
-ELSE IF user_input MATCHES r"^skip:\s*(.+)$":
-    to_skip = [t.strip().lower() for t in extract_after("skip:").split(",")]
-    validated_targets = [t for t in validated_targets if t not in to_skip]
-    REPORT: "✅ Removed: {', '.join(to_skip)}, Final: {', '.join(validated_targets)}"
-ELSE IF user_input MATCHES r"^add:\s*(.+)$":
-    to_add = [t.strip().lower().replace(" ", "-") for t in extract_after("add:").split(",") if t.strip()]
-    validated_targets.extend(to_add)
-    validated_targets = list(dict.fromkeys(validated_targets))  # Remove duplicates
-    REPORT: "✅ Added: {', '.join(to_add)}, Final: {', '.join(validated_targets)}"
-ELSE IF user_input MATCHES r"^type:\s*(page|component)$":
-    target_type = extract_after("type:").strip()
-    REPORT: "✅ Type changed to: {target_type}"
-ELSE:
-    REPORT: "⚠️ Invalid input, proceeding with: {', '.join(validated_targets)}"
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  "device: ..." → device_type = extract_device()
+  default → proceed with current list
 
-IF NOT validated_targets:
-    validated_targets = ["home"]
-    target_type = "page"
+STORE: inferred_target_list, target_type, target_inference_source
 
-STORE: inferred_target_list = validated_targets
-STORE: target_type = target_type
-STORE: target_inference_source = target_source
-STORE: target_structure_data = target_structure IF exists(target_structure) ELSE {}
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# This is the only user interaction point in the workflow
+# After this point, all subsequent phases execute automatically without user intervention
 ```
 
 **Helper Function: detect_target_type()**
 ```bash
 detect_target_type(target_list):
-    # Common page keywords
-    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth",
-                     "landing", "about", "contact", "pricing", "account", "admin"]
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
 
-    # Common component keywords
-    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form",
-                          "modal", "alert", "toast", "menu", "sidebar", "breadcrumb", "tabs",
-                          "table", "list", "grid", "carousel", "gallery", "search", "filter"]
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
 
-    page_matches = 0
-    component_matches = 0
-
-    FOR target IN target_list:
-        IF target IN page_keywords:
-            page_matches += 1
-        ELSE IF target IN component_keywords:
-            component_matches += 1
-        ELSE IF contains_keyword(target, ["page", "screen", "view"]):
-            page_matches += 1
-        ELSE IF contains_keyword(target, ["component", "widget", "element"]):
-            component_matches += 1
-
-    # Decision logic
-    IF component_matches > page_matches:
-        RETURN "component"
-    ELSE IF page_matches > 0 OR len(target_list) == 0:
-        RETURN "page"
-    ELSE:
-        # Ambiguous - default to page
-        RETURN "page"
+    RETURN "component" IF component_matches > page_matches ELSE "page"
 ```
 
 ### Phase 1: Style Extraction
-**Command**:
 ```bash
-images_flag = --images present ? "--images \"{image_glob}\"" : ""
-prompt_flag = --prompt present ? "--prompt \"{prompt_text}\"" : ""
-run_base_flag = "--base-path \"{base_path}\""
-
-command = "/workflow:ui-design:extract {run_base_flag} {images_flag} {prompt_flag} --variants {style_variants}"
+command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--mode explore --variants {style_variants}"
 SlashCommand(command)
+
+# Output: {style_variants} style cards with design_attributes
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue)
 ```
-**Auto-Continue**: On completion → Phase 2
 
----
-
-### Phase 2: Style Consolidation (Separate Design Systems)
-**Command**:
+### Phase 2.3: Animation Extraction (Optional - Interactive Mode)
 ```bash
-run_base_flag = "--base-path \"{base_path}\""
+# Animation extraction for motion design patterns
+REPORT: "🚀 Phase 2.3: Animation Extraction (interactive mode)"
+REPORT: "   → Mode: Interactive specification"
+REPORT: "   → Purpose: Define motion design patterns"
+
+command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
 
-# Consolidate generates independent design systems by default
-# IMPORTANT: Pass --layout-variants to ensure correct number of layout strategies are generated
-command = "/workflow:ui-design:consolidate {run_base_flag} --variants {style_variants} --layout-variants {layout_variants}"
 SlashCommand(command)
+
+# Output: animation-tokens.json + animation-guide.md
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
 ```
-**Result**: Generates `style_variants` independent design systems:
-- `style-consolidation/style-1/design-tokens.json`
-- `style-consolidation/style-{N}/design-tokens.json`
 
-**Auto-Continue**: On completion → Phase 3
-
----
-
-### Phase 3: Matrix UI Generation (Unified)
-**Command**:
+### Phase 2.5: Layout Extraction
 ```bash
-run_base_flag = "--base-path \"{base_path}\""
-
-# Build unified targets string
 targets_string = ",".join(inferred_target_list)
-VERIFY: targets_string matches r"^[a-z0-9_-]+(,[a-z0-9_-]+)*$"
+command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--targets \"{targets_string}\" " +
+          "--mode explore --variants {layout_variants} " +
+          "--device-type \"{device_type}\""
 
-# Prepare command with unified parameters
-targets_flag = "--targets \"{targets_string}\""
-type_flag = "--target-type \"{target_type}\""
-
-command = "/workflow:ui-design:generate {run_base_flag} {targets_flag} {type_flag} --style-variants {style_variants} --layout-variants {layout_variants}"
-
-total_prototypes = style_variants * layout_variants * len(inferred_target_list)
-
-# Report based on type
-IF target_type == "page":
-    type_icon = "📄"
-    type_label = "Pages"
-    context_note = "Full-page layouts"
-ELSE IF target_type == "component":
-    type_icon = "🧩"
-    type_label = "Components"
-    context_note = "Isolated elements with minimal wrapper"
-ELSE:
-    type_icon = "🎯"
-    type_label = "Targets"
-    context_note = "Mixed pages and components"
-
-REPORT: "🚀 Phase 3: Matrix UI Generation"
-REPORT: "   {type_icon} {type_label}: {targets_string}"
-REPORT: "   Matrix: {style_variants}×{layout_variants}"
-REPORT: "   Total: {total_prototypes} prototypes"
-REPORT: "   Context: {context_note}"
+REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
+REPORT: "   → Targets: {targets_string}"
+REPORT: "   → Layout variants: {layout_variants}"
+REPORT: "   → Device: {device_type}"
 
 SlashCommand(command)
+
+# Output: layout-templates.json with {targets × layout_variants} layout structures
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
 ```
 
-**Result**:
-- File naming: `{target}-style-{s}-layout-{l}.html`
-- Total: `style_variants × layout_variants × targets`
-- Matrix view: `compare.html` with interactive grid
-- Rendering: Full-page for pages, minimal wrapper for components
+### Phase 3: UI Assembly
+```bash
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
 
-**Auto-Continue**: On completion → Phase 4
+total = style_variants × layout_variants × len(inferred_target_list)
 
----
+REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "   → Pure assembly: Combining layout templates + design tokens"
+REPORT: "   → Device: {device_type} (from layout templates)"
+REPORT: "   → Assembly tasks: {total} combinations"
+
+SlashCommand(command)
+
+# SlashCommand blocks until phase complete
+# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
+# Output:
+# - {target}-style-{s}-layout-{l}.html (assembled prototypes)
+# - {target}-style-{s}-layout-{l}.css
+# - compare.html (interactive matrix view)
+# - PREVIEW.md (usage instructions)
+```
 
 ### Phase 4: Design System Integration
-**Command**:
 ```bash
-session_flag = --session present ? "--session {session_id}" : ""
-
-# Omit --selected-prototypes to use ALL generated prototypes
-command = "/workflow:ui-design:update {session_flag}"
+command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
 SlashCommand(command)
-```
-**Auto-Continue**: If `--batch-plan` present → Phase 5, else complete
 
----
+# SlashCommand blocks until phase complete
+# Upon completion:
+#   - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
+#   - If no --batch-plan: Workflow complete, display final report
+```
 
 ### Phase 5: Batch Task Generation (Optional)
-**Condition**: Only if `--batch-plan` flag present
-
-**Execution**:
 ```bash
-FOR target IN inferred_target_list:
-    IF target_type == "page":
-        SlashCommand("/workflow:plan --agent \"Implement {target} page based on design system\"")
-    ELSE IF target_type == "component":
-        SlashCommand("/workflow:plan --agent \"Implement {target} component based on design system\"")
-    ELSE:
-        SlashCommand("/workflow:plan --agent \"Implement {target} based on design system\"")
+IF --batch-plan:
+    FOR target IN inferred_target_list:
+        task_desc = "Implement {target} {target_type} based on design system"
+        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
 ```
-**Completion**: Workflow complete
 
 ## TodoWrite Pattern
-
 ```javascript
-// Initialize
+// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
 TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
-  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing style consolidation"},
-  {"content": "Execute UI prototype generation", "status": "pending", "activeForm": "Executing UI generation"},
-  {"content": "Execute design system integration", "status": "pending", "activeForm": "Executing design system integration"}
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
 ]})
 
-// After each phase: Mark current completed, next in_progress, rest pending
-// Phase 1 done → Phase 2 in_progress
-// Phase 2 done → Phase 3 in_progress
-// ... continues until all completed
+// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
+// 1. SlashCommand blocks and returns when phase is complete
+// 2. Update current phase: status → "completed"
+// 3. Update next phase: status → "in_progress"
+// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
+// This ensures continuous workflow tracking and prevents premature stopping
 ```
 
-## Error Handling
+## Key Features
 
-- **Phase Failures**: Workflow halts, keeps failed phase `in_progress`, reports error with recovery instructions
-- **Ambiguity**: Defaults to ALL available items (variants/prototypes) to ensure autonomous continuation
+- **🚀 Performance**: Style-centric batch generation with S agent calls
+- **🎨 Style-Aware**: HTML structure adapts to design_attributes
+- **✅ Perfect Consistency**: Each style by single agent
+- **📦 Autonomous**: No user intervention required between phases
+- **🧠 Intelligent**: Parses natural language, infers targets/types
+- **🔄 Reproducible**: Deterministic flow with isolated run directories
+- **🎯 Flexible**: Supports pages, components, or mixed targets
 
-## Key Features & Workflow Position
+## Examples
 
-**Core Improvements**:
-- **Zero External Dependencies**: Pure Claude + agents, no CLI tools
-- **Streamlined Commands**: Unified patterns, no tool-specific flags
-- **Reproducible Flow**: Deterministic phase dependencies
-- **Intelligent Parsing**: Natural language → variant counts, pages
-- **Run Isolation**: Each execution in timestamped run directory
-
-**Workflow Bridge**: Connects brainstorming (`synthesis-specification.md`) → design phase → planning (`/workflow:plan`) in fully automated fashion with matrix-based design exploration.
-
-## Example Execution Flows
-
-### Example 1: Default 3×3 Matrix (Page Mode - Prompt Inference)
+### 1. Page Mode (Prompt Inference)
 ```bash
-/workflow:ui-design:explore-auto --prompt "Modern minimalist blog with home, article, and author pages"
-
-# Auto-detected type: page
-# Inferred: 3 style variants, 3 layout variants (default)
-# Targets: home, article, author
-# Total: 27 full-page prototypes (3×3×3)
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
+# Result: 27 prototypes (3×3×3) - responsive layouts (default)
 ```
 
-### Example 2: Custom 2×2 Matrix with Session
+### 2. Mobile-First Design
+```bash
+/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
+# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
+```
+
+### 3. Desktop Application
+```bash
+/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
+# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
+```
+
+### 4. Tablet Interface
+```bash
+/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
+# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
+```
+
+### 5. Custom Matrix with Session
 ```bash
 /workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
-
-# Auto-detected from session synthesis
-# Total: 2×2×N prototypes (N from inference)
+# Result: 2×2×N prototypes - device type inferred from session
 ```
 
-### Example 3: Unified - Navbar Design Comparison
+### 6. Component Mode (Desktop)
 ```bash
-/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --prompt "Compare 3 navigation bar designs for SaaS product" --style-variants 3 --layout-variants 2
-
-# Explicit type: component
-# Targets: navbar, hero
-# Matrix: 3 styles × 2 layouts
-# Total: 12 component prototypes (3×2×2)
-# Output: navbar-style-1-layout-1.html, navbar-style-1-layout-2.html, ...
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2) - desktop components
 ```
 
-### Example 4: Unified - Card & Form Exploration
+### 7. Intelligent Parsing + Batch Planning
 ```bash
-/workflow:ui-design:explore-auto --targets "card,form,button" --images "refs/*.png" --style-variants 2 --layout-variants 3
-
-# Auto-detected type: component (based on keywords)
-# Targets: card, form, button
-# Matrix: 2 styles × 3 layouts
-# Total: 18 component prototypes (2×3×3)
-# Context: Each component in minimal wrapper for isolated comparison
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
 ```
 
-### Example 5: Intelligent Parsing + Batch Planning
+### 8. Large Scale Responsive
 ```bash
-/workflow:ui-design:explore-auto --session WFS-saas --prompt "Create 4 styles with 2 layouts for SaaS dashboard and settings" --batch-plan
-
-# Auto-detected type: page
-# Parsed: 4 styles, 2 layouts
-# Targets: dashboard, settings
-# Total: 16 full-page prototypes (4×2×2)
-# Auto-generates implementation tasks for each target
+/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
+# Result: 36 prototypes (3×3×4) - responsive layouts
 ```
 
-### Example 6: Auto-Detected Components from Prompt
-```bash
-/workflow:ui-design:explore-auto --prompt "Design exploration for pricing table and testimonial card components" --style-variants 3 --layout-variants 2
-
-# Auto-detected type: component (keyword: "components")
-# Inferred targets: pricing-table, testimonial-card
-# Matrix: 3 styles × 2 layouts
-# Total: 12 component prototypes (3×2×2)
-```
-
-### Example 7: Legacy Parameter Support
-```bash
-# Using legacy --pages parameter (backward compatible)
-/workflow:ui-design:explore-auto --pages "home,dashboard,settings"
-
-# Equivalent to: --targets "home,dashboard,settings" --target-type "page"
-```
-
-### Example 8: Mixed Mode (Future Enhancement)
-```bash
-/workflow:ui-design:explore-auto --targets "home,dashboard,navbar,hero,card" --target-type "auto"
-
-# Auto-detection: home, dashboard → page; navbar, hero, card → component
-# Generates appropriate wrapper for each target type
-# Future: Support per-target type specification
-```
-
-## Final Completion Message
-
-**Unified Template**:
+## Completion Output
 ```
 ✅ UI Design Explore-Auto Workflow Complete!
 
-Run ID: {run_id}
-Session: {session_id or "standalone"}
-Type: {target_type_icon} {target_type_label}
-Matrix: {style_variants}×{layout_variants} ({total_prototypes} total prototypes)
-Input: {images and/or prompt summary}
+Architecture: Style-Centric Batch Generation
+Run ID: {run_id} | Session: {session_id or "standalone"}
+Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
 
-Phase 1 - Style Extraction: {style_variants} style variants
-Phase 2 - Style Consolidation: {style_variants} independent design systems
-Phase 3 - Matrix Generation: {style_variants}×{layout_variants}×{target_count} = {total_prototypes} prototypes
-Phase 4 - Design Update: Brainstorming artifacts updated
-{IF batch-plan: Phase 5 - Task Generation: {task_count} implementation tasks created}
+Phase 1: {s} complete design systems (style-extract)
+Phase 2: {n×l} layout templates (layout-extract explore mode)
+  - Device: {device_type} layouts
+  - {n} targets × {l} layout variants = {n×l} structural templates
+Phase 3: UI Assembly (generate)
+  - Pure assembly: layout templates + design tokens
+  - {s}×{l}×{n} = {total} final prototypes
+Phase 4: Brainstorming artifacts updated
+[Phase 5: {n} implementation tasks created]  # if --batch-plan
 
-📂 Run Output: {base_path}/
-  ├── style-consolidation/  ({style_variants} design systems)
-  ├── prototypes/           ({total_prototypes} HTML/CSS files)
-  └── .run-metadata.json    (run configuration)
+Assembly Process:
+✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
+✅ Layout Extraction: {n×l} reusable structural templates
+✅ Pure Assembly: No design decisions in generate phase
+✅ Device-Optimized: Layouts designed for {device_type}
 
-🌐 Interactive Preview: {base_path}/prototypes/compare.html
-  - {style_variants}×{layout_variants} matrix view with synchronized scrolling
-  - {IF target_type == "component": "Isolated rendering with minimal wrapper" ELSE: "Full-page layouts"}
-  - Side-by-side comparison for design decisions
-  - Selection export for implementation
+Design Quality:
+✅ Token-Driven Styling: 100% var() usage
+✅ Structural Variety: {l} distinct layouts per target
+✅ Style Variety: {s} independent design systems
+✅ Device-Optimized: Layouts designed for {device_type}
 
-{target_type_icon} Targets Explored: {', '.join(inferred_target_list)}
-  Type: {target_type}
-  Context: {IF target_type == "page": "Full-page layouts" ELSE IF target_type == "component": "Isolated UI elements" ELSE: "Mixed targets"}
+📂 {base_path}/
+  ├── .intermediates/          (Intermediate analysis files)
+  │   ├── style-analysis/      (computed-styles.json, design-space-analysis.json)
+  │   └── layout-analysis/     (dom-structure-*.json, inspirations/*.txt)
+  ├── style-extraction/        ({s} complete design systems)
+  ├── layout-extraction/       ({n×l} layout templates + layout-space-analysis.json)
+  ├── prototypes/              ({total} assembled prototypes)
+  └── .run-metadata.json       (includes device type)
 
-{IF batch-plan:
-📋 Implementation Tasks: .workflow/WFS-{session}/.task/
-Next: /workflow:execute to begin implementation
-}
-{ELSE:
-Next Steps:
-1. Open compare.html to preview all variants
-2. Select preferred style×layout combinations per target
-3. Run /workflow:plan to create implementation tasks
-{IF target_type == "component": "4. Integrate selected components into pages"}
-}
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive {s}×{l} matrix view
+  - Side-by-side comparison
+  - Target-specific layouts with style-aware structure
+  - Toggle between {n} targets
+
+{icon} Targets: {', '.join(targets)} (type: {target_type})
+  - Each target has {l} custom-designed layouts
+  - Each style × target × layout has unique HTML structure (not just CSS!)
+  - Layout plans stored as structured JSON
+  - Optimized for {device_type} viewing
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
 ```
 
-**Dynamic Values**:
-- `target_type_icon`: "📄" for page, "🧩" for component, "🎯" for mixed/auto
-- `target_type_label`: "Pages" for page, "Components" for component, "Targets" for mixed/auto
-- `target_count`: `len(inferred_target_list)`
-- All other placeholders are resolved from stored phase data

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

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

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

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

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

@@ -0,0 +1,746 @@
+---
+name: layout-extract
+description: Extract structural layout information from reference images, URLs, or text prompts
+argument-hint: [--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--targets "<list>"] [--mode <imitate|explore>] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>]
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
+---
+
+# Layout Extraction Command
+
+## Overview
+
+Extract structural layout information from reference images, URLs, or text prompts using AI analysis. This command separates the "scaffolding" (HTML structure and CSS layout) from the "paint" (visual tokens handled by `style-extract`).
+
+**Strategy**: AI-Driven Structural Analysis
+
+- **Agent-Powered**: Uses `ui-design-agent` for deep structural analysis
+- **Dual-Mode**:
+  - `imitate`: High-fidelity replication of single layout structure
+  - `explore`: Multiple structurally distinct layout variations
+- **Single Output**: `layout-templates.json` with DOM structure, component hierarchy, and CSS layout rules
+- **Device-Aware**: Optimized for specific device types (desktop, mobile, tablet, responsive)
+- **Token-Based**: CSS uses `var()` placeholders for spacing and breakpoints
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input, Mode & Targets
+
+```bash
+# Detect input source
+# Priority: --urls + --images → hybrid | --urls → url | --images → image | --prompt → text
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            # Single URL without target
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+ELSE:
+    has_urls = false
+    url_list = []
+
+# Determine extraction mode
+extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+
+# Set variants count based on mode
+IF extraction_mode == "imitate":
+    variants_count = 1  # Force single variant (ignore --variants)
+ELSE IF extraction_mode == "explore":
+    variants_count = --variants OR 3  # Default to 3
+    VALIDATE: 1 <= variants_count <= 5
+
+# Resolve targets
+# Priority: --targets → url_list targets → prompt analysis → default ["page"]
+IF --targets:
+    targets = split(--targets, ",")
+ELSE IF has_urls:
+    targets = [url_info.target for url_info in url_list]
+ELSE IF --prompt:
+    targets = extract_from_prompt(--prompt)
+ELSE:
+    targets = ["page"]
+
+# Resolve device type
+device_type = --device-type OR "responsive"  # desktop|mobile|tablet|responsive
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Load Inputs & Create Directories
+```bash
+# For image mode
+bash(ls {images_pattern})  # Expand glob pattern
+Read({image_path})  # Load each image
+
+# For URL mode
+# Parse URL list format: "target:url,target:url"
+# Validate URLs are accessible
+
+# For text mode
+# Validate --prompt is non-empty
+
+# Create output directory
+bash(mkdir -p {base_path}/layout-extraction)
+```
+
+### Step 2.5: Extract DOM Structure (URL Mode - Auto-Trigger)
+```bash
+# AUTO-TRIGGER: If URLs are available (from --urls parameter), automatically extract real DOM structure
+# This provides accurate layout data to supplement visual analysis
+
+# Check if URLs provided via --urls parameter
+IF --urls AND url_list:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting DOM structure"
+
+    bash(mkdir -p {base_path}/.intermediates/layout-analysis)
+
+    # For each URL in url_list:
+    FOR url_info IN url_list:
+        target = url_info.target
+        url = url_info.url
+
+        IF mcp_chrome_devtools_available:
+            REPORT: "   Processing: {target} ({url})"
+
+            # Read extraction script
+            script_content = Read(~/.claude/scripts/extract-layout-structure.js)
+
+            # Open page in Chrome DevTools
+            mcp__chrome-devtools__navigate_page(url=url)
+
+            # Execute layout extraction script
+            result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+            # Save DOM structure for this target (intermediate file)
+            Write({base_path}/.intermediates/layout-analysis/dom-structure-{target}.json, result)
+
+            REPORT: "   ✅ DOM structure extracted for '{target}'"
+        ELSE:
+            REPORT: "   ⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
+            BREAK
+
+    dom_structure_available = mcp_chrome_devtools_available
+ELSE:
+    dom_structure_available = false
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-layout-structure.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method, version
+- `patterns`: Layout pattern statistics (flexColumn, flexRow, grid counts)
+- `structure`: Hierarchical DOM tree with layout properties
+- `exploration`: (Optional) Progressive exploration results when standard selectors fail
+
+**Benefits**:
+- ✅ Real flex/grid configuration (justifyContent, alignItems, gap, etc.)
+- ✅ Accurate element bounds (x, y, width, height)
+- ✅ Structural hierarchy with depth control
+- ✅ Layout pattern identification (flex-row, flex-column, grid-NCol)
+- ✅ Progressive exploration: Auto-discovers missing selectors
+
+**Progressive Exploration Strategy** (v2.2.0+):
+
+When script finds <3 main containers, it automatically:
+1. **Scans** all large visible containers (≥500×300px)
+2. **Extracts** class patterns matching: `main|content|wrapper|container|page|layout|app`
+3. **Suggests** new selectors to add to script
+4. **Returns** exploration data in `result.exploration`:
+   ```json
+   {
+     "triggered": true,
+     "discoveredCandidates": [{classes, bounds, display}],
+     "suggestedSelectors": [".wrapper", ".page-index"],
+     "recommendation": ".wrapper, .page-index, .app-container"
+   }
+   ```
+
+**Using Exploration Results**:
+```javascript
+// After extraction, check for suggestions
+IF result.exploration?.triggered:
+    REPORT: result.exploration.warning
+    REPORT: "Suggested selectors: " + result.exploration.recommendation
+
+    // Update script by adding to commonClassSelectors array
+    // Then re-run extraction for better coverage
+```
+
+**Selector Update Workflow**:
+1. Run extraction on unfamiliar site
+2. Check `result.exploration.suggestedSelectors`
+3. Add relevant selectors to script's `commonClassSelectors`
+4. Re-run extraction → improved container detection
+
+### Step 3: Memory Check
+```bash
+# 1. Check if inputs cached in session memory
+IF session_has_inputs: SKIP Step 2 file reading
+
+# 2. Check if output already exists
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+IF exists: SKIP to completion
+```
+
+---
+
+**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `targets[]`, `device_type`, loaded inputs
+
+## Phase 1: Layout Concept Generation (Explore Mode Only)
+
+### Step 1: Check Extraction Mode
+```bash
+# extraction_mode == "imitate" → skip this phase
+# extraction_mode == "explore" → execute this phase
+```
+
+**If imitate mode**: Skip to Phase 2
+
+### Step 2: Gather Layout Inspiration (Explore Mode)
+```bash
+bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)
+
+# For each target: Research via MCP
+# mcp__exa__web_search_exa(query="{target} layout patterns {device_type}", numResults=5)
+
+# Write inspiration file
+Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, inspiration_content)
+```
+
+### Step 3: Generate Layout Concept Options (Agent Task 1)
+**Executor**: `Task(ui-design-agent)`
+
+Launch agent to generate `variants_count` layout concept options for each target:
+
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_CONCEPT_GENERATION_TASK]
+  Generate {variants_count} structurally distinct layout concepts for each target
+
+  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+  TARGETS: {targets} | DEVICE_TYPE: {device_type}
+
+  ## Input Analysis
+  - Targets: {targets.join(", ")}
+  - Device type: {device_type}
+  - Layout inspiration: Read inspirations from {base_path}/.intermediates/layout-analysis/inspirations/
+  - Visual references: {loaded_images if available}
+  ${dom_structure_available ? "- DOM Structure: Read from .intermediates/layout-analysis/dom-structure-*.json" : ""}
+
+  ## Analysis Rules
+  - For EACH target, generate {variants_count} structurally DIFFERENT layout concepts
+  - Concepts must differ in: grid structure, component arrangement, visual hierarchy
+  - Each concept should have distinct navigation pattern, content flow, and responsive behavior
+
+  ## Generate for EACH Target
+  For target in {targets}:
+    For concept_index in 1..{variants_count}:
+      1. **Concept Definition**:
+         - concept_name (descriptive, e.g., "Classic Three-Column Holy Grail")
+         - design_philosophy (1-2 sentences explaining the structural approach)
+         - layout_pattern (e.g., "grid-3col", "flex-row", "single-column", "asymmetric-grid")
+         - key_components (array of main layout regions)
+         - structural_features (list of distinguishing characteristics)
+
+      2. **Wireframe Preview** (simple text representation):
+         - ascii_art (simple ASCII box diagram showing layout structure)
+         - Example:
+           ┌─────────────────┐
+           │     HEADER      │
+           ├──┬─────────┬────┤
+           │ L│  MAIN   │ R  │
+           └──┴─────────┴────┘
+
+  ## Output
+  Write single JSON file: {base_path}/.intermediates/layout-analysis/analysis-options.json
+
+  Use schema from INTERACTIVE-DATA-SPEC.md (Layout Extract: analysis-options.json)
+
+  CRITICAL: Use Write() tool immediately after generating complete JSON
+`
+```
+
+### Step 4: Verify Options File Created
+```bash
+bash(test -f {base_path}/.intermediates/layout-analysis/analysis-options.json && echo "created")
+
+# Quick validation
+bash(cat {base_path}/.intermediates/layout-analysis/analysis-options.json | grep -q "layout_concepts" && echo "valid")
+```
+
+**Output**: `analysis-options.json` with layout concept options for all targets
+
+---
+
+## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+
+**Purpose**: Allow user to select preferred layout concept(s) for each target before generating detailed templates
+
+### Step 1: Load and Present Options
+```bash
+# Read options file
+options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+
+# Parse layout concepts
+layout_concepts = options.layout_concepts
+```
+
+### Step 2: Present Options to User (Per Target)
+For each target, present layout concept options and capture selection:
+
+```
+📋 Layout Concept Options for Target: {target}
+
+We've generated {variants_count} structurally different layout concepts for review.
+Please select your preferred concept for this target.
+
+{FOR each concept in layout_concepts[target]:
+  ═══════════════════════════════════════════════════
+  Concept {concept.index}: {concept.concept_name}
+  ═══════════════════════════════════════════════════
+
+  Philosophy: {concept.design_philosophy}
+  Pattern: {concept.layout_pattern}
+
+  Components:
+  {FOR each component in concept.key_components:
+    • {component}
+  }
+
+  Features:
+  {FOR each feature in concept.structural_features:
+    • {feature}
+  }
+
+  Wireframe:
+  {concept.wireframe_preview.ascii_art}
+
+  ═══════════════════════════════════════════════════
+}
+```
+
+### Step 3: Capture User Selection (Per Target)
+```javascript
+// Use AskUserQuestion tool for each target
+FOR each target:
+  AskUserQuestion({
+    questions: [{
+      question: "Which layout concept do you prefer for '{target}'?",
+      header: "Layout for " + target,
+      multiSelect: false,
+      options: [
+        {FOR each concept in layout_concepts[target]:
+          label: "Concept {concept.index}: {concept.concept_name}",
+          description: "{concept.design_philosophy}"
+        }
+      ]
+    }]
+  })
+
+  // Parse user response
+  selected_option_text = user_answer
+
+  // Check for user cancellation
+  IF selected_option_text == null OR selected_option_text == "":
+      REPORT: "⚠️ User canceled selection. Workflow terminated."
+      EXIT workflow
+
+  // Extract concept index from response format "Concept N: Name"
+  match = selected_option_text.match(/Concept (\d+):/)
+  IF match:
+      selected_index = parseInt(match[1])
+  ELSE:
+      ERROR: "Invalid selection format. Expected 'Concept N: ...' format"
+      EXIT workflow
+
+  // Store selection for this target
+  selections[target] = {
+    selected_index: selected_index,
+    concept_name: layout_concepts[target][selected_index-1].concept_name
+  }
+```
+
+### Step 4: Write User Selection File
+```bash
+# Create user selection JSON
+selection_data = {
+  "metadata": {
+    "selected_at": "{current_timestamp}",
+    "selection_type": "per_target",
+    "session_id": "{session_id}"
+  },
+  "selections": selections  // {target: {selected_index, concept_name}}
+}
+
+# Write to file
+bash(echo '{selection_data}' > {base_path}/.intermediates/layout-analysis/user-selection.json)
+
+# Verify
+bash(test -f {base_path}/.intermediates/layout-analysis/user-selection.json && echo "saved")
+```
+
+### Step 5: Confirmation Message
+```
+✅ Selections recorded!
+
+{FOR each target, selection in selections:
+  • {target}: Concept {selection.selected_index} - {selection.concept_name}
+}
+
+Proceeding to generate detailed layout templates based on your selections...
+```
+
+**Output**: `user-selection.json` with user's choices for all targets
+
+## Phase 2: Layout Template Generation (Agent Task 2)
+
+**Executor**: `Task(ui-design-agent)` for selected concept(s)
+
+### Step 1: Load User Selection (Explore Mode)
+```bash
+# For explore mode, read user selection
+IF extraction_mode == "explore":
+    selection = Read({base_path}/.intermediates/layout-analysis/user-selection.json)
+    selections_per_target = selection.selections
+
+    # Also read the selected concept details from options
+    options = Read({base_path}/.intermediates/layout-analysis/analysis-options.json)
+    layout_concepts = options.layout_concepts
+
+    # Build selected concepts map
+    selected_concepts = {}
+    FOR each target in targets:
+        selected_index = selections_per_target[target].selected_index
+        selected_concepts[target] = layout_concepts[target][selected_index-1]  # 0-indexed
+ELSE:
+    # Imitate mode - no selection needed
+    selected_concepts = null
+```
+
+### Step 2: Launch Agent Task
+Generate layout templates for selected concepts:
+```javascript
+Task(ui-design-agent): `
+  [LAYOUT_TEMPLATE_GENERATION_TASK]
+  Generate detailed layout templates based on user-selected concepts.
+  Focus ONLY on structure and layout. DO NOT concern with visual style (colors, fonts, etc.).
+
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+  DEVICE_TYPE: {device_type}
+
+  ${extraction_mode == "explore" ? `
+  USER SELECTIONS:
+  ${targets.map(target => `
+  Target: ${target}
+  - Selected Concept: ${selected_concepts[target].concept_name}
+  - Philosophy: ${selected_concepts[target].design_philosophy}
+  - Pattern: ${selected_concepts[target].layout_pattern}
+  - Key Components: ${selected_concepts[target].key_components.join(", ")}
+  - Structural Features: ${selected_concepts[target].structural_features.join(", ")}
+  `).join("\n")}
+  ` : `
+  MODE: Imitate - High-fidelity replication of reference layout structure
+  TARGETS: ${targets.join(", ")}
+  `}
+
+  ## Input Analysis
+  - Targets: {targets.join(", ")}
+  - Device type: {device_type}
+  - Visual references: {loaded_images if available}
+  ${dom_structure_available ? "- DOM Structure Data: Read from .intermediates/layout-analysis/dom-structure-*.json - USE THIS for accurate layout properties" : ""}
+
+  ## Generation Rules
+  ${extraction_mode == "explore" ? `
+  - **Explore Mode**: Develop each user-selected layout concept into a detailed template
+  - Use the selected concept's key_components as foundation
+  - Apply the selected layout_pattern (grid-3col, flex-row, etc.)
+  - Honor the structural_features defined in the concept
+  - Expand the concept with complete DOM structure and CSS layout rules
+  ` : `
+  - **Imitate Mode**: High-fidelity replication of reference layout structure
+  ${dom_structure_available ? "- Use DOM structure data as ground truth" : "- Use visual inference"}
+  `}
+  ${dom_structure_available ? `
+  - IMPORTANT: You have access to real DOM structure data with accurate flex/grid properties
+  - Use DOM data as primary source for layout properties
+  - Extract real flex/grid configurations (display, flexDirection, justifyContent, alignItems, gap)
+  - Use actual element bounds for responsive breakpoint decisions
+  - Preserve identified patterns from DOM structure
+  ` : ""}
+
+  ## Generate for EACH Target
+  For target in {targets}:
+    ${extraction_mode == "explore" ? "Based on user-selected concept:" : "Based on reference:"}
+
+    1. **DOM Structure**:
+       - Semantic HTML5 tags: <header>, <nav>, <main>, <aside>, <section>, <footer>
+       - ARIA roles and accessibility attributes
+       ${extraction_mode == "explore" ? "- Use key_components from selected concept" : ""}
+       ${dom_structure_available ? "- Base on extracted DOM tree from .intermediates" : "- Infer from visual analysis"}
+       - Device-specific optimizations for {device_type}
+
+    2. **Component Hierarchy**:
+       - Array of main layout regions
+       ${extraction_mode == "explore" ? "- Derived from selected concept's key_components" : ""}
+
+    3. **CSS Layout Rules**:
+       ${extraction_mode == "explore" ? "- Implement selected layout_pattern" : ""}
+       ${dom_structure_available ? "- Use real layout properties from DOM structure data" : "- Focus on Grid, Flexbox, position, alignment"}
+       - Use CSS Custom Properties: var(--spacing-*), var(--breakpoint-*)
+       - Device-specific styles (mobile-first @media for responsive)
+       - NO colors, NO fonts, NO shadows - layout structure only
+
+  ## Output Format
+  Write complete layout-templates.json with layout_templates array.
+  Each template must include:
+  - target (string)
+  - variant_id: "layout-1" (always 1 since only selected concept is generated)
+  - source_image_path (string): Reference image path
+  - device_type (string)
+  - design_philosophy (string ${extraction_mode == "explore" ? "- from selected concept" : ""})
+  - dom_structure (JSON object)
+  - component_hierarchy (array of strings)
+  - css_layout_rules (string)
+
+  ## Critical Requirements
+  - ✅ Use Write() tool for layout-templates.json
+  - ✅ One template per target (only selected concept)
+  - ✅ Structure only, no visual styling
+  - ✅ Token-based CSS (var())
+  ${extraction_mode == "explore" ? "- ✅ Maintain consistency with selected concepts" : ""}
+`
+```
+
+**Output**: Agent generates `layout-templates.json` with one template per target
+
+### Step 2: Write Output File
+```bash
+# Take JSON output from agent
+bash(echo '{agent_json_output}' > {base_path}/layout-extraction/layout-templates.json)
+
+# Verify output
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+bash(cat {base_path}/layout-extraction/layout-templates.json | grep -q "layout_templates" && echo "valid")
+```
+
+**Output**: `layout-templates.json` created and verified
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "Layout research (explore mode)", status: "completed", activeForm: "Researching layout patterns"},
+  {content: "Layout analysis and synthesis (agent)", status: "completed", activeForm: "Generating layout templates"},
+  {content: "Write layout-templates.json", status: "completed", activeForm: "Saving templates"}
+]});
+```
+
+### Output Message
+```
+✅ Layout extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (imitate/explore)
+- Device Type: {device_type}
+- Targets: {targets}
+- Variants per Target: {variants_count}
+- Total Templates: {targets.length × variants_count}
+{IF has_urls AND dom_structure_available:
+- 🔍 URL Mode: DOM structure extracted from {len(url_list)} URL(s)
+- Accuracy: Real flex/grid properties from live pages
+}
+{IF has_urls AND NOT dom_structure_available:
+- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
+}
+
+{IF extraction_mode == "explore":
+Layout Research:
+- {targets.length} inspiration files generated
+- Pattern search focused on {device_type} layouts
+}
+
+Generated Templates:
+{FOR each template: - Target: {template.target} | Variant: {template.variant_id} | Philosophy: {template.design_philosophy}}
+
+Output File:
+- {base_path}/layout-extraction/layout-templates.json
+{IF dom_structure_available:
+- {base_path}/.intermediates/layout-analysis/dom-structure-*.json ({len(url_list)} files)
+}
+
+Next: /workflow:ui-design:generate will combine these structural templates with style systems to produce final prototypes.
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Create output directories
+bash(mkdir -p {base_path}/layout-extraction)
+bash(mkdir -p {base_path}/.intermediates/layout-analysis/inspirations)  # explore mode only
+```
+
+### Validation Commands
+```bash
+# Check if already extracted
+bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+
+# Validate JSON structure
+bash(cat layout-templates.json | grep -q "layout_templates" && echo "valid")
+
+# Count templates
+bash(cat layout-templates.json | grep -c "\"target\":")
+```
+
+### File Operations
+```bash
+# Load image references
+bash(ls {images_pattern})
+Read({image_path})
+
+# Write inspiration files (explore mode)
+Write({base_path}/.intermediates/layout-analysis/inspirations/{target}-layout-ideas.txt, content)
+
+# Write layout templates
+bash(echo '{json}' > {base_path}/layout-extraction/layout-templates.json)
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                    # Intermediate analysis files
+│   └── layout-analysis/
+│       ├── dom-structure-{target}.json   # Extracted DOM structure (URL mode only)
+│       └── inspirations/                 # Explore mode only
+│           └── {target}-layout-ideas.txt # Layout inspiration research
+└── layout-extraction/                 # Final layout templates
+    ├── layout-templates.json          # Structural layout templates
+    └── layout-space-analysis.json     # Layout directions (explore mode only)
+```
+
+## layout-templates.json Format
+
+```json
+{
+  "extraction_metadata": {
+    "session_id": "...",
+    "input_mode": "image|url|prompt|hybrid",
+    "extraction_mode": "imitate|explore",
+    "device_type": "desktop|mobile|tablet|responsive",
+    "timestamp": "...",
+    "variants_count": 3,
+    "targets": ["home", "dashboard"]
+  },
+  "layout_templates": [
+    {
+      "target": "home",
+      "variant_id": "layout-1",
+      "source_image_path": "{base_path}/screenshots/home.png",
+      "device_type": "responsive",
+      "design_philosophy": "Responsive 3-column holy grail layout with fixed header and footer",
+      "dom_structure": {
+        "tag": "body",
+        "children": [
+          {
+            "tag": "header",
+            "attributes": {"class": "layout-header"},
+            "children": [{"tag": "nav"}]
+          },
+          {
+            "tag": "div",
+            "attributes": {"class": "layout-main-wrapper"},
+            "children": [
+              {"tag": "main", "attributes": {"class": "layout-main-content"}},
+              {"tag": "aside", "attributes": {"class": "layout-sidebar-left"}},
+              {"tag": "aside", "attributes": {"class": "layout-sidebar-right"}}
+            ]
+          },
+          {"tag": "footer", "attributes": {"class": "layout-footer"}}
+        ]
+      },
+      "component_hierarchy": [
+        "header",
+        "main-content",
+        "sidebar-left",
+        "sidebar-right",
+        "footer"
+      ],
+      "css_layout_rules": ".layout-main-wrapper { display: grid; grid-template-columns: 1fr 3fr 1fr; gap: var(--spacing-6); } @media (max-width: var(--breakpoint-md)) { .layout-main-wrapper { grid-template-columns: 1fr; } }"
+    }
+  ]
+}
+```
+
+**Requirements**: Token-based CSS (var()), semantic HTML5, device-specific structure, accessibility attributes
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No inputs provided
+→ Provide --images, --urls, or --prompt
+
+ERROR: Invalid target name
+→ Use lowercase, alphanumeric, hyphens only
+
+ERROR: Agent task failed
+→ Check agent output, retry with simplified prompt
+
+ERROR: MCP search failed (explore mode)
+→ Check network, retry
+```
+
+### Recovery Strategies
+- **Partial success**: Keep successfully extracted templates
+- **Invalid JSON**: Retry with stricter format requirements
+- **Missing inspiration**: Works without (less informed exploration)
+
+## Key Features
+
+- **Auto-Trigger URL Mode** - Automatically extracts DOM structure when --urls provided (no manual flag needed)
+- **Hybrid Extraction Strategy** - Combines real DOM structure data with AI visual analysis
+- **Accurate Layout Properties** - Chrome DevTools extracts real flex/grid configurations, bounds, and hierarchy
+- **Separation of Concerns** - Decouples layout (structure) from style (visuals)
+- **Structural Exploration** - Explore mode enables A/B testing of different layouts
+- **Token-Based Layout** - CSS uses `var()` placeholders for instant design system adaptation
+- **Device-Specific** - Tailored structures for different screen sizes
+- **Graceful Fallback** - Falls back to visual analysis if Chrome DevTools unavailable
+- **Foundation for Assembly** - Provides structural blueprint for refactored `generate` command
+- **Agent-Powered** - Deep structural analysis with AI
+
+## Integration
+
+**Workflow Position**: Between style extraction and prototype generation
+
+**New Workflow**:
+1. `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md` (Complete design systems)
+2. `/workflow:ui-design:layout-extract` → `layout-templates.json` (Structural templates)
+3. `/workflow:ui-design:generate` (Pure assembler):
+   - **Reads**: `design-tokens.json` + `layout-templates.json`
+   - **Action**: For each style × layout combination:
+     1. Build HTML from `dom_structure`
+     2. Create layout CSS from `css_layout_rules`
+     3. Link design tokens CSS
+     4. Inject placeholder content
+   - **Output**: Complete token-driven HTML/CSS prototypes
+
+**Input**: Reference images, URLs, or text prompts
+**Output**: `layout-templates.json` for `/workflow:ui-design:generate`
+**Next**: `/workflow:ui-design:generate --session {session_id}`

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

@@ -0,0 +1,624 @@
+---
+name: style-extract
+description: Extract design style from reference images or text prompts using Claude's analysis
+argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+---
+
+# Style Extraction Command
+
+## Overview
+Extract design style from reference images or text prompts using Claude's built-in analysis. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
+
+**Strategy**: AI-Driven Design Space Exploration
+- **Claude-Native**: 100% Claude analysis, no external tools
+- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
+- **Flexible Input**: Images, text prompts, or both (hybrid mode)
+- **Maximum Contrast**: AI generates maximally divergent design directions
+- **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
+
+## Phase 0: Setup & Input Validation
+
+### Step 1: Detect Input Mode, Extraction Mode & Base Path
+```bash
+# Detect input source
+# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
+
+# Parse URLs if provided (format: "target:url,target:url,...")
+IF --urls:
+    url_list = []
+    FOR pair IN split(--urls, ","):
+        IF ":" IN pair:
+            target, url = pair.split(":", 1)
+            url_list.append({target: target.strip(), url: url.strip()})
+        ELSE:
+            # Single URL without target
+            url_list.append({target: "page", url: pair.strip()})
+
+    has_urls = true
+    primary_url = url_list[0].url  # First URL as primary source
+ELSE:
+    has_urls = false
+
+# Determine extraction mode
+# Priority: --mode parameter → default "imitate"
+extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
+
+# Set variants count based on mode
+IF extraction_mode == "imitate":
+    variants_count = 1  # Force single variant for imitate mode (ignore --variants)
+ELSE IF extraction_mode == "explore":
+    variants_count = --variants OR 3  # Default to 3 for explore mode
+    VALIDATE: 1 <= variants_count <= 5
+
+# Determine base path
+bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# OR use --base-path / --session parameters
+```
+
+### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
+```bash
+# AUTO-TRIGGER: If URLs are available (from --urls parameter or capture metadata), automatically extract real CSS values
+# This provides accurate design tokens to supplement visual analysis
+
+# Priority 1: Check for --urls parameter
+IF has_urls:
+    url_to_extract = primary_url
+    url_source = "--urls parameter"
+
+# Priority 2: Check for URL metadata from capture phase
+ELSE IF exists({base_path}/.metadata/capture-urls.json):
+    capture_urls = Read({base_path}/.metadata/capture-urls.json)
+    url_to_extract = capture_urls[0]  # Use first URL
+    url_source = "capture metadata"
+ELSE:
+    url_to_extract = null
+
+# Execute extraction if URL available
+IF url_to_extract AND mcp_chrome_devtools_available:
+    REPORT: "🔍 Auto-triggering URL mode: Extracting computed styles from {url_source}"
+    REPORT: "   URL: {url_to_extract}"
+
+    # Read extraction script
+    script_content = Read(~/.claude/scripts/extract-computed-styles.js)
+
+    # Open page in Chrome DevTools
+    mcp__chrome-devtools__navigate_page(url=url_to_extract)
+
+    # Execute extraction script directly
+    result = mcp__chrome-devtools__evaluate_script(function=script_content)
+
+    # Save computed styles to intermediates directory
+    bash(mkdir -p {base_path}/.intermediates/style-analysis)
+    Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
+
+    computed_styles_available = true
+    REPORT: "   ✅ Computed styles extracted and saved"
+ELSE:
+    computed_styles_available = false
+    IF url_to_extract:
+        REPORT: "⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
+```
+
+**Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
+
+**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
+
+**Script returns**:
+- `metadata`: Extraction timestamp, URL, method
+- `tokens`: Organized design tokens (colors, borderRadii, shadows, fontSizes, fontWeights, spacing)
+
+**Benefits**:
+- ✅ Pixel-perfect accuracy for border-radius, box-shadow, padding, etc.
+- ✅ Eliminates guessing from visual analysis
+- ✅ Provides ground truth for design tokens
+
+### Step 3: Load Inputs
+```bash
+# For image mode
+bash(ls {images_pattern})  # Expand glob pattern
+Read({image_path})  # Load each image
+
+# For text mode
+# Validate --prompt is non-empty
+
+# Create output directory
+bash(mkdir -p {base_path}/style-extraction/)
+```
+
+### Step 3: Memory Check
+```bash
+# 1. Check if inputs cached in session memory
+IF session_has_inputs: SKIP Step 2 file reading
+
+# 2. Check if output already exists
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
+IF exists: SKIP to completion
+```
+
+---
+
+**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`, `has_urls`, `url_list[]`, `computed_styles_available`
+
+## Phase 1: Design Direction Generation (Explore Mode Only)
+
+### Step 1: Check Extraction Mode
+```bash
+# Check extraction mode
+# extraction_mode == "imitate" → skip this phase
+# extraction_mode == "explore" → execute this phase
+```
+
+**If imitate mode**: Skip to Phase 2
+
+### Step 2: Load Project Context (Explore Mode)
+```bash
+# Load brainstorming context if available
+bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
+```
+
+### Step 3: Generate Design Direction Options (Agent Task 1)
+**Executor**: `Task(ui-design-agent)`
+
+Launch agent to generate `variants_count` design direction options with previews:
+
+```javascript
+Task(ui-design-agent): `
+  [DESIGN_DIRECTION_GENERATION_TASK]
+  Generate {variants_count} maximally contrasting design directions with visual previews
+
+  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+
+  ## Input Analysis
+  - User prompt: {prompt_guidance}
+  - Visual references: {loaded_images if available}
+  - Project context: {brainstorming_context if available}
+
+  ## Analysis Rules
+  - Analyze 6D attribute space: color saturation, visual weight, formality, organic/geometric, innovation, density
+  - Generate {variants_count} directions with MAXIMUM contrast
+  - Each direction must be distinctly different (min distance score: 0.7)
+
+  ## Generate for EACH Direction
+  1. **Core Philosophy**:
+     - philosophy_name (2-3 words, e.g., "Minimalist & Airy")
+     - design_attributes (6D scores 0-1)
+     - search_keywords (3-5 keywords)
+     - anti_keywords (2-3 keywords to avoid)
+     - rationale (why this is distinct from others)
+
+  2. **Visual Preview Elements**:
+     - primary_color (OKLCH format)
+     - secondary_color (OKLCH format)
+     - accent_color (OKLCH format)
+     - font_family_heading (specific font name)
+     - font_family_body (specific font name)
+     - border_radius_base (e.g., "0.5rem")
+     - mood_description (1-2 sentences describing the feel)
+
+  ## Output
+  Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+
+  Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
+
+  CRITICAL: Use Write() tool immediately after generating complete JSON
+`
+```
+
+### Step 4: Verify Options File Created
+```bash
+bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
+
+# Quick validation
+bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep -q "design_directions" && echo "valid")
+```
+
+**Output**: `analysis-options.json` with design direction options
+
+---
+
+## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+
+**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
+
+### Step 1: Load and Present Options
+```bash
+# Read options file
+options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+
+# Parse design directions
+design_directions = options.design_directions
+```
+
+### Step 2: Present Options to User
+```
+📋 Design Direction Options
+
+We've generated {variants_count} contrasting design directions for your review.
+Please select the direction(s) you'd like to develop into complete design systems.
+
+{FOR each direction in design_directions:
+  ═══════════════════════════════════════════════════
+  Option {direction.index}: {direction.philosophy_name}
+  ═══════════════════════════════════════════════════
+
+  Philosophy: {direction.rationale}
+
+  Visual Preview:
+  • Colors: {direction.preview.primary_color} (primary), {direction.preview.accent_color} (accent)
+  • Typography: {direction.preview.font_family_heading} (headings), {direction.preview.font_family_body} (body)
+  • Border Radius: {direction.preview.border_radius_base}
+  • Mood: {direction.preview.mood_description}
+
+  Design Attributes:
+  • Color Saturation: {direction.design_attributes.color_saturation * 100}%
+  • Visual Weight: {direction.design_attributes.visual_weight * 100}%
+  • Formality: {direction.design_attributes.formality * 100}%
+  • Innovation: {direction.design_attributes.innovation * 100}%
+
+  Keywords: {join(direction.search_keywords, ", ")}
+  Avoiding: {join(direction.anti_keywords, ", ")}
+}
+
+═══════════════════════════════════════════════════
+```
+
+### Step 3: Capture User Selection
+```javascript
+// Use AskUserQuestion tool for selection
+AskUserQuestion({
+  questions: [{
+    question: "Which design direction would you like to develop into a complete design system?",
+    header: "Style Choice",
+    multiSelect: false,  // Single selection for Phase 1
+    options: [
+      {FOR each direction:
+        label: "Option {direction.index}: {direction.philosophy_name}",
+        description: "{direction.mood_description}"
+      }
+    ]
+  }]
+})
+
+// Parse user response (e.g., "Option 1: Minimalist & Airy")
+selected_option_text = user_answer
+
+// Check for user cancellation
+IF selected_option_text == null OR selected_option_text == "":
+    REPORT: "⚠️ User canceled selection. Workflow terminated."
+    EXIT workflow
+
+// Extract option index from response format "Option N: Name"
+match = selected_option_text.match(/Option (\d+):/)
+IF match:
+    selected_index = parseInt(match[1])
+ELSE:
+    ERROR: "Invalid selection format. Expected 'Option N: ...' format"
+    EXIT workflow
+```
+
+### Step 4: Write User Selection File
+```bash
+# Create user selection JSON
+selection_data = {
+  "metadata": {
+    "selected_at": "{current_timestamp}",
+    "selection_type": "single",
+    "session_id": "{session_id}"
+  },
+  "selected_indices": [selected_index],
+  "refinements": {
+    "enabled": false
+  }
+}
+
+# Write to file
+bash(echo '{selection_data}' > {base_path}/.intermediates/style-analysis/user-selection.json)
+
+# Verify
+bash(test -f {base_path}/.intermediates/style-analysis/user-selection.json && echo "saved")
+```
+
+### Step 5: Confirmation Message
+```
+✅ Selection recorded!
+
+You selected: Option {selected_index} - {selected_direction.philosophy_name}
+
+Proceeding to generate complete design system based on your selection...
+```
+
+**Output**: `user-selection.json` with user's choice
+
+## Phase 2: Design System Generation (Agent Task 2)
+
+**Executor**: `Task(ui-design-agent)` for selected variant(s)
+
+### Step 1: Load User Selection (Explore Mode)
+```bash
+# For explore mode, read user selection
+IF extraction_mode == "explore":
+    selection = Read({base_path}/.intermediates/style-analysis/user-selection.json)
+    selected_indices = selection.selected_indices
+    refinements = selection.refinements
+
+    # Also read the selected direction details from options
+    options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+    selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed
+
+    # For Phase 1, we only allow single selection
+    selected_direction = selected_directions[0]
+    actual_variants_count = 1
+ELSE:
+    # Imitate mode - generate single variant without selection
+    selected_direction = null
+    actual_variants_count = 1
+```
+
+### Step 2: Create Output Directory
+```bash
+# Create directory for selected variant only
+bash(mkdir -p {base_path}/style-extraction/style-1)
+```
+
+### Step 3: Launch Agent Task
+Generate design system for selected direction:
+```javascript
+Task(ui-design-agent): `
+  [DESIGN_SYSTEM_GENERATION_TASK]
+  Generate production-ready design system based on user-selected direction
+
+  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+
+  ${extraction_mode == "explore" ? `
+  USER SELECTION:
+  - Selected Direction: ${selected_direction.philosophy_name}
+  - Design Attributes: ${JSON.stringify(selected_direction.design_attributes)}
+  - Search Keywords: ${selected_direction.search_keywords.join(", ")}
+  - Anti-keywords: ${selected_direction.anti_keywords.join(", ")}
+  - Rationale: ${selected_direction.rationale}
+  - Preview Colors: Primary=${selected_direction.preview.primary_color}, Accent=${selected_direction.preview.accent_color}
+  - Preview Typography: Heading=${selected_direction.preview.font_family_heading}, Body=${selected_direction.preview.font_family_body}
+  - Preview Border Radius: ${selected_direction.preview.border_radius_base}
+
+  ${refinements.enabled ? `
+  USER REFINEMENTS:
+  ${refinements.primary_color ? "- Primary Color Override: " + refinements.primary_color : ""}
+  ${refinements.font_family_heading ? "- Heading Font Override: " + refinements.font_family_heading : ""}
+  ${refinements.font_family_body ? "- Body Font Override: " + refinements.font_family_body : ""}
+  ` : ""}
+  ` : ""}
+
+  ## Input Analysis
+  - Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
+  - Visual references: {loaded_images OR prompt_guidance}
+  ${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
+
+  ## Generation Rules
+  ${extraction_mode == "explore" ? `
+  - **Explore Mode**: Develop the selected design direction into a complete design system
+  - Use preview elements as foundation and expand with full token coverage
+  - Apply design_attributes to all token values:
+    * color_saturation → OKLCH chroma values
+    * visual_weight → font weights, shadow depths
+    * density → spacing scale compression/expansion
+    * formality → typography choices, border radius
+    * organic_geometric → border radius, shape patterns
+    * innovation → token naming, experimental values
+  - Honor search_keywords for design inspiration
+  - Avoid anti_keywords patterns
+  ` : `
+  - **Imitate Mode**: High-fidelity replication of reference design
+  ${computed_styles_available ? "- Use computed styles as ground truth for all measurements" : "- Use visual inference for measurements"}
+  `}
+  - All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
+  - WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
+
+  ## Generate
+  Create complete design system in {base_path}/style-extraction/style-1/
+
+  1. **design-tokens.json**:
+     - Complete token structure: colors (brand, surface, semantic, text, border), typography (families, sizes, weights, line heights, letter spacing), spacing (0-24 scale), border_radius (none to full), shadows (sm to xl), breakpoints (sm to 2xl)
+     - All colors in OKLCH format
+     ${extraction_mode == "explore" ? "- Start from preview colors and expand to full palette" : ""}
+     ${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
+
+  2. **style-guide.md**:
+     - Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
+     - Complete color system documentation with accessibility notes
+     - Typography scale and usage guidelines
+     - Spacing system explanation
+     - Component examples and usage patterns
+
+  ## Critical Requirements
+  - ✅ Use Write() tool immediately for each file
+  - ✅ Write to style-1/ directory (single output)
+  - ❌ NO external research or MCP calls (pure AI generation)
+  - ✅ Maintain consistency with user-selected direction
+  ${refinements.enabled ? "- ✅ Apply user refinements precisely" : ""}
+`
+```
+
+**Output**: Agent generates 2 files (design-tokens.json, style-guide.md) for selected direction
+
+## Phase 3: Verify Output
+
+### Step 1: Check Files Created
+```bash
+# Verify all design systems created
+bash(ls {base_path}/style-extraction/style-*/design-tokens.json | wc -l)
+
+# Validate structure
+bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
+```
+
+### Step 2: Verify File Sizes
+```bash
+bash(ls -lh {base_path}/style-extraction/style-1/)
+```
+
+**Output**: `variants_count × 2` files verified
+
+## Completion
+
+### Todo Update
+```javascript
+TodoWrite({todos: [
+  {content: "Setup and input validation", status: "completed", activeForm: "Validating inputs"},
+  {content: "Design space analysis (explore mode)", status: "completed", activeForm: "Analyzing design space"},
+  {content: "Design system generation (agent)", status: "completed", activeForm: "Generating design systems"},
+  {content: "Verify output files", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+### Output Message
+```
+✅ Style extraction complete!
+
+Configuration:
+- Session: {session_id}
+- Extraction Mode: {extraction_mode} (imitate/explore)
+- Input Mode: {input_mode} (image/text/hybrid{"/url" if has_urls else ""})
+- Variants: {variants_count}
+- Production-Ready: Complete design systems generated
+{IF has_urls AND computed_styles_available:
+- 🔍 URL Mode: Computed styles extracted from {len(url_list)} URL(s)
+- Accuracy: Pixel-perfect design tokens from DOM
+}
+{IF has_urls AND NOT computed_styles_available:
+- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
+}
+
+{IF extraction_mode == "explore":
+Design Direction Selection:
+- You selected: Option {selected_index} - {selected_direction.philosophy_name}
+- Generated from {variants_count} contrasting design direction options
+}
+
+Generated Files:
+{base_path}/style-extraction/
+└── style-1/ (design-tokens.json, style-guide.md)
+
+{IF computed_styles_available:
+Intermediate Analysis:
+{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
+}
+{IF extraction_mode == "explore":
+{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options)
+{base_path}/.intermediates/style-analysis/user-selection.json (your selection)
+}
+
+Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
+  OR: /workflow:ui-design:generate --session {session_id}
+```
+
+## Simple Bash Commands
+
+### Path Operations
+```bash
+# Find design directory
+bash(find .workflow -type d -name "design-*" | head -1)
+
+# Expand image pattern
+bash(ls {images_pattern})
+
+# Create output directory
+bash(mkdir -p {base_path}/style-extraction/)
+```
+
+### Validation Commands
+```bash
+# Check if already extracted
+bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "exists")
+
+# Count variants
+bash(ls {base_path}/style-extraction/style-* -d | wc -l)
+
+# Validate JSON structure
+bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colors" && echo "valid")
+```
+
+### File Operations
+```bash
+# Load brainstorming context
+bash(test -f .brainstorming/role analysis documents && cat it)
+
+# Create directories
+bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
+
+# Verify output
+bash(ls {base_path}/style-extraction/style-1/)
+bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "saved")
+```
+
+## Output Structure
+
+```
+{base_path}/
+├── .intermediates/                  # Intermediate analysis files
+│   └── style-analysis/
+│       ├── computed-styles.json     # Extracted CSS values from DOM (if URL available)
+│       ├── analysis-options.json    # Design direction options (explore mode only)
+│       └── user-selection.json      # User's selected direction (explore mode only)
+└── style-extraction/                # Final design system
+    └── style-1/
+        ├── design-tokens.json       # Production-ready design tokens
+        └── style-guide.md           # Design philosophy and usage guide
+```
+
+## design-tokens.json Format
+
+```json
+{
+  "colors": {
+    "brand": {"primary": "oklch(...)", "secondary": "oklch(...)", "accent": "oklch(...)"},
+    "surface": {"background": "oklch(...)", "elevated": "oklch(...)", "overlay": "oklch(...)"},
+    "semantic": {"success": "oklch(...)", "warning": "oklch(...)", "error": "oklch(...)", "info": "oklch(...)"},
+    "text": {"primary": "oklch(...)", "secondary": "oklch(...)", "tertiary": "oklch(...)", "inverse": "oklch(...)"},
+    "border": {"default": "oklch(...)", "strong": "oklch(...)", "subtle": "oklch(...)"}
+  },
+  "typography": {"font_family": {...}, "font_size": {...}, "font_weight": {...}, "line_height": {...}, "letter_spacing": {...}},
+  "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
+  "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
+}
+```
+
+**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance
+
+## Error Handling
+
+### Common Errors
+```
+ERROR: No images found
+→ Check glob pattern
+
+ERROR: Invalid prompt
+→ Provide non-empty string
+
+ERROR: Claude JSON parsing error
+→ Retry with stricter format
+```
+
+## Key Features
+
+- **Auto-Trigger URL Mode** - Automatically extracts computed styles when --urls provided (no manual flag needed)
+- **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
+- **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
+- **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
+- **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
+- **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
+- **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
+- **Flexible Input** - Images, text, URLs, or hybrid mode
+- **Graceful Fallback** - Falls back to pure visual inference if Chrome DevTools unavailable
+- **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
+- **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
+
+## Integration
+
+**Input**: Reference images or text prompts
+**Output**: `style-extraction/style-{N}/` with design-tokens.json + style-guide.md
+**Next**: `/workflow:ui-design:layout-extract --session {session_id}` OR `/workflow:ui-design:generate --session {session_id}`
+
+**Note**: This command extracts visual style (colors, typography, spacing) and generates production-ready design systems. For layout structure extraction, use `/workflow:ui-design:layout-extract`.

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

@@ -1,23 +1,21 @@
 ---
 name: update
 description: Update brainstorming artifacts with finalized design system references
-usage: /workflow:ui-design:update --session <session_id> [--selected-prototypes "<list>"]
-argument-hint: "--session WFS-session-id [--selected-prototypes \"dashboard-variant-1,auth-variant-2\"]"
-examples:
-  - /workflow:ui-design:update --session WFS-auth
-  - /workflow:ui-design:update --session WFS-dashboard --selected-prototypes "dashboard-variant-1"
+argument-hint: --session <session_id> [--selected-prototypes "<list>"]
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Design Update Command
 
 ## Overview
+
 Synchronize finalized design system references to brainstorming artifacts, preparing them for `/workflow:plan` consumption. This command updates **references only** (via @ notation), not content duplication.
 
 ## Core Philosophy
+
 - **Reference-Only Updates**: Use @ references, no content duplication
 - **Main Claude Execution**: Direct updates by main Claude (no Agent handoff)
-- **Synthesis Alignment**: Update synthesis-specification.md UI/UX Guidelines section
+- **Synthesis Alignment**: Update role analysis documents UI/UX Guidelines section
 - **Plan-Ready Output**: Ensure design artifacts discoverable by task-generate
 - **Minimal Reading**: Verify file existence, don't read design content
 
@@ -27,65 +25,62 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 
 ```bash
 # Validate session
-CHECK: .workflow/.active-* marker files
-VALIDATE: session_id matches active session
+CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
 
-# Verify required design artifacts exist in latest design run
+# Verify design artifacts in latest design run
 latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
 
-# Detect design system structure (unified vs separate)
-IF exists({latest_design}/style-consolidation/design-tokens.json):
-    # Unified mode (single design system)
-    design_system_mode = "unified"
-    design_tokens_path = "style-consolidation/design-tokens.json"
-    style_guide_path = "style-consolidation/style-guide.md"
-ELSE IF exists({latest_design}/style-consolidation/style-1/design-tokens.json):
-    # Separate mode (per-style design systems)
-    design_system_mode = "separate"
-    design_tokens_path = "style-consolidation/style-1/design-tokens.json"
-    style_guide_path = "style-consolidation/style-1/style-guide.md"
+# Detect design system structure
+IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
+    design_system_mode = "separate"; design_tokens_path = "style-extraction/style-1/design-tokens.json"; style_guide_path = "style-extraction/style-1/style-guide.md"
 ELSE:
-    ERROR: "No design tokens found. Run /workflow:ui-design:consolidate first"
+    ERROR: "No design tokens found. Run /workflow:ui-design:style-extract first"
 
-VERIFY:
-- {latest_design}/{design_tokens_path}
-- {latest_design}/{style_guide_path}
-- {latest_design}/prototypes/*.html (at least one prototype)
+VERIFY: {latest_design}/{design_tokens_path}, {latest_design}/{style_guide_path}, {latest_design}/prototypes/*.html
 
-REPORT: "📋 Design system mode: {design_system_mode}"
-REPORT: "   Tokens: {design_tokens_path}"
+REPORT: "📋 Design system mode: {design_system_mode} | Tokens: {design_tokens_path}"
 
 # Prototype selection
-IF --selected-prototypes provided:
-    VALIDATE: Specified prototypes exist
-    selected_list = parse_comma_separated(--selected-prototypes)
-ELSE:
-    AUTO-SELECT: Use all generated prototypes
-    selected_list = Glob({latest_design}/prototypes/*.html)
+selected_list = --selected-prototypes ? parse_comma_separated(--selected-prototypes) : Glob({latest_design}/prototypes/*.html)
+VALIDATE: Specified prototypes exist IF --selected-prototypes
 
 REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
 ```
 
+### Phase 1.1: Memory Check (Skip if Already Updated)
+
+```bash
+# Check if role analysis documents contains current design run reference
+synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents"
+current_design_run = basename(latest_design)  # e.g., "design-run-20250109-143022"
+
+IF exists(synthesis_spec_path):
+    synthesis_content = Read(synthesis_spec_path)
+    IF "## UI/UX Guidelines" in synthesis_content AND current_design_run in synthesis_content:
+        REPORT: "✅ Design system references already updated (found in memory)"
+        REPORT: "   Skipping: Phase 2-5 (Load Target Artifacts, Update Synthesis, Update UI Designer Guide, Completion)"
+        EXIT 0
+```
+
 ### Phase 2: Load Target Artifacts Only
 
 **What to Load**: Only the files we need to **update**, not the design files we're referencing.
 
 ```bash
 # Load target brainstorming artifacts (files to be updated)
-Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
-Read(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md) [if exists]
+Read(.workflow/WFS-{session}/.brainstorming/role analysis documents)
+IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
 
 # Optional: Read prototype notes for descriptions (minimal context)
 FOR each selected_prototype IN selected_list:
-    Read(.workflow/WFS-{session}/.design/prototypes/{selected_prototype}-notes.md)
-    # Extract: layout_strategy, page_name only
-```
+    Read({latest_design}/prototypes/{selected_prototype}-notes.md)  # Extract: layout_strategy, page_name only
 
-**Note**: We do **NOT** read design-tokens.json, style-guide.md, or prototype HTML. We only verify they exist and generate @ references to them.
+# Note: Do NOT read design-tokens.json, style-guide.md, or prototype HTML. Only verify existence and generate @ references.
+```
 
 ### Phase 3: Update Synthesis Specification
 
-Update `.brainstorming/synthesis-specification.md` with design system references.
+Update `.brainstorming/role analysis documents` with design system references.
 
 **Target Section**: `## UI/UX Guidelines`
 
@@ -106,47 +101,98 @@ Update `.brainstorming/synthesis-specification.md` with design system references
 
 ### Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html
-  - Layout: {layout_strategy from notes}
+- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
 }
 
 ### Design System Assets
 ```json
-{
-  "design_tokens": "design-{run_id}/{design_tokens_path}",
-  "style_guide": "design-{run_id}/{style_guide_path}",
-  "design_system_mode": "{design_system_mode}",
-  "prototypes": [
-    {FOR each: "design-{run_id}/prototypes/{prototype}.html"}
-  ]
-}
+{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
 ```
 ```
 
 **Implementation**:
 ```bash
 # Option 1: Edit existing section
-Edit(
-  file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
-  old_string="## UI/UX Guidelines\n[existing content]",
-  new_string="## UI/UX Guidelines\n\n[new design reference content]"
-)
+Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents",
+     old_string="## UI/UX Guidelines\n[existing content]",
+     new_string="## UI/UX Guidelines\n\n[new design reference content]")
 
 # Option 2: Append if section doesn't exist
 IF section not found:
-    Edit(
-      file_path=".workflow/WFS-{session}/.brainstorming/synthesis-specification.md",
-      old_string="[end of document]",
-      new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]"
-    )
+    Edit(file_path="...", old_string="[end of document]", new_string="\n\n## UI/UX Guidelines\n\n[new design reference content]")
 ```
 
-### Phase 4: Update UI Designer Style Guide
+### Phase 4A: Update Relevant Role Analysis Documents
 
-Create or update `.brainstorming/ui-designer/style-guide.md`:
+**Discovery**: Find role analysis.md files affected by design outputs
+
+```bash
+# Always update ui-designer
+ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
+
+# Conditionally update other roles
+has_animations = exists({latest_design}/animation-extraction/animation-tokens.json)
+has_layouts = exists({latest_design}/layout-extraction/layout-templates.json)
+
+IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
+IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md")
+IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md")
+```
+
+**Content Templates**:
+
+**ui-designer/analysis.md** (append if not exists):
+```markdown
+## Design System Implementation Reference
+
+**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
+**Style Guide**: @../../design-{run_id}/{style_guide_path}
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**ux-expert/analysis.md** (if animations):
+```markdown
+## Animation & Interaction Reference
+
+**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**system-architect/analysis.md** (if layouts):
+```markdown
+## Layout Structure Reference
+
+**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**product-manager/analysis.md** (if prototypes):
+```markdown
+## Prototype Validation Reference
+
+**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+
+*Reference added by /workflow:ui-design:update*
+```
+
+**Implementation**:
+```bash
+FOR file IN [ui_designer_files, ux_expert_files, architect_files, pm_files]:
+  IF file exists AND section_not_exists(file):
+    Edit(file, old_string="[end of document]", new_string="\n\n{role-specific section}")
+```
+
+### Phase 4B: Create UI Designer Design System Reference
+
+Create or update `.brainstorming/ui-designer/design-system-reference.md`:
 
 ```markdown
-# UI Designer Style Guide
+# UI Designer Design System Reference
 
 ## Design System Integration
 This style guide references the finalized design system from the design refinement phase.
@@ -172,29 +218,25 @@ For complete token definitions and usage examples, see:
 - Style Guide: @../../design-{run_id}/{style_guide_path}
 
 ---
-*Auto-generated by /workflow:ui-design:update*
-*Last updated: {timestamp}*
+*Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
 ```
 
 **Implementation**:
 ```bash
-Write(
-  file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/style-guide.md",
-  content="[generated content with @ references]"
-)
+Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
+      content="[generated content with @ references]")
 ```
 
 ### Phase 5: Completion
 
 ```javascript
-TodoWrite({
-  todos: [
-    {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
-    {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
-    {content: "Update synthesis-specification.md with design references", status: "completed", activeForm: "Updating synthesis spec"},
-    {content: "Create/update ui-designer/style-guide.md", status: "completed", activeForm: "Updating UI designer guide"}
-  ]
-});
+TodoWrite({todos: [
+  {content: "Validate session and design system artifacts", status: "completed", activeForm: "Validating artifacts"},
+  {content: "Load target brainstorming artifacts", status: "completed", activeForm: "Loading target files"},
+  {content: "Update role analysis documents with design references", status: "completed", activeForm: "Updating synthesis spec"},
+  {content: "Update relevant role analysis.md documents", status: "completed", activeForm: "Updating role analysis files"},
+  {content: "Create/update ui-designer/design-system-reference.md", status: "completed", activeForm: "Creating design system reference"}
+]});
 ```
 
 **Completion Message**:
@@ -202,13 +244,12 @@ TodoWrite({
 ✅ Design system references updated for session: WFS-{session}
 
 Updated artifacts:
-✓ synthesis-specification.md - UI/UX Guidelines section with @ references
-✓ ui-designer/style-guide.md - Design system reference guide
+✓ role analysis documents - UI/UX Guidelines section with @ references
+✓ {role_count} role analysis.md files - Design system references
+✓ ui-designer/design-system-reference.md - Design system reference guide
 
 Design system assets ready for /workflow:plan:
-- design-tokens.json
-- style-guide.md
-- {prototype_count} reference prototypes
+- design-tokens.json | style-guide.md | {prototype_count} reference prototypes
 
 Next: /workflow:plan [--agent] "<task description>"
       The plan phase will automatically discover and utilize the design system.
@@ -219,22 +260,34 @@ Next: /workflow:plan [--agent] "<task description>"
 **Updated Files**:
 ```
 .workflow/WFS-{session}/.brainstorming/
-├── synthesis-specification.md       # Updated with UI/UX Guidelines section
-└── ui-designer/
-    └── style-guide.md               # New or updated design reference guide
+├── role analysis documents              # Updated with UI/UX Guidelines section
+├── ui-designer/
+│   ├── analysis*.md                     # Updated with design system references
+│   └── design-system-reference.md       # New or updated design reference guide
+├── ux-expert/analysis*.md               # Updated if animations exist
+├── product-manager/analysis*.md         # Updated if prototypes exist
+└── system-architect/analysis*.md        # Updated if layouts exist
 ```
 
-**@ Reference Format** (used in synthesis-specification.md):
+**@ Reference Format** (role analysis documents):
 ```
-@../design-{run_id}/style-consolidation/design-tokens.json
-@../design-{run_id}/style-consolidation/style-guide.md
+@../design-{run_id}/style-extraction/style-1/design-tokens.json
+@../design-{run_id}/style-extraction/style-1/style-guide.md
 @../design-{run_id}/prototypes/{prototype}.html
 ```
 
-**@ Reference Format** (used in ui-designer/style-guide.md):
+**@ Reference Format** (ui-designer/design-system-reference.md):
 ```
-@../../design-{run_id}/style-consolidation/design-tokens.json
-@../../design-{run_id}/style-consolidation/style-guide.md
+@../../design-{run_id}/style-extraction/style-1/design-tokens.json
+@../../design-{run_id}/style-extraction/style-1/style-guide.md
+@../../design-{run_id}/prototypes/{prototype}.html
+```
+
+**@ Reference Format** (role analysis.md files):
+```
+@../../design-{run_id}/style-extraction/style-1/design-tokens.json
+@../../design-{run_id}/animation-extraction/animation-tokens.json
+@../../design-{run_id}/layout-extraction/layout-templates.json
 @../../design-{run_id}/prototypes/{prototype}.html
 ```
 
@@ -243,14 +296,10 @@ Next: /workflow:plan [--agent] "<task description>"
 After this update, `/workflow:plan` will discover design assets through:
 
 **Phase 3: Intelligent Analysis** (`/workflow:tools:concept-enhanced`)
-- Reads synthesis-specification.md
-- Discovers @ references to design system files
-- Includes design system context in ANALYSIS_RESULTS.md
+- Reads role analysis documents → Discovers @ references → Includes design system context in ANALYSIS_RESULTS.md
 
 **Phase 4: Task Generation** (`/workflow:tools:task-generate`)
-- Reads ANALYSIS_RESULTS.md
-- Discovers design assets from synthesis-specification.md
-- Includes design system paths in task JSON files
+- Reads ANALYSIS_RESULTS.md → Discovers design assets → Includes design system paths in task JSON files
 
 **Example Task JSON** (generated by task-generate):
 ```json
@@ -258,8 +307,8 @@ After this update, `/workflow:plan` will discover design assets through:
   "task_id": "IMPL-001",
   "context": {
     "design_system": {
-      "tokens": "design-{run_id}/style-consolidation/design-tokens.json",
-      "style_guide": "design-{run_id}/style-consolidation/style-guide.md",
+      "tokens": "design-{run_id}/style-extraction/style-1/design-tokens.json",
+      "style_guide": "design-{run_id}/style-extraction/style-1/style-guide.md",
       "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
     }
   }
@@ -268,8 +317,8 @@ After this update, `/workflow:plan` will discover design assets through:
 
 ## Error Handling
 
-- **Missing design artifacts**: Error with message "Run /workflow:ui-design:consolidate and /workflow:ui-design:generate first"
-- **synthesis-specification.md not found**: Warning, create minimal version with just UI/UX Guidelines
+- **Missing design artifacts**: Error with message "Run /workflow:ui-design:style-extract and /workflow:ui-design:generate first"
+- **role analysis documents not found**: Warning, create minimal version with just UI/UX Guidelines
 - **ui-designer/ directory missing**: Create directory and file
 - **Edit conflicts**: Preserve existing content, append or replace only UI/UX Guidelines section
 - **Invalid prototype names**: Skip invalid entries, continue with valid ones
@@ -277,43 +326,26 @@ After this update, `/workflow:plan` will discover design assets through:
 ## Validation Checks
 
 After update, verify:
-- [ ] synthesis-specification.md contains UI/UX Guidelines section
+- [ ] role analysis documents contains UI/UX Guidelines section
 - [ ] UI/UX Guidelines include @ references (not content duplication)
-- [ ] ui-designer/style-guide.md created or updated
+- [ ] ui-designer/analysis*.md updated with design system references
+- [ ] ui-designer/design-system-reference.md created or updated
+- [ ] Relevant role analysis.md files updated (ux-expert, product-manager, system-architect)
 - [ ] All @ referenced files exist and are accessible
 - [ ] @ reference paths are relative and correct
 
 ## Key Features
 
-1. **Reference-Only Updates**
-   - Uses @ notation for file references
-   - No content duplication between design and brainstorming spaces
-   - Lightweight, maintainable approach
-
-2. **Main Claude Direct Execution**
-   - No Agent handoff (preserves context)
-   - Simple reference generation (no complex synthesis)
-   - Reliable path resolution
-
-3. **Plan-Ready Output**
-   - `/workflow:plan` Phase 3 can discover design system
-   - Task generation includes design asset paths
-   - Clear integration points for implementation tasks
-
-4. **Minimal Reading**
-   - Only reads target files to update (synthesis-specification.md, ui-designer/analysis.md)
-   - Verifies design file existence (no content reading)
-   - Optional: reads prototype notes for descriptions
-
-5. **Flexible Prototype Selection**
-   - Auto-select all prototypes (default)
-   - Manual selection via --selected-prototypes parameter
-   - Validates prototype existence before referencing
+1. **Reference-Only Updates**: Uses @ notation for file references, no content duplication, lightweight and maintainable
+2. **Main Claude Direct Execution**: No Agent handoff (preserves context), simple reference generation, reliable path resolution
+3. **Plan-Ready Output**: `/workflow:plan` Phase 3 can discover design system, task generation includes design asset paths, clear integration points
+4. **Minimal Reading**: Only reads target files to update, verifies design file existence (no content reading), optional prototype notes for descriptions
+5. **Flexible Prototype Selection**: Auto-select all prototypes (default), manual selection via --selected-prototypes parameter, validates existence
 
 ## Integration Points
 
-- **Input**: Design system artifacts from `/workflow:ui-design:consolidate` and `/workflow:ui-design:generate`
-- **Output**: Updated synthesis-specification.md, ui-designer/style-guide.md with @ references
+- **Input**: Design system artifacts from `/workflow:ui-design:style-extract` and `/workflow:ui-design:generate`
+- **Output**: Updated role analysis documents, role analysis.md files, ui-designer/design-system-reference.md with @ references
 - **Next Phase**: `/workflow:plan` discovers and utilizes design system through @ references
 - **Auto Integration**: Automatically triggered by `/workflow:ui-design:auto` workflow
 

.claude/scripts/classify-folders.sh

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

.claude/scripts/detect_changed_modules.sh

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

.claude/scripts/extract-animations.js

@@ -0,0 +1,243 @@
+/**
+ * Animation & Transition Extraction Script
+ *
+ * Extracts CSS animations, transitions, and transform patterns from a live web page.
+ * This script runs in the browser context via Chrome DevTools Protocol.
+ *
+ * @returns {Object} Structured animation data
+ */
+(() => {
+  const extractionTimestamp = new Date().toISOString();
+  const currentUrl = window.location.href;
+
+  /**
+   * Parse transition shorthand or individual properties
+   */
+  function parseTransition(element, computedStyle) {
+    const transition = computedStyle.transition || computedStyle.webkitTransition;
+
+    if (!transition || transition === 'none' || transition === 'all 0s ease 0s') {
+      return null;
+    }
+
+    // Parse shorthand: "property duration easing delay"
+    const transitions = [];
+    const parts = transition.split(/,\s*/);
+
+    parts.forEach(part => {
+      const match = part.match(/^(\S+)\s+([\d.]+m?s)\s+(\S+)(?:\s+([\d.]+m?s))?/);
+      if (match) {
+        transitions.push({
+          property: match[1],
+          duration: match[2],
+          easing: match[3],
+          delay: match[4] || '0s'
+        });
+      }
+    });
+
+    return transitions.length > 0 ? transitions : null;
+  }
+
+  /**
+   * Extract animation name and properties
+   */
+  function parseAnimation(element, computedStyle) {
+    const animationName = computedStyle.animationName || computedStyle.webkitAnimationName;
+
+    if (!animationName || animationName === 'none') {
+      return null;
+    }
+
+    return {
+      name: animationName,
+      duration: computedStyle.animationDuration || computedStyle.webkitAnimationDuration,
+      easing: computedStyle.animationTimingFunction || computedStyle.webkitAnimationTimingFunction,
+      delay: computedStyle.animationDelay || computedStyle.webkitAnimationDelay || '0s',
+      iterationCount: computedStyle.animationIterationCount || computedStyle.webkitAnimationIterationCount || '1',
+      direction: computedStyle.animationDirection || computedStyle.webkitAnimationDirection || 'normal',
+      fillMode: computedStyle.animationFillMode || computedStyle.webkitAnimationFillMode || 'none'
+    };
+  }
+
+  /**
+   * Extract transform value
+   */
+  function parseTransform(computedStyle) {
+    const transform = computedStyle.transform || computedStyle.webkitTransform;
+
+    if (!transform || transform === 'none') {
+      return null;
+    }
+
+    return transform;
+  }
+
+  /**
+   * Get element selector (simplified for readability)
+   */
+  function getSelector(element) {
+    if (element.id) {
+      return `#${element.id}`;
+    }
+
+    if (element.className && typeof element.className === 'string') {
+      const classes = element.className.trim().split(/\s+/).slice(0, 2).join('.');
+      if (classes) {
+        return `.${classes}`;
+      }
+    }
+
+    return element.tagName.toLowerCase();
+  }
+
+  /**
+   * Extract all stylesheets and find @keyframes rules
+   */
+  function extractKeyframes() {
+    const keyframes = {};
+
+    try {
+      // Iterate through all stylesheets
+      Array.from(document.styleSheets).forEach(sheet => {
+        try {
+          // Skip external stylesheets due to CORS
+          if (sheet.href && !sheet.href.startsWith(window.location.origin)) {
+            return;
+          }
+
+          Array.from(sheet.cssRules || sheet.rules || []).forEach(rule => {
+            // Check for @keyframes rules
+            if (rule.type === CSSRule.KEYFRAMES_RULE || rule.type === CSSRule.WEBKIT_KEYFRAMES_RULE) {
+              const name = rule.name;
+              const frames = {};
+
+              Array.from(rule.cssRules || []).forEach(keyframe => {
+                const key = keyframe.keyText; // e.g., "0%", "50%", "100%"
+                frames[key] = keyframe.style.cssText;
+              });
+
+              keyframes[name] = frames;
+            }
+          });
+        } catch (e) {
+          // Skip stylesheets that can't be accessed (CORS)
+          console.warn('Cannot access stylesheet:', sheet.href, e.message);
+        }
+      });
+    } catch (e) {
+      console.error('Error extracting keyframes:', e);
+    }
+
+    return keyframes;
+  }
+
+  /**
+   * Scan visible elements for animations and transitions
+   */
+  function scanElements() {
+    const elements = document.querySelectorAll('*');
+    const transitionData = [];
+    const animationData = [];
+    const transformData = [];
+
+    const uniqueTransitions = new Set();
+    const uniqueAnimations = new Set();
+    const uniqueEasings = new Set();
+    const uniqueDurations = new Set();
+
+    elements.forEach(element => {
+      // Skip invisible elements
+      const rect = element.getBoundingClientRect();
+      if (rect.width === 0 && rect.height === 0) {
+        return;
+      }
+
+      const computedStyle = window.getComputedStyle(element);
+
+      // Extract transitions
+      const transitions = parseTransition(element, computedStyle);
+      if (transitions) {
+        const selector = getSelector(element);
+        transitions.forEach(t => {
+          const key = `${t.property}-${t.duration}-${t.easing}`;
+          if (!uniqueTransitions.has(key)) {
+            uniqueTransitions.add(key);
+            transitionData.push({
+              selector,
+              ...t
+            });
+            uniqueEasings.add(t.easing);
+            uniqueDurations.add(t.duration);
+          }
+        });
+      }
+
+      // Extract animations
+      const animation = parseAnimation(element, computedStyle);
+      if (animation) {
+        const selector = getSelector(element);
+        const key = `${animation.name}-${animation.duration}`;
+        if (!uniqueAnimations.has(key)) {
+          uniqueAnimations.add(key);
+          animationData.push({
+            selector,
+            ...animation
+          });
+          uniqueEasings.add(animation.easing);
+          uniqueDurations.add(animation.duration);
+        }
+      }
+
+      // Extract transforms (on hover/active, we only get current state)
+      const transform = parseTransform(computedStyle);
+      if (transform) {
+        const selector = getSelector(element);
+        transformData.push({
+          selector,
+          transform
+        });
+      }
+    });
+
+    return {
+      transitions: transitionData,
+      animations: animationData,
+      transforms: transformData,
+      uniqueEasings: Array.from(uniqueEasings),
+      uniqueDurations: Array.from(uniqueDurations)
+    };
+  }
+
+  /**
+   * Main extraction function
+   */
+  function extractAnimations() {
+    const elementData = scanElements();
+    const keyframes = extractKeyframes();
+
+    return {
+      metadata: {
+        timestamp: extractionTimestamp,
+        url: currentUrl,
+        method: 'chrome-devtools',
+        version: '1.0.0'
+      },
+      transitions: elementData.transitions,
+      animations: elementData.animations,
+      transforms: elementData.transforms,
+      keyframes: keyframes,
+      summary: {
+        total_transitions: elementData.transitions.length,
+        total_animations: elementData.animations.length,
+        total_transforms: elementData.transforms.length,
+        total_keyframes: Object.keys(keyframes).length,
+        unique_easings: elementData.uniqueEasings,
+        unique_durations: elementData.uniqueDurations
+      }
+    };
+  }
+
+  // Execute extraction
+  return extractAnimations();
+})();

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

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

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

@@ -0,0 +1,411 @@
+/**
+ * Extract Layout Structure from DOM - Enhanced Version
+ *
+ * Extracts real layout information from DOM to provide accurate
+ * structural data for UI replication.
+ *
+ * Features:
+ * - Framework detection (Nuxt.js, Next.js, React, Vue, Angular)
+ * - Multi-strategy container detection (strict → relaxed → class-based → framework-specific)
+ * - Intelligent main content detection with common class names support
+ * - Supports modern SPA frameworks
+ * - Detects non-semantic main containers (.main, .content, etc.)
+ * - Progressive exploration: Auto-discovers missing selectors when standard patterns fail
+ * - Suggests new class names to add to script based on actual page structure
+ *
+ * Progressive Exploration:
+ * When fewer than 3 main containers are found, the script automatically:
+ * 1. Analyzes all large visible containers (≥500×300px)
+ * 2. Extracts class name patterns (main/content/wrapper/container/page/etc.)
+ * 3. Suggests new selectors to add to the script
+ * 4. Returns exploration data in result.exploration
+ *
+ * Usage: Execute via Chrome DevTools evaluate_script
+ * Version: 2.2.0
+ */
+
+(() => {
+  /**
+   * Get element's bounding box relative to viewport
+   */
+  const getBounds = (element) => {
+    const rect = element.getBoundingClientRect();
+    return {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: Math.round(rect.width),
+      height: Math.round(rect.height)
+    };
+  };
+
+  /**
+   * Extract layout properties from an element
+   */
+  const extractLayoutProps = (element) => {
+    const s = window.getComputedStyle(element);
+
+    return {
+      // Core layout
+      display: s.display,
+      position: s.position,
+
+      // Flexbox
+      flexDirection: s.flexDirection,
+      justifyContent: s.justifyContent,
+      alignItems: s.alignItems,
+      flexWrap: s.flexWrap,
+      gap: s.gap,
+
+      // Grid
+      gridTemplateColumns: s.gridTemplateColumns,
+      gridTemplateRows: s.gridTemplateRows,
+      gridAutoFlow: s.gridAutoFlow,
+
+      // Dimensions
+      width: s.width,
+      height: s.height,
+      maxWidth: s.maxWidth,
+      minWidth: s.minWidth,
+
+      // Spacing
+      padding: s.padding,
+      margin: s.margin
+    };
+  };
+
+  /**
+   * Identify layout pattern for an element
+   */
+  const identifyPattern = (props) => {
+    const { display, flexDirection, gridTemplateColumns } = props;
+
+    if (display === 'flex' || display === 'inline-flex') {
+      if (flexDirection === 'column') return 'flex-column';
+      if (flexDirection === 'row') return 'flex-row';
+      return 'flex';
+    }
+
+    if (display === 'grid') {
+      const cols = gridTemplateColumns;
+      if (cols && cols !== 'none') {
+        const colCount = cols.split(' ').length;
+        return `grid-${colCount}col`;
+      }
+      return 'grid';
+    }
+
+    if (display === 'block') return 'block';
+
+    return display;
+  };
+
+  /**
+   * Detect frontend framework
+   */
+  const detectFramework = () => {
+    if (document.querySelector('#__nuxt')) return { name: 'Nuxt.js', version: 'unknown' };
+    if (document.querySelector('#__next')) return { name: 'Next.js', version: 'unknown' };
+    if (document.querySelector('[data-reactroot]')) return { name: 'React', version: 'unknown' };
+    if (document.querySelector('[ng-version]')) return { name: 'Angular', version: 'unknown' };
+    if (window.Vue) return { name: 'Vue.js', version: window.Vue.version || 'unknown' };
+    return { name: 'Unknown', version: 'unknown' };
+  };
+
+  /**
+   * Build layout tree recursively
+   */
+  const buildLayoutTree = (element, depth = 0, maxDepth = 3) => {
+    if (depth > maxDepth) return null;
+
+    const props = extractLayoutProps(element);
+    const bounds = getBounds(element);
+    const pattern = identifyPattern(props);
+
+    // Get semantic role
+    const tagName = element.tagName.toLowerCase();
+    const classes = Array.from(element.classList).slice(0, 3); // Max 3 classes
+    const role = element.getAttribute('role');
+
+    // Build node
+    const node = {
+      tag: tagName,
+      classes: classes,
+      role: role,
+      pattern: pattern,
+      bounds: bounds,
+      layout: {
+        display: props.display,
+        position: props.position
+      }
+    };
+
+    // Add flex/grid specific properties
+    if (props.display === 'flex' || props.display === 'inline-flex') {
+      node.layout.flexDirection = props.flexDirection;
+      node.layout.justifyContent = props.justifyContent;
+      node.layout.alignItems = props.alignItems;
+      node.layout.gap = props.gap;
+    }
+
+    if (props.display === 'grid') {
+      node.layout.gridTemplateColumns = props.gridTemplateColumns;
+      node.layout.gridTemplateRows = props.gridTemplateRows;
+      node.layout.gap = props.gap;
+    }
+
+    // Process children for container elements
+    if (props.display === 'flex' || props.display === 'grid' || props.display === 'block') {
+      const children = Array.from(element.children);
+      if (children.length > 0 && children.length < 50) { // Limit to 50 children
+        node.children = children
+          .map(child => buildLayoutTree(child, depth + 1, maxDepth))
+          .filter(child => child !== null);
+      }
+    }
+
+    return node;
+  };
+
+  /**
+   * Find main layout containers with multi-strategy approach
+   */
+  const findMainContainers = () => {
+    const containers = [];
+    const found = new Set();
+
+    // Strategy 1: Strict selectors (body direct children)
+    const strictSelectors = [
+      'body > header',
+      'body > nav',
+      'body > main',
+      'body > footer'
+    ];
+
+    // Strategy 2: Relaxed selectors (any level)
+    const relaxedSelectors = [
+      'header',
+      'nav',
+      'main',
+      'footer',
+      '[role="banner"]',
+      '[role="navigation"]',
+      '[role="main"]',
+      '[role="contentinfo"]'
+    ];
+
+    // Strategy 3: Common class-based main content selectors
+    const commonClassSelectors = [
+      '.main',
+      '.content',
+      '.main-content',
+      '.page-content',
+      '.container.main',
+      '.wrapper > .main',
+      'div[class*="main-wrapper"]',
+      'div[class*="content-wrapper"]'
+    ];
+
+    // Strategy 4: Framework-specific selectors
+    const frameworkSelectors = [
+      '#__nuxt header', '#__nuxt .main', '#__nuxt main', '#__nuxt footer',
+      '#__next header', '#__next .main', '#__next main', '#__next footer',
+      '#app header', '#app .main', '#app main', '#app footer',
+      '[data-app] header', '[data-app] .main', '[data-app] main', '[data-app] footer'
+    ];
+
+    // Try all strategies
+    const allSelectors = [...strictSelectors, ...relaxedSelectors, ...commonClassSelectors, ...frameworkSelectors];
+
+    allSelectors.forEach(selector => {
+      try {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach(element => {
+          // Avoid duplicates and invisible elements
+          if (!found.has(element) && element.offsetParent !== null) {
+            found.add(element);
+            const tree = buildLayoutTree(element, 0, 3);
+            if (tree && tree.bounds.width > 0 && tree.bounds.height > 0) {
+              containers.push(tree);
+            }
+          }
+        });
+      } catch (e) {
+        console.warn(`Selector failed: ${selector}`, e);
+      }
+    });
+
+    // Fallback: If no containers found, use body's direct children
+    if (containers.length === 0) {
+      Array.from(document.body.children).forEach(child => {
+        if (child.offsetParent !== null && !found.has(child)) {
+          const tree = buildLayoutTree(child, 0, 2);
+          if (tree && tree.bounds.width > 100 && tree.bounds.height > 100) {
+            containers.push(tree);
+          }
+        }
+      });
+    }
+
+    return containers;
+  };
+
+  /**
+   * Progressive exploration: Discover main containers when standard selectors fail
+   * Analyzes large visible containers and suggests class name patterns
+   */
+  const exploreMainContainers = () => {
+    const candidates = [];
+    const minWidth = 500;
+    const minHeight = 300;
+
+    // Find all large visible divs
+    const allDivs = document.querySelectorAll('div');
+    allDivs.forEach(div => {
+      const rect = div.getBoundingClientRect();
+      const style = window.getComputedStyle(div);
+
+      // Filter: large size, visible, not header/footer
+      if (rect.width >= minWidth &&
+          rect.height >= minHeight &&
+          div.offsetParent !== null &&
+          !div.closest('header') &&
+          !div.closest('footer')) {
+
+        const classes = Array.from(div.classList);
+        const area = rect.width * rect.height;
+
+        candidates.push({
+          element: div,
+          classes: classes,
+          area: area,
+          bounds: {
+            width: Math.round(rect.width),
+            height: Math.round(rect.height)
+          },
+          display: style.display,
+          depth: getElementDepth(div)
+        });
+      }
+    });
+
+    // Sort by area (largest first) and take top candidates
+    candidates.sort((a, b) => b.area - a.area);
+
+    // Extract unique class patterns from top candidates
+    const classPatterns = new Set();
+    candidates.slice(0, 20).forEach(c => {
+      c.classes.forEach(cls => {
+        // Identify potential main content class patterns
+        if (cls.match(/main|content|container|wrapper|page|body|layout|app/i)) {
+          classPatterns.add(cls);
+        }
+      });
+    });
+
+    return {
+      candidates: candidates.slice(0, 10).map(c => ({
+        classes: c.classes,
+        bounds: c.bounds,
+        display: c.display,
+        depth: c.depth
+      })),
+      suggestedSelectors: Array.from(classPatterns).map(cls => `.${cls}`)
+    };
+  };
+
+  /**
+   * Get element depth in DOM tree
+   */
+  const getElementDepth = (element) => {
+    let depth = 0;
+    let current = element;
+    while (current.parentElement) {
+      depth++;
+      current = current.parentElement;
+    }
+    return depth;
+  };
+
+  /**
+   * Analyze layout patterns
+   */
+  const analyzePatterns = (containers) => {
+    const patterns = {
+      flexColumn: 0,
+      flexRow: 0,
+      grid: 0,
+      sticky: 0,
+      fixed: 0
+    };
+
+    const analyze = (node) => {
+      if (!node) return;
+
+      if (node.pattern === 'flex-column') patterns.flexColumn++;
+      if (node.pattern === 'flex-row') patterns.flexRow++;
+      if (node.pattern && node.pattern.startsWith('grid')) patterns.grid++;
+      if (node.layout.position === 'sticky') patterns.sticky++;
+      if (node.layout.position === 'fixed') patterns.fixed++;
+
+      if (node.children) {
+        node.children.forEach(analyze);
+      }
+    };
+
+    containers.forEach(analyze);
+    return patterns;
+  };
+
+  /**
+   * Main extraction function with progressive exploration
+   */
+  const extractLayout = () => {
+    const framework = detectFramework();
+    const containers = findMainContainers();
+    const patterns = analyzePatterns(containers);
+
+    // Progressive exploration: if too few containers found, explore and suggest
+    let exploration = null;
+    const minExpectedContainers = 3; // At least header, main, footer
+
+    if (containers.length < minExpectedContainers) {
+      exploration = exploreMainContainers();
+
+      // Add warning message
+      exploration.warning = `Only ${containers.length} containers found. Consider adding these selectors to the script:`;
+      exploration.recommendation = exploration.suggestedSelectors.join(', ');
+    }
+
+    const result = {
+      metadata: {
+        extractedAt: new Date().toISOString(),
+        url: window.location.href,
+        framework: framework,
+        method: 'layout-structure-enhanced',
+        version: '2.2.0'
+      },
+      statistics: {
+        totalContainers: containers.length,
+        patterns: patterns
+      },
+      structure: containers
+    };
+
+    // Add exploration results if triggered
+    if (exploration) {
+      result.exploration = {
+        triggered: true,
+        reason: 'Insufficient containers found with standard selectors',
+        discoveredCandidates: exploration.candidates,
+        suggestedSelectors: exploration.suggestedSelectors,
+        warning: exploration.warning,
+        recommendation: exploration.recommendation
+      };
+    }
+
+    return result;
+  };
+
+  // Execute and return results
+  return extractLayout();
+})();

.claude/scripts/gemini-wrapper

@@ -1,282 +0,0 @@
-#!/bin/bash
-# gemini-wrapper - Token-aware wrapper for gemini command
-# Location: ~/.claude/scripts/gemini-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: gemini-wrapper [all gemini options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "gemini-wrapper - Token-aware wrapper for gemini command"
-    echo ""
-    echo "Usage: gemini-wrapper [options] [gemini options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set GEMINI_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  gemini-wrapper -p \"Analyze the codebase structure\""
-    echo "  gemini-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  gemini-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${GEMINI_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Function to count tokens (approximate: chars/4) - optimized version
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-
-    # Use single find with bulk wc for better performance
-    # Common source file extensions
-    local extensions="py js ts tsx jsx java cpp c h rs go md txt json yaml yml xml html css scss sass php rb sh bash"
-
-    # Build find command with extension patterns
-    local find_cmd="find . -type f \("
-    local first=true
-    for ext in $extensions; do
-        if [[ "$first" == true ]]; then
-            find_cmd+=" -name \"*.$ext\""
-            first=false
-        else
-            find_cmd+=" -o -name \"*.$ext\""
-        fi
-    done
-    find_cmd+=" \)"
-
-    # Exclude common build/cache directories
-    find_cmd+=" -not -path \"*/node_modules/*\""
-    find_cmd+=" -not -path \"*/.git/*\""
-    find_cmd+=" -not -path \"*/dist/*\""
-    find_cmd+=" -not -path \"*/build/*\""
-    find_cmd+=" -not -path \"*/.next/*\""
-    find_cmd+=" -not -path \"*/.nuxt/*\""
-    find_cmd+=" -not -path \"*/target/*\""
-    find_cmd+=" -not -path \"*/vendor/*\""
-    find_cmd+=" -not -path \"*/__pycache__/*\""
-    find_cmd+=" -not -path \"*/.cache/*\""
-    find_cmd+=" 2>/dev/null"
-
-    # Use efficient bulk processing with wc
-    if command -v wc >/dev/null 2>&1; then
-        # Try bulk wc first - much faster for many files
-        local wc_output
-        wc_output=$(eval "$find_cmd" | xargs wc -c 2>/dev/null | tail -n 1)
-
-        # Parse the total line (last line of wc output when processing multiple files)
-        if [[ -n "$wc_output" && "$wc_output" =~ ^[[:space:]]*([0-9]+)[[:space:]]+total[[:space:]]*$ ]]; then
-            total_chars="${BASH_REMATCH[1]}"
-            file_count=$(eval "$find_cmd" | wc -l 2>/dev/null || echo 0)
-        else
-            # Fallback: single file processing
-            while IFS= read -r file; do
-                if [[ -f "$file" && -r "$file" ]]; then
-                    local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-                    total_chars=$((total_chars + chars))
-                    file_count=$((file_count + 1))
-                fi
-            done < <(eval "$find_cmd")
-        fi
-    else
-        # No wc available - fallback method
-        while IFS= read -r file; do
-            if [[ -f "$file" && -r "$file" ]]; then
-                local chars=$(stat -c%s "$file" 2>/dev/null || echo 0)
-                total_chars=$((total_chars + chars))
-                file_count=$((file_count + 1))
-            fi
-        done < <(eval "$find_cmd")
-    fi
-
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-args=()
-i=0
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: gemini ${args[*]}${NC}" >&2
-
-# Execute gemini with adjusted arguments (we're already in the right directory)
-gemini "${args[@]}"

.claude/scripts/get_modules_by_depth.sh

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

.claude/scripts/qwen-wrapper

@@ -1,228 +0,0 @@
-#!/bin/bash
-# qwen-wrapper - Token-aware wrapper for qwen command
-# Location: ~/.claude/scripts/qwen-wrapper
-#
-# This wrapper automatically manages --all-files flag based on project token count
-# and provides intelligent approval mode defaults
-#
-# Usage: qwen-wrapper [all qwen options]
-#
-# Approval Mode Options:
-#   --approval-mode default    : Prompt for approval on each tool call (default)
-#   --approval-mode auto_edit  : Auto-approve edit tools, prompt for others
-#   --approval-mode yolo       : Auto-approve all tool calls
-#
-# Note: Executes in current working directory
-
-set -e
-
-# Function to show help
-show_help() {
-    echo "qwen-wrapper - Token-aware wrapper for qwen command"
-    echo ""
-    echo "Usage: qwen-wrapper [options] [qwen options]"
-    echo ""
-    echo "Options:"
-    echo "  --approval-mode <mode>  Sets the approval mode for tool calls"
-    echo "                          Available modes:"
-    echo "                            default    : Prompt for approval on each tool call (default)"
-    echo "                            auto_edit  : Auto-approve edit tools, prompt for others"
-    echo "                            yolo       : Auto-approve all tool calls"
-    echo "  --help                  Show this help message"
-    echo ""
-    echo "Features:"
-    echo "  - Automatically manages --all-files flag based on project token count"
-    echo "  - Intelligent approval mode detection based on task type"
-    echo "  - Token limit: $DEFAULT_TOKEN_LIMIT (set QWEN_TOKEN_LIMIT to override)"
-    echo ""
-    echo "Examples:"
-    echo "  qwen-wrapper -p \"Analyze the codebase structure\""
-    echo "  qwen-wrapper --approval-mode yolo -p \"Implement user authentication\""
-    echo "  qwen-wrapper --approval-mode auto_edit -p \"Fix all linting errors\""
-    echo ""
-}
-
-# Function to validate approval mode
-validate_approval_mode() {
-    local mode="$1"
-    case "$mode" in
-        "default"|"auto_edit"|"yolo")
-            return 0
-            ;;
-        *)
-            echo -e "${RED}❌ Invalid approval mode: $mode${NC}" >&2
-            echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-            return 1
-            ;;
-    esac
-}
-
-# Configuration
-DEFAULT_TOKEN_LIMIT=2000000
-TOKEN_LIMIT=${QWEN_TOKEN_LIMIT:-$DEFAULT_TOKEN_LIMIT}
-
-# Colors for output
-RED='\033[0;31m'
-GREEN='\033[0;32m'
-YELLOW='\033[1;33m'
-NC='\033[0m' # No Color
-
-# Function to count tokens (approximate: chars/4)
-count_tokens() {
-    local total_chars=0
-    local file_count=0
-    
-    # Count characters in common source files
-    while IFS= read -r -d '' file; do
-        if [[ -f "$file" && -r "$file" ]]; then
-            local chars=$(wc -c < "$file" 2>/dev/null || echo 0)
-            total_chars=$((total_chars + chars))
-            file_count=$((file_count + 1))
-        fi
-    done < <(find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.ts" -o -name "*.tsx" -o -name "*.jsx" -o -name "*.java" -o -name "*.cpp" -o -name "*.c" -o -name "*.h" -o -name "*.rs" -o -name "*.go" -o -name "*.md" -o -name "*.txt" -o -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.xml" -o -name "*.html" -o -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.php" -o -name "*.rb" -o -name "*.sh" -o -name "*.bash" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" -not -path "*/.nuxt/*" -not -path "*/target/*" -not -path "*/vendor/*" -print0 2>/dev/null)
-    
-    local estimated_tokens=$((total_chars / 4))
-    echo "$estimated_tokens $file_count"
-}
-
-# Parse arguments to check for flags
-has_all_files=false
-has_approval_mode=false
-approval_mode_value=""
-
-# Parse arguments with proper handling of --approval-mode value
-args=("$@")  # Start with all arguments
-parsed_args=()
-skip_next=false
-
-for ((i=0; i<${#args[@]}; i++)); do
-    if [[ "$skip_next" == true ]]; then
-        skip_next=false
-        continue
-    fi
-
-    arg="${args[i]}"
-    case "$arg" in
-        "--help"|"-h")
-            show_help
-            exit 0
-            ;;
-        "--all-files")
-            has_all_files=true
-            parsed_args+=("$arg")
-            ;;
-        "--approval-mode")
-            has_approval_mode=true
-            # Get the next argument as the mode value
-            if [[ $((i+1)) -lt ${#args[@]} ]]; then
-                approval_mode_value="${args[$((i+1))]}"
-                if validate_approval_mode "$approval_mode_value"; then
-                    parsed_args+=("$arg" "$approval_mode_value")
-                    skip_next=true
-                else
-                    exit 1
-                fi
-            else
-                echo -e "${RED}❌ --approval-mode requires a value${NC}" >&2
-                echo -e "${YELLOW}Valid modes: default, auto_edit, yolo${NC}" >&2
-                exit 1
-            fi
-            ;;
-        --approval-mode=*)
-            has_approval_mode=true
-            approval_mode_value="${arg#*=}"
-            if validate_approval_mode "$approval_mode_value"; then
-                parsed_args+=("$arg")
-            else
-                exit 1
-            fi
-            ;;
-        *)
-            parsed_args+=("$arg")
-            ;;
-    esac
-done
-
-# Replace args with parsed_args
-args=("${parsed_args[@]}")
-
-# Analyze current working directory
-echo -e "${GREEN}📁 Analyzing current directory: $(pwd)${NC}" >&2
-
-# Count tokens (in the target directory if -c was used)
-echo -e "${YELLOW}🔍 Analyzing project size...${NC}" >&2
-read -r token_count file_count <<< "$(count_tokens)"
-
-echo -e "${YELLOW}📊 Project stats: ~${token_count} tokens across ${file_count} files${NC}" >&2
-
-# Decision logic for --all-files flag
-if [[ $token_count -lt $TOKEN_LIMIT ]]; then
-    if [[ "$has_all_files" == false ]]; then
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Adding --all-files${NC}" >&2
-        args=("--all-files" "${args[@]}")
-    else
-        echo -e "${GREEN}✅ Small project (${token_count} < ${TOKEN_LIMIT} tokens): Keeping --all-files${NC}" >&2
-    fi
-else
-    if [[ "$has_all_files" == true ]]; then
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Removing --all-files to avoid token limits${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-        # Remove --all-files from args
-        new_args=()
-        for arg in "${args[@]}"; do
-            if [[ "$arg" != "--all-files" ]]; then
-                new_args+=("$arg")
-            fi
-        done
-        args=("${new_args[@]}")
-    else
-        echo -e "${RED}⚠️  Large project (${token_count} >= ${TOKEN_LIMIT} tokens): Avoiding --all-files${NC}" >&2
-        echo -e "${YELLOW}💡 Consider using specific @{patterns} for targeted analysis${NC}" >&2
-    fi
-fi
-
-# Auto-add approval-mode if not specified
-if [[ "$has_approval_mode" == false ]]; then
-    # Intelligent approval mode detection based on prompt content
-    prompt_text="${args[*]}"
-
-    # Analysis/Research tasks - use default (prompt for each tool)
-    if [[ "$prompt_text" =~ (analyze|analysis|review|understand|inspect|examine|research|study|explore|investigate) ]]; then
-        echo -e "${GREEN}📋 Analysis task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-
-    # Development/Edit tasks - use auto_edit (auto-approve edits, prompt for others)
-    elif [[ "$prompt_text" =~ (implement|create|build|develop|code|write|edit|modify|update|fix|refactor|generate) ]]; then
-        echo -e "${GREEN}🔧 Development task detected: Adding --approval-mode auto_edit${NC}" >&2
-        args=("--approval-mode" "auto_edit" "${args[@]}")
-
-    # Automation/Batch tasks - use yolo (auto-approve all)
-    elif [[ "$prompt_text" =~ (automate|batch|mass|bulk|all|execute|run|deploy|install|setup) ]]; then
-        echo -e "${YELLOW}⚡ Automation task detected: Adding --approval-mode yolo${NC}" >&2
-        args=("--approval-mode" "yolo" "${args[@]}")
-
-    # Default fallback - use default mode for safety
-    else
-        echo -e "${YELLOW}🔍 General task detected: Adding --approval-mode default${NC}" >&2
-        args=("--approval-mode" "default" "${args[@]}")
-    fi
-
-    # Show approval mode explanation
-    case "${args[1]}" in
-        "default")
-            echo -e "${YELLOW}   → Will prompt for approval on each tool call${NC}" >&2
-            ;;
-        "auto_edit")
-            echo -e "${YELLOW}   → Will auto-approve edit tools, prompt for others${NC}" >&2
-            ;;
-        "yolo")
-            echo -e "${YELLOW}   → Will auto-approve all tool calls${NC}" >&2
-            ;;
-    esac
-fi
-
-# Show final command (for transparency)
-echo -e "${YELLOW}🚀 Executing: qwen ${args[*]}${NC}" >&2
-
-# Execute qwen with adjusted arguments (we're already in the right directory)
-qwen "${args[@]}"