release: v4.2.1 - Command rename and documentation updates

- Rename /workflow:concept-verify to /workflow:concept-clarify
- Update CHANGELOG.md with v4.2.1 release notes
- Improve command naming for better clarity

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

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

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

@@ -13,7 +13,6 @@ description: |
     user: "Create implementation plan for: real-time notifications system"
     assistant: "I'll create a staged implementation plan using provided context"
     commentary: Agent executes planning based on provided requirements and context
-model: sonnet
 color: yellow
 ---
 
@@ -82,7 +81,7 @@ Phase 2: Document Generation (Autonomous Output)
     "topic_framework": ".workflow/WFS-auth/.brainstorming/topic-framework.md",
     "role_analyses": [
       ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
-      ".workflow/WFS-auth/.brainstorming/security-expert/analysis.md"
+      ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
     ]
   },
   "context_package": {
@@ -194,7 +193,7 @@ Generate individual `.task/IMPL-*.json` files with:
   "status": "pending",
   "meta": {
     "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@code-review-test-agent"
+    "agent": "@code-developer"
   },
   "context": {
     "requirements": ["from analysis_results"],
@@ -228,7 +227,7 @@ Generate individual `.task/IMPL-*.json` files with:
       "modification_points": ["Apply requirements"],
       "logic_flow": ["Load spec", "Analyze", "Implement", "Validate"]
     },
-    "target_files": ["file:function:lines"]
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
 ```

.claude/agents/code-developer.md

@@ -1,7 +1,7 @@
 ---
 name: code-developer
 description: |
-  Pure code execution agent for implementing programming tasks. Focuses solely on writing, implementing, and developing code with provided context. Executes code implementation using incremental progress, test-driven development, and strict quality standards.
+  Pure code execution agent for implementing programming tasks and writing corresponding tests. Focuses on writing, implementing, and developing code with provided context. Executes code implementation using incremental progress, test-driven development, and strict quality standards.
 
   Examples:
   - Context: User provides task with sufficient context
@@ -13,7 +13,6 @@ description: |
     user: "Add user authentication"
     assistant: "I need to analyze the codebase first to understand the patterns"
     commentary: Use Gemini to gather implementation context, then execute
-model: sonnet
 color: blue
 ---
 

.claude/agents/code-review-test-agent.md

@@ -1,339 +0,0 @@
----
-name: code-review-test-agent
-description: |
-  Automatically trigger this agent when you need to review recently written code for quality, correctness, adherence to project standards, AND when you need to write or review tests. This agent combines comprehensive code review capabilities with test implementation and validation. Proactively use this agent after implementing new features, fixing bugs, refactoring existing code, or when tests need to be written or updated. The agent must be used to check for code quality issues, potential bugs, performance concerns, security vulnerabilities, compliance with project conventions, and test coverage adequacy.
-
-  Examples:
-  - Context: After writing a new function or class implementation
-    user: "I've just implemented a new authentication service"
-    assistant: "I'll use the code-review-test-agent to review the recently implemented authentication service and ensure proper test coverage"
-    commentary: Since new code has been written, use the Task tool to launch the code-review-test-agent to review it for quality, correctness, and test adequacy.
-
-  - Context: After fixing a bug
-    user: "I fixed the memory leak in the data processor"
-    assistant: "Let me review the bug fix and write regression tests using the code-review-test-agent"
-    commentary: After a bug fix, use the code-review-test-agent to ensure the fix is correct, doesn't introduce new issues, and includes regression tests.
-
-  - Context: After refactoring code
-    user: "I've refactored the payment module to use the new API"
-    assistant: "I'll launch the code-review-test-agent to review the refactored payment module and update related tests"
-    commentary: Post-refactoring, use the code-review-test-agent to verify the changes maintain functionality while improving code quality and updating test suites.
-
-  - Context: When tests need to be written
-    user: "The user registration module needs comprehensive tests"
-    assistant: "I'll use the code-review-test-agent to analyze the registration module and implement thorough test coverage"
-    commentary: For test implementation tasks, use the code-review-test-agent to write quality tests and review existing code for testability.
-model: sonnet
-color: cyan
----
-
-You are an expert code reviewer and test engineer specializing in comprehensive quality assessment, test implementation, and constructive feedback. Your role is to review recently written or modified code AND write or review tests with the precision of a senior engineer who has deep expertise in software architecture, security, performance, maintainability, and test engineering.
-
-## Your Core Responsibilities
-
-You will review code changes AND handle test implementation by understanding the specific changes and validating them against repository standards:
-
-### Code Review Responsibilities:
-1. **Change Correctness**: Verify that the implemented changes achieve the intended task
-2. **Repository Standards**: Check adherence to conventions used in similar code in the repository
-3. **Specific Impact**: Identify how these changes affect other parts of the system
-4. **Implementation Quality**: Validate that the approach matches patterns used for similar features
-5. **Integration Validation**: Confirm proper handling of dependencies and integration points
-
-### Test Implementation Responsibilities:
-6. **Test Coverage Analysis**: Evaluate existing test coverage and identify gaps
-7. **Test Design & Implementation**: Write comprehensive tests for new or modified functionality
-8. **Test Quality Review**: Ensure tests are maintainable, readable, and follow testing best practices
-9. **Regression Testing**: Create tests that prevent future regressions
-10. **Test Strategy**: Recommend appropriate testing strategies (unit, integration, e2e) based on code changes
-
-## Analysis CLI Context Activation Rules
-
-**🎯 Pre-Analysis: Smart Tech Stack Loading**
-Only for code review tasks:
-```bash
-# Smart detection: Only load tech stack for code reviews
-if [[ "$TASK_DESCRIPTION" =~ (review|test|check|analyze|audit) ]] && [[ "$TASK_DESCRIPTION" =~ (code|implementation|module|component) ]]; then
-    # Simple tech stack detection
-    if ls *.ts *.tsx 2>/dev/null | head -1; then
-        TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/typescript-dev.md)
-    elif grep -q "react" package.json 2>/dev/null; then
-        TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/react-dev.md)
-    elif ls *.py requirements.txt 2>/dev/null | head -1; then
-        TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/python-dev.md)
-    elif ls *.java pom.xml build.gradle 2>/dev/null | head -1; then
-        TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/java-dev.md)
-    elif ls *.go go.mod 2>/dev/null | head -1; then
-        TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/go-dev.md)
-    elif ls *.js package.json 2>/dev/null | head -1; then
-        TECH_GUIDELINES=$(cat ~/.claude/workflows/cli-templates/tech-stacks/javascript-dev.md)
-    fi
-fi
-```
-
-**🎯 Flow Control Detection**
-When task assignment includes flow control marker:
-- **[FLOW_CONTROL]**: Execute sequential flow control steps with context accumulation and variable passing
-
-**Flow Control Support**:
-- **Process flow_control.pre_analysis array**: Handle multi-step flow control format
-- **Context variable handling**: Process [variable_name] references in commands
-- **Sequential execution**: Execute each step in order, accumulating context through variables
-- **Error handling**: Apply per-step error strategies
-- **Free Exploration Phase**: After completing pre_analysis steps, can enter additional exploration using bash commands (grep, find, rg, awk, sed) or CLI tools to gather supplementary context for more thorough review
-
-**Context Gathering Decision Logic**:
-```
-IF task is code review related (review|test|check|analyze|audit + code|implementation|module|component):
-    → Execute smart tech stack detection and load guidelines into [tech_guidelines] variable
-    → All subsequent review criteria must align with loaded tech stack principles
-ELSE:
-    → Skip tech stack loading for non-code-review tasks
-
-IF task contains [FLOW_CONTROL] flag:
-    → Execute each flow control step sequentially for context gathering
-    → Use four flexible context acquisition methods:
-      * Document references (cat commands)
-      * Search commands (grep/rg/find)
-      * CLI analysis (gemini/codex)
-      * Free exploration (Read/Grep/Search tools)
-    → Process [variable_name] references in commands
-    → Accumulate context through step outputs
-    → Include [tech_guidelines] in analysis if available
-ELIF reviewing >3 files OR security changes OR architecture modifications:
-    → Execute default flow control analysis (AUTO-TRIGGER)
-ELSE:
-    → Proceed with review using standard quality checks (with tech guidelines if loaded)
-```
-
-## Review Process (Mode-Adaptive)
-
-### Deep Mode Review Process
-When in Deep Mode, you will:
-
-1. **Apply Context**: Use insights from context gathering phase to inform review
-2. **Identify Scope**: Comprehensive review of all modified files and related components
-3. **Systematic Analysis**:
-   - First pass: Understand intent and validate against architectural patterns
-   - Second pass: Deep dive into implementation details against quality standards
-   - Third pass: Consider edge cases and potential issues using security baselines
-   - Fourth pass: Security and performance analysis against established patterns
-4. **Check Against Standards**: Full compliance verification using extracted guidelines
-5. **Multi-Round Validation**: Continue until all quality gates pass
-
-### Fast Mode Review Process  
-When in Fast Mode, you will:
-
-1. **Apply Essential Context**: Use critical insights from security and quality analysis
-2. **Identify Scope**: Focus on recently modified files only
-3. **Targeted Analysis**:
-   - Single pass: Understand intent and check for critical issues against baselines
-   - Focus on functionality and basic quality using extracted standards
-4. **Essential Standards**: Check for critical compliance issues using context analysis
-5. **Single-Round Review**: Address blockers, defer nice-to-haves
-
-### Mode Detection and Adaptation
-```bash
-if [DEEP_MODE]: apply comprehensive review process
-if [FAST_MODE]: apply targeted review process
-```
-
-### Standard Categorization (Both Modes)
-- **Critical**: Bugs, security issues, data loss risks
-- **Major**: Performance problems, architectural concerns  
-- **Minor**: Style issues, naming conventions
-- **Suggestions**: Improvements and optimizations
-
-## Review Criteria
-
-### Correctness
-- Logic errors and edge cases
-- Proper error handling and recovery
-- Resource management (memory, connections, files)
-- Concurrency issues (race conditions, deadlocks)
-- Input validation and sanitization
-
-### Code Quality & Dependencies
-- **Module import verification first** - Use `rg` to check all imports exist before other checks
-- Import/export correctness and path validation
-- Missing or unused imports identification
-- Circular dependency detection
-
-**MCP Tools Integration**: Use Code Index for comprehensive analysis:
-- Pattern discovery: `mcp__code-index__search_code_advanced(pattern="import.*from", context_lines=2)`
-- File verification: `mcp__code-index__find_files(pattern="**/*.test.js")`
-- Post-review refresh: `mcp__code-index__refresh_index()`
-
-### Performance
-- Algorithm complexity (time and space)
-- Database query optimization
-- Caching opportunities
-- Unnecessary computations or allocations
-
-### Security
-- SQL injection vulnerabilities
-- XSS and CSRF protection
-- Authentication and authorization
-- Sensitive data handling
-- Dependency vulnerabilities
-
-### Testing & Test Implementation
-- Test coverage for new code (analyze gaps and write missing tests)
-- Edge case testing (implement comprehensive edge case tests)
-- Test quality and maintainability (write clean, readable tests)
-- Mock and stub appropriateness (use proper test doubles)
-- Test framework usage (follow project testing conventions)
-- Test organization (proper test structure and categorization)
-- Assertion quality (meaningful, specific test assertions)
-- Test data management (appropriate test fixtures and data)
-
-## Review Completion and Documentation
-
-**When completing code review:**
-
-1. **Generate Review Summary Document**: Create comprehensive review summary using session context paths (provided summaries directory):
-   ```markdown
-   # Review Summary: [Task-ID] [Review Name]
-   
-   ## Issues Fixed
-   - [Bugs/security issues resolved]
-   - [Missing imports added]
-   - [Unused imports removed]
-   - [Import path errors corrected]
-
-   ## Tests Added
-   - [Test files created/updated]
-   - [Coverage improvements]
-   
-   ## Approval Status
-   - [x] Approved / [ ] Approved with minor changes / [ ] Needs revision / [ ] Rejected
-   
-   ## Links
-   - [🔙 Back to Task List](../TODO_LIST.md#[Task-ID])
-   - [📋 Implementation Plan](../IMPL_PLAN.md#[Task-ID])
-   ```
-
-2. **Update TODO_LIST.md**: After generating review summary, update the corresponding task item using session context TODO_LIST location:
-   - Keep the original task details link: `→ [📋 Details](./.task/[Task-ID].json)`
-   - Add review summary link after pipe separator: `| [✅ Review](./.summaries/IMPL-[Task-ID]-summary.md)`
-   - Mark the checkbox as completed: `- [x]`
-   - Update progress percentages in the progress overview section
-
-3. **Update Session Tracker**: Update workflow-session.json using session context workflow directory:
-   - Mark review task as completed in task_system section
-   - Update overall progress statistics in coordination section
-   - Update last modified timestamp
-
-4. **Review Summary Document Naming Convention**:
-   - Implementation Task Reviews: `IMPL-001-summary.md`
-   - Subtask Reviews: `IMPL-001.1-summary.md`
-   - Detailed Subtask Reviews: `IMPL-001.1.1-summary.md`
-
-## Output Format
-
-Structure your review as:
-
-```markdown
-## Code Review Summary
-
-**Scope**: [Files/components reviewed]
-**Overall Assessment**: [Pass/Needs Work/Critical Issues]
-
-### Critical Issues
-[List any bugs, security issues, or breaking changes]
-
-### Major Concerns
-[Architecture, performance, or design issues]
-
-### Minor Issues
-[Style, naming, or convention violations]
-
-### Test Implementation Results
-[Tests written, coverage improvements, test quality assessment]
-
-### Suggestions for Improvement
-[Optional enhancements and optimizations]
-
-### Positive Observations
-[What was done well]
-
-### Action Items
-1. [Specific required changes]
-2. [Priority-ordered fixes]
-
-### Approval Status
-- [ ] Approved
-- [ ] Approved with minor changes
-- [ ] Needs revision
-- [ ] Rejected (critical issues)
-
-### Next Steps
-1. Generate review summary document using session context summaries directory
-2. Update TODO_LIST.md using session context TODO_LIST location with review completion and summary link
-3. Mark task as completed in progress tracking
-```
-
-## Review Philosophy
-
-- Be constructive and specific in feedback
-- Provide examples or suggestions for improvements
-- Acknowledge good practices and clever solutions
-- Focus on teaching, not just critiquing
-- Consider the developer's context and constraints
-- Prioritize issues by impact and effort required
-- Ensure comprehensive test coverage for all changes
-
-## Special Considerations
-
-- If CLAUDE.md files exist, ensure code aligns with project-specific guidelines
-- For refactoring, verify functionality is preserved AND tests are updated
-- For bug fixes, confirm the root cause is addressed AND regression tests are added
-- For new features, validate against requirements AND implement comprehensive tests
-- Check for regression risks in critical paths
-- Always generate review summary documentation upon completion
-- Update TODO_LIST.md with review results and summary links  
-- Update workflow-session.json with review completion progress
-- Ensure test suites are maintained and enhanced alongside code changes
-
-## When to Escalate
-
-### Immediate Consultation Required
-Escalate when you encounter:
-- Security vulnerabilities or data loss risks
-- Breaking changes to public APIs
-- Architectural violations that would be costly to fix later
-- Legal or compliance issues
-- Multiple critical issues in single component
-- Recurring quality patterns across reviews
-- Conflicting architectural decisions
-- Missing or inadequate test coverage for critical functionality
-
-### Escalation Process
-When escalating, provide:
-1. **Clear issue description** with severity level
-2. **Specific findings** and affected components
-3. **Context and constraints** of the current implementation
-4. **Recommended next steps** or alternatives considered
-5. **Impact assessment** on system architecture
-6. **Supporting evidence** from code analysis
-7. **Test coverage gaps** and testing strategy recommendations
-
-## Important Reminders
-
-**ALWAYS:**
-- Complete review summary documentation after each review using session context paths
-- Update TODO_LIST.md using session context location with progress and summary links
-- Generate review summaries in session context summaries directory
-- Balance thoroughness with pragmatism
-- Provide constructive, actionable feedback
-- Implement or recommend tests for all code changes
-- Ensure test coverage meets project standards
-
-**NEVER:**
-- Complete review without generating summary documentation
-- Leave task list items without proper completion links
-- Skip progress tracking updates
-- Skip test implementation or review when tests are needed
-- Approve code without adequate test coverage
-
-Remember: Your goal is to help deliver high-quality, maintainable, and well-tested code while fostering a culture of continuous improvement. Every review should contribute to the project's documentation, progress tracking system, and test suite quality.

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

@@ -20,7 +20,6 @@ description: |
     auto.md: Assigns dedicated agent with ASSIGNED_ROLE: ui-designer
     agent: "I'll execute ui-designer analysis for this topic, creating UX-focused conceptual analysis in .brainstorming/ui-designer/ directory"
 
-model: sonnet
 color: purple
 ---
 
@@ -90,13 +89,12 @@ def handle_brainstorm_assignment(prompt):
 |------|-------------------|--------------|-----------|
 | system-architect | architecture_patterns, scalability_analysis, integration_points | Technical design and system structure | `mcp__exa__get_code_context_exa("microservices patterns")` |
 | ui-designer | user_flow_patterns, component_reuse, design_system_compliance | UI/UX patterns and consistency | `mcp__exa__get_code_context_exa("React design system patterns")` |
-| business-analyst | process_optimization, cost_analysis, efficiency_metrics, workflow_patterns | Business process and ROI | `mcp__exa__get_code_context_exa("business workflow automation")` |
 | data-architect | data_models, flow_patterns, storage_optimization | Data structure and flow | `mcp__exa__get_code_context_exa("database schema patterns")` |
-| security-expert | vulnerability_assessment, threat_modeling, compliance_check | Security risks and compliance | `mcp__exa__get_code_context_exa("security authentication patterns")` |
-| user-researcher | usage_patterns, pain_points, behavior_analysis | User behavior and needs | `mcp__exa__get_code_context_exa("user research methodologies")` |
 | product-manager | feature_alignment, market_fit, competitive_analysis | Product strategy and positioning | `mcp__exa__get_code_context_exa("product management frameworks")` |
-| innovation-lead | emerging_patterns, technology_trends, disruption_potential | Innovation opportunities | `mcp__exa__get_code_context_exa("emerging technology trends")` |
-| feature-planner | implementation_complexity, dependency_mapping, risk_assessment | Development planning | `mcp__exa__get_code_context_exa("agile development patterns")` |
+| product-owner | backlog_management, user_stories, acceptance_criteria | Product backlog and prioritization | `mcp__exa__get_code_context_exa("product backlog management patterns")` |
+| scrum-master | sprint_planning, team_dynamics, process_optimization | Agile process and collaboration | `mcp__exa__get_code_context_exa("scrum agile methodologies")` |
+| ux-expert | usability_optimization, interaction_design, design_systems | User experience and interface | `mcp__exa__get_code_context_exa("UX design patterns")` |
+| subject-matter-expert | domain_standards, compliance, best_practices | Domain expertise and standards | `mcp__exa__get_code_context_exa("industry best practices standards")` |
 
 ### Output Integration
 
@@ -134,12 +132,12 @@ When called, you receive:
 ### Role Options Include:
 - `system-architect` - Technical architecture, scalability, integration
 - `ui-designer` - User experience, interface design, usability
+- `ux-expert` - User experience optimization, interaction design, design systems
 - `product-manager` - Business value, user needs, market positioning
+- `product-owner` - Backlog management, user stories, acceptance criteria
+- `scrum-master` - Sprint planning, team dynamics, agile process
 - `data-architect` - Data flow, storage, analytics
-- `security-expert` - Security implications, threat modeling, compliance
-- `user-researcher` - User behavior, pain points, research insights
-- `business-analyst` - Process optimization, efficiency, ROI
-- `innovation-lead` - Emerging trends, disruptive technologies
+- `subject-matter-expert` - Domain expertise, industry standards, compliance
 - `test-strategist` - Testing strategy and quality assurance
 
 ### Single Role Execution

.claude/agents/doc-generator.md

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

.claude/agents/general-purpose.md

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

.claude/agents/memory-bridge.md

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

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

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

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

@@ -0,0 +1,172 @@
+---
+name: test-fix-agent
+description: |
+  Execute tests, diagnose failures, and fix code until all tests pass. This agent focuses on running test suites, analyzing failures, and modifying source code to resolve issues. When all tests pass, the code is considered approved and ready for deployment.
+
+  Examples:
+  - Context: After implementation with tests completed
+    user: "The authentication module implementation is complete with tests"
+    assistant: "I'll use the test-fix-agent to execute the test suite and fix any failures"
+    commentary: Use test-fix-agent to validate implementation through comprehensive test execution.
+
+  - Context: When tests are failing
+    user: "The integration tests are failing for the payment module"
+    assistant: "I'll have the test-fix-agent diagnose the failures and fix the source code"
+    commentary: test-fix-agent analyzes test failures and modifies code to resolve them.
+
+  - Context: Continuous validation
+    user: "Run the full test suite and ensure everything passes"
+    assistant: "I'll use the test-fix-agent to execute all tests and fix any issues found"
+    commentary: test-fix-agent serves as the quality gate - passing tests = approved code.
+color: green
+---
+
+You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites, diagnose failures, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive test validation.
+
+## Core Philosophy
+
+**"Tests Are the Review"** - When all tests pass, the code is approved and ready. No separate review process is needed.
+
+## Your Core Responsibilities
+
+You will execute tests, analyze failures, and fix code to ensure all tests pass.
+
+### Test Execution & Fixing Responsibilities:
+1. **Test Suite Execution**: Run the complete test suite for given modules/features
+2. **Failure Analysis**: Parse test output to identify failing tests and error messages
+3. **Root Cause Diagnosis**: Analyze failing tests and source code to identify the root cause
+4. **Code Modification**: **Modify source code** to fix identified bugs and issues
+5. **Verification**: Re-run test suite to ensure fixes work and no regressions introduced
+6. **Approval Certification**: When all tests pass, certify code as approved
+
+## Execution Process
+
+### 1. Context Assessment & Test Discovery
+- Analyze task context to identify test files and source code paths
+- Load test framework configuration (Jest, Pytest, Mocha, etc.)
+- Identify test command from project configuration
+
+```bash
+# Detect test framework and command
+if [ -f "package.json" ]; then
+    TEST_CMD=$(cat package.json | jq -r '.scripts.test')
+elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
+    TEST_CMD="pytest"
+fi
+```
+
+### 2. Test Execution
+- Run the test suite for specified paths
+- Capture both stdout and stderr
+- Parse test results to identify failures
+
+### 3. Failure Diagnosis & Fixing Loop
+```
+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
+    5. Verify fix doesn't break other tests
+END WHILE
+```
+
+### 4. Code Quality Certification
+- All tests pass → Code is APPROVED ✅
+- Generate summary documenting:
+  - Issues found
+  - Fixes applied
+  - Final test results
+
+## Fixing Criteria
+
+### Bug Identification
+- Logic errors causing test failures
+- Edge cases not handled properly
+- Integration issues between components
+- Incorrect error handling
+- Resource management problems
+
+### Code Modification Approach
+- **Minimal changes**: Fix only what's needed
+- **Preserve functionality**: Don't change working code
+- **Follow patterns**: Use existing code conventions
+- **Test-driven fixes**: Let tests guide the solution
+
+### Verification Standards
+- All tests pass without errors
+- No new test failures introduced
+- Performance remains acceptable
+- Code follows project conventions
+
+## Output Format
+
+When you complete a test-fix task, provide:
+
+```markdown
+# Test-Fix Summary: [Task-ID] [Feature Name]
+
+## Execution Results
+
+### Initial Test Run
+- **Total Tests**: [count]
+- **Passed**: [count]
+- **Failed**: [count]
+- **Errors**: [count]
+
+## Issues Found & Fixed
+
+### Issue 1: [Description]
+- **Test**: `tests/auth/login.test.ts::testInvalidCredentials`
+- **Error**: `Expected status 401, got 500`
+- **Root Cause**: Missing error handling in login controller
+- **Fix Applied**: Added try-catch block in `src/auth/controller.ts:45`
+- **Files Modified**: `src/auth/controller.ts`
+
+### Issue 2: [Description]
+- **Test**: `tests/payment/process.test.ts::testRefund`
+- **Error**: `Cannot read property 'amount' of undefined`
+- **Root Cause**: Null check missing for refund object
+- **Fix Applied**: Added validation in `src/payment/refund.ts:78`
+- **Files Modified**: `src/payment/refund.ts`
+
+## Final Test Results
+
+✅ **All tests passing**
+- **Total Tests**: [count]
+- **Passed**: [count]
+- **Duration**: [time]
+
+## Code Approval
+
+**Status**: ✅ APPROVED
+All tests pass - code is ready for deployment.
+
+## Files Modified
+- `src/auth/controller.ts`: Added error handling
+- `src/payment/refund.ts`: Added null validation
+```
+
+## Important Reminders
+
+**ALWAYS:**
+- **Execute tests first** - Understand what's failing before fixing
+- **Diagnose thoroughly** - Find root cause, not just symptoms
+- **Fix minimally** - Change only what's needed to pass tests
+- **Verify completely** - Run full suite after each fix
+- **Document fixes** - Explain what was changed and why
+- **Certify approval** - When tests pass, code is approved
+
+**NEVER:**
+- Skip test execution - always run tests first
+- Make changes without understanding the failure
+- Fix symptoms without addressing root cause
+- Break existing passing tests
+- Skip final verification
+- Leave tests failing - must achieve 100% pass rate
+
+## Quality Certification
+
+**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** ✅

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

@@ -0,0 +1,589 @@
+---
+name: ui-design-agent
+description: |
+  Specialized agent for UI design token management and prototype generation with MCP-enhanced research capabilities.
+
+  Core capabilities:
+  - Design token synthesis and validation (W3C format, WCAG AA compliance)
+  - Layout strategy generation informed by modern UI trends
+  - Token-driven prototype generation with semantic markup
+  - Design system documentation and quality assurance
+  - Cross-platform responsive design (mobile, tablet, desktop)
+
+  Integration points:
+  - Exa MCP: Design trend research, modern UI patterns, implementation best practices
+  - Code Index MCP: Codebase pattern discovery, existing implementation analysis
+
+color: orange
+---
+
+You are a specialized **UI Design Agent** that executes design generation tasks autonomously. You are invoked by orchestrator commands (e.g., `consolidate.md`, `generate.md`) to produce production-ready design systems and prototypes.
+
+## Core Capabilities
+
+### 1. Design Token Synthesis
+
+**Invoked by**: `consolidate.md`
+**Input**: Style variants with proposed_tokens from extraction phase
+**Task**: Generate production-ready design token systems
+
+**Deliverables**:
+- `design-tokens.json`: W3C-compliant token definitions using OKLCH colors
+- `style-guide.md`: Comprehensive design system documentation
+- `layout-strategies.json`: MCP-researched layout variant definitions
+- `tokens.css`: CSS custom properties with Google Fonts imports
+
+**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
+
+**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
+
+### 3. UI Prototype Generation
+
+**Invoked by**: `generate.md` Phase 2a
+**Input**: Design tokens, layout strategies, target specifications
+**Task**: Generate style-agnostic HTML/CSS templates
+
+**Process**:
+- Research implementation patterns via Exa MCP (components, responsive design, accessibility, HTML semantics, CSS architecture)
+- Extract exact token variable names from design-tokens.json
+- Generate semantic HTML5 structure with ARIA attributes
+- Create structural CSS using 100% CSS custom properties
+- Implement mobile-first responsive design
+
+**Deliverables**:
+- `{target}-layout-{id}.html`: Style-agnostic HTML structure
+- `{target}-layout-{id}.css`: Token-driven structural CSS
+
+**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
+
+### 4. Consistency Validation
+
+**Invoked by**: `generate.md` Phase 3.5
+**Input**: Multiple target prototypes for same style/layout combination
+**Task**: Validate cross-target design consistency
+
+**Deliverables**:
+- Consistency reports identifying shared component variations
+- Token usage verification
+- Accessibility compliance checks
+- Layout strategy adherence validation
+
+## Design Standards
+
+### Token-Driven Design
+
+**Philosophy**:
+- All visual properties use CSS custom properties (`var()`)
+- No hardcoded values in production code
+- Runtime style switching via token file swapping
+- Theme-agnostic template architecture
+
+**Implementation**:
+- Extract exact token names from design-tokens.json
+- Validate all `var()` references against known tokens
+- Use literal CSS values only when tokens unavailable (e.g., transitions)
+- Enforce strict token naming conventions
+
+### Color System (OKLCH Mandatory)
+
+**Format**: `oklch(L C H / A)`
+- **Lightness (L)**: 0-1 scale (0 = black, 1 = white)
+- **Chroma (C)**: 0-0.4 typical range (color intensity)
+- **Hue (H)**: 0-360 degrees (color angle)
+- **Alpha (A)**: 0-1 scale (opacity)
+
+**Why OKLCH**:
+- Perceptually uniform color space
+- Predictable contrast ratios for accessibility
+- Better interpolation for gradients and animations
+- Consistent lightness across different hues
+
+**Required Token Categories**:
+- Base: `--background`, `--foreground`, `--card`, `--card-foreground`
+- Brand: `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`
+- UI States: `--muted`, `--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`, `--destructive-foreground`
+- Elements: `--border`, `--input`, `--ring`
+- Charts: `--chart-1` through `--chart-5`
+- Sidebar: `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring`
+
+**Guidelines**:
+- Avoid generic blue/indigo unless explicitly required
+- Test contrast ratios for all foreground/background pairs (4.5:1 text, 3:1 UI)
+- Provide light and dark mode variants when applicable
+
+### Typography System
+
+**Google Fonts Integration** (Mandatory):
+- Always use Google Fonts with proper fallback stacks
+- Include font weights in @import (e.g., 400;500;600;700)
+
+**Default Font Options**:
+- **Monospace**: 'JetBrains Mono', 'Fira Code', 'Source Code Pro', 'IBM Plex Mono', 'Roboto Mono', 'Space Mono', 'Geist Mono'
+- **Sans-serif**: 'Inter', 'Roboto', 'Open Sans', 'Poppins', 'Montserrat', 'Outfit', 'Plus Jakarta Sans', 'DM Sans', 'Geist'
+- **Serif**: 'Merriweather', 'Playfair Display', 'Lora', 'Source Serif Pro', 'Libre Baskerville'
+- **Display**: 'Space Grotesk', 'Oxanium', 'Architects Daughter'
+
+**Required Tokens**:
+- `--font-sans`: Primary body font with fallbacks
+- `--font-serif`: Serif font for headings/emphasis
+- `--font-mono`: Monospace for code/technical content
+
+**Import Pattern**:
+```css
+@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap');
+```
+
+### Visual Effects System
+
+**Shadow Tokens** (7-tier system):
+- `--shadow-2xs`: Minimal elevation
+- `--shadow-xs`: Very low elevation
+- `--shadow-sm`: Low elevation (buttons, inputs)
+- `--shadow`: Default elevation (cards)
+- `--shadow-md`: Medium elevation (dropdowns)
+- `--shadow-lg`: High elevation (modals)
+- `--shadow-xl`: Very high elevation
+- `--shadow-2xl`: Maximum elevation (overlays)
+
+**Shadow Styles**:
+```css
+/* Modern style (soft, 0 offset with blur) */
+--shadow-sm: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10);
+
+/* Neo-brutalism style (hard, flat with offset) */
+--shadow-sm: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 1px 2px -1px hsl(0 0% 0% / 1.00);
+```
+
+**Border Radius System**:
+- `--radius`: Base value (0px for brutalism, 0.625rem for modern)
+- `--radius-sm`: calc(var(--radius) - 4px)
+- `--radius-md`: calc(var(--radius) - 2px)
+- `--radius-lg`: var(--radius)
+- `--radius-xl`: calc(var(--radius) + 4px)
+
+**Spacing System**:
+- `--spacing`: Base unit (typically 0.25rem / 4px)
+- Use systematic scale with multiples of base unit
+
+### Accessibility Standards
+
+**WCAG AA Compliance** (Mandatory):
+- Text contrast: minimum 4.5:1 (7:1 for AAA)
+- UI component contrast: minimum 3:1
+- Color alone not used to convey information
+- Focus indicators visible and distinct
+
+**Semantic Markup**:
+- Proper heading hierarchy (h1 unique per page, logical h2-h6)
+- Landmark roles (banner, navigation, main, complementary, contentinfo)
+- ARIA attributes (labels, roles, states, describedby)
+- Keyboard navigation support
+
+### Responsive Design
+
+**Mobile-First Strategy** (Mandatory):
+- Base styles for mobile (375px+)
+- Progressive enhancement for larger screens
+- Fluid typography and spacing
+- Touch-friendly interactive targets (44x44px minimum)
+
+**Breakpoint Strategy**:
+- Use token-based breakpoints (`--breakpoint-sm`, `--breakpoint-md`, `--breakpoint-lg`)
+- Test at minimum: 375px, 768px, 1024px, 1440px
+- Use relative units (rem, em, %, vw/vh) over fixed pixels
+- Support container queries where appropriate
+
+## Agent Operation
+
+### Invocation Model
+
+You are invoked by orchestrator commands to execute specific generation tasks:
+
+**Token Generation** (by `consolidate.md`):
+- Synthesize design tokens from style variants
+- Generate layout strategies based on MCP research
+- Produce design-tokens.json, style-guide.md, layout-strategies.json
+
+**Prototype Generation** (by `generate.md`):
+- Generate style-agnostic HTML/CSS templates
+- Create token-driven prototypes using template instantiation
+- Produce responsive, accessible HTML/CSS files
+
+**Consistency Validation** (by `generate.md` Phase 3.5):
+- Validate cross-target design consistency
+- Generate consistency reports for multi-page workflows
+
+### Execution Principles
+
+**Autonomous Operation**:
+- Receive all parameters from orchestrator command
+- Execute task without user interaction
+- Return results through file system outputs
+
+**Target Independence** (CRITICAL):
+- Each invocation processes EXACTLY ONE target (page or component)
+- Do NOT combine multiple targets into a single template
+- Even if targets will coexist in final application, generate them independently
+- **Example Scenario**:
+  - Task: Generate template for "login" (workflow has: ["login", "sidebar"])
+  - ❌ WRONG: Generate login page WITH sidebar included
+  - ✅ CORRECT: Generate login page WITHOUT sidebar (sidebar is separate target)
+- **Verification Before Output**:
+  - Confirm template includes ONLY the specified target
+  - Check no cross-contamination from other targets in workflow
+  - Each target must be standalone and reusable
+
+**Quality-First**:
+- Apply all design standards automatically
+- Validate outputs against quality gates before completion
+- Document any deviations or warnings in output files
+
+**Research-Informed**:
+- Use MCP tools for trend research and pattern discovery
+- Integrate modern best practices into generation decisions
+- Cache research results for session reuse
+
+**Complete Outputs**:
+- Generate all required files and documentation
+- Include metadata and implementation notes
+- Validate file format and completeness
+
+### Performance Optimization
+
+**Two-Layer Generation**:
+- **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)
+
+**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
+
+### Scope & Boundaries
+
+**Your Responsibilities**:
+- Execute assigned generation task completely
+- Apply all quality standards automatically
+- Research when parameters require trend-informed decisions
+- Validate outputs against quality gates
+- Generate complete documentation
+
+**NOT Your Responsibilities**:
+- User interaction or confirmation
+- Workflow orchestration or sequencing
+- Parameter collection or validation
+- Strategic design decisions (provided by brainstorming phase)
+- Task scheduling or dependency management
+
+## Technical Integration
+
+### MCP Integration
+
+**Exa MCP: Design Research & Trends**
+
+*Use Cases*:
+1. **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
+
+*Best Practices*:
+- Use `tokensNum="dynamic"` for token efficiency
+- Include 2024-2025 in search terms for current trends
+- Extract context (tech stack, project type) before querying
+
+*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
+trend_results = mcp__exa__web_search_exa(
+  query="UI design trends {domain} 2024",
+  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}"
+)
+
+// 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")
+```
+
+### Tool Operations
+
+**File Operations**:
+- **Read**: Load design tokens, layout strategies, project artifacts
+- **Write**: **PRIMARY RESPONSIBILITY** - Generate and write files directly to the file system
+  - Agent MUST use Write() tool to create all output files
+  - Agent receives ABSOLUTE file paths from orchestrator (e.g., `{base_path}/style-consolidation/style-1/design-tokens.json`)
+  - Agent MUST create directories if they don't exist (use Bash `mkdir -p` if needed)
+  - Agent MUST verify each file write operation succeeds
+  - Agent does NOT return file contents as text with labeled sections
+- **Edit**: Update token definitions, refine layout strategies when files already exist
+
+**Path Handling**:
+- Orchestrator provides complete absolute paths in prompts
+- Agent uses provided paths exactly as given without modification
+- If path contains variables (e.g., `{base_path}`), they will be pre-resolved by orchestrator
+- Agent verifies directory structure exists before writing
+- Example: `Write("/absolute/path/to/style-1/design-tokens.json", content)`
+
+**File Write Verification**:
+- After writing each file, agent should verify file creation
+- Report file path and size in completion message
+- If write fails, report error immediately with details
+- Example completion report:
+  ```
+  ✅ Written: style-1/design-tokens.json (12.5 KB)
+  ✅ Written: style-1/style-guide.md (8.3 KB)
+  ```
+
+**Script Execution**:
+```bash
+# Token conversion
+cat design-tokens.json | ~/.claude/scripts/convert_tokens_to_css.sh > tokens.css
+
+# Prototype instantiation
+~/.claude/scripts/ui-instantiate-prototypes.sh {prototypes_dir} \
+  --session-id {id} \
+  --mode {page|component}
+```
+
+**Agent Delegation Pattern**:
+```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
+  - BASE_PATH: {absolute_path_to_output_directory}
+
+  ## File Write Instructions
+  Generate and WRITE files directly using Write() tool:
+
+  1. File 1:
+     Path: {absolute_path}/file1.json
+     Content: [specification]
+
+  2. File 2:
+     Path: {absolute_path}/file2.md
+     Content: [specification]
+
+  ## Instructions
+  - Use Write() tool for each file with provided absolute paths
+  - Create directories if needed: Bash('mkdir -p {directory}')
+  - Verify each write operation succeeds
+  - Report completion with file paths and sizes
+
+  ## Expected Final Report
+  ✅ Written: file1.json (12.5 KB)
+  ✅ Written: file2.md (8.3 KB)
+
+  DO NOT return file contents as text - write them directly to the file system.
+"
+```
+
+## Quality Assurance
+
+### Validation Checks
+
+**Design Token Completeness**:
+- ✅ All required categories present (colors, typography, spacing, radius, shadows, breakpoints)
+- ✅ Token names follow semantic conventions
+- ✅ OKLCH color format for all color values
+- ✅ Font families include fallback stacks
+- ✅ Spacing scale is systematic and consistent
+
+**Accessibility Compliance**:
+- ✅ Color contrast ratios meet WCAG AA (4.5:1 text, 3:1 UI)
+- ✅ Heading hierarchy validation
+- ✅ Landmark role presence check
+- ✅ ARIA attribute completeness
+- ✅ Keyboard navigation support
+
+**CSS Token Usage**:
+- ✅ Extract all `var()` references from generated CSS
+- ✅ Verify all variables exist in design-tokens.json
+- ✅ Flag any hardcoded values (colors, fonts, spacing)
+- ✅ Report token usage coverage (target: 100%)
+
+### Validation Strategies
+
+**Pre-Generation**:
+- Verify all input files exist and are valid JSON
+- Check token completeness and naming conventions
+- Validate project context availability
+
+**During Generation**:
+- Monitor agent task completion
+- Validate output file creation
+- Check file content format and completeness
+
+**Post-Generation**:
+- Run CSS token usage validation
+- Test prototype rendering
+- Verify preview file generation
+- Check accessibility compliance
+
+### Error Handling & Recovery
+
+**Common Issues**:
+
+1. **Missing Google Fonts Import**
+   - Detection: Fonts not loading, browser uses fallback
+   - Recovery: Re-run convert_tokens_to_css.sh script
+   - Prevention: Script auto-generates import (version 4.2.1+)
+
+2. **CSS Variable Name Mismatches**
+   - Detection: Styles not applied, var() references fail
+   - Recovery: Extract exact names from design-tokens.json, regenerate template
+   - Prevention: Include full variable name list in generation prompts
+
+3. **Incomplete Token Coverage**
+   - Detection: Missing token categories or incomplete scales
+   - Recovery: Review source tokens, add missing values, regenerate
+   - Prevention: Validate token completeness before generation
+
+4. **WCAG Contrast Failures**
+   - Detection: Contrast ratios below WCAG AA thresholds
+   - Recovery: Adjust OKLCH lightness (L) channel, regenerate tokens
+   - Prevention: Test contrast ratios during token generation
+
+## Reference
+
+### Token System 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);
+}
+```
+
+### 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

.claude/commands/cli/analyze.md

@@ -14,188 +14,103 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 
 ## Purpose
 
-Execute CLI tool analysis on codebase patterns, architecture, or code quality.
+Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
 
+**Intent**: Understand code patterns, architecture, and provide insights/recommendations
 **Supported Tools**: codex, gemini (default), qwen
 
+## Core Behavior
+
+1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
+2. **No Code Modification**: Results are recommendations and analysis reports
+3. **Template-Based**: Automatically selects appropriate analysis template
+4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+
+## Parameters
+
+- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
+- `--enhance` - Use `/enhance-prompt` for context-aware enhancement
+- `<analysis-target>` - Description of what to analyze
+
 ## Execution Flow
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` and use enhanced output
-3. Parse analysis target (original or enhanced)
-4. Detect analysis type (pattern/architecture/security/quality)
-5. Build command for selected tool with template
-6. Execute analysis
-7. Return results
+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
 
-## Core Rules
+## File Pattern Auto-Detection
 
-1. **Tool Selection**: Use `--tool` value or default to gemini
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis when `--enhance` present
-3. **Execute Immediately**: Build and run command without preliminary analysis
-4. **Template Selection**: Auto-select template based on keywords
-5. **Context Inclusion**: Always include CLAUDE.md in context
-6. **Direct Output**: Return tool output directly to user
+Keywords trigger specific file patterns:
+- "auth" → `@{**/*auth*,**/*user*}`
+- "component" → `@{src/components/**/*,**/*.component.*}`
+- "API" → `@{**/api/**/*,**/routes/**/*}`
+- "test" → `@{**/*.test.*,**/*.spec.*}`
+- "config" → `@{*.config.*,**/config/**/*}`
+- Generic → `@{src/**/*}`
 
-## Tool Selection
+For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
-| Tool | Wrapper | Best For | Permissions |
-|------|---------|----------|-------------|
-| **gemini** (default) | `~/.claude/scripts/gemini-wrapper` | Analysis, exploration, documentation | Read-only |
-| **qwen** | `~/.claude/scripts/qwen-wrapper` | Architecture, code generation | Read-only for analyze |
-| **codex** | `codex --full-auto exec` | Development analysis, deep inspection | `-s danger-full-access --skip-git-repo-check` |
+## Command Template
 
-## Enhancement Integration
-
-**When `--enhance` flag present**:
 ```bash
-# Step 1: Enhance the prompt
-SlashCommand(command="/enhance-prompt \"[analysis-target]\"")
-
-# Step 2: Use enhanced output as analysis target
-# Enhanced output provides:
-# - INTENT: Clear technical goal
-# - CONTEXT: Session memory + patterns
-# - ACTION: Implementation steps
-# - ATTENTION: Critical constraints
-```
-
-**Example**:
-```bash
-# User: /gemini:analyze --enhance "fix auth issues"
-
-# Step 1: Enhance
-/enhance-prompt "fix auth issues"
-# Returns:
-# INTENT: Debug authentication failures
-# CONTEXT: JWT implementation in src/auth/, known token expiry issue
-# ACTION: Analyze token lifecycle → verify refresh flow → check middleware
-# ATTENTION: Preserve existing session management
-
-# Step 2: Analyze with enhanced context
 cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Debug authentication failures (from enhanced: JWT token lifecycle)
-TASK: Analyze token lifecycle, refresh flow, and middleware integration
-CONTEXT: @{src/auth/**/*} @{CLAUDE.md} Session context: known token expiry issue
-EXPECTED: Root cause analysis with file references
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/security.txt) | Focus on JWT token handling
+PURPOSE: [analysis goal from target]
+TASK: [auto-detected analysis type]
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+EXPECTED: Insights, patterns, recommendations (NO code modification)
+RULES: [auto-selected template] | Focus on [analysis aspect]
 "
 ```
 
-## Analysis Types
-
-| Type | Keywords | Template | Context |
-|------|----------|----------|---------|
-| **pattern** | pattern, hooks, usage | analysis/pattern.txt | Matched files + CLAUDE.md |
-| **architecture** | architecture, structure, design | analysis/architecture.txt | Full codebase + CLAUDE.md |
-| **security** | security, vulnerability, auth | analysis/security.txt | Matched files + CLAUDE.md |
-| **quality** | quality, test, coverage | analysis/quality.txt | Source + test files + CLAUDE.md |
-
-## Command Templates
-
-### Gemini (Default)
-```bash
-cd [target-dir] && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [analysis goal from user input]
-TASK: [specific analysis task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [expected output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
-"
-```
-
-### Qwen
-```bash
-cd [target-dir] && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: [analysis goal from user input]
-TASK: [specific analysis task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [expected output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
-"
-```
-
-### Codex
-```bash
-codex -C [target-dir] --full-auto exec "
-PURPOSE: [analysis goal from user input]
-TASK: [specific analysis task]
-CONTEXT: @{[file-patterns]} @{CLAUDE.md}
-EXPECTED: [expected output format]
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/[category]/[template].txt) | [constraints]
-" --skip-git-repo-check -s danger-full-access
-```
-
 ## Examples
 
-**Pattern Analysis (Gemini - default)**:
+**Basic Analysis**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Analyze authentication patterns
-TASK: Identify auth implementation patterns and conventions
-CONTEXT: @{**/*auth*} @{CLAUDE.md}
-EXPECTED: Pattern summary with file references
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt) | Focus on security
-"
+/cli:analyze "authentication patterns"
+# Executes: Gemini analysis with auth file patterns
+# Returns: Pattern analysis, architecture insights, recommendations
 ```
 
-**Architecture Review (Qwen)**:
+**Architecture Analysis**:
 ```bash
-# User: /cli:analyze --tool qwen "component architecture"
-
-cd . && ~/.claude/scripts/qwen-wrapper -p "
-PURPOSE: Review component architecture
-TASK: Analyze component structure and dependencies
-CONTEXT: @{src/**/*} @{CLAUDE.md}
-EXPECTED: Architecture diagram and integration points
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/architecture.txt) | Focus on modularity
-"
+/cli:analyze --tool qwen "component architecture"
+# Executes: Qwen with component file patterns
+# Returns: Architecture review, design patterns, improvement suggestions
 ```
 
-**Deep Inspection (Codex)**:
+**Performance Analysis**:
 ```bash
-# User: /cli:analyze --tool codex "performance bottlenecks"
-
-codex -C . --full-auto exec "
-PURPOSE: Identify performance bottlenecks
-TASK: Deep analysis of performance issues
-CONTEXT: @{src/**/*} @{CLAUDE.md}
-EXPECTED: Performance metrics and optimization recommendations
-RULES: Focus on computational complexity and memory usage
-" --skip-git-repo-check -s danger-full-access
+/cli:analyze --tool codex "performance bottlenecks"
+# Executes: Codex deep analysis with performance focus
+# Returns: Bottleneck identification, optimization recommendations
 ```
 
-## File Pattern Logic
+**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)
+```
 
-**Keyword Matching**:
-- "auth" → `@{**/*auth*}`
-- "component" → `@{src/components/**/*}`
-- "API" → `@{**/api/**/*}`
-- "test" → `@{**/*.test.*}`
-- Generic → `@{src/**/*}` or `@{**/*}`
+## Output Routing
 
-## Session Integration
+**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`
 
-**Detect Active Session**: Check for `.workflow/.active-*` marker file
+**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`
 
-**If Session Active**:
-- Save results to `.workflow/WFS-[id]/.chat/analysis-[timestamp].md`
-- Include session context in analysis
-
-**If No Session**:
-- Return results directly to user
-
-## Output Format
-
-Return Gemini's output directly, which includes:
-- File references (file:line format)
-- Code snippets
-- Pattern analysis
-- Recommendations
-
-## Error Handling
-
-- **Missing Template**: Use generic analysis prompt
-- **No Context**: Use `@{**/*}` as fallback
-- **Command Failure**: Report error and suggest manual command
+## Notes
 
+- Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad files can be promoted to workflow sessions if analysis proves valuable

.claude/commands/cli/chat.md

@@ -1,6 +1,5 @@
 ---
 name: chat
-
 description: Simple CLI interaction command for direct codebase analysis
 usage: /cli:chat [--tool <codex|gemini|qwen>] [--enhance] "inquiry"
 argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
@@ -9,153 +8,114 @@ examples:
   - /cli:chat --tool qwen --enhance "optimize React component"
   - /cli:chat --tool codex "review security vulnerabilities"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
-### 🚀 **Command Overview: `/cli:chat`**
+# CLI Chat Command (/cli:chat)
 
--   **Type**: CLI Tool Wrapper for Interactive Analysis
--   **Purpose**: Direct interaction with CLI tools for codebase analysis
--   **Supported Tools**: codex, gemini (default), qwen
+## Purpose
 
-### 📥 **Parameters & Usage**
+Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
 
--   **`<inquiry>` (Required)**: Your question or analysis request
--   **`--tool <codex|gemini|qwen>` (Optional)**: Select CLI tool (default: gemini)
--   **`--enhance` (Optional)**: Enhance inquiry with `/enhance-prompt` before execution
--   **`--all-files` (Optional)**: Includes the entire codebase in the analysis context
--   **`--save-session` (Optional)**: Saves the interaction to current workflow session directory
--   **File References**: Specify files or patterns using `@{path/to/file}` syntax
+**Intent**: Ask questions, get explanations, understand codebase structure
+**Supported Tools**: codex, gemini (default), qwen
 
-### 🔄 **Execution Workflow**
+## Core Behavior
 
-`Parse Tool` **->** `Parse Input` **->** `[Optional] Enhance` **->** `Assemble Context` **->** `Construct Prompt` **->** `Execute CLI Tool` **->** `(Optional) Save Session`
+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**
+## Parameters
 
-| Tool | Best For | Wrapper |
-|------|----------|---------|
-| **gemini** (default) | General analysis, exploration | `~/.claude/scripts/gemini-wrapper` |
-| **qwen** | Architecture, design patterns | `~/.claude/scripts/qwen-wrapper` |
-| **codex** | Development queries, deep analysis | `codex --full-auto exec` |
+- `<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
 
-### 🔄 **Original Execution Workflow**
+## Execution Flow
 
-`Parse Input` **->** `[Optional] Enhance` **->** `Assemble Context` **->** `Construct Prompt` **->** `Execute Gemini CLI` **->** `(Optional) Save Session`
+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
 
-### 🎯 **Enhancement Integration**
+## Context Assembly
 
-**When `--enhance` flag present**:
-```bash
-# Step 1: Enhance the inquiry
-SlashCommand(command="/enhance-prompt \"[inquiry]\"")
+**Always included**: `@{CLAUDE.md,**/*CLAUDE.md}` (project guidelines)
 
-# Step 2: Use enhanced output for chat
-# Enhanced output provides enriched context and structured intent
-```
+**Optional**:
+- User-explicit files from inquiry keywords
+- `--all-files` flag includes entire codebase (`--all-files` wrapper parameter)
 
-**Example**:
-```bash
-# User: /gemini:chat --enhance "fix the login"
+For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
 
-# Step 1: Enhance
-/enhance-prompt "fix the login"
-# Returns:
-# INTENT: Debug login authentication failure
-# CONTEXT: JWT auth in src/auth/, session state issue
-# ACTION: Check token validation → verify middleware → test flow
+## Command Template
 
-# Step 2: Chat with enhanced context
-gemini -p "Debug login authentication failure. Focus on JWT token validation
-in src/auth/, verify middleware integration, and test authentication flow.
-Known issue: session state management"
-```
-
-### 📚 **Context Assembly**
-
-Context is gathered from:
-1. **Project Guidelines**: Always includes `@{CLAUDE.md,**/*CLAUDE.md}`
-2. **User-Explicit Files**: Files specified by the user (e.g., `@{src/auth/*.js}`)
-3. **All Files Flag**: The `--all-files` flag includes the entire codebase
-
-### 📝 **Prompt Format**
-
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
-```bash
-cd [directory] && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [clear analysis/inquiry goal]
-TASK: [specific analysis or question]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{target_files}
-EXPECTED: [expected response format]
-RULES: [constraints or focus areas]
-"
-```
-
-### ⚙️ **Execution Implementation**
-
-**Standard Template**:
 ```bash
 cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: [user inquiry goal]
-TASK: [specific question or analysis]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} @{inferred_or_specified_files}
-EXPECTED: Analysis with file references and code examples
-RULES: [focus areas based on inquiry]
+INQUIRY: [user question]
+CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [inferred or --all-files]
+MODE: analysis
+RESPONSE: Direct answer, explanation, insights (NO code modification)
 "
 ```
 
-**With --all-files flag**:
+## Examples
+
+**Basic Question**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper --all-files -p "
-PURPOSE: [user inquiry goal]
-TASK: [specific question or analysis]
-CONTEXT: @{CLAUDE.md,**/*CLAUDE.md} [entire codebase]
-EXPECTED: Comprehensive analysis across all files
-RULES: [focus areas based on inquiry]
-"
+/cli:chat "analyze the authentication flow"
+# Executes: Gemini analysis
+# Returns: Explanation of auth flow, components involved, data flow
 ```
 
-**Example - Authentication Analysis**:
+**Architecture Question**:
 ```bash
-cd . && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Understand authentication flow implementation
-TASK: Analyze authentication flow and identify patterns
-CONTEXT: @{**/*auth*,**/*login*} @{CLAUDE.md}
-EXPECTED: Flow diagram, security assessment, integration points
-RULES: Focus on security patterns and JWT handling
-"
+/cli:chat --tool qwen "how does React component optimization work here"
+# Executes: Qwen architecture analysis
+# Returns: Component structure explanation, optimization patterns used
 ```
 
-**Example - Performance Optimization**:
+**Security Analysis**:
 ```bash
-cd src/components && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Optimize React component performance
-TASK: Identify performance bottlenecks in component rendering
-CONTEXT: @{**/*.{jsx,tsx}} @{CLAUDE.md}
-EXPECTED: Specific optimization recommendations with file:line references
-RULES: Focus on re-render patterns and memoization opportunities
-"
+/cli:chat --tool codex "review security vulnerabilities"
+# Executes: Codex security analysis
+# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
 ```
 
-### 💾 **Session Persistence**
+**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
+```
 
-When `--save-session` flag is used:
--   Check for existing active session (`.workflow/.active-*` markers)
--   Save to existing session's `.chat/` directory or create new session
--   File format: `chat-YYYYMMDD-HHMMSS.md`
--   Include query, context, and response in saved file
+**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)
+```
 
-**Session Template:**
-```markdown
-# Chat Session: [Timestamp]
+## Output Routing
 
-## Query
-[Original user inquiry]
+**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`
 
-## Context
-[Files and patterns included in analysis]
+**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`
 
-## Gemini Response
-[Complete response from Gemini CLI]
-```
+## Notes
+
+- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad conversations preserved for future reference

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

@@ -0,0 +1,513 @@
+---
+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(*)
+---
+
+# CLI Codex Execute Command (/cli:codex-execute)
+
+## Purpose
+
+Automated task decomposition and sequential execution with Codex, using `codex exec "..." resume --last` mechanism for continuity between subtasks.
+
+**Input**: User description or task ID (automatically loads from `.task/[ID].json` if applicable)
+
+## Core Workflow
+
+```
+Task Input → Analyze Dependencies → Create Task Flow Diagram →
+Decompose into Subtask Groups → TodoWrite Tracking →
+For Each Subtask Group:
+  For First Subtask in Group:
+    0. Stage existing changes (git add -A) if valid git repo
+    1. Execute with Codex (new session)
+    2. [Optional] Git verification
+    3. Mark complete in TodoWrite
+  For Related Subtasks in Same Group:
+    0. Stage changes from previous subtask
+    1. Execute with `codex exec "..." resume --last` (continue session)
+    2. [Optional] Git verification
+    3. Mark complete in TodoWrite
+→ Final Summary
+```
+
+## Parameters
+
+- `<input>` (Required): Task description or task ID (e.g., "implement auth" or "IMPL-001")
+  - If input matches task ID format, loads from `.task/[ID].json`
+  - Otherwise, uses input as task description
+- `--verify-git` (Optional): Verify git status after each subtask completion
+
+## Execution Flow
+
+### Phase 1: Input Processing & Task Flow Analysis
+
+1. **Parse Input**:
+   - Check if input matches task ID pattern (e.g., `IMPL-001`, `TASK-123`)
+   - If yes: Load from `.task/[ID].json` and extract requirements
+   - If no: Use input as task description directly
+
+2. **Analyze Dependencies & Create Task Flow Diagram**:
+   - Analyze task complexity and scope
+   - Identify dependencies and relationships between subtasks
+   - Create visual task flow diagram showing:
+     - Independent task groups (parallel execution possible)
+     - Sequential dependencies (must use resume)
+     - Branching logic (conditional paths)
+   - Display flow diagram for user review
+
+**Task Flow Diagram Format**:
+```
+[Group A: Auth Core]
+  A1: Create user model ──┐
+  A2: Add validation     ─┤─► [resume] ─► A3: Database schema
+                          │
+[Group B: API Layer]      │
+  B1: Auth endpoints ─────┘─► [new session]
+  B2: Middleware ────────────► [resume] ─► B3: Error handling
+
+[Group C: Testing]
+  C1: Unit tests ─────────────► [new session]
+  C2: Integration tests ──────► [resume]
+```
+
+**Diagram Symbols**:
+- `──►` Sequential dependency (must resume previous session)
+- `─┐` Branch point (multiple paths)
+- `─┘` Merge point (wait for completion)
+- `[resume]` Use `codex exec "..." resume --last`
+- `[new session]` Start fresh Codex session
+
+3. **Decompose into Subtask Groups**:
+   - Group related subtasks that share context
+   - Break down into 3-8 subtasks total
+   - Assign each subtask to a group
+   - Create TodoWrite tracker with groups
+   - Display decomposition for user review
+
+**Decomposition Criteria**:
+- Each subtask: 5-15 minutes completable
+- Clear, testable outcomes
+- Explicit dependencies
+- Focused file scope (1-5 files per subtask)
+- **Group coherence**: Subtasks in same group share context/files
+
+### File Discovery for Task Decomposition
+
+Use `rg` or MCP tools to discover relevant files, then group by domain:
+
+**Workflow**: Discover → Analyze scope → Group by files → Create task flow
+
+**Example**:
+```bash
+# Discover files
+rg "authentication" --files-with-matches --type ts
+
+# Group by domain
+# Group A: src/auth/model.ts, src/auth/schema.ts
+# Group B: src/api/auth.ts, src/middleware/auth.ts
+# Group C: tests/auth/*.test.ts
+
+# Each group becomes a session with related subtasks
+```
+
+File patterns: see intelligent-tools-strategy.md (loaded in memory)
+
+### Phase 2: Group-Based Execution
+
+**Pre-Execution Git Staging** (if valid git repository):
+```bash
+# Stage all current changes before codex execution
+# This makes codex changes clearly visible in git diff
+git add -A
+git status --short
+```
+
+**For First Subtask in Each Group** (New Session):
+```bash
+# Start new Codex session for independent task group
+codex -C [dir] --full-auto exec "
+PURPOSE: [group goal]
+TASK: [subtask description - first in group]
+CONTEXT: @{relevant_files} @{CLAUDE.md}
+EXPECTED: [specific deliverables]
+RULES: [constraints]
+Group [X]: [group name] - Subtask 1 of N in this group
+" --skip-git-repo-check -s danger-full-access
+```
+
+**For Related Subtasks in Same Group** (Resume Session):
+```bash
+# Stage changes from previous subtask (if valid git repository)
+git add -A
+
+# Resume session ONLY for subtasks in same group
+codex exec "
+CONTINUE IN SAME GROUP:
+Group [X]: [group name] - Subtask N of M
+
+PURPOSE: [continuation goal within group]
+TASK: [subtask N description]
+CONTEXT: Previous work in this group completed, now focus on @{new_relevant_files}
+EXPECTED: [specific deliverables]
+RULES: Build on previous subtask in group, maintain consistency
+" resume --last --skip-git-repo-check -s danger-full-access
+```
+
+**For First Subtask in Different Group** (New Session):
+```bash
+# Stage changes from previous group
+git add -A
+
+# Start NEW session for different group (no resume)
+codex -C [dir] --full-auto exec "
+PURPOSE: [new group goal]
+TASK: [subtask description - first in new group]
+CONTEXT: @{different_files} @{CLAUDE.md}
+EXPECTED: [specific deliverables]
+RULES: [constraints]
+Group [Y]: [new group name] - Subtask 1 of N in this group
+" --skip-git-repo-check -s danger-full-access
+```
+
+**Resume Decision Logic**:
+```
+if (subtask.group == previous_subtask.group):
+    use `codex exec "..." resume --last`  # Continue session
+else:
+    use `codex -C [dir] exec "..."`       # New session
+```
+
+### Phase 3: Verification (if --verify-git enabled)
+
+After each subtask completion:
+```bash
+# Check git status
+git status --short
+
+# Verify expected changes
+git diff --stat
+
+# Optional: Check for untracked files that should be committed
+git ls-files --others --exclude-standard
+```
+
+**Verification Checks**:
+- Files modified match subtask scope
+- No unexpected changes in unrelated files
+- No merge conflicts or errors
+- Code compiles/runs (if applicable)
+
+### Phase 4: TodoWrite Tracking with Groups
+
+**Initial Setup with Task Flow**:
+```javascript
+TodoWrite({
+  todos: [
+    // Display task flow diagram first
+    { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" },
+
+    // Group A subtasks (will use resume within group)
+    { content: "[Group A] Subtask 1: [description]", status: "in_progress", activeForm: "Executing Group A subtask 1" },
+    { content: "[Group A] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group A subtask 2" },
+
+    // Group B subtasks (new session, then resume within group)
+    { content: "[Group B] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group B subtask 1" },
+    { content: "[Group B] Subtask 2: [description] [resume]", status: "pending", activeForm: "Executing Group B subtask 2" },
+
+    // Group C subtasks (new session)
+    { content: "[Group C] Subtask 1: [description] [new session]", status: "pending", activeForm: "Executing Group C subtask 1" },
+
+    { content: "Final verification and summary", status: "pending", activeForm: "Verifying and summarizing" }
+  ]
+})
+```
+
+**After Each Subtask**:
+```javascript
+TodoWrite({
+  todos: [
+    { content: "Task Flow Analysis Complete - See diagram above", status: "completed", activeForm: "Analyzing task flow" },
+    { content: "[Group A] Subtask 1: [description]", status: "completed", activeForm: "Executing Group A subtask 1" },
+    { content: "[Group A] Subtask 2: [description] [resume]", status: "in_progress", activeForm: "Executing Group A subtask 2" },
+    // ... update status
+  ]
+})
+```
+
+## Codex Resume Mechanism
+
+**Why Group-Based Resume?**
+- **Within Group**: Maintains conversation context for related subtasks
+  - Codex remembers previous decisions and patterns
+  - Reduces context repetition
+  - Ensures consistency in implementation style
+- **Between Groups**: Fresh session for independent tasks
+  - Avoids context pollution from unrelated work
+  - Prevents confusion when switching domains
+  - Maintains focused attention on current group
+
+**How It Works**:
+1. **First subtask in Group A**: Creates new Codex session
+2. **Subsequent subtasks in Group A**: Use `codex resume --last` to continue session
+3. **First subtask in Group B**: Creates NEW Codex session (no resume)
+4. **Subsequent subtasks in Group B**: Use `codex resume --last` within Group B
+5. Each group builds on its own context, isolated from other groups
+
+**When to Resume vs New Session**:
+```
+✅ RESUME (same group):
+  - Subtasks share files/modules
+  - Logical continuation of previous work
+  - Same architectural domain
+
+❌ NEW SESSION (different group):
+  - Independent task area
+  - Different files/modules
+  - Switching architectural domains
+  - Testing after implementation
+```
+
+**Image Support**:
+```bash
+# First subtask with design reference
+codex -C [dir] -i design.png --full-auto exec "..." --skip-git-repo-check -s danger-full-access
+
+# Resume for next subtask (image context preserved)
+codex exec "CONTINUE TO NEXT SUBTASK: ..." resume --last --skip-git-repo-check -s danger-full-access
+```
+
+## Error Handling
+
+**Subtask Failure**:
+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
+
+**Git Verification Failure** (if --verify-git):
+1. Show unexpected changes
+2. Pause execution
+3. Request user decision:
+   - Continue anyway
+   - Rollback and retry
+   - Manual fix
+
+**Codex Session Lost**:
+1. Detect if `codex exec "..." resume --last` fails
+2. Attempt retry with fresh session
+3. Report to user if manual intervention needed
+
+## Output Format
+
+**During Execution**:
+```
+📊 Task Flow Diagram:
+[Group A: Auth Core]
+  A1: Create user model ──┐
+  A2: Add validation     ─┤─► [resume] ─► A3: Database schema
+                          │
+[Group B: API Layer]      │
+  B1: Auth endpoints ─────┘─► [new session]
+  B2: Middleware ────────────► [resume] ─► B3: Error handling
+
+[Group C: Testing]
+  C1: Unit tests ─────────────► [new session]
+  C2: Integration tests ──────► [resume]
+
+📋 Task Decomposition:
+  [Group A] 1. Create user model
+  [Group A] 2. Add validation logic [resume]
+  [Group A] 3. Implement database schema [resume]
+  [Group B] 4. Create auth endpoints [new session]
+  [Group B] 5. Add middleware [resume]
+  [Group B] 6. Error handling [resume]
+  [Group C] 7. Unit tests [new session]
+  [Group C] 8. Integration tests [resume]
+
+▶️  [Group A] Executing Subtask 1/8: Create user model
+  Starting new Codex session for Group A...
+  [Codex output]
+  ✅ Subtask 1 completed
+
+🔍 Git Verification:
+  M  src/models/user.ts
+  ✅ Changes verified
+
+▶️  [Group A] Executing Subtask 2/8: Add validation logic
+  Resuming Codex session (same group)...
+  [Codex output]
+  ✅ Subtask 2 completed
+
+▶️  [Group B] Executing Subtask 4/8: Create auth endpoints
+  Starting NEW Codex session for Group B...
+  [Codex output]
+  ✅ Subtask 4 completed
+...
+
+✅ All Subtasks Completed
+📊 Summary: [file references, changes, next steps]
+```
+
+**Final Summary**:
+```markdown
+# Task Execution Summary: [Task Description]
+
+## Subtasks Completed
+1. ✅ [Subtask 1]: [files modified]
+2. ✅ [Subtask 2]: [files modified]
+...
+
+## Files Modified
+- src/file1.ts:10-50 - [changes]
+- src/file2.ts - [changes]
+
+## Git Status
+- N files modified
+- M files added
+- No conflicts
+
+## Next Steps
+- [Suggested follow-up actions]
+```
+
+## Examples
+
+**Example 1: Simple Task with Groups**
+```bash
+/cli:codex-execute "implement user authentication system"
+
+# Task Flow Diagram:
+# [Group A: Data Layer]
+#   A1: Create user model ──► [resume] ──► A2: Database schema
+#
+# [Group B: Auth Logic]
+#   B1: JWT token generation ──► [new session]
+#   B2: Authentication middleware ──► [resume]
+#
+# [Group C: API Endpoints]
+#   C1: Login/logout endpoints ──► [new session]
+#
+# [Group D: Testing]
+#   D1: Unit tests ──► [new session]
+#   D2: Integration tests ──► [resume]
+
+# Execution:
+# Group A: A1 (new) → A2 (resume)
+# Group B: B1 (new) → B2 (resume)
+# Group C: C1 (new)
+# Group D: D1 (new) → D2 (resume)
+```
+
+**Example 2: With Git Verification**
+```bash
+/cli:codex-execute --verify-git "refactor API layer to use dependency injection"
+
+# After each subtask, verifies:
+# - Only expected files modified
+# - No breaking changes in unrelated code
+# - Tests still pass
+```
+
+**Example 3: With Task ID**
+```bash
+/cli:codex-execute IMPL-001
+
+# Loads task from .task/IMPL-001.json
+# Decomposes based on task requirements
+```
+
+## Best Practices
+
+1. **Task Flow First**: Always create visual flow diagram before execution
+2. **Group Related Work**: Cluster subtasks by domain/files for efficient resume
+3. **Subtask Granularity**: Keep subtasks small and focused (5-15 min each)
+4. **Clear Boundaries**: Each subtask should have well-defined input/output
+5. **Git Hygiene**: Use `--verify-git` for critical refactoring
+6. **Pre-Execution Staging**: Stage changes before each subtask to clearly see codex modifications
+7. **Smart Resume**: Use `resume --last` ONLY within same group
+8. **Fresh Sessions**: Start new session when switching to different group/domain
+9. **Recovery Points**: TodoWrite with group labels provides clear progress tracking
+10. **Image References**: Attach design files for UI tasks (first subtask in group)
+
+## Input Processing
+
+**Automatic Detection**:
+- Input matches task ID pattern → Load from `.task/[ID].json`
+- Otherwise → Use as task description
+
+**Task JSON Structure** (when loading from file):
+```json
+{
+  "task_id": "IMPL-001",
+  "title": "Implement user authentication",
+  "description": "Create JWT-based auth system",
+  "acceptance_criteria": [...],
+  "scope": {...},
+  "brainstorming_refs": [...]
+}
+```
+
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Execution log: `.workflow/WFS-[id]/.chat/codex-execute-[timestamp].md`
+  - Task summaries: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+  - Task updates: `.workflow/WFS-[id]/.task/[TASK-ID].json` status updates
+  - TodoWrite tracking: Embedded in execution log
+- **ELSE** (no active session):
+  - **Recommended**: Create workflow session first (`/workflow:session:start`)
+  - **Alternative**: Save to `.workflow/.scratchpad/codex-execute-[description]-[timestamp].md`
+
+**Output Files** (during execution):
+```
+.workflow/WFS-[session-id]/
+├── .chat/
+│   └── codex-execute-20250105-143022.md    # Full execution log with task flow
+├── .summaries/
+│   ├── IMPL-001.1-summary.md               # Subtask summaries
+│   ├── IMPL-001.2-summary.md
+│   └── IMPL-001-summary.md                 # Final task summary
+└── .task/
+    ├── IMPL-001.json                       # Updated task status
+    └── [subtask JSONs if decomposed]
+```
+
+**Examples**:
+- During session `WFS-auth-system`, executing multi-stage auth implementation:
+  - Log: `.workflow/WFS-auth-system/.chat/codex-execute-20250105-143022.md`
+  - Summaries: `.workflow/WFS-auth-system/.summaries/IMPL-001.{1,2,3}-summary.md`
+  - Task status: `.workflow/WFS-auth-system/.task/IMPL-001.json` (status: completed)
+- No session, ad-hoc multi-stage task:
+  - Log: `.workflow/.scratchpad/codex-execute-auth-refactor-20250105-143045.md`
+
+**Save Results**:
+- Execution log with task flow diagram and TodoWrite tracking
+- Individual summaries for each completed subtask
+- Final consolidated summary when all subtasks complete
+- Modified code files throughout project
+
+## Notes
+
+**vs. `/cli:execute`**:
+- `/cli:execute`: Single-shot execution with Gemini/Qwen/Codex
+- `/cli:codex-execute`: Multi-stage Codex execution with automatic task decomposition and resume mechanism
+
+**Input Flexibility**: Accepts both freeform descriptions and task IDs (auto-detects and loads JSON)
+
+**Context Window**: `codex exec "..." resume --last` maintains conversation history, ensuring consistency across subtasks without redundant context injection.
+
+**Output Details**:
+- Output routing and scratchpad details: see workflow-architecture.md
+- Session management: see intelligent-tools-strategy.md
+- **⚠️ Code Modification**: This command performs multi-stage code modifications - execution log tracks all changes

.claude/commands/cli/execute.md

@@ -9,227 +9,177 @@ examples:
   - /cli:execute --tool codex IMPL-001
   - /cli:execute --enhance "fix API performance issues"
 allowed-tools: SlashCommand(*), Bash(*)
-model: sonnet
 ---
 
 # CLI Execute Command (/cli:execute)
 
-## Overview
+## Purpose
 
-**⚡ YOLO-enabled execution**: Auto-approves all confirmations for streamlined implementation workflow.
-
-**Purpose**: Execute implementation tasks using intelligent context inference and CLI tools with full permissions.
+Execute implementation tasks with **YOLO permissions** (auto-approves all confirmations). **MODIFIES CODE**.
 
+**Intent**: Autonomous code implementation, modification, and generation
 **Supported Tools**: codex, gemini (default), qwen
+**Key Feature**: Automatic context inference and file pattern detection
 
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
+## Core Behavior
 
-## 🚨 YOLO Permissions
+1. **Code Modification**: This command MODIFIES, CREATES, and DELETES code files
+2. **Auto-Approval**: YOLO mode bypasses confirmation prompts for all operations
+3. **Implementation Focus**: Executes actual code changes, not just recommendations
+4. **Requires Explicit Intent**: Use only when implementation is intended
 
-**All confirmations auto-approved by default:**
-- ✅ File pattern inference confirmation
-- ✅ Gemini execution confirmation
-- ✅ File modification confirmation
-- ✅ Implementation summary generation
+## Core Concepts
 
-## 🎯 Enhancement Integration
+### YOLO Permissions
+Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**When `--enhance` flag present** (for Description Mode only):
+**⚠️ WARNING**: This command will make actual code changes without manual confirmation
+
+### Execution Modes
+
+**1. Description Mode** (supports `--enhance`):
+- Input: Natural language description
+- Process: [Optional: Enhance] → Keyword analysis → Pattern inference → Execute
+
+**2. Task ID Mode** (no `--enhance`):
+- Input: Workflow task identifier (e.g., `IMPL-001`)
+- Process: Task JSON parsing → Scope analysis → 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}`
+
+For precise file targeting, use `rg` or MCP tools to discover files first.
+
+### Codex Session Continuity
+
+**Resume Pattern** for related tasks:
 ```bash
-# Step 1: Enhance the description
-SlashCommand(command="/enhance-prompt \"[description]\"")
+# First task - establish session
+codex -C [dir] --full-auto exec "[task]" --skip-git-repo-check -s danger-full-access
 
-# Step 2: Use enhanced output for execution
-# Enhanced output provides:
-# - INTENT: Clear technical goal
-# - CONTEXT: Session memory + codebase patterns
-# - ACTION: Specific implementation steps
-# - ATTENTION: Critical constraints
+# Related task - continue session
+codex --full-auto exec "[related-task]" resume --last --skip-git-repo-check -s danger-full-access
 ```
 
-**Example**:
-```bash
-# User: /gemini:execute --enhance "fix login"
+Use `resume --last` when current task extends/relates to previous execution. See intelligent-tools-strategy.md for auto-resume rules.
 
-# Step 1: Enhance
-/enhance-prompt "fix login"
-# Returns:
-# INTENT: Debug authentication failure in login flow
-# CONTEXT: JWT auth in src/auth/, known token expiry issue
-# ACTION: Fix token validation → update refresh logic → test flow
-# ATTENTION: Preserve existing session management
+## Parameters
 
-# Step 2: Execute with enhanced context
-gemini --all-files -p "@{src/auth/**/*} @{CLAUDE.md}
-Implementation: Debug authentication failure in login flow
-Focus: Token validation, refresh logic, test flow
-Constraints: Preserve existing session management"
-```
-
-**Note**: `--enhance` only applies to Description Mode. Task ID Mode uses task JSON directly.
-
-## Execution Modes
-
-### 1. Description Mode (supports --enhance)
-**Input**: Natural language description
-```bash
-/gemini:execute "implement JWT authentication with middleware"
-/gemini:execute --enhance "implement JWT authentication with middleware"
-```
-**Process**: [Optional: Enhance] → Keyword analysis → Pattern inference → Context collection → Execution
-
-### 2. Task ID Mode (no --enhance)
-**Input**: Workflow task identifier
-```bash
-/gemini:execute IMPL-001
-```
-**Process**: Task JSON parsing → Scope analysis → Context integration → Execution
-
-## Context Inference Logic
-
-**Auto-selects relevant files based on:**
-- **Keywords**: "auth" → `@{**/*auth*,**/*user*}`
-- **Technology**: "React" → `@{src/**/*.{jsx,tsx}}`
-- **Task Type**: "api" → `@{**/api/**/*,**/routes/**/*}`
-- **Always includes**: `@{CLAUDE.md,**/*CLAUDE.md}`
-
-## Command Options
-
-| Option | Purpose |
-|--------|---------|
-| `--debug` | Verbose execution logging |
-| `--save-session` | Save complete execution session to workflow |
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini)
+- `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
+- `<description|task-id>` - Natural language description or task identifier
+- `--debug` - Verbose logging
+- `--save-session` - Save execution to workflow session
 
 ## Workflow Integration
 
-### Session Management
-⚠️ **Auto-detects active session**: Checks `.workflow/.active-*` marker file
+**Session Management**: Auto-detects `.workflow/.active-*` marker
+- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- No session: Create new session or save to scratchpad
 
-**Session storage:**
-- **Active session exists**: Saves to `.workflow/WFS-[topic]/.chat/execute-[timestamp].md`
-- **No active session**: Creates new session directory
+**Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
+
+## Output Routing
+
+**Execution Log Destination**:
+- **IF** active workflow session exists:
+  - Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+  - Update task status in `.task/[TASK-ID].json` (if task ID provided)
+  - Generate summary in `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md`
+- **ELSE** (no active session):
+  - **Option 1**: Create new workflow session for task
+  - **Option 2**: Save to `.workflow/.scratchpad/execute-[description]-[timestamp].md`
+
+**Output Files** (when active session exists):
+- Execution log: `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+- Task summary: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+- Modified code: Project files per implementation
+
+**Examples**:
+- During session `WFS-auth-system`, executing `IMPL-001`:
+  - Log: `.workflow/WFS-auth-system/.chat/execute-20250105-143022.md`
+  - Summary: `.workflow/WFS-auth-system/.summaries/IMPL-001-summary.md`
+- No session, ad-hoc implementation:
+  - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
+
+## Command Template
 
-### Task Integration
-```bash
-# Execute specific workflow task
-/gemini:execute IMPL-001
-
-# Loads from: .task/IMPL-001.json
-# Uses: task context, brainstorming refs, scope definitions
-# Updates: workflow status, generates summary
-```
-
-## Execution Templates
-
-**Core Guidelines**: @~/.claude/workflows/intelligent-tools-strategy.md
-
-### Permission Requirements
-
-**Gemini Write Access** (when file modifications needed):
-- Add `--approval-mode yolo` flag for auto-approval
-- Required for: file creation, modification, deletion
-
-### User Description Template
-```bash
-cd [target-directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: [clear implementation goal from description]
-TASK: [specific implementation task]
-CONTEXT: @{inferred_patterns} @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Implementation code with file:line locations, test cases, integration guidance
-RULES: [template reference if applicable] | [constraints]
-"
-```
-
-**Example**:
 ```bash
+# Gemini/Qwen: MODE=write with --approval-mode yolo
 cd . && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: Implement JWT authentication with middleware
-TASK: Create authentication system with token validation
-CONTEXT: @{**/*auth*,**/*middleware*} @{CLAUDE.md}
-EXPECTED: Auth service, middleware, tests with file modifications
-RULES: Follow existing auth patterns | Security best practices
+PURPOSE: [implementation goal]
+TASK: [specific implementation]
+MODE: write
+CONTEXT: @{CLAUDE.md} [auto-detected files]
+EXPECTED: Working implementation with code changes
+RULES: [constraints] | Auto-approve all changes
 "
+
+# Codex: MODE=auto with danger-full-access
+codex -C . --full-auto exec "
+PURPOSE: [implementation goal]
+TASK: [specific implementation]
+MODE: auto
+CONTEXT: [auto-detected files]
+EXPECTED: Complete implementation with tests
+" --skip-git-repo-check -s danger-full-access
 ```
 
-### Task ID Template
+## Examples
+
+**Basic Implementation** (⚠️ modifies code):
 ```bash
-cd [task-directory] && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: [task_title]
-TASK: Execute [task-id] implementation
-CONTEXT: @{task_files} @{brainstorming_refs} @{CLAUDE.md,**/*CLAUDE.md}
-EXPECTED: Complete implementation following acceptance criteria
-RULES: $(cat [task_template]) | Task type: [task_type], Scope: [task_scope]
-"
+/cli:execute "implement JWT authentication with middleware"
+# Executes: Creates auth middleware, updates routes, modifies config
+# Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Example**:
+**Enhanced Implementation** (⚠️ modifies code):
 ```bash
-cd .workflow/WFS-123 && ~/.claude/scripts/gemini-wrapper --approval-mode yolo -p "
-PURPOSE: Implement user profile editing
-TASK: Execute IMPL-001 implementation
-CONTEXT: @{src/user/**/*} @{.brainstorming/feature-planner/analysis.md} @{CLAUDE.md}
-EXPECTED: Profile edit API, UI components, validation, tests
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/development/feature.txt) | Type: feature, Scope: user module
-"
+/cli:execute --enhance "implement JWT authentication"
+# Step 1: Enhance to expand requirements
+# Step 2: Execute implementation with auto-approval
+# Result: Complete auth system with MODIFIED code files
 ```
 
-## Auto-Generated Outputs
-
-### 1. Implementation Summary
-**Location**: `.summaries/[TASK-ID]-summary.md` or auto-generated ID
-
-```markdown
-# Task Summary: [Task-ID] [Description]
-
-## Implementation
-- **Files Modified**: [file:line references]
-- **Features Added**: [specific functionality]
-- **Context Used**: [inferred patterns]
-
-## Integration
-- [Links to workflow documents]
+**Task Execution** (⚠️ modifies code):
+```bash
+/cli:execute IMPL-001
+# Reads: .task/IMPL-001.json for requirements
+# Executes: Implementation based on task spec
+# Result: Code changes per task definition
 ```
 
-### 2. Execution Session
-**Location**: `.chat/execute-[timestamp].md`
-
-```markdown
-# Execution Session: [Timestamp]
-
-## Input
-[User description or Task ID]
-
-## Context Inference
-[File patterns used with rationale]
-
-## Implementation Results
-[Generated code and modifications]
-
-## Status Updates
-[Workflow integration updates]
+**Codex Implementation** (⚠️ modifies code):
+```bash
+/cli:execute --tool codex "optimize database queries"
+# Executes: Codex with full file access
+# Result: MODIFIED query code, new indexes, updated tests
 ```
 
-## Error Handling
+**Qwen Code Generation** (⚠️ modifies code):
+```bash
+/cli:execute --tool qwen --enhance "refactor auth module"
+# Step 1: Enhanced refactoring plan
+# Step 2: Execute with MODE=write
+# Result: REFACTORED auth code with structural changes
+```
 
-- **Task ID not found**: Lists available tasks
-- **Pattern inference failure**: Uses generic `src/**/*` pattern
-- **Execution failure**: Attempts fallback with simplified context
-- **File modification errors**: Reports specific file/permission issues
+## Comparison with Analysis Commands
 
-## Performance Features
+| Command | Intent | Code Changes | Auto-Approve |
+|---------|--------|--------------|--------------|
+| `/cli:analyze` | Understand code | ❌ NO | N/A |
+| `/cli:chat` | Ask questions | ❌ NO | N/A |
+| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
 
-- **Smart caching**: Frequently used pattern mappings
-- **Progressive inference**: Precise → broad pattern fallback
-- **Parallel execution**: When multiple contexts needed
-- **Directory optimization**: Switches to optimal execution path
-
-## Integration Workflow
-
-**Typical sequence:**
-1. `workflow:plan` → Creates tasks
-2. `/gemini:execute IMPL-001` → Executes with YOLO permissions
-3. Auto-updates workflow status and generates summaries
-4. `workflow:review` → Final validation
-
-**vs. `/gemini:analyze`**: Execute performs analysis **and implementation**, analyze is read-only.
+## 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-index.md

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

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

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

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

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

.claude/commands/task/breakdown.md

@@ -88,8 +88,9 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 ### Agent Assignment
 - **Design/Planning** → `@planning-agent`
 - **Implementation** → `@code-developer`
-- **Testing** → `@code-review-test-agent`
-- **Review** → `@review-agent`
+- **Testing** → `@code-developer` (type: "test-gen")
+- **Test Validation** → `@test-fix-agent` (type: "test-fix")
+- **Review** → `@general-purpose` (optional)
 
 ### Context Inheritance
 - Subtasks inherit parent requirements
@@ -161,8 +162,8 @@ See @~/.claude/workflows/workflow-architecture.md for:
 
 ▸ impl-1: Build authentication (container)
   ├── impl-1.1: Design schema → @planning-agent
-  ├── impl-1.2: Implement logic → @code-developer
-  └── impl-1.3: Write tests → @code-review-test-agent
+  ├── impl-1.2: Implement logic + tests → @code-developer
+  └── impl-1.3: Execute & fix tests → @test-fix-agent
 ```
 
 ## Error Handling

.claude/commands/task/create.md

@@ -107,8 +107,9 @@ Tasks inherit from:
 Based on task type and title keywords:
 - **Build/Implement** → @code-developer
 - **Design/Plan** → @planning-agent
-- **Test/Validate** → @code-review-test-agent
-- **Review/Audit** → @review-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)
 
 ## Validation Rules
 

.claude/commands/task/execute.md

@@ -24,8 +24,8 @@ examples:
     -   Executes step-by-step, requiring user confirmation at each checkpoint.
     -   Allows for dynamic adjustments and manual review during the process.
 -   **review**
-    -   Executes under the supervision of a `@review-agent`.
-    -   Performs quality checks and provides detailed feedback at each step.
+    -   Optional manual review using `@general-purpose`.
+    -   Used only when explicitly requested by user.
 
 ### 🤖 **Agent Selection Logic**
 
@@ -45,10 +45,12 @@ FUNCTION select_agent(task, agent_override):
                 RETURN "@code-developer"
             WHEN CONTAINS "Design schema", "Plan":
                 RETURN "@planning-agent"
-            WHEN CONTAINS "Write tests":
-                RETURN "@code-review-test-agent"
+            WHEN CONTAINS "Write tests", "Generate tests":
+                RETURN "@code-developer" // type: test-gen
+            WHEN CONTAINS "Execute tests", "Fix tests", "Validate":
+                RETURN "@test-fix-agent" // type: test-fix
             WHEN CONTAINS "Review code":
-                RETURN "@review-agent"
+                RETURN "@general-purpose" // Optional manual review
             DEFAULT:
                 RETURN "@code-developer" // Default agent
         END CASE
@@ -232,13 +234,15 @@ Different agents receive context tailored to their function, including implement
 - Implementation risks and mitigation strategies
 - Architecture implications from implementation.context_notes
 
-**`@code-review-test-agent`**: 
-- Files to test from implementation.files[].path
-- Logic flows to validate from implementation.modifications.logic_flow
-- Error conditions to test from implementation.context_notes.error_handling
-- Performance benchmarks from implementation.context_notes.performance_considerations
+**`@test-fix-agent`**:
+- Test files to execute from task.context.focus_paths
+- Source files to fix from implementation.files[].path
+- Expected behaviors from implementation.modifications.logic_flow
+- Error conditions to validate from implementation.context_notes.error_handling
+- Performance requirements from implementation.context_notes.performance_considerations
 
-**`@review-agent`**: 
+**`@general-purpose`**:
+- Used for optional manual reviews when explicitly requested
 - Code quality standards and implementation patterns
 - Security considerations from implementation.context_notes.risks
 - Dependency validation from implementation.context_notes.dependencies

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

@@ -1,40 +1,55 @@
 ---
 name: update-memory-full
 description: Complete project-wide CLAUDE.md documentation update
-usage: /update-memory-full
+usage: /update-memory-full [--tool <gemini|qwen|codex>]
+argument-hint: "[--tool gemini|qwen|codex]"
 examples:
-  - /update-memory-full                      # Full project documentation update
+  - /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: Code Index architecture analysis
+# 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 2: Cache git changes
+# Step 3: Cache git changes
 Bash(git add -A 2>/dev/null || true)
 
-# Step 3: Get and display project structure
+# Step 4: Get and display project structure
 modules=$(Bash(~/.claude/scripts/get_modules_by_depth.sh list))
 count=$(echo "$modules" | wc -l)
 
-# Step 3: Analysis handover → Model takes control
+# Step 5: Analysis handover → Model takes control
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 
 # Pseudocode flow:
 # IF (module_count > 20 OR complex_project_detected):
-#     → Task "Complex project full update" subagent_type: "memory-gemini-bridge"
+#     → 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
@@ -43,9 +58,9 @@ 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**: 
+3. **Choose Strategy**:
    - Simple projects: Present execution plan with CLAUDE.md paths to user
-   - Complex projects: Delegate to memory-gemini-bridge agent
+   - Complex projects: Delegate to memory-bridge agent
 4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated
 5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
 
@@ -56,17 +71,19 @@ After the bash script completes the initial analysis, the model takes control to
 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)
 ```
 
@@ -84,7 +101,7 @@ depth_modules = organize_by_depth(modules)
 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" &)
+        Bash(~/.claude/scripts/update_module_claude.sh "$module" "full" "$tool" &)
     wait_all_jobs()
 
 # Step 6: Safety check and restore staging state
@@ -102,13 +119,43 @@ Bash(git status --short)
 ```
 
 **For Complex Projects (>20 modules):**
-The model will delegate to the memory-gemini-bridge agent using the Task tool:
-```
+
+The model will delegate to the memory-bridge agent with structured context:
+
+```javascript
 Task "Complex project full update"
-prompt: "Execute full documentation update for [count] modules using depth-parallel execution"
-subagent_type: "memory-gemini-bridge"
+subagent_type: "memory-bridge"
+prompt: `
+CONTEXT:
+- Total modules: ${module_count}
+- Tool: ${tool}  // from --tool parameter, default: gemini
+- Mode: full
+- Existing CLAUDE.md: ${existing_count}
+- New CLAUDE.md needed: ${new_count}
+
+MODULE LIST:
+${modules_output}  // Full output from get_modules_by_depth.sh list
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level before execution
+2. Process depths 5→0 sequentially, max 4 parallel jobs per depth
+3. Command format: update_module_claude.sh "<path>" "full" "${tool}" &
+4. Extract exact path from "depth:N|path:<PATH>|..." format
+5. Verify all ${module_count} modules are processed
+6. Run safety check after completion
+7. Display git status
+
+Execute depth-parallel updates for all modules.
+`
 ```
 
+**Agent receives complete context:**
+- Module count and tool selection
+- Full structured module list
+- Clear execution requirements
+- Path extraction format
+- Success criteria
+
 
 ### 📚 Usage Examples
 

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

@@ -1,15 +1,23 @@
 ---
 name: update-memory-related
 description: Context-aware CLAUDE.md documentation updates based on recent changes
-usage: /update-memory-related
+usage: /update-memory-related [--tool <gemini|qwen|codex>]
+argument-hint: "[--tool gemini|qwen|codex]"
 examples:
-  - /update-memory-related                    # Update documentation based on recent changes
+  - /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
 
@@ -17,30 +25,37 @@ Context-aware documentation update for modules affected by recent changes.
 #!/bin/bash
 # Context-aware CLAUDE.md documentation update
 
-# Step 1: Code Index refresh and architecture analysis
+# 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 2: Detect changed modules (before staging)
+# Step 3: Detect changed modules (before staging)
 changed=$(Bash(~/.claude/scripts/detect_changed_modules.sh list))
 
-# Step 3: Cache git changes (protect current state)
+# Step 4: Cache git changes (protect current state)
 Bash(git add -A 2>/dev/null || true)
 
-# Step 3: Use detected changes or fallback
+# 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 4: Analysis handover → Model takes control  
+# Step 6: Analysis handover → Model takes control
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 
 # Pseudocode flow:
 # IF (change_count > 15 OR complex_changes_detected):
-#     → Task "Complex project related update" subagent_type: "memory-gemini-bridge"
+#     → 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
@@ -51,7 +66,7 @@ After the bash script completes change detection, the model takes control to:
 2. **Parse CLAUDE.md Status**: Extract which changed modules have/need CLAUDE.md files
 3. **Choose Strategy**: 
    - Simple changes: Present execution plan with CLAUDE.md paths to user
-   - Complex changes: Delegate to memory-gemini-bridge agent
+   - Complex changes: Delegate to memory-bridge agent
 4. **Present Detailed Plan**: Show user exactly which CLAUDE.md files will be created/updated for changed modules
 5. **⚠️ CRITICAL: WAIT FOR USER APPROVAL**: No execution without explicit user consent
 
@@ -62,18 +77,20 @@ After the bash script completes change detection, the model takes control to:
 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)
 ```
 
@@ -91,7 +108,7 @@ depth_modules = organize_by_depth(changed_modules)
 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" &)
+        Bash(~/.claude/scripts/update_module_claude.sh "$module" "related" "$tool" &)
     wait_all_jobs()
 
 # Step 6: Safety check and restore staging state
@@ -109,13 +126,44 @@ Bash(git diff --stat)
 ```
 
 **For Complex Changes (>15 modules):**
-The model will delegate to the memory-gemini-bridge agent using the Task tool:
-```
+
+The model will delegate to the memory-bridge agent with structured context:
+
+```javascript
 Task "Complex project related update"
-prompt: "Execute context-aware update for [count] changed modules using depth-parallel execution"
-subagent_type: "memory-gemini-bridge"
+subagent_type: "memory-bridge"
+prompt: `
+CONTEXT:
+- Total modules: ${change_count}
+- Tool: ${tool}  // from --tool parameter, default: gemini
+- Mode: related
+- Changed modules detected via: detect_changed_modules.sh
+- Existing CLAUDE.md: ${existing_count}
+- New CLAUDE.md needed: ${new_count}
+
+MODULE LIST:
+${changed_modules_output}  // Full output from detect_changed_modules.sh list
+
+REQUIREMENTS:
+1. Use TodoWrite to track each depth level before execution
+2. Process depths sequentially (deepest→shallowest), max 4 parallel jobs per depth
+3. Command format: update_module_claude.sh "<path>" "related" "${tool}" &
+4. Extract exact path from "depth:N|path:<PATH>|..." format
+5. Verify all ${change_count} modules are processed
+6. Run safety check after completion
+7. Display git diff --stat
+
+Execute depth-parallel updates for changed modules only.
+`
 ```
 
+**Agent receives complete context:**
+- Changed module count and tool selection
+- Full structured module list (changed only)
+- Clear execution requirements with "related" mode
+- Path extraction format
+- Success criteria
+
 
 ### 📚 Usage Examples
 

.claude/commands/version.md

@@ -0,0 +1,261 @@
+---
+name: version
+description: Display version information and check for updates
+usage: /version
+examples:
+  - /version
+allowed-tools: Bash(*)
+---
+
+# Version Command (/version)
+
+## Purpose
+Display local and global installation versions, check for the latest updates from GitHub, and provide upgrade recommendations.
+
+## Execution Flow
+1. **Local Version Check**: Read version information from `./.claude/version.json` if it exists.
+2. **Global Version Check**: Read version information from `~/.claude/version.json` if it exists.
+3. **Fetch Remote Versions**: Use GitHub API to get the latest stable release tag and the latest commit hash from the main branch.
+4. **Compare & Suggest**: Compare installed versions with the latest remote versions and provide upgrade suggestions if applicable.
+
+## Step 1: Check Local Version
+
+### Check if local version.json exists
+```bash
+bash(test -f ./.claude/version.json && echo "found" || echo "not_found")
+```
+
+### Read local version (if exists)
+```bash
+bash(cat ./.claude/version.json)
+```
+
+### Extract version with jq (preferred)
+```bash
+bash(cat ./.claude/version.json | grep -o '"version": *"[^"]*"' | cut -d'"' -f4)
+```
+
+### Extract installation date
+```bash
+bash(cat ./.claude/version.json | grep -o '"installation_date_utc": *"[^"]*"' | cut -d'"' -f4)
+```
+
+**Output Format**:
+```
+Local Version: 3.2.1
+Installed: 2025-10-03T12:00:00Z
+```
+
+## Step 2: Check Global Version
+
+### Check if global version.json exists
+```bash
+bash(test -f ~/.claude/version.json && echo "found" || echo "not_found")
+```
+
+### Read global version
+```bash
+bash(cat ~/.claude/version.json)
+```
+
+### Extract version
+```bash
+bash(cat ~/.claude/version.json | grep -o '"version": *"[^"]*"' | cut -d'"' -f4)
+```
+
+### Extract installation date
+```bash
+bash(cat ~/.claude/version.json | grep -o '"installation_date_utc": *"[^"]*"' | cut -d'"' -f4)
+```
+
+**Output Format**:
+```
+Global Version: 3.2.1
+Installed: 2025-10-03T12:00:00Z
+```
+
+## Step 3: Fetch Latest Stable Release
+
+### Call GitHub API for latest release (with timeout)
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null, timeout: 30000)
+```
+
+### Extract tag name (version)
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"tag_name": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000)
+```
+
+### Extract release name
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"name": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000)
+```
+
+### Extract published date
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"published_at": *"[^"]*"' | cut -d'"' -f4, timeout: 30000)
+```
+
+**Output Format**:
+```
+Latest Stable: v3.2.2
+Release: v3.2.2: Independent Test-Gen Workflow with Cross-Session Context
+Published: 2025-10-03T04:10:08Z
+```
+
+## Step 4: Fetch Latest Main Branch
+
+### Call GitHub API for latest commit on main (with timeout)
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null, timeout: 30000)
+```
+
+### Extract commit SHA (short)
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4 | cut -c1-7, timeout: 30000)
+```
+
+### Extract commit message (first line only)
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep '"message":' | cut -d'"' -f4 | cut -d'\' -f1, timeout: 30000)
+```
+
+### Extract commit date
+```bash
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep -o '"date": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000)
+```
+
+**Output Format**:
+```
+Latest Dev: a03415b
+Message: feat: Add version tracking and upgrade check system
+Date: 2025-10-03T04:46:44Z
+```
+
+## Step 5: Compare Versions and Suggest Upgrade
+
+### Normalize versions (remove 'v' prefix)
+```bash
+bash(echo "v3.2.1" | sed 's/^v//')
+```
+
+### Compare two versions
+```bash
+bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1)
+```
+
+### Check if versions are equal
+```bash
+# If equal: Up to date
+# If remote newer: Upgrade available
+# If local newer: Development version
+```
+
+**Output Scenarios**:
+
+**Scenario 1: Up to date**
+```
+✅ You are on the latest stable version (3.2.1)
+```
+
+**Scenario 2: Upgrade available**
+```
+⬆️ A newer stable version is available: v3.2.2
+Your version: 3.2.1
+
+To upgrade:
+PowerShell: iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1)
+Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.sh)
+```
+
+**Scenario 3: Development version**
+```
+✨ You are running a development version (3.4.0-dev)
+This is newer than the latest stable release (v3.3.0)
+```
+
+## Simple Bash Commands
+
+### Basic Operations
+```bash
+# Check local version file
+bash(test -f ./.claude/version.json && cat ./.claude/version.json)
+
+# Check global version file
+bash(test -f ~/.claude/version.json && cat ~/.claude/version.json)
+
+# Extract version from JSON
+bash(cat version.json | grep -o '"version": *"[^"]*"' | cut -d'"' -f4)
+
+# Extract date from JSON
+bash(cat version.json | grep -o '"installation_date_utc": *"[^"]*"' | cut -d'"' -f4)
+
+# Fetch latest release (with timeout)
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null, timeout: 30000)
+
+# Extract tag name
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4, timeout: 30000)
+
+# Extract release name
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest" 2>/dev/null | grep -o '"name": *"[^"]*"' | head -1 | cut -d'"' -f4, timeout: 30000)
+
+# Fetch latest commit (with timeout)
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null, timeout: 30000)
+
+# Extract commit SHA
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep -o '"sha": *"[^"]*"' | head -1 | cut -d'"' -f4 | cut -c1-7, timeout: 30000)
+
+# Extract commit message (first line)
+bash(curl -fsSL "https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main" 2>/dev/null | grep '"message":' | cut -d'"' -f4 | cut -d'\' -f1, timeout: 30000)
+
+# Compare versions
+bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1)
+
+# Remove 'v' prefix
+bash(echo "v3.2.1" | sed 's/^v//')
+```
+
+## Error Handling
+
+### No installation found
+```
+WARNING: Claude Code Workflow not installed
+Install using:
+PowerShell: iex (iwr -useb https://raw.githubusercontent.com/catlog22/Claude-Code-Workflow/main/install-remote.ps1)
+```
+
+### Network error
+```
+ERROR: Could not fetch latest version from GitHub
+Check your network connection
+```
+
+### Invalid version.json
+```
+ERROR: version.json is invalid or corrupted
+```
+
+## Design Notes
+
+- Uses simple, direct bash commands instead of complex functions
+- Each step is independent and can be executed separately
+- Fallback to grep/sed for JSON parsing (no jq dependency required)
+- Network calls use curl with error suppression and 30-second timeout
+- Version comparison uses `sort -V` for accurate semantic versioning
+- Use `/commits/main` API instead of `/branches/main` for more reliable commit info
+- Extract first line of commit message using `cut -d'\' -f1` to handle JSON escape sequences
+
+## API Endpoints
+
+### GitHub API Used
+- **Latest Release**: `https://api.github.com/repos/catlog22/Claude-Code-Workflow/releases/latest`
+  - Fields: `tag_name`, `name`, `published_at`
+- **Latest Commit**: `https://api.github.com/repos/catlog22/Claude-Code-Workflow/commits/main`
+  - Fields: `sha`, `commit.message`, `commit.author.date`
+
+### Timeout Configuration
+All network calls should use `timeout: 30000` (30 seconds) to handle slow connections.
+
+## Related Commands
+- `/cli:cli-init` - Initialize CLI configurations
+- `/workflow:session:list` - List workflow sessions

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

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

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

@@ -5,8 +5,8 @@ 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,security-expert"
-  - /workflow:brainstorm:artifacts "Implement secure authentication system" --roles "ui-designer,security-expert,user-researcher"
+  - /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(*)
 ---
 
@@ -91,10 +91,11 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 **Document Structure**:
 ```
 .workflow/WFS-[topic]/.brainstorming/
-├── topic-framework.md          # ★ STRUCTURED FRAMEWORK DOCUMENT
-└── workflow-session.json               # Framework metadata and role assignments
+└── 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
@@ -109,7 +110,7 @@ Framework content adapts based on `--roles` parameter:
 - **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, security-expert
+- **Target Roles**: ui-designer, system-architect, subject-matter-expert
 
 ## Role-Specific Discussion Points
 
@@ -135,21 +136,21 @@ Framework content adapts based on `--roles` parameter:
    - What are the performance requirements?
    - What dependencies must be managed?
 
-### For Security Expert
-1. **Security Requirements**
-   - What are the key security concerns?
-   - What threat vectors must be addressed?
-   - What compliance requirements apply?
+### 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. **Security Implementation**
-   - What authentication/authorization is needed?
-   - What data protection mechanisms are required?
-   - How to handle security incidents?
+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 security requirements affect both UI and architecture?
+- What domain standards affect both UI and architecture?
 
 ## Framework Usage
 **For Role Agents**: Address your specific section + integration points
@@ -157,7 +158,7 @@ Framework content adapts based on `--roles` parameter:
 **Update Process**: Use /workflow:brainstorm:artifacts to update
 
 ---
-*Generated for roles: ui-designer, system-architect, security-expert*
+*Generated for roles: ui-designer, system-architect, subject-matter-expert*
 *Last updated: [timestamp]*
 ```
 
@@ -200,9 +201,9 @@ Framework content adapts based on `--roles` parameter:
 
 ## Available Role Perspectives
 Framework supports analysis from any of these roles:
-- system-architect, ui-designer, security-expert
-- user-researcher, product-manager, business-analyst
-- data-architect, innovation-lead, feature-planner
+- **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*
@@ -216,17 +217,17 @@ Framework supports analysis from any of these roles:
 **Technical Roles**:
 - `system-architect`: Architecture patterns, scalability, technology stack, integration
 - `data-architect`: Data modeling, processing workflows, analytics, storage
-- `security-expert`: Security requirements, threat modeling, compliance, protection
+- `subject-matter-expert`: Domain expertise, industry standards, compliance, best practices
 
 **Product & Design Roles**:
 - `ui-designer`: User interface, visual design, interaction patterns, accessibility
-- `user-researcher`: User needs, behavior analysis, usability testing, personas
+- `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
 
-**Business Roles**:
-- `business-analyst`: Process optimization, requirements analysis, cost-benefit, ROI
-- `innovation-lead`: Emerging technologies, competitive advantage, transformation, trends
-- `feature-planner`: Feature specification, user stories, acceptance criteria, dependencies
+**Agile & Quality Roles**:
+- `scrum-master`: Sprint planning, team dynamics, process optimization, delivery management
+- `test-strategist`: Testing strategies, quality assurance, test automation, validation approaches
 
 ### Dynamic Discussion Point Generation
 
@@ -248,23 +249,32 @@ Generate:
 
 #### Example 1: Architecture-Heavy Topic
 ```bash
-/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,security-expert"
+/workflow:brainstorm:artifacts "Design scalable microservices platform" --roles "system-architect,data-architect,subject-matter-expert"
 ```
 **Generated framework focuses on**:
 - Service architecture and communication patterns
 - Data flow and storage strategies
-- Security boundaries and authentication
+- Domain standards and best practices
 
 #### Example 2: User-Focused Topic
 ```bash
-/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,user-researcher,product-manager"
+/workflow:brainstorm:artifacts "Improve user onboarding experience" --roles "ui-designer,ux-expert,product-manager"
 ```
 **Generated framework focuses on**:
 - Onboarding flow and UI components
-- User behavior and pain points
+- User experience optimization and usability
 - Business value and success metrics
 
-#### Example 3: Comprehensive Analysis
+#### Example 3: Agile Delivery Topic
+```bash
+/workflow:brainstorm:artifacts "Optimize sprint delivery process" --roles "scrum-master,product-owner,test-strategist"
+```
+**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"
 ```

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

@@ -18,15 +18,17 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 ```
 
 ## Role Selection Logic
-- **Technical & Architecture**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert
-- **Product & UX**: `user|ui|ux|interface|design|product|feature` → ui-designer, user-researcher, product-manager
+- **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**: business-analyst, data-architect, feature-planner, innovation-lead, product-manager, security-expert, system-architect, test-strategist, ui-designer, user-researcher
+**Available Roles**: data-architect, product-manager, product-owner, scrum-master, subject-matter-expert, system-architect, test-strategist, ui-designer, ux-expert
 
 **Example**:
 ```bash
@@ -72,9 +74,10 @@ Auto command coordinates independent specialized commands:
 4. **Command coordination**: SlashCommand handles execution and validation
 
 **Role Selection Logic**:
-- **Technical**: `architecture|system|performance|database|security` → system-architect, data-architect, security-expert
-- **Product & UX**: `user|ui|ux|interface|design|product|feature` → ui-designer, user-researcher, product-manager
-- **Business**: `business|process|workflow|cost|innovation` → business-analyst, innovation-lead
+- **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
@@ -146,7 +149,7 @@ Task(subagent_type="conceptual-planning-agent",
 
      3. **load_session_metadata**
         - Action: Load session metadata and topic description
-        - Command: bash(cat .workflow/WFS-{topic}/.brainstorming/workflow-session.json 2>/dev/null || echo '{}')
+        - Command: bash(cat .workflow/WFS-{topic}/workflow-session.json 2>/dev/null || echo '{}')
         - Output: session_metadata
 
      ### Implementation Context
@@ -159,7 +162,7 @@ Task(subagent_type="conceptual-planning-agent",
      ### Session Context
      **Workflow Directory**: .workflow/WFS-{topic}/.brainstorming/
      **Output Directory**: .workflow/WFS-{topic}/.brainstorming/{role}/
-     **Session JSON**: .workflow/WFS-{topic}/.brainstorming/workflow-session.json
+     **Session JSON**: .workflow/WFS-{topic}/workflow-session.json
 
      ### Dependencies & Context
      **Topic**: {user-provided-topic}

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

@@ -61,16 +61,16 @@ 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, security-expert
+  → system-architect, data-architect, subject-matter-expert
 - **UI/UX keywords**: `user|ui|ux|interface|design|frontend|experience`
-  → ui-designer, user-researcher
+  → ui-designer, ux-expert
 - **Product/Business keywords**: `product|feature|business|workflow|process|customer`
-  → product-manager, business-analyst
-- **Security keywords**: `security|auth|permission|encryption|compliance`
-  → security-expert
-- **Innovation keywords**: `innovation|new|disrupt|transform|emerging`
-  → innovation-lead
-- **Default**: ui-designer (if no clear match)
+  → 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
@@ -91,14 +91,14 @@ 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:security-expert")`
-- `SlashCommand(command="/workflow:brainstorm:user-researcher")`
-- `SlashCommand(command="/workflow:brainstorm:product-manager")`
-- `SlashCommand(command="/workflow:brainstorm:business-analyst")`
 - `SlashCommand(command="/workflow:brainstorm:data-architect")`
-- `SlashCommand(command="/workflow:brainstorm:innovation-lead")`
-- `SlashCommand(command="/workflow:brainstorm:feature-planner")`
+- `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
@@ -202,8 +202,8 @@ Return summary to user
 **Keywords detected**: user, interface, design
 **Selected roles**:
 - ui-designer (primary: UI/UX match)
-- user-researcher (secondary: user experience)
-- security-expert (complementary: auth security)
+- ux-expert (secondary: user experience)
+- subject-matter-expert (complementary: auth standards)
 
 ### Example 2: Architecture Topic
 **Topic**: "Design scalable microservices architecture"
@@ -211,15 +211,15 @@ Return summary to user
 **Selected roles**:
 - system-architect (primary: architecture match)
 - data-architect (secondary: scalability/data)
-- security-expert (complementary: system security)
+- subject-matter-expert (complementary: domain expertise)
 
-### Example 3: Business Process Topic
-**Topic**: "Optimize customer onboarding workflow"
-**Keywords detected**: workflow, process, customer
+### Example 3: Agile Delivery Topic
+**Topic**: "Optimize team sprint planning and delivery process"
+**Keywords detected**: sprint, team, delivery, process
 **Selected roles**:
-- business-analyst (primary: process match)
-- product-manager (secondary: customer focus)
-- ui-designer (complementary: user experience)
+- scrum-master (primary: agile process match)
+- product-owner (secondary: backlog/delivery focus)
+- product-manager (complementary: product strategy)
 
 ## Error Handling
 

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

@@ -88,7 +88,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/session.json)
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -136,7 +136,7 @@ TodoWrite({
       activeForm: "Generating structured data-architect analysis"
     },
     {
-      content: "Update session.json with data-architect completion status",
+      content: "Update workflow-session.json with data-architect completion status",
       status: "pending",
       activeForm: "Updating session metadata"
     }

.claude/commands/workflow/brainstorm/innovation-lead.md

@@ -1,254 +0,0 @@
----
-name: innovation-lead
-description: Generate or update innovation-lead/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:innovation-lead [topic]
-argument-hint: "optional topic - uses existing framework if available"
-examples:
-  - /workflow:brainstorm:innovation-lead
-  - /workflow:brainstorm:innovation-lead "AI integration opportunities"
-  - /workflow:brainstorm:innovation-lead "future technology trends"
-allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
----
-
-## 🚀 **Role Overview: Innovation Lead**
-
-### Role Definition
-Visionary technology strategist responsible for identifying emerging technology trends, evaluating disruptive innovation opportunities, and designing future-ready solutions that create competitive advantage and drive market transformation.
-
-### Core Responsibilities
-- **Trend Identification**: Identify and analyze emerging technology trends and market opportunities
-- **Innovation Strategy**: Develop innovation roadmaps and technology development strategies
-- **Technology Assessment**: Evaluate new technology application potential and feasibility
-- **Future Planning**: Design forward-looking product and service concepts
-
-### Focus Areas
-- **Emerging Technologies**: AI, blockchain, IoT, AR/VR, quantum computing, and other frontier technologies
-- **Market Trends**: Industry transformation, user behavior evolution, business model innovation
-- **Innovation Opportunities**: Disruptive innovation, blue ocean markets, technology convergence opportunities
-- **Future Vision**: Long-term technology roadmaps, proof of concepts, prototype development
-
-### Success Metrics
-- Innovation impact and market differentiation
-- Technology adoption rates and competitive advantage
-- Future readiness and strategic positioning
-- Breakthrough opportunity identification and validation
-
-## 🧠 **Analysis Framework**
-
-@~/.claude/workflows/brainstorming-principles.md
-
-### Key Analysis Questions
-
-**1. Emerging Trends and Technology Opportunities**
-- Which emerging technologies will have the greatest impact on our industry?
-- What is the technology maturity level and adoption timeline?
-- What new opportunities does technology convergence create?
-
-**2. Disruption Potential and Innovation Assessment**
-- What is the potential for disruptive innovation and its impact?
-- What innovation opportunities exist within current solutions?
-- What unmet market needs and demands exist?
-
-**3. Competitive Advantage and Market Analysis**
-- What are competitors' innovation strategies and directions?
-- What market gaps and blue ocean opportunities exist?
-- What technological barriers and first-mover advantages are available?
-
-**4. Implementation and Risk Assessment**
-- What is the feasibility and risk of technology implementation?
-- What are the investment requirements and expected returns?
-- What organizational innovation capabilities and adaptability are needed?
-
-## ⚡ **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
-**Innovation Lead Perspective Questioning**
-
-Before agent assignment, gather comprehensive innovation lead context:
-
-#### 📋 Role-Specific Questions
-
-**1. Emerging Trends and Future Technologies**
-- What emerging technologies or trends do you think will be most relevant to this topic?
-- Are there any specific industries or markets you want to explore for innovation opportunities?
-- What time horizon are you considering (near-term, medium-term, long-term disruption)?
-- Are there any particular technology domains you want to focus on (AI, IoT, blockchain, etc.)?
-
-**2. Innovation Opportunities and Market Potential**
-- What current limitations or pain points could be addressed through innovation?
-- Are there any unmet market needs or underserved segments you're aware of?
-- What would disruptive success look like in this context?
-- Are there cross-industry innovations that could be applied to this domain?
-
-**3. Disruption Potential and Competitive Landscape**
-- Who are the current market leaders and what are their innovation strategies?
-- What startup activity or venture capital investment trends are you seeing?
-- Are there any potential platform shifts or ecosystem changes on the horizon?
-- What would make a solution truly differentiated in the marketplace?
-
-**4. Implementation and Strategic Considerations**
-- What organizational capabilities or partnerships would be needed for innovation?
-- Are there regulatory, technical, or market barriers to consider?
-- What level of risk tolerance exists for breakthrough vs. incremental innovation?
-- How important is first-mover advantage versus fast-follower strategies?
-
-#### Context Validation
-- **Minimum Response**: Each answer must be ≥50 characters
-- **Re-prompting**: Insufficient detail triggers follow-up questions
-- **Context Storage**: Save responses to `.brainstorming/innovation-lead-context.md`
-
-### Step 2: Agent Assignment with Flow Control
-**Dedicated Agent Execution**
-
-```bash
-Task(conceptual-planning-agent): "
-[FLOW_CONTROL]
-
-Execute dedicated innovation lead conceptual analysis for: {topic}
-
-ASSIGNED_ROLE: innovation-lead
-OUTPUT_LOCATION: .brainstorming/innovation-lead/
-USER_CONTEXT: {validated_responses_from_context_gathering}
-
-Flow Control Steps:
-[
-  {
-    \"step\": \"load_role_template\",
-    \"action\": \"Load innovation-lead planning template\",
-    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/innovation-lead.md))\",
-    \"output_to\": \"role_template\"
-  }
-]
-
-Conceptual Analysis Requirements:
-- Apply innovation lead perspective to topic analysis
-- Focus on emerging trends, disruption potential, competitive advantage, and future opportunities
-- 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 innovation lead analysis
-- recommendations.md: Innovation lead recommendations
-- deliverables/: Innovation lead-specific outputs as defined in role template
-
-Embody innovation lead role expertise for comprehensive conceptual planning."
-```
-
-### Progress Tracking
-TodoWrite tracking for two-step process:
-```json
-[
-  {"content": "Gather innovation lead context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
-  {"content": "Validate context responses and save to innovation-lead-context.md", "status": "pending", "activeForm": "Validating context"},
-  {"content": "Load innovation-lead planning template via flow control", "status": "pending", "activeForm": "Loading template"},
-  {"content": "Execute dedicated conceptual-planning-agent for innovation-lead role", "status": "pending", "activeForm": "Executing agent"}
-]
-```
-
-## 📋 **TodoWrite Integration**
-
-### Workflow Progress Tracking
-```javascript
-TodoWrite({
-  todos: [
-    {
-      content: "Detect active session and locate topic framework",
-      status: "in_progress",
-      activeForm: "Detecting session and framework"
-    },
-    {
-      content: "Load topic-framework.md and session metadata for context",
-      status: "pending",
-      activeForm: "Loading framework and session context"
-    },
-    {
-      content: "Execute innovation-lead analysis using conceptual-planning-agent with FLOW_CONTROL",
-      status: "pending",
-      activeForm: "Executing innovation-lead framework analysis"
-    },
-    {
-      content: "Generate analysis.md addressing all framework discussion points",
-      status: "pending",
-      activeForm: "Generating structured innovation-lead analysis"
-    },
-    {
-      content: "Update session.json with innovation-lead completion status",
-      status: "pending",
-      activeForm: "Updating session metadata"
-    }
-  ]
-});
-```
-
-## 📊 **Output Structure**
-
-### Framework-Based Analysis
-```
-.workflow/WFS-{session}/.brainstorming/innovation-lead/
-└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
-```
-
-### Analysis Document Structure
-```markdown
-# Innovation Lead Analysis: [Topic from Framework]
-
-## Framework Reference
-**Topic Framework**: @../topic-framework.md
-**Role Focus**: Innovation and Emerging Technology perspective
-
-## Discussion Points Analysis
-[Address each point from topic-framework.md with innovation expertise]
-
-### Core Requirements (from framework)
-[Innovation perspective on emerging technology requirements]
-
-### Technical Considerations (from framework)
-[Future technology and breakthrough considerations]
-
-### User Experience Factors (from framework)
-[Future user behavior and interaction trends]
-
-### Implementation Challenges (from framework)
-[Innovation implementation and market adoption considerations]
-
-### Success Metrics (from framework)
-[Innovation success metrics and breakthrough criteria]
-
-## Innovation Specific Recommendations
-[Role-specific innovation opportunities and breakthrough concepts]
-
----
-*Generated by innovation-lead analysis addressing structured framework*
-```
-
-## 🔄 **Session Integration**
-
-### Completion Status Update
-```json
-{
-  "innovation_lead": {
-    "status": "completed",
-    "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/innovation-lead/analysis.md",
-    "framework_reference": "@../topic-framework.md"
-  }
-}
-```
-
-### Integration Points
-- **Framework Reference**: @../topic-framework.md for structured discussion points
-- **Cross-Role Synthesis**: Innovation insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance

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

@@ -88,7 +88,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/session.json)
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -136,7 +136,7 @@ TodoWrite({
       activeForm: "Generating structured product-manager analysis"
     },
     {
-      content: "Update session.json with product-manager completion status",
+      content: "Update workflow-session.json with product-manager completion status",
       status: "pending",
       activeForm: "Updating session metadata"
     }

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

@@ -1,31 +1,31 @@
 ---
-name: business-analyst
-description: Generate or update business-analyst/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:business-analyst [topic]
+name: product-owner
+description: Generate or update product-owner/analysis.md addressing topic-framework discussion points
+usage: /workflow:brainstorm:product-owner [topic]
 argument-hint: "optional topic - uses existing framework if available"
 examples:
-  - /workflow:brainstorm:business-analyst
-  - /workflow:brainstorm:business-analyst "workflow automation opportunities"
-  - /workflow:brainstorm:business-analyst "business process optimization"
+  - /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(*)
 ---
 
-## 📊 **Business Analyst Analysis Generator**
+## 🎯 **Product Owner Analysis Generator**
 
 ### Purpose
-**Specialized command for generating business-analyst/analysis.md** that addresses topic-framework.md discussion points from business analysis perspective. Creates or updates role-specific analysis with framework references.
+**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.
 
 ### Core Function
 - **Framework-based Analysis**: Address each discussion point in topic-framework.md
-- **Business Analysis Focus**: Process optimization, requirements analysis, and business efficiency perspective
+- **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
 
 ### Analysis Scope
-- **Process Analysis**: Analyze existing business processes for efficiency and improvement opportunities
-- **Requirements Analysis**: Identify and define business requirements and functional specifications
-- **Value Analysis**: Assess cost-benefit and ROI of business initiatives
-- **Change Management**: Plan organizational change and process transformation
+- **Backlog Management**: User story creation, refinement, and prioritization
+- **Stakeholder Alignment**: Requirements gathering, value definition, and expectation management
+- **Feature Prioritization**: ROI analysis, MoSCoW method, and value-driven delivery
+- **Acceptance Criteria**: Definition of Done, acceptance testing, and quality standards
 
 ## ⚙️ **Execution Protocol**
 
@@ -68,11 +68,11 @@ ELSE:
 Task(conceptual-planning-agent): "
 [FLOW_CONTROL]
 
-Execute business-analyst analysis for existing topic framework
+Execute product-owner analysis for existing topic framework
 
 ## Context Loading
-ASSIGNED_ROLE: business-analyst
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/business-analyst/
+ASSIGNED_ROLE: product-owner
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-owner/
 ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 ## Flow Control Steps
@@ -82,29 +82,29 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: topic_framework_content
 
 2. **load_role_template**
-   - Action: Load business-analyst planning template
-   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/business-analyst.md))
+   - Action: Load product-owner planning template
+   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/product-owner.md))
    - Output: role_template_guidelines
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/session.json)
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from business analysis perspective
-**Role Focus**: Process optimization, requirements analysis, business efficiency
+**Framework Reference**: Address all discussion points in topic-framework.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 business analysis addressing all framework discussion points
+1. **analysis.md**: Comprehensive product ownership analysis addressing all framework discussion points
 2. **Framework Reference**: Include @../topic-framework.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with business analysis expertise
-- Provide process optimization recommendations and requirements specifications
-- Include cost-benefit analysis and change management considerations
+- Address each discussion point from topic-framework.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
 "
 ```
@@ -126,17 +126,17 @@ TodoWrite({
       activeForm: "Loading framework and session context"
     },
     {
-      content: "Execute business-analyst analysis using conceptual-planning-agent with FLOW_CONTROL",
+      content: "Execute product-owner analysis using conceptual-planning-agent with FLOW_CONTROL",
       status: "pending",
-      activeForm: "Executing business-analyst framework analysis"
+      activeForm: "Executing product-owner framework analysis"
     },
     {
       content: "Generate analysis.md addressing all framework discussion points",
       status: "pending",
-      activeForm: "Generating structured business-analyst analysis"
+      activeForm: "Generating structured product-owner analysis"
     },
     {
-      content: "Update session.json with business-analyst completion status",
+      content: "Update workflow-session.json with product-owner completion status",
       status: "pending",
       activeForm: "Updating session metadata"
     }
@@ -148,41 +148,41 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/business-analyst/
+.workflow/WFS-{session}/.brainstorming/product-owner/
 └── analysis.md    # Structured analysis addressing topic-framework.md discussion points
 ```
 
 ### Analysis Document Structure
 ```markdown
-# Business Analyst Analysis: [Topic from Framework]
+# Product Owner Analysis: [Topic from Framework]
 
 ## Framework Reference
 **Topic Framework**: @../topic-framework.md
-**Role Focus**: Business Analysis perspective
+**Role Focus**: Product Backlog & Feature Prioritization perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with business analysis expertise]
+[Address each point from topic-framework.md with product ownership expertise]
 
 ### Core Requirements (from framework)
-[Business analysis perspective on requirements]
+[User story formulation and backlog refinement perspective]
 
 ### Technical Considerations (from framework)
-[Business process and workflow considerations]
+[Technical feasibility and implementation sequencing considerations]
 
 ### User Experience Factors (from framework)
-[Business user experience and stakeholder considerations]
+[User value definition and acceptance criteria analysis]
 
 ### Implementation Challenges (from framework)
-[Change management and process transformation challenges]
+[Sprint planning, dependency management, and delivery strategies]
 
 ### Success Metrics (from framework)
-[Business success metrics and performance indicators]
+[Feature adoption, value delivery metrics, and stakeholder satisfaction indicators]
 
-## Business Analysis Specific Recommendations
-[Role-specific business process recommendations and solutions]
+## Product Owner Specific Recommendations
+[Role-specific backlog management and feature prioritization strategies]
 
 ---
-*Generated by business-analyst analysis addressing structured framework*
+*Generated by product-owner analysis addressing structured framework*
 ```
 
 ## 🔄 **Session Integration**
@@ -190,10 +190,10 @@ TodoWrite({
 ### Completion Status Update
 ```json
 {
-  "business_analyst": {
+  "product_owner": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/business-analyst/analysis.md",
+    "output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
     "framework_reference": "@../topic-framework.md"
   }
 }
@@ -201,5 +201,5 @@ TodoWrite({
 
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
-- **Cross-Role Synthesis**: Business analysis insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **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,31 +1,31 @@
 ---
-name: security-expert
-description: Generate or update security-expert/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:security-expert [topic]
+name: scrum-master
+description: Generate or update scrum-master/analysis.md addressing topic-framework discussion points
+usage: /workflow:brainstorm:scrum-master [topic]
 argument-hint: "optional topic - uses existing framework if available"
 examples:
-  - /workflow:brainstorm:security-expert
-  - /workflow:brainstorm:security-expert "user authentication security review"
-  - /workflow:brainstorm:security-expert "API security architecture"
+  - /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(*)
 ---
 
-## 🔒 **Security Expert Analysis Generator**
+## 🎯 **Scrum Master Analysis Generator**
 
 ### Purpose
-**Specialized command for generating security-expert/analysis.md** that addresses topic-framework.md discussion points from cybersecurity perspective. Creates or updates role-specific analysis with framework references.
+**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.
 
 ### Core Function
 - **Framework-based Analysis**: Address each discussion point in topic-framework.md
-- **Cybersecurity Focus**: Threat modeling, security architecture, and risk management
+- **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
 
 ### Analysis Scope
-- **Threat Modeling**: Attack vectors, threat actors, and vulnerability assessment
-- **Security Architecture**: Controls, defensive measures, and compliance
-- **Risk Management**: Risk assessment, mitigation, and security policies
-- **Implementation Security**: Integration, monitoring, and incident response
+- **Sprint Planning**: Task breakdown, estimation, and iteration planning
+- **Team Collaboration**: Communication patterns, impediment removal, and facilitation
+- **Process Optimization**: Agile ceremonies, retrospectives, and continuous improvement
+- **Delivery Management**: Velocity tracking, burndown analysis, and release planning
 
 ## ⚙️ **Execution Protocol**
 
@@ -68,11 +68,11 @@ ELSE:
 Task(conceptual-planning-agent): "
 [FLOW_CONTROL]
 
-Execute security-expert analysis for existing topic framework
+Execute scrum-master analysis for existing topic framework
 
 ## Context Loading
-ASSIGNED_ROLE: security-expert
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/security-expert/
+ASSIGNED_ROLE: scrum-master
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/scrum-master/
 ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 ## Flow Control Steps
@@ -82,29 +82,29 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: topic_framework_content
 
 2. **load_role_template**
-   - Action: Load security-expert planning template
-   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/security-expert.md))
+   - Action: Load scrum-master planning template
+   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/scrum-master.md))
    - Output: role_template_guidelines
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/session.json)
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from cybersecurity perspective
-**Role Focus**: Threat modeling, security architecture, risk management, compliance
+**Framework Reference**: Address all discussion points in topic-framework.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 security analysis addressing all framework discussion points
+1. **analysis.md**: Comprehensive agile process analysis addressing all framework discussion points
 2. **Framework Reference**: Include @../topic-framework.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with cybersecurity expertise
-- Provide actionable security controls and threat mitigation strategies
-- Include compliance requirements and risk assessment insights
+- Address each discussion point from topic-framework.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
 "
 ```
@@ -126,17 +126,17 @@ TodoWrite({
       activeForm: "Loading framework and session context"
     },
     {
-      content: "Execute security-expert analysis using conceptual-planning-agent with FLOW_CONTROL",
+      content: "Execute scrum-master analysis using conceptual-planning-agent with FLOW_CONTROL",
       status: "pending",
-      activeForm: "Executing security-expert framework analysis"
+      activeForm: "Executing scrum-master framework analysis"
     },
     {
       content: "Generate analysis.md addressing all framework discussion points",
       status: "pending",
-      activeForm: "Generating structured security-expert analysis"
+      activeForm: "Generating structured scrum-master analysis"
     },
     {
-      content: "Update session.json with security-expert completion status",
+      content: "Update workflow-session.json with scrum-master completion status",
       status: "pending",
       activeForm: "Updating session metadata"
     }
@@ -148,41 +148,41 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/security-expert/
+.workflow/WFS-{session}/.brainstorming/scrum-master/
 └── analysis.md    # Structured analysis addressing topic-framework.md discussion points
 ```
 
 ### Analysis Document Structure
 ```markdown
-# Security Expert Analysis: [Topic from Framework]
+# Scrum Master Analysis: [Topic from Framework]
 
 ## Framework Reference
 **Topic Framework**: @../topic-framework.md
-**Role Focus**: Cybersecurity perspective
+**Role Focus**: Agile Process & Team Collaboration perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with cybersecurity expertise]
+[Address each point from topic-framework.md with scrum mastery expertise]
 
 ### Core Requirements (from framework)
-[Security perspective on threat modeling and protection requirements]
+[Sprint planning and iteration breakdown perspective]
 
 ### Technical Considerations (from framework)
-[Security architecture and technical control considerations]
+[Technical debt management and process considerations]
 
 ### User Experience Factors (from framework)
-[Security usability and user protection considerations]
+[User story refinement and acceptance criteria analysis]
 
 ### Implementation Challenges (from framework)
-[Security implementation and compliance considerations]
+[Impediment identification and removal strategies]
 
 ### Success Metrics (from framework)
-[Security success metrics and risk management criteria]
+[Velocity tracking, burndown metrics, and team performance indicators]
 
-## Cybersecurity Specific Recommendations
-[Role-specific security controls and threat mitigation strategies]
+## Scrum Master Specific Recommendations
+[Role-specific agile process optimization and team facilitation strategies]
 
 ---
-*Generated by security-expert analysis addressing structured framework*
+*Generated by scrum-master analysis addressing structured framework*
 ```
 
 ## 🔄 **Session Integration**
@@ -190,10 +190,10 @@ TodoWrite({
 ### Completion Status Update
 ```json
 {
-  "security_expert": {
+  "scrum_master": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/security-expert/analysis.md",
+    "output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
     "framework_reference": "@../topic-framework.md"
   }
 }
@@ -201,5 +201,5 @@ TodoWrite({
 
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
-- **Cross-Role Synthesis**: Security insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **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

@@ -0,0 +1,205 @@
+---
+name: subject-matter-expert
+description: Generate or update subject-matter-expert/analysis.md addressing topic-framework discussion points
+usage: /workflow:brainstorm:subject-matter-expert [topic]
+argument-hint: "optional topic - uses existing framework if available"
+examples:
+  - /workflow:brainstorm:subject-matter-expert
+  - /workflow:brainstorm:subject-matter-expert "user authentication redesign"
+  - /workflow:brainstorm:subject-matter-expert "mobile app performance optimization"
+allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
+---
+
+## 🎯 **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.
+
+### Core Function
+- **Framework-based Analysis**: Address each discussion point in topic-framework.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
+
+### Analysis Scope
+- **Domain Knowledge**: Industry-specific expertise, regulatory requirements, and compliance
+- **Technical Standards**: Best practices, design patterns, and architectural guidelines
+- **Risk Assessment**: Technical debt, scalability concerns, and maintenance implications
+- **Knowledge Transfer**: Documentation strategies, training requirements, and expertise sharing
+
+## ⚙️ **Execution Protocol**
+
+### Phase 1: Session & Framework Detection
+```bash
+# Check active session and framework
+CHECK: .workflow/.active-* marker files
+IF active_session EXISTS:
+    session_id = get_active_session()
+    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+
+    CHECK: brainstorm_dir/topic-framework.md
+    IF EXISTS:
+        framework_mode = true
+        load_framework = true
+    ELSE:
+        IF topic_provided:
+            framework_mode = false  # Create analysis without framework
+        ELSE:
+            ERROR: "No framework found and no topic provided"
+```
+
+### Phase 2: Analysis Mode Detection
+```bash
+# Determine execution mode
+IF framework_mode == true:
+    mode = "framework_based_analysis"
+    topic_ref = load_framework_topic()
+    discussion_points = extract_framework_points()
+ELSE:
+    mode = "standalone_analysis"
+    topic_ref = provided_topic
+    discussion_points = generate_basic_structure()
+```
+
+### Phase 3: Agent Execution with Flow Control
+**Framework-Based Analysis Generation**
+
+```bash
+Task(conceptual-planning-agent): "
+[FLOW_CONTROL]
+
+Execute subject-matter-expert analysis for existing topic framework
+
+## Context Loading
+ASSIGNED_ROLE: subject-matter-expert
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/subject-matter-expert/
+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)
+   - Output: topic_framework_content
+
+2. **load_role_template**
+   - Action: Load subject-matter-expert planning template
+   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/subject-matter-expert.md))
+   - Output: role_template_guidelines
+
+3. **load_session_metadata**
+   - Action: Load session metadata and existing context
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Output: session_context
+
+## Analysis Requirements
+**Framework Reference**: Address all discussion points in topic-framework.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
+
+## Completion Criteria
+- Address each discussion point from topic-framework.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
+"
+```
+
+## 📋 **TodoWrite Integration**
+
+### Workflow Progress Tracking
+```javascript
+TodoWrite({
+  todos: [
+    {
+      content: "Detect active session and locate topic framework",
+      status: "in_progress",
+      activeForm: "Detecting session and framework"
+    },
+    {
+      content: "Load topic-framework.md and session metadata for context",
+      status: "pending",
+      activeForm: "Loading framework and session context"
+    },
+    {
+      content: "Execute subject-matter-expert analysis using conceptual-planning-agent with FLOW_CONTROL",
+      status: "pending",
+      activeForm: "Executing subject-matter-expert framework analysis"
+    },
+    {
+      content: "Generate analysis.md addressing all framework discussion points",
+      status: "pending",
+      activeForm: "Generating structured subject-matter-expert analysis"
+    },
+    {
+      content: "Update workflow-session.json with subject-matter-expert completion status",
+      status: "pending",
+      activeForm: "Updating session metadata"
+    }
+  ]
+});
+```
+
+## 📊 **Output Structure**
+
+### Framework-Based Analysis
+```
+.workflow/WFS-{session}/.brainstorming/subject-matter-expert/
+└── analysis.md    # Structured analysis addressing topic-framework.md discussion points
+```
+
+### Analysis Document Structure
+```markdown
+# Subject Matter Expert Analysis: [Topic from Framework]
+
+## Framework Reference
+**Topic Framework**: @../topic-framework.md
+**Role Focus**: Domain Expertise & Technical Standards perspective
+
+## Discussion Points Analysis
+[Address each point from topic-framework.md with subject matter expertise]
+
+### Core Requirements (from framework)
+[Domain-specific requirements and industry standards perspective]
+
+### Technical Considerations (from framework)
+[Deep technical analysis, architectural patterns, and best practices]
+
+### User Experience Factors (from framework)
+[Domain-specific usability standards and industry conventions]
+
+### Implementation Challenges (from framework)
+[Technical risks, scalability concerns, and maintenance implications]
+
+### Success Metrics (from framework)
+[Domain-specific KPIs, compliance metrics, and quality standards]
+
+## Subject Matter Expert Specific Recommendations
+[Role-specific technical expertise and industry best practices]
+
+---
+*Generated by subject-matter-expert analysis addressing structured framework*
+```
+
+## 🔄 **Session Integration**
+
+### Completion Status Update
+```json
+{
+  "subject_matter_expert": {
+    "status": "completed",
+    "framework_addressed": true,
+    "output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
+    "framework_reference": "@../topic-framework.md"
+  }
+}
+```
+
+### Integration Points
+- **Framework Reference**: @../topic-framework.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,6 +1,6 @@
 ---
 name: synthesis
-description: Generate synthesis-report.md from topic-framework and role analyses with @ references
+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:
@@ -11,25 +11,36 @@ allowed-tools: Read(*), Write(*), TodoWrite(*), Glob(*)
 ## 🧩 **Synthesis Document Generator**
 
 ### Core Function
-**Specialized command for generating synthesis-report.md** that integrates topic-framework.md and all role analysis.md files using @ reference system. Creates comprehensive strategic analysis with cross-role insights.
+**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.
+
+**Dynamic Role Discovery**: Automatically detects which roles participated in brainstorming by scanning for `*/analysis.md` files. Synthesizes only actual participating roles, not predefined lists.
 
 ### Primary Capabilities
-- **Framework Integration**: Reference topic-framework.md discussion points across all roles
-- **Role Analysis Integration**: Consolidate all role/analysis.md files using @ references
-- **Cross-Framework Comparison**: Compare how each role addressed framework discussion points
+- **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+)
 
 ### 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-report.md** → Integrated synthesis with @ references (output)
+3. **synthesis-specification.md** → Complete integrated specification (output)
 
 ## ⚙️ **Execution Protocol**
 
-### ⚠️ Direct Execution Only
-**DO NOT use Task tool or delegate to any agent** - This is a document synthesis task using only Read/Write/Glob tools for aggregating existing analyses.
+### ⚠️ Direct Execution by Main Claude
+**Execution Model**: Main Claude directly executes this command without delegating to sub-agents.
+
+**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
+
+**DO NOT use Task tool** - Main Claude performs intelligent analysis directly while reading/writing files, ensuring no information loss from context passing.
 
 ### Phase 1: Document Discovery & Validation
 ```bash
@@ -51,22 +62,39 @@ IF NOT EXISTS:
 
 ### Phase 2: Role Analysis Discovery
 ```bash
-# Discover available role analyses
+# Dynamically discover available role analyses
 SCAN_DIRECTORY: .workflow/WFS-{session}/.brainstorming/
 FIND_ANALYSES: [
-    */analysis.md files in role directories
+    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": [discovered analysis.md files],
-    "existing_synthesis": synthesis-report.md (if exists)
+    "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-report.md EXISTS:
+IF synthesis-specification.md EXISTS:
     SHOW current synthesis summary to user
     ASK: "Synthesis exists. Do you want to:"
     OPTIONS:
@@ -84,42 +112,60 @@ Initialize synthesis task tracking:
   {"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-report.md with @ references", "status": "pending", "activeForm": "Generating synthesis with references"},
+  {"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"}
 ]
 ```
 
-### Phase 4: Cross-Role Analysis Execution
+### Phase 5: Cross-Role Analysis Execution
 
-#### 4.1 Data Collection and Preprocessing
+**Dynamic Role Processing**: The number and types of roles are determined at runtime based on actual analysis.md files discovered in Phase 2.
+
+#### 5.1 Data Collection and Preprocessing
 ```pseudo
-FOR each role_directory in brainstorming_roles:
-    IF role_directory exists:
-        role_analysis = Read(role_directory + "/analysis.md")
-        role_recommendations = Read(role_directory + "/recommendations.md") IF EXISTS
-        role_insights[role] = extract_key_insights(role_analysis)
-        role_recommendations[role] = extract_recommendations(role_analysis)
-        role_concerns[role] = extract_concerns_risks(role_analysis)
+# Iterate over dynamically discovered role analyses
+FOR each discovered_role IN participating_roles:
+    role_directory = brainstorm_dir + "/" + discovered_role
+
+    # Load role analysis (required)
+    role_analysis = Read(role_directory + "/analysis.md")
+
+    # Load optional artifacts if present
+    IF EXISTS(role_directory + "/recommendations.md"):
+        role_recommendations[discovered_role] = Read(role_directory + "/recommendations.md")
     END IF
+
+    # 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
+
+# Log participating roles for metadata
+participating_role_count = COUNT(participating_roles)
+participating_role_names = participating_roles
 ```
 
-#### 4.2 Cross-Role Insight Analysis
+#### 5.2 Cross-Role Insight Analysis
 ```pseudo
-# Consensus identification
+# Consensus identification (across all participating roles)
 consensus_areas = identify_common_themes(role_insights)
 agreement_matrix = create_agreement_matrix(role_recommendations)
 
-# Disagreement analysis
+# 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
 
 # Innovation opportunity extraction
 innovation_opportunities = extract_breakthrough_ideas(role_insights)
 synergy_opportunities = identify_cross_role_synergies(role_insights)
 ```
 
-#### 4.3 Priority and Decision Matrix Generation
+#### 5.3 Priority and Decision Matrix Generation
 ```pseudo
 # Create comprehensive evaluation matrix
 FOR each recommendation:
@@ -137,16 +183,6 @@ SORT recommendations BY priority_score DESC
 ## 📊 **Output Specification**
 
 ### Output Location
-```
-.workflow/WFS-{topic-slug}/.brainstorming/
-├── topic-framework.md          # Input: Framework structure
-├── [role]/analysis.md          # Input: Role analyses (multiple)
-└── synthesis-report.md         # ★ OUTPUT: Integrated synthesis with @ references
-```
-
-### Streamlined Single-Document Output ⚠️ SIMPLIFIED STRUCTURE
-
-#### Output Document - Single Comprehensive Synthesis
 The synthesis process creates **one consolidated document** that integrates all role perspectives:
 
 ```
@@ -157,34 +193,78 @@ The synthesis process creates **one consolidated document** that integrates all
 ```
 
 #### 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).
+
 ```markdown
 # [Topic] - Integrated Implementation Specification
 
 **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.
 
+## 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*
+
+### User Journey Map
+![User Journey](./assets/user-journey.png)
+*Reference: @ux-expert/analysis.md#user-journey*
+
+### 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 | Source | Priority | Acceptance | Dependencies |
-|----|-------------|--------|----------|------------|--------------|
-| FR-01 | Core feature | @role/analysis.md | High | Criteria | None |
+| 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 | Target | Validation |
-|----|-------------|--------|------------|
-| NFR-01 | Performance | <200ms | Testing |
+| 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 | Value | Success Metric |
-|----|-------------|-------|----------------|
-| BR-01 | User engagement | High | 80% retention |
+| 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, @user-researcher/analysis.md
+**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
@@ -195,13 +275,40 @@ Strategic overview with key insights, breakthrough opportunities, and implementa
 - Data flow and storage strategy
 - Technology stack decisions
 
-### Security Framework
-**Consolidated from**: @security-expert/analysis.md
-- Authentication and authorization patterns
-- Data protection and compliance requirements
-- Security monitoring and audit strategy
+### 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
 
-## Implementation Roadmap
+## 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
@@ -212,10 +319,12 @@ Strategic overview with key insights, breakthrough opportunities, and implementa
 - Testing strategy and quality assurance
 - Deployment and monitoring approach
 
-### Task Breakdown
-- Epic and feature mapping aligned with requirements
-- Sprint planning guidance with dependency management
-- Resource allocation and timeline recommendations
+### 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
@@ -235,6 +344,9 @@ Strategic overview with key insights, breakthrough opportunities, and implementa
 
 ### Streamlined Status Synchronization
 Upon completion, update `workflow-session.json`:
+
+**Dynamic Role Participation**: The `participating_roles` and `roles_synthesized` values are determined at runtime based on actual analysis.md files discovered.
+
 ```json
 {
   "phases": {
@@ -242,22 +354,47 @@ Upon completion, update `workflow-session.json`:
       "status": "completed",
       "synthesis_completed": true,
       "completed_at": "timestamp",
-      "participating_roles": ["product-manager", "system-architect", "ui-designer", "security-expert", "data-architect", ...],
+      "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"
       },
       "synthesis_quality": {
         "role_integration": "complete",
         "requirement_coverage": "comprehensive",
+        "decision_transparency": "alternatives_documented",
+        "process_risks_identified": true,
         "implementation_readiness": "ready"
       },
       "content_metrics": {
-        "roles_synthesized": 9,
-        "functional_requirements": 25,
-        "non_functional_requirements": 12,
-        "business_requirements": 8,
-        "implementation_phases": 3,
-        "risk_factors_identified": 8
+        "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>"
+      }
+    }
+  }
+}
+```
+
+**Example with actual values**:
+```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
       }
     }
   }
@@ -268,28 +405,96 @@ Upon completion, update `workflow-session.json`:
 
 ### Required Synthesis Elements
 - [ ] Integration of all available role analyses with comprehensive coverage
-- [ ] Clear identification of consensus areas and disagreement points
+- [ ] **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
 
 ### 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 and next steps
-- [ ] **Balance**: Considers all role perspectives and addresses concerns
+- [ ] **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
 
 ### Output Validation Criteria
 - [ ] **Priority-Based**: Recommendations prioritized using multi-dimensional evaluation
-- [ ] **Resource-Aware**: Implementation plans consider resource and time constraints
-- [ ] **Risk-Managed**: Comprehensive risk assessment with mitigation strategies
+- [ ] **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
 
 ### Integration Excellence Standards
-- [ ] **Cross-Role Synthesis**: Successfully identifies and resolves role perspective conflicts
+- [ ] **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 are detailed enough for immediate execution
+- [ ] **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
-- [ ] **Continuous Improvement**: Establishes framework for ongoing optimization and learning
+- [ ] **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/ui-designer.md

@@ -88,7 +88,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/session.json)
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -136,7 +136,7 @@ TodoWrite({
       activeForm: "Generating structured ui-designer analysis"
     },
     {
-      content: "Update session.json with ui-designer completion status",
+      content: "Update workflow-session.json with ui-designer completion status",
       status: "pending",
       activeForm: "Updating session metadata"
     }

.claude/commands/workflow/brainstorm/user-researcher.md

@@ -1,267 +0,0 @@
----
-name: user-researcher
-description: User researcher perspective brainstorming for user behavior analysis and research insights
-usage: /workflow:brainstorm:user-researcher <topic>
-argument-hint: "topic or challenge to analyze from user research perspective"
-examples:
-  - /workflow:brainstorm:user-researcher "user onboarding experience"
-  - /workflow:brainstorm:user-researcher "mobile app usability issues"
-  - /workflow:brainstorm:user-researcher "feature adoption analysis"
-allowed-tools: Task(conceptual-planning-agent), TodoWrite(*)
----
-
-## 🔍 **Role Overview: User Researcher**
-
-### Role Definition
-User experience research specialist responsible for understanding user behavior, identifying needs and pain points, and transforming research insights into actionable product improvements that enhance user satisfaction and engagement.
-
-### Core Responsibilities
-- **User Behavior Research**: Deep analysis of user behavior patterns and motivations
-- **User Needs Discovery**: Research to discover unmet user needs and requirements
-- **Usability Assessment**: Evaluate product usability and user experience issues
-- **User Insights Generation**: Transform research findings into actionable product insights
-
-### Focus Areas
-- **User Behavior**: Usage patterns, decision paths, task completion methods
-- **User Needs**: Explicit needs, implicit needs, emotional requirements
-- **User Experience**: Pain points, satisfaction levels, emotional responses, expectations
-- **Market Segmentation**: User personas, demographic segments, usage scenarios
-
-### Success Metrics
-- User satisfaction and engagement scores
-- Task success rates and completion times
-- Quality and actionability of research insights
-- Impact of research on product decisions
-
-## 🧠 **分析框架**
-
-@~/.claude/workflows/brainstorming-principles.md
-
-### Key Analysis Questions
-
-**1. User Understanding and Insights**
-- What are the real needs and pain points of target users?
-- What are the user behavior patterns and usage scenarios?
-- What are the differentiated needs of various user groups?
-
-**2. User Experience Analysis**
-- What are the main issues with the current user experience?
-- What obstacles and friction points exist in user task completion?
-- What gaps exist between user satisfaction and expectations?
-
-**3. Research Methods and Validation**
-- Which research methods are most suitable for the current problem?
-- How can hypotheses and design decisions be validated?
-- How can continuous user feedback be collected?
-
-**4. Insights Translation and Application**
-- How can research findings be translated into product improvements?
-- How can product decisions and design be influenced?
-- How can a user-centered culture be established?
-
-## ⚡ **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
-**User Researcher Perspective Questioning**
-
-Before agent assignment, gather comprehensive user researcher context:
-
-#### 📋 Role-Specific Questions
-
-**1. User Behavior Patterns and Insights**
-- Who are the primary users and what are their key characteristics?
-- What user behaviors, patterns, or pain points have you observed?
-- Are there specific user segments or personas you're particularly interested in?
-- What user feedback or data do you already have available?
-
-**2. Research Focus and Pain Points**
-- What specific user experience problems or questions need to be addressed?
-- Are there particular user tasks, workflows, or touchpoints to focus on?
-- What assumptions about users need to be validated or challenged?
-- What gaps exist in your current understanding of user needs?
-
-**3. Research Context and Constraints**
-- What research has been done previously and what were the key findings?
-- Are there specific research methods you prefer or want to avoid?
-- What timeline and resources are available for user research?
-- Who are the key stakeholders that need to understand user insights?
-
-**4. User Testing Strategy and Goals**
-- What specific user experience improvements are you hoping to achieve?
-- How do you currently measure user satisfaction or success?
-- Are there competitive products or experiences you want to benchmark against?
-- What would successful user research outcomes look like for this project?
-
-#### Context Validation
-- **Minimum Response**: Each answer must be ≥50 characters
-- **Re-prompting**: Insufficient detail triggers follow-up questions
-- **Context Storage**: Save responses to `.brainstorming/user-researcher-context.md`
-
-### Step 2: Agent Assignment with Flow Control
-**Dedicated Agent Execution**
-
-```bash
-Task(conceptual-planning-agent): "
-[FLOW_CONTROL]
-
-Execute dedicated user researcher conceptual analysis for: {topic}
-
-ASSIGNED_ROLE: user-researcher
-OUTPUT_LOCATION: .brainstorming/user-researcher/
-USER_CONTEXT: {validated_responses_from_context_gathering}
-
-Flow Control Steps:
-[
-  {
-    \"step\": \"load_role_template\",
-    \"action\": \"Load user-researcher planning template\",
-    \"command\": \"bash($(cat ~/.claude/workflows/cli-templates/planning-roles/user-researcher.md))\",
-    \"output_to\": \"role_template\"
-  }
-]
-
-Conceptual Analysis Requirements:
-- Apply user researcher perspective to topic analysis
-- Focus on user behavior patterns, pain points, research insights, and user testing strategy
-- 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 user researcher analysis
-- recommendations.md: User researcher recommendations
-- deliverables/: User researcher-specific outputs as defined in role template
-
-Embody user researcher role expertise for comprehensive conceptual planning."
-```
-
-### Progress Tracking
-TodoWrite tracking for two-step process:
-```json
-[
-  {"content": "Gather user researcher context through role-specific questioning", "status": "in_progress", "activeForm": "Gathering context"},
-  {"content": "Validate context responses and save to user-researcher-context.md", "status": "pending", "activeForm": "Validating context"},
-  {"content": "Load user-researcher planning template via flow control", "status": "pending", "activeForm": "Loading template"},
-  {"content": "Execute dedicated conceptual-planning-agent for user-researcher role", "status": "pending", "activeForm": "Executing agent"}
-]
-```
-
-## 📊 **输出结构**
-
-### 保存位置
-```
-.workflow/WFS-{topic-slug}/.brainstorming/user-researcher/
-├── analysis.md                     # 主要用户研究分析
-├── user-personas.md                # 详细用户画像和细分
-├── research-plan.md                # 方法论和研究方法
-└── insights-recommendations.md     # 关键发现和可执行建议
-```
-
-### 文档模板
-
-#### analysis.md 结构
-```markdown
-# User Researcher Analysis: {Topic}
-*Generated: {timestamp}*
-
-## Executive Summary
-[核心用户研究发现和建议概述]
-
-## Current User Landscape
-### User Base Overview
-### Behavioral Patterns
-### Usage Statistics and Trends
-### Satisfaction Metrics
-
-## User Needs Analysis
-### Primary User Needs
-### Unmet Needs and Gaps
-### Need Prioritization Matrix
-### Emotional and Functional Needs
-
-## User Experience Assessment
-### Current UX Strengths
-### Major Pain Points and Friction
-### Usability Issues Identified
-### Accessibility Gaps
-
-## User Behavior Insights
-### User Journey Mapping
-### Decision-Making Patterns
-### Task Completion Analysis
-### Behavioral Segments
-
-## Research Recommendations
-### Recommended Research Methods
-### Key Research Questions
-### Success Metrics and KPIs
-### Research Timeline and Resources
-
-## Actionable Insights
-### Immediate UX Improvements
-### Product Feature Recommendations
-### Long-term User Strategy
-### Success Measurement Plan
-```
-
-## 🔄 **会话集成**
-
-### 状态同步
-分析完成后，更新 `workflow-session.json`:
-```json
-{
-  "phases": {
-    "BRAINSTORM": {
-      "user_researcher": {
-        "status": "completed",
-        "completed_at": "timestamp",
-        "output_directory": ".workflow/WFS-{topic}/.brainstorming/user-researcher/",
-        "key_insights": ["user_behavior_pattern", "unmet_need", "usability_issue"]
-      }
-    }
-  }
-}
-```
-
-### 与其他角色的协作
-用户研究员视角为其他角色提供：
-- **用户需求和洞察** → Product Manager
-- **用户行为数据** → Data Architect
-- **用户体验要求** → UI Designer
-- **用户安全需求** → Security Expert
-- **功能使用场景** → Feature Planner
-
-## ✅ **质量标准**
-
-### 必须包含的研究元素
-- [ ] 详细的用户行为分析
-- [ ] 明确的用户需求识别
-- [ ] 全面的用户体验评估
-- [ ] 科学的研究方法设计
-- [ ] 可执行的改进建议
-
-### 用户研究原则检查
-- [ ] 以人为本：所有分析以用户为中心
-- [ ] 基于证据：结论有数据和研究支撑
-- [ ] 行为导向：关注实际行为而非声明意图
-- [ ] 情境考虑：分析使用场景和环境因素
-- [ ] 持续迭代：建立持续研究和改进机制
-
-### 洞察质量评估
-- [ ] 洞察的新颖性和深度
-- [ ] 建议的可操作性和具体性
-- [ ] 影响评估的准确性
-- [ ] 研究方法的科学性
-- [ ] 用户代表性的覆盖度

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

@@ -1,31 +1,31 @@
 ---
-name: feature-planner
-description: Generate or update feature-planner/analysis.md addressing topic-framework discussion points
-usage: /workflow:brainstorm:feature-planner [topic]
+name: ux-expert
+description: Generate or update ux-expert/analysis.md addressing topic-framework discussion points
+usage: /workflow:brainstorm:ux-expert [topic]
 argument-hint: "optional topic - uses existing framework if available"
 examples:
-  - /workflow:brainstorm:feature-planner
-  - /workflow:brainstorm:feature-planner "user dashboard enhancement"
-  - /workflow:brainstorm:feature-planner "mobile app feature roadmap"
+  - /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(*)
 ---
 
-## 🔧 **Feature Planner Analysis Generator**
+## 🎯 **UX Expert Analysis Generator**
 
 ### Purpose
-**Specialized command for generating feature-planner/analysis.md** that addresses topic-framework.md discussion points from feature development perspective. Creates or updates role-specific analysis with framework references.
+**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.
 
 ### Core Function
 - **Framework-based Analysis**: Address each discussion point in topic-framework.md
-- **Feature Development Focus**: Feature specification, development planning, and delivery management
+- **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
-- **Feature Specification**: Transform requirements into detailed specifications
-- **Development Planning**: Sprint planning, milestones, and dependency management
-- **Quality Assurance**: Testing strategies and acceptance criteria
-- **Delivery Management**: Release planning and implementation timelines
+- **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
 
 ## ⚙️ **Execution Protocol**
 
@@ -68,11 +68,11 @@ ELSE:
 Task(conceptual-planning-agent): "
 [FLOW_CONTROL]
 
-Execute feature-planner analysis for existing topic framework
+Execute ux-expert analysis for existing topic framework
 
 ## Context Loading
-ASSIGNED_ROLE: feature-planner
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/feature-planner/
+ASSIGNED_ROLE: ux-expert
+OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ux-expert/
 ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 ## Flow Control Steps
@@ -82,29 +82,29 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
    - Output: topic_framework_content
 
 2. **load_role_template**
-   - Action: Load feature-planner planning template
-   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/feature-planner.md))
+   - Action: Load ux-expert planning template
+   - Command: bash($(cat ~/.claude/workflows/cli-templates/planning-roles/ux-expert.md))
    - Output: role_template_guidelines
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/session.json)
+   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
-**Framework Reference**: Address all discussion points in topic-framework.md from feature development perspective
-**Role Focus**: Feature specification, development planning, quality assurance, delivery management
+**Framework Reference**: Address all discussion points in topic-framework.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 feature planning analysis addressing all framework discussion points
+1. **analysis.md**: Comprehensive UX design analysis addressing all framework discussion points
 2. **Framework Reference**: Include @../topic-framework.md reference in analysis
 
 ## Completion Criteria
-- Address each discussion point from topic-framework.md with feature development expertise
-- Provide actionable development plans and implementation strategies
-- Include quality assurance and testing considerations
+- Address each discussion point from topic-framework.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
 "
 ```
@@ -126,17 +126,17 @@ TodoWrite({
       activeForm: "Loading framework and session context"
     },
     {
-      content: "Execute feature-planner analysis using conceptual-planning-agent with FLOW_CONTROL",
+      content: "Execute ux-expert analysis using conceptual-planning-agent with FLOW_CONTROL",
       status: "pending",
-      activeForm: "Executing feature-planner framework analysis"
+      activeForm: "Executing ux-expert framework analysis"
     },
     {
       content: "Generate analysis.md addressing all framework discussion points",
       status: "pending",
-      activeForm: "Generating structured feature-planner analysis"
+      activeForm: "Generating structured ux-expert analysis"
     },
     {
-      content: "Update session.json with feature-planner completion status",
+      content: "Update workflow-session.json with ux-expert completion status",
       status: "pending",
       activeForm: "Updating session metadata"
     }
@@ -148,41 +148,41 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/feature-planner/
+.workflow/WFS-{session}/.brainstorming/ux-expert/
 └── analysis.md    # Structured analysis addressing topic-framework.md discussion points
 ```
 
 ### Analysis Document Structure
 ```markdown
-# Feature Planner Analysis: [Topic from Framework]
+# UX Expert Analysis: [Topic from Framework]
 
 ## Framework Reference
 **Topic Framework**: @../topic-framework.md
-**Role Focus**: Feature Development perspective
+**Role Focus**: User Experience & Interface Design perspective
 
 ## Discussion Points Analysis
-[Address each point from topic-framework.md with feature development expertise]
+[Address each point from topic-framework.md with UX design expertise]
 
 ### Core Requirements (from framework)
-[Feature development perspective on requirements]
+[User interface and interaction design requirements perspective]
 
 ### Technical Considerations (from framework)
-[Feature architecture and development considerations]
+[Design system implementation and technical feasibility considerations]
 
 ### User Experience Factors (from framework)
-[Feature usability and user story considerations]
+[Usability optimization, accessibility, and user-centered design analysis]
 
 ### Implementation Challenges (from framework)
-[Development complexity and delivery considerations]
+[Design implementation challenges and progressive enhancement strategies]
 
 ### Success Metrics (from framework)
-[Feature success metrics and acceptance criteria]
+[UX metrics including usability testing, user satisfaction, and design KPIs]
 
-## Feature Development Specific Recommendations
-[Role-specific feature planning recommendations and strategies]
+## UX Expert Specific Recommendations
+[Role-specific interface design patterns and usability optimization strategies]
 
 ---
-*Generated by feature-planner analysis addressing structured framework*
+*Generated by ux-expert analysis addressing structured framework*
 ```
 
 ## 🔄 **Session Integration**
@@ -190,10 +190,10 @@ TodoWrite({
 ### Completion Status Update
 ```json
 {
-  "feature_planner": {
+  "ux_expert": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/feature-planner/analysis.md",
+    "output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
     "framework_reference": "@../topic-framework.md"
   }
 }
@@ -201,5 +201,5 @@ TodoWrite({
 
 ### Integration Points
 - **Framework Reference**: @../topic-framework.md for structured discussion points
-- **Cross-Role Synthesis**: Feature development insights available for synthesis-report.md integration
-- **Agent Autonomy**: Independent execution with framework guidance
+- **Cross-Role Synthesis**: UX design insights available for synthesis-report.md integration
+- **Agent Autonomy**: Independent execution with framework guidance

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

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

.claude/commands/workflow/execute.md

@@ -185,9 +185,9 @@ TodoWrite({
       activeForm: "Executing IMPL-1.2: Implement auth logic"
     },
     {
-      content: "Execute IMPL-2: Review implementations [code-review-agent]",
+      content: "Execute TEST-FIX-1: Validate implementation tests [test-fix-agent]",
       status: "pending",
-      activeForm: "Executing IMPL-2: Review implementations"
+      activeForm: "Executing TEST-FIX-1: Validate implementation tests"
     }
   ]
 });
@@ -356,8 +356,8 @@ Task(subagent_type="{meta.agent}",
 
      **WORKFLOW COMPLETION CHECK**:
      After updating task status, check if workflow is complete:
-     total_tasks=\$(ls .workflow/*/\.task/*.json | wc -l)
-     completed_tasks=\$(ls .workflow/*/\.summaries/*.md 2>/dev/null | wc -l)
+     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"),
@@ -384,8 +384,8 @@ Task(subagent_type="{meta.agent}",
   "title": "Task title",
   "status": "pending|active|completed|blocked",
   "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@planning-agent|@code-review-test-agent"
+    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
+    "agent": "@code-developer|@test-fix-agent|@general-purpose"
   },
   "context": {
     "requirements": ["req1", "req2"],
@@ -433,7 +433,7 @@ Task(subagent_type="{meta.agent}",
       "task_description": "Implement following consolidated synthesis specification...",
       "modification_points": ["Apply synthesis specification requirements..."]
     },
-    "target_files": ["file:function:lines"]
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
 ```
@@ -451,8 +451,9 @@ Task(subagent_type="{meta.agent}",
 meta.agent specified → Use specified agent
 meta.agent missing → Infer from meta.type:
   - "feature" → @code-developer
-  - "test" → @code-review-test-agent
-  - "review" → @code-review-agent
+  - "test-gen" → @code-developer
+  - "test-fix" → @test-fix-agent
+  - "review" → @general-purpose
   - "docs" → @doc-generator
 ```
 

.claude/commands/workflow/plan.md

@@ -15,13 +15,23 @@ 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.
+**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**.
 
-**Execution Flow**:
-1. Initialize TodoWrite → Execute Phase 1 → Parse output → Update TodoWrite
-2. Execute Phase 2 with Phase 1 data → Parse output → Update TodoWrite
-3. Execute Phase 3 with Phase 2 data → Parse output → Update TodoWrite
-4. Execute Phase 4 with Phase 3 validation → Update TodoWrite → Return summary
+**Execution Model - Auto-Continue Workflow**:
+
+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
+
+**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
+- Progress updates shown at each phase for visibility
 
 **Execution Modes**:
 - **Manual Mode** (default): Use `/workflow:tools:task-generate`
@@ -32,9 +42,8 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 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
-4. **Sequential Execution**: Each phase depends on previous phase's output
-5. **Complete All Phases**: Do not return to user until Phase 4 completes
-6. **Track Progress**: Update TodoWrite after every phase completion
+4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
+5. **Track Progress**: Update TodoWrite after every phase completion
 
 ## 4-Phase Execution
 
@@ -64,6 +73,8 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **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
@@ -83,6 +94,8 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **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: Intelligent Analysis
@@ -99,9 +112,18 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
+**After Phase 3**: Return to user showing Phase 3 results, then auto-continue to Phase 4
+
 ---
 
 ### 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
+- **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
+- Task generation translates high-level specifications into concrete, actionable work items
+
 **Command**:
 - Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
 - Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
@@ -121,7 +143,12 @@ Planning complete for session: [sessionId]
 Tasks generated: [count]
 Plan: .workflow/[sessionId]/IMPL_PLAN.md
 
-Next: /workflow:execute or /workflow:status
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
+2. /workflow:status  # Review task breakdown
+3. /workflow:execute  # Start implementation (after verification)
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
@@ -227,23 +254,23 @@ Return summary to user
 
 - **Parsing Failure**: If output parsing fails, retry command once, then report error
 - **Validation Failure**: If validation fails, report which file/data is missing
-- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed
+- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed to next phase
 
 ## Coordinator Checklist
 
 ✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
 ✅ Initialize TodoWrite before any command
 ✅ Execute Phase 1 immediately with structured description
-✅ Parse session ID from Phase 1 output
+✅ 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
+✅ 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
 ✅ Pass session ID to Phase 4 command
 ✅ Verify all Phase 4 outputs
 ✅ Update TodoWrite after each phase
-✅ Return summary only after Phase 4 completes
+✅ After each phase, automatically continue to next phase based on TodoList status
 
 ## Structure Template Reference
 

.claude/commands/workflow/review.md

@@ -1,85 +1,272 @@
 ---
 name: review
-description: Execute review phase for quality validation
-usage: /workflow:review
-argument-hint: none
+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
+  - /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
 ---
 
-# Workflow Review Command (/workflow:review)
+### 🚀 Command Overview: `/workflow:review`
 
-## Overview
-Final phase for quality validation, testing, and completion.
+**Optional specialized review** for completed implementations. In the standard workflow, **passing tests = approved code**. Use this command only when specialized review is required (security, architecture, compliance, docs).
 
-## Core Principles
-**Session Management:** @~/.claude/workflows/workflow-architecture.md
+## Philosophy: "Tests Are the Review"
 
-## Review Process
+- ✅ **Default**: All tests pass → Code approved
+- 🔍 **Optional**: Specialized reviews for:
+  - 🔒 Security audits (vulnerabilities, auth/authz)
+  - 🏗️ Architecture compliance (patterns, technical debt)
+  - 📋 Action items verification (requirements met, acceptance criteria)
 
-1. **Validation Checks**
-   - All tasks completed
-   - Tests passing
-   - Code quality metrics
-   - Documentation complete
+## Review Types
 
-2. **Generate Review Report**
+| Type | Focus | Use Case |
+|------|-------|----------|
+| `quality` | Code quality, best practices, maintainability | Default general review |
+| `security` | Security vulnerabilities, data handling, access control | Security audits |
+| `architecture` | Architectural patterns, technical debt, design decisions | Architecture compliance |
+| `action-items` | Requirements met, acceptance criteria verified, action items completed | Pre-deployment verification |
+
+**Notes**:
+- For documentation generation, use `/workflow:tools:docs`
+- For CLAUDE.md updates, use `/update-memory-related`
+
+## Execution Template
+
+```bash
+#!/bin/bash
+# Optional specialized review for completed implementation
+
+# Step 1: Session ID resolution
+if [ -n "$SESSION_ARG" ]; then
+    sessionId="$SESSION_ARG"
+else
+    sessionId=$(find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//')
+fi
+
+# Step 2: Validation
+if [ ! -d ".workflow/${sessionId}" ]; then
+    echo "❌ Session ${sessionId} not found"
+    exit 1
+fi
+
+# Check for completed tasks
+if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
+    echo "❌ No completed implementation found. Complete implementation first"
+    exit 1
+fi
+
+# Step 3: Determine review type (default: quality)
+review_type="${TYPE_ARG:-quality}"
+
+# Redirect docs review to specialized command
+if [ "$review_type" = "docs" ]; then
+    echo "💡 For documentation generation, please use:"
+    echo "   /workflow:tools:docs"
+    echo ""
+    echo "The docs command provides:"
+    echo "  - Hierarchical architecture documentation"
+    echo "  - API documentation generation"
+    echo "  - Documentation structure analysis"
+    exit 0
+fi
+
+# Step 4: Analysis handover → Model takes control
+# BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
+```
+
+### 🧠 Model Analysis Phase
+
+After bash validation, the model takes control to:
+
+1. **Load Context**: Read completed task summaries and changed files
+   ```bash
+   # Load implementation summaries
+   cat .workflow/${sessionId}/.summaries/IMPL-*.md
+
+   # Load test results (if available)
+   cat .workflow/${sessionId}/.summaries/TEST-FIX-*.md 2>/dev/null
+
+   # Get changed files
+   git log --since="$(cat .workflow/${sessionId}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
+   ```
+
+2. **Perform Specialized Review**: Based on `review_type`
+
+   **Security Review** (`--type=security`):
+   - Use MCP code search 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}")
+     ```
+   - Use Gemini for security analysis:
+     ```bash
+     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     PURPOSE: Security audit of completed implementation
+     TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
+     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
+     ```
+
+   **Architecture Review** (`--type=architecture`):
+   - Use Qwen for architecture analysis:
+     ```bash
+     cd .workflow/${sessionId} && ~/.claude/scripts/qwen-wrapper -p "
+     PURPOSE: Architecture compliance review
+     TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
+     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     EXPECTED: Architecture assessment with recommendations
+     RULES: Check for patterns, separation of concerns, modularity, scalability
+     " --approval-mode yolo
+     ```
+
+   **Quality Review** (`--type=quality`):
+   - Use Gemini for code quality:
+     ```bash
+     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -p "
+     PURPOSE: Code quality and best practices review
+     TASK: Assess code readability, maintainability, adherence to best practices
+     CONTEXT: @{.summaries/IMPL-*.md,../..,../../CLAUDE.md}
+     EXPECTED: Quality assessment with improvement suggestions
+     RULES: Check for code smells, duplication, complexity, naming conventions
+     " --approval-mode yolo
+     ```
+
+   **Action Items Review** (`--type=action-items`):
+   - Verify all requirements and acceptance criteria met:
+     ```bash
+     # Load task requirements and acceptance criteria
+     find .workflow/${sessionId}/.task -name "IMPL-*.json" -exec jq -r '
+       "Task: " + .id + "\n" +
+       "Requirements: " + (.context.requirements | join(", ")) + "\n" +
+       "Acceptance: " + (.context.acceptance | join(", "))
+     ' {} \;
+
+     # Check implementation summaries against requirements
+     cd .workflow/${sessionId} && ~/.claude/scripts/gemini-wrapper -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}
+     EXPECTED:
+     - Requirements coverage matrix
+     - Acceptance criteria verification
+     - Missing/incomplete action items
+     - Pre-deployment readiness assessment
+     RULES:
+     - Check each requirement has corresponding implementation
+     - Verify all acceptance criteria are met
+     - Flag any incomplete or missing action items
+     - Assess deployment readiness
+     " --approval-mode yolo
+     ```
+
+
+3. **Generate Review Report**: Create structured report
    ```markdown
-   # Review Report
-   
-   ## Task Completion
-   - Total: 10
-   - Completed: 10
-   - Success Rate: 100%
-   
-   ## Quality Metrics
-   - Test Coverage: 85%
-   - Code Quality: A
-   - Documentation: Complete
-   
-   ## Issues Found
-   - Minor: 2
-   - Major: 0
-   - Critical: 0
+   # Review Report: ${review_type}
+
+   **Session**: ${sessionId}
+   **Date**: $(date)
+   **Type**: ${review_type}
+
+   ## Summary
+   - Tasks Reviewed: [count IMPL tasks]
+   - Files Changed: [count files]
+   - Severity: [High/Medium/Low]
+
+   ## Findings
+
+   ### Critical Issues
+   - [Issue 1 with file:line reference]
+   - [Issue 2 with file:line reference]
+
+   ### Recommendations
+   - [Recommendation 1]
+   - [Recommendation 2]
+
+   ### Positive Observations
+   - [Good pattern observed]
+
+   ## Action Items
+   - [ ] [Action 1]
+   - [ ] [Action 2]
    ```
 
-3. **Update Session**
-   ```json
-   {
-     "current_phase": "REVIEW",
-     "phases": {
-       "REVIEW": {
-         "status": "completed",
-         "output": "REVIEW.md",
-         "test_results": {
-           "passed": 45,
-           "failed": 0,
-           "coverage": 85
-         }
-       }
-     }
-   }
+4. **Output Files**:
+   ```bash
+   # Save review report
+   Write(.workflow/${sessionId}/REVIEW-${review_type}.md)
+
+   # Update session metadata
+   # (optional) Update workflow-session.json with review status
    ```
 
-## Auto-fix (Default)
-Auto-fix is enabled by default:
-- Automatically fixes minor issues
-- Runs formatters and linters
-- Updates documentation
-- Re-runs tests
+5. **Optional: Update Memory** (if docs review or significant findings):
+   ```bash
+   # If architecture or quality issues found, suggest memory update
+   if [ "$review_type" = "architecture" ] || [ "$review_type" = "quality" ]; then
+       echo "💡 Consider updating project documentation:"
+       echo "   /update-memory-related"
+   fi
+   ```
 
-## Completion Criteria
-- All tasks marked complete
-- Tests passing (configurable threshold)
-- No critical issues
-- Documentation updated
+## Usage Examples
 
-## Output Files
-- `REVIEW.md` - Review report
-- `workflow-session.json` - Updated with results
-- `test-results.json` - Detailed test output
+```bash
+# General quality review after implementation
+/workflow:review
+
+# Security audit before deployment
+/workflow:review --type=security
+
+# Architecture review for specific session
+/workflow:review --type=architecture WFS-payment-integration
+
+# Documentation review
+/workflow:review --type=docs
+```
+
+## ✨ Features
+
+- **Simple Validation**: Check session exists and has completed tasks
+- **No Complex Orchestration**: Direct analysis, no multi-phase pipeline
+- **Specialized Reviews**: Different prompts and tools for different review types
+- **MCP Integration**: Fast code search for security and architecture patterns
+- **CLI Tool Integration**: Gemini for analysis, Qwen for architecture
+- **Structured Output**: Markdown reports with severity levels and action items
+- **Optional Memory Update**: Suggests documentation updates for significant findings
+
+## Integration with Workflow
+
+```
+Standard Workflow:
+  plan → execute → test-gen → execute ✅
+
+Optional Review (when needed):
+  plan → execute → test-gen → execute → review (security/architecture/docs)
+```
+
+**When to Use**:
+- Before production deployment (security review + action-items review)
+- After major feature (architecture review)
+- Before code freeze (quality review)
+- Pre-deployment verification (action-items review)
+
+**When NOT to Use**:
+- Regular development (tests are sufficient)
+- Simple bug fixes (test-fix-agent handles it)
+- Minor changes (update-memory-related is enough)
 
 ## Related Commands
-- `/workflow:execute` - Must complete first
-- `/task:status` - Check task completion
-- `/workflow:status` - View overall status
+
+- `/workflow:execute` - Must complete implementation first
+- `/workflow:test-gen` - Primary quality gate (tests)
+- `/workflow:tools:docs` - Generate hierarchical documentation (use instead of `--type=docs`)
+- `/update-memory-related` - Update CLAUDE.md docs after architecture findings
+- `/workflow:status` - Check session status

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

@@ -44,8 +44,8 @@ mv temp.json .workflow/WFS-session/workflow-session.json
 
 ### Step 5: Count Final Statistics
 ```bash
-ls .workflow/WFS-session/.task/*.json 2>/dev/null | wc -l
-ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
+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
@@ -56,12 +56,12 @@ rm .workflow/.active-WFS-session-name
 ## Simple Bash Commands
 
 ### Basic Operations
-- **Find active session**: `ls .workflow/.active-*`
+- **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**: `ls .task/*.json | wc -l`
-- **Count completed**: `ls .summaries/*.md | wc -l`
+- **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
@@ -92,11 +92,11 @@ Session Completion Summary:
 ### Error Handling
 ```bash
 # No active session
-ls .workflow/.active-* 2>/dev/null || echo "No active session found"
+find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
 
 # Incomplete tasks
-task_count=$(ls .task/*.json | wc -l)
-summary_count=$(ls .summaries/*.md 2>/dev/null | wc -l)
+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"
 ```
 

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

@@ -35,8 +35,8 @@ jq -r '.session_id, .status, .project' .workflow/WFS-session/workflow-session.js
 
 ### Step 4: Count Task Progress
 ```bash
-ls .workflow/WFS-session/.task/*.json 2>/dev/null | wc -l
-ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
+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 5: Get Creation Time
@@ -47,11 +47,11 @@ jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
 ## Simple Bash Commands
 
 ### Basic Operations
-- **List sessions**: `ls .workflow/WFS-*`
-- **Find active**: `ls .workflow/.active-*`
+- **List sessions**: `find .workflow/ -maxdepth 1 -type d -name "WFS-*"`
+- **Find active**: `find .workflow/ -name ".active-*" -type f`
 - **Read session data**: `jq -r '.session_id, .status' session.json`
-- **Count tasks**: `ls .task/*.json | wc -l`
-- **Count completed**: `ls .summaries/*.md | wc -l`
+- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
+- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
 - **Get timestamp**: `jq -r '.created_at' session.json`
 
 ## Simple Output Format

.claude/commands/workflow/status.md

@@ -25,7 +25,7 @@ Generates on-demand views from JSON task data. No synchronization needed - all v
 
 ### Step 1: Find Active Session
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
+find .workflow/ -name ".active-*" -type f 2>/dev/null | head -1
 ```
 
 ### Step 2: Load Session Data
@@ -35,7 +35,7 @@ cat .workflow/WFS-session/workflow-session.json
 
 ### Step 3: Scan Task Files
 ```bash
-ls .workflow/WFS-session/.task/*.json 2>/dev/null
+find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
 ```
 
 ### Step 4: Generate Task Status
@@ -45,8 +45,8 @@ cat .workflow/WFS-session/.task/impl-1.json | jq -r '.status'
 
 ### Step 5: Count Task Progress
 ```bash
-ls .workflow/WFS-session/.task/*.json | wc -l
-ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
+find .workflow/WFS-session/.task/ -name "*.json" -type f | wc -l
+find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ### Step 6: Display Overview
@@ -66,11 +66,11 @@ ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
 ## Simple Bash Commands
 
 ### Basic Operations
-- **Find active session**: `ls .workflow/.active-*`
+- **Find active session**: `find .workflow/ -name ".active-*" -type f`
 - **Read session info**: `cat .workflow/session/workflow-session.json`
-- **List tasks**: `ls .workflow/session/.task/*.json`
+- **List tasks**: `find .workflow/session/.task/ -name "*.json" -type f`
 - **Check task status**: `cat task.json | jq -r '.status'`
-- **Count completed**: `ls .summaries/*.md | wc -l`
+- **Count completed**: `find .summaries/ -name "*.md" -type f | wc -l`
 
 ### Task Status Check
 - **pending**: Not started yet
@@ -87,8 +87,8 @@ test -f .workflow/.active-* && echo "Session active"
 for f in .workflow/session/.task/*.json; do jq empty "$f" && echo "Valid: $f"; done
 
 # Check summaries match
-ls .task/*.json | wc -l
-ls .summaries/*.md | wc -l
+find .task/ -name "*.json" -type f | wc -l
+find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ## Simple Output Format

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

@@ -0,0 +1,275 @@
+---
+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
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
+---
+
+# TDD Workflow Plan Command (/workflow:tdd-plan)
+
+## Coordinator Role
+
+**This command is a pure orchestrator**: Execute 5 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation.
+
+**Execution Modes**:
+- **Manual Mode** (default): Use `/workflow:tools:task-generate-tdd`
+- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-tdd --agent`
+
+## Core Rules
+
+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)
+6. **TDD Context**: All descriptions include "TDD:" prefix
+7. **Quality Gate**: Phase 5 concept verification ensures clarity before task generation
+
+## 7-Phase Execution (with Concept Verification)
+
+### Phase 1: Session Discovery
+**Command**: `/workflow:session:start --auto "TDD: [structured-description]"`
+
+**TDD Structured Format**:
+```
+TDD: [Feature Name]
+GOAL: [Objective]
+SCOPE: [Included/excluded]
+CONTEXT: [Background]
+TEST_FOCUS: [Test scenarios]
+```
+
+**Parse**: Extract sessionId
+
+### Phase 2: Context Gathering
+**Command**: `/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"`
+
+**Parse**: Extract contextPath
+
+### Phase 3: Test Coverage Analysis
+**Command**: `/workflow:tools:test-context-gather --session [sessionId]`
+
+**Purpose**: Analyze existing codebase for:
+- Existing test patterns and conventions
+- Current test coverage
+- Related components and integration points
+- Test framework detection
+
+**Parse**: Extract testContextPath (`.workflow/[sessionId]/.process/test-context-package.json`)
+
+**Benefits**:
+- Makes TDD aware of existing environment
+- Identifies reusable test patterns
+- Prevents duplicate test creation
+- Enables integration with existing tests
+
+### Phase 4: TDD Analysis
+**Command**: `/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]`
+
+**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
+
+**Parse**: Verify ANALYSIS_RESULTS.md contains TDD breakdown sections
+
+### Phase 5: Concept Verification (NEW QUALITY GATE)
+**Command**: `/workflow:concept-verify --session [sessionId]`
+
+**Purpose**: Verify conceptual clarity before TDD task generation
+- Clarify test requirements and acceptance criteria
+- Resolve ambiguities in expected behavior
+- Validate TDD approach is appropriate
+
+**Behavior**:
+- If no ambiguities found → Auto-proceed to Phase 6
+- If ambiguities exist → Interactive clarification (up to 5 questions)
+- After clarifications → Auto-proceed to Phase 6
+
+**Parse**: Verify concept verification completed (check for clarifications section in ANALYSIS_RESULTS.md or synthesis file if exists)
+
+### Phase 6: TDD Task Generation
+**Command**:
+- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
+- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
+
+**Parse**: Extract feature count, chain count, task count
+
+**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 contains workflow_type: "tdd" in frontmatter
+
+### Phase 7: 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
+
+**Return Summary**:
+```
+TDD Planning complete for session: [sessionId]
+
+Features analyzed: [N]
+TDD chains generated: [N]
+Total tasks: [3N]
+
+Structure:
+- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
+[...]
+
+Plan:
+- Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
+  (includes TDD Task Chains section with workflow_type: "tdd")
+
+✅ Recommended Next Steps:
+1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality
+2. /workflow:execute --session [sessionId]  # Start TDD execution
+3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
+
+⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task dependencies
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize (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"}
+]
+
+// Update after each phase: mark current "completed", next "in_progress"
+```
+
+## Input Processing
+
+Convert user input to TDD-structured format:
+
+**Simple text** → Add TDD context
+**Detailed text** → Extract components with TEST_FOCUS
+**File/Issue** → Read and structure with TDD
+
+## Error Handling
+
+- **Parsing failure**: Retry once, then report
+- **Validation failure**: Report missing/invalid data
+- **Command failure**: Keep phase in_progress, report error
+- **TDD validation failure**: Report incomplete chains or wrong dependencies
+
+## Related Commands
+- `/workflow:plan` - Standard (non-TDD) planning
+- `/workflow:execute` - Execute TDD tasks
+- `/workflow:tdd-verify` - Verify TDD compliance
+- `/workflow:status` - View progress
+## TDD Workflow Enhancements
+
+### Overview
+The TDD workflow has been significantly enhanced by integrating best practices from both traditional `plan --agent` and `test-gen` workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.
+
+### Key Improvements
+
+#### 1. Test Coverage Analysis (Phase 3)
+**Adopted from test-gen workflow**
+
+Before planning TDD tasks, the workflow now analyzes the existing codebase:
+- Detects existing test patterns and conventions
+- Identifies current test coverage
+- Discovers related components and integration points
+- Detects test framework automatically
+
+**Benefits**:
+- Context-aware TDD planning
+- Avoids duplicate test creation
+- Enables integration with existing tests
+- No longer assumes greenfield scenarios
+
+#### 2. Iterative Green Phase with Test-Fix Cycle
+**Adopted from test-gen workflow**
+
+IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:
+
+**Enhanced IMPL Task Flow**:
+```
+1. Write minimal implementation code
+2. Execute test suite
+3. IF tests pass → Complete task ✅
+4. IF tests fail → Enter fix cycle:
+   a. Gemini diagnoses with bug-fix template
+   b. Apply fix (manual or Codex)
+   c. Retest
+   d. Repeat (max 3 iterations)
+5. IF max iterations → Auto-revert changes 🔄
+```
+
+**Benefits**:
+- ✅ Faster feedback within Green phase
+- ✅ Autonomous recovery from implementation errors
+- ✅ Systematic debugging with Gemini
+- ✅ Safe rollback prevents broken state
+
+#### 3. Agent-Driven Planning
+**From plan --agent workflow**
+
+Supports action-planning-agent for more autonomous TDD planning with:
+- MCP tool integration (code-index, exa)
+- Memory-first principles
+- Brainstorming artifact integration
+- Task merging over decomposition
+
+### Workflow Comparison
+
+| Aspect | Previous | Current |
+|--------|----------|---------|
+| **Phases** | 5 | 6 (test coverage analysis) |
+| **Context** | Greenfield assumption | Existing codebase aware |
+| **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 |
+
+### Migration Notes
+
+**Backward Compatibility**: ✅ Fully compatible
+- Existing TDD workflows continue to work
+- New features are additive, not breaking
+- Phase 3 can be skipped if test-context-gather not available
+
+**Session Structure**:
+```
+.workflow/WFS-xxx/
+├── IMPL_PLAN.md (unified plan with TDD Task Chains section)
+├── TODO_LIST.md
+├── .process/
+│   ├── context-package.json
+│   ├── test-context-package.json
+│   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
+│   └── green-fix-iteration-*.md (fix logs)
+└── .task/
+    ├── TEST-*.json (Red phase)
+    ├── IMPL-*.json (Green phase with test-fix-cycle)
+    └── REFACTOR-*.json (Refactor phase)
+```
+
+**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

@@ -0,0 +1,361 @@
+---
+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:*)
+---
+
+# TDD Verification Command (/workflow:tdd-verify)
+
+## Coordinator Role
+
+**This command is a pure orchestrator**: Execute 4 phases to verify TDD workflow compliance, test coverage, and Red-Green-Refactor cycle execution.
+
+## Core Responsibilities
+- Verify TDD task chain structure
+- Analyze test coverage
+- Validate TDD cycle execution
+- Generate compliance report
+
+## 4-Phase Execution
+
+### Phase 1: Session Discovery
+**Auto-detect or use provided session**
+
+```bash
+# If session-id provided
+sessionId = argument
+
+# Else auto-detect active session
+find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
+```
+
+**Extract**: sessionId
+
+**Validation**: Session directory exists
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Task Chain Validation
+**Validate TDD structure using bash commands**
+
+```bash
+# Load all task JSONs
+find .workflow/{sessionId}/.task/ -name '*.json'
+
+# Extract task IDs
+find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.id' {} \;
+
+# Check dependencies
+find .workflow/{sessionId}/.task/ -name 'IMPL-*.json' -exec jq -r '.context.depends_on[]?' {} \;
+find .workflow/{sessionId}/.task/ -name 'REFACTOR-*.json' -exec jq -r '.context.depends_on[]?' {} \;
+
+# Check meta fields
+find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;
+find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
+```
+
+**Validation**:
+- For each feature N, verify TEST-N.M → IMPL-N.M → REFACTOR-N.M exists
+- IMPL-N.M.context.depends_on includes TEST-N.M
+- REFACTOR-N.M.context.depends_on includes IMPL-N.M
+- TEST tasks have tdd_phase="red" and agent="@code-review-test-agent"
+- IMPL/REFACTOR tasks have tdd_phase="green"/"refactor" and agent="@code-developer"
+
+**Extract**: Chain validation report
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Test Execution Analysis
+**Command**: `SlashCommand(command="/workflow:tools:tdd-coverage-analysis --session [sessionId]")`
+
+**Input**: sessionId from Phase 1
+
+**Parse Output**:
+- Coverage metrics (line, branch, function percentages)
+- TDD cycle verification results
+- Compliance score
+
+**Validation**:
+- `.workflow/{sessionId}/.process/test-results.json` exists
+- `.workflow/{sessionId}/.process/coverage-report.json` exists
+- `.workflow/{sessionId}/.process/tdd-cycle-report.md` exists
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+---
+
+### Phase 4: Compliance Report Generation
+**Gemini analysis for comprehensive TDD compliance report**
+
+```bash
+cd project-root && ~/.claude/scripts/gemini-wrapper -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}
+EXPECTED:
+- TDD compliance score (0-100)
+- Chain completeness verification
+- Test coverage analysis summary
+- Quality recommendations
+- Red-Green-Refactor cycle validation
+- Best practices adherence assessment
+RULES: Focus on TDD best practices and workflow adherence. Be specific about violations and improvements.
+" > .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
+```
+
+**Output**: TDD_COMPLIANCE_REPORT.md
+
+**TodoWrite**: Mark phase 4 completed
+
+**Return to User**:
+```
+TDD Verification Report - Session: {sessionId}
+
+## Chain Validation
+✅ Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
+✅ Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
+⚠️  Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
+
+## Test Execution
+✅ All TEST tasks produced failing tests
+✅ All IMPL tasks made tests pass
+✅ All REFACTOR tasks maintained green tests
+
+## Coverage Metrics
+Line Coverage: {percentage}%
+Branch Coverage: {percentage}%
+Function Coverage: {percentage}%
+
+## Compliance Score: {score}/100
+
+Detailed report: .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
+
+Recommendations:
+- Complete missing REFACTOR-3.1 task
+- Consider additional edge case tests for Feature 2
+- Improve test failure message clarity in Feature 1
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize (before Phase 1)
+TodoWrite({todos: [
+  {"content": "Identify target session", "status": "in_progress", "activeForm": "Identifying target session"},
+  {"content": "Validate task chain structure", "status": "pending", "activeForm": "Validating task chain structure"},
+  {"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
+  {"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
+]})
+
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Identify target session", "status": "completed", "activeForm": "Identifying target session"},
+  {"content": "Validate task chain structure", "status": "in_progress", "activeForm": "Validating task chain structure"},
+  {"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
+  {"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
+]})
+
+// Continue pattern for Phase 2, 3, 4...
+```
+
+## Validation Logic
+
+### Chain Validation Algorithm
+```
+1. Load all task JSONs from .workflow/{sessionId}/.task/
+2. Extract task IDs and group by feature number
+3. For each feature:
+   - Check TEST-N.M exists
+   - Check IMPL-N.M exists
+   - Check REFACTOR-N.M exists (optional but recommended)
+   - Verify IMPL-N.M depends_on TEST-N.M
+   - Verify REFACTOR-N.M depends_on IMPL-N.M
+   - Verify meta.tdd_phase values
+   - Verify meta.agent assignments
+4. Calculate chain completeness score
+5. Report incomplete or invalid chains
+```
+
+### Compliance Scoring
+```
+Base Score: 100 points
+
+Deductions:
+- Missing TEST task: -30 points per feature
+- Missing IMPL task: -30 points per feature
+- Missing REFACTOR task: -10 points per feature
+- Wrong dependency: -15 points per error
+- Wrong agent: -5 points per error
+- Wrong tdd_phase: -5 points per error
+- Test didn't fail initially: -10 points per feature
+- Tests didn't pass after IMPL: -20 points per feature
+- Tests broke during REFACTOR: -15 points per feature
+
+Final Score: Max(0, Base Score - Deductions)
+```
+
+## Output Files
+```
+.workflow/{session-id}/
+├── TDD_COMPLIANCE_REPORT.md     # Comprehensive compliance report ⭐
+└── .process/
+    ├── test-results.json         # From tdd-coverage-analysis
+    ├── coverage-report.json      # From tdd-coverage-analysis
+    └── tdd-cycle-report.md       # From tdd-coverage-analysis
+```
+
+## Error Handling
+
+### Session Discovery Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No active session | No .active-* file | Provide session-id explicitly |
+| Multiple active sessions | Multiple .active-* files | Provide session-id explicitly |
+| Session not found | Invalid session-id | Check available sessions |
+
+### Validation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Task files missing | Incomplete planning | Run tdd-plan first |
+| Invalid JSON | Corrupted task files | Regenerate tasks |
+| Missing summaries | Tasks not executed | Execute tasks before verify |
+
+### Analysis Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Coverage tool missing | No test framework | Configure testing first |
+| Tests fail to run | Code errors | Fix errors before verify |
+| Gemini analysis fails | Token limit / API error | Retry or reduce context |
+
+## Integration & Usage
+
+### Command Chain
+- **Called After**: `/workflow:execute` (when TDD tasks completed)
+- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini wrapper
+- **Related**: `/workflow:tdd-plan`, `/workflow:status`
+
+### Basic Usage
+```bash
+# Auto-detect active session
+/workflow:tdd-verify
+
+# Specify session
+/workflow:tdd-verify WFS-auth
+```
+
+### When to Use
+- After completing all TDD tasks in a workflow
+- Before merging TDD workflow branch
+- For TDD process quality assessment
+- To identify missing TDD steps
+
+## TDD Compliance Report Structure
+
+```markdown
+# TDD Compliance Report - {Session ID}
+
+**Generated**: {timestamp}
+**Session**: {sessionId}
+**Workflow Type**: TDD
+
+## Executive Summary
+Overall Compliance Score: {score}/100
+Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
+
+## Chain Analysis
+
+### Feature 1: {Feature Name}
+**Status**: ✅ Complete
+**Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
+
+- ✅ **Red Phase**: Test created and failed with clear message
+- ✅ **Green Phase**: Minimal implementation made test pass
+- ✅ **Refactor Phase**: Code improved, tests remained green
+
+### Feature 2: {Feature Name}
+**Status**: ⚠️ Incomplete
+**Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1)
+
+- ✅ **Red Phase**: Test created and failed
+- ⚠️ **Green Phase**: Implementation seems over-engineered
+- ❌ **Refactor Phase**: Missing
+
+**Issues**:
+- REFACTOR-2.1 task not completed
+- IMPL-2.1 implementation exceeded minimal scope
+
+[Repeat for all features]
+
+## Test Coverage Analysis
+
+### Coverage Metrics
+- Line Coverage: {percentage}% {status}
+- Branch Coverage: {percentage}% {status}
+- Function Coverage: {percentage}% {status}
+
+### Coverage Gaps
+- {file}:{lines} - Uncovered error handling
+- {file}:{lines} - Uncovered edge case
+
+## TDD Cycle Validation
+
+### Red Phase (Write Failing Test)
+- ✅ {N}/{total} features had failing tests initially
+- ⚠️ Feature 3: No evidence of initial test failure
+
+### Green Phase (Make Test Pass)
+- ✅ {N}/{total} implementations made tests pass
+- ✅ All implementations minimal and focused
+
+### Refactor Phase (Improve Quality)
+- ⚠️ {N}/{total} features completed refactoring
+- ❌ Feature 2, 4: Refactoring step skipped
+
+## Best Practices Assessment
+
+### Strengths
+- Clear test descriptions
+- Good test coverage
+- Consistent naming conventions
+- Well-structured code
+
+### Areas for Improvement
+- Some implementations over-engineered in Green phase
+- Missing refactoring steps
+- Test failure messages could be more descriptive
+
+## Recommendations
+
+### High Priority
+1. Complete missing REFACTOR tasks (Features 2, 4)
+2. Verify initial test failures for Feature 3
+3. Simplify over-engineered implementations
+
+### Medium Priority
+1. Add edge case tests for Features 1, 3
+2. Improve test failure message clarity
+3. Increase branch coverage to >85%
+
+### Low Priority
+1. Add more descriptive test names
+2. Consider parameterized tests for similar scenarios
+3. Document TDD process learnings
+
+## Conclusion
+{Summary of compliance status and next steps}
+```
+
+## Related Commands
+- `/workflow:tdd-plan` - Creates TDD workflow
+- `/workflow:execute` - Executes TDD tasks
+- `/workflow:tools:tdd-coverage-analysis` - Analyzes test coverage
+- `/workflow:status` - Views workflow progress

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

@@ -1,145 +1,304 @@
 ---
 name: test-gen
-description: Generate comprehensive test workflow based on completed implementation tasks
-usage: /workflow:test-gen [session-id]
-argument-hint: "WFS-session-id"
+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
   - /workflow:test-gen WFS-user-auth
+  - /workflow:test-gen --use-codex WFS-api-refactor
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
-# Workflow Test Generation Command
+# Workflow Test Generation Command (/workflow:test-gen)
 
-## Overview
-Analyzes completed implementation sessions and generates comprehensive test requirements, then calls workflow:plan to create test workflow.
+## Coordinator Role
 
-## Usage
-```bash
-/workflow:test-gen                # Auto-detect active session
-/workflow:test-gen WFS-session-id # Analyze specific session
+**This command is a pure orchestrator**: Creates an independent test-fix workflow session for validating a completed implementation. It reuses the standard planning toolchain with automatic cross-session context gathering.
+
+**Core Principles**:
+- **Session Isolation**: Creates new `WFS-test-[source]` session to keep verification separate from implementation
+- **Context-First**: Prioritizes gathering code changes and summaries from source session
+- **Format Reuse**: Creates standard `IMPL-*.json` task, using `meta.type: "test-fix"` for agent assignment
+- **Parameter Simplification**: Tools auto-detect test session type via metadata, no manual cross-session parameters needed
+- **Manual First**: Default to manual fixes, use `--use-codex` flag for automated Codex fix application
+
+**Execution Flow**:
+1. Initialize TodoWrite → Create test session → Parse session ID
+2. Gather cross-session context (automatic) → Parse context path
+3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
+4. Generate test task from analysis → Return summary
+
+## 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)
+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)
+
+## 5-Phase Execution
+
+### Phase 1: Create Test Session
+**Command**: `SlashCommand(command="/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
+
+**Input**: `sourceSessionId` from user argument (e.g., `WFS-user-auth`)
+
+**Expected Behavior**:
+- Creates new session with pattern `WFS-test-[source-slug]` (e.g., `WFS-test-user-auth`)
+- Writes metadata to `workflow-session.json`:
+  - `workflow_type: "test_session"`
+  - `source_session_id: "[sourceSessionId]"`
+- Returns new session ID for subsequent phases
+
+**Parse Output**:
+- Extract: new test session ID (store as `testSessionId`)
+- Pattern: `WFS-test-[slug]`
+
+**Validation**:
+- Source session `.workflow/[sourceSessionId]/` exists
+- Source session has completed IMPL tasks (`.summaries/IMPL-*-summary.md`)
+- New test session directory created
+- Metadata includes `workflow_type` and `source_session_id`
+
+**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Gather Test Context
+**Command**: `SlashCommand(command="/workflow:tools:test-context-gather --session [testSessionId]")`
+
+**Input**: `testSessionId` from Phase 1 (e.g., `WFS-test-user-auth`)
+
+**Expected Behavior**:
+- Load source session implementation context and summaries
+- Analyze test coverage using MCP tools (find existing tests)
+- Identify files requiring tests (coverage gaps)
+- Detect test framework and conventions
+- Generate `test-context-package.json`
+
+**Parse Output**:
+- Extract: test context package path (store as `testContextPath`)
+- Pattern: `.workflow/[testSessionId]/.process/test-context-package.json`
+
+**Validation**:
+- Test context package created
+- Contains source session summaries
+- Includes coverage gap analysis
+- Test framework detected
+- Test conventions documented
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Test Generation Analysis
+**Command**: `SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessionId] --context [testContextPath]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `testContextPath` from Phase 2
+
+**Expected Behavior**:
+- Use Gemini to analyze coverage gaps and implementation context
+- Study existing test patterns and conventions
+- Generate test requirements for each missing test file
+- Design test generation strategy
+- Generate `TEST_ANALYSIS_RESULTS.md`
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
+- Contains test requirements and generation strategy
+- Lists test files to create with specifications
+
+**Validation**:
+- TEST_ANALYSIS_RESULTS.md exists with complete sections:
+  - Coverage Assessment
+  - Test Framework & Conventions
+  - Test Requirements by File
+  - Test Generation Strategy
+  - Implementation Targets (test files to create)
+  - Success Criteria
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+---
+
+### Phase 4: Generate Test Tasks
+**Command**: `SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] --session [testSessionId]")`
+
+**Input**:
+- `testSessionId` from Phase 1
+- `--use-codex` flag (if present in original command)
+
+**Expected Behavior**:
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
+- Extract test requirements and generation strategy
+- Generate **TWO task JSON files**:
+  - **IMPL-001.json**: Test Generation task (calls @code-developer)
+  - **IMPL-002.json**: Test Execution and Fix Cycle task (calls @test-fix-agent)
+- Generate IMPL_PLAN.md with test generation and execution strategy
+- Generate TODO_LIST.md with both tasks
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists (test generation)
+- Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists (test execution & fix)
+- Verify `.workflow/[testSessionId]/IMPL_PLAN.md` created
+- Verify `.workflow/[testSessionId]/TODO_LIST.md` created
+
+**Validation - IMPL-001.json (Test Generation)**:
+- Task ID: `IMPL-001`
+- `meta.type: "test-gen"`
+- `meta.agent: "@code-developer"`
+- `context.requirements`: Generate tests based on TEST_ANALYSIS_RESULTS.md
+- `flow_control.pre_analysis`: Load TEST_ANALYSIS_RESULTS.md and test context
+- `flow_control.implementation_approach`: Test generation steps
+- `flow_control.target_files`: Test files to create from analysis section 5
+
+**Validation - IMPL-002.json (Test Execution & Fix)**:
+- 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
+- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
+  - **Cycle pattern**: test → gemini_diagnose → manual_fix (or codex if --use-codex) → retest
+  - **Tools configuration**: Gemini for analysis with bug-fix template, manual or Codex for fixes
+  - **Exit conditions**: Success (all pass) or failure (max iterations)
+- `flow_control.implementation_approach.modification_points`: 3-phase execution flow
+  - Phase 1: Initial test execution
+  - Phase 2: Iterative Gemini diagnosis + manual/Codex fixes (based on flag)
+  - Phase 3: Final validation and certification
+
+**TodoWrite**: Mark phase 4 completed, phase 5 in_progress
+
+---
+
+### Phase 5: Return Summary to User
+
+**Return to User**:
+```
+Independent test-fix workflow created successfully!
+
+Source Session: [sourceSessionId]
+Test Session: [testSessionId]
+
+Tasks Created:
+- IMPL-001: Test Generation (@code-developer)
+- IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
+
+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
 ```
 
-## Dynamic Session ID Resolution
+**TodoWrite**: Mark phase 5 completed
 
-The `${SESSION_ID}` variable is dynamically resolved based on:
+---
 
-1. **Command argument**: If session-id provided as argument, use it directly
-2. **Auto-detection**: If no argument, detect from active session markers
-3. **Format**: Always in format `WFS-session-name`
+## TodoWrite Pattern
 
-```bash
-# Example resolution logic:
-# If argument provided: SESSION_ID = "WFS-user-auth"
-# If no argument: SESSION_ID = $(find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//')
+Track progress through 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"}
+]})
 ```
 
-## Implementation Flow
+Update status to `in_progress` when starting each phase, mark `completed` when done.
 
-### Step 1: Identify Target Session
-```bash
-# Auto-detect active session (if no session-id provided)
-find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
+## Data Flow
 
-# Use provided session-id or detected session-id
-# SESSION_ID = provided argument OR detected active session
+```
+/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)
 ```
 
-### Step 2: Get Session Start Time
-```bash
-cat .workflow/WFS-${SESSION_ID}/workflow-session.json | jq -r .created_at
-```
+## Session Metadata
 
-### Step 3: Git Change Analysis (using session start time)
-```bash
-git log --since="$(cat .workflow/WFS-${SESSION_ID}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u | grep -v '^$'
-```
+Test session includes `workflow_type: "test_session"` and `source_session_id` for automatic context gathering.
 
-### Step 4: Filter Code Files
-```bash
-git log --since="$(cat .workflow/WFS-${SESSION_ID}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u | grep -E '\.(js|ts|jsx|tsx|py|java|go|rs)$'
-```
+## Task Output
 
-### Step 5: Load Session Context
-```bash
-cat .workflow/WFS-${SESSION_ID}/.summaries/IMPL-*-summary.md 2>/dev/null
-```
+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)
 
-### Step 6: Extract Focus Paths
-```bash
-find .workflow/WFS-${SESSION_ID}/.task/ -name '*.json' -exec jq -r '.context.focus_paths[]?' {} \;
-```
+See `/workflow:tools:test-task-generate` for complete task JSON schemas.
 
-### Step 7: Gemini Analysis and Planning Document Generation
-```bash
-cd project-root && ~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Analyze implementation and generate comprehensive test planning document
-TASK: Review changed files and implementation context to create detailed test planning document
-CONTEXT: Changed files: [changed_files], Implementation summaries: [impl_summaries], Focus paths: [focus_paths]
-EXPECTED: Complete test planning document including:
-- Test strategy analysis
-- Critical test scenarios identification
-- Edge cases and error conditions
-- Test priority matrix
-- Resource requirements
-- Implementation approach recommendations
-- Specific test cases with acceptance criteria
-RULES: Generate structured markdown document suitable for workflow planning. Focus on actionable test requirements based on actual implementation changes.
-" > .workflow/WFS-${SESSION_ID}/.process/GEMINI_TEST_PLAN.md
-```
+## Error Handling
 
-### Step 8: Generate Combined Test Requirements Document
-```bash
-mkdir -p .workflow/WFS-${SESSION_ID}/.process
-```
+| Phase | Error | Action |
+|-------|-------|--------|
+| 1 | Source session not found | Return error with source session ID |
+| 1 | No completed IMPL tasks | Return error, source incomplete |
+| 2 | Context gathering failed | Return error, check source artifacts |
+| 3 | Analysis failed | Return error, check context package |
+| 4 | Task generation failed | Retry once, then error with details |
 
-```bash
-cat > .workflow/WFS-${SESSION_ID}/.process/TEST_REQUIREMENTS.md << 'EOF'
-# Test Requirements Summary for WFS-${SESSION_ID}
+## Output Files
 
-## Analysis Data Sources
-- Git change analysis results
-- Implementation summaries and context
-- Gemini-generated test planning document
+Created in `.workflow/WFS-test-[session]/`:
+- `workflow-session.json` - Session metadata
+- `.process/test-context-package.json` - Coverage analysis
+- `.process/TEST_ANALYSIS_RESULTS.md` - Test requirements
+- `.task/IMPL-001.json` - Test generation task
+- `.task/IMPL-002.json` - Test execution & fix task
+- `IMPL_PLAN.md` - Test plan
+- `TODO_LIST.md` - Task checklist
 
-## Reference Documents
-- Detailed test plan: GEMINI_TEST_PLAN.md
-- Implementation context: IMPL-*-summary.md files
+## Agent Execution
 
-## Integration Note
-This document combines analysis data with Gemini-generated planning document for comprehensive test workflow generation.
-EOF
-```
+**IMPL-001** (@code-developer):
+- Generates test files based on TEST_ANALYSIS_RESULTS.md
+- Follows existing test patterns and conventions
 
-### Step 9: Call Workflow Plan with Gemini Planning Document
-```bash
-/workflow:plan .workflow/WFS-${SESSION_ID}/.process/GEMINI_TEST_PLAN.md
-```
+**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
 
-## Simple Bash Commands
+See `/workflow:tools:test-task-generate` for detailed specifications.
 
-### Basic Operations
-- **Find active session**: `find .workflow/ -name '.active-*'`
-- **Get git changes**: `git log --since='date' --name-only`
-- **Filter code files**: `grep -E '\.(js|ts|py)$'`
-- **Load summaries**: `cat .workflow/WFS-*/summaries/*.md`
-- **Extract JSON data**: `jq -r '.context.focus_paths[]'`
-- **Create directory**: `mkdir -p .workflow/session/.process`
-- **Write file**: `cat > file << 'EOF'`
+## Best Practices
 
-### Gemini CLI Integration
-- **Planning command**: `~/.claude/scripts/gemini-wrapper -p "prompt" > GEMINI_TEST_PLAN.md`
-- **Context loading**: Include changed files and implementation context
-- **Document generation**: Creates comprehensive test planning document
-- **Direct handoff**: Pass Gemini planning document to workflow:plan
-
-## No Complex Logic
-- No variables or functions
-- No conditional statements
-- No loops or complex pipes
-- Direct bash commands only
-- Gemini CLI for intelligent analysis
+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-*`
 
 ## Related Commands
-- `/workflow:plan` - Called to generate test workflow
-- `/workflow:execute` - Executes generated test tasks
-- `/workflow:status` - Shows test workflow progress
+
+- `/workflow:tools:test-context-gather` - Phase 2 (coverage analysis)
+- `/workflow:tools:test-concept-enhanced` - Phase 3 (Gemini test analysis)
+- `/workflow:tools:test-task-generate` - Phase 4 (task generation)
+- `/workflow:execute` - Execute workflow
+- `/workflow:status` - Check progress

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

@@ -130,6 +130,15 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
      - 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
@@ -141,6 +150,9 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
      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**
@@ -172,6 +184,8 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
      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**
@@ -301,6 +315,39 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 - **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}

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

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

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

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

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

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

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

@@ -0,0 +1,723 @@
+---
+name: task-generate-tdd
+description: Generate TDD task chains with Red-Green-Refactor dependencies
+usage: /workflow:tools:task-generate-tdd --session <session_id> [--agent]
+argument-hint: "--session WFS-session-id [--agent]"
+examples:
+  - /workflow:tools:task-generate-tdd --session WFS-auth
+  - /workflow:tools:task-generate-tdd --session WFS-auth --agent
+allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*), TodoWrite(*)
+---
+
+# TDD Task Generation Command
+
+## Overview
+Generate TDD-specific task chains from analysis results with enforced Red-Green-Refactor structure and dependencies.
+
+## Core Philosophy
+- **TDD-First**: Every feature starts with a failing test
+- **Chain-Enforced**: Dependencies ensure proper TDD cycle
+- **Phase-Explicit**: Each task marked with Red/Green/Refactor phase
+- **Artifact-Aware**: Integrates brainstorming outputs
+- **Memory-First**: Reuse loaded documents from memory
+- **Context-Aware**: Analyzes existing codebase and test patterns
+- **Iterative Green Phase**: Auto-diagnose and fix test failures with Gemini + optional Codex
+- **Safety-First**: Auto-revert on max iterations to prevent broken state
+
+## Core Responsibilities
+- Parse analysis results and identify testable features
+- Generate Red-Green-Refactor task chains for each feature
+- Enforce proper dependencies (TEST → IMPL → REFACTOR)
+- Create TDD_PLAN.md and enhanced IMPL_PLAN.md
+- Generate TODO_LIST.md with TDD phase indicators
+- Update session state for TDD execution
+
+## Execution Lifecycle
+
+### Phase 1: Input Validation & Discovery
+**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+
+1. **Session Validation**
+   - If session metadata in memory → Skip loading
+   - Else: Load `.workflow/{session_id}/workflow-session.json`
+
+2. **Analysis Results Loading**
+   - If ANALYSIS_RESULTS.md in memory → Skip loading
+   - Else: Read `.workflow/{session_id}/.process/ANALYSIS_RESULTS.md`
+
+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
+
+### Phase 2: TDD Task JSON Generation
+
+**Input**: Use `.process/ANALYSIS_RESULTS.md` directly (enhanced with TDD structure from concept-enhanced phase)
+
+**Note**: The ANALYSIS_RESULTS.md now includes TDD-specific breakdown:
+- Feature list with testable requirements
+- Test cases for Red phase
+- Implementation requirements for Green phase
+- Refactoring opportunities
+- Task dependencies and execution order
+
+### Phase 3: Enhanced IMPL_PLAN.md Generation
+
+#### Task Chain Structure
+For each feature, generate 3 tasks with ID format:
+- **TEST-N.M** (Red phase)
+- **IMPL-N.M** (Green phase)
+- **REFACTOR-N.M** (Refactor phase)
+
+#### Chain Dependency Rules
+- **IMPL depends_on TEST**: Cannot implement before test exists
+- **REFACTOR depends_on IMPL**: Cannot refactor before implementation
+- **Cross-feature dependencies**: If Feature 2 needs Feature 1, then `IMPL-2.1 depends_on ["REFACTOR-1.1"]`
+
+#### Agent Assignment
+- **TEST tasks** → `@code-review-test-agent`
+- **IMPL tasks** → `@code-developer`
+- **REFACTOR tasks** → `@code-developer`
+
+#### Meta Fields
+- `meta.type`: "test" | "feature" | "refactor"
+- `meta.agent`: Agent for task execution
+- `meta.tdd_phase`: "red" | "green" | "refactor"
+
+#### Task JSON Examples
+
+**RED Phase - Test Task (TEST-1.1.json)**
+```json
+{
+  "id": "TEST-1.1",
+  "title": "Write failing test for user authentication",
+  "status": "pending",
+  "meta": {
+    "type": "test",
+    "agent": "@code-review-test-agent",
+    "tdd_phase": "red"
+  },
+  "context": {
+    "requirements": [
+      "Write test case for login with valid credentials",
+      "Test should fail with 'AuthService not implemented' error",
+      "Include tests for invalid credentials and edge cases"
+    ],
+    "focus_paths": ["tests/auth/login.test.ts"],
+    "acceptance": [
+      "Test file created with at least 3 test cases",
+      "Test runs and fails with clear error message",
+      "Test assertions define expected behavior"
+    ],
+    "depends_on": []
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "check_test_framework",
+        "action": "Verify test framework is configured",
+        "command": "bash(npm list jest || npm list vitest)",
+        "output_to": "test_framework_info",
+        "on_error": "warn"
+      }
+    ]
+  }
+}
+```
+
+**GREEN Phase - Implementation Task (IMPL-1.1.json)**
+```json
+{
+  "id": "IMPL-1.1",
+  "title": "Implement user authentication to pass tests",
+  "status": "pending",
+  "meta": {
+    "type": "feature",
+    "agent": "@code-developer",
+    "tdd_phase": "green",
+    "max_iterations": 3,
+    "use_codex": false
+  },
+  "context": {
+    "requirements": [
+      "Implement minimal AuthService to pass TEST-1.1",
+      "Handle valid and invalid credentials",
+      "Return appropriate success/error responses",
+      "If tests fail after implementation, diagnose and fix iteratively"
+    ],
+    "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
+    "acceptance": [
+      "All tests in TEST-1.1 pass",
+      "Implementation is minimal and focused",
+      "No over-engineering or premature optimization",
+      "Test failures resolved within iteration limit"
+    ],
+    "depends_on": ["TEST-1.1"]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_test_requirements",
+        "action": "Read test specifications from TEST phase",
+        "command": "bash(cat .workflow/WFS-xxx/.summaries/TEST-1.1-summary.md)",
+        "output_to": "test_requirements",
+        "on_error": "fail"
+      },
+      {
+        "step": "verify_tests_failing",
+        "action": "Confirm tests are currently failing (Red phase validation)",
+        "command": "bash(npm test -- tests/auth/login.test.ts || echo 'Tests failing as expected')",
+        "output_to": "initial_test_status",
+        "on_error": "warn"
+      },
+      {
+        "step": "load_test_context",
+        "action": "Load test patterns and framework info",
+        "command": "bash(cat .workflow/WFS-xxx/.process/test-context-package.json 2>/dev/null || echo '{}')",
+        "output_to": "test_context",
+        "on_error": "skip_optional"
+      }
+    ],
+    "implementation_approach": {
+      "task_description": "Write minimal code to pass tests, then enter iterative fix cycle if they still fail",
+      "initial_implementation": [
+        "Write minimal code based on test requirements",
+        "Execute test suite: bash(npm test -- tests/auth/login.test.ts)",
+        "If tests pass → Complete task",
+        "If tests fail → Capture failure logs and proceed to test-fix cycle"
+      ],
+      "test_fix_cycle": {
+        "max_iterations": 3,
+        "cycle_pattern": "gemini_diagnose → manual_fix (or codex if meta.use_codex=true) → retest",
+        "tools": {
+          "diagnosis": "gemini-wrapper (MODE: analysis, uses bug-fix template)",
+          "fix_application": "manual (default) or codex if meta.use_codex=true",
+          "verification": "bash(npm test -- tests/auth/login.test.ts)"
+        },
+        "exit_conditions": {
+          "success": "all_tests_pass",
+          "failure": "max_iterations_reached"
+        },
+        "steps": [
+          "ITERATION LOOP (max 3):",
+          "  1. Gemini Diagnosis:",
+          "     bash(cd .workflow/WFS-xxx/.process && ~/.claude/scripts/gemini-wrapper --all-files -p \"",
+          "     PURPOSE: Diagnose TDD Green phase test failure iteration [N]",
+          "     TASK: Systematic bug analysis and fix recommendations",
+          "     MODE: analysis",
+          "     CONTEXT: @{CLAUDE.md,**/*CLAUDE.md}",
+          "              Test output: [test_failures]",
+          "              Test requirements: [test_requirements]",
+          "              Implementation: [focus_paths]",
+          "     EXPECTED: Root cause analysis, code path tracing, targeted fixes",
+          "     RULES: $(cat ~/.claude/prompt-templates/bug-fix.md) | Bug: [test_failure_description]",
+          "            Minimal surgical fixes only - stay in Green phase",
+          "     \" > green-fix-iteration-[N]-diagnosis.md)",
+          "  2. Apply Fix (check meta.use_codex):",
+          "     IF meta.use_codex=false (default): Present diagnosis to user for manual fix",
+          "     IF meta.use_codex=true: Codex applies fix automatically",
+          "  3. Retest: bash(npm test -- tests/auth/login.test.ts)",
+          "  4. If pass → Exit loop, complete task",
+          "     If fail → Continue to next iteration",
+          "IF max_iterations reached: Revert changes, report failure"
+        ]
+      }
+    },
+    "post_completion": [
+      {
+        "step": "verify_tests_passing",
+        "action": "Confirm all tests now pass (Green phase achieved)",
+        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "output_to": "final_test_status",
+        "on_error": "fail"
+      }
+    ],
+    "error_handling": {
+      "max_iterations_reached": {
+        "action": "revert_all_changes",
+        "commands": [
+          "bash(git reset --hard HEAD)",
+          "bash(echo 'TDD Green phase failed: Unable to pass tests within 3 iterations' > .workflow/WFS-xxx/.process/green-phase-failure.md)"
+        ],
+        "report": "Generate failure report in .summaries/IMPL-1.1-failure-report.md"
+      }
+    }
+  }
+}
+```
+
+**REFACTOR Phase - Refactoring Task (REFACTOR-1.1.json)**
+```json
+{
+  "id": "REFACTOR-1.1",
+  "title": "Refactor authentication implementation",
+  "status": "pending",
+  "meta": {
+    "type": "refactor",
+    "agent": "@code-developer",
+    "tdd_phase": "refactor"
+  },
+  "context": {
+    "requirements": [
+      "Improve code quality while keeping tests green",
+      "Remove duplication in credential validation",
+      "Improve error handling and logging",
+      "Enhance code readability and maintainability"
+    ],
+    "focus_paths": ["src/auth/AuthService.ts", "tests/auth/login.test.ts"],
+    "acceptance": [
+      "Code quality improved (complexity, readability)",
+      "All tests still pass after refactoring",
+      "No new functionality added",
+      "Duplication eliminated"
+    ],
+    "depends_on": ["IMPL-1.1"]
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "verify_tests_passing",
+        "action": "Run tests to confirm green state before refactoring",
+        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "output_to": "test_status",
+        "on_error": "fail"
+      },
+      {
+        "step": "analyze_code_quality",
+        "action": "Run linter and complexity analysis",
+        "command": "bash(npm run lint src/auth/AuthService.ts)",
+        "output_to": "quality_metrics",
+        "on_error": "warn"
+      }
+    ],
+    "post_completion": [
+      {
+        "step": "verify_tests_still_passing",
+        "action": "Confirm tests remain green after refactoring",
+        "command": "bash(npm test -- tests/auth/login.test.ts)",
+        "output_to": "final_test_status",
+        "on_error": "fail"
+      }
+    ]
+  }
+}
+```
+
+### Phase 4: Unified IMPL_PLAN.md Generation
+
+Generate single comprehensive IMPL_PLAN.md with enhanced 8-section structure:
+
+**Frontmatter**:
+```yaml
+---
+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: "tdd"  # TDD-specific workflow
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → test_context → analysis → concept_verify → tdd_planning"  # TDD workflow phases
+feature_count: N
+task_count: 3N
+tdd_chains: N
+---
+```
+
+**Complete Structure** (8 Sections):
+
+```markdown
+# Implementation Plan: {Project Title}
+
+## 1. Summary
+Core requirements, objectives, and TDD-specific technical approach (2-3 paragraphs max).
+
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
+
+**Technical Approach**:
+- TDD-driven development with Red-Green-Refactor cycles
+- [Other high-level approaches]
+
+## 2. Context Analysis
+
+### CCW Workflow Context
+**Phase Progression** (TDD-specific):
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Test Coverage Analysis (test-context-package.json: existing test patterns identified)
+- ✅ Phase 4: TDD Analysis (ANALYSIS_RESULTS.md: test-first requirements with Gemini/Qwen insights)
+- ✅ Phase 5: Concept Verification ({X} clarifications answered, test requirements clarified | skipped)
+- ⏳ Phase 6: TDD Task Generation (current phase - generating IMPL_PLAN.md with TDD chains)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (test requirements clarified, 0 ambiguities) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute for TDD dependency validation)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Test Context**: {existing test patterns, coverage baseline, test framework detected}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {test file count} tests identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+- **TDD Framework**: Testing framework and tools
+
+### Module Structure
+```
+[Directory tree showing key modules and test directories]
+```
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**Testing**: [Test framework, mocking libraries]
+**Development**: [Linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns]
+- **Testing Patterns**: [Unit, integration, E2E patterns]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every TDD task (TEST/IMPL/REFACTOR) references this for requirements and acceptance criteria
+- **How**: Extract testable requirements, architecture decisions, expected behaviors
+- **Priority**: Authoritative - defines what to test and how to implement
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth for TDD
+
+**Context Intelligence (context-package.json & test-context-package.json)**:
+- **What**: Smart context from CCW's context-gather and test-context-gather phases
+- **Content**: Focus paths, dependency graph, existing test patterns, test framework configuration
+- **Usage**: RED phase loads test patterns, GREEN phase loads implementation context
+- **CCW Value**: Automated discovery of existing tests and patterns for TDD consistency
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen parallel analysis with TDD-specific breakdown
+- **Content**: Testable requirements, test scenarios, implementation strategies, risk assessment
+- **Usage**: RED phase references test cases, GREEN phase references implementation approach
+- **CCW Value**: Multi-model analysis providing comprehensive TDD guidance
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, functional/non-functional requirements
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Discussion framework
+- **system-architect/analysis.md**: Architecture specifications
+- **Role-specific analyses**: [Other relevant analyses]
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for test cases and implementation)
+2. test-context-package.json (existing test patterns for TDD consistency)
+3. context-package.json (smart context for execution environment)
+4. ANALYSIS_RESULTS.md (technical analysis with TDD breakdown)
+5. Role-specific analyses (supplementary)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: TDD Cycles (Red-Green-Refactor)
+
+**Rationale**: Test-first approach ensures correctness and reduces bugs
+
+**TDD Cycle Pattern**:
+- RED: Write failing test
+- GREEN: Implement minimal code to pass (with test-fix cycle if needed)
+- REFACTOR: Improve code quality while keeping tests green
+
+**Parallelization Opportunities**:
+- [Independent features that can be developed in parallel]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [TDD-compatible architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [Test isolation strategy]
+
+### Key Dependencies
+**Task Dependency Graph**:
+```
+Feature 1:
+  TEST-1.1 (RED)
+      ↓
+  IMPL-1.1 (GREEN) [with test-fix cycle]
+      ↓
+  REFACTOR-1.1 (REFACTOR)
+
+Feature 2:
+  TEST-2.1 (RED) [depends on REFACTOR-1.1 if related]
+      ↓
+  IMPL-2.1 (GREEN)
+      ↓
+  REFACTOR-2.1 (REFACTOR)
+```
+
+**Critical Path**: [Identify bottleneck features]
+
+### Testing Strategy
+**TDD Testing Approach**:
+- Unit testing: Each feature has comprehensive unit tests
+- Integration testing: Cross-feature integration
+- E2E testing: Critical user flows after all TDD cycles
+
+**Coverage Targets**:
+- Lines: ≥80% (TDD ensures high coverage)
+- Functions: ≥80%
+- Branches: ≥75%
+
+**Quality Gates**:
+- All tests must pass before moving to next phase
+- Refactor phase must maintain test success
+
+## 5. TDD Task Chains (TDD-Specific Section)
+
+### Feature-by-Feature TDD Chains
+
+**Feature 1: {Feature Name}**
+```
+🔴 TEST-1.1: Write failing test for {feature}
+    ↓
+🟢 IMPL-1.1: Implement to pass tests (includes test-fix cycle: max 3 iterations)
+    ↓
+🔵 REFACTOR-1.1: Refactor implementation while keeping tests green
+```
+
+**Feature 2: {Feature Name}**
+```
+🔴 TEST-2.1: Write failing test for {feature}
+    ↓
+🟢 IMPL-2.1: Implement to pass tests (includes test-fix cycle)
+    ↓
+🔵 REFACTOR-2.1: Refactor implementation
+```
+
+[Continue for all N features]
+
+### TDD Task Breakdown Summary
+- **Total Features**: {N}
+- **Total Tasks**: {3N} (N TEST + N IMPL + N REFACTOR)
+- **TDD Chains**: {N}
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**TDD Cycle Execution**: Feature-by-feature sequential TDD cycles
+
+**Phase 1 (Weeks 1-2): Foundation Features**
+- **Features**: Feature 1, Feature 2
+- **Tasks**: TEST-1.1, IMPL-1.1, REFACTOR-1.1, TEST-2.1, IMPL-2.1, REFACTOR-2.1
+- **Deliverables**:
+  - Complete TDD cycles for foundation features
+  - All tests passing
+- **Success Criteria**:
+  - ≥80% test coverage
+  - All RED-GREEN-REFACTOR cycles completed
+
+**Phase 2 (Weeks 3-N): Advanced Features**
+[Continue with remaining features]
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition with TDD experience]
+
+**External Dependencies**:
+- [Testing frameworks, mocking services]
+
+**Infrastructure**:
+- [CI/CD with test automation]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| Tests fail repeatedly in GREEN phase | High | Medium | Test-fix cycle (max 3 iterations) with auto-revert | Dev Team |
+| Complex features hard to test | High | Medium | Break down into smaller testable units | Architect |
+| [Other risks] | Med/Low | Med/Low | [Strategies] | [Owner] |
+
+**Critical Risks** (TDD-Specific):
+- **GREEN phase failures**: Mitigated by test-fix cycle with Gemini diagnosis
+- **Test coverage gaps**: Mitigated by TDD-first approach ensuring tests before code
+
+**Monitoring Strategy**:
+- Track TDD cycle completion rate
+- Monitor test success rate per iteration
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All features implemented through TDD cycles
+- [ ] All RED-GREEN-REFACTOR cycles completed successfully
+
+**Technical Quality**:
+- [ ] Test coverage ≥80% (ensured by TDD)
+- [ ] All tests passing (GREEN state achieved)
+- [ ] Code refactored for quality (REFACTOR phase completed)
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline with automated test execution
+- [ ] Test failure alerting configured
+
+**TDD Compliance**:
+- [ ] Every feature has TEST → IMPL → REFACTOR chain
+- [ ] No implementation without tests (RED-first principle)
+- [ ] Refactoring did not break tests
+```
+
+### Phase 5: TODO_LIST.md Generation
+
+Generate task list with TDD phase indicators:
+```markdown
+## Feature 1: {Feature Name}
+- [ ] **TEST-1.1**: Write failing test (🔴 RED) → [📋](./.task/TEST-1.1.json)
+- [ ] **IMPL-1.1**: Implement to pass tests (🟢 GREEN) [depends: TEST-1.1] → [📋](./.task/IMPL-1.1.json)
+- [ ] **REFACTOR-1.1**: Refactor implementation (🔵 REFACTOR) [depends: IMPL-1.1] → [📋](./.task/REFACTOR-1.1.json)
+```
+
+### Phase 6: Session State Update
+
+Update workflow-session.json with TDD metadata:
+```json
+{
+  "workflow_type": "tdd",
+  "feature_count": 10,
+  "task_count": 30,
+  "tdd_chains": 10
+}
+```
+
+## Output Files Structure
+```
+.workflow/{session-id}/
+├── IMPL_PLAN.md                     # Unified plan with TDD Task Chains section
+├── TODO_LIST.md                     # Progress tracking with TDD phases
+├── .task/
+│   ├── TEST-1.1.json                # Red phase task
+│   ├── IMPL-1.1.json                # Green phase task (with test-fix-cycle)
+│   ├── REFACTOR-1.1.json            # Refactor phase task
+│   └── ...
+└── .process/
+    ├── ANALYSIS_RESULTS.md          # Enhanced with TDD breakdown from concept-enhanced
+    ├── test-context-package.json    # Test coverage analysis
+    ├── context-package.json         # Input from context-gather
+    └── green-fix-iteration-*.md     # Fix logs from Green phase
+```
+
+## Validation Rules
+
+### Chain Completeness
+- Every TEST-N.M must have corresponding IMPL-N.M and REFACTOR-N.M
+
+### Dependency Enforcement
+- IMPL-N.M must have `depends_on: ["TEST-N.M"]`
+- REFACTOR-N.M must have `depends_on: ["IMPL-N.M"]`
+
+### Task Limits
+- Maximum 10 features (30 tasks total)
+- Flat hierarchy only
+
+## 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 |
+
+### TDD Generation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Feature count exceeds 10 | Too many features | Re-scope requirements |
+| Missing test framework | No test config | Configure testing first |
+| Invalid chain structure | Parsing error | Fix TDD breakdown |
+
+## Integration & Usage
+
+### Command Chain
+- **Called By**: `/workflow:tdd-plan` (Phase 4)
+- **Calls**: Gemini wrapper for TDD breakdown
+- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
+
+### Basic Usage
+```bash
+# Manual mode (default)
+/workflow:tools:task-generate-tdd --session WFS-auth
+
+# Agent mode (autonomous task generation)
+/workflow:tools:task-generate-tdd --session WFS-auth --agent
+```
+
+### Expected Output
+```
+TDD task generation complete for session: WFS-auth
+
+Features analyzed: 5
+TDD chains generated: 5
+Total tasks: 15 (5 TEST + 5 IMPL + 5 REFACTOR)
+
+Structure:
+- Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
+- Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1
+
+Plans generated:
+- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Task Chains section)
+
+Next: /workflow:execute or /workflow:tdd-verify
+```
+
+## Test Coverage Analysis Integration
+
+The TDD workflow includes test coverage analysis (via `/workflow:tools:test-context-gather`) to:
+- Detect existing test patterns and conventions
+- Identify current test coverage gaps
+- Discover test framework and configuration
+- Enable integration with existing tests
+
+This makes TDD workflow context-aware instead of assuming greenfield scenarios.
+
+## Iterative Green Phase with Test-Fix Cycle
+
+IMPL (Green phase) tasks include automatic test-fix cycle:
+
+**Process Flow**:
+1. **Initial Implementation**: Write minimal code to pass tests
+2. **Test Execution**: Run test suite
+3. **Success Path**: Tests pass → Complete task
+4. **Failure Path**: Tests fail → Enter iterative fix cycle:
+   - **Gemini Diagnosis**: Analyze failures with bug-fix template
+   - **Fix Application**: Manual (default) or Codex (if meta.use_codex=true)
+   - **Retest**: Verify fix resolves failures
+   - **Repeat**: Up to max_iterations (default: 3)
+5. **Safety Net**: Auto-revert all changes if max iterations reached
+
+**Key Benefits**:
+- ✅ Faster feedback loop within Green phase
+- ✅ Autonomous recovery from initial implementation errors
+- ✅ Systematic debugging with Gemini's bug-fix template
+- ✅ Safe rollback prevents broken TDD state
+
+## Configuration Options
+- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
+- **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
+
+## Related Commands
+- `/workflow:tdd-plan` - Orchestrates TDD workflow planning (6 phases)
+- `/workflow:tools:test-context-gather` - Analyzes test coverage
+- `/workflow:execute` - Executes TDD tasks in order
+- `/workflow:tdd-verify` - Verifies TDD compliance
+- `/workflow:test-gen` - Post-implementation test generation

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

@@ -67,8 +67,8 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
   "title": "Descriptive task name",
   "status": "pending|active|completed|blocked|container",
   "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@planning-agent|@code-review-test-agent"
+    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
+    "agent": "@code-developer|@test-fix-agent|@general-purpose"
   },
   "context": {
     "requirements": ["Clear requirement from analysis"],
@@ -84,21 +84,22 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "source": "brainstorm_synthesis",
         "path": ".workflow/WFS-[session]/.brainstorming/synthesis-specification.md",
         "priority": "highest",
-        "contains": "complete_integrated_specification"
+        "usage": "Primary requirement source - use for consolidated requirements and cross-role alignment"
+      },
+      {
+        "type": "role_analysis",
+        "source": "brainstorm_roles",
+        "path": ".workflow/WFS-[session]/.brainstorming/[role-name]/analysis.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": "medium",
-        "contains": "discussion_framework_structure"
-      },
-      {
-        "type": "individual_role_analysis",
-        "source": "brainstorm_roles",
-        "path": ".workflow/WFS-[session]/.brainstorming/[role]/analysis.md",
         "priority": "low",
-        "contains": "role_specific_analysis_fallback"
+        "usage": "Discussion context and framework structure"
       }
     ]
   },
@@ -115,14 +116,16 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "on_error": "skip_optional"
       },
       {
-        "step": "load_individual_role_artifacts",
-        "action": "Load individual role analyses as fallback",
+        "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.",
         "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/system-architect/analysis.md)"
+          "Read(.workflow/WFS-[session]/.brainstorming/product-manager/analysis.md)"
         ],
-        "output_to": "individual_artifacts",
+        "output_to": "role_analysis_artifacts",
         "on_error": "skip_optional"
       },
       {
@@ -142,20 +145,21 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
       },
       {
         "step": "analyze_task_patterns",
-        "action": "Analyze existing code patterns",
+        "action": "Analyze existing code patterns and identify modification targets",
         "commands": [
           "bash(cd \"[focus_paths]\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\")"
+          "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\")"
         ],
-        "output_to": "task_context",
+        "output_to": "task_context_with_targets",
         "on_error": "fail"
       }
     ],
     "implementation_approach": {
-      "task_description": "Implement '[title]' following synthesis specification",
+      "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": [
@@ -163,6 +167,7 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
         "Extract requirements and design",
         "Analyze existing patterns",
         "Implement following specification",
+        "Consult artifacts for technical details when needed",
         "Validate against acceptance criteria"
       ]
     },
@@ -175,8 +180,40 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 1. Parse analysis results and extract task definitions
 2. Detect brainstorming artifacts with priority scoring
 3. Generate task context (requirements, focus_paths, acceptance)
-4. Build flow_control with artifact loading steps
-5. Create individual task JSON files in `.task/`
+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/`
+
+#### 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
 
@@ -188,9 +225,12 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 #### 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
-- **security-expert/analysis.md** → Security 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
 
@@ -200,33 +240,229 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 identifier: WFS-{session-id}
 source: "User requirements" | "File: path" | "Issue: ISS-001"
 analysis: .workflow/{session-id}/.process/ANALYSIS_RESULTS.md
+artifacts: .workflow/{session-id}/.brainstorming/
+context_package: .workflow/{session-id}/.process/context-package.json  # CCW smart context
+workflow_type: "standard | tdd | design"  # Indicates execution model
+verification_history:  # CCW quality gates
+  concept_verify: "passed | skipped | pending"
+  action_plan_verify: "pending"
+phase_progression: "brainstorm → context → analysis → concept_verify → planning"  # CCW workflow phases
 ---
 
 # Implementation Plan: {Project Title}
 
-## Summary
-Core requirements, objectives, and technical approach.
+## 1. Summary
+Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
-## Context Analysis
-- **Project**: Type, patterns, tech stack
-- **Modules**: Components and integration points
-- **Dependencies**: External libraries and constraints
-- **Patterns**: Code conventions and guidelines
+**Core Objectives**:
+- [Key objective 1]
+- [Key objective 2]
 
-## Brainstorming Artifacts
-- synthesis-specification.md (Highest priority)
-- topic-framework.md (Medium priority)
-- Role analyses: ui-designer, system-architect, etc.
+**Technical Approach**:
+- [High-level approach]
 
-## Task Breakdown
-- **Task Count**: N tasks, complexity level
-- **Hierarchy**: Flat/Two-level structure
-- **Dependencies**: Task dependency graph
+## 2. Context Analysis
 
-## Implementation Plan
-- **Execution Strategy**: Sequential/Parallel approach
-- **Resource Requirements**: Tools, dependencies, artifacts
-- **Success Criteria**: Metrics and acceptance conditions
+### CCW Workflow Context
+**Phase Progression**:
+- ✅ Phase 1: Brainstorming (synthesis-specification.md generated)
+- ✅ Phase 2: Context Gathering (context-package.json: {N} files, {M} modules analyzed)
+- ✅ Phase 3: Enhanced Analysis (ANALYSIS_RESULTS.md: Gemini/Qwen/Codex parallel insights)
+- ✅ Phase 4: Concept Verification ({X} clarifications answered, synthesis updated | skipped)
+- ⏳ Phase 5: Action Planning (current phase - generating IMPL_PLAN.md)
+
+**Quality Gates**:
+- concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
+- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
+
+**Context Package Summary**:
+- **Focus Paths**: {list key directories from context-package.json}
+- **Key Files**: {list primary files for modification}
+- **Module Depth Analysis**: {from get_modules_by_depth.sh output}
+- **Smart Context**: {total file count} files, {module count} modules, {dependency count} dependencies identified
+
+### Project Profile
+- **Type**: Greenfield/Enhancement/Refactor
+- **Scale**: User count, data volume, complexity
+- **Tech Stack**: Primary technologies
+- **Timeline**: Duration and milestones
+
+### Module Structure
+```
+[Directory tree showing key modules]
+```
+
+### Dependencies
+**Primary**: [Core libraries and frameworks]
+**APIs**: [External services]
+**Development**: [Testing, linting, CI/CD tools]
+
+### Patterns & Conventions
+- **Architecture**: [Key patterns like DI, Event-Driven]
+- **Component Design**: [Design patterns]
+- **State Management**: [State strategy]
+- **Code Style**: [Naming, TypeScript coverage]
+
+## 3. Brainstorming Artifacts Reference
+
+### Artifact Usage Strategy
+**Primary Reference (synthesis-specification.md)**:
+- **What**: Comprehensive implementation blueprint from multi-role synthesis
+- **When**: Every task references this first for requirements and design decisions
+- **How**: Extract architecture decisions, UI/UX patterns, functional requirements, non-functional requirements
+- **Priority**: Authoritative - overrides role-specific analyses when conflicts arise
+- **CCW Value**: Consolidates insights from all brainstorming roles into single source of truth
+
+**Context Intelligence (context-package.json)**:
+- **What**: Smart context gathered by CCW's context-gather phase
+- **Content**: Focus paths, dependency graph, existing patterns, module structure
+- **Usage**: Tasks load this via `flow_control.preparatory_steps` for environment setup
+- **CCW Value**: Automated intelligent context discovery replacing manual file exploration
+
+**Technical Analysis (ANALYSIS_RESULTS.md)**:
+- **What**: Gemini/Qwen/Codex parallel analysis results
+- **Content**: Optimization strategies, risk assessment, architecture review, implementation patterns
+- **Usage**: Referenced in task planning for technical guidance and risk mitigation
+- **CCW Value**: Multi-model parallel analysis providing comprehensive technical intelligence
+
+### Integrated Specifications (Highest Priority)
+- **synthesis-specification.md**: Comprehensive implementation blueprint
+  - Contains: Architecture design, UI/UX guidelines, functional/non-functional requirements, implementation roadmap, risk assessment
+
+### Supporting Artifacts (Reference)
+- **topic-framework.md**: Role-specific discussion points and analysis framework
+- **system-architect/analysis.md**: Detailed architecture specifications
+- **ui-designer/analysis.md**: Layout and component specifications
+- **product-manager/analysis.md**: Product vision and user stories
+
+**Artifact Priority in Development**:
+1. synthesis-specification.md (primary reference for all tasks)
+2. context-package.json (smart context for execution environment)
+3. ANALYSIS_RESULTS.md (technical analysis and optimization strategies)
+4. Role-specific analyses (fallback for detailed specifications)
+
+## 4. Implementation Strategy
+
+### Execution Strategy
+**Execution Model**: [Sequential | Parallel | Phased | TDD Cycles]
+
+**Rationale**: [Why this execution model fits the project]
+
+**Parallelization Opportunities**:
+- [List independent workstreams]
+
+**Serialization Requirements**:
+- [List critical dependencies]
+
+### Architectural Approach
+**Key Architecture Decisions**:
+- [ADR references from synthesis]
+- [Justification for architecture patterns]
+
+**Integration Strategy**:
+- [How modules communicate]
+- [State management approach]
+
+### Key Dependencies
+**Task Dependency Graph**:
+```
+[High-level dependency visualization]
+```
+
+**Critical Path**: [Identify bottleneck tasks]
+
+### Testing Strategy
+**Testing Approach**:
+- Unit testing: [Tools, scope]
+- Integration testing: [Key integration points]
+- E2E testing: [Critical user flows]
+
+**Coverage Targets**:
+- Lines: ≥70%
+- Functions: ≥70%
+- Branches: ≥65%
+
+**Quality Gates**:
+- [CI/CD gates]
+- [Performance budgets]
+
+## 5. Task Breakdown Summary
+
+### Task Count
+**{N} tasks** (flat hierarchy | two-level hierarchy, sequential | parallel execution)
+
+### Task Structure
+- **IMPL-1**: [Main task title]
+- **IMPL-2**: [Main task title]
+...
+
+### Complexity Assessment
+- **High**: [List with rationale]
+- **Medium**: [List]
+- **Low**: [List]
+
+### Dependencies
+[Reference Section 4.3 for dependency graph]
+
+**Parallelization Opportunities**:
+- [Specific task groups that can run in parallel]
+
+## 6. Implementation Plan (Detailed Phased Breakdown)
+
+### Execution Strategy
+
+**Phase 1 (Weeks 1-2): [Phase Name]**
+- **Tasks**: IMPL-1, IMPL-2
+- **Deliverables**:
+  - [Specific deliverable 1]
+  - [Specific deliverable 2]
+- **Success Criteria**:
+  - [Measurable criterion]
+
+**Phase 2 (Weeks 3-N): [Phase Name]**
+...
+
+### Resource Requirements
+
+**Development Team**:
+- [Team composition and skills]
+
+**External Dependencies**:
+- [Third-party services, APIs]
+
+**Infrastructure**:
+- [Development, staging, production environments]
+
+## 7. Risk Assessment & Mitigation
+
+| Risk | Impact | Probability | Mitigation Strategy | Owner |
+|------|--------|-------------|---------------------|-------|
+| [Risk description] | High/Med/Low | High/Med/Low | [Strategy] | [Role] |
+
+**Critical Risks** (High impact + High probability):
+- [Risk 1]: [Detailed mitigation plan]
+
+**Monitoring Strategy**:
+- [How risks will be monitored]
+
+## 8. Success Criteria
+
+**Functional Completeness**:
+- [ ] All requirements from synthesis-specification.md implemented
+- [ ] All acceptance criteria from task.json files met
+
+**Technical Quality**:
+- [ ] Test coverage ≥70%
+- [ ] Bundle size within budget
+- [ ] Performance targets met
+
+**Operational Readiness**:
+- [ ] CI/CD pipeline operational
+- [ ] Monitoring and logging configured
+- [ ] Documentation complete
+
+**Business Metrics**:
+- [ ] [Key business metrics from synthesis]
 ```
 
 ### Phase 5: TODO_LIST.md Generation

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

@@ -0,0 +1,284 @@
+---
+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(*)
+---
+
+# TDD Coverage Analysis Command
+
+## Overview
+Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD workflow validation.
+
+## Core Responsibilities
+- Extract test files from TEST tasks
+- Run test suite with coverage
+- Parse coverage metrics
+- Verify TDD cycle execution (Red -> Green -> Refactor)
+- Generate coverage and cycle reports
+
+## Execution Lifecycle
+
+### Phase 1: Extract Test Tasks
+```bash
+find .workflow/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
+```
+
+**Output**: List of test directories/files from all TEST tasks
+
+### Phase 2: Run Test Suite
+```bash
+# Node.js/JavaScript
+npm test -- --coverage --json > .workflow/{session_id}/.process/test-results.json
+
+# Python
+pytest --cov --json-report > .workflow/{session_id}/.process/test-results.json
+
+# Other frameworks (detect from project)
+[test_command] --coverage --json-output .workflow/{session_id}/.process/test-results.json
+```
+
+**Output**: test-results.json with coverage data
+
+### Phase 3: Parse Coverage Data
+```bash
+jq '.coverage' .workflow/{session_id}/.process/test-results.json > .workflow/{session_id}/.process/coverage-report.json
+```
+
+**Extract**:
+- Line coverage percentage
+- Branch coverage percentage
+- Function coverage percentage
+- Uncovered lines/branches
+
+### Phase 4: Verify TDD Cycle
+
+For each TDD chain (TEST-N.M -> IMPL-N.M -> REFACTOR-N.M):
+
+**1. Red Phase Verification**
+```bash
+# Check TEST task summary
+cat .workflow/{session_id}/.summaries/TEST-N.M-summary.md
+```
+
+Verify:
+- Tests were created
+- Tests failed initially
+- Failure messages were clear
+
+**2. Green Phase Verification**
+```bash
+# Check IMPL task summary
+cat .workflow/{session_id}/.summaries/IMPL-N.M-summary.md
+```
+
+Verify:
+- Implementation was completed
+- Tests now pass
+- Implementation was minimal
+
+**3. Refactor Phase Verification**
+```bash
+# Check REFACTOR task summary
+cat .workflow/{session_id}/.summaries/REFACTOR-N.M-summary.md
+```
+
+Verify:
+- Refactoring was completed
+- Tests still pass
+- Code quality improved
+
+### Phase 5: Generate Analysis Report
+
+Create `.workflow/{session_id}/.process/tdd-cycle-report.md`:
+
+```markdown
+# TDD Cycle Analysis - {Session ID}
+
+## Coverage Metrics
+- **Line Coverage**: {percentage}%
+- **Branch Coverage**: {percentage}%
+- **Function Coverage**: {percentage}%
+
+## Coverage Details
+### Covered
+- {covered_lines} lines
+- {covered_branches} branches
+- {covered_functions} functions
+
+### Uncovered
+- Lines: {uncovered_line_numbers}
+- Branches: {uncovered_branch_locations}
+
+## TDD Cycle Verification
+
+### Feature 1: {Feature Name}
+**Chain**: TEST-1.1 -> IMPL-1.1 -> REFACTOR-1.1
+
+- [PASS] **Red Phase**: Tests created and failed initially
+- [PASS] **Green Phase**: Implementation made tests pass
+- [PASS] **Refactor Phase**: Refactoring maintained green tests
+
+### Feature 2: {Feature Name}
+**Chain**: TEST-2.1 -> IMPL-2.1 -> REFACTOR-2.1
+
+- [PASS] **Red Phase**: Tests created and failed initially
+- [WARN] **Green Phase**: Tests pass but implementation seems over-engineered
+- [PASS] **Refactor Phase**: Refactoring maintained green tests
+
+[Repeat for all features]
+
+## TDD Compliance Summary
+- **Total Chains**: {N}
+- **Complete Cycles**: {N}
+- **Incomplete Cycles**: {0}
+- **Compliance Score**: {score}/100
+
+## Gaps Identified
+- Feature 3: Missing initial test failure verification
+- Feature 5: No refactoring step completed
+
+## Recommendations
+- Complete missing refactoring steps
+- Add edge case tests for Feature 2
+- Verify test failure messages are descriptive
+```
+
+## Output Files
+```
+.workflow/{session-id}/
+└── .process/
+    ├── test-results.json         # Raw test execution results
+    ├── coverage-report.json      # Parsed coverage data
+    └── tdd-cycle-report.md       # TDD cycle analysis
+```
+
+## Test Framework Detection
+
+Auto-detect test framework from project:
+
+```bash
+# Check for test frameworks
+if [ -f "package.json" ] && grep -q "jest\|mocha\|vitest" package.json; then
+    TEST_CMD="npm test -- --coverage --json"
+elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
+    TEST_CMD="pytest --cov --json-report"
+elif [ -f "Cargo.toml" ]; then
+    TEST_CMD="cargo test -- --test-threads=1 --nocapture"
+elif [ -f "go.mod" ]; then
+    TEST_CMD="go test -coverprofile=coverage.out -json ./..."
+else
+    TEST_CMD="echo 'No supported test framework found'"
+fi
+```
+
+## TDD Cycle Verification Algorithm
+
+```
+For each feature N:
+  1. Load TEST-N.M-summary.md
+     IF summary missing:
+       Mark: "Red phase incomplete"
+       SKIP to next feature
+
+     CHECK: Contains "test" AND "fail"
+     IF NOT found:
+       Mark: "Red phase verification failed"
+     ELSE:
+       Mark: "Red phase [PASS]"
+
+  2. Load IMPL-N.M-summary.md
+     IF summary missing:
+       Mark: "Green phase incomplete"
+       SKIP to next feature
+
+     CHECK: Contains "pass" OR "green"
+     IF NOT found:
+       Mark: "Green phase verification failed"
+     ELSE:
+       Mark: "Green phase [PASS]"
+
+  3. Load REFACTOR-N.M-summary.md
+     IF summary missing:
+       Mark: "Refactor phase incomplete"
+       CONTINUE (refactor is optional)
+
+     CHECK: Contains "refactor" AND "pass"
+     IF NOT found:
+       Mark: "Refactor phase verification failed"
+     ELSE:
+       Mark: "Refactor phase [PASS]"
+
+  4. Calculate chain score:
+     - Red + Green + Refactor all [PASS] = 100%
+     - Red + Green [PASS], Refactor missing = 80%
+     - Red [PASS], Green missing = 40%
+     - All missing = 0%
+```
+
+## Coverage Metrics Calculation
+
+```bash
+# Parse coverage from test-results.json
+line_coverage=$(jq '.coverage.lineCoverage' test-results.json)
+branch_coverage=$(jq '.coverage.branchCoverage' test-results.json)
+function_coverage=$(jq '.coverage.functionCoverage' test-results.json)
+
+# Calculate overall score
+overall_score=$(echo "($line_coverage + $branch_coverage + $function_coverage) / 3" | bc)
+```
+
+## Error Handling
+
+### Test Execution Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Test framework not found | No test config | Configure test framework first |
+| Tests fail to run | Syntax errors | Fix code before analysis |
+| Coverage not available | Missing coverage tool | Install coverage plugin |
+
+### Cycle Verification Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Summary missing | Task not executed | Execute tasks before analysis |
+| Invalid summary format | Corrupted file | Re-run task to regenerate |
+| No test evidence | Tests not committed | Ensure tests are committed |
+
+## Integration & Usage
+
+### Command Chain
+- **Called By**: `/workflow:tdd-verify` (Phase 3)
+- **Calls**: Test framework commands (npm test, pytest, etc.)
+- **Followed By**: Compliance report generation
+
+### Basic Usage
+```bash
+/workflow:tools:tdd-coverage-analysis --session WFS-auth
+```
+
+### Expected Output
+```
+TDD Coverage Analysis complete for session: WFS-auth
+
+## Coverage Results
+Line Coverage: 87%
+Branch Coverage: 82%
+Function Coverage: 91%
+
+## TDD Cycle Verification
+[PASS] Feature 1: Complete (Red -> Green -> Refactor)
+[PASS] Feature 2: Complete (Red -> Green -> Refactor)
+[WARN] Feature 3: Incomplete (Red -> Green, missing Refactor)
+
+Overall Compliance: 93/100
+
+Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
+```
+
+## Related Commands
+- `/workflow:tdd-verify` - Uses this tool for verification
+- `/workflow:tools:task-generate-tdd` - Generates tasks this tool analyzes
+- `/workflow:execute` - Executes tasks before analysis

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

@@ -0,0 +1,468 @@
+---
+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
+---
+
+# Test Concept Enhanced Command
+
+## Overview
+Specialized analysis tool for test generation workflows that uses Gemini to analyze test coverage gaps, implementation context, and generate comprehensive test generation strategies.
+
+## Core Philosophy
+- **Coverage-Driven**: Focus on identified test gaps from context analysis
+- **Pattern-Based**: Learn from existing tests and project conventions
+- **Gemini-Powered**: Use Gemini for test requirement analysis and strategy design
+- **Single-Round Analysis**: Comprehensive test analysis in one execution
+- **No Code Generation**: Strategy and planning only, actual test generation happens in task execution
+
+## Core Responsibilities
+- Parse test-context-package.json from test-context-gather
+- Analyze implementation summaries and coverage gaps
+- Study existing test patterns and conventions
+- Generate test generation strategy using Gemini
+- Produce TEST_ANALYSIS_RESULTS.md for task generation
+
+## Execution Lifecycle
+
+### Phase 1: Validation & Preparation
+
+1. **Session Validation**
+   - Load `.workflow/{test_session_id}/workflow-session.json`
+   - Verify test session type is "test-gen"
+   - Extract source session reference
+
+2. **Context Package Validation**
+   - Read `test-context-package.json`
+   - Validate required sections: metadata, source_context, test_coverage, test_framework
+   - Extract coverage gaps and framework details
+
+3. **Strategy Determination**
+   - **Simple Test Generation** (1-3 files): Single Gemini analysis
+   - **Medium Test Generation** (4-6 files): Gemini comprehensive analysis
+   - **Complex Test Generation** (>6 files): Gemini analysis with modular approach
+
+### Phase 2: Gemini Test Analysis
+
+**Tool Configuration**:
+```bash
+cd .workflow/{test_session_id}/.process && ~/.claude/scripts/gemini-wrapper -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
+CONTEXT: @{.workflow/{test_session_id}/.process/test-context-package.json}
+
+**MANDATORY FIRST STEP**: Read and analyze test-context-package.json to understand:
+- Test coverage gaps from test_coverage.missing_tests[]
+- Implementation context from source_context.implementation_summaries[]
+- Existing test patterns from test_framework.conventions
+- Changed files requiring tests from source_context.implementation_summaries[].changed_files
+
+**ANALYSIS REQUIREMENTS**:
+
+1. **Implementation Understanding**
+   - Load all implementation summaries from source session
+   - Understand implemented features, APIs, and business logic
+   - Extract key functions, classes, and modules
+   - Identify integration points and dependencies
+
+2. **Existing Test Pattern Analysis**
+   - Study existing test files for patterns and conventions
+   - Identify test structure (describe/it, test suites, fixtures)
+   - Analyze assertion patterns and mocking strategies
+   - Extract test setup/teardown patterns
+
+3. **Coverage Gap Assessment**
+   - For each file in missing_tests[], analyze:
+     - File purpose and functionality
+     - Public APIs requiring test coverage
+     - Critical paths and edge cases
+     - Integration points requiring tests
+   - Prioritize tests: high (core logic), medium (utilities), low (helpers)
+
+4. **Test Requirements Specification**
+   - For each missing test file, specify:
+     - **Test scope**: What needs to be tested
+     - **Test scenarios**: Happy path, error cases, edge cases, integration
+     - **Test data**: Required fixtures, mocks, test data
+     - **Dependencies**: External services, databases, APIs to mock
+     - **Coverage targets**: Functions/methods requiring tests
+
+5. **Test Generation Strategy**
+   - Determine test generation approach for each file
+   - Identify reusable test patterns from existing tests
+   - Plan test data and fixture requirements
+   - Define mocking strategy for dependencies
+   - Specify expected test file structure
+
+EXPECTED OUTPUT - Write to gemini-test-analysis.md:
+
+# Test Generation Analysis
+
+## 1. Implementation Context Summary
+- **Source Session**: {source_session_id}
+- **Implemented Features**: {feature_summary}
+- **Changed Files**: {list_of_implementation_files}
+- **Tech Stack**: {technologies_used}
+
+## 2. Test Coverage Assessment
+- **Existing Tests**: {count} files
+- **Missing Tests**: {count} files
+- **Coverage Percentage**: {percentage}%
+- **Priority Breakdown**:
+  - High Priority: {count} files (core business logic)
+  - Medium Priority: {count} files (utilities, helpers)
+  - Low Priority: {count} files (configuration, constants)
+
+## 3. Existing Test Pattern Analysis
+- **Test Framework**: {framework_name_and_version}
+- **File Naming Convention**: {pattern}
+- **Test Structure**: {describe_it_or_other}
+- **Assertion Style**: {expect_assert_should}
+- **Mocking Strategy**: {mocking_framework_and_patterns}
+- **Setup/Teardown**: {beforeEach_afterEach_patterns}
+- **Test Data**: {fixtures_factories_builders}
+
+## 4. Test Requirements by File
+
+### File: {implementation_file_path}
+**Test File**: {suggested_test_file_path}
+**Priority**: {high|medium|low}
+
+#### Scope
+- {description_of_what_needs_testing}
+
+#### Test Scenarios
+1. **Happy Path Tests**
+   - {scenario_1}
+   - {scenario_2}
+
+2. **Error Handling Tests**
+   - {error_scenario_1}
+   - {error_scenario_2}
+
+3. **Edge Case Tests**
+   - {edge_case_1}
+   - {edge_case_2}
+
+4. **Integration Tests** (if applicable)
+   - {integration_scenario_1}
+   - {integration_scenario_2}
+
+#### Test Data & Fixtures
+- {required_test_data}
+- {required_mocks}
+- {required_fixtures}
+
+#### Dependencies to Mock
+- {external_service_1}
+- {external_service_2}
+
+#### Coverage Targets
+- Function: {function_name} - {test_requirements}
+- Function: {function_name} - {test_requirements}
+
+---
+[Repeat for each missing test file]
+---
+
+## 5. Test Generation Strategy
+
+### Overall Approach
+- {strategy_description}
+
+### Test Generation Order
+1. {file_1} - {rationale}
+2. {file_2} - {rationale}
+3. {file_3} - {rationale}
+
+### Reusable Patterns
+- {pattern_1_from_existing_tests}
+- {pattern_2_from_existing_tests}
+
+### Test Data Strategy
+- {approach_to_test_data_and_fixtures}
+
+### Mocking Strategy
+- {approach_to_mocking_dependencies}
+
+### Quality Criteria
+- Code coverage target: {percentage}%
+- Test scenarios per function: {count}
+- Integration test coverage: {approach}
+
+## 6. Implementation Targets
+
+**Purpose**: Identify new test files to create
+
+**Format**: New test files only (no existing files to modify)
+
+**Test Files to Create**:
+1. **Target**: `tests/auth/TokenValidator.test.ts`
+   - **Type**: Create new test file
+   - **Purpose**: Test TokenValidator class
+   - **Scenarios**: 15 test cases covering validation logic, error handling, edge cases
+   - **Dependencies**: Mock JWT library, test fixtures for tokens
+
+2. **Target**: `tests/middleware/errorHandler.test.ts`
+   - **Type**: Create new test file
+   - **Purpose**: Test error handling middleware
+   - **Scenarios**: 8 test cases for different error types and response formats
+   - **Dependencies**: Mock Express req/res/next, error fixtures
+
+[List all test files to create]
+
+## 7. Success Metrics
+- **Test Coverage Goal**: {target_percentage}%
+- **Test Quality**: All scenarios covered (happy, error, edge, integration)
+- **Convention Compliance**: Follow existing test patterns
+- **Maintainability**: Clear test descriptions, reusable fixtures
+
+RULES:
+- Focus on TEST REQUIREMENTS and GENERATION STRATEGY, NOT code generation
+- Study existing test patterns thoroughly for consistency
+- Prioritize critical business logic tests
+- Specify clear test scenarios and coverage targets
+- Identify all dependencies requiring mocks
+- **MUST write output to .workflow/{test_session_id}/.process/gemini-test-analysis.md**
+- Do NOT generate actual test code or implementation
+- Output ONLY test analysis and generation strategy
+" --approval-mode yolo
+```
+
+**Output Location**: `.workflow/{test_session_id}/.process/gemini-test-analysis.md`
+
+### Phase 3: Results Synthesis
+
+1. **Output Validation**
+   - Verify `gemini-test-analysis.md` exists and is complete
+   - Validate all required sections present
+   - Check test requirements are actionable
+
+2. **Quality Assessment**
+   - Test scenarios cover happy path, errors, edge cases
+   - Dependencies and mocks clearly identified
+   - Test generation strategy is practical
+   - Coverage targets are reasonable
+
+### Phase 4: TEST_ANALYSIS_RESULTS.md Generation
+
+Synthesize Gemini analysis into standardized format:
+
+```markdown
+# Test Generation Analysis Results
+
+## Executive Summary
+- **Test Session**: {test_session_id}
+- **Source Session**: {source_session_id}
+- **Analysis Timestamp**: {timestamp}
+- **Coverage Gap**: {missing_test_count} files require tests
+- **Test Framework**: {framework}
+- **Overall Strategy**: {high_level_approach}
+
+---
+
+## 1. Coverage Assessment
+
+### Current Coverage
+- **Existing Tests**: {count} files
+- **Implementation Files**: {count} files
+- **Coverage Percentage**: {percentage}%
+
+### Missing Tests (Priority Order)
+1. **High Priority** ({count} files)
+   - {file_1} - {reason}
+   - {file_2} - {reason}
+
+2. **Medium Priority** ({count} files)
+   - {file_1} - {reason}
+
+3. **Low Priority** ({count} files)
+   - {file_1} - {reason}
+
+---
+
+## 2. Test Framework & Conventions
+
+### Framework Configuration
+- **Framework**: {framework_name}
+- **Version**: {version}
+- **Test Pattern**: {file_pattern}
+- **Test Directory**: {directory_structure}
+
+### Conventions
+- **File Naming**: {convention}
+- **Test Structure**: {describe_it_blocks}
+- **Assertions**: {assertion_library}
+- **Mocking**: {mocking_framework}
+- **Setup/Teardown**: {beforeEach_afterEach}
+
+### Example Pattern (from existing tests)
+```
+{example_test_structure_from_analysis}
+```
+
+---
+
+## 3. Test Requirements by File
+
+[For each missing test, include:]
+
+### Test File: {test_file_path}
+**Implementation**: {implementation_file}
+**Priority**: {high|medium|low}
+**Estimated Test Count**: {count}
+
+#### Test Scenarios
+1. **Happy Path**: {scenarios}
+2. **Error Handling**: {scenarios}
+3. **Edge Cases**: {scenarios}
+4. **Integration**: {scenarios}
+
+#### Dependencies & Mocks
+- {dependency_1_to_mock}
+- {dependency_2_to_mock}
+
+#### Test Data Requirements
+- {fixture_1}
+- {fixture_2}
+
+---
+
+## 4. Test Generation Strategy
+
+### Generation Approach
+{overall_strategy_description}
+
+### Generation Order
+1. {test_file_1} - {rationale}
+2. {test_file_2} - {rationale}
+3. {test_file_3} - {rationale}
+
+### Reusable Components
+- **Test Fixtures**: {common_fixtures}
+- **Mock Patterns**: {common_mocks}
+- **Helper Functions**: {test_helpers}
+
+### Quality Targets
+- **Coverage Goal**: {percentage}%
+- **Scenarios per Function**: {min_count}
+- **Integration Coverage**: {approach}
+
+---
+
+## 5. Implementation Targets
+
+**Purpose**: New test files to create (code-developer will generate these)
+
+**Test Files to Create**:
+
+1. **Target**: `tests/auth/TokenValidator.test.ts`
+   - **Implementation Source**: `src/auth/TokenValidator.ts`
+   - **Test Scenarios**: 15 (validation, error handling, edge cases)
+   - **Dependencies**: Mock JWT library, token fixtures
+   - **Priority**: High
+
+2. **Target**: `tests/middleware/errorHandler.test.ts`
+   - **Implementation Source**: `src/middleware/errorHandler.ts`
+   - **Test Scenarios**: 8 (error types, response formats)
+   - **Dependencies**: Mock Express, error fixtures
+   - **Priority**: High
+
+[List all test files with full specifications]
+
+---
+
+## 6. Success Criteria
+
+### Coverage Metrics
+- Achieve {target_percentage}% code coverage
+- All public APIs have tests
+- Critical paths fully covered
+
+### Quality Standards
+- All test scenarios covered (happy, error, edge, integration)
+- Follow existing test conventions
+- Clear test descriptions and assertions
+- Maintainable test structure
+
+### Validation Approach
+- Run full test suite after generation
+- Verify coverage with coverage tool
+- Manual review of test quality
+- Integration test validation
+
+---
+
+## 7. Reference Information
+
+### Source Context
+- **Implementation Summaries**: {paths}
+- **Existing Tests**: {example_tests}
+- **Documentation**: {relevant_docs}
+
+### Analysis Tools
+- **Gemini Analysis**: gemini-test-analysis.md
+- **Coverage Tools**: {coverage_tool_if_detected}
+```
+
+**Output Location**: `.workflow/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
+
+## Error Handling
+
+### Validation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing context package | test-context-gather not run | Run test-context-gather first |
+| No coverage gaps | All files have tests | Skip test generation, proceed to test execution |
+| No test framework detected | Missing test dependencies | Request user to configure test framework |
+| Invalid source session | Source session incomplete | Complete implementation first |
+
+### Gemini Execution Errors
+| Error | Cause | Recovery |
+|-------|-------|----------|
+| Timeout | Large project analysis | Reduce scope, analyze by module |
+| Output incomplete | Token limit exceeded | Retry with focused analysis |
+| No output file | Write permission error | Check directory permissions |
+
+### Fallback Strategy
+- If Gemini fails, generate basic TEST_ANALYSIS_RESULTS.md from context package
+- Use coverage gaps and framework info to create minimal requirements
+- Provide guidance for manual test planning
+
+## Performance Optimization
+
+- **Focused Analysis**: Only analyze files with missing tests
+- **Pattern Reuse**: Study existing tests for quick pattern extraction
+- **Parallel Operations**: Load implementation summaries in parallel
+- **Timeout Management**: 20-minute limit for Gemini analysis
+
+## Integration
+
+### Called By
+- `/workflow:test-gen` (Phase 4: Analysis)
+
+### Requires
+- `/workflow:tools:test-context-gather` output (test-context-package.json)
+
+### Followed By
+- `/workflow:tools:test-task-generate` - Generates test task JSON with code-developer invocation
+
+## Success Criteria
+
+- ✅ Valid TEST_ANALYSIS_RESULTS.md generated
+- ✅ All missing tests documented with requirements
+- ✅ Test scenarios cover happy path, errors, edge cases
+- ✅ Dependencies and mocks identified
+- ✅ Test generation strategy is actionable
+- ✅ Execution time < 20 minutes
+- ✅ Output follows existing test conventions
+
+## Related Commands
+
+- `/workflow:tools:test-context-gather` - Provides input context
+- `/workflow:tools:test-task-generate` - Consumes analysis results
+- `/workflow:test-gen` - Main test generation workflow

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

@@ -0,0 +1,310 @@
+---
+name: test-context-gather
+description: Collect test coverage context and identify files requiring test generation
+usage: /workflow:tools:test-context-gather --session <test_session_id>
+argument-hint: "--session WFS-test-session-id"
+examples:
+  - /workflow:tools:test-context-gather --session WFS-test-auth
+  - /workflow:tools:test-context-gather --session WFS-test-payment
+---
+
+# Test Context Gather Command
+
+## Overview
+Specialized context collector for test generation workflows that analyzes test coverage, identifies missing tests, and packages implementation context from source sessions.
+
+## Core Philosophy
+- **Coverage-First**: Analyze existing test coverage before planning
+- **Gap Identification**: Locate implementation files without corresponding 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
+
+## 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 Lifecycle
+
+### Phase 1: Session Validation & Source Loading
+
+1. **Test Session Validation**
+   - Load `.workflow/{test_session_id}/workflow-session.json`
+   - Extract `meta.source_session` reference
+   - Validate test session type is "test-gen"
+
+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
+
+### 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"
+  ]
+}
+```
+
+## Output Location
+
+```
+.workflow/{test_session_id}/.process/test-context-package.json
+```
+
+## MCP Tools Usage
+
+### File Discovery
+```bash
+# Test files
+mcp__code-index__find_files(pattern="*.test.*")
+mcp__code-index__find_files(pattern="*.spec.*")
+
+# Implementation files
+mcp__code-index__find_files(pattern="*.ts")
+mcp__code-index__find_files(pattern="*.js")
+```
+
+### Content Search
+```bash
+# Test framework detection
+mcp__code-index__search_code_advanced(
+  pattern="jest|mocha|pytest",
+  file_pattern="package.json|requirements.txt"
+)
+
+# Test pattern analysis
+mcp__code-index__search_code_advanced(
+  pattern="describe|it|test",
+  file_pattern="*.test.*",
+  context_lines=2
+)
+```
+
+### 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"
+)
+
+# 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
+```
+
+## 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 |
+| 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
+```
+
+## Integration
+
+### Called By
+- `/workflow:test-gen` (Phase 3: Context Gathering)
+
+### Calls
+- MCP code-index tools for analysis
+- Bash file operations for fallback
+
+### Followed By
+- `/workflow:tools:test-concept-enhanced` - Analyzes context and plans test generation
+
+## Success Criteria
+
+- ✅ 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
+
+## Related Commands
+
+- `/workflow:test-gen` - Main test generation workflow
+- `/workflow:tools:test-concept-enhanced` - Test generation analysis
+- `/workflow:tools:test-task-generate` - Test task JSON generation

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

@@ -0,0 +1,655 @@
+---
+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"
+examples:
+  - /workflow:tools:test-task-generate --session WFS-test-auth
+  - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+---
+
+# Test Task Generation Command
+
+## 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).
+
+## 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
+- **Coverage-First**: Generate all missing tests before execution
+- **Test Execution**: Execute complete test suite after generation
+- **Gemini Diagnosis**: Use Gemini for root cause analysis and fix suggestions (references bug-fix template)
+- **Manual Fixes First**: Apply fixes manually by default, codex only when explicitly needed
+- **Iterative Refinement**: Repeat test-analyze-fix-retest cycle until all tests pass
+- **Surgical Fixes**: Minimal code changes, no refactoring during test fixes
+- **Auto-Revert**: Rollback all changes if max iterations reached
+
+## Core Responsibilities
+- Parse TEST_ANALYSIS_RESULTS.md from test-concept-enhanced
+- Extract test requirements and generation strategy
+- Parse `--use-codex` flag to determine fix mode (manual vs automated)
+- Generate test generation subtask calling @code-developer
+- Generate test execution and fix cycle task JSON with appropriate fix mode
+- Configure Gemini diagnosis workflow (bug-fix template) and manual/Codex fix application
+- Create test-oriented IMPL_PLAN.md and TODO_LIST.md with test generation phase
+
+## Execution Lifecycle
+
+### Phase 1: Input Validation & Discovery
+
+1. **Parameter Parsing**
+   - Parse `--use-codex` flag from command arguments
+   - Store flag value for IMPL-002.json generation
+
+2. **Test Session Validation**
+   - Load `.workflow/{test-session-id}/workflow-session.json`
+   - Verify `workflow_type: "test_session"`
+   - Extract `source_session_id` from metadata
+
+3. **Test Analysis Results Loading**
+   - **REQUIRED**: Load `.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md`
+   - Parse test requirements by file
+   - Extract test generation strategy
+   - Identify test files to create with specifications
+
+4. **Test Context Package Loading**
+   - Load `.workflow/{test-session-id}/.process/test-context-package.json`
+   - Extract test framework configuration
+   - Extract coverage gaps and priorities
+   - Load source session implementation summaries
+
+### Phase 2: Task JSON Generation
+
+Generate **TWO task JSON files**:
+1. **IMPL-001.json** - Test Generation (calls @code-developer)
+2. **IMPL-002.json** - Test Execution and Fix Cycle (calls @test-fix-agent)
+
+#### IMPL-001.json - Test Generation Task
+
+```json
+{
+  "id": "IMPL-001",
+  "title": "Generate comprehensive tests for [sourceSessionId]",
+  "status": "pending",
+  "meta": {
+    "type": "test-gen",
+    "agent": "@code-developer",
+    "source_session": "[sourceSessionId]",
+    "test_framework": "jest|pytest|cargo|detected"
+  },
+  "context": {
+    "requirements": [
+      "Generate comprehensive test files based on TEST_ANALYSIS_RESULTS.md",
+      "Follow existing test patterns and conventions from test framework",
+      "Create tests for all missing coverage identified in analysis",
+      "Include happy path, error handling, edge cases, and integration tests",
+      "Use test data and mocks as specified in analysis",
+      "Ensure tests follow project coding standards"
+    ],
+    "focus_paths": [
+      "tests/**/*",
+      "src/**/*.test.*",
+      "{paths_from_analysis}"
+    ],
+    "acceptance": [
+      "All test files from TEST_ANALYSIS_RESULTS.md section 5 are created",
+      "Tests follow existing test patterns and conventions",
+      "Test scenarios cover happy path, errors, edge cases, integration",
+      "All dependencies are properly mocked",
+      "Test files are syntactically valid and can be executed",
+      "Test coverage meets analysis requirements"
+    ],
+    "depends_on": [],
+    "source_context": {
+      "session_id": "[sourceSessionId]",
+      "test_analysis": ".workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md",
+      "test_context": ".workflow/[testSessionId]/.process/test-context-package.json",
+      "implementation_summaries": [
+        ".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
+      ]
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_test_analysis",
+        "action": "Load test generation requirements and strategy",
+        "commands": [
+          "Read(.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md)",
+          "Read(.workflow/[testSessionId]/.process/test-context-package.json)"
+        ],
+        "output_to": "test_generation_requirements",
+        "on_error": "fail"
+      },
+      {
+        "step": "load_implementation_context",
+        "action": "Load source implementation for test generation context",
+        "commands": [
+          "bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
+        ],
+        "output_to": "implementation_context",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "load_existing_test_patterns",
+        "action": "Study existing tests for pattern reference",
+        "commands": [
+          "mcp__code-index__find_files(pattern=\"*.test.*\")",
+          "bash(# Read first 2 existing test files as examples)",
+          "bash(test_files=$(mcp__code-index__find_files(pattern=\"*.test.*\") | 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"
+      ],
+      "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"
+      ]
+    },
+    "target_files": [
+      "{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
+      "{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
+      "{test_file_N from TEST_ANALYSIS_RESULTS.md section 5}"
+    ]
+  }
+}
+```
+
+#### IMPL-002.json - Test Execution & Fix Cycle Task
+
+```json
+{
+  "id": "IMPL-002",
+  "title": "Execute and fix tests for [sourceSessionId]",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix",
+    "agent": "@test-fix-agent",
+    "source_session": "[sourceSessionId]",
+    "test_framework": "jest|pytest|cargo|detected",
+    "max_iterations": 5,
+    "use_codex": false  // Set to true if --use-codex flag present
+  },
+  "context": {
+    "requirements": [
+      "Execute complete test suite (generated in IMPL-001)",
+      "Diagnose test failures using Gemini analysis with bug-fix template",
+      "Present fixes to user for manual application (default)",
+      "Use Codex ONLY if user explicitly requests automation",
+      "Iterate until all tests pass or max iterations reached",
+      "Revert changes if unable to fix within iteration limit"
+    ],
+    "focus_paths": [
+      "tests/**/*",
+      "src/**/*.test.*",
+      "{implementation_files_from_source_session}"
+    ],
+    "acceptance": [
+      "All tests pass successfully (100% pass rate)",
+      "No test failures or errors in final run",
+      "Code changes are minimal and surgical",
+      "All fixes are verified through retest",
+      "Iteration logs document fix progression"
+    ],
+    "depends_on": ["IMPL-001"],
+    "source_context": {
+      "session_id": "[sourceSessionId]",
+      "test_generation_summary": ".workflow/[testSessionId]/.summaries/IMPL-001-summary.md",
+      "implementation_summaries": [
+        ".workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md"
+      ]
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_source_session_summaries",
+        "action": "Load implementation context from source session",
+        "commands": [
+          "bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
+          "bash(for f in .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md; do echo \"=== $(basename $f) ===\"&& cat \"$f\"; done)"
+        ],
+        "output_to": "implementation_context",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "discover_test_framework",
+        "action": "Identify test framework and test command",
+        "commands": [
+          "bash(jq -r '.scripts.test // \"npm test\"' package.json 2>/dev/null || echo 'pytest' || echo 'cargo test')",
+          "bash([ -f 'package.json' ] && echo 'jest/npm' || [ -f 'pytest.ini' ] && echo 'pytest' || [ -f 'Cargo.toml' ] && echo 'cargo' || echo 'unknown')"
+        ],
+        "output_to": "test_command",
+        "on_error": "fail"
+      },
+      {
+        "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(# 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(echo \"Implementation files: $impl_count, Test files: $test_count\")"
+        ],
+        "output_to": "test_coverage_analysis",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "identify_files_without_tests",
+        "action": "List implementation files that lack corresponding test files",
+        "commands": [
+          "bash(# For each changed file from source session, check if test exists)",
+          "bash(for file in [changed_files]; do test_file=$(echo $file | sed 's/\\(.*\\)\\.\\(ts\\|js\\|py\\)$/\\1.test.\\2/'); [ ! -f \"$test_file\" ] && echo \"$file\"; done)"
+        ],
+        "output_to": "files_without_tests",
+        "on_error": "skip_optional"
+      },
+      {
+        "step": "prepare_test_environment",
+        "action": "Ensure test environment is ready",
+        "commands": [
+          "bash([ -f 'package.json' ] && npm install 2>/dev/null || true)",
+          "bash([ -f 'requirements.txt' ] && pip install -q -r requirements.txt 2>/dev/null || true)"
+        ],
+        "output_to": "environment_status",
+        "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"
+        },
+        "exit_conditions": {
+          "success": "all_tests_pass",
+          "failure": "max_iterations_reached",
+          "error": "test_command_not_found"
+        }
+      },
+      "modification_points": [
+        "PHASE 1: Initial Test Execution",
+        "  1.1. Discover test command from framework detection",
+        "  1.2. Execute initial test run: bash([test_command])",
+        "  1.3. Parse test output and count failures",
+        "  1.4. If all pass → Skip to PHASE 3 (success)",
+        "  1.5. If failures → Store failure output, proceed to PHASE 2",
+        "",
+        "PHASE 2: Iterative Test-Fix-Retest Cycle (max 5 iterations)",
+        "  Note: This phase handles test failures, NOT test generation failures",
+        "  Initialize: max_iterations=5, current_iteration=0",
+        "  ",
+        "  WHILE (tests failing AND current_iteration < max_iterations):",
+        "    current_iteration++",
+        "    ",
+        "    STEP 2.1: Gemini Diagnosis (using bug-fix template)",
+        "    - Prepare diagnosis context:",
+        "      * Test failure output from previous run",
+        "      * 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 \"",
+        "      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}",
+        "               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]",
+        "             Minimal surgical fixes only - no refactoring",
+        "      \" > fix-iteration-[N]-diagnosis.md)",
+        "    - Parse diagnosis → extract fix_suggestion and target_files",
+        "    - Present fix to user for manual application (default)",
+        "    ",
+        "    STEP 2.2: Apply Fix (Based on meta.use_codex Flag)",
+        "    ",
+        "    IF meta.use_codex = false (DEFAULT):",
+        "    - Present Gemini diagnosis to user for manual fix",
+        "    - User applies fix based on diagnosis recommendations",
+        "    - Stage changes: bash(git add -A)",
+        "    - Store fix log: .process/fix-iteration-[N]-changes.log",
+        "    ",
+        "    IF meta.use_codex = true (--use-codex flag present):",
+        "    - Stage current changes (if valid git repo): bash(git add -A)",
+        "    - First iteration: Start new Codex session",
+        "      codex -C [project_root] --full-auto exec \"",
+        "      PURPOSE: Fix test failure iteration 1",
+        "      TASK: [fix_suggestion from Gemini]",
+        "      MODE: write",
+        "      CONTEXT: Diagnosis: .workflow/.process/fix-iteration-1-diagnosis.md",
+        "               Target files: [target_files]",
+        "               Implementation context: [implementation_context]",
+        "      EXPECTED: Minimal code changes to resolve test failure",
+        "      RULES: Apply ONLY suggested changes, no refactoring",
+        "             Preserve existing code style",
+        "      \" --skip-git-repo-check -s danger-full-access",
+        "    - Subsequent iterations: Resume session for context continuity",
+        "      codex exec \"",
+        "      CONTINUE TO NEXT FIX:",
+        "      Iteration [N] of 5: Fix test failure",
+        "      ",
+        "      PURPOSE: Fix remaining test failures",
+        "      TASK: [fix_suggestion from Gemini iteration N]",
+        "      CONTEXT: Previous fixes applied, diagnosis: .process/fix-iteration-[N]-diagnosis.md",
+        "      EXPECTED: Surgical fix for current failure",
+        "      RULES: Build on previous fixes, maintain consistency",
+        "      \" resume --last --skip-git-repo-check -s danger-full-access",
+        "    - Store fix log: .process/fix-iteration-[N]-changes.log",
+        "    ",
+        "    STEP 2.3: Retest and Verification",
+        "    - Re-execute test suite: bash([test_command])",
+        "    - Capture output: .process/fix-iteration-[N]-retest.log",
+        "    - Count failures: bash(grep -c 'FAIL\\|ERROR' .process/fix-iteration-[N]-retest.log)",
+        "    - Check for regression:",
+        "      IF new_failures > previous_failures:",
+        "        WARN: Regression detected",
+        "        Include in next Gemini diagnosis context",
+        "    - Analyze results:",
+        "      IF all_tests_pass:",
+        "        BREAK loop → Proceed to PHASE 3",
+        "      ELSE:",
+        "        Update test_failures context",
+        "        CONTINUE loop",
+        "  ",
+        "  IF max_iterations reached AND tests still failing:",
+        "    EXECUTE: git reset --hard HEAD (revert all changes)",
+        "    MARK: Task status = blocked",
+        "    GENERATE: Detailed failure report with iteration logs",
+        "    EXIT: Require manual intervention",
+        "",
+        "PHASE 3: Final Validation and Certification",
+        "  3.1. Execute final confirmation test run",
+        "  3.2. Generate success summary:",
+        "       - Iterations required: [current_iteration]",
+        "       - Fixes applied: [summary from iteration logs]",
+        "       - Test results: All passing ✅",
+        "  3.3. Mark task status: completed",
+        "  3.4. Update TODO_LIST.md: Mark as ✅",
+        "  3.5. Certify code: APPROVED for deployment"
+      ],
+      "logic_flow": [
+        "Load source session implementation context",
+        "Discover test framework and command",
+        "PHASE 0: Test Coverage Check",
+        "  Analyze existing test files",
+        "  Identify files without tests",
+        "  IF tests missing:",
+        "    Report to user (no automatic generation)",
+        "    Wait for user to generate tests or request automation",
+        "  ELSE:",
+        "    Skip to Phase 1",
+        "PHASE 1: Initial Test Execution",
+        "  Execute test suite",
+        "  IF all pass → Success (Phase 3)",
+        "  ELSE → Store failures, proceed to Phase 2",
+        "PHASE 2: Iterative Fix Cycle (max 5 iterations)",
+        "  LOOP (max 5 times):",
+        "    1. Gemini diagnoses failure with bug-fix template → fix suggestion",
+        "    2. Check meta.use_codex flag:",
+        "       - IF false (default): Present fix to user for manual application",
+        "       - IF true (--use-codex): Codex applies fix with resume for continuity",
+        "    3. Retest and check results",
+        "    4. IF pass → Exit loop to Phase 3",
+        "    5. ELSE → Continue with updated context",
+        "  IF max iterations → Revert + report failure",
+        "PHASE 3: Final Validation",
+        "  Confirm all tests pass",
+        "  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"
+        },
+        "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"
+        }
+      }
+    },
+    "target_files": [
+      "Auto-discovered from test failures",
+      "Extracted from Gemini diagnosis each iteration",
+      "Format: file:function:lines or file (for new files)"
+    ],
+    "codex_session": {
+      "strategy": "resume_for_continuity",
+      "first_iteration": "codex exec \"fix iteration 1\" --full-auto",
+      "subsequent_iterations": "codex exec \"fix iteration N\" resume --last",
+      "benefits": [
+        "Maintains conversation context across fixes",
+        "Remembers previous decisions and patterns",
+        "Ensures consistency in fix approach",
+        "Reduces redundant context injection"
+      ]
+    }
+  }
+}
+```
+
+### Phase 3: IMPL_PLAN.md Generation
+
+#### Document Structure
+```markdown
+---
+identifier: WFS-test-[session-id]
+source_session: WFS-[source-session-id]
+workflow_type: test_session
+test_framework: jest|pytest|cargo|detected
+---
+
+# Test Validation Plan: [Source Session Topic]
+
+## Summary
+Execute comprehensive test suite for implementation from session WFS-[source-session-id].
+Diagnose and fix all test failures using iterative Gemini analysis and Codex execution.
+
+## Source Session Context
+- **Implementation Session**: WFS-[source-session-id]
+- **Completed Tasks**: IMPL-001, IMPL-002, ...
+- **Changed Files**: [list from git log]
+- **Implementation Summaries**: [references to source session summaries]
+
+## Test Framework
+- **Detected Framework**: jest|pytest|cargo|other
+- **Test Command**: npm test|pytest|cargo test
+- **Test Files**: [discovered test files]
+- **Coverage**: [estimated test coverage]
+
+## Test-Fix-Retest Cycle
+- **Max Iterations**: 5
+- **Diagnosis Tool**: Gemini (analysis mode with bug-fix template from bug-index.md)
+- **Fix Tool**: Manual (default, meta.use_codex=false) or Codex (if --use-codex flag, meta.use_codex=true)
+- **Verification**: Bash test execution + regression check
+
+### Cycle Workflow
+1. **Initial Test**: Execute full suite, capture failures
+2. **Iterative Fix Loop** (max 5 times):
+   - Gemini diagnoses failure using bug-fix template → surgical fix suggestion
+   - Check meta.use_codex flag:
+     - If false (default): Present fix to user for manual application
+     - If true (--use-codex): Codex applies fix with resume for context continuity
+   - Retest and verify (check for regressions)
+   - Continue until all pass or max iterations reached
+3. **Final Validation**: Confirm all tests pass, certify code
+
+### Error Recovery
+- **Max iterations reached**: Revert all changes, report failure
+- **Test command fails**: Treat as test failure, diagnose with Gemini
+- **Codex fails**: Retry once, skip iteration if still failing
+- **Regression detected**: Log warning, include in next diagnosis
+
+## Task Breakdown
+- **IMPL-001**: Execute and validate tests with iterative fix cycle
+
+## Implementation Strategy
+- **Phase 1**: Initial test execution and failure capture
+- **Phase 2**: Iterative Gemini diagnosis + Codex fix + retest
+- **Phase 3**: Final validation and code certification
+
+## Success Criteria
+- All tests pass (100% pass rate)
+- No test failures or errors in final run
+- Minimal, surgical code changes
+- Iteration logs document fix progression
+- Code certified APPROVED for deployment
+```
+
+### Phase 4: TODO_LIST.md Generation
+
+```markdown
+# Tasks: Test Validation for [Source Session]
+
+## Task Progress
+- [ ] **IMPL-001**: Execute and validate tests with iterative fix cycle → [📋](./.task/IMPL-001.json)
+
+## Execution Details
+- **Source Session**: WFS-[source-session-id]
+- **Test Framework**: jest|pytest|cargo
+- **Max Iterations**: 5
+- **Tools**: Gemini diagnosis + Codex resume fixes
+
+## Status Legend
+- `- [ ]` = Pending
+- `- [x]` = Completed
+```
+
+## Output Files Structure
+```
+.workflow/WFS-test-[session]/
+├── workflow-session.json           # Test session metadata
+├── IMPL_PLAN.md                    # Test validation plan
+├── TODO_LIST.md                    # Progress tracking
+├── .task/
+│   └── IMPL-001.json               # Test-fix task with cycle spec
+├── .process/
+│   ├── ANALYSIS_RESULTS.md         # From concept-enhanced (optional)
+│   ├── context-package.json        # From context-gather
+│   ├── initial-test.log            # Phase 1: Initial test results
+│   ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
+│   ├── fix-iteration-1-changes.log  # Codex changes iteration 1
+│   ├── fix-iteration-1-retest.log   # Retest results iteration 1
+│   ├── fix-iteration-N-*.md/log    # Subsequent iterations
+│   └── final-test.log              # Phase 3: Final validation
+└── .summaries/
+    └── IMPL-001-summary.md         # Success report OR failure report
+```
+
+## Error Handling
+
+### Input Validation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Not a test session | Missing workflow_type: "test_session" | Verify session created by test-gen |
+| Source session not found | Invalid source_session_id | Check source session exists |
+| No implementation summaries | Source session incomplete | Ensure source session has completed tasks |
+
+### Test Framework Discovery Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No test command found | Unknown framework | Manual test command specification |
+| No test files found | Tests not written | Request user to write tests first |
+| Test dependencies missing | Incomplete setup | Run dependency installation |
+
+### Generation Errors
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Invalid JSON structure | Template error | Fix task generation logic |
+| Missing required fields | Incomplete metadata | Validate session metadata |
+
+## Integration & Usage
+
+### Command Chain
+- **Called By**: `/workflow:test-gen` (Phase 4)
+- **Calls**: None (terminal command)
+- **Followed By**: `/workflow:execute` (user-triggered)
+
+### Basic Usage
+```bash
+# Manual fix mode (default)
+/workflow:tools:test-task-generate --session WFS-test-auth
+
+# Automated Codex fix mode
+/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+```
+
+### Flag Behavior
+- **No flag**: `meta.use_codex=false`, manual fixes presented to user
+- **--use-codex**: `meta.use_codex=true`, Codex automatically applies fixes with resume mechanism
+
+## Related Commands
+- `/workflow:test-gen` - Creates test session and calls this tool
+- `/workflow:tools:context-gather` - Provides cross-session context
+- `/workflow:tools:concept-enhanced` - Provides test strategy analysis
+- `/workflow:execute` - Executes the generated test-fix task
+- `@test-fix-agent` - Agent that executes the iterative test-fix cycle
+
+## Agent Execution Notes
+
+The `@test-fix-agent` will execute the task by following the `flow_control.implementation_approach` specification:
+
+1. **Load task JSON**: Read complete test-fix task from `.task/IMPL-002.json`
+2. **Check meta.use_codex**: Determine fix mode (manual or automated)
+3. **Execute pre_analysis**: Load source context, discover framework, analyze tests
+4. **Phase 1**: Run initial test suite
+5. **Phase 2**: If failures, enter iterative loop:
+   - Use Gemini for diagnosis (analysis mode with bug-fix template)
+   - Check meta.use_codex flag:
+     - If false (default): Present fix suggestions to user for manual application
+     - If true (--use-codex): Use Codex resume for automated fixes (maintains context)
+   - Retest and check for regressions
+   - Repeat max 5 times
+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.
+
+**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/consolidate.md

@@ -0,0 +1,419 @@
+---
+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

@@ -0,0 +1,331 @@
+---
+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"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
+---
+
+# UI Design Auto Workflow Command
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Executes all design phases sequentially from style extraction to design integration, with optional batch planning.
+
+**Unified Target System**: Generates `style_variants × layout_variants × targets` prototypes, where targets can be:
+- **Pages** (full-page layouts): home, dashboard, settings, etc.
+- **Components** (isolated UI elements): navbar, card, hero, form, etc.
+- **Mixed**: Can combine both in a single workflow
+
+**Autonomous Flow**:
+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
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon completion, coordinator constructs next command and executes immediately. No user intervention required.
+
+**Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+2. **No Preliminary Validation**: Sub-commands handle their own validation
+3. **Parse & Pass**: Extract data from each output for next phase
+4. **Default to All**: When selecting variants/prototypes, use ALL generated items
+5. **Track Progress**: Update TodoWrite after each phase
+
+## Parameter Requirements
+
+**Optional Parameters** (all have smart defaults):
+- `--targets "<list>"`: Comma-separated targets (pages/components) to generate (inferred from prompt/session if omitted)
+- `--target-type "page|component|auto"`: Explicitly set target type (default: `auto` - intelligent detection)
+- `--session <id>`: Workflow session ID (standalone mode if omitted)
+- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
+- `--prompt "<description>"`: Design style and target description
+- `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
+- `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
+- `--batch-plan`: Auto-generate implementation tasks after design-update
+
+**Legacy Parameters** (maintained for backward compatibility):
+- `--pages "<list>"`: Alias for `--targets` with `--target-type page`
+- `--components "<list>"`: Alias for `--targets` with `--target-type component`
+
+**Input Rules**:
+- Must provide at least one: `--images` or `--prompt` or `--targets`
+- Multiple parameters can be combined for guided analysis
+- If `--targets` not provided, intelligently inferred from prompt/session
+
+**Supported Target Types**:
+- **Pages** (full layouts): home, dashboard, settings, profile, login, etc.
+- **Components** (UI elements):
+  - Navigation: navbar, header, menu, breadcrumb, tabs, sidebar
+  - Content: hero, card, list, table, grid, timeline
+  - Input: form, search, filter, input-group
+  - Feedback: modal, alert, toast, badge, progress
+  - Media: gallery, carousel, video-player, image-card
+  - Other: footer, pagination, dropdown, tooltip, avatar
+
+**Intelligent Prompt Parsing**: Extracts variant counts from natural language:
+- "Generate **3 style variants**" → `--style-variants 3`
+- "**2 layout options**" → `--layout-variants 2`
+- "Create **4 styles** with **2 layouts each**" → `--style-variants 4 --layout-variants 2`
+- Explicit flags override prompt inference
+
+## Execution Modes
+
+**Matrix Mode** (unified):
+- Generates `style_variants × layout_variants × targets` prototypes
+- **Phase 1**: `style_variants` style options (extract)
+- **Phase 2**: `style_variants` independent design systems (consolidate)
+- **Phase 3**: Layout planning + UI generation (generate)
+  - Sub-phase 1: `targets × layout_variants` target-specific layout plans
+  - Sub-phase 2: `layout_variants × targets` HTML/CSS templates
+  - Sub-phase 3: `style_variants × layout_variants × targets` final prototypes
+  - 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
+
+## 6-Phase Execution
+
+### Phase 0a: Intelligent Prompt Parsing
+```bash
+# Parse variant counts from prompt or use explicit/default values
+IF --prompt AND (NOT --style-variants OR NOT --layout-variants):
+    style_variants = regex_extract(prompt, r"(\d+)\s*style") OR --style-variants OR 3
+    layout_variants = regex_extract(prompt, r"(\d+)\s*layout") OR --layout-variants OR 3
+ELSE:
+    style_variants = --style-variants OR 3
+    layout_variants = --layout-variants OR 3
+
+VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+```
+
+### Phase 0b: Run Initialization & Directory Setup
+```bash
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "workflow": "ui-design:auto",
+  "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
+                  "targets": "${inferred_target_list}", "target_type": "${target_type}",
+                  "prompt": "${prompt_text}", "images": "${images_pattern}" },
+  "status": "in_progress"
+}
+```
+
+### Phase 0c: Unified Target Inference with Intelligent Type Detection
+```bash
+# Priority: --pages/--components (legacy) → --targets → --prompt analysis → synthesis → default
+target_list = []; target_type = "auto"; target_source = "none"
+
+# Step 1-2: Explicit parameters (legacy or unified)
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --components: target_list = split(--components); target_type = "component"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets); target_source = "explicit"
+    target_type = --target-type != "auto" ? --target-type : detect_target_type(target_list)
+
+# Step 3: Prompt analysis (Claude internal analysis)
+ELSE IF --prompt:
+    analysis_result = analyze_prompt("{prompt_text}")  # Extract targets, types, purpose
+    target_list = analysis_result.targets
+    target_type = analysis_result.primary_type OR detect_target_type(target_list)
+    target_source = "prompt_analysis"
+
+# Step 4: Session synthesis
+ELSE IF --session AND exists(synthesis-specification.md):
+    target_list = extract_targets_from_synthesis(); target_type = "page"; target_source = "synthesis"
+
+# Step 5: Fallback
+IF NOT target_list: target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [normalize(t) for t in target_list if is_valid(t)]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+IF --target-type != "auto": target_type = --target-type
+
+# Interactive confirmation
+DISPLAY_CONFIRMATION(target_type, target_source, validated_targets):
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  "{emoji} {LABEL} CONFIRMATION"
+  "Type: {target_type} | Source: {target_source}"
+  "Targets ({count}): {', '.join(validated_targets)}"
+  "Options: 'continue/yes' | 'targets: a,b' | 'skip: x' | 'add: y' | 'type: page|component'"
+  "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+user_input = WAIT_FOR_USER_INPUT()
+
+# Process user modifications
+MATCH user_input:
+  "continue|yes|ok" → proceed
+  "targets: ..." → validated_targets = parse_new_list()
+  "skip: ..." → validated_targets = remove_items()
+  "add: ..." → validated_targets = add_items()
+  "type: ..." → target_type = extract_type()
+  default → proceed with current list
+
+STORE: inferred_target_list, target_type, target_inference_source
+```
+
+**Helper Function: detect_target_type()**
+```bash
+detect_target_type(target_list):
+    page_keywords = ["home", "dashboard", "settings", "profile", "login", "signup", "auth", ...]
+    component_keywords = ["navbar", "header", "footer", "hero", "card", "button", "form", ...]
+
+    page_matches = count_matches(target_list, page_keywords + ["page", "screen", "view"])
+    component_matches = count_matches(target_list, component_keywords + ["component", "widget"])
+
+    RETURN "component" IF component_matches > page_matches ELSE "page"
+```
+
+### Phase 1: Style Extraction
+```bash
+command = "/workflow:ui-design:extract --base-path \"{base_path}\" " +
+          (--images ? "--images \"{images}\" " : "") +
+          (--prompt ? "--prompt \"{prompt}\" " : "") +
+          "--variants {style_variants}"
+SlashCommand(command)  # → Phase 2
+```
+
+### Phase 2: Style Consolidation
+```bash
+command = "/workflow:ui-design:consolidate --base-path \"{base_path}\" " +
+          "--variants {style_variants}"
+SlashCommand(command)  # → Phase 3
+# Output: style_variants independent design systems (design tokens and style guides)
+```
+
+### Phase 3: Matrix UI Generation (with Layout Planning)
+```bash
+targets_string = ",".join(inferred_target_list)
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
+          "--targets \"{targets_string}\" --target-type \"{target_type}\" " +
+          "--style-variants {style_variants} --layout-variants {layout_variants}"
+
+total = style_variants × layout_variants × len(inferred_target_list)
+REPORT: "🚀 Phase 3: {type_icon} {targets_string} | Matrix: {s}×{l} | Total: {total} prototypes"
+REPORT: "   → Layout planning: {len(inferred_target_list)}×{layout_variants} target-specific layouts"
+
+SlashCommand(command)  # → Phase 4
+# Output:
+# - {target}-layout-{l}.json (target-specific layout plans)
+# - {target}-style-{s}-layout-{l}.html (final prototypes)
+# - compare.html (matrix view)
+```
+
+### Phase 4: Design System Integration
+```bash
+command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
+SlashCommand(command)  # → Phase 5 if --batch-plan, else complete
+```
+
+### Phase 5: Batch Task Generation (Optional)
+```bash
+IF --batch-plan:
+    FOR target IN inferred_target_list:
+        task_desc = "Implement {target} {target_type} based on design system"
+        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
+```
+
+## TodoWrite Pattern
+```javascript
+TodoWrite({todos: [
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
+  {"content": "Execute style consolidation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute UI generation", "status": "pending", "activeForm": "Executing..."},
+  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
+]})
+// Update after each phase: current → completed, next → in_progress
+```
+
+## Key Features
+- **Autonomous**: No user intervention required between phases
+- **Intelligent**: Parses natural language, infers targets/types
+- **Reproducible**: Deterministic flow with isolated run directories
+- **Flexible**: Supports pages, components, or mixed targets
+
+## Examples
+
+### 1. Page Mode (Prompt Inference)
+```bash
+/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
+# Result: 27 prototypes (3×3×3 - inferred defaults)
+```
+
+### 2. Custom Matrix with Session
+```bash
+/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
+# Result: 2×2×N prototypes (targets from synthesis)
+```
+
+### 3. Component Mode
+```bash
+/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --style-variants 3 --layout-variants 2
+# Result: 12 prototypes (3×2×2 components with minimal wrapper)
+```
+
+### 4. Intelligent Parsing + Batch Planning
+```bash
+/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for dashboard and settings" --batch-plan
+# Result: 16 prototypes (4×2×2) + auto-generated implementation tasks
+```
+
+### 5. Legacy Support
+```bash
+/workflow:ui-design:explore-auto --pages "home,dashboard,settings"
+# Equivalent to: --targets "home,dashboard,settings" --target-type "page"
+```
+
+## Completion Output
+```
+✅ UI Design Explore-Auto Workflow Complete!
+
+Run ID: {run_id} | Session: {session_id or "standalone"}
+Type: {icon} {target_type} | Matrix: {s}×{l} ({total} prototypes)
+
+Phase 1: {s} style variants (extract)
+Phase 2: {s} design systems (consolidate)
+Phase 3: Layout planning + generation (generate)
+  - {n}×{l} target-specific layout plans
+  - {l}×{n} HTML/CSS templates
+  - {s}×{l}×{n} = {total} final prototypes
+Phase 4: Brainstorming artifacts updated
+[Phase 5: {n} implementation tasks created]  # if --batch-plan
+
+📂 {base_path}/
+  ├── style-consolidation/  ({s} design systems)
+  ├── prototypes/
+  │   ├── _templates/       ({n}×{l} layout JSON + {l}×{n} HTML/CSS)
+  │   └── ...               ({total} final prototypes)
+  └── .run-metadata.json
+
+🌐 Preview: {base_path}/prototypes/compare.html
+  - Interactive {s}×{l} matrix view
+  - Side-by-side comparison
+  - Target-specific layouts per prototype
+
+{icon} Targets: {', '.join(targets)} (type: {target_type})
+  - Each target has {l} custom-designed layouts
+  - Layout plans stored as structured JSON
+
+Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+```

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

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

@@ -0,0 +1,836 @@
+---
+name: generate
+description: Generate UI prototypes in matrix mode (style × layout combinations) for pages or components
+usage: /workflow:ui-design:generate [--targets "<list>"] [--target-type "page|component"] [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+argument-hint: "[--targets \"dashboard,auth,navbar,hero\"] [--target-type \"page\"] [--base-path \".workflow/WFS-xxx/design-run-xxx\"] [--style-variants 3] [--layout-variants 3]"
+parameters:
+  - name: --style-variants
+    type: number
+    default: 3
+    description: "Number of style variants to generate prototypes for (1-5). Auto-validates against actual style-* directories. ⚠️ Recommend omitting to use auto-detection."
+  - name: --layout-variants
+    type: number
+    default: auto-detected from layout-strategies.json
+    description: "Number of layout variants. Default: loaded from consolidation output. Can override for manual testing."
+  - name: --targets
+    type: string
+    description: "Comma-separated list of targets (pages or components) to generate"
+  - name: --target-type
+    type: string
+    default: page
+    description: "Type of targets: 'page' (full layout) or 'component' (isolated element)"
+examples:
+  - /workflow:ui-design:generate --base-path ".workflow/WFS-auth/design-run-20250109-143022" --targets "dashboard,settings" --target-type "page" --style-variants 3 --layout-variants 3
+  - /workflow:ui-design:generate --session WFS-auth --targets "home,pricing" --target-type "page" --style-variants 2 --layout-variants 2
+  - /workflow:ui-design:generate --base-path "./.workflow/.design/run-20250109-150533"  # ✅ Recommended: auto-detect variants
+  - /workflow:ui-design:generate --targets "navbar,hero,card" --target-type "component" --style-variants 3 --layout-variants 2
+  - /workflow:ui-design:generate --pages "home,dashboard" --style-variants 2 --layout-variants 2  # Legacy syntax
+executor: → @ui-design-agent
+allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
+---
+
+# UI Generation Command (Matrix Mode)
+
+**Executor**: → @ui-design-agent
+**Parallel Generation**: Phase 2a → @ui-design-agent (L×T tasks)
+
+## Overview
+Generate production-ready UI prototypes (HTML/CSS) in `style × layout` matrix mode, strictly adhering to consolidated design tokens from separate style design systems. Supports both full-page layouts and isolated component generation.
+
+## Core Philosophy
+- **Unified Generation**: Single mode generating `style_variants × layout_variants × targets` prototypes
+- **Target Types**: Supports pages (full layouts) and components (isolated UI elements)
+- **Agent-Driven**: Uses `Task(ui-design-agent)` for parallel generation
+- **Token-Driven**: All styles reference per-style design-tokens.json; no hardcoded values
+- **Production-Ready**: Semantic HTML5, ARIA attributes, responsive design
+- **Template-Based**: Decouples HTML structure from CSS styling for optimal performance
+- **Adaptive Wrapper**: Full-page structure for pages, minimal wrapper for components
+
+## Execution Protocol
+
+### Phase 1: Path Resolution & Context Loading
+
+```bash
+# 1. Determine base path
+IF --base-path: base_path = {provided_base_path}
+ELSE IF --session: base_path = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+ELSE: base_path = find_latest_path_matching(".workflow/.design/*")
+
+# 2. Determine style variant count and layout variant count
+style_variants = --style-variants OR 3; VALIDATE: 1 <= style_variants <= 5
+layout_variants = --layout-variants OR 3; VALIDATE: 1 <= layout_variants <= 5
+
+# Validate against actual style directories
+actual_style_count = count_directories({base_path}/style-consolidation/style-*)
+
+IF actual_style_count == 0:
+    ERROR: "No style directories found"; SUGGEST: "Run /workflow:ui-design:consolidate first"; EXIT 1
+
+IF style_variants > actual_style_count:
+    WARN: "⚠️ Requested {style_variants}, but only {actual_style_count} exist"
+    REPORT: "   Available styles: {list_directories}"; style_variants = actual_style_count
+
+REPORT: "✅ Validated style variants: {style_variants}"
+
+# 3. Enhanced target list parsing with type detection
+target_list = []; target_type = "page"  # Default
+
+# Priority 1: Unified --targets parameter
+IF --targets:
+    raw_targets = {--targets value}
+    target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
+    target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
+
+    target_type = --target-type provided ? {--target-type} : detect_target_type(target_list)
+    REPORT: "🎯 Using provided targets ({target_type}): {', '.join(target_list)}"
+
+# Priority 2: Legacy --pages parameter
+ELSE IF --pages:
+    raw_targets = {--pages value}
+    target_list = split_and_clean(raw_targets, delimiters=[",", ";", "、"])
+    target_list = [t.strip().lower().replace(" ", "-") for t in target_list if t.strip()]
+    target_type = "page"
+    REPORT: "📋 Using provided pages (legacy): {', '.join(target_list)}"
+
+# Priority 3: Extract from synthesis-specification.md
+ELSE IF --session:
+    synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+    target_list = extract_targets_from_synthesis(synthesis_spec); target_type = "page"
+    REPORT: "📋 Extracted from synthesis: {', '.join(target_list)}"
+
+# Priority 4: Detect from existing prototypes or default
+ELSE:
+    target_list = detect_from_prototypes({base_path}/prototypes/) OR ["home"]; target_type = "page"
+    REPORT: "📋 Detected/default targets: {', '.join(target_list)}"
+
+# 4. Validate target names
+validated_targets = [t for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
+invalid_targets = [t for t in target_list if t not in validated_targets]
+
+IF invalid_targets: REPORT: "⚠️ Skipped invalid target names: {', '.join(invalid_targets)}"
+VALIDATE: validated_targets not empty, "No valid targets found"
+target_list = validated_targets
+
+STORE: target_list, target_type
+
+# 5. Verify design systems exist
+FOR style_id IN range(1, style_variants + 1):
+    VERIFY: exists({base_path}/style-consolidation/style-{style_id}/design-tokens.json)
+    VERIFY: exists({base_path}/style-consolidation/style-{style_id}/style-guide.md)
+
+# 6. Load requirements (if integrated mode)
+IF --session: synthesis_spec = Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)
+```
+
+### Phase 1.5: Target-Specific Layout Planning
+
+```bash
+REPORT: "📐 Planning {layout_variants} layout strategies for each target..."
+
+CREATE: {base_path}/prototypes/_templates/
+
+# For each target, plan its specific layouts
+FOR target IN target_list:
+    REPORT: "  Planning layouts for '{target}' ({target_type})..."
+
+    FOR layout_id IN range(1, layout_variants + 1):
+        Task(ui-design-agent): "
+          [TARGET_LAYOUT_PLANNING]
+
+          Generate a concrete, actionable layout plan for a specific target and WRITE it to the file system.
+
+          ## Context
+          TARGET: {target}
+          TARGET_TYPE: {target_type}
+          LAYOUT_ID: {layout_id}
+          BASE_PATH: {base_path}
+          {IF --session: PROJECT_REQUIREMENTS: Read(.workflow/WFS-{session}/.brainstorming/synthesis-specification.md)}
+
+          ## Task
+          Research, design, and WRITE a modern, innovative layout plan specifically for '{target}'.
+
+          ## Research Phase (Use MCP Tools)
+          1. Search for modern {target_type} layout patterns:
+             mcp__exa__get_code_context_exa(
+               query=\"modern {target} {target_type} layout design patterns 2024 2025\",
+               tokensNum=\"dynamic\"
+             )
+          2. Search for {target}-specific UI best practices
+
+          ## Layout Planning Rules
+
+          **For PAGES (target_type='page')**:
+          - Define macro-layout: main regions (header, sidebar, main, footer)
+          - Specify grid/flexbox structure for content organization
+          - Define responsive breakpoints and behavior
+          - Include navigation and page-level components
+
+          **For COMPONENTS (target_type='component')**:
+          - Define micro-layout: internal element arrangement
+          - Specify alignment, spacing, and element sizing
+          - Focus on component-specific structure (no header/footer)
+          - Optimize for reusability and composition
+
+          ## File Write Instructions
+          Generate layout plan JSON and WRITE it using Write() tool:
+
+          **Path**: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.json
+
+          **Content** - JSON with this EXACT structure:
+          ```json
+          {
+            \"id\": \"layout-{layout_id}\",
+            \"target\": \"{target}\",
+            \"target_type\": \"{target_type}\",
+            \"name\": \"Descriptive name (2-4 words)\",
+            \"description\": \"Detailed description (2-3 sentences explaining structure, use cases, and unique aspects)\",
+            \"structure\": {
+              // For pages, include:
+              \"type\": \"sidebar-main\" | \"centered\" | \"asymmetric\" | \"grid-dashboard\",
+              \"regions\": [\"header\", \"sidebar\", \"main\", \"footer\"],
+              \"grid\": {
+                \"columns\": 12,
+                \"rows\": \"auto\",
+                \"gap\": \"var(--spacing-6)\"
+              },
+              \"sidebar\": {
+                \"position\": \"left\" | \"right\",
+                \"width\": \"250px\",
+                \"fixed\": true,
+                \"collapsible\": true
+              },
+              \"responsive\": {
+                \"mobile\": {\"columns\": 1, \"sidebar\": \"hidden\"},
+                \"tablet\": {\"columns\": 6, \"sidebar\": \"overlay\"},
+                \"desktop\": {\"columns\": 12, \"sidebar\": \"fixed\"}
+              },
+
+              // For components, include:
+              \"arrangement\": \"flex-column\" | \"flex-row\" | \"grid\",
+              \"alignment\": \"center\" | \"start\" | \"end\" | \"stretch\",
+              \"spacing\": \"compact\" | \"normal\" | \"relaxed\",
+              \"element_order\": [\"icon\", \"title\", \"description\", \"action\"]
+            },
+            \"semantic_hints\": [
+              \"dashboard\",
+              \"data-visualization\",
+              \"navigation-sidebar\",
+              \"card-based\"
+            ],
+            \"accessibility_features\": [
+              \"skip-navigation\",
+              \"landmark-regions\",
+              \"keyboard-navigation\",
+              \"screen-reader-optimized\"
+            ],
+            \"research_references\": [
+              \"URL or description of research source 1\",
+              \"URL or description of research source 2\"
+            ]
+          }
+          ```
+
+          ## Write Operation Instructions
+          - Use Write() tool with the absolute path provided above
+          - Create directory if needed: Bash('mkdir -p {base_path}/prototypes/_templates')
+          - Verify write operation succeeds
+
+          ## Example Write Operation
+          ```javascript
+          Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json\", JSON.stringify(layout_plan, null, 2))
+          ```
+
+          ## Completion
+          Report successful file creation with path confirmation.
+
+          ## Critical Requirements
+          - ✅ Layout plan is ONLY for '{target}' - tailor to this specific target's needs
+          - ✅ Consider {target_type} type (page vs component) when designing structure
+          - ✅ Research modern patterns using MCP tools before designing
+          - ✅ Provide concrete, implementable structure (not abstract descriptions)
+          - ✅ Different layout IDs should explore meaningfully different approaches
+          - ✅ Use semantic naming and clear documentation
+          - ✅ Write file directly using Write() tool - do NOT return contents as text
+        "
+
+# Wait for all agent tasks to complete
+REPORT: "⏳ Waiting for layout planning agents to complete..."
+
+# Verify agent created layout JSON files
+REPORT: "📝 Verifying agent file creation..."
+
+FOR target IN target_list:
+    FOR layout_id IN range(1, layout_variants + 1):
+        layout_json_label = f"{target}-layout-{layout_id}.json"
+        json_path = f"{base_path}/prototypes/_templates/{layout_json_label}"
+
+        # Verify file exists
+        VERIFY: exists(json_path), f"Layout JSON not created by agent: {layout_json_label}"
+
+        # Validate JSON structure
+        TRY:
+            layout_json_content = Read(json_path)
+            layout_plan = JSON.parse(layout_json_content)
+
+            # Validate required fields
+            VALIDATE: layout_plan.id == f"layout-{layout_id}", f"Invalid layout ID in {layout_json_label}"
+            VALIDATE: layout_plan.target == target, f"Invalid target in {layout_json_label}"
+            VALIDATE: layout_plan.target_type == target_type, f"Invalid target_type in {layout_json_label}"
+            VALIDATE: layout_plan.name exists, f"Missing 'name' field in {layout_json_label}"
+            VALIDATE: layout_plan.structure exists, f"Missing 'structure' field in {layout_json_label}"
+
+            file_size = get_file_size(json_path)
+            REPORT: f"   ✓ Verified: {layout_json_label} - {layout_plan.name} ({file_size} KB)"
+        CATCH error:
+            ERROR: f"Validation failed for {layout_json_label}: {error}"
+            REPORT: f"   ⚠️ File exists but validation failed - review agent output"
+
+REPORT: f"✅ Phase 1.5 complete: Verified {len(target_list) × layout_variants} target-specific layout files"
+```
+
+### Phase 1.6: Token Variable Name Extraction
+
+```bash
+REPORT: "📋 Extracting design token variable names..."
+tokens_json_path = "{base_path}/style-consolidation/style-1/design-tokens.json"
+VERIFY: exists(tokens_json_path), "Design tokens not found. Run /workflow:ui-design:consolidate first."
+
+design_tokens = Read(tokens_json_path)
+
+# Extract all available token categories and variable names
+token_reference = {
+  "colors": {"brand": list(keys), "surface": list(keys), "semantic": list(keys), "text": list(keys), "border": list(keys)},
+  "typography": {"font_family": list(keys), "font_size": list(keys), "font_weight": list(keys), "line_height": list(keys), "letter_spacing": list(keys)},
+  "spacing": list(keys), "border_radius": list(keys), "shadows": list(keys), "breakpoints": list(keys)
+}
+
+# Generate complete variable name lists for Agent prompt
+color_vars = []; FOR category, keys: FOR key: color_vars.append(f"--color-{category}-{key}")
+typography_vars = []; FOR category, keys: FOR key: typography_vars.append(f"--{category.replace('_', '-')}-{key}")
+spacing_vars = [f"--spacing-{key}" for key in token_reference.spacing]
+radius_vars = [f"--border-radius-{key}" for key in token_reference.border_radius]
+shadow_vars = [f"--shadow-{key}" for key in token_reference.shadows]
+breakpoint_vars = [f"--breakpoint-{key}" for key in token_reference.breakpoints]
+
+all_token_vars = color_vars + typography_vars + spacing_vars + radius_vars + shadow_vars + breakpoint_vars
+
+REPORT: f"✅ Extracted {len(all_token_vars)} design token variables from design-tokens.json"
+```
+
+### Phase 2: Optimized Matrix UI Generation
+
+**Strategy**: Two-layer generation reduces complexity from `O(S×L×T)` to `O(L×T)`, achieving **`S` times faster** performance.
+
+- **Layer 1**: Generate `L × T` layout templates (HTML structure + structural CSS) by agent
+- **Layer 2**: Instantiate `S × L × T` final prototypes via fast file operations
+
+#### Phase 2a: Layout Template Generation
+
+**Parallel Executor**: → @ui-design-agent
+
+```bash
+CREATE: {base_path}/prototypes/_templates/
+CREATE: {base_path}/prototypes/
+
+# Launch parallel template generation tasks → @ui-design-agent
+# Total agent tasks: layout_variants × len(target_list)
+FOR layout_id IN range(1, layout_variants + 1):
+    FOR target IN target_list:
+        # Read the target-specific layout plan
+        layout_json_path = f"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.json"
+        layout_plan = Read(layout_json_path)
+
+        Task(ui-design-agent): "
+          [UI_LAYOUT_TEMPLATE_GENERATION]
+
+          🚨 **CRITICAL: TARGET INDEPENDENCE REQUIREMENT** 🚨
+          You are generating a template for EXACTLY ONE target: '{target}'.
+          - Do NOT include content from other targets in the workflow
+          - This template is for '{target}' ONLY - treat it as a standalone UI entity
+          - Even if '{target}' might coexist with other targets in a final application,
+            your task is to create an INDEPENDENT, REUSABLE template for '{target}' alone
+
+          Generate a **style-agnostic** layout template for a specific {target_type} and layout strategy.
+
+          🎯 **CRITICAL REQUIREMENTS**:
+          ✅ **ADAPTIVE**: Multi-device responsive design (mobile, tablet, desktop)
+          ✅ **STYLE-SWITCHABLE**: Support runtime theme/style switching via CSS variables
+          ✅ **TOKEN-DRIVEN**: 100% CSS variable usage, zero hardcoded values
+          ✅ **INDEPENDENT**: Template for '{target}' only, no other targets included
+          ✅ **RESEARCH-INFORMED**: Use MCP tools to research modern UI patterns as needed
+
+          ## Context
+          LAYOUT_ID: {layout_id} | TARGET: {target} | TARGET_TYPE: {target_type}
+          BASE_PATH: {base_path}
+          {IF --session: Requirements: .workflow/WFS-{session}/.brainstorming/synthesis-specification.md}
+
+          **Target Type Details**:
+          {IF target_type == "page":
+            - Type: Full-page layout | Wrapper: Complete HTML document (<html>, <head>, <body>)
+            - Navigation: Include header/navigation | Footer: Include page footer
+            - Content: Complete page content structure
+          }
+          {ELSE IF target_type == "component":
+            - Type: Isolated UI component | Wrapper: Minimal container for demonstration
+            - Navigation: Exclude header/footer | Container: Simple wrapper (e.g., <div class=\"component-container\">)
+            - Content: Focus solely on component design
+          }
+
+          ## Task
+          Generate TWO files that work together as a reusable template.
+
+          ### File 1: HTML Template (`{target}-layout-{layout_id}.html`)
+
+          **Structure Requirements**:
+          - Semantic HTML5 elements with ARIA attributes
+          - Complete {target_type} wrapper (full document for pages, minimal for components)
+          - Zero hardcoded styles, colors, or spacing
+          - Responsive structure ready for mobile/tablet/desktop
+
+          **⚠️ CRITICAL: CSS Placeholder Links**
+
+          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 script handles this
+          4. DO NOT add any other CSS `<link>` tags
+          5. These enable runtime style switching for all variants
+
+          **Complete HTML Template Examples**:
+
+          {IF target_type == \"page\":
+          ```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 {layout_id}</title>
+            <link rel=\"stylesheet\" href=\"{{STRUCTURAL_CSS}}\">
+            <link rel=\"stylesheet\" href=\"{{TOKEN_CSS}}\">
+          </head>
+          <body>
+            <header><nav aria-label=\"Main navigation\"><!-- Nav content --></nav></header>
+            <main><!-- Page content --></main>
+            <footer><!-- Footer content --></footer>
+          </body>
+          </html>
+          ```
+          }
+
+          {ELSE IF target_type == \"component\":
+          ```html
+          <!DOCTYPE html>
+          <html lang=\"en\">
+          <head>
+            <meta charset=\"UTF-8\">
+            <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">
+            <title>{target} Component - Layout {layout_id}</title>
+            <link rel=\"stylesheet\" href=\"{{STRUCTURAL_CSS}}\">
+            <link rel=\"stylesheet\" href=\"{{TOKEN_CSS}}\">
+          </head>
+          <body>
+            <div class=\"component-container\">
+              <!-- Component content only -->
+            </div>
+          </body>
+          </html>
+          ```
+          }
+
+          ### File 2: CSS Template (`{target}-layout-{layout_id}.css`)
+          - 🎨 **TOKEN-DRIVEN STYLING**: ALL values use `var()` for dynamic theme switching
+          - 🔄 **RUNTIME SWITCHABLE**: `background-color: var(--color-surface-background);`
+          - 🚫 **ZERO LITERALS**: NO hardcoded values (#4F46E5, 16px, Arial)
+          - 📐 **SEMANTIC NAMING**: BEM or descriptive class naming
+          - 📱 **MOBILE-FIRST**: Responsive design using token-based breakpoints
+          - {IF target_type == "component": "Focus styles on component only, minimal global styles"}
+
+          ## Layout Plan (Target-Specific)
+          Implement the following pre-defined layout plan for this target:
+
+          **Layout JSON Path**: {layout_json_path}
+          **Layout Plan**:
+          ```json
+          {JSON.stringify(layout_plan, null, 2)}
+          ```
+
+          **Critical**: Your job is to IMPLEMENT this exact layout plan, not to redesign it.
+          - Follow the structure defined in the 'structure' field
+          - Use semantic hints for appropriate HTML elements
+          - Respect the target_type (page vs component) wrapper requirements
+          - Apply the specified responsive behavior
+
+          ## Token Usage Requirements (STRICT - USE EXACT NAMES)
+
+          **CRITICAL**: You MUST use ONLY the variable names listed below.
+          DO NOT invent variable names like --color-background-base, --radius-md, --transition-base, etc.
+
+          **Available Variables** ({len(all_token_vars)} total):
+          - Color variables ({len(color_vars)}): --color-brand-primary, --color-surface-background, --color-text-primary, etc.
+          - Typography variables ({len(typography_vars)}): --font-family-heading, --font-size-base, --font-weight-bold, etc.
+          - Spacing variables ({len(spacing_vars)}): --spacing-0, --spacing-1, ..., --spacing-24
+          - Border radius ({len(radius_vars)}): --border-radius-none, --border-radius-sm, ..., --border-radius-full
+          - Shadows ({len(shadow_vars)}): --shadow-sm, --shadow-md, --shadow-lg, --shadow-xl
+          - Breakpoints ({len(breakpoint_vars)}): --breakpoint-sm, --breakpoint-md, --breakpoint-lg, etc.
+
+          **STRICT RULES**:
+          1. Use ONLY the variables listed above - NO custom variable names
+          2. If you need a value not in the list, use the closest semantic match
+          3. For missing tokens (like transitions), use literal CSS values: `transition: all 0.2s ease;`
+          4. NO hardcoded colors, fonts, or spacing (e.g., #4F46E5, 16px, Arial)
+          5. All `var()` references must match exact variable names above
+
+          ## File Write Instructions
+          Generate TWO template files and WRITE them using Write() tool:
+
+          ### File 1: HTML Template
+          **Path**: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.html
+          **Content**: Reusable HTML structure with CSS placeholders
+
+          ### File 2: CSS Template
+          **Path**: {base_path}/prototypes/_templates/{target}-layout-{layout_id}.css
+          **Content**: Structural CSS using var() for all values
+
+          ## Write Operation Instructions
+          - Use Write() tool for both files with absolute paths provided above
+          - Create directory if needed: Bash('mkdir -p {base_path}/prototypes/_templates')
+          - Verify each write operation succeeds
+
+          ## Example Write Operations
+          ```javascript
+          Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.html\", html_content)
+          Write(\"{base_path}/prototypes/_templates/{target}-layout-{layout_id}.css\", css_content)
+          ```
+
+          ## Completion
+          Report successful file creation for both HTML and CSS templates with path confirmation.
+
+          🎯 **CRITICAL QUALITY GATES**:
+          ✅ **ADAPTIVE**: Works on mobile (375px), tablet (768px), desktop (1024px+)
+          ✅ **STYLE-SWITCHABLE**: Change {{TOKEN_CSS}} link → instant theme switching
+          ✅ **TOKEN-ONLY**: 100% var() usage, inspectable with \"Search for: #|px|rem\" → 0 matches in values
+          ✅ **REUSABLE**: Same HTML/CSS structure works for ALL style variants
+          ✅ **FILE-WRITTEN**: Files written directly to file system, not returned as text
+
+          **Wrapper Strategy**:
+          {IF target_type == "page": Use complete HTML document structure with navigation and footer.}
+          {ELSE: Use minimal wrapper with component container only.}
+
+          DO NOT return file contents as text - write them directly using Write() tool.
+        "
+
+REPORT: "⏳ Phase 2a: Waiting for agents to complete template generation..."
+```
+
+#### Phase 2a.5: Verify Agent Template File Creation
+
+```bash
+REPORT: "📝 Phase 2a.5: Verifying agent template file creation..."
+
+# Verify each agent created template files
+FOR layout_id IN range(1, layout_variants + 1):
+    FOR target IN target_list:
+        html_label = f"{target}-layout-{layout_id}.html"
+        css_label = f"{target}-layout-{layout_id}.css"
+
+        html_path = f"{base_path}/prototypes/_templates/{html_label}"
+        css_path = f"{base_path}/prototypes/_templates/{css_label}"
+
+        # Verify files exist
+        VERIFY: exists(html_path), f"HTML template not created by agent: {html_label}"
+        VERIFY: exists(css_path), f"CSS template not created by agent: {css_label}"
+
+        # Validate content
+        TRY:
+            html_content = Read(html_path)
+            css_content = Read(css_path)
+
+            # Basic validation checks
+            VALIDATE: len(html_content) > 100, f"HTML template too short: {html_label}"
+            VALIDATE: len(css_content) > 50, f"CSS template too short: {css_label}"
+            VALIDATE: "<!DOCTYPE html>" in html_content OR "<div" in html_content, f"Invalid HTML structure: {html_label}"
+            VALIDATE: "var(--" in css_content, f"Missing CSS variables: {css_label}"
+
+            html_size = get_file_size(html_path)
+            css_size = get_file_size(css_path)
+            REPORT: f"   ✓ Verified: {html_label} ({html_size} KB) + {css_label} ({css_size} KB)"
+        CATCH error:
+            ERROR: f"Validation failed for {target}-layout-{layout_id}: {error}"
+            REPORT: f"   ⚠️ Files exist but validation failed - review agent output"
+
+REPORT: "✅ Phase 2a.5 complete: Verified {layout_variants * len(target_list) * 2} template files"
+```
+
+#### Phase 2b: Prototype Instantiation
+
+```bash
+REPORT: "🚀 Phase 2b: Instantiating prototypes from templates..."
+
+# Step 1: Convert design tokens to CSS for each style
+REPORT: "   Converting design tokens to CSS variables..."
+
+# Check for jq dependency
+IF NOT command_exists("jq"):
+    ERROR: "jq is not installed or not in PATH. The conversion script requires jq."
+    REPORT: "Please install jq: macOS: brew install jq | Linux: apt-get install jq | Windows: https://stedolan.github.io/jq/download/"
+    EXIT 1
+
+# Convert design tokens to CSS for each style variant
+FOR style_id IN range(1, style_variants + 1):
+    tokens_json_path = "{base_path}/style-consolidation/style-${style_id}/design-tokens.json"
+    tokens_css_path = "{base_path}/style-consolidation/style-${style_id}/tokens.css"
+    script_path = "~/.claude/scripts/convert_tokens_to_css.sh"
+
+    # Verify input file exists
+    IF NOT exists(tokens_json_path): REPORT: "   ✗ ERROR: Input file not found"; CONTINUE
+
+    # Execute conversion: cat input.json | script.sh > output.css
+    Bash(cat "${tokens_json_path}" | "${script_path}" > "${tokens_css_path}")
+
+    # Verify output was generated
+    IF exit_code == 0 AND exists(tokens_css_path):
+        REPORT: "   ✓ Generated tokens.css for style-${style_id}"
+    ELSE:
+        REPORT: "   ✗ ERROR: Failed to generate tokens.css for style-${style_id}"
+
+# Step 2: Use ui-instantiate-prototypes.sh script for instantiation
+prototypes_dir = "{base_path}/prototypes"; targets_csv = ','.join(target_list)
+session_id = --session provided ? {session_id} : "standalone"
+
+# Execute instantiation script with target type
+Bash(~/.claude/scripts/ui-instantiate-prototypes.sh "{prototypes_dir}" --session-id "{session_id}" --mode "{target_type}")
+
+# The script auto-detects: Targets, Style variants, Layout variants
+# The script generates:
+# 1. S × L × T HTML prototypes with CSS links
+# 2. Implementation notes for each prototype
+# 3. compare.html (interactive matrix)
+# 4. index.html (navigation page)
+# 5. PREVIEW.md (documentation)
+
+REPORT: "✅ Phase 2b complete: Instantiated {style_variants * layout_variants * len(target_list)} final prototypes"
+REPORT: "   Mode: {target_type} | Performance: {style_variants}× faster than original approach"
+```
+
+### Phase 3: Verify Preview Files
+
+```bash
+REPORT: "🔍 Phase 3: Verifying preview files..."
+
+expected_files = ["{base_path}/prototypes/compare.html", "{base_path}/prototypes/index.html", "{base_path}/prototypes/PREVIEW.md"]
+
+all_present = true
+FOR file_path IN expected_files:
+    IF exists(file_path): REPORT: "   ✓ Found: {basename(file_path)}"
+    ELSE: REPORT: "   ✗ Missing: {basename(file_path)}"; all_present = false
+
+IF all_present: REPORT: "✅ Phase 3 complete: All preview files verified"
+ELSE: WARN: "⚠️ Some preview files missing - script may have failed"
+
+# Optional: Generate fallback design-tokens.css for reference
+fallback_css_path = "{base_path}/prototypes/design-tokens.css"
+IF NOT exists(fallback_css_path):
+    Write(fallback_css_path, "/* Auto-generated fallback CSS custom properties */\n/* See style-consolidation/style-{n}/tokens.css for actual values */")
+    REPORT: "   ✓ Generated fallback design-tokens.css"
+```
+
+### Phase 3.5: Cross-Target Consistency Validation
+
+**Condition**: Only executes if `len(target_list) > 1 AND target_type == "page"`
+
+```bash
+# Skip if single target or component mode
+IF len(target_list) <= 1 OR target_type == "component": SKIP to Phase 4
+
+# For multi-page workflows, validate cross-page consistency → @ui-design-agent
+FOR style_id IN range(1, style_variants + 1):
+    FOR layout_id IN range(1, layout_variants + 1):
+        Task(@ui-design-agent): "
+          [CROSS_PAGE_CONSISTENCY_VALIDATION]
+
+          Validate design consistency across multiple {target_type}s for Style-{style_id} Layout-{layout_id}
+
+          🎯 **VALIDATION FOCUS**:
+          ✅ **ADAPTIVE CONSISTENCY**: Same responsive behavior across all pages
+          ✅ **STYLE-SWITCHING**: Verify token references enable uniform theme switching
+          ✅ **CROSS-PAGE HARMONY**: Shared components use identical CSS variables
+
+          ## Context
+          STYLE_ID: {style_id} | LAYOUT_ID: {layout_id} | TARGETS: {target_list} | TARGET_TYPE: {target_type}
+          BASE_PATH: {base_path}
+
+          ## Input Files
+          FOR each target: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html/css
+
+          ## Validation Tasks
+          1. **Shared Component Consistency**: Check header/nav/footer structure matches
+          2. **Token Usage Consistency**: Verify same design-tokens file, no hardcoded values
+          3. **Accessibility Consistency**: ARIA attributes, heading hierarchy, landmark roles
+          4. **Layout Strategy Adherence**: Layout-{layout_id} strategy applied consistently
+
+          ## Output
+          Generate consistency report markdown file at:
+          {base_path}/prototypes/consistency-report-s{style_id}-l{layout_id}.md
+
+          Include validation results, issues found, and recommendations.
+          Focus on truly shared elements. Page-specific content variations are acceptable.
+        "
+
+# Aggregate consistency reports
+Write({base_path}/prototypes/CONSISTENCY_SUMMARY.md):
+# Multi-{target_type.capitalize()} Consistency Summary
+
+## Validated Combinations
+- Style Variants: {style_variants} | Layout Variants: {layout_variants}
+- Total Reports: {style_variants * layout_variants}
+
+## Report Files
+{FOR s, l: - [Style {s} Layout {l}](./consistency-report-s{s}-l{l}.md)}
+
+Run `/workflow:ui-design:update` once all issues are resolved.
+```
+
+### Phase 4: Completion
+
+```javascript
+TodoWrite({todos: [
+  {content: "Resolve paths and load design systems", status: "completed", activeForm: "Loading design systems"},
+  {content: `Plan ${target_list.length}×${layout_variants} target-specific layouts`, status: "completed", activeForm: "Planning layouts"},
+  {content: "Extract design token variable names", status: "completed", activeForm: "Extracting token variables"},
+  {content: `Generate ${layout_variants}×${target_list.length} layout templates using target-specific plans`, status: "completed", activeForm: "Generating templates"},
+  {content: "Convert design tokens to CSS variables", status: "completed", activeForm: "Converting tokens"},
+  {content: `Instantiate ${style_variants}×${layout_variants}×${target_list.length} prototypes using script`, status: "completed", activeForm: "Running script"},
+  {content: "Verify preview files generation", status: "completed", activeForm: "Verifying files"}
+]});
+```
+
+**Completion Message**:
+```
+✅ Optimized Matrix UI generation complete!
+
+Configuration:
+- Style Variants: {style_variants}
+- Layout Variants: {layout_variants} (target-specific planning)
+- Target Type: {target_type_icon} {target_type}
+- Targets: {target_list}
+- Total Prototypes: {style_variants * layout_variants * len(target_list)}
+- Layout Plans: {len(target_list) × layout_variants} target-specific JSON files generated
+
+Performance Metrics:
+- Layout Templates Generated: {layout_variants * len(target_list)} (Agent tasks)
+- Prototypes Instantiated: {style_variants * layout_variants * len(target_list)} (script-based)
+- Preview Files: compare.html, index.html, PREVIEW.md (auto-generated)
+- Speed Improvement: {style_variants}× faster than previous approach
+- Resource Efficiency: {100 * (1 - 1/style_variants)}% reduction in Agent calls
+- Script: ui-instantiate-prototypes.sh v3.0 with auto-detection
+
+Generated Structure:
+📂 {base_path}/prototypes/
+├── _templates/
+│   ├── {target}-layout-{l}.json ({len(target_list) × layout_variants} layout plans)
+│   ├── {target}-layout-{l}.html ({layout_variants * len(target_list)} HTML templates)
+│   └── {target}-layout-{l}.css ({layout_variants * len(target_list)} CSS templates)
+├── {target}-style-{s}-layout-{l}.html ({style_variants * layout_variants * len(target_list)} final prototypes)
+├── {target}-style-{s}-layout-{l}-notes.md
+├── compare.html (interactive matrix visualization)
+└── index.html (quick navigation)
+
+🌐 Interactive Preview:
+1. Matrix View: Open compare.html (recommended)
+2. Quick Index: Open index.html
+3. Instructions: See PREVIEW.md
+
+{IF target_type == "component": Note: Components are rendered with minimal wrapper for isolated comparison.}
+
+Next: /workflow:ui-design:update {--session flag if applicable}
+
+Note: When called from /workflow:ui-design:auto, design-update is triggered automatically.
+
+**Dynamic Values**: target_type_icon: "📄" for page, "🧩" for component
+```
+
+## Output Structure
+
+```
+{base_path}/prototypes/
+├── _templates/                            # Target-specific layout plans and templates
+│   ├── {target}-layout-1.json            # Layout plan JSON (target-specific)
+│   ├── {target}-layout-1.html            # Style-agnostic HTML structure
+│   ├── {target}-layout-1.css             # Structural CSS with var() references
+│   └── ... (T × L layout plans + templates)
+├── compare.html                           # Interactive matrix visualization
+├── index.html                             # Simple navigation page
+├── PREVIEW.md                             # Preview instructions
+├── design-tokens.css                      # CSS custom properties fallback
+├── {target}-style-{s}-layout-{l}.html    # Final prototypes (copied from templates)
+├── {target}-style-{s}-layout-{l}-notes.md  # Implementation notes
+└── ... (S × L × T total final files)
+
+{base_path}/style-consolidation/
+├── style-1/ (design-tokens.json, tokens.css, style-guide.md)
+├── style-2/ (same structure)
+└── ...
+```
+
+## Error Handling
+
+### Pre-execution Checks
+- **No design systems found**: Error - Run `/workflow:ui-design:consolidate` first
+- **Invalid target names**: Extract from synthesis-specification.md or error with validation message
+- **Missing templates directory**: Auto-created in Phase 1.5
+- **Unsupported target type**: Error if target_type not in ["page", "component"]
+- **Layout planning failures**: Check Phase 1.5 agent outputs for errors
+
+### Phase-Specific Errors
+- **Agent execution errors (Phase 2a)**: Report details, suggest retry with specific phase
+- **Token conversion errors (Phase 2b)**: Check design-tokens.json format, validate JSON schema
+- **Script execution errors (Phase 2b)**: Check script exists, permissions, output for specific errors
+- **Preview generation errors (Phase 3)**: Check script completed, verify template exists, review Phase 2b output
+
+### Recovery Strategies
+- **Partial failure**: Script reports generated vs failed counts - review logs
+- **Missing templates**: Indicates Phase 2a issue - regenerate templates
+- **Auto-detection failures**: Use manual mode with explicit parameters
+- **Permission errors**: Run `chmod +x ~/.claude/scripts/ui-instantiate-prototypes.sh`
+
+## Quality Checks
+
+After generation, ensure:
+- [ ] All CSS values reference design token custom properties
+- [ ] No hardcoded colors, spacing, or typography
+- [ ] Semantic HTML structure with proper element hierarchy
+- [ ] ARIA attributes present for accessibility
+- [ ] Responsive design implemented with mobile-first approach
+- [ ] File naming follows `{target}-style-{s}-layout-{l}` convention
+- [ ] compare.html loads correctly with all prototypes
+- [ ] Template files are reusable and style-agnostic
+- [ ] Appropriate wrapper used (full-page for pages, minimal for components)
+
+## Key Features
+
+1. **Target-Specific Layout Planning** 🆕 - Each target gets custom-designed layouts; Agent researches modern patterns using MCP tools; Layout plans saved as structured JSON
+2. **Unified Target Generation** - Supports both pages (full layouts) and components (isolated elements); Backward compatible with legacy `--pages` parameter
+3. **Optimized Template-Based Architecture** - Generates `L × T` reusable templates plus `L × T` layout plans; **`S` times faster**
+4. **Three-Layer Generation Strategy** - Layer 1: Layout planning (target-specific); Layer 2: Template generation (implements plans); Layer 3: Fast instantiation; Agent autonomously uses MCP tools
+5. **Script-Based Instantiation (v3.0)** - Uses `ui-instantiate-prototypes.sh` for efficient file operations; Auto-detection; Robust error handling; Integrated preview generation; Supports both page and component modes
+6. **Consistent Cross-Style Layouts** - Same layout structure applied uniformly; Easier to compare styles; Simplified maintenance
+7. **Dynamic Style Injection** - CSS custom properties enable runtime style switching; Each style variant has its own `tokens.css` file
+8. **Interactive Visualization** - Full-featured compare.html; Matrix grid view with synchronized scrolling; Enhanced index.html with statistics; Comprehensive PREVIEW.md
+9. **Production-Ready Output** - Semantic HTML5 and ARIA attributes (WCAG 2.2); Mobile-first responsive design; Token-driven styling; Implementation notes
+
+## Integration Points
+
+- **Input**: Per-style `design-tokens.json` from `/workflow:ui-design:consolidate`; `--targets` and `--layout-variants` parameters; Optional: `synthesis-specification.md` for target requirements; Target type specification
+- **Output**: Target-specific `layout-{n}.json` files; Matrix HTML/CSS prototypes for `/workflow:ui-design:update`
+- **Template**: `~/.claude/workflows/_template-compare-matrix.html` (global)
+- **Auto Integration**: Automatically triggered by `/workflow:ui-design:explore-auto` workflow
+- **Key Change**: Layout planning moved from consolidate to generate phase; Each target gets custom-designed layouts
+- **Backward Compatibility**: Legacy `--pages` parameter continues to work

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

@@ -0,0 +1,335 @@
+---
+name: imitate-auto
+description: Imitation-focused UI design workflow - Rapidly replicate a single design style from URL or images (skip exploration, direct to implementation)
+usage: /workflow:ui-design:imitate-auto [--url "<url>"] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>]
+argument-hint: "[--url \"https://example.com\"] [--images \"refs/*.png\"] [--prompt \"Imitate dark mode style\"] [--targets \"dashboard,settings\"] [--target-type \"page\"]"
+examples:
+  - /workflow:ui-design:imitate-auto --url "https://linear.app" --targets "home,features,pricing"
+  - /workflow:ui-design:imitate-auto --images "refs/design.png" --prompt "Imitate this minimalist design for dashboard and settings"
+  - /workflow:ui-design:imitate-auto --url "https://stripe.com" --session WFS-payment
+  - /workflow:ui-design:imitate-auto --images "refs/*.png" --targets "home"
+  - /workflow:ui-design:imitate-auto --url "https://example.com" --targets "navbar,hero" --target-type "component"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*)
+---
+
+# UI Design Imitate-Auto Workflow Command
+
+## Overview & Philosophy
+
+**Fast-track UI imitation workflow**: Replicates a single design style from reference source (URL or images), bypassing exploration and consolidation phases for maximum speed (~2-3× faster than explore-auto).
+
+**Core Philosophy**:
+- **Imitation over Exploration**: Focus on replicating specific design, not generating variants
+- **Single Mode**: Always 1 style × 1 layout × N targets
+- **Speed Optimized**: Bypasses `consolidate` step via direct token extraction
+- **Reference-Driven**: Requires URL or images as primary input
+- **Auto-Screenshot**: Supports Playwright/Chrome with manual upload fallback
+
+**Streamlined Flow**: Phase 0 (init) → 0.5 (screenshot) → 1 (extraction) → 2 (token adapt) → 3 (generate) → 4 (integrate)
+
+**Performance**: ~2-3× faster than explore-auto for single-style scenarios
+
+**Ideal For**: MVP development, high-fidelity prototyping, design replication, studying successful patterns
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 0 execution
+2. **No Multi-Variant**: Always 1 style × 1 layout × N targets
+3. **Reference Required**: Must provide `--url` OR `--images`
+4. **Auto-Continue**: Automatic phase progression without pausing
+5. **Track Progress**: Update TodoWrite after each phase
+
+## Parameter Requirements
+
+**Required** (at least one): `--url "<url>"` OR `--images "<glob>"`
+
+**Optional**: `--targets "<list>"`, `--target-type "page|component"`, `--session <id>`, `--prompt "<desc>"`
+
+**Legacy**: `--pages "<list>"` (alias for `--targets` with type=page)
+
+**Not Supported**: `--style-variants`, `--layout-variants`, `--batch-plan`
+
+## 5-Phase Execution
+
+### Phase 0: Simplified Initialization
+
+```bash
+run_id = "run-$(date +%Y%m%d-%H%M%S)"
+base_path = --session ? ".workflow/WFS-{session}/design-${run_id}" : ".workflow/.design/${run_id}"
+
+Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation/style-1,prototypes}")
+
+# Metadata
+Write({base_path}/.run-metadata.json): {
+  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "workflow": "ui-design:imitate-auto", "mode": "single_style_imitation",
+  "parameters": {"url": "${url_value}", "images": "${images_pattern}", "targets": "${target_list}", "prompt": "${prompt_text}"},
+  "status": "in_progress"
+}
+
+# Unified target inference (no interactive confirmation)
+target_list = []; target_type = "page"; target_source = "none"
+
+# Priority: --pages (legacy) → --targets → --prompt → default
+IF --pages: target_list = split(--pages); target_type = "page"; target_source = "explicit_legacy"
+ELSE IF --targets:
+    target_list = split(--targets)
+    target_type = --target-type ? --target-type : detect_target_type(target_list)
+    target_source = "explicit"
+ELSE IF --prompt:
+    target_list = extract_targets_from_prompt(prompt_text) OR ["home"]
+    target_type = --target-type ? --target-type : detect_target_type(target_list)
+    target_source = "prompt_inferred"
+ELSE:
+    target_list = ["home"]; target_type = "page"; target_source = "default"
+
+# Validate and clean
+validated_targets = [t.strip().lower().replace(" ", "-") for t in target_list if regex_match(t, r"^[a-z0-9][a-z0-9_-]*$")]
+IF NOT validated_targets: validated_targets = ["home"]; target_type = "page"
+
+type_emoji = "📄" IF target_type == "page" ELSE "🧩"
+type_label = "pages" IF target_type == "page" ELSE "components"
+
+REPORT: "📋 Imitate mode: {len(validated_targets)} {type_label} with single style"
+REPORT: "   {type_emoji} Targets: {', '.join(validated_targets)} | Type: {target_type} | Reference: {url_value OR images_pattern}"
+
+STORE: run_id, base_path, inferred_target_list = validated_targets, target_type
+```
+
+### Phase 0.5: URL Screenshot Capture (Auto-Fallback)
+
+**Condition**: Only if `--url` provided
+
+```bash
+IF --url:
+    screenshot_dir = "{base_path}/screenshots"; Bash(mkdir -p "{screenshot_dir}")
+    screenshot_success = false; screenshot_files = []
+
+    # Try Playwright → Chrome → Manual fallback
+    TRY: Bash(npx playwright screenshot "{url_value}" "{screenshot_dir}/full-page.png" --full-page --timeout 30000)
+         screenshot_files.append("{screenshot_dir}/full-page.png"); screenshot_success = true
+         REPORT: "   ✅ Playwright screenshot captured"
+    CATCH: REPORT: "   ⚠️ Playwright failed"
+
+    IF NOT screenshot_success:
+        TRY: Bash(google-chrome --headless --disable-gpu --screenshot="{screenshot_dir}/full-page.png" --window-size=1920,1080 "{url_value}")
+             screenshot_files.append("{screenshot_dir}/full-page.png"); screenshot_success = true
+             REPORT: "   ✅ Chrome screenshot captured"
+        CATCH: REPORT: "   ⚠️ Chrome failed"
+
+    # Manual upload fallback
+    IF NOT screenshot_success:
+        REPORT: "━━━ ⚠️ AUTOMATED SCREENSHOT FAILED ━━━"
+        REPORT: "Unable to capture: {url_value}"
+        REPORT: "Manual screenshot required:"
+        REPORT: "  1. Visit: {url_value} | 2. Take full-page screenshot | 3. Save to: {screenshot_dir}/"
+        REPORT: "Options: 'ready' (screenshot saved) | 'skip' (URL only) | 'abort' (cancel)"
+        REPORT: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+          "ready|done|ok" → screenshot_files = Glob("{screenshot_dir}/*.{png,jpg,jpeg}");
+                            IF screenshot_files: screenshot_success = true; REPORT: "✅ Manual screenshot detected"
+                            ELSE: REPORT: "❌ No screenshot found, using URL analysis only"
+          "skip" → REPORT: "⏭️ Skipping screenshot, using URL analysis"
+          "abort" → ERROR: "Workflow aborted by user"; EXIT
+          _ → REPORT: "⚠️ Invalid input, proceeding with URL analysis"
+
+    # Store results
+    STORE: screenshot_mode = screenshot_success ? "with_screenshots" : "url_only", screenshot_paths = screenshot_files
+    REPORT: screenshot_success ? "✅ Screenshot capture complete: {len(screenshot_files)} image(s)" : "ℹ️ Proceeding with URL analysis only"
+ELSE:
+    STORE: screenshot_mode = "manual_images", screenshot_paths = []
+    REPORT: "ℹ️ Using provided images (--images parameter)"
+```
+
+### Phase 1: Single Style Extraction
+
+```bash
+# Determine input based on screenshot capture
+source_desc = screenshot_mode == "with_screenshots" ? "captured screenshots from {url_value}" :
+              screenshot_mode == "url_only" ? "URL analysis of {url_value}" : "user-provided images"
+
+images_flag = screenshot_mode == "with_screenshots" ? "--images \"{base_path}/screenshots/*.{png,jpg,jpeg}\"" :
+              screenshot_mode == "manual_images" AND --images ? "--images \"{image_glob}\"" : ""
+
+url_flag = screenshot_mode == "url_only" ? "--url \"{url_value}\"" : ""
+
+# Construct optimized extraction prompt
+enhanced_prompt = "Extract a single, high-fidelity design system that accurately imitates the visual style from {source_desc}. {prompt_text}"
+
+# Force single variant
+command = "/workflow:ui-design:extract --base-path \"{base_path}\" {url_flag} {images_flag} --prompt \"{enhanced_prompt}\" --variants 1"
+
+REPORT: "🚀 Phase 1: Style Extraction | Source: {source_desc} | Mode: Single style (imitation-optimized)"
+
+SlashCommand(command)
+```
+
+### Phase 2: Fast Token Adaptation (Bypass Consolidate)
+
+```bash
+REPORT: "🚀 Phase 2: Fast token adaptation (bypassing consolidate)"
+
+style_cards = Read({base_path}/style-extraction/style-cards.json)
+style_card = style_cards.style_cards[0]
+
+design_tokens = style_card.proposed_tokens
+philosophy = style_card.design_philosophy
+style_name = style_card.name
+
+# Write design-tokens.json directly
+Write({base_path}/style-consolidation/style-1/design-tokens.json, JSON.stringify(design_tokens, null, 2))
+
+# Create minimal style-guide.md
+Write({base_path}/style-consolidation/style-1/style-guide.md):
+# Design System: {style_name}
+
+## Design Philosophy
+{philosophy}
+
+## Description
+{style_card.description}
+
+## Design Tokens
+All tokens in `design-tokens.json` follow OKLCH color space.
+
+**Key Colors**: Primary: {design_tokens.colors.brand.primary} | Background: {design_tokens.colors.surface.background} | Text: {design_tokens.colors.text.primary}
+
+**Typography**: Heading: {design_tokens.typography.font_family.heading} | Body: {design_tokens.typography.font_family.body}
+
+**Spacing Scale**: {design_tokens.spacing.keys().length} values
+
+*Note: Generated in imitate mode for fast replication.*
+
+REPORT: "✅ Tokens extracted and formatted | Style: {style_name} | Bypassed consolidate for {performance_gain}× speed"
+```
+
+### Phase 3: Single Prototype Generation
+
+```bash
+targets_string = ",".join(inferred_target_list)
+type_emoji = "📄" IF target_type == "page" ELSE "🧩"
+type_label = "page(s)" IF target_type == "page" ELSE "component(s)"
+
+command = "/workflow:ui-design:generate --base-path \"{base_path}\" --targets \"{targets_string}\" --target-type \"{target_type}\" --style-variants 1 --layout-variants 1"
+
+REPORT: "🚀 Phase 3: Generating {len(inferred_target_list)} {type_label}"
+REPORT: "   {type_emoji} Targets: {targets_string} | Mode: 1×1 (imitation-optimized)"
+
+SlashCommand(command)
+
+# Result: Prototypes: {target}-style-1-layout-1.html, Total: len(inferred_target_list), Type: {target_type}
+```
+
+### Phase 4: Design System Integration
+
+```bash
+IF --session:
+    SlashCommand("/workflow:ui-design:update --session {session_id}")
+ELSE:
+    REPORT: "ℹ️ Standalone mode: Skipping integration | Prototypes at: {base_path}/prototypes/"
+```
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize
+TodoWrite({todos: [
+  {"content": "Initialize run directory and infer targets", "status": "in_progress", "activeForm": "Initializing"},
+  {"content": "Capture screenshots from URL (if provided)", "status": "pending", "activeForm": "Capturing screenshots"},
+  {"content": "Extract single design style from reference", "status": "pending", "activeForm": "Extracting style"},
+  {"content": "Adapt tokens (bypass consolidate)", "status": "pending", "activeForm": "Adapting tokens"},
+  {"content": "Generate single-style prototypes", "status": "pending", "activeForm": "Generating prototypes"},
+  {"content": "Integrate design system", "status": "pending", "activeForm": "Integrating design"}
+]})
+
+// Update after each phase: Mark current completed, next in_progress
+```
+
+## Error Handling
+
+- **No reference source**: Error if neither `--url` nor `--images` provided
+- **Screenshot capture failure**: Tries Playwright → Chrome → Manual upload (user uploads, skips, or aborts); gracefully handles missing tools
+- **Invalid URL/images**: Report error, suggest alternative input
+- **Token extraction failure**: Fallback to minimal default design system
+
+## Performance Comparison
+
+| Aspect | explore-auto | imitate-auto |
+|--------|--------------|--------------|
+| **Purpose** | Design exploration | Design replication |
+| **Input** | Optional URL/images | **Required** URL or images |
+| **Variants** | 1-5 styles × 1-5 layouts | Always 1 × 1 |
+| **Consolidate** | Full consolidation | **Bypassed** (direct tokens) |
+| **Speed** | Baseline | **~2-3× faster** |
+| **Output** | Matrix (S×L×T) | Direct (1×1×T) |
+
+**Performance Benefits**: Skipped consolidate (~30-60s saved), single variant, direct token mapping, streamlined decisions
+
+## Example Execution Flows
+
+### Example 1: URL with Auto-Screenshot (Pages)
+```bash
+/workflow:ui-design:imitate-auto --url "https://linear.app" --targets "home,features,pricing"
+
+# Flow: 0 (3 pages) → 0.5 (Playwright captures) → 1 (single style) → 2 (direct tokens ~2s vs ~45s) → 3 (3 prototypes) → 4
+# Time: ~2-3 min (vs 5-7 min with explore-auto)
+```
+
+### Example 2: Images with Guidance (Page Mode)
+```bash
+/workflow:ui-design:imitate-auto --images "refs/dark-theme.png" --prompt "Focus on dark mode" --targets "dashboard"
+
+# Flow: 0 → 0.5 (skip) → 1 → 2 → 3 → 4
+# Output: dashboard-style-1-layout-1.html | Type: page (full-page layout)
+```
+
+### Example 3: Component Mode
+```bash
+/workflow:ui-design:imitate-auto --url "https://example.com" --targets "navbar,hero,card" --target-type "component"
+
+# Flow: 0 → 0.5 → 1 → 2 → 3 → 4
+# Output: navbar/hero/card-style-1-layout-1.html | Type: component (minimal wrapper)
+```
+
+### Example 4: URL with Manual Screenshot
+```bash
+/workflow:ui-design:imitate-auto --url "https://stripe.com/pricing" --targets "pricing"
+
+# 0.5: Playwright failed → Chrome failed → User prompted → types 'ready' → ✅ continues OR 'skip' → ⚠️ URL only
+# Continues: 1 → 2 → 3 → 4
+```
+
+## Final Completion Message
+
+```
+✅ UI Design Imitation Complete!
+
+Mode: Single Style Replication | Run ID: {run_id} | Session: {session_id or "standalone"} | Reference: {url OR images} | Type: {type_emoji} {type_label}
+
+Phase 0 - Initialization: {target_count} {target_type}(s) prepared
+Phase 0.5 - Screenshot Capture: {screenshot_status}
+  {IF success: ✅ Captured via {method} | ELSE: ⚠️ URL analysis only}
+Phase 1 - Style Extraction: Single style extracted
+Phase 2 - Token Adaptation: Bypassed consolidate (⚡ {time_saved}s saved)
+Phase 3 - Prototype Generation: {target_count} {target_type} prototypes created
+Phase 4 - Design Integration: {integrated OR "Standalone mode"}
+
+📂 Output: {base_path}/
+  ├── style-extraction/style-cards.json (1 style card)
+  ├── style-consolidation/style-1/ (design tokens)
+  └── prototypes/ ({target_count} HTML/CSS files)
+
+🌐 Preview: {base_path}/prototypes/index.html
+
+{type_emoji} Targets: {', '.join(inferred_target_list)} | Type: {target_type}
+  Context: {IF target_type == "page": "Full-page layouts" ELSE: "Isolated components with minimal wrapper"}
+
+Performance:
+- Design system: ~{time}s (vs ~{consolidate_time}s with consolidate)
+- Total workflow: ~{total_time}s
+- Speed improvement: ~{improvement}× faster than explore-auto
+
+{IF session: Next: /workflow:plan to create implementation tasks | ELSE: Prototypes ready: {base_path}/prototypes/}
+```

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

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

.claude/prompt-templates/plan.md

@@ -1,10 +1,3 @@
----
-name: plan
-description: 软件架构规划和技术实现计划分析模板
-category: planning
-keywords: [规划, 架构, 实现计划, 技术设计, 修改方案]
----
-
 # 软件架构规划模板
 # AI Persona & Core Mission
 

.claude/scripts/convert_tokens_to_css.sh

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

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

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

.claude/scripts/update_module_claude.sh

@@ -1,13 +1,15 @@
 #!/bin/bash
 # Update CLAUDE.md for a specific module with automatic layer detection
-# Usage: update_module_claude.sh <module_path> [update_type]
+# Usage: update_module_claude.sh <module_path> [update_type] [tool]
 #   module_path: Path to the module directory
 #   update_type: full|related (default: full)
+#   tool: gemini|qwen|codex (default: gemini)
 #   Script automatically detects layer depth and selects appropriate template
 
 update_module_claude() {
     local module_path="$1"
     local update_type="${2:-full}"
+    local tool="${3:-gemini}"
     
     # Validate parameters
     if [ -z "$module_path" ]; then
@@ -40,30 +42,30 @@ update_module_claude() {
     if [ "$module_path" = "." ]; then
         # Root directory
         layer="Layer 1 (Root)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer1-root.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer1-root.txt"
         analysis_strategy="--all-files"
     elif [[ "$clean_path" =~ ^[^/]+$ ]]; then
         # Top-level directories (e.g., .claude, src, tests)
         layer="Layer 2 (Domain)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer2-domain.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer2-domain.txt"
         analysis_strategy="@{*/CLAUDE.md}"
     elif [[ "$clean_path" =~ ^[^/]+/[^/]+$ ]]; then
         # Second-level directories (e.g., .claude/scripts, src/components)
         layer="Layer 3 (Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer3-module.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer3-module.txt"
         analysis_strategy="@{*/CLAUDE.md}"
     else
         # Deeper directories (e.g., .claude/workflows/cli-templates/prompts)
         layer="Layer 4 (Sub-Module)"
-        template_path="$HOME/.claude/workflows/cli-templates/prompts/dms/claude-layer4-submodule.txt"
+        template_path="$HOME/.claude/workflows/cli-templates/prompts/memory/claude-layer4-submodule.txt"
         analysis_strategy="--all-files"
     fi
     
     # Prepare logging info
     local module_name=$(basename "$module_path")
-    
+
     echo "⚡ Updating: $module_path"
-    echo "   Layer: $layer | Type: $update_type | Files: $file_count"
+    echo "   Layer: $layer | Type: $update_type | Tool: $tool | Files: $file_count"
     echo "   Template: $(basename "$template_path") | Strategy: $analysis_strategy"
     
     # Generate prompt with template injection
@@ -106,31 +108,50 @@ update_module_claude() {
     # Execute update
     local start_time=$(date +%s)
     echo "   🔄 Starting update..."
-    
+
     if cd "$module_path" 2>/dev/null; then
-        # Execute gemini command with layer-specific analysis strategy
-        local gemini_result=0
-        if [ "$analysis_strategy" = "--all-files" ]; then
-            gemini --all-files --yolo -p "$base_prompt
+        local tool_result=0
+        local final_prompt="$base_prompt
 
         Module Information:
         - Name: $module_name
         - Path: $module_path
         - Layer: $layer
-        - Analysis Strategy: $analysis_strategy" 2>&1
-            gemini_result=$?
-        else
-            gemini --yolo -p "$analysis_strategy $base_prompt
+        - Tool: $tool
+        - Analysis Strategy: $analysis_strategy"
 
-        Module Information:
-        - Name: $module_name
-        - Path: $module_path
-        - Layer: $layer
-        - Analysis Strategy: $analysis_strategy" 2>&1
-            gemini_result=$?
-        fi
-        
-        if [ $gemini_result -eq 0 ]; then
+        # Execute with selected tool
+        case "$tool" in
+            qwen)
+                if [ "$analysis_strategy" = "--all-files" ]; then
+                    qwen --all-files --yolo -p "$final_prompt" 2>&1
+                    tool_result=$?
+                else
+                    qwen --yolo -p "$analysis_strategy $final_prompt" 2>&1
+                    tool_result=$?
+                fi
+                ;;
+            codex)
+                if [ "$analysis_strategy" = "--all-files" ]; then
+                    codex --full-auto exec "$final_prompt" --skip-git-repo-check -s danger-full-access 2>&1
+                    tool_result=$?
+                else
+                    codex --full-auto exec "$final_prompt CONTEXT: $analysis_strategy" --skip-git-repo-check -s danger-full-access 2>&1
+                    tool_result=$?
+                fi
+                ;;
+            gemini|*)
+                if [ "$analysis_strategy" = "--all-files" ]; then
+                    gemini --all-files --yolo -p "$final_prompt" 2>&1
+                    tool_result=$?
+                else
+                    gemini --yolo -p "$analysis_strategy $final_prompt" 2>&1
+                    tool_result=$?
+                fi
+                ;;
+        esac
+
+        if [ $tool_result -eq 0 ]; then
             local end_time=$(date +%s)
             local duration=$((end_time - start_time))
             echo "   ✅ Completed in ${duration}s"

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

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

.claude/workflows/brainstorming-principles.md

@@ -1,82 +0,0 @@
-# Brainstorming System Principles
-
-## Core Philosophy
-**"Diverge first, then converge"** - Generate multiple solutions from diverse perspectives, then synthesize and prioritize.
-
-## Creative Techniques Reference
-
-### SCAMPER Method
-- **Substitute**: What can be substituted or replaced?
-- **Combine**: What can be combined or merged?
-- **Adapt**: What can be adapted from elsewhere?
-- **Modify**: What can be magnified, minimized, or modified?
-- **Put to other uses**: How else can this be used?
-- **Eliminate**: What can be removed or simplified?
-- **Reverse**: What can be rearranged or reversed?
-
-### Six Thinking Hats
-- **White Hat**: Facts, information, data
-- **Red Hat**: Emotions, feelings, intuition
-- **Black Hat**: Critical judgment, caution, problems
-- **Yellow Hat**: Optimism, benefits, positive thinking
-- **Green Hat**: Creativity, alternatives, new ideas
-- **Blue Hat**: Process control, meta-thinking
-
-### Additional Techniques
-- **Mind Mapping**: Visual idea exploration and connection
-- **Brainwriting**: Silent idea generation and building
-- **Random Word**: Stimulus-based creative thinking
-- **Assumption Challenging**: Question fundamental assumptions
-
-## Analysis Modes
-
-### Creative Mode (Default)
-- **Focus**: Innovation and unconventional solutions
-- **Approach**: Emphasize divergent thinking, "what if" scenarios, assumption challenging
-
-### Analytical Mode
-- **Focus**: Evidence-based systematic problem-solving
-- **Approach**: Structured analysis, root cause analysis, logical reasoning
-
-### Strategic Mode
-- **Focus**: Long-term strategic positioning
-- **Approach**: Systems thinking, competitive dynamics, market forces
-
-## Documentation Standards
-
-### Session Output Format
-```
-CHALLENGE_DEFINITION: Clear problem space definition
-KEY_INSIGHTS: Major discoveries and patterns
-TOP_CONCEPTS: 5 most promising solutions with analysis
-PERSPECTIVE_SYNTHESIS: Integration of role-based insights
-FEASIBILITY_ASSESSMENT: Technical and resource evaluation
-RECOMMENDATIONS: Prioritized next steps and actions
-```
-
-### Idea Documentation
-For each significant concept:
-- Core mechanism and description
-- Multi-perspective implications
-- Feasibility assessment (technical, resource, timeline)
-- Impact potential and success metrics
-- Implementation considerations
-- Risk assessment and mitigation
-
-## Quality Standards
-
-### Session Excellence
-- **Clear Structure**: Follow Explore → Ideate → Converge → Document phases
-- **Inclusive Participation**: Ensure all perspectives are valued
-- **Creative Environment**: Maintain judgment-free ideation atmosphere
-- **Actionable Outcomes**: Generate concrete next steps
-
-### Perspective Integration
-- **Authentic Representation**: Accurately channel each role's mental models
-- **Constructive Synthesis**: Combine insights into stronger solutions
-- **Conflict Navigation**: Address perspective tensions constructively
-- **Comprehensive Coverage**: Ensure no critical aspects overlooked
-
----
-
-This framework provides the conceptual foundation for brainstorming activities. Implementation details are handled by individual role commands and the auto coordination system.

.claude/workflows/cli-templates/planning-roles/business-analyst.md

@@ -1,119 +0,0 @@
----
-name: business-analyst
-description: Business process optimization, requirements analysis, and efficiency improvement
----
-
-# Business Analyst Planning Template
-
-You are a **Business Analyst** specializing in process optimization, requirements analysis, and business efficiency improvement.
-
-## Your Role & Responsibilities
-
-**Primary Focus**: Business process analysis, requirement gathering, workflow optimization, and organizational efficiency
-
-**Core Responsibilities**:
-- Business process mapping and optimization planning
-- Requirements analysis and documentation
-- Stakeholder needs assessment and alignment
-- Workflow efficiency analysis and improvement planning
-- Cost-benefit analysis and ROI evaluation
-- Change management and process adoption planning
-
-**Does NOT Include**: Technical implementation, software development, direct process execution
-
-## Planning Document Structure
-
-Generate a comprehensive business analysis planning document with the following structure:
-
-### 1. Business Context & Objectives
-- **Business Goals**: Strategic objectives and key business outcomes
-- **Current State Analysis**: Existing processes, systems, and workflows
-- **Problem Statement**: Business challenges and improvement opportunities
-- **Success Metrics**: KPIs, efficiency gains, and business impact measures
-
-### 2. Stakeholder Analysis & Requirements
-- **Stakeholder Mapping**: Internal and external stakeholders and their needs
-- **Requirements Gathering**: Functional and non-functional requirements
-- **Business Rules**: Constraints, policies, and governance requirements
-- **Acceptance Criteria**: Clear definition of successful outcomes
-
-### 3. Process Analysis & Optimization
-- **Current Process Mapping**: As-is process flows and bottlenecks
-- **Gap Analysis**: Inefficiencies, redundancies, and improvement areas
-- **Future State Design**: Optimized process flows and workflows
-- **Process Metrics**: Efficiency measures and performance indicators
-
-### 4. Impact Analysis & Business Case
-- **Cost-Benefit Analysis**: Implementation costs vs expected benefits
-- **ROI Calculation**: Return on investment and payback period
-- **Risk Assessment**: Business risks and mitigation strategies
-- **Resource Requirements**: People, budget, time, and tool requirements
-
-### 5. Change Management & Adoption
-- **Change Impact Assessment**: Organizational impact and change readiness
-- **Training Requirements**: Skill gaps and training needs analysis
-- **Communication Strategy**: Stakeholder communication and change messaging
-- **Adoption Planning**: Rollout strategy and success measurement
-
-### 6. Implementation Strategy & Governance
-- **Implementation Roadmap**: Phased approach and timeline planning
-- **Quality Assurance**: Testing, validation, and quality control measures
-- **Governance Framework**: Decision-making processes and escalation paths
-- **Continuous Improvement**: Post-implementation monitoring and optimization
-
-## Key Questions to Address
-
-1. **Business Value**: What specific business problems are we solving?
-2. **Process Efficiency**: Where are the current inefficiencies and bottlenecks?
-3. **Stakeholder Impact**: How will different stakeholders be affected by changes?
-4. **Resource Optimization**: How can we achieve better results with existing resources?
-5. **Change Readiness**: How prepared is the organization for this change?
-
-## Output Requirements
-
-- **Requirements Document**: Comprehensive functional and business requirements
-- **Process Maps**: Current state and future state process documentation
-- **Business Case**: Detailed cost-benefit analysis and ROI justification
-- **Implementation Plan**: Phased rollout strategy with timelines and milestones
-- **Change Management Plan**: Stakeholder engagement and adoption strategy
-
-## Brainstorming Documentation Files to Create
-
-When conducting brainstorming sessions, create the following files:
-
-### Individual Role Analysis File: `business-analyst-analysis.md`
-```markdown
-# Business Analyst Analysis: [Topic]
-
-## Process Impact Assessment
-- Current process analysis and bottlenecks
-- Process optimization opportunities
-- Workflow efficiency improvements
-
-## Requirements Analysis
-- Functional and non-functional requirements
-- Business rules and constraints
-- Stakeholder needs and expectations
-
-## Cost-Benefit Analysis
-- Implementation costs and resource requirements
-- Expected benefits and ROI projections
-- Risk assessment and mitigation strategies
-
-## Change Management Assessment
-- Organizational change impact
-- Stakeholder readiness and adoption factors
-- Training and communication requirements
-
-## Recommendations
-- Process improvement recommendations
-- Implementation approach and timeline
-- Success metrics and measurement strategies
-```
-
-### Session Contribution Template
-For role-specific contributions to broader brainstorming sessions, provide:
-- Process efficiency implications for each solution
-- Business requirements and constraints analysis
-- ROI and cost-benefit assessment
-- Change management and adoption considerations

.claude/workflows/cli-templates/planning-roles/feature-planner.md

@@ -1,115 +0,0 @@
----
-name: feature-planner
-description: Feature specification, requirement analysis, and implementation roadmap planning
----
-
-# Feature Planner Planning Template
-
-You are a **Feature Planner** specializing in feature analysis and implementation pathway planning.
-
-## Your Role & Responsibilities
-
-**Primary Focus**: Feature specification, requirement analysis, and implementation roadmap planning
-
-**Core Responsibilities**:
-- Feature specifications and detailed requirement analysis
-- Implementation steps and dependency mapping
-- User story decomposition and acceptance criteria definition
-- Feature prioritization and release planning strategies
-- Risk assessment and mitigation strategies for feature development
-- Integration planning with existing system components
-
-**Does NOT Include**: Developing features, writing tests, performing actual implementation
-
-## Planning Document Structure
-
-Generate a comprehensive feature planning document with the following structure:
-
-### 1. Feature Overview & Definition
-- **Feature Definition**: Clear description, business value, target users, priority level
-- **User Stories**: Detailed user stories with "As a... I want... so that..." format
-- **Business Justification**: Why this feature is important and expected impact
-
-### 2. Requirements Analysis
-- **Functional Requirements**: Specific functional requirements (FR-1, FR-2, etc.)
-- **Non-Functional Requirements**: Performance, scalability, security, usability requirements
-- **Constraints & Assumptions**: Technical, business constraints and key assumptions
-
-### 3. Feature Breakdown & Architecture
-- **Core Components**: Component definitions and functionality
-- **User Interface Elements**: Screen/page definitions and key elements
-- **Data Requirements**: Data models, sources, and storage requirements
-- **API Design**: Required endpoints and data contracts
-
-### 4. Implementation Roadmap
-- **Phased Approach**: Multi-phase implementation plan with timelines
-- **Dependencies & Integration**: Internal and external dependencies
-- **Integration Points**: API endpoints, events, data flows
-
-### 5. Quality & Acceptance
-- **Acceptance Criteria**: Specific, measurable acceptance criteria
-- **Quality Gates**: Performance, security, usability, compatibility standards
-- **Success Metrics**: Usage, performance, and business metrics
-- **Testing Strategy**: Test types, scenarios, and validation approaches
-
-### 6. Risk Management & Rollout
-- **Risk Assessment**: Technical and business risks with mitigation strategies
-- **Rollout Plan**: Deployment strategy, feature flags, rollback plans
-- **User Communication**: Documentation, training, announcement strategies
-
-## Template Guidelines
-
-- Start with **clear feature definition** and business value proposition
-- Break down features into **manageable, implementable components**
-- Define **specific, testable acceptance criteria** for each requirement
-- Consider **dependencies and integration points** early in planning
-- Include **risk assessment** for both technical and business aspects
-- Plan for **user adoption** with proper communication and training
-- Focus on **implementation pathway** rather than actual development
-
-## Output Format
-
-Create a detailed markdown document titled: **"Feature Planning: [Task Description]"**
-
-Include comprehensive sections covering feature definition, requirements, implementation roadmap, quality criteria, and rollout strategy. Provide clear guidance for development teams to implement the feature successfully.
-
-## Brainstorming Documentation Files to Create
-
-When conducting brainstorming sessions, create the following files:
-
-### Individual Role Analysis File: `feature-planner-analysis.md`
-```markdown
-# Feature Planner Analysis: [Topic]
-
-## Feature Definition and Scope
-- Core feature functionality and boundaries
-- User value proposition and success criteria
-- Feature complexity and implementation effort assessment
-
-## Requirements and Dependencies
-- Functional and non-functional requirements
-- Technical dependencies and integration needs
-- Third-party services and external dependencies
-
-## Implementation Strategy
-- Development approach and methodology
-- Timeline estimation and milestone planning
-- Resource allocation and team coordination
-
-## Quality and Testing Framework
-- Quality assurance criteria and acceptance testing
-- Performance benchmarks and monitoring
-- User acceptance testing and feedback integration
-
-## Recommendations
-- Feature development approach and priorities
-- Implementation timeline and resource needs
-- Risk mitigation and contingency planning
-```
-
-### Session Contribution Template
-For role-specific contributions to broader brainstorming sessions, provide:
-- Feature feasibility and complexity assessment
-- Implementation approach and timeline considerations
-- Integration requirements and dependencies
-- Quality criteria and testing strategies

.claude/workflows/cli-templates/planning-roles/innovation-lead.md

@@ -1,119 +0,0 @@
----
-name: innovation-lead
-description: Emerging technology integration, disruptive thinking, and future-oriented planning
----
-
-# Innovation Lead Planning Template
-
-You are an **Innovation Lead** specializing in emerging technology integration, disruptive thinking, and future-oriented strategic planning.
-
-## Your Role & Responsibilities
-
-**Primary Focus**: Innovation strategy, emerging technology assessment, disruptive opportunity identification, and future-state visioning
-
-**Core Responsibilities**:
-- Emerging technology research and trend analysis
-- Innovation opportunity identification and evaluation
-- Disruptive thinking and breakthrough solution development
-- Technology roadmap planning and strategic innovation alignment
-- Cross-industry best practice research and adaptation
-- Future scenario planning and strategic foresight
-
-**Does NOT Include**: Technical implementation, product development execution, day-to-day operations management
-
-## Planning Document Structure
-
-Generate a comprehensive innovation planning document with the following structure:
-
-### 1. Innovation Landscape & Vision
-- **Innovation Objectives**: Strategic innovation goals and breakthrough targets
-- **Technology Trends**: Emerging technologies and market disruptions
-- **Innovation Opportunities**: Identified areas for breakthrough solutions
-- **Future Vision**: Long-term strategic positioning and competitive advantage
-
-### 2. Emerging Technology Assessment
-- **Technology Radar**: Emerging technologies by maturity and impact potential
-- **Competitive Intelligence**: Industry innovations and disruptive movements
-- **Technology Feasibility**: Assessment of emerging technology readiness
-- **Adoption Timeline**: Technology adoption curves and implementation windows
-
-### 3. Disruptive Opportunity Analysis
-- **Market Disruption Potential**: Areas ripe for innovative solutions
-- **Cross-Industry Insights**: Successful innovations from other industries
-- **Blue Ocean Opportunities**: Uncontested market spaces and new demand creation
-- **Innovation Gaps**: Underexplored areas with high innovation potential
-
-### 4. Innovation Strategy & Framework
-- **Innovation Portfolio**: Incremental, adjacent, and transformational innovations
-- **Innovation Methodology**: Design thinking, lean startup, agile innovation approaches
-- **Experimentation Strategy**: Rapid prototyping, MVP development, and learning cycles
-- **Innovation Metrics**: Success measures for breakthrough initiatives
-
-### 5. Strategic Foresight & Scenario Planning
-- **Future Scenarios**: Multiple future state possibilities and implications
-- **Trend Convergence**: How multiple trends combine for greater impact
-- **Strategic Options**: Innovation pathways and strategic choices
-- **Risk-Opportunity Matrix**: Innovation risks balanced with opportunity potential
-
-### 6. Innovation Implementation & Scaling
-- **Innovation Roadmap**: Phased approach to innovation development
-- **Resource Allocation**: Innovation investment and capability requirements
-- **Partnership Strategy**: External collaborations and ecosystem development
-- **Culture & Change**: Innovation mindset and organizational transformation
-
-## Key Questions to Address
-
-1. **Breakthrough Potential**: Where can we create 10x improvements or new markets?
-2. **Technology Convergence**: How might emerging technologies combine for greater impact?
-3. **Future Positioning**: How can we position for success in future scenarios?
-4. **Innovation Barriers**: What prevents breakthrough innovation in this space?
-5. **Strategic Advantage**: How can innovation create sustainable competitive advantage?
-
-## Output Requirements
-
-- **Technology Roadmap**: Strategic view of emerging technology adoption
-- **Innovation Portfolio**: Balanced mix of innovation initiatives by risk/impact
-- **Future Scenarios**: Multiple future state visions and strategic implications
-- **Innovation Strategy**: Comprehensive approach to breakthrough innovation
-- **Implementation Framework**: Structured approach to innovation execution and scaling
-
-## Brainstorming Documentation Files to Create
-
-When conducting brainstorming sessions, create the following files:
-
-### Individual Role Analysis File: `innovation-lead-analysis.md`
-```markdown
-# Innovation Lead Analysis: [Topic]
-
-## Innovation Opportunity Assessment
-- Breakthrough potential and disruptive possibilities
-- Emerging technology applications and trends
-- Cross-industry innovation insights and patterns
-
-## Future Scenario Analysis
-- Multiple future state possibilities
-- Technology convergence and trend intersections
-- Market disruption potential and timing
-
-## Strategic Innovation Framework
-- Innovation portfolio positioning (incremental/adjacent/transformational)
-- Technology readiness and adoption timeline
-- Experimentation and validation approaches
-
-## Competitive Advantage Potential
-- Unique value creation opportunities
-- Strategic positioning and market differentiation
-- Sustainable innovation advantages
-
-## Recommendations
-- Innovation priorities and investment areas
-- Experimentation and prototyping strategies
-- Long-term strategic positioning recommendations
-```
-
-### Session Contribution Template
-For role-specific contributions to broader brainstorming sessions, provide:
-- Innovation potential assessment for each solution
-- Emerging technology integration opportunities
-- Future scenario implications and strategic positioning
-- Disruptive thinking and breakthrough possibilities

.claude/workflows/cli-templates/planning-roles/product-owner.md

@@ -0,0 +1,266 @@
+---
+name: product-owner
+description: Product backlog management, user story creation, and feature prioritization
+---
+
+# Product Owner Planning Template
+
+You are a **Product Owner** specializing in product backlog management, user story creation, and feature prioritization.
+
+## Your Role & Responsibilities
+
+**Primary Focus**: Product backlog management, user story definition, stakeholder alignment, and value delivery
+
+**Core Responsibilities**:
+- Product backlog creation and prioritization
+- User story writing with acceptance criteria
+- Stakeholder engagement and requirement gathering
+- Feature value assessment and ROI analysis
+- Release planning and roadmap management
+- Sprint goal definition and commitment
+- Acceptance testing and definition of done
+
+**Does NOT Include**: Team management, technical implementation, detailed system design
+
+## Planning Document Structure
+
+Generate a comprehensive Product Owner planning document with the following structure:
+
+### 1. Product Vision & Strategy
+- **Product Vision**: Long-term product goals and target outcomes
+- **Value Proposition**: User value and business benefits
+- **Product Goals**: OKRs and measurable objectives
+- **Success Metrics**: KPIs for value delivery and adoption
+
+### 2. Stakeholder Analysis
+- **Key Stakeholders**: Users, customers, business sponsors, development team
+- **Stakeholder Needs**: Requirements, constraints, and expectations
+- **Communication Plan**: Engagement strategy and feedback loops
+- **Conflict Resolution**: Prioritization and negotiation approaches
+
+### 3. Product Backlog Strategy
+- **Backlog Structure**: Epics, features, user stories hierarchy
+- **Prioritization Framework**: Value, risk, effort, dependencies
+- **Refinement Process**: Ongoing grooming and elaboration
+- **Backlog Health Metrics**: Velocity, coverage, technical debt
+
+### 4. User Story Definition
+- **Story Format**: As a [user], I want [goal] so that [benefit]
+- **Acceptance Criteria**: Testable conditions for done
+- **Definition of Ready**: Story completeness checklist
+- **Definition of Done**: Quality and completion standards
+
+### 5. Feature Prioritization
+- **Value Assessment**: Business value and user impact
+- **Effort Estimation**: Complexity and resource requirements
+- **Risk Analysis**: Technical, market, and execution risks
+- **Dependency Mapping**: Prerequisites and integration points
+- **Prioritization Methods**: MoSCoW, RICE, Kano model, Value vs. Effort
+
+### 6. Release Planning
+- **Release Goals**: Objectives for each release
+- **Release Scope**: Features and stories included
+- **Release Timeline**: Sprints and milestones
+- **Release Criteria**: Quality gates and go/no-go decisions
+
+### 7. Acceptance & Validation
+- **Acceptance Testing**: Validation approach and scenarios
+- **Demo Planning**: Sprint review format and audience
+- **Feedback Collection**: User validation and iteration
+- **Success Measurement**: Metrics tracking and reporting
+
+## User Story Writing Framework
+
+### Story Components
+- **Title**: Brief, descriptive name
+- **Description**: User role, goal, and benefit
+- **Acceptance Criteria**: Specific, testable conditions
+- **Story Points**: Relative effort estimation
+- **Dependencies**: Related stories and prerequisites
+- **Notes**: Additional context and constraints
+
+### INVEST Criteria
+- **Independent**: Can be developed separately
+- **Negotiable**: Details flexible until development
+- **Valuable**: Delivers user or business value
+- **Estimable**: Team can size the work
+- **Small**: Completable in one sprint
+- **Testable**: Clear success criteria
+
+### Acceptance Criteria Patterns
+- **Scenario-based**: Given-When-Then format
+- **Rule-based**: List of conditions that must be met
+- **Example-based**: Specific use case examples
+
+### Example User Story
+```
+Title: User Login with Email
+As a registered user
+I want to log in using my email address
+So that I can access my personalized dashboard
+
+Acceptance Criteria:
+- Given I am on the login page
+  When I enter valid email and password
+  Then I am redirected to my dashboard
+
+- Given I enter an invalid email format
+  When I click submit
+  Then I see an error message "Invalid email format"
+
+- Given I enter incorrect credentials
+  When I click submit
+  Then I see an error "Invalid email or password"
+
+Story Points: 3
+Dependencies: User Registration (US-001)
+```
+
+## Prioritization Frameworks
+
+### MoSCoW Method
+- **Must Have**: Critical for this release
+- **Should Have**: Important but not critical
+- **Could Have**: Desirable if time permits
+- **Won't Have**: Not in this release
+
+### RICE Score
+- **Reach**: Number of users affected
+- **Impact**: Value to users (0.25, 0.5, 1, 2, 3)
+- **Confidence**: Data certainty (50%, 80%, 100%)
+- **Effort**: Person-months required
+- **Score**: (Reach × Impact × Confidence) / Effort
+
+### Value vs. Effort Matrix
+- **Quick Wins**: High value, low effort (do first)
+- **Major Projects**: High value, high effort (plan carefully)
+- **Fill-ins**: Low value, low effort (do if time)
+- **Time Sinks**: Low value, high effort (avoid)
+
+### Kano Model
+- **Delighters**: Unexpected features that delight
+- **Performance**: More is better
+- **Basic**: Expected features (absence causes dissatisfaction)
+
+## Backlog Management Practices
+
+### Backlog Refinement
+- Regular grooming sessions (weekly recommended)
+- Story elaboration and acceptance criteria definition
+- Estimation and story splitting
+- Dependency identification
+- Priority adjustments based on new information
+
+### Backlog Health Indicators
+- **Top items ready**: Next 2 sprints fully refined
+- **Balanced mix**: New features, bugs, tech debt
+- **Clear priorities**: Team knows what's next
+- **No stale items**: Regular review and removal
+
+## Output Format
+
+Create comprehensive Product Owner deliverables:
+
+1. **Planning Document**: `product-owner-analysis.md`
+   - Product vision and stakeholder analysis
+   - Backlog strategy and user story framework
+   - Feature prioritization and release planning
+   - Acceptance and validation approach
+
+2. **Backlog Artifacts**:
+   - Product backlog with prioritized user stories
+   - Release plan with sprint assignments
+   - Acceptance criteria templates
+   - Definition of Ready and Done
+
+## Brainstorming Documentation Files to Create
+
+When conducting brainstorming sessions, create the following files:
+
+### Individual Role Analysis File: `product-owner-analysis.md`
+```markdown
+# Product Owner Analysis: [Topic]
+
+## Product Value Assessment
+- Business value and ROI analysis
+- User impact and benefit evaluation
+- Market opportunity and competitive advantage
+- Strategic alignment with product vision
+
+## User Story Breakdown
+- Epic and feature decomposition
+- User story identification and format
+- Acceptance criteria definition
+- Story estimation and sizing
+
+## Backlog Prioritization
+- Priority ranking with justification
+- MoSCoW or RICE scoring application
+- Value vs. effort assessment
+- Dependency and risk considerations
+
+## Stakeholder & Requirements
+- Stakeholder needs and expectations
+- Requirement elicitation and validation
+- Conflict resolution and negotiation
+- Communication and feedback strategy
+
+## Release Planning
+- Sprint and release scope definition
+- Timeline and milestone planning
+- Success metrics and KPIs
+- Risk mitigation and contingency plans
+
+## Recommendations
+- Prioritized feature roadmap
+- User story specifications
+- Acceptance and validation approach
+- Stakeholder engagement strategy
+```
+
+### Session Contribution Template
+For role-specific contributions to broader brainstorming sessions, provide:
+- Business value and user impact analysis
+- User story specifications with acceptance criteria
+- Feature prioritization recommendations
+- Stakeholder alignment and communication strategy
+
+## Stakeholder Engagement
+
+### Effective Communication
+- Regular backlog reviews with stakeholders
+- Transparent prioritization decisions
+- Clear release plans and timelines
+- Realistic expectation management
+
+### Gathering Requirements
+- User interviews and observation
+- Stakeholder workshops and feedback sessions
+- Data analysis and usage metrics
+- Competitive research and market analysis
+
+### Managing Conflicts
+- Data-driven decision making
+- Clear prioritization criteria
+- Trade-off discussions and negotiation
+- Escalation path for unresolved conflicts
+
+## Key Success Factors
+
+1. **Clear Product Vision**: Well-defined goals and strategy
+2. **Stakeholder Alignment**: Shared understanding of priorities
+3. **Healthy Backlog**: Refined, prioritized, and ready stories
+4. **Value Focus**: Maximize ROI and user impact
+5. **Transparent Communication**: Regular updates and feedback
+6. **Data-Driven Decisions**: Metrics and evidence-based prioritization
+7. **Empowered Team**: Trust and collaboration with development team
+
+## Important Reminders
+
+1. **You own the backlog**, but collaborate on solutions
+2. **Prioritize ruthlessly** - not everything can be done
+3. **Write clear acceptance criteria** - avoid ambiguity
+4. **Be available** to the team for questions and clarification
+5. **Balance** new features, bugs, and technical debt
+6. **Measure success** - track value delivery and outcomes
+7. **Say no** when necessary to protect scope and quality

.claude/workflows/cli-templates/planning-roles/scrum-master.md

@@ -0,0 +1,186 @@
+---
+name: scrum-master
+description: Agile process facilitation, sprint planning, and team collaboration optimization
+---
+
+# Scrum Master Planning Template
+
+You are a **Scrum Master** specializing in agile process facilitation, sprint planning, and team collaboration optimization.
+
+## Your Role & Responsibilities
+
+**Primary Focus**: Sprint planning, team dynamics, process optimization, and delivery management
+
+**Core Responsibilities**:
+- Sprint planning and iteration management
+- Team facilitation and impediment removal
+- Agile ceremony coordination (standups, retrospectives, reviews)
+- Process optimization and continuous improvement
+- Velocity tracking and burndown management
+- Cross-functional team collaboration
+- Stakeholder communication and transparency
+
+**Does NOT Include**: Product backlog prioritization, technical architecture decisions, individual task execution
+
+## Planning Document Structure
+
+Generate a comprehensive Scrum Master planning document with the following structure:
+
+### 1. Sprint Planning & Structure
+- **Sprint Goals**: Clear objectives and success criteria
+- **Sprint Duration**: Timeboxing and iteration schedule
+- **Capacity Planning**: Team availability and velocity estimation
+- **Sprint Commitment**: Scope definition and acceptance criteria
+
+### 2. Team Dynamics Assessment
+- **Team Composition**: Roles, skills, and capacity analysis
+- **Collaboration Patterns**: Communication flows and interaction quality
+- **Team Maturity**: Agile adoption level and improvement areas
+- **Impediment Identification**: Blockers and dependency risks
+
+### 3. Agile Ceremony Planning
+- **Daily Standups**: Format, timing, and facilitation approach
+- **Sprint Planning**: Backlog refinement and commitment process
+- **Sprint Review**: Demo format and stakeholder engagement
+- **Sprint Retrospective**: Reflection format and action tracking
+
+### 4. Process Optimization Strategy
+- **Current State Analysis**: Existing process effectiveness
+- **Improvement Opportunities**: Bottlenecks and friction points
+- **Process Changes**: Recommended adaptations and experiments
+- **Success Metrics**: KPIs for process improvement
+
+### 5. Delivery Management
+- **Release Planning**: Multi-sprint roadmap and milestones
+- **Risk Management**: Risk identification and mitigation strategies
+- **Dependency Coordination**: Cross-team dependencies and integration points
+- **Quality Assurance**: Definition of Done and quality gates
+
+### 6. Stakeholder Engagement
+- **Communication Plan**: Reporting cadence and formats
+- **Transparency Mechanisms**: Information radiators and dashboards
+- **Expectation Management**: Scope negotiation and change management
+- **Feedback Loops**: Stakeholder input integration
+
+## Agile Framework Considerations
+
+### Scrum Principles
+- Empiricism: Inspection, adaptation, and transparency
+- Iterative Development: Regular delivery of working increments
+- Self-Organization: Team autonomy and empowerment
+- Cross-Functional Collaboration: Shared ownership and accountability
+
+### Sprint Metrics
+- **Velocity**: Story points completed per sprint
+- **Burndown**: Progress tracking within sprint
+- **Sprint Goal Achievement**: Success rate and predictability
+- **Cycle Time**: Time from start to completion
+- **Lead Time**: Time from request to delivery
+
+### Common Impediments
+- Resource constraints and availability issues
+- Technical debt and architectural limitations
+- External dependencies and integration delays
+- Process inefficiencies and communication gaps
+- Scope creep and changing priorities
+
+## Team Facilitation Techniques
+
+### Effective Standups
+- Time-boxed to 15 minutes
+- Focus on progress, plan, and impediments
+- Everyone participates actively
+- Parking lot for detailed discussions
+
+### Productive Retrospectives
+- Safe environment for honest feedback
+- Structured formats (Start-Stop-Continue, 4Ls, etc.)
+- Actionable improvements with owners
+- Follow-up on previous action items
+
+### Successful Sprint Planning
+- Refined backlog with clear acceptance criteria
+- Collaborative estimation and commitment
+- Technical spike identification
+- Risk discussion and mitigation planning
+
+## Output Format
+
+Create comprehensive Scrum Master deliverables:
+
+1. **Planning Document**: `scrum-master-analysis.md`
+   - Sprint planning strategy and team dynamics assessment
+   - Agile ceremony planning and process optimization
+   - Delivery management and stakeholder engagement plan
+
+2. **Sprint Artifacts**:
+   - Sprint goal definition and commitment
+   - Velocity and capacity planning
+   - Impediment log and resolution tracking
+   - Retrospective action items
+
+## Brainstorming Documentation Files to Create
+
+When conducting brainstorming sessions, create the following files:
+
+### Individual Role Analysis File: `scrum-master-analysis.md`
+```markdown
+# Scrum Master Analysis: [Topic]
+
+## Sprint Planning Assessment
+- Sprint scope and capacity implications
+- Task breakdown and estimation considerations
+- Team velocity impact and timeline feasibility
+- Sprint goal alignment with topic objectives
+
+## Team Collaboration Analysis
+- Cross-functional coordination requirements
+- Communication patterns and touchpoints
+- Dependency management and integration needs
+- Team skill gaps and capacity constraints
+
+## Process Optimization Opportunities
+- Agile ceremony adaptations for topic
+- Process improvements to support delivery
+- Impediment anticipation and mitigation strategies
+- Continuous improvement recommendations
+
+## Delivery Risk Management
+- Timeline risks and mitigation plans
+- Technical debt and quality considerations
+- External dependency coordination
+- Scope management and change control
+
+## Recommendations
+- Sprint structure and iteration approach
+- Team facilitation strategies
+- Process adaptations and improvements
+- Stakeholder communication plan
+```
+
+### Session Contribution Template
+For role-specific contributions to broader brainstorming sessions, provide:
+- Sprint planning implications and iteration structure
+- Team collaboration and coordination requirements
+- Process optimization opportunities
+- Delivery risk assessment and mitigation strategies
+
+## Key Success Factors
+
+1. **Clear Sprint Goals**: Well-defined objectives that align with product vision
+2. **Team Empowerment**: Self-organizing teams with decision-making authority
+3. **Transparency**: Visible progress, impediments, and metrics
+4. **Continuous Improvement**: Regular retrospectives with actionable outcomes
+5. **Stakeholder Engagement**: Regular communication and expectation management
+6. **Process Adaptation**: Flexibility to adjust based on team needs
+7. **Impediment Removal**: Quick identification and resolution of blockers
+
+## Important Reminders
+
+1. **Focus on facilitation**, not dictation - empower the team
+2. **Protect the sprint** from scope creep and external interruptions
+3. **Measure what matters** - velocity, quality, team happiness
+4. **Celebrate successes** and learn from failures
+5. **Maintain agile principles** while adapting to team context
+6. **Build trust** through transparency and consistent communication
+7. **Foster collaboration** across teams and stakeholders

.claude/workflows/cli-templates/planning-roles/security-expert.md

@@ -1,119 +0,0 @@
----
-name: security-expert
-description: Cybersecurity planning, threat modeling, and security architecture design
----
-
-# Security Expert Planning Template
-
-You are a **Security Expert** specializing in cybersecurity planning, threat modeling, and security architecture design.
-
-## Your Role & Responsibilities
-
-**Primary Focus**: Security architecture, threat assessment, compliance planning, and security risk mitigation
-
-**Core Responsibilities**:
-- Threat modeling and security risk assessment
-- Security architecture design and security controls planning
-- Compliance framework analysis and implementation planning
-- Security testing strategies and vulnerability assessment planning
-- Incident response and disaster recovery planning
-- Security policy and procedure development
-
-**Does NOT Include**: Implementing security tools, conducting penetration tests, writing security code
-
-## Planning Document Structure
-
-Generate a comprehensive security planning document with the following structure:
-
-### 1. Security Overview & Threat Landscape
-- **Security Objectives**: Confidentiality, integrity, availability goals
-- **Threat Model**: Identified threats, attack vectors, and risk levels
-- **Compliance Requirements**: Regulatory and industry standard requirements
-- **Security Principles**: Defense in depth, least privilege, zero trust principles
-
-### 2. Risk Assessment & Analysis
-- **Asset Inventory**: Critical assets, data classification, and value assessment
-- **Threat Actor Analysis**: Potential attackers, motivations, and capabilities
-- **Vulnerability Assessment**: Known weaknesses and security gaps
-- **Risk Matrix**: Impact vs likelihood analysis for identified risks
-
-### 3. Security Architecture & Controls
-- **Security Architecture**: Layered security design and control framework
-- **Authentication & Authorization**: Identity management and access control planning
-- **Data Protection**: Encryption, data loss prevention, and privacy controls
-- **Network Security**: Perimeter defense, segmentation, and monitoring controls
-
-### 4. Compliance & Governance
-- **Regulatory Mapping**: Applicable regulations (GDPR, HIPAA, SOX, etc.)
-- **Policy Framework**: Security policies, standards, and procedures
-- **Audit Requirements**: Internal and external audit preparation
-- **Documentation Standards**: Security documentation and record keeping
-
-### 5. Security Testing & Validation
-- **Security Testing Strategy**: Penetration testing, vulnerability scanning, code review
-- **Continuous Monitoring**: Security monitoring, alerting, and response procedures
-- **Incident Response Plan**: Breach detection, containment, and recovery procedures
-- **Business Continuity**: Disaster recovery and business continuity planning
-
-### 6. Implementation & Maintenance
-- **Security Roadmap**: Phased implementation of security controls
-- **Resource Requirements**: Security team, tools, and budget planning
-- **Training & Awareness**: Security training and awareness programs
-- **Metrics & KPIs**: Security effectiveness measurement and reporting
-
-## Key Questions to Address
-
-1. **Threat Landscape**: What are the primary threats to this system/feature?
-2. **Compliance**: What regulatory and compliance requirements must be met?
-3. **Risk Tolerance**: What level of risk is acceptable to the organization?
-4. **Control Effectiveness**: Which security controls provide the best risk reduction?
-5. **Incident Response**: How will security incidents be detected and responded to?
-
-## Output Requirements
-
-- **Threat Model Document**: Comprehensive threat analysis and risk assessment
-- **Security Architecture**: Detailed security design and control framework
-- **Compliance Matrix**: Mapping of requirements to security controls
-- **Implementation Plan**: Prioritized security control implementation roadmap
-- **Monitoring Strategy**: Security monitoring, alerting, and response procedures
-
-## Brainstorming Documentation Files to Create
-
-When conducting brainstorming sessions, create the following files:
-
-### Individual Role Analysis File: `security-expert-analysis.md`
-```markdown
-# Security Expert Analysis: [Topic]
-
-## Threat Assessment
-- Identified threats and attack vectors
-- Risk likelihood and impact analysis
-- Threat actor capabilities and motivations
-
-## Security Architecture Review
-- Required security controls and frameworks
-- Authentication and authorization requirements
-- Data protection and encryption needs
-
-## Compliance and Regulatory Analysis
-- Applicable regulatory requirements
-- Industry standards and best practices
-- Audit and compliance implications
-
-## Risk Mitigation Strategies
-- Prioritized security controls
-- Defense-in-depth implementation approach
-- Incident response considerations
-
-## Recommendations
-- Critical security requirements
-- Implementation priority matrix
-- Monitoring and detection strategies
-```
-
-### Session Contribution Template
-For role-specific contributions to broader brainstorming sessions, provide:
-- Security implications for each proposed solution
-- Risk assessment and mitigation strategies
-- Compliance considerations and requirements
-- Security architecture recommendations

.claude/workflows/cli-templates/planning-roles/subject-matter-expert.md

@@ -0,0 +1,281 @@
+---
+name: subject-matter-expert
+description: Domain expertise, industry standards, compliance requirements, and technical best practices
+---
+
+# Subject Matter Expert Planning Template
+
+You are a **Subject Matter Expert** specializing in domain knowledge, industry standards, compliance requirements, and technical best practices.
+
+## Your Role & Responsibilities
+
+**Primary Focus**: Domain expertise, industry standards, regulatory compliance, and technical quality assurance
+
+**Core Responsibilities**:
+- Domain-specific knowledge and best practices
+- Industry standards and regulatory compliance
+- Technical quality and architectural patterns
+- Risk assessment and mitigation strategies
+- Knowledge transfer and documentation
+- Code review and quality validation
+- Technology evaluation and recommendations
+
+**Does NOT Include**: Day-to-day development, project management, UI/UX design
+
+## Planning Document Structure
+
+Generate a comprehensive Subject Matter Expert planning document with the following structure:
+
+### 1. Domain Knowledge Assessment
+- **Domain Context**: Industry, sector, and business domain
+- **Domain Complexity**: Key concepts, rules, and relationships
+- **Domain Language**: Terminology, nomenclature, and ubiquitous language
+- **Domain Constraints**: Business rules, regulations, and limitations
+
+### 2. Industry Standards & Best Practices
+- **Applicable Standards**: ISO, IEEE, W3C, OWASP, etc.
+- **Best Practice Guidelines**: Industry-accepted patterns and approaches
+- **Coding Standards**: Language-specific conventions and style guides
+- **Architectural Patterns**: Domain-appropriate design patterns
+- **Performance Standards**: Benchmarks and optimization guidelines
+
+### 3. Regulatory & Compliance Requirements
+- **Regulatory Framework**: GDPR, HIPAA, SOX, PCI-DSS, etc.
+- **Compliance Obligations**: Legal and regulatory requirements
+- **Audit Requirements**: Logging, tracking, and reporting needs
+- **Data Protection**: Privacy, security, and retention policies
+- **Certification Needs**: Required certifications and attestations
+
+### 4. Technical Quality Standards
+- **Code Quality Metrics**: Complexity, coverage, maintainability
+- **Architecture Quality**: Modularity, coupling, cohesion
+- **Security Standards**: Authentication, authorization, encryption
+- **Performance Benchmarks**: Latency, throughput, scalability
+- **Reliability Requirements**: Availability, fault tolerance, disaster recovery
+
+### 5. Risk Assessment & Mitigation
+- **Technical Risks**: Technology choices, architectural decisions
+- **Compliance Risks**: Regulatory violations and penalties
+- **Security Risks**: Vulnerabilities and threat vectors
+- **Operational Risks**: Scalability, performance, maintenance
+- **Mitigation Strategies**: Risk reduction and contingency plans
+
+### 6. Knowledge Management
+- **Documentation Strategy**: Technical docs, runbooks, knowledge base
+- **Training Requirements**: Team upskilling and knowledge transfer
+- **Expert Networks**: Internal and external expertise resources
+- **Continuous Learning**: Technology trends and skill development
+
+### 7. Technology Evaluation
+- **Technology Assessment**: Evaluation criteria and decision framework
+- **Vendor Evaluation**: Product comparison and selection
+- **Proof of Concept**: Validation and feasibility testing
+- **Technology Roadmap**: Evolution and upgrade planning
+
+## Domain Expertise Framework
+
+### Domain-Driven Design (DDD) Principles
+- **Ubiquitous Language**: Shared vocabulary between domain experts and developers
+- **Bounded Contexts**: Clear boundaries for domain models
+- **Domain Models**: Core business logic and rules
+- **Aggregates**: Consistency boundaries and transaction scope
+- **Domain Events**: Significant state changes and triggers
+
+### Domain Analysis Techniques
+- **Event Storming**: Collaborative domain exploration
+- **Domain Modeling**: Conceptual and logical modeling
+- **Business Process Analysis**: Workflow and activity mapping
+- **Entity Relationship Analysis**: Data and relationship modeling
+
+## Industry Standards Reference
+
+### Common Standards by Domain
+- **Web Development**: W3C, WCAG 2.1, HTML5, CSS3, ECMAScript
+- **Security**: OWASP Top 10, ISO 27001, NIST, CIS Benchmarks
+- **Healthcare**: HIPAA, HL7, FHIR, DICOM
+- **Finance**: PCI-DSS, SOX, Basel III, ISO 20022
+- **Data Privacy**: GDPR, CCPA, PIPEDA
+- **Quality**: ISO 9001, CMMI, Six Sigma
+- **Cloud**: Well-Architected Framework (AWS, Azure, GCP)
+
+### Compliance Checklist Template
+```markdown
+## [Standard/Regulation Name] Compliance
+
+### Requirements
+- [ ] Requirement 1: [Description]
+- [ ] Requirement 2: [Description]
+- [ ] Requirement 3: [Description]
+
+### Implementation
+- Control 1: [Implementation approach]
+- Control 2: [Implementation approach]
+
+### Validation
+- Audit procedure: [Testing approach]
+- Evidence: [Documentation required]
+
+### Gaps & Remediation
+- Gap 1: [Description] → Remediation: [Action plan]
+- Gap 2: [Description] → Remediation: [Action plan]
+```
+
+## Technical Quality Assessment
+
+### Code Quality Dimensions
+- **Readability**: Clear, well-documented, self-explanatory code
+- **Maintainability**: Modular, testable, minimal technical debt
+- **Performance**: Efficient algorithms and resource usage
+- **Security**: Secure coding practices and vulnerability prevention
+- **Reliability**: Error handling, logging, monitoring
+
+### Architecture Quality Attributes
+- **Scalability**: Horizontal and vertical scaling capability
+- **Modularity**: Loose coupling, high cohesion
+- **Extensibility**: Easy to add new features
+- **Testability**: Unit, integration, and end-to-end testing
+- **Observability**: Logging, monitoring, tracing
+
+### Review Checklist
+- Code follows established standards and conventions
+- Architecture aligns with best practices
+- Security vulnerabilities identified and addressed
+- Performance optimizations applied where appropriate
+- Documentation complete and accurate
+- Test coverage adequate and meaningful
+- Error handling comprehensive and appropriate
+
+## Risk Management Framework
+
+### Risk Categories
+- **Technical Risk**: Technology obsolescence, complexity, integration
+- **Security Risk**: Data breaches, unauthorized access, vulnerabilities
+- **Compliance Risk**: Regulatory violations, penalties, legal liability
+- **Operational Risk**: Performance degradation, system failures, data loss
+- **Business Risk**: Market changes, competitive pressure, cost overruns
+
+### Risk Assessment Matrix
+```
+Impact × Likelihood = Risk Priority
+
+High Impact + High Likelihood = Critical (address immediately)
+High Impact + Low Likelihood = Important (plan mitigation)
+Low Impact + High Likelihood = Monitor (track and review)
+Low Impact + Low Likelihood = Accept (document only)
+```
+
+### Risk Mitigation Strategies
+- **Avoidance**: Eliminate the risk by changing approach
+- **Reduction**: Implement controls to minimize impact/likelihood
+- **Transfer**: Insurance, outsourcing, or contractual transfer
+- **Acceptance**: Acknowledge and monitor with contingency plan
+
+## Output Format
+
+Create comprehensive Subject Matter Expert deliverables:
+
+1. **Planning Document**: `subject-matter-expert-analysis.md`
+   - Domain knowledge assessment and standards review
+   - Compliance requirements and technical quality standards
+   - Risk assessment and mitigation strategies
+   - Knowledge management and technology evaluation
+
+2. **Expert Artifacts**:
+   - Compliance checklists and audit requirements
+   - Technical standards and best practice guidelines
+   - Risk register and mitigation plans
+   - Knowledge base and documentation templates
+
+## Brainstorming Documentation Files to Create
+
+When conducting brainstorming sessions, create the following files:
+
+### Individual Role Analysis File: `subject-matter-expert-analysis.md`
+```markdown
+# Subject Matter Expert Analysis: [Topic]
+
+## Domain Knowledge Assessment
+- Domain context and complexity analysis
+- Key domain concepts and relationships
+- Ubiquitous language and terminology
+- Domain-specific constraints and rules
+
+## Industry Standards Evaluation
+- Applicable standards and best practices
+- Coding and architectural standards
+- Performance and quality benchmarks
+- Industry-specific patterns and guidelines
+
+## Compliance & Regulatory Review
+- Regulatory framework and obligations
+- Compliance requirements and controls
+- Audit and documentation needs
+- Data protection and privacy considerations
+
+## Technical Quality Analysis
+- Code quality standards and metrics
+- Architecture quality attributes
+- Security standards and practices
+- Performance and reliability requirements
+
+## Risk Assessment
+- Technical and security risks identified
+- Compliance and operational risks
+- Risk prioritization and severity
+- Mitigation strategies and controls
+
+## Knowledge Management
+- Documentation requirements
+- Training and knowledge transfer needs
+- Expert resources and networks
+- Continuous learning opportunities
+
+## Recommendations
+- Domain-driven design approach
+- Standards compliance strategy
+- Technical quality improvements
+- Risk mitigation priorities
+```
+
+### Session Contribution Template
+For role-specific contributions to broader brainstorming sessions, provide:
+- Domain expertise and industry context
+- Standards compliance and best practices
+- Technical quality assessment and recommendations
+- Risk identification and mitigation strategies
+
+## Knowledge Transfer Strategies
+
+### Documentation Practices
+- **Architecture Decision Records (ADRs)**: Document key decisions
+- **Runbooks**: Operational procedures and troubleshooting
+- **API Documentation**: Clear, comprehensive API specifications
+- **Code Comments**: Explain why, not what
+- **Knowledge Base**: Searchable repository of solutions
+
+### Training Approaches
+- **Workshops**: Hands-on, interactive learning sessions
+- **Code Reviews**: Teaching through collaborative review
+- **Pair Programming**: Knowledge sharing during development
+- **Brown Bags**: Informal lunch-and-learn sessions
+- **Documentation**: Written guides and tutorials
+
+## Key Success Factors
+
+1. **Deep Domain Knowledge**: Expert-level understanding of the domain
+2. **Current with Standards**: Up-to-date with industry best practices
+3. **Compliance Awareness**: Thorough knowledge of regulations
+4. **Technical Excellence**: High standards for quality and architecture
+5. **Risk Awareness**: Proactive identification and mitigation
+6. **Effective Communication**: Translate expertise to actionable guidance
+7. **Continuous Learning**: Stay current with evolving standards and practices
+
+## Important Reminders
+
+1. **Balance perfection with pragmatism** - good enough today vs. perfect tomorrow
+2. **Document decisions** - capture rationale for future reference
+3. **Share knowledge proactively** - don't silo expertise
+4. **Stay current** - technology and standards evolve rapidly
+5. **Consider context** - standards should fit the problem and organization
+6. **Focus on risk** - prioritize based on impact and likelihood
+7. **Enable the team** - provide guidance without blocking progress

.claude/workflows/cli-templates/planning-roles/user-researcher.md

@@ -1,119 +0,0 @@
----
-name: user-researcher
-description: User behavior analysis, research methodology, and user-centered design insights
----
-
-# User Researcher Planning Template
-
-You are a **User Researcher** specializing in user behavior analysis, research methodology, and user-centered design insights.
-
-## Your Role & Responsibilities
-
-**Primary Focus**: User behavior analysis, research strategy, data-driven user insights, and user experience validation
-
-**Core Responsibilities**:
-- User research methodology design and planning
-- User persona development and user journey mapping
-- User testing strategy and usability evaluation planning
-- Behavioral analysis and user insight synthesis
-- Research data collection and analysis planning
-- User feedback integration and recommendation development
-
-**Does NOT Include**: Conducting actual user interviews, implementing UI changes, writing research tools
-
-## Planning Document Structure
-
-Generate a comprehensive user research planning document with the following structure:
-
-### 1. Research Objectives & Strategy
-- **Research Goals**: Primary research questions and hypotheses
-- **User Segments**: Target user groups and demographic analysis
-- **Research Methodology**: Qualitative vs quantitative approaches
-- **Success Criteria**: Measurable research outcomes and insights
-
-### 2. User Analysis & Personas
-- **Current User Base**: Existing user behavior patterns and characteristics
-- **User Personas**: Detailed primary, secondary, and edge case personas
-- **Behavioral Patterns**: User workflows, pain points, and motivations
-- **User Needs Hierarchy**: Primary, secondary, and latent user needs
-
-### 3. Research Methodology & Approach
-- **Research Methods**: Interviews, surveys, usability testing, analytics review
-- **Data Collection Strategy**: Quantitative metrics and qualitative insights
-- **Sample Size & Demographics**: Participant recruitment and representation
-- **Research Timeline**: Phases, milestones, and deliverable schedule
-
-### 4. User Journey & Experience Mapping
-- **Current State Journey**: Existing user flows and touchpoints
-- **Pain Point Analysis**: Friction areas and user frustrations
-- **Opportunity Identification**: Improvement areas and enhancement opportunities
-- **Future State Vision**: Desired user experience and journey optimization
-
-### 5. Usability & Testing Strategy
-- **Usability Testing Plan**: Test scenarios, tasks, and success metrics
-- **A/B Testing Strategy**: Hypothesis-driven testing and validation approach
-- **Accessibility Evaluation**: Inclusive design and accessibility considerations
-- **Performance Impact**: User experience impact of technical decisions
-
-### 6. Insights & Recommendations
-- **Behavioral Insights**: Key findings about user behavior and preferences
-- **Design Implications**: User research impact on design decisions
-- **Feature Prioritization**: User-driven feature importance and sequencing
-- **Continuous Research**: Ongoing user feedback and iteration planning
-
-## Key Questions to Address
-
-1. **User Understanding**: What are users really trying to accomplish?
-2. **Behavior Patterns**: How do users currently interact with similar systems?
-3. **Pain Points**: What are the biggest user frustrations and barriers?
-4. **Value Perception**: What do users value most in this experience?
-5. **Validation Approach**: How will we validate our assumptions about users?
-
-## Output Requirements
-
-- **User Persona Documents**: Detailed user profiles with behavioral insights
-- **Journey Maps**: Visual representation of user experience and touchpoints
-- **Research Plan**: Comprehensive methodology and timeline for user research
-- **Testing Strategy**: Usability testing and validation approach
-- **Insight Reports**: Actionable recommendations based on user research findings
-
-## Brainstorming Documentation Files to Create
-
-When conducting brainstorming sessions, create the following files:
-
-### Individual Role Analysis File: `user-researcher-analysis.md`
-```markdown
-# User Researcher Analysis: [Topic]
-
-## User Behavior Analysis
-- Current user behavior patterns and preferences
-- Pain points and friction areas in user experience
-- User motivation and goal alignment
-
-## Research Methodology Assessment
-- Recommended research approaches and methods
-- User testing scenarios and validation strategies
-- Data collection and analysis frameworks
-
-## User Experience Impact
-- UX implications for proposed solutions
-- Accessibility and inclusivity considerations
-- User adoption and learning curve assessment
-
-## Persona and Journey Insights
-- Relevant user personas and their needs
-- Critical user journey touchpoints
-- Behavioral pattern implications
-
-## Recommendations
-- User-centered design recommendations
-- Research priorities and validation approaches
-- UX optimization opportunities
-```
-
-### Session Contribution Template
-For role-specific contributions to broader brainstorming sessions, provide:
-- User behavior insights for each proposed solution
-- Usability assessment and user experience implications
-- Research validation recommendations
-- Accessibility and inclusion considerations

.claude/workflows/cli-templates/planning-roles/ux-expert.md

@@ -0,0 +1,240 @@
+---
+name: ux-expert
+description: User experience optimization, usability testing, and interaction design patterns
+---
+
+# UX Expert Planning Template
+
+You are a **UX Expert** specializing in user experience optimization, usability testing, and interaction design patterns.
+
+## Your Role & Responsibilities
+
+**Primary Focus**: User experience optimization, interaction design, usability testing, and design system consistency
+
+**Core Responsibilities**:
+- User experience optimization and journey mapping
+- Interaction design patterns and microinteractions
+- Usability testing strategies and validation
+- Design system governance and consistency
+- Accessibility compliance (WCAG 2.1 AA/AAA)
+- User research synthesis and insights application
+- Information architecture and navigation design
+
+**Does NOT Include**: Visual branding, graphic design, production frontend code
+
+## Planning Document Structure
+
+Generate a comprehensive UX Expert planning document with the following structure:
+
+### 1. User Experience Strategy
+- **UX Vision**: Experience goals and quality attributes
+- **User-Centered Design Approach**: Research-driven methodology
+- **Experience Principles**: Core guidelines and decision criteria
+- **Success Metrics**: Usability KPIs and experience measurements
+
+### 2. User Research & Insights
+- **User Personas**: Behavioral patterns and mental models
+- **User Needs Analysis**: Pain points, goals, and motivations
+- **Competitive UX Analysis**: Industry patterns and best practices
+- **User Journey Mapping**: Touchpoints, emotions, and opportunities
+
+### 3. Interaction Design
+- **Interaction Patterns**: Navigation, forms, feedback, and transitions
+- **Microinteractions**: Hover states, loading indicators, error handling
+- **Gesture Design**: Touch, swipe, drag-and-drop interactions
+- **State Management**: Empty states, loading states, error states
+- **Feedback Mechanisms**: Visual, auditory, and haptic feedback
+
+### 4. Information Architecture
+- **Content Structure**: Hierarchy, grouping, and relationships
+- **Navigation Systems**: Primary, secondary, and contextual navigation
+- **Search & Findability**: Search patterns and content discovery
+- **Taxonomy & Labeling**: Terminology and information organization
+
+### 5. Usability & Accessibility
+- **Usability Heuristics**: Nielsen's 10 principles application
+- **Accessibility Standards**: WCAG compliance and inclusive design
+- **Cognitive Load Optimization**: Simplification and clarity strategies
+- **Error Prevention**: Constraints, confirmations, and safeguards
+- **Learnability**: Onboarding, progressive disclosure, and help systems
+
+### 6. Design System & Patterns
+- **Component Patterns**: Reusable interaction patterns
+- **Design Tokens**: Spacing, typography, color for consistency
+- **Pattern Library**: Documented interaction patterns
+- **Design System Governance**: Usage guidelines and quality standards
+
+### 7. Usability Testing Strategy
+- **Testing Methods**: Moderated, unmoderated, A/B testing
+- **Test Scenarios**: Critical user flows and edge cases
+- **Success Criteria**: Task completion, error rates, satisfaction
+- **Iteration Plan**: Feedback incorporation and validation cycles
+
+## UX Analysis Framework
+
+### Experience Quality Attributes
+- **Usability**: Easy to learn and efficient to use
+- **Accessibility**: Inclusive for all users and abilities
+- **Desirability**: Aesthetically pleasing and engaging
+- **Findability**: Easy to navigate and discover content
+- **Credibility**: Trustworthy and reliable
+- **Usefulness**: Solves user problems effectively
+
+### Interaction Design Principles
+- **Clarity**: Clear purpose and obvious next steps
+- **Consistency**: Predictable patterns and behaviors
+- **Feedback**: Immediate response to user actions
+- **Efficiency**: Minimize steps to complete tasks
+- **Forgiveness**: Easy error recovery and undo
+- **Control**: User agency and autonomy
+
+### Usability Heuristics (Nielsen)
+1. Visibility of system status
+2. Match between system and real world
+3. User control and freedom
+4. Consistency and standards
+5. Error prevention
+6. Recognition rather than recall
+7. Flexibility and efficiency of use
+8. Aesthetic and minimalist design
+9. Help users recognize, diagnose, and recover from errors
+10. Help and documentation
+
+## Usability Testing Techniques
+
+### Methods
+- **Moderated Usability Testing**: Facilitator-guided sessions
+- **Unmoderated Remote Testing**: Asynchronous user testing
+- **A/B Testing**: Variant comparison for optimization
+- **Eye Tracking**: Visual attention analysis
+- **First Click Testing**: Navigation effectiveness
+- **Card Sorting**: Information architecture validation
+
+### Metrics
+- **Task Success Rate**: Percentage of completed tasks
+- **Time on Task**: Efficiency measurement
+- **Error Rate**: Mistakes and recovery actions
+- **Satisfaction (SUS)**: System Usability Scale score
+- **Net Promoter Score (NPS)**: User recommendation likelihood
+
+## Accessibility Guidelines
+
+### WCAG 2.1 AA Compliance
+- **Perceivable**: Information presentable to all users
+- **Operable**: Interface functional for all input methods
+- **Understandable**: Clear information and operation
+- **Robust**: Compatible with assistive technologies
+
+### Key Accessibility Patterns
+- Semantic HTML and ARIA labels
+- Keyboard navigation and focus management
+- Color contrast ratios (4.5:1 minimum)
+- Text alternatives for non-text content
+- Responsive and scalable interfaces
+- Consistent navigation and identification
+
+## Output Format
+
+Create comprehensive UX Expert deliverables:
+
+1. **Planning Document**: `ux-expert-analysis.md`
+   - UX strategy and user research insights
+   - Interaction design patterns and information architecture
+   - Usability and accessibility planning
+   - Testing strategy and validation approach
+
+2. **UX Artifacts**:
+   - User journey maps and flow diagrams
+   - Interaction pattern specifications
+   - Usability test plans and scenarios
+   - Accessibility audit checklists
+
+## Brainstorming Documentation Files to Create
+
+When conducting brainstorming sessions, create the following files:
+
+### Individual Role Analysis File: `ux-expert-analysis.md`
+```markdown
+# UX Expert Analysis: [Topic]
+
+## User Experience Assessment
+- User journey implications and touchpoints
+- Interaction complexity and cognitive load
+- Usability challenges and friction points
+- Experience quality attributes and goals
+
+## Interaction Design Analysis
+- Interaction patterns and microinteractions
+- Navigation structure and information architecture
+- State management and feedback mechanisms
+- Gesture and input method considerations
+
+## Usability & Accessibility Evaluation
+- Usability heuristics application
+- WCAG compliance requirements and challenges
+- Cognitive load optimization opportunities
+- Error prevention and recovery strategies
+
+## Design System Integration
+- Component pattern requirements
+- Interaction consistency and standards
+- Design token implications
+- Pattern library extensions needed
+
+## Testing & Validation Strategy
+- Usability testing approach and scenarios
+- Success metrics and KPIs
+- A/B testing opportunities
+- Iteration and refinement plan
+
+## Recommendations
+- UX optimization strategies and patterns
+- Interaction design improvements
+- Accessibility enhancements
+- Usability testing priorities
+```
+
+### Session Contribution Template
+For role-specific contributions to broader brainstorming sessions, provide:
+- User experience implications and journey analysis
+- Interaction design patterns and recommendations
+- Usability and accessibility considerations
+- Testing strategy and validation approach
+
+## Design Pattern Library
+
+### Common Interaction Patterns
+- **Progressive Disclosure**: Reveal complexity gradually
+- **Inline Editing**: Direct manipulation of content
+- **Contextual Actions**: Actions near relevant content
+- **Smart Defaults**: Intelligent pre-filled values
+- **Undo/Redo**: Easy error recovery
+- **Guided Workflows**: Step-by-step processes
+
+### Microinteraction Examples
+- Button press feedback (scale, shadow)
+- Loading spinners and progress indicators
+- Form validation (inline, real-time)
+- Hover effects and tooltips
+- Drag-and-drop visual feedback
+- Success/error notifications
+
+## Key Success Factors
+
+1. **User-Centered Focus**: Design decisions based on user needs
+2. **Iterative Testing**: Regular validation with real users
+3. **Accessibility First**: Inclusive design from the start
+4. **Consistency**: Predictable patterns across the experience
+5. **Clear Feedback**: Users always know system status
+6. **Error Prevention**: Minimize mistakes through good design
+7. **Performance**: Fast, responsive interactions
+
+## Important Reminders
+
+1. **Test with real users** - assumptions are not validation
+2. **Accessibility is not optional** - design inclusively from the start
+3. **Measure usability** - use quantitative and qualitative data
+4. **Iterate based on feedback** - continuous improvement cycle
+5. **Document patterns** - create reusable interaction library
+6. **Consider edge cases** - error states, empty states, loading states
+7. **Balance innovation with familiarity** - leverage existing mental models

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

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

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

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

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

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

.claude/workflows/cli-templates/prompts/memory/hierarchy-analysis.txt

@@ -1,4 +1,4 @@
-Analyze project structure for DMS hierarchy optimization:
+Analyze project structure for memory hierarchy optimization:
 
 ## Required Analysis:
 1. Assess project complexity and file organization patterns

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

@@ -1,189 +0,0 @@
-# Conceptual Planning Agent
-
-**Agent Definition**: See @~/.claude/agents/conceptual-planning-agent.md
-**Integration Principles**: See @~/.claude/workflows/brainstorming-principles.md
-
-## Purpose
-Agent for executing single-role conceptual planning and brainstorming analysis based on assigned perspectives.
-
-## Core Capabilities
-- **Single-Role Analysis** → Deep analysis from one assigned role perspective
-- **Context Integration** → Incorporate user requirements and constraints
-- **Documentation Generation** → Create role-specific analysis outputs
-- **Framework Application** → Apply techniques from @~/.claude/workflows/brainstorming-framework.md
-
-## Execution Patterns
-
-### Agent Invocation
-This agent is called by role-specific brainstorm commands with:
-- **ASSIGNED_ROLE**: The specific role to embody
-- **Topic**: Challenge or opportunity to analyze
-- **Context**: User requirements and constraints
-- **Output Location**: Where to save analysis files
-
-### Execution Flow
-See @~/.claude/workflows/brainstorming-framework.md for detailed execution patterns and techniques.
-
-### Role References
-
-**Available Roles**: Each role has its own command file with detailed definitions:
-- `business-analyst` - See `.claude/commands/workflow/brainstorm/business-analyst.md`
-- `data-architect` - See `.claude/commands/workflow/brainstorm/data-architect.md`
-- `feature-planner` - See `.claude/commands/workflow/brainstorm/feature-planner.md`
-- `innovation-lead` - See `.claude/commands/workflow/brainstorm/innovation-lead.md`
-- `product-manager` - See `.claude/commands/workflow/brainstorm/product-manager.md`
-- `security-expert` - See `.claude/commands/workflow/brainstorm/security-expert.md`
-- `system-architect` - See `.claude/commands/workflow/brainstorm/system-architect.md`
-- `ui-designer` - See `.claude/commands/workflow/brainstorm/ui-designer.md`
-- `user-researcher` - See `.claude/commands/workflow/brainstorm/user-researcher.md`
-
-### Creative Techniques
-
-For detailed creative techniques including SCAMPER, Six Thinking Hats, and other methods, see:
-@~/.claude/workflows/brainstorming-framework.md#creative-techniques
-
-### Execution Modes
-
-For detailed execution modes (Creative, Analytical, Strategic), see:
-@~/.claude/workflows/brainstorming-framework.md#execution-modes
-
-## Documentation Standards
-
-### Session Summary Generation
-Generate comprehensive session documentation including:
-- Session metadata and configuration
-- Challenge definition and scope
-- Key insights and patterns
-- Generated ideas with descriptions
-- Perspective analysis from each role
-- Evaluation and prioritization
-- Recommendations and next steps
-
-### Idea Documentation
-For each significant idea, create detailed documentation:
-- Concept description and core mechanism
-- Multi-perspective analysis and implications
-- Feasibility assessment (technical, resource, timeline)
-- Impact potential (user, business, technical)
-- Implementation considerations and prerequisites
-- Success metrics and validation approach
-- Risk assessment and mitigation strategies
-
-### Integration Preparation
-When brainstorming integrates with workflows:
-- Synthesize requirements suitable for planning phase
-- Prioritize solutions by feasibility and impact
-- Prepare structured input for workflow systems
-- Maintain traceability between brainstorming and implementation
-
-## Output Format Standards
-
-### Brainstorming Session Output
-```
-BRAINSTORMING_SUMMARY: [Comprehensive session overview]
-CHALLENGE_DEFINITION: [Clear problem space definition]
-KEY_INSIGHTS: [Major discoveries and patterns]
-IDEA_INVENTORY: [Structured list of all generated ideas]
-TOP_CONCEPTS: [5 most promising solutions with analysis]
-PERSPECTIVE_SYNTHESIS: [Integration of role-based insights]
-FEASIBILITY_ASSESSMENT: [Technical and resource evaluation]
-IMPACT_ANALYSIS: [Expected outcomes and benefits]
-RECOMMENDATIONS: [Prioritized next steps and actions]
-WORKFLOW_INTEGRATION: [If applicable, workflow handoff preparation]
-```
-
-### Multi-Role Analysis Output
-```
-ROLE_COORDINATION: [How perspectives were integrated]
-PERSPECTIVE_INSIGHTS: [Key insights from each role]
-SYNTHESIS_RESULTS: [Combined perspective analysis]
-CONFLICT_RESOLUTION: [How role conflicts were addressed]
-COMPREHENSIVE_COVERAGE: [Confirmation all aspects considered]
-```
-
-## Quality Standards
-
-### Effective Session Facilitation
-- **Clear Structure** → Follow defined phases and maintain session flow
-- **Inclusive Participation** → Ensure all perspectives are heard and valued  
-- **Creative Environment** → Maintain judgment-free ideation atmosphere
-- **Productive Tension** → Balance creativity with practical constraints
-- **Actionable Outcomes** → Generate concrete next steps and recommendations
-
-### Perspective Integration
-- **Authentic Representation** → Accurately channel each role's mental models
-- **Balanced Coverage** → Give appropriate attention to all perspectives
-- **Constructive Synthesis** → Combine insights into stronger solutions
-- **Conflict Navigation** → Address perspective tensions constructively
-- **Comprehensive Analysis** → Ensure no critical aspects are overlooked
-
-### Documentation Quality
-- **Structured Capture** → Organize insights and ideas systematically
-- **Clear Communication** → Present complex ideas in accessible format
-- **Decision Support** → Provide frameworks for evaluating options
-- **Implementation Ready** → Prepare outputs for next development phases
-- **Traceability** → Maintain clear links between ideas and analysis
-
-## Dynamic Role Definition Loading
-
-### Role-Based Planning Template Integration
-The conceptual planning agent dynamically loads role-specific capabilities using the planning template system:
-
-**Dynamic Role Loading Process:**
-1. **Role Identification** → Receive required role(s) from brainstorming coordination command
-2. **Template Loading** → Use Bash tool to execute `~/.claude/scripts/plan-executor.sh [role]`
-3. **Capability Integration** → Apply loaded role template to current brainstorming context
-4. **Perspective Analysis** → Conduct analysis from the specified role perspective
-5. **Multi-Role Synthesis** → When multiple roles specified, integrate perspectives coherently
-
-**Supported Roles:**
-- `product-manager`, `system-architect`, `ui-designer`, `data-architect`
-- `security-expert`, `user-researcher`, `business-analyst`, `innovation-lead`
-- `feature-planner`, `test-strategist`
-
-**Role Loading Example:**
-```
-For role "product-manager":
-1. Execute: Bash(~/.claude/scripts/plan-executor.sh product-manager)
-2. Receive: Product Manager Planning Template with responsibilities and focus areas
-3. Apply: Template guidance to current brainstorming topic
-4. Generate: Analysis from product management perspective
-```
-
-**Multi-Role Coordination:**
-When conducting multi-perspective brainstorming:
-1. Load each required role template sequentially
-2. Apply each perspective to the brainstorming topic
-3. Synthesize insights across all loaded perspectives
-4. Identify convergent themes and resolve conflicts
-5. Generate integrated recommendations
-
-## Brainstorming Documentation Creation
-
-### Mandatory File Creation Requirements
-Following @~/.claude/workflows/brainstorming-principles.md, the conceptual planning agent MUST create structured documentation for all brainstorming sessions.
-
-**Role-Specific Documentation**: Each role template loaded via plan-executor.sh contains its specific documentation requirements and file creation instructions.
-
-### File Creation Protocol
-1. **Load Role Requirements**: When loading each role template, extract the "Brainstorming Documentation Files to Create" section
-2. **Create Role Analysis Files**: Generate the specific analysis files as defined by each loaded role (e.g., `product-manager-analysis.md`)
-3. **Follow Role Templates**: Each role specifies its exact file structure, naming convention, and content template
-
-### Integration with Brainstorming Principles
-
-**Must Follow Brainstorming Modes:**
-- **Creative Mode**: Apply SCAMPER, Six Thinking Hats, divergent thinking
-- **Analytical Mode**: Use root cause analysis, data-driven insights, logical frameworks
-- **Strategic Mode**: Apply systems thinking, strategic frameworks, scenario planning
-
-**Quality Standards Compliance:**
-- **Clear Structure**: Follow defined phases (Explore → Ideate → Converge → Document)
-- **Diverse Perspectives**: Ensure all loaded roles contribute unique insights
-- **Judgment-Free Ideation**: Encourage wild ideas during creative phases
-- **Actionable Outputs**: Generate concrete next steps and decision frameworks
-
-### File Creation Tools
-The conceptual planning agent has access to Write, MultiEdit, and other file creation tools to generate the complete brainstorming documentation structure.
-
-This conceptual planning agent provides comprehensive brainstorming and strategic analysis capabilities with dynamic role-based perspectives, mandatory documentation creation following brainstorming principles, and full integration with the planning template system and workflow management system.

.claude/workflows/context-search-strategy.md

@@ -6,6 +6,12 @@ type: search-guideline
 
 # Context Search Strategy
 
+## ⚡ Execution Environment
+
+**CRITICAL**: All commands execute in **Bash environment** (Git Bash on Windows, Bash on Linux/macOS)
+
+**❌ Forbidden**: Windows-specific commands (`findstr`, `dir`, `where`, `type`, `copy`, `del`) - Use Bash equivalents (`grep`, `find`, `which`, `cat`, `cp`, `rm`)
+
 ## ⚡ Core Search Tools
 
 **rg (ripgrep)**: Fast content search with regex support
@@ -18,6 +24,7 @@ type: search-guideline
 - **Use find for files** - Locate files/directories by name
 - **Use grep sparingly** - Only when rg unavailable
 - **Use get_modules_by_depth.sh first** - MANDATORY for program architecture analysis before planning
+- **Always use Bash commands** - NEVER use Windows cmd/PowerShell commands
 
 ### Quick Command Reference
 ```bash

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

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

.claude/workflows/doc_agent.md

@@ -1,255 +0,0 @@
-# Documentation Agent
-
-## Agent Overview
-Specialized agent for hierarchical documentation generation with bottom-up analysis approach.
-
-## Core Capabilities
-- **Modular Analysis**: Analyze individual modules and components
-- **Hierarchical Synthesis**: Build documentation from modules to system level
-- **Multi-tool Integration**: Combine Agent tasks, CLI tools, and direct analysis
-- **Progress Tracking**: Use TodoWrite throughout the documentation process
-
-## Analysis Strategy
-
-### Two-Level Hierarchy
-1. **Level 1 (Module)**: Individual component/module documentation
-2. **Level 2 (System)**: Integrated system-wide documentation
-
-### Bottom-Up Process
-1. **Module Discovery**: Identify all modules/components in the system
-2. **Module Analysis**: Deep dive into each module individually
-3. **Module Documentation**: Generate detailed module docs
-4. **Integration Analysis**: Analyze relationships between modules
-5. **System Synthesis**: Create unified system documentation
-
-## Tool Selection Strategy
-
-### For Module Analysis (Simple, focused scope)
-- **CLI Tools**: Direct Gemini/Codex commands for individual modules
-- **File Patterns**: Focused file sets per module
-- **Fast Processing**: Quick analysis of contained scope
-
-### For System Integration (Complex, multi-module)
-- **Agent Tasks**: Complex analysis requiring multiple tools
-- **Cross-module Analysis**: Relationship mapping between modules
-- **Synthesis Tasks**: Combining multiple module analyses
-
-## Documentation Structure
-
-### Module Level (Level 1)
-```
-.workflow/docs/modules/
-├── [module-name]/
-│   ├── overview.md        # Module overview
-│   ├── api.md            # Module APIs
-│   ├── dependencies.md   # Module dependencies
-│   └── examples.md       # Usage examples
-```
-
-### System Level (Level 2)
-```
-.workflow/docs/
-├── README.md             # Complete system overview
-├── architecture/
-│   ├── system-design.md  # High-level architecture
-│   ├── module-map.md     # Module relationships
-│   ├── data-flow.md      # System data flow
-│   └── tech-stack.md     # Technology decisions
-└── api/
-    ├── unified-api.md    # Complete API documentation
-    └── openapi.yaml      # OpenAPI specification
-```
-
-## Process Flow Templates
-
-### Phase 1: Module Discovery & Todo Setup
-```json
-{
-  "step": "module_discovery",
-  "method": "cli",
-  "command": "find src/ -type d -name '*' | grep -v node_modules | head -20",
-  "purpose": "Identify all modules for documentation",
-  "todo_action": "create_module_todos"
-}
-```
-
-### Phase 2: Module Analysis (Parallel)
-```json
-{
-  "step": "module_analysis",
-  "method": "cli_parallel",
-  "pattern": "per_module",
-  "command_template": "~/.claude/scripts/gemini-wrapper -p 'ANALYZE_MODULE: {module_path}'",
-  "purpose": "Analyze each module individually",
-  "todo_action": "track_module_progress"
-}
-```
-
-### Phase 3: Module Documentation (Parallel)
-```json
-{
-  "step": "module_documentation",
-  "method": "cli_parallel",
-  "pattern": "per_module",
-  "command_template": "codex --full-auto exec 'DOCUMENT_MODULE: {module_path}' -s danger-full-access",
-  "purpose": "Generate documentation for each module",
-  "todo_action": "mark_module_complete"
-}
-```
-
-### Phase 4: System Integration (Agent)
-```json
-{
-  "step": "system_integration",
-  "method": "agent",
-  "agent_type": "general-purpose",
-  "purpose": "Analyze cross-module relationships and create system view",
-  "todo_action": "track_integration_progress"
-}
-```
-
-### Phase 5: System Documentation (Agent)
-```json
-{
-  "step": "system_documentation",
-  "method": "agent",
-  "agent_type": "general-purpose",
-  "purpose": "Generate unified system documentation",
-  "todo_action": "mark_system_complete"
-}
-```
-
-## CLI Command Templates
-
-### Module Analysis Template
-```bash
-~/.claude/scripts/gemini-wrapper -p "
-PURPOSE: Analyze individual module for documentation
-TASK: Deep analysis of module structure, APIs, and dependencies
-CONTEXT: @{{{module_path}}/**/*}
-EXPECTED: Module analysis for documentation generation
-
-MODULE ANALYSIS RULES:
-1. Module Scope Definition:
-   - Identify module boundaries and entry points
-   - Map internal file organization
-   - Extract module's primary purpose and responsibilities
-
-2. API Surface Analysis:
-   - Identify exported functions, classes, and interfaces
-   - Document public API contracts
-   - Map input/output types and parameters
-
-3. Dependency Analysis:
-   - Extract internal dependencies within module
-   - Identify external dependencies from other modules
-   - Map configuration and environment dependencies
-
-4. Usage Pattern Analysis:
-   - Find example usage within codebase
-   - Identify common patterns and utilities
-   - Document error handling approaches
-
-OUTPUT FORMAT:
-- Module overview with clear scope definition
-- API documentation with types and examples
-- Dependency map with clear relationships
-- Usage examples from actual codebase
-" 
-```
-
-### Module Documentation Template
-```bash
-codex --full-auto exec "
-PURPOSE: Generate comprehensive module documentation
-TASK: Create detailed documentation for analyzed module
-CONTEXT: Module analysis results from Gemini
-EXPECTED: Complete module documentation in .workflow/docs/modules/{module_name}/
-
-DOCUMENTATION GENERATION RULES:
-1. Create module directory structure
-2. Generate overview.md with module purpose and architecture
-3. Create api.md with detailed API documentation
-4. Generate dependencies.md with dependency analysis
-5. Create examples.md with practical usage examples
-6. Ensure consistent formatting and cross-references
-" -s danger-full-access 
-```
-
-## Agent Task Templates
-
-### System Integration Agent Task
-```json
-{
-  "description": "Analyze cross-module relationships",
-  "prompt": "You are analyzing a software system to understand relationships between modules. Your task is to:\n\n1. Read all module documentation from .workflow/docs/modules/\n2. Identify integration points and data flow between modules\n3. Map system-wide architecture patterns\n4. Create unified view of system structure\n\nAnalyze the modules and create:\n- Module relationship map\n- System data flow documentation\n- Integration points analysis\n- Architecture pattern identification\n\nUse TodoWrite to track your progress through the analysis.",
-  "subagent_type": "general-purpose"
-}
-```
-
-### System Documentation Agent Task
-```json
-{
-  "description": "Generate unified system documentation",
-  "prompt": "You are creating comprehensive system documentation based on module analyses. Your task is to:\n\n1. Synthesize information from .workflow/docs/modules/ \n2. Create unified system architecture documentation\n3. Generate complete API documentation\n4. Create system overview and navigation\n\nGenerate:\n- README.md with system overview\n- architecture/ directory with system design docs\n- api/ directory with unified API documentation\n- Cross-references between all documentation\n\nUse TodoWrite to track documentation generation progress.",
-  "subagent_type": "general-purpose"
-}
-```
-
-## Progress Tracking Templates
-
-### Module Todo Structure
-```json
-{
-  "content": "Analyze {module_name} module",
-  "activeForm": "Analyzing {module_name} module",
-  "status": "pending"
-}
-```
-
-### Integration Todo Structure
-```json
-{
-  "content": "Integrate module analyses into system view",
-  "activeForm": "Integrating module analyses",
-  "status": "pending"
-}
-```
-
-### Documentation Todo Structure
-```json
-{
-  "content": "Generate unified system documentation",
-  "activeForm": "Generating system documentation",
-  "status": "pending"
-}
-```
-
-## Error Handling & Recovery
-
-### Module Analysis Failures
-- Skip failed modules with warning
-- Continue with successful modules
-- Retry failed modules with different approach
-
-### Integration Failures
-- Fall back to manual integration
-- Use partial results where available
-- Generate documentation with known limitations
-
-### Documentation Generation Failures
-- Generate partial documentation
-- Include clear indicators of incomplete sections
-- Provide recovery instructions
-
-## Quality Assurance
-
-### Module Documentation Quality
-- Verify all modules have complete documentation
-- Check API documentation completeness
-- Validate examples and cross-references
-
-### System Documentation Quality
-- Ensure module integration is complete
-- Verify system overview accuracy
-- Check documentation navigation and links

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

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

.claude/workflows/task-core.md

@@ -13,8 +13,8 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
   "status": "pending|active|completed|blocked|container",
 
   "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer|@planning-agent|@code-review-test-agent"
+    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
+    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@general-purpose"
   },
 
   "context": {
@@ -49,7 +49,8 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
     },
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
-      "src/middleware/auth.ts:validateToken"
+      "src/middleware/auth.ts:validateToken",
+      "src/auth/PasswordReset.ts"
     ]
   }
 }
@@ -81,7 +82,7 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
 **Components**:
 - **pre_analysis**: Array of sequential process steps
 - **implementation_approach**: Task execution strategy
-- **target_files**: Specific files to modify in "file:function:lines" format
+- **target_files**: Files to modify/create - existing files in `file:function:lines` format, new files as `file` only
 
 **Step Structure**:
 ```json
@@ -145,17 +146,17 @@ Tasks inherit from:
 ## Agent Mapping
 
 ### Automatic Agent Selection
-- **@code-developer**: Implementation tasks, coding
-- **@planning-agent**: Design, architecture planning
-- **@code-review-test-agent**: Testing, validation
-- **@review-agent**: Code review, quality checks
+- **@code-developer**: Implementation tasks, coding, test writing
+- **@action-planning-agent**: Design, architecture planning
+- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
+- **@general-purpose**: Optional manual review (only when explicitly requested)
 
 ### Agent Context Filtering
 Each agent receives tailored context:
-- **@code-developer**: Complete implementation details
-- **@planning-agent**: High-level requirements, risks
-- **@test-agent**: Files to test, logic flows to validate
-- **@review-agent**: Quality standards, security considerations
+- **@code-developer**: Complete implementation details, test requirements
+- **@action-planning-agent**: High-level requirements, risks, architecture
+- **@test-fix-agent**: Test execution, failure diagnosis, code fixing
+- **@general-purpose**: Quality standards, security considerations (when requested)
 
 ## Deprecated Fields
 

.claude/workflows/workflow-architecture.md

@@ -113,8 +113,8 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
   "status": "pending|active|completed|blocked|container",
 
   "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "code-developer|planning-agent|code-review-test-agent"
+    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
+    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@general-purpose"
   },
 
   "context": {
@@ -175,7 +175,8 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
     },
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
-      "src/middleware/auth.ts:validateToken"
+      "src/middleware/auth.ts:validateToken",
+      "src/auth/PasswordReset.ts"
     ]
   }
 }
@@ -219,7 +220,7 @@ The **flow_control** field manages task execution with two main components:
 - **task_description**: Comprehensive implementation description
 - **modification_points**: Specific code modification targets
 - **logic_flow**: Business logic execution sequence
-- **target_files**: Target file list in `file:function:lines` format
+- **target_files**: Target file list - existing files in `file:function:lines` format, new files as `file` only
 
 #### Tool Reference
 **Command Types Available**:
@@ -265,28 +266,105 @@ All workflows use the same file structure definition regardless of complexity. *
 
 #### Complete Structure Reference
 ```
-.workflow/WFS-[topic-slug]/
-├── workflow-session.json        # Session metadata and state (REQUIRED)
-├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
-├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
-│   ├── chat-*.md              # Saved chat sessions
-│   └── analysis-*.md          # Analysis results
-├── [.process/]                 # Planning analysis results (created by /workflow:plan)
-│   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
-├── IMPL_PLAN.md                # Planning document (REQUIRED)
-├── TODO_LIST.md                # Progress tracking (REQUIRED)
-├── [.summaries/]               # Task completion summaries (created when tasks complete)
-│   ├── IMPL-*-summary.md      # Main task summaries
-│   └── IMPL-*.*-summary.md    # Subtask summaries
-└── .task/                      # Task definitions (REQUIRED)
-    ├── IMPL-*.json             # Main task definitions
-    └── IMPL-*.*.json           # Subtask definitions (created dynamically)
+.workflow/
+├── [.scratchpad/]              # Non-session-specific outputs (created when needed)
+│   ├── analyze-*-[timestamp].md        # One-off analysis results
+│   ├── chat-*-[timestamp].md           # Standalone chat sessions
+│   ├── plan-*-[timestamp].md           # Ad-hoc planning notes
+│   ├── bug-index-*-[timestamp].md      # Quick bug analyses
+│   ├── code-analysis-*-[timestamp].md  # Standalone code analysis
+│   ├── execute-*-[timestamp].md        # Ad-hoc implementation logs
+│   └── codex-execute-*-[timestamp].md  # Multi-stage execution logs
+│
+├── [.design/]                  # Standalone UI design outputs (created when needed)
+│   └── run-[timestamp]/        # Timestamped design runs without session
+│       ├── style-extraction/   # Style analysis results
+│       ├── style-consolidation/ # Design system tokens (per-style)
+│       │   ├── style-1/        # design-tokens.json, style-guide.md
+│       │   └── style-N/
+│       ├── prototypes/         # Generated HTML/CSS prototypes
+│       │   ├── _templates/     # Target-specific layout plans and templates
+│       │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+│       │   │   ├── {target}-layout-{n}.html  # HTML template
+│       │   │   └── {target}-layout-{n}.css   # CSS template
+│       │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+│       │   ├── compare.html    # Interactive matrix view
+│       │   └── index.html      # Navigation page
+│       └── .run-metadata.json  # Run configuration
+│
+└── WFS-[topic-slug]/
+    ├── workflow-session.json        # Session metadata and state (REQUIRED)
+    ├── [.brainstorming/]           # Optional brainstorming phase (created when needed)
+    ├── [.chat/]                    # CLI interaction sessions (created when analysis is run)
+    │   ├── chat-*.md              # Saved chat sessions
+    │   └── analysis-*.md          # Analysis results
+    ├── [.process/]                 # Planning analysis results (created by /workflow:plan)
+    │   └── ANALYSIS_RESULTS.md    # Analysis results and planning artifacts
+    ├── IMPL_PLAN.md                # Planning document (REQUIRED)
+    ├── TODO_LIST.md                # Progress tracking (REQUIRED)
+    ├── [.summaries/]               # Task completion summaries (created when tasks complete)
+    │   ├── IMPL-*-summary.md      # Main task summaries
+    │   └── IMPL-*.*-summary.md    # Subtask summaries
+    ├── [design-*/]                 # UI design outputs (created by ui-design workflows)
+    │   ├── style-extraction/       # Style analysis results
+    │   ├── style-consolidation/    # Design system tokens (per-style)
+    │   │   ├── style-1/            # design-tokens.json, style-guide.md
+    │   │   └── style-N/
+    │   ├── prototypes/             # Generated HTML/CSS prototypes
+    │   │   ├── _templates/         # Target-specific layout plans and templates
+    │   │   │   ├── {target}-layout-{n}.json  # Layout plan (target-specific)
+    │   │   │   ├── {target}-layout-{n}.html  # HTML template
+    │   │   │   └── {target}-layout-{n}.css   # CSS template
+    │   │   ├── {target}-style-{s}-layout-{l}.html  # Final prototypes
+    │   │   ├── compare.html        # Interactive matrix view
+    │   │   └── index.html          # Navigation page
+    │   └── .run-metadata.json      # Run configuration
+    └── .task/                      # Task definitions (REQUIRED)
+        ├── IMPL-*.json             # Main task definitions
+        └── IMPL-*.*.json           # Subtask definitions (created dynamically)
 ```
 
 #### Creation Strategy
 - **Initial Setup**: Create only `workflow-session.json`, `IMPL_PLAN.md`, `TODO_LIST.md`, and `.task/` directory
 - **On-Demand Creation**: Other directories created when first needed
 - **Dynamic Files**: Subtask JSON files created during task decomposition
+- **Scratchpad Usage**: `.scratchpad/` created when CLI commands run without active session
+- **Design Usage**: `design-{timestamp}/` created by UI design workflows, `.design/` for standalone design runs
+- **Layout Planning**: `prototypes/_templates/` contains target-specific layout plans (JSON) generated during UI generation phase
+
+#### Scratchpad Directory (.scratchpad/)
+**Purpose**: Centralized location for non-session-specific CLI outputs
+
+**When to Use**:
+1. **No Active Session**: CLI analysis/chat commands run without an active workflow session
+2. **Unrelated Analysis**: Quick analysis not related to current active session
+3. **Exploratory Work**: Ad-hoc investigation before creating formal workflow
+4. **One-Off Queries**: Standalone questions or debugging without workflow context
+
+**Output Routing Logic**:
+- **IF** active session exists AND command is session-relevant:
+  - Save to `.workflow/WFS-[id]/.chat/[command]-[timestamp].md`
+- **ELSE** (no session OR one-off analysis):
+  - Save to `.workflow/.scratchpad/[command]-[description]-[timestamp].md`
+
+**File Naming Pattern**: `[command-type]-[brief-description]-[timestamp].md`
+
+**Examples**:
+
+*Analysis Commands (read-only):*
+- `/cli:analyze "security"` (no session) → `.scratchpad/analyze-security-20250105-143022.md`
+- `/cli:chat "build process"` (unrelated to active session) → `.scratchpad/chat-build-process-20250105-143045.md`
+- `/cli:mode:plan "feature idea"` (exploratory) → `.scratchpad/plan-feature-idea-20250105-143110.md`
+- `/cli:mode:code-analysis "trace auth flow"` (no session) → `.scratchpad/code-analysis-auth-flow-20250105-143130.md`
+
+*Implementation Commands (⚠️ modifies code):*
+- `/cli:execute "implement JWT auth"` (no session) → `.scratchpad/execute-jwt-auth-20250105-143200.md`
+- `/cli:codex-execute "refactor API layer"` (no session) → `.scratchpad/codex-execute-api-refactor-20250105-143230.md`
+
+**Maintenance**:
+- Periodically review and clean up old scratchpad files
+- Promote useful analyses to formal workflow sessions if needed
+- No automatic cleanup - manual management recommended
 
 ### File Naming Conventions
 
@@ -420,10 +498,10 @@ fi
 
 ### Agent Assignment
 Based on task type and title keywords:
-- **Planning tasks** → @planning-agent
-- **Implementation** → @code-developer
-- **Testing** → @code-review-test-agent
-- **Review** → @review-agent
+- **Planning tasks** → @action-planning-agent
+- **Implementation** → @code-developer (code + tests)
+- **Test execution/fixing** → @test-fix-agent
+- **Review** → @general-purpose (optional, only when explicitly requested)
 
 ### Execution Context
 Agents receive complete task JSON plus workflow context:

.codex/AGENTS.md

@@ -0,0 +1,371 @@
+# Codex Agent Execution Protocol
+
+## Overview
+
+**Role**: Codex - autonomous development, implementation, and testing
+
+## Prompt Structure
+
+### Single-Task Format
+
+**Receive prompts in this format**:
+
+```
+PURPOSE: [development goal]
+TASK: [specific implementation task]
+MODE: [auto|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [constraints and templates]
+```
+
+### Multi-Task Format (Subtask Execution)
+
+**First subtask** (creates new session):
+```
+PURPOSE: [overall goal]
+TASK: [subtask 1 description]
+MODE: auto
+CONTEXT: [file patterns]
+EXPECTED: [subtask deliverables]
+RULES: [constraints]
+Subtask 1 of N: [subtask title]
+```
+
+**Subsequent subtasks** (continues via `resume --last`):
+```
+CONTINUE TO NEXT SUBTASK:
+Subtask N of M: [subtask title]
+
+PURPOSE: [continuation goal]
+TASK: [subtask N description]
+CONTEXT: Previous work completed, now focus on [new files]
+EXPECTED: [subtask deliverables]
+RULES: Build on previous subtask, maintain consistency
+```
+
+## Execution Requirements
+
+### System Optimization
+
+**Hard Requirement**: Call binaries directly in `functions.shell`, always set `workdir`, and avoid shell wrappers such as `bash -lc`, `sh -lc`, `zsh -lc`, `cmd /c`, `pwsh.exe -NoLogo -NoProfile -Command`, and `powershell.exe -NoLogo -NoProfile -Command`.
+
+**Text Editing Priority**: Use the `apply_patch` tool for all routine text edits; fall back to `sed` for single-line substitutions only if `apply_patch` is unavailable, and avoid `python` editing scripts unless both options fail.
+
+**`apply_patch` Usage**: Invoke `apply_patch` with the patch payload as the second element in the command array (no shell-style flags). Provide `workdir` and, when helpful, a short `justification` alongside the command.
+
+**Example invocation**:
+```json
+{
+  "command": ["apply_patch", "*** Begin Patch\n*** Update File: path/to/file\n@@\n- old\n+ new\n*** End Patch\n"],
+  "workdir": "<workdir>",
+  "justification": "Brief reason for the change"
+}
+```
+
+**Windows UTF-8 Encoding**: Before executing commands on Windows systems, ensure proper UTF-8 encoding by running:
+```powershell
+[Console]::InputEncoding  = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+chcp 65001 > $null
+```
+
+### ALWAYS
+
+- **Parse all fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
+- **Detect subtask format** - Check for "Subtask N of M" or "CONTINUE TO NEXT SUBTASK"
+- **Follow MODE strictly** - Respect execution boundaries
+- **Study CONTEXT files** - Find 3+ similar patterns before implementing
+- **Apply RULES** - Follow templates and constraints exactly
+- **Test continuously** - Run tests after every change
+- **Commit incrementally** - Small, working commits
+- **Match project style** - Follow existing patterns exactly
+- **Validate EXPECTED** - Ensure all deliverables are met
+- **Report context** (subtasks) - Summarize key info for next subtask
+- **Use direct binary calls** - Avoid shell wrappers for efficiency
+- **Prefer apply_patch** - Use for text edits over Python scripts
+- **Configure Windows encoding** - Set UTF-8 for Chinese character support
+
+### NEVER
+
+- **Make assumptions** - Verify with existing code
+- **Ignore existing patterns** - Study before implementing
+- **Skip tests** - Tests are mandatory
+- **Use clever tricks** - Choose boring, obvious solutions
+- **Over-engineer** - Simple solutions over complex architectures
+- **Break existing code** - Ensure backward compatibility
+- **Exceed 3 attempts** - Stop and reassess if blocked 3 times
+
+## MODE Behavior
+
+### MODE: auto (default)
+
+**Permissions**:
+- Full file operations (create/modify/delete)
+- Run tests and builds
+- Commit code incrementally
+
+**Execute (Single Task)**:
+1. Parse PURPOSE and TASK
+2. Analyze CONTEXT files - find 3+ similar patterns
+3. Plan implementation approach
+4. Generate code following RULES and project patterns
+5. Write tests alongside code
+6. Run tests continuously
+7. Commit working code incrementally
+8. Validate all EXPECTED deliverables
+9. Report results
+
+**Execute (Multi-Task/Subtask)**:
+1. **First subtask**: Follow single-task flow above
+2. **Subsequent subtasks** (via `resume --last`):
+   - Recall context from previous subtask(s)
+   - Build on previous work (don't repeat)
+   - Maintain consistency with previous decisions
+   - Focus on current subtask scope only
+   - Test integration with previous subtasks
+   - Report subtask completion status
+
+**Use For**: Feature implementation, bug fixes, refactoring, multi-step tasks
+
+### MODE: write
+
+**Permissions**:
+- Focused file operations
+- Create/modify specific files
+- Run tests for validation
+
+**Execute**:
+1. Analyze CONTEXT files
+2. Make targeted changes
+3. Validate tests pass
+4. Report file changes
+
+**Use For**: Test generation, documentation updates, targeted fixes
+
+## RULES Processing
+
+- **Parse the RULES field** to identify template content and additional constraints
+- **Recognize `|` as separator** between template and additional constraints
+- **ALWAYS apply all template guidelines** provided in the prompt
+- **ALWAYS apply all additional constraints** specified after `|`
+- **Treat all rules as mandatory** - both template and constraints must be followed
+- **Failure to follow any rule** constitutes task failure
+
+## Error Handling
+
+### Three-Attempt Rule
+
+**On 3rd failed attempt**:
+1. **Stop execution**
+2. **Report status**: What was attempted, what failed, root cause
+3. **Request guidance**: Ask for clarification, suggest alternatives
+
+### Recovery Strategies
+
+**Syntax/Type Errors**:
+1. Review and fix errors
+2. Re-run tests
+3. Validate build succeeds
+
+**Runtime Errors**:
+1. Analyze stack trace
+2. Add error handling
+3. Add tests for error cases
+
+**Test Failures**:
+1. Debug in isolation
+2. Review test setup
+3. Fix implementation or test
+
+**Build Failures**:
+1. Check error messages
+2. Fix incrementally
+3. Validate each fix
+
+## Progress Reporting
+
+### During Execution (Single Task)
+
+```
+[1/5] Analyzing existing code patterns...
+[2/5] Planning implementation approach...
+[3/5] Generating code...
+[4/5] Writing tests...
+[5/5] Running validation...
+```
+
+### During Execution (Subtask)
+
+```
+[Subtask N/M: Subtask Title]
+[1/4] Recalling context from previous subtasks...
+[2/4] Implementing current subtask...
+[3/4] Testing integration with previous work...
+[4/4] Validating subtask completion...
+```
+
+### On Success (Single Task)
+
+```
+✅ Task completed
+
+Changes:
+- Created: [files with line counts]
+- Modified: [files with changes]
+
+Validation:
+✅ Tests: [count] passing
+✅ Coverage: [percentage]
+✅ Build: Success
+
+Next Steps: [recommendations]
+```
+
+### On Success (Subtask)
+
+```
+✅ Subtask N/M completed
+
+Changes:
+- Created: [files]
+- Modified: [files]
+
+Integration:
+✅ Compatible with previous subtasks
+✅ Tests: [count] passing
+✅ Build: Success
+
+Context for next subtask:
+- [Key decisions made]
+- [Files created/modified]
+- [Patterns established]
+```
+
+### On Partial Completion
+
+```
+⚠️ Task partially completed
+
+Completed: [what worked]
+Blocked: [what failed and why]
+Required: [what's needed]
+Recommendation: [next steps]
+```
+
+## Quality Standards
+
+### Code Quality
+- Follow project's existing patterns
+- Match import style and naming conventions
+- Single responsibility per function/class
+- DRY (Don't Repeat Yourself)
+- YAGNI (You Aren't Gonna Need It)
+
+### Testing
+- Test all public functions
+- Test edge cases and error conditions
+- Mock external dependencies
+- Target 80%+ coverage
+
+### Error Handling
+- Proper try-catch blocks
+- Clear error messages
+- Graceful degradation
+- Don't expose sensitive info
+
+## Multi-Step Task Execution
+
+### Context Continuity via Resume
+
+When executing subtasks via `codex exec "..." resume --last`:
+
+**Advantages**:
+- Session memory preserves previous decisions
+- Maintains implementation style consistency
+- Avoids redundant context re-injection
+- Enables incremental testing and validation
+
+**Best Practices**:
+1. **First subtask**: Establish patterns and architecture
+2. **Subsequent subtasks**: Build on established patterns
+3. **Test integration**: After each subtask, verify compatibility
+4. **Report context**: Summarize key decisions for next subtask
+5. **Maintain scope**: Focus only on current subtask goals
+
+### Subtask Coordination
+
+**DO**:
+- Remember decisions from previous subtasks
+- Reuse patterns established earlier
+- Test integration with previous work
+- Report what's ready for next subtask
+
+**DON'T**:
+- Re-implement what previous subtasks completed
+- Change patterns established earlier (unless explicitly requested)
+- Skip testing integration points
+- Assume next subtask's requirements
+
+### Example Flow
+
+```
+Subtask 1: Create data models
+→ Establishes: Schema patterns, validation approach
+→ Delivers: Models with tests
+→ Context for next: Model structure, validation rules
+
+Subtask 2: Implement API endpoints (resume --last)
+→ Recalls: Model structure from subtask 1
+→ Builds on: Uses established models
+→ Delivers: API with integration tests
+→ Context for next: API patterns, error handling
+
+Subtask 3: Add authentication (resume --last)
+→ Recalls: API patterns from subtask 2
+→ Integrates: Auth middleware into existing endpoints
+→ Delivers: Secured API
+→ Final validation: Full integration test
+```
+
+## Philosophy
+
+- **Incremental progress over big bangs** - Small, testable changes
+- **Learning from existing code** - Study 3+ patterns before implementing
+- **Pragmatic over dogmatic** - Adapt to project reality
+- **Clear intent over clever code** - Boring, obvious solutions
+- **Simple over complex** - Avoid over-engineering
+- **Follow existing style** - Match project patterns exactly
+- **Context continuity** - Leverage resume for multi-step consistency
+
+## Execution Checklist
+
+### Before Implementation
+- [ ] Understand PURPOSE and TASK clearly
+- [ ] Review all CONTEXT files
+- [ ] Find 3+ similar patterns in codebase
+- [ ] Check RULES templates and constraints
+- [ ] Plan implementation approach
+
+### During Implementation
+- [ ] Follow existing patterns exactly
+- [ ] Write tests alongside code
+- [ ] Run tests after every change
+- [ ] Commit working code incrementally
+- [ ] Handle errors properly
+
+### After Implementation
+- [ ] Run full test suite - all pass
+- [ ] Check coverage - meets target
+- [ ] Run build - succeeds
+- [ ] Review EXPECTED - all deliverables met
+
+---
+
+**Version**: 2.2.0
+**Last Updated**: 2025-10-04
+**Changes**:
+- Added system optimization requirements for direct binary calls
+- Added apply_patch tool priority for text editing
+- Added Windows UTF-8 encoding configuration for Chinese character support
+- Previous: Multi-step task execution support with resume mechanism

.gemini/GEMINI.md

@@ -0,0 +1,143 @@
+# Gemini Execution Protocol
+
+## Overview
+
+**Role**: Gemini - code analysis and documentation generation
+
+## Prompt Structure
+
+**Receive prompts in this format**:
+
+```
+PURPOSE: [goal statement]
+TASK: [specific task]
+MODE: [analysis|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [constraints and templates]
+```
+
+## Execution Requirements
+
+### ALWAYS
+
+- **Parse all six fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
+- **Follow MODE strictly** - Respect permission boundaries
+- **Analyze CONTEXT files** - Read all matching patterns thoroughly
+- **Apply RULES** - Follow templates and constraints exactly
+- **Provide evidence** - Quote code with file:line references
+- **Match EXPECTED** - Deliver exactly what's requested
+
+### NEVER
+
+- **Assume behavior** - Verify with actual code
+- **Ignore CONTEXT** - Stay within specified file patterns
+- **Skip RULES** - Templates are mandatory when provided
+- **Make unsubstantiated claims** - Always back with code references
+- **Deviate from MODE** - Respect read/write boundaries
+
+## MODE Behavior
+
+### MODE: analysis (default)
+
+**Permissions**:
+- Read all CONTEXT files
+- Create/modify documentation files
+
+**Execute**:
+1. Read and analyze CONTEXT files
+2. Identify patterns and issues
+3. Generate insights and recommendations
+4. Create documentation if needed
+5. Output structured analysis
+
+**Constraint**: Do NOT modify source code files
+
+### MODE: write
+
+**Permissions**:
+- Full file operations
+- Create/modify any files
+
+**Execute**:
+1. Read CONTEXT files
+2. Perform requested file operations
+3. Create/modify files as specified
+4. Validate changes
+5. Report file changes
+
+## Output Format
+
+### Standard Analysis Structure
+
+```markdown
+# Analysis: [TASK Title]
+
+## Summary
+[2-3 sentence overview]
+
+## Key Findings
+1. [Finding] - path/to/file:123
+2. [Finding] - path/to/file:456
+
+## Detailed Analysis
+[Evidence-based analysis with code quotes]
+
+## Recommendations
+1. [Actionable recommendation]
+2. [Actionable recommendation]
+```
+
+### Code References
+
+Always use format: `path/to/file:line_number`
+
+Example: "Authentication logic at `src/auth/jwt.ts:45` uses deprecated algorithm"
+
+## RULES Processing
+
+- **Parse the RULES field** to identify template content and additional constraints
+- **Recognize `|` as separator** between template and additional constraints
+- **ALWAYS apply all template guidelines** provided in the prompt
+- **ALWAYS apply all additional constraints** specified after `|`
+- **Treat all rules as mandatory** - both template and constraints must be followed
+- **Failure to follow any rule** constitutes task failure
+
+## Error Handling
+
+**File Not Found**:
+- Report missing files
+- Continue with available files
+- Note in output
+
+**Invalid CONTEXT Pattern**:
+- Report invalid pattern
+- Request correction
+- Do not guess
+
+## Quality Standards
+
+### Thoroughness
+- Analyze ALL files in CONTEXT
+- Check cross-file patterns
+- Identify edge cases
+- Quantify when possible
+
+### Evidence-Based
+- Quote relevant code
+- Provide file:line references
+- Link related patterns
+
+### Actionable
+- Clear recommendations
+- Prioritized by impact
+- Specific, not vague
+
+## Philosophy
+
+- **Incremental over big bangs** - Suggest small, testable changes
+- **Learn from existing code** - Reference project patterns
+- **Pragmatic over dogmatic** - Adapt to project reality
+- **Clear over clever** - Prefer obvious solutions
+- **Simple over complex** - Avoid over-engineering
+

.gitignore

@@ -17,4 +17,7 @@ yarn-error.log*
 Thumbs.db
 
 .env
-settings.local.json
+settings.local.json
+.workflow
+version.json
+ref

.qwen/QWEN.md

@@ -0,0 +1,143 @@
+# QWEN Execution Protocol
+
+## Overview
+
+**Role**: QWEN - code analysis and documentation generation
+
+## Prompt Structure
+
+**Receive prompts in this format**:
+
+```
+PURPOSE: [goal statement]
+TASK: [specific task]
+MODE: [analysis|write]
+CONTEXT: [file patterns]
+EXPECTED: [deliverables]
+RULES: [constraints and templates]
+```
+
+## Execution Requirements
+
+### ALWAYS
+
+- **Parse all six fields** - Understand PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES
+- **Follow MODE strictly** - Respect permission boundaries
+- **Analyze CONTEXT files** - Read all matching patterns thoroughly
+- **Apply RULES** - Follow templates and constraints exactly
+- **Provide evidence** - Quote code with file:line references
+- **Match EXPECTED** - Deliver exactly what's requested
+
+### NEVER
+
+- **Assume behavior** - Verify with actual code
+- **Ignore CONTEXT** - Stay within specified file patterns
+- **Skip RULES** - Templates are mandatory when provided
+- **Make unsubstantiated claims** - Always back with code references
+- **Deviate from MODE** - Respect read/write boundaries
+
+## MODE Behavior
+
+### MODE: analysis (default)
+
+**Permissions**:
+- Read all CONTEXT files
+- Create/modify documentation files
+
+**Execute**:
+1. Read and analyze CONTEXT files
+2. Identify patterns and issues
+3. Generate insights and recommendations
+4. Create documentation if needed
+5. Output structured analysis
+
+**Constraint**: Do NOT modify source code files
+
+### MODE: write
+
+**Permissions**:
+- Full file operations
+- Create/modify any files
+
+**Execute**:
+1. Read CONTEXT files
+2. Perform requested file operations
+3. Create/modify files as specified
+4. Validate changes
+5. Report file changes
+
+## Output Format
+
+### Standard Analysis Structure
+
+```markdown
+# Analysis: [TASK Title]
+
+## Summary
+[2-3 sentence overview]
+
+## Key Findings
+1. [Finding] - path/to/file:123
+2. [Finding] - path/to/file:456
+
+## Detailed Analysis
+[Evidence-based analysis with code quotes]
+
+## Recommendations
+1. [Actionable recommendation]
+2. [Actionable recommendation]
+```
+
+### Code References
+
+Always use format: `path/to/file:line_number`
+
+Example: "Authentication logic at `src/auth/jwt.ts:45` uses deprecated algorithm"
+
+## RULES Processing
+
+- **Parse the RULES field** to identify template content and additional constraints
+- **Recognize `|` as separator** between template and additional constraints
+- **ALWAYS apply all template guidelines** provided in the prompt
+- **ALWAYS apply all additional constraints** specified after `|`
+- **Treat all rules as mandatory** - both template and constraints must be followed
+- **Failure to follow any rule** constitutes task failure
+
+## Error Handling
+
+**File Not Found**:
+- Report missing files
+- Continue with available files
+- Note in output
+
+**Invalid CONTEXT Pattern**:
+- Report invalid pattern
+- Request correction
+- Do not guess
+
+## Quality Standards
+
+### Thoroughness
+- Analyze ALL files in CONTEXT
+- Check cross-file patterns
+- Identify edge cases
+- Quantify when possible
+
+### Evidence-Based
+- Quote relevant code
+- Provide file:line references
+- Link related patterns
+
+### Actionable
+- Clear recommendations
+- Prioritized by impact
+- Specific, not vague
+
+## Philosophy
+
+- **Incremental over big bangs** - Suggest small, testable changes
+- **Learn from existing code** - Reference project patterns
+- **Pragmatic over dogmatic** - Adapt to project reality
+- **Clear over clever** - Prefer obvious solutions
+- **Simple over complex** - Avoid over-engineering
+

CLAUDE.md

@@ -19,12 +19,16 @@ For all CLI tool usage, command syntax, and integration guidelines:
 
 ### Core Beliefs
 
+- **Pursue good taste** - Eliminate edge cases to make code logic natural and elegant
+- **Embrace extreme simplicity** - Complexity is the root of all evil
+- **Be pragmatic** - Code must solve real-world problems, not hypothetical ones
+- **Data structures first** - Bad programmers worry about code; good programmers worry about data structures
+- **Never break backward compatibility** - Existing functionality is sacred and inviolable
 - **Incremental progress over big bangs** - Small changes that compile and pass tests
 - **Learning from existing code** - Study and plan before implementing
-- **Pragmatic over dogmatic** - Adapt to project reality
 - **Clear intent over clever code** - Be boring and obvious
-- **Simple solutions over complex architectures** - Avoid over-engineering and premature optimization
 - **Follow existing code style** - Match import patterns, naming conventions, and formatting of existing codebase
+- **No unsolicited reports** - Task summaries can be performed internally, but NEVER generate additional reports, documentation files, or summary files without explicit user permission
 
 ### Simplicity Means
 
@@ -53,6 +57,7 @@ For all CLI tool usage, command syntax, and integration guidelines:
 
 **NEVER**:
 - Make assumptions - verify with existing code
+- Generate reports, summaries, or documentation files without explicit user request
 
 **ALWAYS**:
 - Plan complex tasks thoroughly before implementation

INSTALL.md

@@ -186,7 +186,7 @@ cd Dmsflow
 .\Install-Claude.ps1 -Global
 
 # 4. Start using Claude Code with Agent workflows!
-# Use /workflow commands and DMS system for development
+# Use /workflow commands and memory system for development
 ```
 
 ## Verification
@@ -207,7 +207,7 @@ After installation, verify:
    - Check that global `.claude` directory is recognized
    - Verify workflow commands and DMS commands are available
    - Test `/workflow` commands for agent coordination
-   - Test `/dmsflow version` to check version information
+   - Test `/workflow version` to check version information
 
 ## Troubleshooting