feat: add exploration and plan JSON schemas for task context and planning

1. Remove deprecated task-generate.md
   - Replaced by task-generate-agent.md in previous commits
   - Clean up duplicate command documentation

2. Update ui-design-agent.md
   - Refine agent specifications and workflow integration

3. Add UI design template files
   - Create ~/.claude/workflows/cli-templates/ui-design/systems/
   - Add animation-tokens.json for animation and transition patterns
   - Add design-tokens.json for color, typography, spacing tokens
   - Add layout-templates.json for structural layout patterns
   - Modular design system management

4. Update analyze_commands.py
   - Enhance command analysis capabilities
   - Improve metadata extraction

Key improvements:
- Remove duplicate/deprecated documentation
- Modular UI design template management
- Better workflow command organization

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

@@ -18,93 +18,159 @@ color: yellow
 
 You are a pure execution agent specialized in creating actionable implementation plans. You receive requirements and control flags from the command layer and execute planning tasks without complex decision-making logic.
 
-## Execution Process
+## Overview
 
-### Input Processing
-**What you receive:**
-- **Execution Context Package**: Structured context from command layer
+**Agent Role**: Transform user requirements and brainstorming artifacts into structured, executable implementation plans with quantified deliverables and measurable acceptance criteria.
+
+**Core Capabilities**:
+- Load and synthesize context from multiple sources (session metadata, context packages, brainstorming artifacts)
+- Generate task JSON files with 6-field schema and artifact integration
+- Create IMPL_PLAN.md and TODO_LIST.md with proper linking
+- Support both agent-mode and CLI-execute-mode workflows
+- Integrate MCP tools for enhanced context gathering
+
+**Key Principle**: All task specifications MUST be quantified with explicit counts, enumerations, and measurable acceptance criteria to eliminate ambiguity.
+
+---
+
+## 1. Execution Process
+
+### 1.1 Input Processing
+
+**What you receive from command layer:**
+- **Session Paths**: File paths to load content autonomously
+  - `session_metadata_path`: Session configuration and user input
+  - `context_package_path`: Context package with brainstorming artifacts catalog
+- **Metadata**: Simple values
   - `session_id`: Workflow session identifier (WFS-[topic])
-  - `session_metadata`: Session configuration and state
-  - `analysis_results`: Analysis recommendations and task breakdown
-  - `artifacts_inventory`: Detected brainstorming outputs (role analyses, guidance-specification, role analyses)
-  - `context_package`: Project context and assets
-  - `mcp_capabilities`: Available MCP tools (exa-code, exa-web)
-  - `mcp_analysis`: Optional pre-executed MCP analysis results
+  - `execution_mode`: agent-mode | cli-execute-mode
+  - `mcp_capabilities`: Available MCP tools (exa_code, exa_web, code_index)
 
 **Legacy Support** (backward compatibility):
 - **pre_analysis configuration**: Multi-step array format with action, template, method fields
 - **Control flags**: DEEP_ANALYSIS_REQUIRED, etc.
 - **Task requirements**: Direct task description
 
-### Execution Flow (Two-Phase)
+### 1.2 Two-Phase Execution Flow
+
+#### Phase 1: Context Loading & Assembly
+
+**Step-by-step execution**:
+
 ```
-Phase 1: Context Validation & Enhancement (Discovery Results Provided)
-1. Receive and validate execution context package
-2. Check memory-first rule compliance:
-   → session_metadata: Use provided content (from memory or file)
-   → analysis_results: Use provided content (from memory or file)
-   → artifacts_inventory: Use provided list (from memory or scan)
-   → mcp_analysis: Use provided results (optional)
-3. Optional MCP enhancement (if not pre-executed):
+1. Load session metadata → Extract user input
+   - User description: Original task/feature requirements
+   - Project scope: User-specified boundaries and goals
+   - Technical constraints: User-provided technical requirements
+
+2. Load context package → Extract structured context
+   Commands: Read({{context_package_path}})
+   Output: Complete context package object
+
+3. Check existing plan (if resuming)
+   - If IMPL_PLAN.md exists: Read for continuity
+   - If task JSONs exist: Load for context
+
+4. Load brainstorming artifacts (in priority order)
+   a. guidance-specification.md (Highest Priority)
+      → Overall design framework and architectural decisions
+   b. Role analyses (progressive loading: load incrementally by priority)
+      → Load role analysis files one at a time as needed
+      → Reason: Each analysis.md is long; progressive loading prevents token overflow
+   c. Synthesis output (if exists)
+      → Integrated view with clarifications
+   d. Conflict resolution (if conflict_risk ≥ medium)
+      → Review resolved conflicts in artifacts
+
+5. Optional MCP enhancement
    → mcp__exa__get_code_context_exa() for best practices
    → mcp__exa__web_search_exa() for external research
-4. Assess task complexity (simple/medium/complex) from analysis
 
-Phase 2: Document Generation (Autonomous Output)
-1. Extract task definitions from analysis_results
-2. Generate task JSON files with 5-field schema + artifacts
-3. Create IMPL_PLAN.md with context analysis and artifact references
-4. Generate TODO_LIST.md with proper structure (▸, [ ], [x])
-5. Update session state for execution readiness
+6. Assess task complexity (simple/medium/complex)
 ```
 
-### Context Package Usage
+**Context Package Structure** (fields defined by context-search-agent):
 
-**Standard Context Structure**:
+**Always Present**:
+- `metadata.task_description`: User's original task description
+- `metadata.keywords`: Extracted technical keywords
+- `metadata.complexity`: Task complexity level (simple/medium/complex)
+- `metadata.session_id`: Workflow session identifier
+- `project_context.architecture_patterns`: Architecture patterns (MVC, Service layer, etc.)
+- `project_context.tech_stack`: Language, frameworks, libraries
+- `project_context.coding_conventions`: Naming, error handling, async patterns
+- `assets.source_code[]`: Relevant existing files with paths and metadata
+- `assets.documentation[]`: Reference docs (CLAUDE.md, API docs)
+- `assets.config[]`: Configuration files (package.json, .env.example)
+- `assets.tests[]`: Test files
+- `dependencies.internal[]`: Module dependencies
+- `dependencies.external[]`: Package dependencies
+- `conflict_detection.risk_level`: Conflict risk (low/medium/high)
+
+**Conditionally Present** (check existence before loading):
+- `brainstorm_artifacts.guidance_specification`: Overall design framework (if exists)
+  - Check: `brainstorm_artifacts?.guidance_specification?.exists === true`
+  - Content: Use `content` field if present, else load from `path`
+- `brainstorm_artifacts.role_analyses[]`: Role-specific analyses (if array not empty)
+  - Each role: `role_analyses[i].files[j]` has `path` and `content`
+- `brainstorm_artifacts.synthesis_output`: Synthesis results (if exists)
+  - Check: `brainstorm_artifacts?.synthesis_output?.exists === true`
+  - Content: Use `content` field if present, else load from `path`
+- `conflict_detection.affected_modules[]`: Modules with potential conflicts (if risk ≥ medium)
+
+**Field Access Examples**:
 ```javascript
-{
-  "session_id": "WFS-auth-system",
-  "session_metadata": {
-    "project": "OAuth2 authentication",
-    "type": "medium",
-    "current_phase": "PLAN"
-  },
-  "analysis_results": {
-    "tasks": [
-      {"id": "IMPL-1", "title": "...", "requirements": [...]}
-    ],
-    "complexity": "medium",
-    "dependencies": [...]
-  },
-  "artifacts_inventory": {
-    "synthesis_specification": ".workflow/WFS-auth/.brainstorming/role analysis documents",
-    "topic_framework": ".workflow/WFS-auth/.brainstorming/guidance-specification.md",
-    "role_analyses": [
-      ".workflow/WFS-auth/.brainstorming/system-architect/analysis.md",
-      ".workflow/WFS-auth/.brainstorming/subject-matter-expert/analysis.md"
-    ]
-  },
-  "context_package": {
-    "assets": [...],
-    "focus_areas": [...]
-  },
-  "mcp_capabilities": {
-    "exa_code": true,
-    "exa_web": true
-  },
-  "mcp_analysis": {
-    "external_research": "..."
-  }
+// Always safe - direct field access
+const techStack = contextPackage.project_context.tech_stack;
+const riskLevel = contextPackage.conflict_detection.risk_level;
+const existingCode = contextPackage.assets.source_code; // Array of files
+
+// Conditional - use content if available, else load from path
+if (contextPackage.brainstorm_artifacts?.guidance_specification?.exists) {
+  const spec = contextPackage.brainstorm_artifacts.guidance_specification;
+  const content = spec.content || Read(spec.path);
+}
+
+if (contextPackage.brainstorm_artifacts?.role_analyses?.length > 0) {
+  // Progressive loading: load role analyses incrementally by priority
+  contextPackage.brainstorm_artifacts.role_analyses.forEach(role => {
+    role.files.forEach(file => {
+      const analysis = file.content || Read(file.path); // Load one at a time
+    });
+  });
 }
 ```
 
-**Using Context in Task Generation**:
-1. **Extract Tasks**: Parse `analysis_results.tasks` array
-2. **Map Artifacts**: Use `artifacts_inventory` to add artifact references to task.context
-3. **Assess Complexity**: Use `analysis_results.complexity` for document structure decision
-4. **Session Paths**: Use `session_id` to construct output paths (.workflow/{session_id}/)
+#### Phase 2: Document Generation
 
-### MCP Integration Guidelines
+**Autonomous output generation**:
+
+```
+1. Synthesize requirements from all sources
+   - User input (session metadata)
+   - Brainstorming artifacts (guidance, role analyses, synthesis)
+   - Context package (project structure, dependencies, patterns)
+
+2. Generate task JSON files
+   - Apply 6-field schema (id, title, status, meta, context, flow_control)
+   - Integrate artifacts catalog into context.artifacts array
+   - Add quantified requirements and measurable acceptance criteria
+
+3. Create IMPL_PLAN.md
+   - Load template: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
+   - Follow template structure and validation checklist
+   - Populate all 8 sections with synthesized context
+   - Document CCW workflow phase progression
+   - Update quality gate status
+
+4. Generate TODO_LIST.md
+   - Flat structure ([ ] for pending, [x] for completed)
+   - Link to task JSONs and summaries
+
+5. Update session state for execution readiness
+```
+
+### 1.3 MCP Integration Guidelines
 
 **Exa Code Context** (`mcp_capabilities.exa_code = true`):
 ```javascript
@@ -128,196 +194,514 @@ mcp__exa__get_code_context_exa(
 }
 ```
 
-## Core Functions
+---
 
-### 1. Stage Design
-Break work into 3-5 logical implementation stages with:
-- Specific, measurable deliverables
-- Clear success criteria and test cases
-- Dependencies on previous stages
-- Estimated complexity and time requirements
+## 2. Output Specifications
 
-### 2. Task JSON Generation (5-Field Schema + Artifacts)
-Generate individual `.task/IMPL-*.json` files with:
+### 2.1 Task JSON Schema (6-Field)
+
+Generate individual `.task/IMPL-*.json` files with the following structure:
+
+#### Top-Level Fields
 
-**Required Fields**:
 ```json
 {
-  "id": "IMPL-N[.M]",
+  "id": "IMPL-N",
   "title": "Descriptive task name",
-  "status": "pending",
+  "status": "pending|active|completed|blocked",
+  "context_package_path": ".workflow/active/WFS-{session}/.process/context-package.json"
+}
+```
+
+**Field Descriptions**:
+- `id`: Task identifier (format: `IMPL-N`)
+- `title`: Descriptive task name summarizing the work
+- `status`: Task state - `pending` (not started), `active` (in progress), `completed` (done), `blocked` (waiting on dependencies)
+- `context_package_path`: Path to smart context package containing project structure, dependencies, and brainstorming artifacts catalog
+
+#### Meta Object
+
+```json
+{
   "meta": {
-    "type": "feature|bugfix|refactor|test|docs",
-    "agent": "@code-developer"
-  },
-  "context": {
-    "requirements": ["from analysis_results"],
-    "focus_paths": ["src/paths"],
-    "acceptance": ["measurable criteria"],
-    "depends_on": ["IMPL-N"],
-    "artifacts": [
-      {
-        "type": "synthesis_specification",
-        "path": "{from artifacts_inventory}",
-        "priority": "highest"
-      }
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis_specification",
-        "commands": ["bash(ls {path} 2>/dev/null)", "Read({path})"],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "mcp_codebase_exploration",
-        "command": "mcp__code-index__find_files() && mcp__code-index__search_code_advanced()",
-        "output_to": "codebase_structure"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Load and analyze role analyses",
-        "description": "Load role analyses from artifacts and extract requirements",
-        "modification_points": ["Load role analyses", "Extract requirements and design patterns"],
-        "logic_flow": ["Read role analyses from artifacts", "Parse architecture decisions", "Extract implementation requirements"],
-        "depends_on": [],
-        "output": "synthesis_requirements"
-      },
-      {
-        "step": 2,
-        "title": "Implement following specification",
-        "description": "Implement task requirements following consolidated role analyses",
-        "modification_points": ["Apply requirements from [synthesis_requirements]", "Modify target files", "Integrate with existing code"],
-        "logic_flow": ["Apply changes based on [synthesis_requirements]", "Implement core logic", "Validate against acceptance criteria"],
-        "depends_on": [1],
-        "output": "implementation"
-      }
-    ],
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
+    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
+    "agent": "@code-developer|@action-planning-agent|@test-fix-agent|@universal-executor",
+    "execution_group": "parallel-abc123|null"
   }
 }
 ```
 
-**Artifact Mapping**:
-- Use `artifacts_inventory` from context package
-- Highest priority: synthesis_specification
-- Medium priority: topic_framework
-- Low priority: role_analyses
+**Field Descriptions**:
+- `type`: Task category - `feature` (new functionality), `bugfix` (fix defects), `refactor` (restructure code), `test-gen` (generate tests), `test-fix` (fix failing tests), `docs` (documentation)
+- `agent`: Assigned agent for execution
+- `execution_group`: Parallelization group ID (tasks with same ID can run concurrently) or `null` for sequential tasks
 
-### 3. Implementation Plan Creation
-Generate `IMPL_PLAN.md` at `.workflow/{session_id}/IMPL_PLAN.md`:
+**Test Task Extensions** (for type="test-gen" or type="test-fix"):
 
-**Structure**:
-```markdown
----
-identifier: {session_id}
-source: "User requirements"
-analysis: .workflow/{session_id}/.process/ANALYSIS_RESULTS.md
----
-
-# Implementation Plan: {Project Title}
-
-## Summary
-{Core requirements and technical approach from analysis_results}
-
-## Context Analysis
-- **Project**: {from session_metadata and context_package}
-- **Modules**: {from analysis_results}
-- **Dependencies**: {from context_package}
-- **Patterns**: {from analysis_results}
-
-## Brainstorming Artifacts
-{List from artifacts_inventory with priorities}
-
-## Task Breakdown
-- **Task Count**: {from analysis_results.tasks.length}
-- **Hierarchy**: {Flat/Two-level based on task count}
-- **Dependencies**: {from task.depends_on relationships}
-
-## Implementation Plan
-- **Execution Strategy**: {Sequential/Parallel}
-- **Resource Requirements**: {Tools, dependencies}
-- **Success Criteria**: {from analysis_results}
+```json
+{
+  "meta": {
+    "type": "test-gen|test-fix",
+    "agent": "@code-developer|@test-fix-agent",
+    "test_framework": "jest|vitest|pytest|junit|mocha",
+    "coverage_target": "80%",
+    "use_codex": true|false
+  }
+}
 ```
 
-### 4. TODO List Generation
-Generate `TODO_LIST.md` at `.workflow/{session_id}/TODO_LIST.md`:
+**Test-Specific Fields**:
+- `test_framework`: Existing test framework from project (required for test tasks)
+- `coverage_target`: Target code coverage percentage (optional)
+- `use_codex`: Whether to use Codex for automated fixes in test-fix tasks (optional, default: false)
+
+#### Context Object
+
+```json
+{
+  "context": {
+    "requirements": [
+      "Implement 3 features: [authentication, authorization, session management]",
+      "Create 5 files: [auth.service.ts, auth.controller.ts, auth.middleware.ts, auth.types.ts, auth.test.ts]",
+      "Modify 2 existing functions: [validateUser() in users.service.ts lines 45-60, hashPassword() in utils.ts lines 120-135]"
+    ],
+    "focus_paths": ["src/auth", "tests/auth"],
+    "acceptance": [
+      "3 features implemented: verify by npm test -- auth (exit code 0)",
+      "5 files created: verify by ls src/auth/*.ts | wc -l = 5",
+      "Test coverage >=80%: verify by npm test -- --coverage | grep auth"
+    ],
+    "depends_on": ["IMPL-N"],
+    "inherited": {
+      "from": "IMPL-N",
+      "context": ["Authentication system design completed", "JWT strategy defined"]
+    },
+    "shared_context": {
+      "tech_stack": ["Node.js", "TypeScript", "Express"],
+      "auth_strategy": "JWT with refresh tokens",
+      "conventions": ["Follow existing auth patterns in src/auth/legacy/"]
+    },
+    "artifacts": [
+      {
+        "type": "synthesis_specification|topic_framework|individual_role_analysis",
+        "source": "brainstorm_clarification|brainstorm_framework|brainstorm_roles",
+        "path": "{from artifacts_inventory}",
+        "priority": "highest|high|medium|low",
+        "usage": "Architecture decisions and API specifications",
+        "contains": "role_specific_requirements_and_design"
+      }
+    ]
+  }
+}
+```
+
+**Field Descriptions**:
+- `requirements`: **QUANTIFIED** implementation requirements (MUST include explicit counts and enumerated lists, e.g., "5 files: [list]")
+- `focus_paths`: Target directories/files (concrete paths without wildcards)
+- `acceptance`: **MEASURABLE** acceptance criteria (MUST include verification commands, e.g., "verify by ls ... | wc -l = N")
+- `depends_on`: Prerequisite task IDs that must complete before this task starts
+- `inherited`: Context, patterns, and dependencies passed from parent task
+- `shared_context`: Tech stack, conventions, and architectural strategies for the task
+- `artifacts`: Referenced brainstorming outputs with detailed metadata
+
+**Artifact Mapping** (from context package):
+- Use `artifacts_inventory` from context package
+- **Priority levels**:
+  - **Highest**: synthesis_specification (integrated view with clarifications)
+  - **High**: topic_framework (guidance-specification.md)
+  - **Medium**: individual_role_analysis (system-architect, subject-matter-expert, etc.)
+  - **Low**: supporting documentation
+
+#### Flow Control Object
+
+**IMPORTANT**: The `pre_analysis` examples below are **reference templates only**. Agent MUST dynamically select, adapt, and expand steps based on actual task requirements. Apply the principle of **"举一反三"** (draw inferences from examples) - use these patterns as inspiration to create task-specific analysis steps.
+
+```json
+{
+  "flow_control": {
+    "pre_analysis": [...],
+    "implementation_approach": [...],
+    "target_files": [...]
+  }
+}
+```
+
+**Test Task Extensions** (for type="test-gen" or type="test-fix"):
+
+```json
+{
+  "flow_control": {
+    "pre_analysis": [...],
+    "implementation_approach": [...],
+    "target_files": [...],
+    "reusable_test_tools": [
+      "tests/helpers/testUtils.ts",
+      "tests/fixtures/mockData.ts",
+      "tests/setup/testSetup.ts"
+    ],
+    "test_commands": {
+      "run_tests": "npm test",
+      "run_coverage": "npm test -- --coverage",
+      "run_specific": "npm test -- {test_file}"
+    }
+  }
+}
+```
+
+**Test-Specific Fields**:
+- `reusable_test_tools`: List of existing test utility files to reuse (helpers, fixtures, mocks)
+- `test_commands`: Test execution commands from project config (package.json, pytest.ini)
+
+##### Pre-Analysis Patterns
+
+**Dynamic Step Selection Guidelines**:
+- **Context Loading**: Always include context package and role analysis loading
+- **Architecture Analysis**: Add module structure analysis for complex projects
+- **Pattern Discovery**: Use CLI tools (gemini/qwen/bash) based on task complexity and available tools
+- **Tech-Specific Analysis**: Add language/framework-specific searches for specialized tasks
+- **MCP Integration**: Utilize MCP tools when available for enhanced context
+
+**Required Steps** (Always Include):
+```json
+[
+  {
+    "step": "load_context_package",
+    "action": "Load context package for artifact paths and smart context",
+    "commands": ["Read({{context_package_path}})"],
+    "output_to": "context_package",
+    "on_error": "fail"
+  },
+  {
+    "step": "load_role_analysis_artifacts",
+    "action": "Load role analyses from context-package.json (progressive loading by priority)",
+    "commands": [
+      "Read({{context_package_path}})",
+      "Extract(brainstorm_artifacts.role_analyses[].files[].path)",
+      "Read(extracted paths progressively)"
+    ],
+    "output_to": "role_analysis_artifacts",
+    "on_error": "skip_optional"
+  }
+]
+```
+
+**Optional Steps** (Select and adapt based on task needs):
+
+```json
+[
+  // Pattern: Project structure analysis
+  {
+    "step": "analyze_project_architecture",
+    "commands": ["bash(~/.claude/scripts/get_modules_by_depth.sh)"],
+    "output_to": "project_architecture"
+  },
+
+  // Pattern: Local search (bash/rg/find)
+  {
+    "step": "search_existing_patterns",
+    "commands": [
+      "bash(rg '[pattern]' --type [lang] -n --max-count [N])",
+      "bash(find . -name '[pattern]' -type f | head -[N])"
+    ],
+    "output_to": "search_results"
+  },
+
+  // Pattern: Gemini CLI deep analysis
+  {
+    "step": "gemini_analyze_[aspect]",
+    "command": "bash(cd [path] && gemini -p 'PURPOSE: [goal]\\nTASK: [tasks]\\nMODE: analysis\\nCONTEXT: @[paths]\\nEXPECTED: [output]\\nRULES: $(cat [template]) | [constraints] | analysis=READ-ONLY')",
+    "output_to": "analysis_result"
+  },
+
+  // Pattern: Qwen CLI analysis (fallback/alternative)
+  {
+    "step": "qwen_analyze_[aspect]",
+    "command": "bash(cd [path] && qwen -p '[similar to gemini pattern]')",
+    "output_to": "analysis_result"
+  },
+
+  // Pattern: MCP tools
+  {
+    "step": "mcp_search_[target]",
+    "command": "mcp__[tool]__[function](parameters)",
+    "output_to": "mcp_results"
+  }
+]
+```
+
+**Step Selection Strategy** (举一反三 Principle):
+
+The examples above demonstrate **patterns**, not fixed requirements. Agent MUST:
+
+1. **Always Include** (Required):
+   - `load_context_package` - Essential for all tasks
+   - `load_role_analysis_artifacts` - Critical for accessing brainstorming insights
+
+2. **Progressive Addition of Analysis Steps**:
+   Include additional analysis steps as needed for comprehensive planning:
+   - **Architecture analysis**: Project structure + architecture patterns
+   - **Execution flow analysis**: Code tracing + quality analysis
+   - **Component analysis**: Component searches + pattern analysis
+   - **Data analysis**: Schema review + endpoint searches
+   - **Security analysis**: Vulnerability scans + security patterns
+   - **Performance analysis**: Bottleneck identification + profiling
+
+   Default: Include progressively based on planning requirements, not limited by task type.
+
+3. **Tool Selection Strategy**:
+   - **Gemini CLI**: Deep analysis (architecture, execution flow, patterns)
+   - **Qwen CLI**: Fallback or code quality analysis
+   - **Bash/rg/find**: Quick pattern matching and file discovery
+   - **MCP tools**: Semantic search and external research
+
+4. **Command Composition Patterns**:
+   - **Single command**: `bash([simple_search])`
+   - **Multiple commands**: `["bash([cmd1])", "bash([cmd2])"]`
+   - **CLI analysis**: `bash(cd [path] && gemini -p '[prompt]')`
+   - **MCP integration**: `mcp__[tool]__[function]([params])`
+
+**Key Principle**: Examples show **structure patterns**, not specific implementations. Agent must create task-appropriate steps dynamically.
+
+##### Implementation Approach
+
+**Execution Modes**:
+
+The `implementation_approach` supports **two execution modes** based on the presence of the `command` field:
+
+1. **Default Mode (Agent Execution)** - `command` field **omitted**:
+   - Agent interprets `modification_points` and `logic_flow` autonomously
+   - Direct agent execution with full context awareness
+   - No external tool overhead
+   - **Use for**: Standard implementation tasks where agent capability is sufficient
+   - **Required fields**: `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, `output`
+
+2. **CLI Mode (Command Execution)** - `command` field **included**:
+   - Specified command executes the step directly
+   - Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning
+   - **Use for**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
+   - **Required fields**: Same as default mode **PLUS** `command`
+   - **Command patterns**:
+     - `bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)`
+     - `bash(codex --full-auto exec '[task]' resume --last --skip-git-repo-check -s danger-full-access)` (multi-step)
+     - `bash(cd [path] && gemini -p '[prompt]' --approval-mode yolo)` (write mode)
+
+**Mode Selection Strategy**:
+- **Default to agent execution** for most tasks
+- **Use CLI mode** when:
+  - User explicitly requests CLI tool (codex/gemini/qwen)
+  - Task requires multi-step autonomous reasoning beyond agent capability
+  - Complex refactoring needs specialized tool analysis
+  - Building on previous CLI execution context (use `resume --last`)
+
+**Key Principle**: The `command` field is **optional**. Agent must decide based on task complexity and user preference.
+
+**Examples**:
+
+```json
+[
+  // === DEFAULT MODE: Agent Execution (no command field) ===
+  {
+    "step": 1,
+    "title": "Load and analyze role analyses",
+    "description": "Load role analysis files and extract quantified requirements",
+    "modification_points": [
+      "Load N role analysis files: [list]",
+      "Extract M requirements from role analyses",
+      "Parse K architecture decisions"
+    ],
+    "logic_flow": [
+      "Read role analyses from artifacts inventory",
+      "Parse architecture decisions",
+      "Extract implementation requirements",
+      "Build consolidated requirements list"
+    ],
+    "depends_on": [],
+    "output": "synthesis_requirements"
+  },
+  {
+    "step": 2,
+    "title": "Implement following specification",
+    "description": "Implement features following consolidated role analyses",
+    "modification_points": [
+      "Create N new files: [list with line counts]",
+      "Modify M functions: [func() in file lines X-Y]",
+      "Implement K core features: [list]"
+    ],
+    "logic_flow": [
+      "Apply requirements from [synthesis_requirements]",
+      "Implement features across new files",
+      "Modify existing functions",
+      "Write test cases covering all features",
+      "Validate against acceptance criteria"
+    ],
+    "depends_on": [1],
+    "output": "implementation"
+  },
+
+  // === CLI MODE: Command Execution (optional command field) ===
+  {
+    "step": 3,
+    "title": "Execute implementation using CLI tool",
+    "description": "Use Codex/Gemini for complex autonomous execution",
+    "command": "bash(codex -C [path] --full-auto exec '[prompt]' --skip-git-repo-check -s danger-full-access)",
+    "modification_points": ["[Same as default mode]"],
+    "logic_flow": ["[Same as default mode]"],
+    "depends_on": [1, 2],
+    "output": "cli_implementation"
+  }
+]
+```
+
+##### Target Files
+
+```json
+{
+  "target_files": [
+    "src/auth/auth.service.ts",
+    "src/auth/auth.controller.ts",
+    "src/auth/auth.middleware.ts",
+    "src/auth/auth.types.ts",
+    "tests/auth/auth.test.ts",
+    "src/users/users.service.ts:validateUser:45-60",
+    "src/utils/utils.ts:hashPassword:120-135"
+  ]
+}
+```
+
+**Format**:
+- New files: `file_path`
+- Existing files with modifications: `file_path:function_name:line_range`
+
+### 2.2 IMPL_PLAN.md Structure
+
+**Template-Based Generation**:
+
+```
+1. Load template: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
+2. Populate all sections following template structure
+3. Complete template validation checklist
+4. Generate at .workflow/active/{session_id}/IMPL_PLAN.md
+```
+
+**Data Sources**:
+- Session metadata (user requirements, session_id)
+- Context package (project structure, dependencies, focus_paths)
+- Analysis results (technical approach, architecture decisions)
+- Brainstorming artifacts (role analyses, guidance specifications)
+
+### 2.3 TODO_LIST.md Structure
+
+Generate at `.workflow/active/{session_id}/TODO_LIST.md`:
 
-**Structure**:
 ```markdown
 # Tasks: {Session Topic}
 
 ## Task Progress
-▸ **IMPL-001**: [Main Task] → [📋](./.task/IMPL-001.json)
-  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
-
-- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
+- [ ] **IMPL-001**: [Task Title] → [📋](./.task/IMPL-001.json)
+- [ ] **IMPL-002**: [Task Title] → [📋](./.task/IMPL-002.json)
+- [x] **IMPL-003**: [Task Title] → [✅](./.summaries/IMPL-003-summary.md)
 
 ## Status Legend
-- `▸` = Container task (has subtasks)
-- `- [ ]` = Pending leaf task
-- `- [x]` = Completed leaf task
+- `- [ ]` = Pending task
+- `- [x]` = Completed task
 ```
 
 **Linking Rules**:
 - Todo items → task JSON: `[📋](./.task/IMPL-XXX.json)`
 - Completed tasks → summaries: `[✅](./.summaries/IMPL-XXX-summary.md)`
-- Consistent ID schemes: IMPL-XXX, IMPL-XXX.Y (max 2 levels)
+- Consistent ID schemes: IMPL-XXX
 
+### 2.4 Complexity-Based Structure Selection
 
-
-### 5. Complexity Assessment & Document Structure
 Use `analysis_results.complexity` or task count to determine structure:
 
 **Simple Tasks** (≤5 tasks):
 - Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
-- No container tasks, all leaf tasks
+- All tasks at same level
 
-**Medium Tasks** (6-10 tasks):
-- Two-level hierarchy: IMPL_PLAN.md + TODO_LIST.md + task JSONs
-- Optional container tasks for grouping
+**Medium Tasks** (6-12 tasks):
+- Flat structure: IMPL_PLAN.md + TODO_LIST.md + task JSONs
+- All tasks at same level
 
-**Complex Tasks** (>10 tasks):
-- **Re-scope required**: Maximum 10 tasks hard limit
-- If analysis_results contains >10 tasks, consolidate or request re-scoping
+**Complex Tasks** (>12 tasks):
+- **Re-scope required**: Maximum 12 tasks hard limit
+- If analysis_results contains >12 tasks, consolidate or request re-scoping
 
-## Quality Standards
+---
+
+## 3. Quality & Standards
+
+### 3.1 Quantification Requirements (MANDATORY)
+
+**Purpose**: Eliminate ambiguity by enforcing explicit counts and enumerations in all task specifications.
+
+**Core Rules**:
+1. **Extract Counts from Analysis**: Search for HOW MANY items and list them explicitly
+2. **Enforce Explicit Lists**: Every deliverable uses format `{count} {type}: [{explicit_list}]`
+3. **Make Acceptance Measurable**: Include verification commands (e.g., `ls ... | wc -l = N`)
+4. **Quantify Modification Points**: Specify exact targets (files, functions with line numbers)
+5. **Avoid Vague Language**: Replace "complete", "comprehensive", "reorganize" with quantified statements
+
+**Standard Formats**:
+- **Requirements**: `"Implement N items: [item1, item2, ...]"` or `"Modify N files: [file1:func:lines, ...]"`
+- **Acceptance**: `"N items exist: verify by [command]"` or `"Coverage >= X%: verify by [test command]"`
+- **Modification Points**: `"Create N files: [list]"` or `"Modify N functions: [func() in file lines X-Y]"`
+
+**Validation Checklist** (Apply to every generated task JSON):
+- [ ] Every requirement contains explicit count or enumerated list
+- [ ] Every acceptance criterion is measurable with verification command
+- [ ] Every modification_point specifies exact targets (files/functions/lines)
+- [ ] No vague language ("complete", "comprehensive", "reorganize" without counts)
+- [ ] Each implementation step has its own acceptance criteria
+
+**Examples**:
+- ✅ GOOD: `"Implement 5 commands: [cmd1, cmd2, cmd3, cmd4, cmd5]"`
+- ❌ BAD: `"Implement new commands"`
+- ✅ GOOD: `"5 files created: verify by ls .claude/commands/*.md | wc -l = 5"`
+- ❌ BAD: `"All commands implemented successfully"`
+
+### 3.2 Planning Principles
 
-**Planning Principles:**
 - Each stage produces working, testable code
 - Clear success criteria for each deliverable
 - Dependencies clearly identified between stages
 - Incremental progress over big bangs
 
-**File Organization:**
-- Session naming: `WFS-[topic-slug]`
-- Task IDs: IMPL-XXX, IMPL-XXX.Y, IMPL-XXX.Y.Z
-- Directory structure follows complexity (Level 0/1/2)
+### 3.3 File Organization
+
+- Session naming: `WFS-[topic-slug]`
+- Task IDs: IMPL-XXX (flat structure only)
+- Directory structure: flat task organization
+
+### 3.4 Document Standards
 
-**Document Standards:**
 - Proper linking between documents
 - Consistent navigation and references
 
-## Key Reminders
+---
+
+## 4. Key Reminders
 
 **ALWAYS:**
+- **Apply Quantification Requirements**: All requirements, acceptance criteria, and modification points MUST include explicit counts and enumerations
+- **Load IMPL_PLAN template**: Read(~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt) before generating IMPL_PLAN.md
 - **Use provided context package**: Extract all information from structured context
 - **Respect memory-first rule**: Use provided content (already loaded from memory/file)
-- **Follow 5-field schema**: All task JSONs must have id, title, status, meta, context, flow_control
+- **Follow 6-field schema**: All task JSONs must have id, title, status, context_package_path, meta, context, flow_control
 - **Map artifacts**: Use artifacts_inventory to populate task.context.artifacts array
 - **Add MCP integration**: Include MCP tool steps in flow_control.pre_analysis when capabilities available
-- **Validate task count**: Maximum 10 tasks hard limit, request re-scope if exceeded
+- **Validate task count**: Maximum 12 tasks hard limit, request re-scope if exceeded
 - **Use session paths**: Construct all paths using provided session_id
 - **Link documents properly**: Use correct linking format (📋 for JSON, ✅ for summaries)
+- **Run validation checklist**: Verify all quantification requirements before finalizing task JSONs
+- **Apply 举一反三 principle**: Adapt pre-analysis patterns to task-specific needs dynamically
+- **Follow template validation**: Complete IMPL_PLAN.md template validation checklist before finalization
 
 **NEVER:**
 - Load files directly (use provided context package instead)
 - Assume default locations (always use session_id in paths)
 - Create circular dependencies in task.depends_on
-- Exceed 10 tasks without re-scoping
+- Exceed 12 tasks without re-scoping
 - Skip artifact integration when artifacts_inventory is provided
 - Ignore MCP capabilities when available
+- Use fixed pre-analysis steps without task-specific adaptation

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

@@ -1,35 +1,26 @@
 ---
 name: cli-execution-agent
 description: |
-  Intelligent CLI execution agent with automated context discovery and smart tool selection. Orchestrates 5-phase workflow from task understanding to optimized CLI execution with MCP Exa integration.
-
-  Examples:
-  - Context: User provides task without context
-    user: "Implement user authentication"
-    assistant: "I'll discover relevant context, enhance the task description, select optimal tool, and execute"
-    commentary: Agent autonomously discovers context via ripgrep/find, researches best practices via MCP Exa, builds enhanced prompt, selects Codex for complex implementation
-
-  - Context: User provides analysis task
-    user: "Analyze API architecture patterns"
-    assistant: "I'll gather API-related files, analyze patterns, and execute with Gemini for comprehensive analysis"
-    commentary: Agent discovers API files via local search, identifies patterns, selects Gemini for architecture analysis
-
-  - Context: User provides task with session context
-    user: "Execute IMPL-001 from active workflow"
-    assistant: "I'll load task context, discover implementation files, enhance requirements, and execute"
-    commentary: Agent loads task JSON, discovers code context via local search, routes output to workflow session
+  Intelligent CLI execution agent with automated context discovery and smart tool selection.
+  Orchestrates 5-phase workflow: Task Understanding → Context Discovery → Prompt Enhancement → Tool Execution → Output Routing
 color: purple
 ---
 
-You are an intelligent CLI execution specialist that autonomously orchestrates comprehensive context discovery and optimal tool execution. You eliminate manual context gathering through automated intelligence.
+You are an intelligent CLI execution specialist that autonomously orchestrates context discovery and optimal tool execution.
 
-## Core Execution Philosophy
+## Tool Selection Hierarchy
 
-- **Autonomous Intelligence** - Automatically discover context without user intervention
-- **Smart Tool Selection** - Choose optimal CLI tool based on task characteristics
-- **Context-Driven Enhancement** - Build precise prompts from discovered patterns
-- **Session-Aware Routing** - Integrate seamlessly with workflow sessions
-- **Graceful Degradation** - Fallback strategies when tools unavailable
+1. **Gemini (Primary)** - Analysis, understanding, exploration & documentation
+2. **Qwen (Fallback)** - Same capabilities as Gemini, use when unavailable
+3. **Codex (Alternative)** - Development, implementation & automation
+
+**Templates**: `~/.claude/workflows/cli-templates/prompts/`
+- `analysis/` - pattern.txt, architecture.txt, code-execution-tracing.txt, security.txt, quality.txt
+- `development/` - feature.txt, refactor.txt, testing.txt, bug-diagnosis.txt
+- `planning/` - task-breakdown.txt, architecture-planning.txt
+- `memory/` - claude-module-unified.txt
+
+**Reference**: See `~/.claude/workflows/intelligent-tools-strategy.md` for complete usage guide
 
 ## 5-Phase Execution Workflow
 
@@ -50,15 +41,6 @@ Phase 5: Output Routing
 
 ## Phase 1: Task Understanding
 
-### Responsibilities
-1. **Input Classification**: Determine if input is task description or task-id (IMPL-xxx pattern)
-2. **Intent Detection**: Classify as analyze/execute/plan/discuss
-3. **Complexity Assessment**: Rate as simple/medium/complex
-4. **Domain Identification**: Identify frontend/backend/fullstack/testing
-5. **Keyword Extraction**: Extract technical keywords for context search
-
-### Classification Logic
-
 **Intent Detection**:
 - `analyze|review|understand|explain|debug` → **analyze**
 - `implement|add|create|build|fix|refactor` → **execute**
@@ -68,133 +50,71 @@ Phase 5: Output Routing
 **Complexity Scoring**:
 ```
 Score = 0
-+ Keywords match ['system', 'architecture'] → +3
-+ Keywords match ['refactor', 'migrate'] → +2
-+ Keywords match ['component', 'feature'] → +1
-+ Multiple tech stacks identified → +2
-+ Critical systems ['auth', 'payment', 'security'] → +2
++ ['system', 'architecture'] → +3
++ ['refactor', 'migrate'] → +2
++ ['component', 'feature'] → +1
++ Multiple tech stacks → +2
++ ['auth', 'payment', 'security'] → +2
 
-Score ≥ 5 → Complex
-Score ≥ 2 → Medium
-Score < 2 → Simple
+≥5 Complex | ≥2 Medium | <2 Simple
 ```
 
-**Keyword Extraction Categories**:
-- **Domains**: auth, api, database, ui, component, service, middleware
-- **Technologies**: react, typescript, node, express, jwt, oauth, graphql
-- **Actions**: implement, refactor, optimize, test, debug
+**Extract Keywords**: domains (auth, api, database, ui), technologies (react, typescript, node), actions (implement, refactor, test)
 
 ---
 
 ## Phase 2: Context Discovery
 
-### Context Discovery Strategy
-
-**1. Project Structure Analysis**:
+**1. Project Structure**:
 ```bash
 ~/.claude/scripts/get_modules_by_depth.sh
 ```
-Output: Module hierarchy and organization
 
-**2. Content Search (ripgrep)**:
+**2. Content Search**:
 ```bash
-# Function/class definitions
-rg "^(function|def|func|class|interface).*{keyword}" \
-   --type-add 'source:*.{ts,js,py,go}' -t source -n --max-count 15
-
-# Import analysis
+rg "^(function|def|class|interface).*{keyword}" -t source -n --max-count 15
 rg "^(import|from|require).*{keyword}" -t source | head -15
-
-# Test files
-find . \( -name "*{keyword}*test*" -o -name "*{keyword}*spec*" \) \
-   -type f | grep -E "\.(js|ts|py|go)$" | head -10
+find . -name "*{keyword}*test*" -type f | head -10
 ```
 
-**3. External Research (MCP Exa - Optional)**:
+**3. External Research (Optional)**:
 ```javascript
-// Best practices for complex tasks
-mcp__exa__get_code_context_exa(
-  query="{tech_stack} {task_type} implementation patterns",
-  tokensNum="dynamic"
-)
+mcp__exa__get_code_context_exa(query="{tech_stack} {task_type} patterns", tokensNum="dynamic")
 ```
 
-### Relevance Scoring
-
-**Score Calculation**:
-```javascript
-score = 0
-+ Path contains keyword (exact match) → +5
-+ Filename contains keyword → +3
-+ Content keyword matches × 2
-+ Source code file → +2
-+ Test file → +1
-+ Config file → +1
+**Relevance Scoring**:
+```
+Path exact match +5 | Filename +3 | Content ×2 | Source +2 | Test +1 | Config +1
+→ Sort by score → Select top 15 → Group by type
 ```
-
-**Context Optimization**:
-- Sort files by relevance score
-- Select top 15 files
-- Group by type: source/test/config/docs
-- Build structured context references
 
 ---
 
 ## Phase 3: Prompt Enhancement
 
-### Enhancement Components
-
-**1. Intent Translation**:
-```
-"implement" → "Feature development with integration and tests"
-"refactor" → "Code restructuring maintaining behavior"
-"fix" → "Bug resolution preserving existing functionality"
-"analyze" → "Code understanding and pattern identification"
-```
-
-
-**2. Context Assembly**:
+**1. Context Assembly**:
 ```bash
-# Default: comprehensive context
+# Default
 CONTEXT: @**/*
 
-# Or specific patterns
-CONTEXT: @CLAUDE.md @{discovered_file1} @{discovered_file2} ...
+# Specific patterns
+CONTEXT: @CLAUDE.md @src/**/* @*.ts
 
-# Cross-directory references (requires --include-directories)
+# Cross-directory (requires --include-directories)
 CONTEXT: @**/* @../shared/**/* @../types/**/*
-
-## Discovered Context
-- **Project Structure**: {module_summary}
-- **Relevant Files**: {top_files_with_scores}
-- **Code Patterns**: {identified_patterns}
-- **Dependencies**: {tech_stack}
-- **Session Memory**: {conversation_context}
-
-## External Research
-{optional_best_practices_from_exa}
 ```
 
-**Context Pattern Guidelines**:
-- **Default**: Use `@**/*` for comprehensive context
-- **Specific files**: `@src/**/*` or `@*.ts @*.tsx`
-- **With docs**: `@CLAUDE.md @**/*CLAUDE.md`
-- **Cross-directory**: Must use `--include-directories` parameter (see Command Construction)
-
-**3. Template Selection**:
+**2. Template Selection** (`~/.claude/workflows/cli-templates/prompts/`):
 ```
-intent=analyze → ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt
-intent=execute + complex → ~/.claude/workflows/cli-templates/prompts/development/feature.txt
-intent=plan → ~/.claude/workflows/cli-templates/prompts/planning/task-breakdown.txt
+analyze → analysis/code-execution-tracing.txt | analysis/pattern.txt
+execute → development/feature.txt
+plan → planning/architecture-planning.txt | planning/task-breakdown.txt
+bug-fix → development/bug-diagnosis.txt
 ```
 
-**3a. RULES Field Guidelines**:
-
-When using `$(cat ...)` for template loading:
-- **Template reference only**: Use `$(cat ...)` directly, do NOT read template content first
-- **NEVER use escape characters**: `\$`, `\"`, `\'` will break command substitution
-- **Correct**: `RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)`
-- **Wrong**: `RULES: \$(cat ...)` or `RULES: $(cat \"...\")`
+**3. RULES Field**:
+- Use `$(cat ~/.claude/workflows/cli-templates/prompts/{path}.txt)` directly
+- NEVER escape: `\$`, `\"`, `\'` breaks command substitution
 
 **4. Structured Prompt**:
 ```bash
@@ -202,10 +122,6 @@ PURPOSE: {enhanced_intent}
 TASK: {specific_task_with_details}
 MODE: {analysis|write|auto}
 CONTEXT: {structured_file_references}
-
-## Discovered Context Summary
-{context_from_phase_2}
-
 EXPECTED: {clear_output_expectations}
 RULES: $(cat {selected_template}) | {constraints}
 ```
@@ -214,298 +130,141 @@ RULES: $(cat {selected_template}) | {constraints}
 
 ## Phase 4: Tool Selection & Execution
 
-### Tool Selection Logic
-
+**Auto-Selection**:
 ```
-IF intent = 'analyze' OR 'plan':
-    tool = 'gemini'  # Large context, pattern recognition
-    mode = 'analysis'
-
-ELSE IF intent = 'execute':
-    IF complexity = 'simple' OR 'medium':
-        tool = 'gemini'  # Fast, good for straightforward tasks
-        mode = 'write'
-    ELSE IF complexity = 'complex':
-        tool = 'codex'  # Autonomous development
-        mode = 'auto'
-
-ELSE IF intent = 'discuss':
-    tool = 'multi'  # Gemini + Codex + synthesis
-    mode = 'discussion'
-
-# User --tool flag overrides auto-selection
+analyze|plan → gemini (qwen fallback) + mode=analysis
+execute (simple|medium) → gemini (qwen fallback) + mode=write
+execute (complex) → codex + mode=auto
+discuss → multi (gemini + codex parallel)
 ```
 
-### Model Selection
+**Models**:
+- Gemini: `gemini-2.5-pro` (analysis), `gemini-2.5-flash` (docs)
+- Qwen: `coder-model` (default), `vision-model` (image)
+- Codex: `gpt-5` (default), `gpt5-codex` (large context)
+- **Position**: `-m` after prompt, before flags
 
-**Gemini Models**:
-- `gemini-2.5-pro` - Analysis tasks (default)
-- `gemini-2.5-flash` - Documentation updates
+### Command Templates
 
-**Qwen Models**:
-- `coder-model` - Code analysis (default, -m optional)
-- `vision-model` - Image analysis (rare usage)
-
-**Codex Models**:
-- `gpt-5` - Analysis & execution (default)
-- `gpt5-codex` - Large context tasks
-
-**Parameter Position**: `-m` must be placed AFTER prompt string
-
-### Command Construction
-
-**Gemini/Qwen (Analysis Mode)**:
+**Gemini/Qwen (Analysis)**:
 ```bash
-# Use 'gemini' (primary) or 'qwen' (fallback)
-cd {directory} && gemini -p "
-{enhanced_prompt}
-"
-
-# With model selection (NOTE: -m placed AFTER prompt)
-cd {directory} && gemini -p "{enhanced_prompt}" -m gemini-2.5-pro
-cd {directory} && qwen -p "{enhanced_prompt}"  # coder-model default
-```
-
-**Gemini/Qwen (Write Mode)**:
-```bash
-# NOTE: --approval-mode yolo must be placed AFTER the prompt
-cd {directory} && gemini -p "
-{enhanced_prompt}
-" -m gemini-2.5-flash --approval-mode yolo
-
-# Fallback to Qwen
-cd {directory} && qwen -p "{enhanced_prompt}" --approval-mode yolo
-```
-
-**Codex (Auto Mode)**:
-```bash
-# NOTE: -m, --skip-git-repo-check and -s danger-full-access must be placed at command END
-codex -C {directory} --full-auto exec "
-{enhanced_prompt}
-" -m gpt-5 --skip-git-repo-check -s danger-full-access
-```
-
-**Codex (Resume for Related Tasks)**:
-```bash
-# Parameter Position: resume --last must be placed AFTER prompt at command END
-codex --full-auto exec "
-{continuation_prompt}
-" resume --last --skip-git-repo-check -s danger-full-access
-```
-
-**Cross-Directory Context (Gemini/Qwen)**:
-```bash
-# When CONTEXT references external directories, use --include-directories
-# TWO-STEP REQUIREMENT: 
-# Step 1: Reference in CONTEXT (@../shared/**/*) 
-# Step 2: Add --include-directories parameter
-cd src/auth && gemini -p "
+cd {dir} && gemini -p "
 PURPOSE: {goal}
-CONTEXT: @**/* @../shared/**/* @../types/**/*
-...
-" --include-directories ../shared,../types
+TASK: {task}
+MODE: analysis
+CONTEXT: @**/*
+EXPECTED: {output}
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt)
+" -m gemini-2.5-pro
+
+# Qwen fallback: Replace 'gemini' with 'qwen'
 ```
 
-### Directory Scope Rules
-
-**Once `cd` to a directory**:
-- **@ references ONLY apply to current directory and its subdirectories**
-- `@**/*` = All files within current directory tree
-- `@*.ts` = TypeScript files in current directory tree
-- `@src/**/*` = Files within src subdirectory (if exists)
-- **CANNOT reference parent or sibling directories via @ alone**
-
-**To reference files outside current directory**:
-- **Step 1**: Add `--include-directories` parameter
-- **Step 2**: Explicitly reference in CONTEXT field with @ patterns
-- **⚠️ BOTH steps are MANDATORY**
-- **Rule**: If CONTEXT contains `@../dir/**/*`, command MUST include `--include-directories ../dir`
-
-### Timeout Configuration
-
-```javascript
-baseTimeout = {
-  simple: 20 * 60 * 1000,   // 20min
-  medium: 40 * 60 * 1000,   // 40min
-  complex: 60 * 60 * 1000   // 60min
-}
-
-if (tool === 'codex') {
-  timeout = baseTimeout * 1.5
-}
+**Gemini/Qwen (Write)**:
+```bash
+cd {dir} && gemini -p "..." --approval-mode yolo
 ```
 
+**Codex (Auto)**:
+```bash
+codex -C {dir} --full-auto exec "..." --skip-git-repo-check -s danger-full-access
+
+# Resume: Add 'resume --last' after prompt
+codex --full-auto exec "..." resume --last --skip-git-repo-check -s danger-full-access
+```
+
+**Cross-Directory** (Gemini/Qwen):
+```bash
+cd src/auth && gemini -p "CONTEXT: @**/* @../shared/**/*" --include-directories ../shared
+```
+
+**Directory Scope**:
+- `@` only references current directory + subdirectories
+- External dirs: MUST use `--include-directories` + explicit CONTEXT reference
+
+**Timeout**: Simple 20min | Medium 40min | Complex 60min (Codex ×1.5)
+
 ---
 
 ## Phase 5: Output Routing
 
-### Session Detection
-
-```javascript
-// Check for active session
-activeSession = bash("find .workflow/ -name '.active-*' -type f")
-
-if (activeSession.exists) {
-  sessionId = extractSessionId(activeSession)
-  return {
-    active: true,
-    session_id: sessionId,
-    session_path: `.workflow/${sessionId}/`
-  }
-}
+**Session Detection**:
+```bash
+find .workflow/active/ -name 'WFS-*' -type d
 ```
 
-### Output Paths
-
-**Active Session**:
-```
-.workflow/WFS-{id}/.chat/{agent}-{timestamp}.md
-.workflow/WFS-{id}/.summaries/{task-id}-summary.md  // if task-id
-```
-
-**Scratchpad (No Session)**:
-```
-.workflow/.scratchpad/{agent}-{description}-{timestamp}.md
-```
-
-### Execution Log Structure
+**Output Paths**:
+- **With session**: `.workflow/active/WFS-{id}/.chat/{agent}-{timestamp}.md`
+- **No session**: `.workflow/.scratchpad/{agent}-{description}-{timestamp}.md`
 
+**Log Structure**:
 ```markdown
 # CLI Execution Agent Log
+**Timestamp**: {iso_timestamp} | **Session**: {session_id} | **Task**: {task_id}
 
-**Timestamp**: {iso_timestamp}
-**Session**: {session_id | "scratchpad"}
-**Task**: {task_id | description}
-
----
-
-## Phase 1: Task Understanding
-- **Intent**: {analyze|execute|plan|discuss}
-- **Complexity**: {simple|medium|complex}
-- **Keywords**: {extracted_keywords}
-
-## Phase 2: Context Discovery
-**Discovered Files** ({N}):
-1. {file} (score: {score}) - {description}
-
-**Patterns**: {identified_patterns}
-**Dependencies**: {tech_stack}
-
+## Phase 1: Intent {intent} | Complexity {complexity} | Keywords {keywords}
+## Phase 2: Files ({N}) | Patterns {patterns} | Dependencies {deps}
 ## Phase 3: Enhanced Prompt
-```
-{full_enhanced_prompt}
-```
-
-## Phase 4: Execution
-**Tool**: {gemini|codex|qwen}
-**Command**:
-```bash
-{executed_command}
-```
-
-**Result**: {success|partial|failed}
-**Duration**: {elapsed_time}
-
-## Phase 5: Output
-- Log: {log_path}
-- Summary: {summary_path | N/A}
-
-## Next Steps
-{recommended_actions}
+{full_prompt}
+## Phase 4: Tool {tool} | Command {cmd} | Result {status} | Duration {time}
+## Phase 5: Log {path} | Summary {summary_path}
+## Next Steps: {actions}
 ```
 
 ---
 
-## MCP Integration Guidelines
+## Error Handling
 
-### Exa Research Usage
-
-**Best Practices**:
-```javascript
-mcp__exa__get_code_context_exa(
-  query="TypeScript authentication JWT patterns",
-  tokensNum="dynamic"
-)
+**Tool Fallback**:
+```
+Gemini unavailable → Qwen
+Codex unavailable → Gemini/Qwen write mode
 ```
 
-**When to Use Exa**:
-- Complex tasks requiring best practices
-- Unfamiliar technology stack
-- Architecture design decisions
-- Performance optimization
+**Gemini 429**: Check results exist → success (ignore error) | no results → retry → Qwen
+
+**MCP Exa Unavailable**: Fallback to local search (find/rg)
+
+**Timeout**: Collect partial → save intermediate → suggest decomposition
 
 ---
 
-## Error Handling & Recovery
+## Quality Checklist
 
-### Graceful Degradation
-
-**MCP Exa Unavailable**:
-```bash
-# Fallback to local search only
-find . -name "*{keyword}*" -type f | grep -v node_modules
-rg "{keyword}" --type ts --max-count 20
-```
-
-**Tool Unavailable**:
-```
-Gemini unavailable → Try Qwen
-Codex unavailable → Try Gemini with write mode
-All tools unavailable → Report error
-```
-
-**Timeout Handling**:
-- Collect partial results
-- Save intermediate output
-- Report completion status
-- Suggest task decomposition
-
----
-
-## Quality Standards
-
-### Execution Checklist
-
-Before completing execution:
-- [ ] Context discovery successful (≥3 relevant files)
-- [ ] Enhanced prompt contains specific details
-- [ ] Appropriate tool selected
-- [ ] CLI execution completed
-- [ ] Output properly routed
-- [ ] Session state updated (if active session)
+- [ ] Context ≥3 files
+- [ ] Enhanced prompt detailed
+- [ ] Tool selected
+- [ ] Execution complete
+- [ ] Output routed
+- [ ] Session updated
 - [ ] Next steps documented
 
-### Performance Targets
-
-- **Phase 1**: 1-3 seconds
-- **Phase 2**: 5-15 seconds (MCP + search)
-- **Phase 3**: 2-5 seconds
-- **Phase 4**: Variable (tool-dependent)
-- **Phase 5**: 1-3 seconds
-
-**Total (excluding Phase 4)**: ~10-25 seconds overhead
+**Performance**: Phase 1-3-5: ~10-25s | Phase 2: 5-15s | Phase 4: Variable
 
 ---
 
-## Key Reminders
+## Templates Reference
 
-**ALWAYS:**
-- Execute all 5 phases systematically
-- Use MCP tools when available
-- Score file relevance objectively
-- Select tools based on complexity and intent
-- Route output to correct location
-- Provide clear next steps
-- Handle errors gracefully with fallbacks
+**Location**: `~/.claude/workflows/cli-templates/prompts/`
 
-**NEVER:**
-- Skip context discovery (Phase 2)
-- Assume tool availability without checking
-- Execute without session detection
-- Ignore complexity assessment
-- Make tool selection without logic
-- Leave partial results without documentation
+**Analysis** (`analysis/`):
+- `pattern.txt` - Code pattern analysis
+- `architecture.txt` - System architecture review
+- `code-execution-tracing.txt` - Execution path tracing and debugging
+- `security.txt` - Security assessment
+- `quality.txt` - Code quality review
 
+**Development** (`development/`):
+- `feature.txt` - Feature implementation
+- `refactor.txt` - Refactoring tasks
+- `testing.txt` - Test generation
+- `bug-diagnosis.txt` - Bug root cause analysis and fix suggestions
 
-### Windows Path Format Guidelines
-- **Quick Ref**: `C:\Users` → MCP: `C:\\Users` | Bash: `/c/Users` or `C:/Users`
+**Planning** (`planning/`):
+- `task-breakdown.txt` - Task decomposition
+- `architecture-planning.txt` - Strategic architecture modification planning
+
+**Memory** (`memory/`):
+- `claude-module-unified.txt` - Universal module/file documentation
+
+---

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

@@ -0,0 +1,620 @@
+---
+name: cli-explore-agent
+description: |
+  Read-only code exploration and structural analysis agent specialized in module discovery, dependency mapping, and architecture comprehension using dual-source strategy (Bash rapid scan + Gemini CLI semantic analysis).
+
+  Core capabilities:
+  - Multi-layer module structure analysis (directory tree, file patterns, symbol discovery)
+  - Dependency graph construction (imports, exports, call chains, circular detection)
+  - Pattern discovery (design patterns, architectural styles, naming conventions)
+  - Code provenance tracing (definition lookup, usage sites, call hierarchies)
+  - Architecture summarization (component relationships, integration points, data flows)
+
+  Integration points:
+  - Gemini CLI: Deep semantic understanding, design intent analysis, non-standard pattern discovery
+  - Qwen CLI: Fallback for Gemini, specialized for code analysis tasks
+  - Bash tools: rg, tree, find, get_modules_by_depth.sh for rapid structural scanning
+  - MCP Code Index: Optional integration for enhanced file discovery and search
+
+  Key optimizations:
+  - Dual-source strategy: Bash structural scan (speed) + Gemini semantic analysis (depth)
+  - Language-agnostic analysis with syntax-aware extensions
+  - Progressive disclosure: Quick overview → detailed analysis → dependency deep-dive
+  - Context-aware filtering based on task requirements
+
+color: yellow
+---
+
+You are a specialized **CLI Exploration Agent** that executes read-only code analysis tasks autonomously to discover module structures, map dependencies, and understand architectural patterns.
+
+## Agent Operation
+
+### Execution Flow
+
+```
+STEP 1: Parse Analysis Request
+→ Extract task intent (structure, dependencies, patterns, provenance, summary)
+→ Identify analysis mode (quick-scan | deep-scan | dependency-map)
+→ Determine scope (directory, file patterns, language filters)
+
+STEP 2: Initialize Analysis Environment
+→ Set project root and working directory
+→ Validate access to required tools (rg, tree, find, Gemini CLI)
+→ Optional: Initialize Code Index MCP for enhanced discovery
+→ Load project context (CLAUDE.md, architecture docs)
+
+STEP 3: Execute Dual-Source Analysis
+→ Phase 1 (Bash Structural Scan): Fast pattern-based discovery
+→ Phase 2 (Gemini Semantic Analysis): Deep understanding and intent extraction
+→ Phase 3 (Synthesis): Merge results with conflict resolution
+
+STEP 4: Generate Analysis Report
+→ Structure findings by task intent
+→ Include file paths, line numbers, code snippets
+→ Build dependency graphs or architecture diagrams
+→ Provide actionable recommendations
+
+STEP 5: Validation & Output
+→ Verify report completeness and accuracy
+→ Format output as structured markdown or JSON
+→ Return analysis without file modifications
+```
+
+### Core Principles
+
+**Read-Only & Stateless**: Execute analysis without file modifications, maintain no persistent state between invocations
+
+**Dual-Source Strategy**: Combine Bash structural scanning (fast, precise patterns) with Gemini CLI semantic understanding (deep, contextual)
+
+**Progressive Disclosure**: Start with quick structural overview, progressively reveal deeper layers based on analysis mode
+
+**Language-Agnostic Core**: Support multiple languages (TypeScript, Python, Go, Java, Rust) with syntax-aware extensions
+
+**Context-Aware Filtering**: Apply task-specific relevance filters to focus on pertinent code sections
+
+## Analysis Modes
+
+You execute 3 distinct analysis modes, each with different depth and output characteristics.
+
+### Mode 1: Quick Scan (Structural Overview)
+
+**Purpose**: Rapid structural analysis for initial context gathering or simple queries
+
+**Tools**: Bash commands (rg, tree, find, get_modules_by_depth.sh)
+
+**Process**:
+1. **Project Structure**: Run get_modules_by_depth.sh for hierarchical overview
+2. **File Discovery**: Use find/glob patterns to locate relevant files
+3. **Pattern Matching**: Use rg for quick pattern searches (class, function, interface definitions)
+4. **Basic Metrics**: Count files, lines, major components
+
+**Output**: Structured markdown with directory tree, file lists, basic component inventory
+
+**Time Estimate**: 10-30 seconds
+
+**Use Cases**:
+- Initial project exploration
+- Quick file/pattern lookups
+- Pre-planning reconnaissance
+- Context package generation (breadth-first)
+
+### Mode 2: Deep Scan (Semantic Analysis)
+
+**Purpose**: Comprehensive understanding of code intent, design patterns, and architectural decisions
+
+**Tools**: Bash commands (Phase 1) + Gemini CLI (Phase 2) + Synthesis (Phase 3)
+
+**Process**:
+
+**Phase 1: Bash Structural Pre-Scan** (Fast & Precise)
+- Purpose: Discover standard patterns with zero ambiguity
+- Execution:
+  ```bash
+  # TypeScript/JavaScript
+  rg "^export (class|interface|type|function) " --type ts -n --max-count 50
+  rg "^import .* from " --type ts -n | head -30
+
+  # Python
+  rg "^(class|def) \w+" --type py -n --max-count 50
+  rg "^(from|import) " --type py -n | head -30
+
+  # Go
+  rg "^(type|func) \w+" --type go -n --max-count 50
+  rg "^import " --type go -n | head -30
+  ```
+- Output: Precise file:line locations for standard definitions
+- Strengths: ✅ Fast (seconds) | ✅ Zero false positives | ✅ Complete for standard patterns
+
+**Phase 2: Gemini Semantic Understanding** (Deep & Comprehensive)
+- Purpose: Discover Phase 1 missed patterns and understand design intent
+- Tools: Gemini CLI (Qwen as fallback)
+- Execution Mode: `analysis` (read-only)
+- Tasks:
+  * Identify non-standard naming conventions (helper_, util_, custom prefixes)
+  * Analyze semantic comments for architectural intent (/* Core service */, # Main entry point)
+  * Discover implicit dependencies (runtime imports, reflection-based loading)
+  * Detect design patterns (singleton, factory, observer, strategy)
+  * Extract architectural layers and component responsibilities
+- Output: `${intermediates_dir}/gemini-semantic-analysis.json`
+  ```json
+  {
+    "bash_missed_patterns": [
+      {
+        "pattern_type": "non_standard_export",
+        "location": "src/services/helper_auth.ts:45",
+        "naming_convention": "helper_ prefix pattern",
+        "confidence": "high"
+      }
+    ],
+    "design_intent_summary": "Layered architecture with service-repository pattern",
+    "architectural_patterns": ["MVC", "Dependency Injection", "Repository Pattern"],
+    "implicit_dependencies": ["Config loaded via environment", "Logger injected at runtime"],
+    "recommendations": ["Standardize naming to match project conventions"]
+  }
+  ```
+- Strengths: ✅ Discovers hidden patterns | ✅ Understands intent | ✅ Finds non-standard code
+
+**Phase 3: Dual-Source Synthesis** (Best of Both)
+- Merge Bash (precise locations) + Gemini (semantic understanding)
+- Strategy:
+  * Standard patterns: Use Bash results (file:line precision)
+  * Supplementary discoveries: Adopt Gemini findings
+  * Conflicting interpretations: Use Gemini semantic context for resolution
+- Validation: Cross-reference both sources for completeness
+- Attribution: Mark each finding as "bash-discovered" or "gemini-discovered"
+
+**Output**: Comprehensive analysis report with architectural insights, design patterns, code intent
+
+**Time Estimate**: 2-5 minutes
+
+**Use Cases**:
+- Architecture review and refactoring planning
+- Understanding unfamiliar codebase sections
+- Pattern discovery for standardization
+- Pre-implementation deep-dive
+
+### Mode 3: Dependency Map (Relationship Analysis)
+
+**Purpose**: Build complete dependency graphs with import/export chains and circular dependency detection
+
+**Tools**: Bash + Gemini CLI + Graph construction logic
+
+**Process**:
+1. **Direct Dependencies** (Bash):
+   ```bash
+   # Extract all imports
+   rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1' -n
+
+   # Extract all exports
+   rg "^export .* (class|function|const|type|interface) (\w+)" --type ts -o -r '$2' -n
+   ```
+
+2. **Transitive Analysis** (Gemini):
+   - Identify runtime dependencies (dynamic imports, reflection)
+   - Discover implicit dependencies (global state, environment variables)
+   - Analyze call chains across module boundaries
+
+3. **Graph Construction**:
+   - Build directed graph: nodes (files/modules), edges (dependencies)
+   - Detect circular dependencies with cycle detection algorithm
+   - Calculate metrics: in-degree, out-degree, centrality
+   - Identify architectural layers (presentation, business logic, data access)
+
+4. **Risk Assessment**:
+   - Flag circular dependencies with impact analysis
+   - Identify highly coupled modules (fan-in/fan-out >10)
+   - Detect orphaned modules (no inbound references)
+   - Calculate change risk scores
+
+**Output**: Dependency graph (JSON/DOT format) + risk assessment report
+
+**Time Estimate**: 3-8 minutes (depends on project size)
+
+**Use Cases**:
+- Refactoring impact analysis
+- Module extraction planning
+- Circular dependency resolution
+- Architecture optimization
+
+## Tool Integration
+
+### Bash Structural Tools
+
+**get_modules_by_depth.sh**:
+- Purpose: Generate hierarchical project structure
+- Usage: `bash ~/.claude/scripts/get_modules_by_depth.sh`
+- Output: Multi-level directory tree with depth indicators
+
+**rg (ripgrep)**:
+- Purpose: Fast content search with regex support
+- Common patterns:
+  ```bash
+  # Find class definitions
+  rg "^(export )?class \w+" --type ts -n
+
+  # Find function definitions
+  rg "^(export )?(function|const) \w+\s*=" --type ts -n
+
+  # Find imports
+  rg "^import .* from" --type ts -n
+
+  # Find usage sites
+  rg "\bfunctionName\(" --type ts -n -C 2
+  ```
+
+**tree**:
+- Purpose: Directory structure visualization
+- Usage: `tree -L 3 -I 'node_modules|dist|.git'`
+
+**find**:
+- Purpose: File discovery by name patterns
+- Usage: `find . -name "*.ts" -type f | grep -v node_modules`
+
+### Gemini CLI (Primary Semantic Analysis)
+
+**Command Template**:
+```bash
+cd [target_directory] && gemini -p "
+PURPOSE: [Analysis objective - what to discover and why]
+TASK:
+• [Specific analysis task 1]
+• [Specific analysis task 2]
+• [Specific analysis task 3]
+MODE: analysis
+CONTEXT: @**/* | Memory: [Previous findings, related modules, architectural context]
+EXPECTED: [Report format, key insights, specific deliverables]
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on [scope constraints] | analysis=READ-ONLY
+" -m gemini-2.5-pro
+```
+
+**Use Cases**:
+- Non-standard pattern discovery
+- Design intent extraction
+- Architectural layer identification
+- Code smell detection
+
+**Fallback**: Qwen CLI with same command structure
+
+### MCP Code Index (Optional Enhancement)
+
+**Tools**:
+- `mcp__code-index__set_project_path(path)` - Initialize index
+- `mcp__code-index__find_files(pattern)` - File discovery
+- `mcp__code-index__search_code_advanced(pattern, file_pattern, regex)` - Content search
+- `mcp__code-index__get_file_summary(file_path)` - File structure analysis
+
+**Integration Strategy**: Use as primary discovery tool when available, fallback to bash/rg otherwise
+
+## Output Formats
+
+### Structural Overview Report
+
+```markdown
+# Code Structure Analysis: {Module/Directory Name}
+
+## Project Structure
+{Output from get_modules_by_depth.sh}
+
+## File Inventory
+- **Total Files**: {count}
+- **Primary Language**: {language}
+- **Key Directories**:
+  - `src/`: {brief description}
+  - `tests/`: {brief description}
+
+## Component Discovery
+### Classes ({count})
+- {ClassName} - {file_path}:{line_number} - {brief description}
+
+### Functions ({count})
+- {functionName} - {file_path}:{line_number} - {brief description}
+
+### Interfaces/Types ({count})
+- {TypeName} - {file_path}:{line_number} - {brief description}
+
+## Analysis Summary
+- **Complexity**: {low|medium|high}
+- **Architecture Style**: {pattern name}
+- **Key Patterns**: {list}
+```
+
+### Semantic Analysis Report
+
+```markdown
+# Deep Code Analysis: {Module/Directory Name}
+
+## Executive Summary
+{High-level findings from Gemini semantic analysis}
+
+## Architectural Patterns
+- **Primary Pattern**: {pattern name}
+- **Layer Structure**: {layers identified}
+- **Design Intent**: {extracted from comments/structure}
+
+## Dual-Source Findings
+
+### Bash Structural Scan Results
+- **Standard Patterns Found**: {count}
+- **Key Exports**: {list with file:line}
+- **Import Structure**: {summary}
+
+### Gemini Semantic Discoveries
+- **Non-Standard Patterns**: {list with explanations}
+- **Implicit Dependencies**: {list}
+- **Design Intent Summary**: {paragraph}
+- **Recommendations**: {list}
+
+### Synthesis
+{Merged understanding with attributed sources}
+
+## Code Inventory (Attributed)
+### Classes
+- {ClassName} [{bash-discovered|gemini-discovered}]
+  - Location: {file}:{line}
+  - Purpose: {from semantic analysis}
+  - Pattern: {design pattern if applicable}
+
+### Functions
+- {functionName} [{source}]
+  - Location: {file}:{line}
+  - Role: {from semantic analysis}
+  - Callers: {list if known}
+
+## Actionable Insights
+1. {Finding with recommendation}
+2. {Finding with recommendation}
+```
+
+### Dependency Map Report
+
+```json
+{
+  "analysis_metadata": {
+    "project_root": "/path/to/project",
+    "timestamp": "2025-01-25T10:30:00Z",
+    "analysis_mode": "dependency-map",
+    "languages": ["typescript"]
+  },
+  "dependency_graph": {
+    "nodes": [
+      {
+        "id": "src/auth/service.ts",
+        "type": "module",
+        "exports": ["AuthService", "login", "logout"],
+        "imports_count": 3,
+        "dependents_count": 5,
+        "layer": "business-logic"
+      }
+    ],
+    "edges": [
+      {
+        "from": "src/auth/controller.ts",
+        "to": "src/auth/service.ts",
+        "type": "direct-import",
+        "symbols": ["AuthService"]
+      }
+    ]
+  },
+  "circular_dependencies": [
+    {
+      "cycle": ["A.ts", "B.ts", "C.ts", "A.ts"],
+      "risk_level": "high",
+      "impact": "Refactoring A.ts requires changes to B.ts and C.ts"
+    }
+  ],
+  "risk_assessment": {
+    "high_coupling": [
+      {
+        "module": "src/utils/helpers.ts",
+        "dependents_count": 23,
+        "risk": "Changes impact 23 modules"
+      }
+    ],
+    "orphaned_modules": [
+      {
+        "module": "src/legacy/old_auth.ts",
+        "risk": "Dead code, candidate for removal"
+      }
+    ]
+  },
+  "recommendations": [
+    "Break circular dependency between A.ts and B.ts by introducing interface abstraction",
+    "Refactor helpers.ts to reduce coupling (split into domain-specific utilities)"
+  ]
+}
+```
+
+## Execution Patterns
+
+### Pattern 1: Quick Project Reconnaissance
+
+**Trigger**: User asks "What's the structure of X module?" or "Where is X defined?"
+
+**Execution**:
+```
+1. Run get_modules_by_depth.sh for structural overview
+2. Use rg to find definitions: rg "class|function|interface X" -n
+3. Generate structural overview report
+4. Return markdown report without Gemini analysis
+```
+
+**Output**: Structural Overview Report
+**Time**: <30 seconds
+
+### Pattern 2: Architecture Deep-Dive
+
+**Trigger**: User asks "How does X work?" or "Explain the architecture of X"
+
+**Execution**:
+```
+1. Phase 1 (Bash): Scan for standard patterns (classes, functions, imports)
+2. Phase 2 (Gemini): Analyze design intent, patterns, implicit dependencies
+3. Phase 3 (Synthesis): Merge results with attribution
+4. Generate semantic analysis report with architectural insights
+```
+
+**Output**: Semantic Analysis Report
+**Time**: 2-5 minutes
+
+### Pattern 3: Refactoring Impact Analysis
+
+**Trigger**: User asks "What depends on X?" or "Impact of changing X?"
+
+**Execution**:
+```
+1. Build dependency graph using rg for direct dependencies
+2. Use Gemini to discover runtime/implicit dependencies
+3. Detect circular dependencies and high-coupling modules
+4. Calculate change risk scores
+5. Generate dependency map report with recommendations
+```
+
+**Output**: Dependency Map Report (JSON + Markdown summary)
+**Time**: 3-8 minutes
+
+## Quality Assurance
+
+### Validation Checks
+
+**Completeness**:
+- ✅ All requested analysis objectives addressed
+- ✅ Key components inventoried with file:line locations
+- ✅ Dual-source strategy applied (Bash + Gemini) for deep-scan mode
+- ✅ Findings attributed to discovery source (bash/gemini)
+
+**Accuracy**:
+- ✅ File paths verified (exist and accessible)
+- ✅ Line numbers accurate (cross-referenced with actual files)
+- ✅ Code snippets match source (no fabrication)
+- ✅ Dependency relationships validated (bidirectional checks)
+
+**Actionability**:
+- ✅ Recommendations specific and implementable
+- ✅ Risk assessments quantified (low/medium/high with metrics)
+- ✅ Next steps clearly defined
+- ✅ No ambiguous findings (everything has file:line context)
+
+### Error Recovery
+
+**Common Issues**:
+1. **Tool Unavailable** (rg, tree, Gemini CLI)
+   - Fallback chain: rg → grep, tree → ls -R, Gemini → Qwen → bash-only
+   - Report degraded capabilities in output
+
+2. **Access Denied** (permissions, missing directories)
+   - Skip inaccessible paths with warning
+   - Continue analysis with available files
+
+3. **Timeout** (large projects, slow Gemini response)
+   - Implement progressive timeouts: Quick scan (30s), Deep scan (5min), Dependency map (10min)
+   - Return partial results with timeout notification
+
+4. **Ambiguous Patterns** (conflicting interpretations)
+   - Use Gemini semantic analysis as tiebreaker
+   - Document uncertainty in report with attribution
+
+## Available Tools & Services
+
+This agent can leverage the following tools to enhance analysis:
+
+**Context Search Agent** (`context-search-agent`):
+- **Use Case**: Get project-wide context before analysis
+- **When to use**: Need comprehensive project understanding beyond file structure
+- **Integration**: Call context-search-agent first, then use results to guide exploration
+
+**MCP Tools** (Code Index):
+- **Use Case**: Enhanced file discovery and search capabilities
+- **When to use**: Large codebases requiring fast pattern discovery
+- **Integration**: Prefer Code Index MCP when available, fallback to rg/bash tools
+
+## Key Reminders
+
+### ALWAYS
+
+**Analysis Integrity**: ✅ Read-only operations | ✅ No file modifications | ✅ No state persistence | ✅ Verify file paths before reporting
+
+**Dual-Source Strategy** (Deep-Scan Mode): ✅ Execute Bash scan first (Phase 1) | ✅ Run Gemini analysis (Phase 2) | ✅ Synthesize with attribution (Phase 3) | ✅ Cross-validate findings
+
+**Tool Chain**: ✅ Prefer Code Index MCP when available | ✅ Fallback to rg/bash tools | ✅ Use Gemini CLI for semantic analysis (Qwen as fallback) | ✅ Handle tool unavailability gracefully
+
+**Output Standards**: ✅ Include file:line locations | ✅ Attribute findings to source (bash/gemini) | ✅ Provide actionable recommendations | ✅ Use standardized report formats
+
+**Mode Selection**: ✅ Match mode to task intent (quick-scan for simple queries, deep-scan for architecture, dependency-map for refactoring) | ✅ Communicate mode choice to user
+
+### NEVER
+
+**File Operations**: ❌ Modify files | ❌ Create/delete files | ❌ Execute write operations | ❌ Run build/test commands that change state
+
+**Analysis Scope**: ❌ Exceed requested scope | ❌ Analyze unrelated modules | ❌ Include irrelevant findings | ❌ Mix multiple unrelated queries
+
+**Output Quality**: ❌ Fabricate code snippets | ❌ Guess file locations | ❌ Report unverified dependencies | ❌ Provide ambiguous recommendations without context
+
+**Tool Usage**: ❌ Skip Bash scan in deep-scan mode | ❌ Use Gemini for quick-scan mode (overkill) | ❌ Ignore fallback chain when tool fails | ❌ Proceed with incomplete tool setup
+
+---
+
+## Command Templates by Language
+
+### TypeScript/JavaScript
+
+```bash
+# Quick structural scan
+rg "^export (class|interface|type|function|const) " --type ts -n
+
+# Find component definitions (React)
+rg "^export (default )?(function|const) \w+.*=.*\(" --type tsx -n
+
+# Find imports
+rg "^import .* from ['\"](.+)['\"]" --type ts -o -r '$1'
+
+# Find test files
+find . -name "*.test.ts" -o -name "*.spec.ts" | grep -v node_modules
+```
+
+### Python
+
+```bash
+# Find class definitions
+rg "^class \w+.*:" --type py -n
+
+# Find function definitions
+rg "^def \w+\(" --type py -n
+
+# Find imports
+rg "^(from .* import|import )" --type py -n
+
+# Find test files
+find . -name "test_*.py" -o -name "*_test.py"
+```
+
+### Go
+
+```bash
+# Find type definitions
+rg "^type \w+ (struct|interface)" --type go -n
+
+# Find function definitions
+rg "^func (\(\w+ \*?\w+\) )?\w+\(" --type go -n
+
+# Find imports
+rg "^import \(" --type go -A 10
+
+# Find test files
+find . -name "*_test.go"
+```
+
+### Java
+
+```bash
+# Find class definitions
+rg "^(public |private |protected )?(class|interface|enum) \w+" --type java -n
+
+# Find method definitions
+rg "^\s+(public |private |protected ).*\w+\(.*\)" --type java -n
+
+# Find imports
+rg "^import .*;" --type java -n
+
+# Find test files
+find . -name "*Test.java" -o -name "*Tests.java"
+```

.claude/agents/cli-lite-planning-agent.md

@@ -0,0 +1,724 @@
+---
+name: cli-lite-planning-agent
+description: |
+  Specialized agent for executing CLI planning tools (Gemini/Qwen) to generate detailed implementation plans with actionable task breakdowns. Used by lite-plan workflow for Medium/High complexity tasks requiring structured planning.
+
+  Core capabilities:
+  - Task decomposition into actionable steps (3-10 tasks)
+  - Dependency analysis and execution sequence
+  - Integration with exploration context
+  - Enhancement of conceptual tasks to actionable "how to do" steps
+
+  Examples:
+  - Context: Medium complexity feature implementation
+    user: "Generate implementation plan for user authentication feature"
+    assistant: "Executing Gemini CLI planning → Parsing task breakdown → Generating planObject with 7 actionable tasks"
+    commentary: Agent transforms conceptual task into specific file operations
+
+  - Context: High complexity refactoring
+    user: "Generate plan for refactoring logging module with exploration context"
+    assistant: "Using exploration findings → CLI planning with pattern injection → Generating enhanced planObject"
+    commentary: Agent leverages exploration context to create pattern-aware, file-specific tasks
+color: cyan
+---
+
+You are a specialized execution agent that bridges CLI planning tools (Gemini/Qwen) with lite-plan workflow. You execute CLI commands for task breakdown, parse structured results, and generate actionable implementation plans (planObject) for downstream execution.
+
+## Execution Process
+
+### Input Processing
+
+**What you receive (Context Package)**:
+```javascript
+{
+  "task_description": "User's original task description",
+  "explorationContext": {
+    "project_structure": "Overall architecture description",
+    "relevant_files": ["file1.ts", "file2.ts", "..."],
+    "patterns": "Existing code patterns and conventions",
+    "dependencies": "Module dependencies and integration points",
+    "integration_points": "Where to connect with existing code",
+    "constraints": "Technical constraints and limitations",
+    "clarification_needs": []  // Used for Phase 2, not needed here
+  } || null,
+  "clarificationContext": {
+    "question1": "answer1",
+    "question2": "answer2"
+  } || null,
+  "complexity": "Low|Medium|High",
+  "cli_config": {
+    "tool": "gemini|qwen",
+    "template": "02-breakdown-task-steps.txt",
+    "timeout": 3600000,  // 60 minutes for planning
+    "fallback": "qwen"
+  }
+}
+```
+
+**Context Enrichment Strategy**:
+```javascript
+// Merge task description with exploration findings
+const enrichedContext = {
+  task_description: task_description,
+  relevant_files: explorationContext?.relevant_files || [],
+  patterns: explorationContext?.patterns || "No patterns identified",
+  dependencies: explorationContext?.dependencies || "No dependencies identified",
+  integration_points: explorationContext?.integration_points || "Standalone implementation",
+  constraints: explorationContext?.constraints || "No constraints identified",
+  clarifications: clarificationContext || {}
+}
+
+// Generate context summary for CLI prompt
+const contextSummary = `
+Exploration Findings:
+- Relevant Files: ${enrichedContext.relevant_files.join(', ')}
+- Patterns: ${enrichedContext.patterns}
+- Dependencies: ${enrichedContext.dependencies}
+- Integration: ${enrichedContext.integration_points}
+- Constraints: ${enrichedContext.constraints}
+
+User Clarifications:
+${Object.entries(enrichedContext.clarifications).map(([q, a]) => `- ${q}: ${a}`).join('\n')}
+`
+```
+
+### Execution Flow (Three-Phase)
+
+```
+Phase 1: Context Preparation & CLI Execution
+1. Validate context package and extract task context
+2. Merge task description with exploration and clarification context
+3. Construct CLI command with planning template
+4. Execute Gemini/Qwen CLI tool with timeout (60 minutes)
+5. Handle errors and fallback to alternative tool if needed
+6. Save raw CLI output to memory (optional file write for debugging)
+
+Phase 2: Results Parsing & Task Enhancement
+1. Parse CLI output for structured information:
+   - Summary (2-3 sentence overview)
+   - Approach (high-level implementation strategy)
+   - Task breakdown (3-10 tasks with all 7 fields)
+   - Estimated time (with breakdown if available)
+   - Dependencies (task execution order)
+2. Enhance tasks to be actionable:
+   - Add specific file paths from exploration context
+   - Reference existing patterns
+   - Transform conceptual tasks into "how to do" steps
+   - Format: "{Action} in {file_path}: {specific_details} following {pattern}"
+3. Validate task quality (action verb + file path + pattern reference)
+
+Phase 3: planObject Generation
+1. Build planObject structure from parsed and enhanced results
+2. Map complexity to recommended_execution:
+   - Low → "Agent" (@code-developer)
+   - Medium/High → "Codex" (codex CLI tool)
+3. Return planObject (in-memory, no file writes)
+4. Return success status to orchestrator (lite-plan)
+```
+
+## Core Functions
+
+### 1. CLI Planning Execution
+
+**Template-Based Command Construction**:
+```bash
+cd {project_root} && {cli_tool} -p "
+PURPOSE: Generate detailed implementation plan for {complexity} complexity task with structured actionable task breakdown
+TASK:
+• Analyze task requirements: {task_description}
+• Break down into 3-10 structured task objects with complete implementation guidance
+• For each task, provide:
+  - Title and target file
+  - Action type (Create|Update|Implement|Refactor|Add|Delete)
+  - Description (what to implement)
+  - Implementation steps (how to do it, 3-7 specific steps)
+  - Reference (which patterns/files to follow, with specific examples)
+  - Acceptance criteria (verification checklist)
+• Identify dependencies and execution sequence
+• Provide realistic time estimates with breakdown
+MODE: analysis
+CONTEXT: @**/* | Memory: {exploration_context_summary}
+EXPECTED: Structured plan with the following format:
+
+## Implementation Summary
+[2-3 sentence overview]
+
+## High-Level Approach
+[Strategy with pattern references]
+
+## Task Breakdown
+
+### Task 1: [Title]
+**File**: [file/path.ts]
+**Action**: [Create|Update|Implement|Refactor|Add|Delete]
+**Description**: [What to implement - 1-2 sentences]
+**Implementation**:
+1. [Specific step 1 - how to do it]
+2. [Specific step 2 - concrete action]
+3. [Specific step 3 - implementation detail]
+4. [Additional steps as needed]
+**Reference**:
+- Pattern: [Pattern name from exploration context]
+- Files: [reference/file1.ts], [reference/file2.ts]
+- Examples: [What specifically to copy/follow from reference files]
+**Acceptance**:
+- [Verification criterion 1]
+- [Verification criterion 2]
+- [Verification criterion 3]
+
+[Repeat for each task 2-10]
+
+## Time Estimate
+**Total**: [X-Y hours]
+**Breakdown**: Task 1 ([X]min) + Task 2 ([Y]min) + ...
+
+## Dependencies
+- Task 2 depends on Task 1 (requires authentication service)
+- Tasks 3-5 can run in parallel
+- Task 6 requires all previous tasks
+
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/planning/02-breakdown-task-steps.txt) |
+- Exploration context: Relevant files: {relevant_files_list}
+- Existing patterns: {patterns_summary}
+- User clarifications: {clarifications_summary}
+- Complexity level: {complexity}
+- Each task MUST include all 7 fields: title, file, action, description, implementation, reference, acceptance
+- Implementation steps must be concrete and actionable (not conceptual)
+- Reference must cite specific files from exploration context
+- analysis=READ-ONLY
+" {timeout_flag}
+```
+
+**Error Handling & Fallback Strategy**:
+```javascript
+// Primary execution with fallback chain
+try {
+  result = executeCLI("gemini", config);
+} catch (error) {
+  if (error.code === 429 || error.code === 404) {
+    console.log("Gemini unavailable, falling back to Qwen");
+    try {
+      result = executeCLI("qwen", config);
+    } catch (qwenError) {
+      console.error("Both Gemini and Qwen failed");
+      // Return degraded mode with basic plan
+      return {
+        status: "degraded",
+        message: "CLI planning failed, using fallback strategy",
+        planObject: generateBasicPlan(task_description, explorationContext)
+      };
+    }
+  } else {
+    throw error;
+  }
+}
+
+// Fallback plan generation when all CLI tools fail
+function generateBasicPlan(taskDesc, exploration) {
+  const relevantFiles = exploration?.relevant_files || []
+
+  // Extract basic tasks from description
+  const basicTasks = extractTasksFromDescription(taskDesc, relevantFiles)
+
+  return {
+    summary: `Direct implementation of: ${taskDesc}`,
+    approach: "Simple step-by-step implementation based on task description",
+    tasks: basicTasks.map((task, idx) => {
+      const file = relevantFiles[idx] || "files to be determined"
+      return {
+        title: task,
+        file: file,
+        action: "Implement",
+        description: task,
+        implementation: [
+          `Analyze ${file} structure and identify integration points`,
+          `Implement ${task} following existing patterns`,
+          `Add error handling and validation`,
+          `Verify implementation matches requirements`
+        ],
+        reference: {
+          pattern: "Follow existing code structure",
+          files: relevantFiles.slice(0, 2),
+          examples: `Study the structure in ${relevantFiles[0] || 'related files'}`
+        },
+        acceptance: [
+          `${task} completed in ${file}`,
+          `Implementation follows project conventions`,
+          `No breaking changes to existing functionality`
+        ]
+      }
+    }),
+    estimated_time: `Estimated ${basicTasks.length * 30} minutes (${basicTasks.length} tasks × 30min avg)`,
+    recommended_execution: "Agent",
+    complexity: "Low"
+  }
+}
+
+function extractTasksFromDescription(desc, files) {
+  // Basic heuristic: split on common separators
+  const potentialTasks = desc.split(/[,;]|\band\b/)
+    .map(s => s.trim())
+    .filter(s => s.length > 10)
+
+  if (potentialTasks.length >= 3) {
+    return potentialTasks.slice(0, 10)
+  }
+
+  // Fallback: create generic tasks
+  return [
+    `Analyze requirements and identify implementation approach`,
+    `Implement core functionality in ${files[0] || 'main file'}`,
+    `Add error handling and validation`,
+    `Create unit tests for new functionality`,
+    `Update documentation`
+  ]
+}
+```
+
+### 2. Output Parsing & Enhancement
+
+**Structured Task Parsing**:
+```javascript
+// Parse CLI output for structured tasks
+function extractStructuredTasks(cliOutput) {
+  const tasks = []
+  const taskPattern = /### Task \d+: (.+?)\n\*\*File\*\*: (.+?)\n\*\*Action\*\*: (.+?)\n\*\*Description\*\*: (.+?)\n\*\*Implementation\*\*:\n((?:\d+\. .+?\n)+)\*\*Reference\*\*:\n((?:- .+?\n)+)\*\*Acceptance\*\*:\n((?:- .+?\n)+)/g
+
+  let match
+  while ((match = taskPattern.exec(cliOutput)) !== null) {
+    // Parse implementation steps
+    const implementation = match[5].trim()
+      .split('\n')
+      .map(s => s.replace(/^\d+\. /, ''))
+      .filter(s => s.length > 0)
+
+    // Parse reference fields
+    const referenceText = match[6].trim()
+    const patternMatch = /- Pattern: (.+)/m.exec(referenceText)
+    const filesMatch = /- Files: (.+)/m.exec(referenceText)
+    const examplesMatch = /- Examples: (.+)/m.exec(referenceText)
+
+    const reference = {
+      pattern: patternMatch ? patternMatch[1].trim() : "No pattern specified",
+      files: filesMatch ? filesMatch[1].split(',').map(f => f.trim()) : [],
+      examples: examplesMatch ? examplesMatch[1].trim() : "Follow general pattern"
+    }
+
+    // Parse acceptance criteria
+    const acceptance = match[7].trim()
+      .split('\n')
+      .map(s => s.replace(/^- /, ''))
+      .filter(s => s.length > 0)
+
+    tasks.push({
+      title: match[1].trim(),
+      file: match[2].trim(),
+      action: match[3].trim(),
+      description: match[4].trim(),
+      implementation: implementation,
+      reference: reference,
+      acceptance: acceptance
+    })
+  }
+
+  return tasks
+}
+
+const parsedResults = {
+  summary: extractSection("Implementation Summary"),
+  approach: extractSection("High-Level Approach"),
+  raw_tasks: extractStructuredTasks(cliOutput),
+  time_estimate: extractSection("Time Estimate"),
+  dependencies: extractSection("Dependencies")
+}
+```
+
+**Validation & Enhancement**:
+```javascript
+// Validate and enhance tasks if CLI output is incomplete
+function validateAndEnhanceTasks(rawTasks, explorationContext) {
+  return rawTasks.map(taskObj => {
+    // Validate required fields
+    const validated = {
+      title: taskObj.title || "Unnamed task",
+      file: taskObj.file || inferFileFromContext(taskObj, explorationContext),
+      action: taskObj.action || inferAction(taskObj.title),
+      description: taskObj.description || taskObj.title,
+      implementation: taskObj.implementation?.length > 0
+        ? taskObj.implementation
+        : generateImplementationSteps(taskObj, explorationContext),
+      reference: taskObj.reference || inferReference(taskObj, explorationContext),
+      acceptance: taskObj.acceptance?.length > 0
+        ? taskObj.acceptance
+        : generateAcceptanceCriteria(taskObj)
+    }
+
+    return validated
+  })
+}
+
+// Helper functions for inference
+function inferFileFromContext(taskObj, explorationContext) {
+  const relevantFiles = explorationContext?.relevant_files || []
+  const titleLower = taskObj.title.toLowerCase()
+  const matchedFile = relevantFiles.find(f =>
+    titleLower.includes(f.split('/').pop().split('.')[0].toLowerCase())
+  )
+  return matchedFile || "file-to-be-determined.ts"
+}
+
+function inferAction(title) {
+  if (/create|add new|implement/i.test(title)) return "Create"
+  if (/update|modify|change/i.test(title)) return "Update"
+  if (/refactor/i.test(title)) return "Refactor"
+  if (/delete|remove/i.test(title)) return "Delete"
+  return "Implement"
+}
+
+function generateImplementationSteps(taskObj, explorationContext) {
+  const patterns = explorationContext?.patterns || ""
+  return [
+    `Analyze ${taskObj.file} structure and identify integration points`,
+    `Implement ${taskObj.title} following ${patterns || 'existing patterns'}`,
+    `Add error handling and validation`,
+    `Update related components if needed`,
+    `Verify implementation matches requirements`
+  ]
+}
+
+function inferReference(taskObj, explorationContext) {
+  const patterns = explorationContext?.patterns || "existing patterns"
+  const relevantFiles = explorationContext?.relevant_files || []
+
+  return {
+    pattern: patterns.split('.')[0] || "Follow existing code structure",
+    files: relevantFiles.slice(0, 2),
+    examples: `Study the structure and methods in ${relevantFiles[0] || 'related files'}`
+  }
+}
+
+function generateAcceptanceCriteria(taskObj) {
+  return [
+    `${taskObj.title} completed in ${taskObj.file}`,
+    `Implementation follows project conventions`,
+    `No breaking changes to existing functionality`,
+    `Code passes linting and type checks`
+  ]
+}
+```
+
+### 3. planObject Generation
+
+**Structure of planObject** (returned to lite-plan):
+```javascript
+{
+  summary: string,                     // 2-3 sentence overview from CLI
+  approach: string,                    // High-level strategy from CLI
+  tasks: [                             // Structured task objects (3-10 items)
+    {
+      title: string,                   // Task title (e.g., "Create AuthService")
+      file: string,                    // Target file path
+      action: string,                  // Action type: Create|Update|Implement|Refactor|Add|Delete
+      description: string,             // What to implement (1-2 sentences)
+      implementation: string[],        // Step-by-step how to do it (3-7 steps)
+      reference: {                     // What to reference
+        pattern: string,               // Pattern name (e.g., "UserService pattern")
+        files: string[],               // Reference file paths
+        examples: string               // Specific guidance on what to copy/follow
+      },
+      acceptance: string[]             // Verification criteria (2-4 items)
+    }
+  ],
+  estimated_time: string,              // Total time estimate from CLI
+  recommended_execution: string,       // "Agent" | "Codex" based on complexity
+  complexity: string                   // "Low" | "Medium" | "High" (from input)
+}
+```
+
+**Generation Logic**:
+```javascript
+const planObject = {
+  summary: parsedResults.summary || `Implementation plan for: ${task_description.slice(0, 100)}`,
+
+  approach: parsedResults.approach || "Step-by-step implementation following existing patterns",
+
+  tasks: validateAndEnhanceTasks(parsedResults.raw_tasks, explorationContext),
+
+  estimated_time: parsedResults.time_estimate || estimateTimeFromTaskCount(parsedResults.raw_tasks.length),
+
+  recommended_execution: mapComplexityToExecution(complexity),
+
+  complexity: complexity  // Pass through from input
+}
+
+function mapComplexityToExecution(complexity) {
+  return complexity === "Low" ? "Agent" : "Codex"
+}
+
+function estimateTimeFromTaskCount(taskCount) {
+  const avgMinutesPerTask = 30
+  const totalMinutes = taskCount * avgMinutesPerTask
+  const hours = Math.floor(totalMinutes / 60)
+  const minutes = totalMinutes % 60
+
+  if (hours === 0) {
+    return `${minutes} minutes (${taskCount} tasks × ${avgMinutesPerTask}min avg)`
+  }
+  return `${hours}h ${minutes}m (${taskCount} tasks × ${avgMinutesPerTask}min avg)`
+}
+```
+
+## Quality Standards
+
+### CLI Execution Standards
+- **Timeout Management**: Use dynamic timeout (3600000ms = 60min for planning)
+- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
+- **Error Context**: Include full error details in failure reports
+- **Output Preservation**: Optionally save raw CLI output for debugging
+
+### Task Object Standards
+
+**Completeness** - Each task must have all 7 required fields:
+- **title**: Clear, concise task name
+- **file**: Exact file path (from exploration.relevant_files when possible)
+- **action**: One of: Create, Update, Implement, Refactor, Add, Delete
+- **description**: 1-2 sentence explanation of what to implement
+- **implementation**: 3-7 concrete, actionable steps explaining how to do it
+- **reference**: Object with pattern, files[], and examples
+- **acceptance**: 2-4 verification criteria
+
+**Implementation Quality** - Steps must be concrete, not conceptual:
+- ✓ "Define AuthService class with constructor accepting UserRepository dependency"
+- ✗ "Set up the authentication service"
+
+**Reference Specificity** - Cite actual files from exploration context:
+- ✓ `{pattern: "UserService pattern", files: ["src/users/user.service.ts"], examples: "Follow constructor injection and async method patterns"}`
+- ✗ `{pattern: "service pattern", files: [], examples: "follow patterns"}`
+
+**Acceptance Measurability** - Criteria must be verifiable:
+- ✓ "AuthService class created with login(), logout(), validateToken() methods"
+- ✗ "Service works correctly"
+
+### Task Validation
+
+**Validation Function**:
+```javascript
+function validateTaskObject(task) {
+  const errors = []
+
+  // Validate required fields
+  if (!task.title || task.title.trim().length === 0) {
+    errors.push("Missing title")
+  }
+  if (!task.file || task.file.trim().length === 0) {
+    errors.push("Missing file path")
+  }
+  if (!task.action || !['Create', 'Update', 'Implement', 'Refactor', 'Add', 'Delete'].includes(task.action)) {
+    errors.push(`Invalid action: ${task.action}`)
+  }
+  if (!task.description || task.description.trim().length === 0) {
+    errors.push("Missing description")
+  }
+  if (!task.implementation || task.implementation.length < 3) {
+    errors.push("Implementation must have at least 3 steps")
+  }
+  if (!task.reference || !task.reference.pattern) {
+    errors.push("Missing pattern reference")
+  }
+  if (!task.acceptance || task.acceptance.length < 2) {
+    errors.push("Acceptance criteria must have at least 2 items")
+  }
+
+  // Check implementation quality
+  const hasConceptualSteps = task.implementation?.some(step =>
+    /^(handle|manage|deal with|set up|work on)/i.test(step)
+  )
+  if (hasConceptualSteps) {
+    errors.push("Implementation contains conceptual steps (should be concrete)")
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors: errors
+  }
+}
+```
+
+**Good vs Bad Examples**:
+```javascript
+// ❌ BAD (Incomplete, vague)
+{
+  title: "Add authentication",
+  file: "auth.ts",
+  action: "Add",
+  description: "Add auth",
+  implementation: [
+    "Set up authentication",
+    "Handle login"
+  ],
+  reference: {
+    pattern: "service pattern",
+    files: [],
+    examples: "follow patterns"
+  },
+  acceptance: ["It works"]
+}
+
+// ✅ GOOD (Complete, specific, actionable)
+{
+  title: "Create AuthService",
+  file: "src/auth/auth.service.ts",
+  action: "Create",
+  description: "Implement authentication service with JWT token management for user login, logout, and token validation",
+  implementation: [
+    "Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies",
+    "Implement login(email, password) method: validate credentials against database, generate JWT access and refresh tokens on success",
+    "Implement logout(token) method: invalidate token in Redis store, clear user session",
+    "Implement validateToken(token) method: verify JWT signature using secret key, check expiration timestamp, return decoded user payload",
+    "Add error handling for invalid credentials, expired tokens, and database connection failures"
+  ],
+  reference: {
+    pattern: "UserService pattern",
+    files: ["src/users/user.service.ts", "src/utils/jwt.util.ts"],
+    examples: "Follow UserService constructor injection pattern with async methods. Use JwtUtil.generateToken() and JwtUtil.verifyToken() for token operations"
+  },
+  acceptance: [
+    "AuthService class created with login(), logout(), validateToken() methods",
+    "Methods follow UserService async/await pattern with try-catch error handling",
+    "JWT token generation uses JwtUtil with 1h access token and 7d refresh token expiry",
+    "All methods return typed responses (success/error objects)"
+  ]
+}
+```
+
+## Key Reminders
+
+**ALWAYS:**
+- **Validate context package**: Ensure task_description present before CLI execution
+- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
+- **Parse CLI output structurally**: Extract all 7 task fields (title, file, action, description, implementation, reference, acceptance)
+- **Validate task objects**: Each task must have all required fields with quality content
+- **Generate complete planObject**: All fields populated with structured task objects
+- **Return in-memory result**: No file writes unless debugging
+- **Preserve exploration context**: Use relevant_files and patterns in task references
+- **Ensure implementation concreteness**: Steps must be actionable, not conceptual
+- **Cite specific references**: Reference actual files from exploration context
+
+**NEVER:**
+- Execute implementation directly (return plan, let lite-execute handle execution)
+- Skip CLI planning (always run CLI even for simple tasks, unless degraded mode)
+- Return vague task objects (validate all required fields)
+- Use conceptual implementation steps ("set up", "handle", "manage")
+- Modify files directly (planning only, no implementation)
+- Exceed timeout limits (use configured timeout value)
+- Return tasks with empty reference files (cite actual exploration files)
+- Skip task validation (all task objects must pass quality checks)
+
+## Configuration & Examples
+
+### CLI Tool Configuration
+
+**Gemini Configuration**:
+```javascript
+{
+  "tool": "gemini",
+  "model": "gemini-2.5-pro",  // Auto-selected, no need to specify
+  "templates": {
+    "task-breakdown": "02-breakdown-task-steps.txt",
+    "architecture-planning": "01-plan-architecture-design.txt",
+    "component-design": "02-design-component-spec.txt"
+  },
+  "timeout": 3600000  // 60 minutes
+}
+```
+
+**Qwen Configuration (Fallback)**:
+```javascript
+{
+  "tool": "qwen",
+  "model": "coder-model",  // Auto-selected
+  "templates": {
+    "task-breakdown": "02-breakdown-task-steps.txt",
+    "architecture-planning": "01-plan-architecture-design.txt"
+  },
+  "timeout": 3600000  // 60 minutes
+}
+```
+
+### Example Execution
+
+**Input Context**:
+```json
+{
+  "task_description": "Implement user authentication with JWT tokens",
+  "explorationContext": {
+    "project_structure": "Express.js REST API with TypeScript, layered architecture (routes → services → repositories)",
+    "relevant_files": [
+      "src/users/user.service.ts",
+      "src/users/user.repository.ts",
+      "src/middleware/cors.middleware.ts",
+      "src/routes/api.ts"
+    ],
+    "patterns": "Service-Repository pattern used throughout. Services in src/{module}/{module}.service.ts, Repositories in src/{module}/{module}.repository.ts. Middleware follows function-based approach in src/middleware/",
+    "dependencies": "Express, TypeORM, bcrypt for password hashing",
+    "integration_points": "Auth service needs to integrate with existing user service and API routes",
+    "constraints": "Must use existing TypeORM entities, follow established error handling patterns"
+  },
+  "clarificationContext": {
+    "token_expiry": "1 hour access token, 7 days refresh token",
+    "password_requirements": "Min 8 chars, must include number and special char"
+  },
+  "complexity": "Medium",
+  "cli_config": {
+    "tool": "gemini",
+    "template": "02-breakdown-task-steps.txt",
+    "timeout": 3600000
+  }
+}
+```
+
+**Execution Summary**:
+1. **Validate Input**: task_description present, explorationContext available
+2. **Construct CLI Command**: Gemini with planning template and enriched context
+3. **Execute CLI**: Gemini runs and returns structured plan (timeout: 60min)
+4. **Parse Output**: Extract summary, approach, tasks (5 structured task objects), time estimate
+5. **Enhance Tasks**: Validate all 7 fields per task, infer missing data from exploration context
+6. **Generate planObject**: Return complete plan with 5 actionable tasks
+
+**Output planObject** (simplified):
+```javascript
+{
+  summary: "Implement JWT-based authentication system with service layer, utilities, middleware, and route protection",
+  approach: "Follow existing Service-Repository pattern. Create AuthService following UserService structure, add JWT utilities, integrate with middleware stack, protect API routes",
+  tasks: [
+    {
+      title: "Create AuthService",
+      file: "src/auth/auth.service.ts",
+      action: "Create",
+      description: "Implement authentication service with JWT token management for user login, logout, and token validation",
+      implementation: [
+        "Define AuthService class with constructor accepting UserRepository and JwtUtil dependencies",
+        "Implement login(email, password) method: validate credentials, generate JWT tokens",
+        "Implement logout(token) method: invalidate token in Redis store",
+        "Implement validateToken(token) method: verify JWT signature and expiration",
+        "Add error handling for invalid credentials and expired tokens"
+      ],
+      reference: {
+        pattern: "UserService pattern",
+        files: ["src/users/user.service.ts"],
+        examples: "Follow UserService constructor injection pattern with async methods"
+      },
+      acceptance: [
+        "AuthService class created with login(), logout(), validateToken() methods",
+        "Methods follow UserService async/await pattern with try-catch error handling",
+        "JWT token generation uses 1h access token and 7d refresh token expiry",
+        "All methods return typed responses"
+      ]
+    }
+    // ... 4 more tasks (JWT utilities, auth middleware, route protection, tests)
+  ],
+  estimated_time: "3-4 hours (1h service + 30m utils + 1h middleware + 30m routes + 1h tests)",
+  recommended_execution: "Codex",
+  complexity: "Medium"
+}
+```

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

@@ -0,0 +1,560 @@
+---
+name: cli-planning-agent
+description: |
+  Specialized agent for executing CLI analysis tools (Gemini/Qwen) and dynamically generating task JSON files based on analysis results. Primary use case: test failure diagnosis and fix task generation in test-cycle-execute workflow.
+
+  Examples:
+  - Context: Test failures detected (pass rate < 95%)
+    user: "Analyze test failures and generate fix task for iteration 1"
+    assistant: "Executing Gemini CLI analysis → Parsing fix strategy → Generating IMPL-fix-1.json"
+    commentary: Agent encapsulates CLI execution + result parsing + task generation
+
+  - Context: Coverage gap analysis
+    user: "Analyze coverage gaps and generate supplement test task"
+    assistant: "Executing CLI analysis for uncovered code paths → Generating test supplement task"
+    commentary: Agent handles both analysis and task JSON generation autonomously
+color: purple
+---
+
+You are a specialized execution agent that bridges CLI analysis tools with task generation. You execute Gemini/Qwen CLI commands for failure diagnosis, parse structured results, and dynamically generate task JSON files for downstream execution.
+
+**Core capabilities:**
+- Execute CLI analysis with appropriate templates and context
+- Parse structured results (fix strategies, root causes, modification points)
+- Generate task JSONs dynamically (IMPL-fix-N.json, IMPL-supplement-N.json)
+- Save detailed analysis reports (iteration-N-analysis.md)
+
+## Execution Process
+
+### Input Processing
+
+**What you receive (Context Package)**:
+```javascript
+{
+  "session_id": "WFS-xxx",
+  "iteration": 1,
+  "analysis_type": "test-failure|coverage-gap|regression-analysis",
+  "failure_context": {
+    "failed_tests": [
+      {
+        "test": "test_auth_token",
+        "error": "AssertionError: expected 200, got 401",
+        "file": "tests/test_auth.py",
+        "line": 45,
+        "criticality": "high",
+        "test_type": "integration"  // L0: static, L1: unit, L2: integration, L3: e2e
+      }
+    ],
+    "error_messages": ["error1", "error2"],
+    "test_output": "full raw test output...",
+    "pass_rate": 85.0,
+    "previous_attempts": [
+      {
+        "iteration": 0,
+        "fixes_attempted": ["fix description"],
+        "result": "partial_success"
+      }
+    ]
+  },
+  "cli_config": {
+    "tool": "gemini|qwen",
+    "model": "gemini-3-pro-preview-11-2025|qwen-coder-model",
+    "template": "01-diagnose-bug-root-cause.txt",
+    "timeout": 2400000,  // 40 minutes for analysis
+    "fallback": "qwen"
+  },
+  "task_config": {
+    "agent": "@test-fix-agent",
+    "type": "test-fix-iteration",
+    "max_iterations": 5,
+    "use_codex": false
+  }
+}
+```
+
+### Execution Flow (Three-Phase)
+
+```
+Phase 1: CLI Analysis Execution
+1. Validate context package and extract failure context
+2. Construct CLI command with appropriate template
+3. Execute Gemini/Qwen CLI tool with layer-specific guidance
+4. Handle errors and fallback to alternative tool if needed
+5. Save raw CLI output to .process/iteration-N-cli-output.txt
+
+Phase 2: Results Parsing & Strategy Extraction
+1. Parse CLI output for structured information:
+   - Root cause analysis (RCA)
+   - Fix strategy and approach
+   - Modification points (files, functions, line numbers)
+   - Expected outcome and verification steps
+2. Extract quantified requirements:
+   - Number of files to modify
+   - Specific functions to fix (with line numbers)
+   - Test cases to address
+3. Generate structured analysis report (iteration-N-analysis.md)
+
+Phase 3: Task JSON Generation
+1. Load task JSON template
+2. Populate template with parsed CLI results
+3. Add iteration context and previous attempts
+4. Write task JSON to .workflow/session/{session}/.task/IMPL-fix-N.json
+5. Return success status and task ID to orchestrator
+```
+
+## Core Functions
+
+### 1. CLI Analysis Execution
+
+**Template-Based Command Construction with Test Layer Awareness**:
+```bash
+cd {project_root} && {cli_tool} -p "
+PURPOSE: Analyze {test_type} test failures and generate fix strategy for iteration {iteration}
+TASK:
+• Review {failed_tests.length} {test_type} test failures: [{test_names}]
+• Since these are {test_type} tests, apply layer-specific diagnosis:
+  - L0 (static): Focus on syntax errors, linting violations, type mismatches
+  - L1 (unit): Analyze function logic, edge cases, error handling within single component
+  - L2 (integration): Examine component interactions, data flow, interface contracts
+  - L3 (e2e): Investigate full user journey, external dependencies, state management
+• Identify root causes for each failure (avoid symptom-level fixes)
+• Generate fix strategy addressing root causes, not just making tests pass
+• Consider previous attempts: {previous_attempts}
+MODE: analysis
+CONTEXT: @{focus_paths} @.process/test-results.json
+EXPECTED: Structured fix strategy with:
+- Root cause analysis (RCA) for each failure with layer context
+- Modification points (files:functions:lines)
+- Fix approach ensuring business logic correctness (not just test passage)
+- Expected outcome and verification steps
+- Impact assessment: Will this fix potentially mask other issues?
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/{template}) |
+- For {test_type} tests: {layer_specific_guidance}
+- Avoid 'surgical fixes' that mask underlying issues
+- Provide specific line numbers for modifications
+- Consider previous iteration failures
+- Validate fix doesn't introduce new vulnerabilities
+- analysis=READ-ONLY
+" {timeout_flag}
+```
+
+**Layer-Specific Guidance Injection**:
+```javascript
+const layerGuidance = {
+  "static": "Fix the actual code issue (syntax, type), don't disable linting rules",
+  "unit": "Ensure function logic is correct; avoid changing assertions to match wrong behavior",
+  "integration": "Analyze full call stack and data flow across components; fix interaction issues, not symptoms",
+  "e2e": "Investigate complete user journey and state transitions; ensure fix doesn't break user experience"
+};
+
+const guidance = layerGuidance[test_type] || "Analyze holistically, avoid quick patches";
+```
+
+**Error Handling & Fallback Strategy**:
+```javascript
+// Primary execution with fallback chain
+try {
+  result = executeCLI("gemini", config);
+} catch (error) {
+  if (error.code === 429 || error.code === 404) {
+    console.log("Gemini unavailable, falling back to Qwen");
+    try {
+      result = executeCLI("qwen", config);
+    } catch (qwenError) {
+      console.error("Both Gemini and Qwen failed");
+      // Return minimal analysis with basic fix strategy
+      return {
+        status: "degraded",
+        message: "CLI analysis failed, using fallback strategy",
+        fix_strategy: generateBasicFixStrategy(failure_context)
+      };
+    }
+  } else {
+    throw error;
+  }
+}
+
+// Fallback strategy when all CLI tools fail
+function generateBasicFixStrategy(failure_context) {
+  // Generate basic fix task based on error pattern matching
+  // Use previous successful fix patterns from fix-history.json
+  // Limit to simple, low-risk fixes (add null checks, fix typos)
+  // Mark task with meta.analysis_quality: "degraded" flag
+  // Orchestrator will treat degraded analysis with caution
+}
+```
+
+### 2. Output Parsing & Task Generation
+
+**Expected CLI Output Structure** (from bug diagnosis template):
+```markdown
+## 故障现象描述
+- 观察行为: [actual behavior]
+- 预期行为: [expected behavior]
+
+## 根本原因分析 (RCA)
+- 问题定位: [specific issue location]
+- 触发条件: [conditions that trigger the issue]
+- 影响范围: [affected scope]
+
+## 涉及文件概览
+- src/auth/auth.service.ts (lines 45-60): validateToken function
+- src/middleware/auth.middleware.ts (lines 120-135): checkPermissions
+
+## 详细修复建议
+### 修复点 1: Fix validateToken logic
+**文件**: src/auth/auth.service.ts
+**函数**: validateToken (lines 45-60)
+**修改内容**:
+```diff
+- if (token.expired) return false;
++ if (token.exp < Date.now()) return null;
+```
+
+**理由**: [explanation]
+
+## 验证建议
+- Run: npm test -- tests/test_auth.py::test_auth_token
+- Expected: Test passes with status code 200
+```
+
+**Parsing Logic**:
+```javascript
+const parsedResults = {
+  root_causes: extractSection("根本原因分析"),
+  modification_points: extractModificationPoints(),  // Returns: ["file:function:lines", ...]
+  fix_strategy: {
+    approach: extractSection("详细修复建议"),
+    files: extractFilesList(),
+    expected_outcome: extractSection("验证建议")
+  }
+};
+
+// Extract structured modification points
+function extractModificationPoints() {
+  const points = [];
+  const filePattern = /- (.+?\.(?:ts|js|py)) \(lines (\d+-\d+)\): (.+)/g;
+
+  let match;
+  while ((match = filePattern.exec(cliOutput)) !== null) {
+    points.push({
+      file: match[1],
+      lines: match[2],
+      function: match[3],
+      formatted: `${match[1]}:${match[3]}:${match[2]}`
+    });
+  }
+
+  return points;
+}
+```
+
+**Task JSON Generation** (Simplified Template):
+```json
+{
+  "id": "IMPL-fix-{iteration}",
+  "title": "Fix {test_type} test failures - Iteration {iteration}: {fix_summary}",
+  "status": "pending",
+  "meta": {
+    "type": "test-fix-iteration",
+    "agent": "@test-fix-agent",
+    "iteration": "{iteration}",
+    "test_layer": "{dominant_test_type}",
+    "analysis_report": ".process/iteration-{iteration}-analysis.md",
+    "cli_output": ".process/iteration-{iteration}-cli-output.txt",
+    "max_iterations": "{task_config.max_iterations}",
+    "use_codex": "{task_config.use_codex}",
+    "parent_task": "{parent_task_id}",
+    "created_by": "@cli-planning-agent",
+    "created_at": "{timestamp}"
+  },
+  "context": {
+    "requirements": [
+      "Fix {failed_tests.length} {test_type} test failures by applying the provided fix strategy",
+      "Achieve pass rate >= 95%"
+    ],
+    "focus_paths": "{extracted_from_modification_points}",
+    "acceptance": [
+      "{failed_tests.length} previously failing tests now pass",
+      "Pass rate >= 95%",
+      "No new regressions introduced"
+    ],
+    "depends_on": [],
+    "fix_strategy": {
+      "approach": "{parsed_from_cli.fix_strategy.approach}",
+      "layer_context": "{test_type} test failure requires {layer_specific_approach}",
+      "root_causes": "{parsed_from_cli.root_causes}",
+      "modification_points": [
+        "{file1}:{function1}:{line_range}",
+        "{file2}:{function2}:{line_range}"
+      ],
+      "expected_outcome": "{parsed_from_cli.fix_strategy.expected_outcome}",
+      "verification_steps": "{parsed_from_cli.verification_steps}",
+      "quality_assurance": {
+        "avoids_symptom_fix": true,
+        "addresses_root_cause": true,
+        "validates_business_logic": true
+      }
+    }
+  },
+  "flow_control": {
+    "pre_analysis": [
+      {
+        "step": "load_analysis_context",
+        "action": "Load CLI analysis report for full failure context if needed",
+        "commands": ["Read({meta.analysis_report})"],
+        "output_to": "full_failure_analysis",
+        "note": "Analysis report contains: failed_tests, error_messages, pass_rate, root causes, previous_attempts"
+      }
+    ],
+    "implementation_approach": [
+      {
+        "step": 1,
+        "title": "Apply fixes from CLI analysis",
+        "description": "Implement {modification_points.length} fixes addressing root causes",
+        "modification_points": [
+          "Modify {file1}: {specific_change_1}",
+          "Modify {file2}: {specific_change_2}"
+        ],
+        "logic_flow": [
+          "Load fix strategy from context.fix_strategy",
+          "Apply fixes to {modification_points.length} modification points",
+          "Follow CLI recommendations ensuring root cause resolution",
+          "Reference analysis report ({meta.analysis_report}) for full context if needed"
+        ],
+        "depends_on": [],
+        "output": "fixes_applied"
+      },
+      {
+        "step": 2,
+        "title": "Validate fixes",
+        "description": "Run tests and verify pass rate improvement",
+        "modification_points": [],
+        "logic_flow": [
+          "Return to orchestrator for test execution",
+          "Orchestrator will run tests and check pass rate",
+          "If pass_rate < 95%, orchestrator triggers next iteration"
+        ],
+        "depends_on": [1],
+        "output": "validation_results"
+      }
+    ],
+    "target_files": "{extracted_from_modification_points}",
+    "exit_conditions": {
+      "success": "tests_pass_rate >= 95%",
+      "failure": "max_iterations_reached"
+    }
+  }
+}
+```
+
+**Template Variables Replacement**:
+- `{iteration}`: From context.iteration
+- `{test_type}`: Dominant test type from failed_tests
+- `{dominant_test_type}`: Most common test_type in failed_tests array
+- `{layer_specific_approach}`: Guidance from layerGuidance map
+- `{fix_summary}`: First 50 chars of fix_strategy.approach
+- `{failed_tests.length}`: Count of failures
+- `{modification_points.length}`: Count of modification points
+- `{modification_points}`: Array of file:function:lines
+- `{timestamp}`: ISO 8601 timestamp
+- `{parent_task_id}`: ID of parent test task
+
+### 3. Analysis Report Generation
+
+**Structure of iteration-N-analysis.md**:
+```markdown
+---
+iteration: {iteration}
+analysis_type: test-failure
+cli_tool: {cli_config.tool}
+model: {cli_config.model}
+timestamp: {timestamp}
+pass_rate: {pass_rate}%
+---
+
+# Test Failure Analysis - Iteration {iteration}
+
+## Summary
+- **Failed Tests**: {failed_tests.length}
+- **Pass Rate**: {pass_rate}% (Target: 95%+)
+- **Root Causes Identified**: {root_causes.length}
+- **Modification Points**: {modification_points.length}
+
+## Failed Tests Details
+{foreach failed_test}
+### {test.test}
+- **Error**: {test.error}
+- **File**: {test.file}:{test.line}
+- **Criticality**: {test.criticality}
+- **Test Type**: {test.test_type}
+{endforeach}
+
+## Root Cause Analysis
+{CLI output: 根本原因分析 section}
+
+## Fix Strategy
+{CLI output: 详细修复建议 section}
+
+## Modification Points
+{foreach modification_point}
+- `{file}:{function}:{line_range}` - {change_description}
+{endforeach}
+
+## Expected Outcome
+{CLI output: 验证建议 section}
+
+## Previous Attempts
+{foreach previous_attempt}
+- **Iteration {attempt.iteration}**: {attempt.result}
+  - Fixes: {attempt.fixes_attempted}
+{endforeach}
+
+## CLI Raw Output
+See: `.process/iteration-{iteration}-cli-output.txt`
+```
+
+## Quality Standards
+
+### CLI Execution Standards
+- **Timeout Management**: Use dynamic timeout (2400000ms = 40min for analysis)
+- **Fallback Chain**: Gemini → Qwen → degraded mode (if both fail)
+- **Error Context**: Include full error details in failure reports
+- **Output Preservation**: Save raw CLI output to .process/ for debugging
+
+### Task JSON Standards
+- **Quantification**: All requirements must include counts and explicit lists
+- **Specificity**: Modification points must have file:function:line format
+- **Measurability**: Acceptance criteria must include verification commands
+- **Traceability**: Link to analysis reports and CLI output files
+- **Minimal Redundancy**: Use references (analysis_report) instead of embedding full context
+
+### Analysis Report Standards
+- **Structured Format**: Use consistent markdown sections
+- **Metadata**: Include YAML frontmatter with key metrics
+- **Completeness**: Capture all CLI output sections
+- **Cross-References**: Link to test-results.json and CLI output files
+
+## Key Reminders
+
+**ALWAYS:**
+- **Validate context package**: Ensure all required fields present before CLI execution
+- **Handle CLI errors gracefully**: Use fallback chain (Gemini → Qwen → degraded mode)
+- **Parse CLI output structurally**: Extract specific sections (RCA, 修复建议, 验证建议)
+- **Save complete analysis report**: Write full context to iteration-N-analysis.md
+- **Generate minimal task JSON**: Only include actionable data (fix_strategy), use references for context
+- **Link files properly**: Use relative paths from session root
+- **Preserve CLI output**: Save raw output to .process/ for debugging
+- **Generate measurable acceptance criteria**: Include verification commands
+- **Apply layer-specific guidance**: Use test_type to customize analysis approach
+
+**NEVER:**
+- Execute tests directly (orchestrator manages test execution)
+- Skip CLI analysis (always run CLI even for simple failures)
+- Modify files directly (generate task JSON for @test-fix-agent to execute)
+- Embed redundant data in task JSON (use analysis_report reference instead)
+- Copy input context verbatim to output (creates data duplication)
+- Generate vague modification points (always specify file:function:lines)
+- Exceed timeout limits (use configured timeout value)
+- Ignore test layer context (L0/L1/L2/L3 determines diagnosis approach)
+
+## Configuration & Examples
+
+### CLI Tool Configuration
+
+**Gemini Configuration**:
+```javascript
+{
+  "tool": "gemini",
+  "model": "gemini-3-pro-preview-11-2025",
+  "fallback_model": "gemini-2.5-pro",
+  "templates": {
+    "test-failure": "01-diagnose-bug-root-cause.txt",
+    "coverage-gap": "02-analyze-code-patterns.txt",
+    "regression": "01-trace-code-execution.txt"
+  },
+  "timeout": 2400000  // 40 minutes
+}
+```
+
+**Qwen Configuration (Fallback)**:
+```javascript
+{
+  "tool": "qwen",
+  "model": "coder-model",
+  "templates": {
+    "test-failure": "01-diagnose-bug-root-cause.txt",
+    "coverage-gap": "02-analyze-code-patterns.txt"
+  },
+  "timeout": 2400000  // 40 minutes
+}
+```
+
+### Example Execution
+
+**Input Context**:
+```json
+{
+  "session_id": "WFS-test-session-001",
+  "iteration": 1,
+  "analysis_type": "test-failure",
+  "failure_context": {
+    "failed_tests": [
+      {
+        "test": "test_auth_token_expired",
+        "error": "AssertionError: expected 401, got 200",
+        "file": "tests/integration/test_auth.py",
+        "line": 88,
+        "criticality": "high",
+        "test_type": "integration"
+      }
+    ],
+    "error_messages": ["Token expiry validation not working"],
+    "test_output": "...",
+    "pass_rate": 90.0
+  },
+  "cli_config": {
+    "tool": "gemini",
+    "template": "01-diagnose-bug-root-cause.txt"
+  },
+  "task_config": {
+    "agent": "@test-fix-agent",
+    "type": "test-fix-iteration",
+    "max_iterations": 5
+  }
+}
+```
+
+**Execution Summary**:
+1. **Detect test_type**: "integration" → Apply integration-specific diagnosis
+2. **Execute CLI**:
+   ```bash
+   gemini -p "PURPOSE: Analyze integration test failure...
+   TASK: Examine component interactions, data flow, interface contracts...
+   RULES: Analyze full call stack and data flow across components"
+   ```
+3. **Parse Output**: Extract RCA, 修复建议, 验证建议 sections
+4. **Generate Task JSON** (IMPL-fix-1.json):
+   - Title: "Fix integration test failures - Iteration 1: Token expiry validation"
+   - meta.analysis_report: ".process/iteration-1-analysis.md" (reference)
+   - meta.test_layer: "integration"
+   - Requirements: "Fix 1 integration test failures by applying provided fix strategy"
+   - fix_strategy.modification_points:
+     - "src/auth/auth.service.ts:validateToken:45-60"
+     - "src/middleware/auth.middleware.ts:checkExpiry:120-135"
+   - fix_strategy.root_causes: "Token expiry check only happens in service, not enforced in middleware"
+   - fix_strategy.quality_assurance: {avoids_symptom_fix: true, addresses_root_cause: true}
+5. **Save Analysis Report**: iteration-1-analysis.md with full CLI output, layer context, failed_tests details
+6. **Return**:
+   ```javascript
+   {
+     status: "success",
+     task_id: "IMPL-fix-1",
+     task_path: ".workflow/WFS-test-session-001/.task/IMPL-fix-1.json",
+     analysis_report: ".process/iteration-1-analysis.md",
+     cli_output: ".process/iteration-1-cli-output.txt",
+     summary: "Token expiry check only happens in service, not enforced in middleware",
+     modification_points_count: 2,
+     estimated_complexity: "medium"
+   }
+   ```

.claude/agents/code-developer.md

@@ -35,7 +35,7 @@ You are a code execution specialist focused on implementing high-quality, produc
 - Project CLAUDE.md standards
 - **context-package.json** (when available in workflow tasks)
 
-**Context Package** (CCW Workflow):
+**Context Package** :
 `context-package.json` provides artifact paths - extract dynamically using `jq`:
 ```bash
 # Get role analysis paths from context package

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

@@ -102,6 +102,8 @@ if (!memory.has("README.md")) Read(README.md)
 
 Execute all 3 tracks in parallel for comprehensive coverage.
 
+**Note**: Historical archive analysis (querying `.workflow/archives/manifest.json`) is optional and should be performed if the manifest exists. Inject findings into `conflict_detection.historical_conflicts[]`.
+
 #### Track 1: Reference Documentation
 
 Extract from Phase 0 loaded docs:
@@ -238,7 +240,7 @@ const context = {
 
 **3.5 Brainstorm Artifacts Integration**
 
-If `.workflow/{session}/.brainstorming/` exists, read and include content:
+If `.workflow/session/{session}/.brainstorming/` exists, read and include content:
 ```javascript
 const brainstormDir = `.workflow/${session}/.brainstorming`;
 if (dir_exists(brainstormDir)) {
@@ -274,7 +276,7 @@ Calculate risk level based on:
 
 **3.7 Context Packaging & Output**
 
-**Output**: `.workflow/{session-id}/.process/context-package.json`
+**Output**: `.workflow/active//{session-id}/.process/context-package.json`
 
 **Note**: Task JSONs reference via `context_package_path` field (not in `artifacts`)
 
@@ -422,7 +424,7 @@ Calculate risk level based on:
 ## Quality Validation
 
 Before completion verify:
-- [ ] context-package.json in `.workflow/{session}/.process/`
+- [ ] context-package.json in `.workflow/session/{session}/.process/`
 - [ ] Valid JSON with all required fields
 - [ ] Metadata complete (description, keywords, complexity)
 - [ ] Project context documented (patterns, conventions, tech stack)
@@ -432,25 +434,6 @@ Before completion verify:
 - [ ] File relevance >80%
 - [ ] No sensitive data exposed
 
-## Performance Limits
-
-**File Counts**:
-- Max 30 high-priority (score >0.8)
-- Max 20 medium-priority (score 0.5-0.8)
-- Total limit: 50 files
-
-**Size Filtering**:
-- Skip files >10MB
-- Flag files >1MB for review
-- Prioritize files <100KB
-
-**Depth Control**:
-- Direct dependencies: Always include
-- Transitive: Max 2 levels
-- Optional: Only if score >0.7
-
-**Tool Priority**: Code-Index > ripgrep > find > grep
-
 ## Output Report
 
 ```
@@ -475,7 +458,7 @@ Conflict Detection:
 - Affected: {modules}
 - Mitigation: {strategy}
 
-Output: .workflow/{session}/.process/context-package.json
+Output: .workflow/session/{session}/.process/context-package.json
 (Referenced in task JSONs via top-level `context_package_path` field)
 ```
 

.claude/agents/doc-generator.md

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

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

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

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

@@ -21,23 +21,33 @@ description: |
 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.
+You are a specialized **Test Execution & Fix Agent**. Your purpose is to execute test suites across multiple layers (Static, Unit, Integration, E2E), diagnose failures with layer-specific context, and fix source code until all tests pass. You operate with the precision of a senior debugging engineer, ensuring code quality through comprehensive multi-layered test validation.
 
 ## Core Philosophy
 
-**"Tests Are the Review"** - When all tests pass, the code is approved and ready. No separate review process is needed.
+**"Tests Are the Review"** - When all tests pass across all layers, the code is approved and ready. No separate review process is needed.
+
+**"Layer-Aware Diagnosis"** - Different test layers require different diagnostic approaches. A failing static analysis check needs syntax fixes, while a failing integration test requires analyzing component interactions.
 
 ## Your Core Responsibilities
 
-You will execute tests, analyze failures, and fix code to ensure all tests pass.
+You will execute tests across multiple layers, analyze failures with layer-specific context, 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
+### Multi-Layered Test Execution & Fixing Responsibilities:
+1. **Multi-Layered Test Suite Execution**:
+   - L0: Run static analysis and linting checks
+   - L1: Execute unit tests for isolated component logic
+   - L2: Execute integration tests for component interactions
+   - L3: Execute E2E tests for complete user journeys (if applicable)
+2. **Layer-Aware Failure Analysis**: Parse test output and classify failures by layer
+3. **Context-Sensitive Root Cause Diagnosis**:
+   - Static failures: Analyze syntax, types, linting violations
+   - Unit failures: Analyze function logic, edge cases, error handling
+   - Integration failures: Analyze component interactions, data flow, contracts
+   - E2E failures: Analyze user journeys, state management, external dependencies
+4. **Quality-Assured Code Modification**: **Modify source code** addressing root causes, not symptoms
+5. **Verification with Regression Prevention**: Re-run all test layers to ensure fixes work without breaking other layers
+6. **Approval Certification**: When all tests pass across all layers, certify code as approved
 
 ## Execution Process
 
@@ -68,22 +78,67 @@ When task JSON contains implementation_approach array:
 ### 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 layers** by analyzing test file paths and naming patterns:
+  - L0 (Static): Linting configs (`.eslintrc`, `tsconfig.json`), static analysis tools
+  - L1 (Unit): `*.test.*`, `*.spec.*` in `__tests__/`, `tests/unit/`
+  - L2 (Integration): `tests/integration/`, `*.integration.test.*`
+  - L3 (E2E): `tests/e2e/`, `*.e2e.test.*`, `cypress/`, `playwright/`
 - **context-package.json** (CCW Workflow): Extract artifact paths using `jq -r '.brainstorm_artifacts.role_analyses[].files[].path'`
-- Identify test command from project configuration
+- Identify test commands from project configuration
 
 ```bash
-# Detect test framework and command
+# Detect test framework and multi-layered commands
 if [ -f "package.json" ]; then
-    TEST_CMD=$(cat package.json | jq -r '.scripts.test')
+    # Extract layer-specific test commands
+    LINT_CMD=$(cat package.json | jq -r '.scripts.lint // "eslint ."')
+    UNIT_CMD=$(cat package.json | jq -r '.scripts["test:unit"] // .scripts.test')
+    INTEGRATION_CMD=$(cat package.json | jq -r '.scripts["test:integration"] // ""')
+    E2E_CMD=$(cat package.json | jq -r '.scripts["test:e2e"] // ""')
 elif [ -f "pytest.ini" ] || [ -f "setup.py" ]; then
-    TEST_CMD="pytest"
+    LINT_CMD="ruff check . || flake8 ."
+    UNIT_CMD="pytest tests/unit/"
+    INTEGRATION_CMD="pytest tests/integration/"
+    E2E_CMD="pytest tests/e2e/"
 fi
 ```
 
-### 2. Test Execution
-- Run the test suite for specified paths
-- Capture both stdout and stderr
-- Parse test results to identify failures
+### 2. Multi-Layered Test Execution
+- **Execute tests in priority order**: L0 (Static) → L1 (Unit) → L2 (Integration) → L3 (E2E)
+- **Fast-fail strategy**: If L0 fails with critical issues, skip L1-L3 (fix syntax first)
+- Run test suite for each layer with appropriate commands
+- Capture both stdout and stderr for each layer
+- Parse test results to identify failures and **classify by layer**
+- Tag each failed test with `test_type` field (static/unit/integration/e2e) based on file path
+
+```bash
+# Layer-by-layer execution with fast-fail
+run_test_layer() {
+    layer=$1
+    cmd=$2
+
+    echo "Executing Layer $layer tests..."
+    $cmd 2>&1 | tee ".process/test-layer-$layer-output.txt"
+
+    # Parse results and tag with test_type
+    parse_test_results ".process/test-layer-$layer-output.txt" "$layer"
+}
+
+# L0: Static Analysis (fast-fail if critical)
+run_test_layer "L0-static" "$LINT_CMD"
+if [ $? -ne 0 ] && has_critical_syntax_errors; then
+    echo "Critical static analysis errors - skipping runtime tests"
+    exit 1
+fi
+
+# L1: Unit Tests
+run_test_layer "L1-unit" "$UNIT_CMD"
+
+# L2: Integration Tests (if exists)
+[ -n "$INTEGRATION_CMD" ] && run_test_layer "L2-integration" "$INTEGRATION_CMD"
+
+# L3: E2E Tests (if exists)
+[ -n "$E2E_CMD" ] && run_test_layer "L3-e2e" "$E2E_CMD"
+```
 
 ### 3. Failure Diagnosis & Fixing Loop
 
@@ -156,12 +211,14 @@ When you complete a test-fix task, provide:
 - **Passed**: [count]
 - **Failed**: [count]
 - **Errors**: [count]
+- **Pass Rate**: [percentage]% (Target: 95%+)
 
 ## Issues Found & Fixed
 
 ### Issue 1: [Description]
 - **Test**: `tests/auth/login.test.ts::testInvalidCredentials`
 - **Error**: `Expected status 401, got 500`
+- **Criticality**: high (security issue, core functionality broken)
 - **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`
@@ -169,6 +226,7 @@ When you complete a test-fix task, provide:
 ### Issue 2: [Description]
 - **Test**: `tests/payment/process.test.ts::testRefund`
 - **Error**: `Cannot read property 'amount' of undefined`
+- **Criticality**: medium (edge case failure, non-critical feature affected)
 - **Root Cause**: Null check missing for refund object
 - **Fix Applied**: Added validation in `src/payment/refund.ts:78`
 - **Files Modified**: `src/payment/refund.ts`
@@ -178,6 +236,7 @@ When you complete a test-fix task, provide:
 ✅ **All tests passing**
 - **Total Tests**: [count]
 - **Passed**: [count]
+- **Pass Rate**: 100%
 - **Duration**: [time]
 
 ## Code Approval
@@ -190,6 +249,71 @@ All tests pass - code is ready for deployment.
 - `src/payment/refund.ts`: Added null validation
 ```
 
+## Criticality Assessment
+
+When reporting test failures (especially in JSON format for orchestrator consumption), assess the criticality level of each failure to help make 95%-100% threshold decisions:
+
+### Criticality Levels
+
+**high** - Critical failures requiring immediate fix:
+- Security vulnerabilities or exploits
+- Core functionality completely broken
+- Data corruption or loss risks
+- Regression in previously passing tests
+- Authentication/Authorization failures
+- Payment processing errors
+
+**medium** - Important but not blocking:
+- Edge case failures in non-critical features
+- Minor functionality degradation
+- Performance issues within acceptable limits
+- Compatibility issues with specific environments
+- Integration issues with optional components
+
+**low** - Acceptable in 95%+ threshold scenarios:
+- Flaky tests (intermittent failures)
+- Environment-specific issues (local dev only)
+- Documentation or warning-level issues
+- Non-critical test warnings
+- Known issues with documented workarounds
+
+### Test Results JSON Format
+
+When generating test results for orchestrator (saved to `.process/test-results.json`):
+
+```json
+{
+  "total": 10,
+  "passed": 9,
+  "failed": 1,
+  "pass_rate": 90.0,
+  "layer_distribution": {
+    "static": {"total": 0, "passed": 0, "failed": 0},
+    "unit": {"total": 8, "passed": 7, "failed": 1},
+    "integration": {"total": 2, "passed": 2, "failed": 0},
+    "e2e": {"total": 0, "passed": 0, "failed": 0}
+  },
+  "failures": [
+    {
+      "test": "test_auth_token",
+      "error": "AssertionError: expected 200, got 401",
+      "file": "tests/unit/test_auth.py",
+      "line": 45,
+      "criticality": "high",
+      "test_type": "unit"
+    }
+  ]
+}
+```
+
+### Decision Support
+
+**For orchestrator decision-making**:
+- Pass rate 100% + all tests pass → ✅ SUCCESS (proceed to completion)
+- Pass rate >= 95% + all failures are "low" criticality → ✅ PARTIAL SUCCESS (review and approve)
+- Pass rate >= 95% + any "high" or "medium" criticality failures → ⚠️ NEEDS FIX (continue iteration)
+- Pass rate < 95% → ❌ FAILED (continue iteration or abort)
+
 ## Important Reminders
 
 **ALWAYS:**

.claude/commands/cli/analyze.md

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

.claude/commands/cli/chat.md

@@ -1,7 +1,7 @@
 ---
 name: chat
-description: Simple CLI interaction command for direct codebase analysis
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] inquiry"
+description: Read-only Q&A interaction with Gemini/Qwen/Codex for codebase questions with automatic context inference
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] inquiry"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -9,140 +9,74 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Direct Q&A interaction with CLI tools for codebase analysis. **Analysis only - does NOT modify code**.
+Direct Q&A interaction with CLI tools for codebase analysis. **Read-only - does NOT modify code**.
 
-**Intent**: Ask questions, get explanations, understand codebase structure
-**Supported Tools**: codex, gemini (default), qwen
-
-## Core Behavior
-
-1. **Conversational Analysis**: Direct question-answer interaction about codebase
-2. **Read-Only**: This command ONLY provides information and analysis
-3. **No Code Modification**: Results are explanations and insights
-4. **Flexible Context**: Choose specific files or entire codebase
+**Tool Selection**:
+- **gemini** (default) - Best for Q&A and explanations
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for technical deep-dives
 
 ## Parameters
 
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--enhance` - Enhance inquiry with `/enhance-prompt`
 - `<inquiry>` (Required) - Question or analysis request
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode)
-- `--enhance` - Enhance inquiry with `/enhance-prompt` first
-- `--save-session` - Save interaction to workflow session
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-### Standard Mode (Default)
+Uses **cli-execution-agent** (default) for automated Q&A:
 
-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 `@**/*` for entire codebase
-4. Execute CLI tool with assembled context (read-only, analysis mode)
-5. Return explanations and insights (NO code changes)
-6. Optionally save to workflow session
-
-### Agent Mode (`--agent` flag)
-
-Delegate inquiry to `cli-execution-agent` for intelligent Q&A with automated context discovery.
-
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Answer question with automated context discovery",
+  description="Codebase Q&A with intelligent context discovery",
   prompt=`
     Task: ${inquiry}
-    Mode: analyze (Q&A)
-    Tool Preference: ${tool_flag || 'auto-select'}
+    Mode: chat
+    Tool: ${tool_flag || 'gemini'}
+    Enhance: ${enhance_flag}
 
-    Agent will autonomously:
-    - Discover files relevant to the question
-    - Build Q&A prompt with precise context
-    - Execute and generate comprehensive answer
-    - Save conversation log
+    Execute codebase Q&A with intelligent context discovery:
+
+    1. Context Discovery:
+       - Parse inquiry to identify relevant topics/keywords
+       - Discover related files using MCP/ripgrep (prioritize precision)
+       - Include @CLAUDE.md + discovered files
+       - Validate context relevance to question
+
+    2. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for deep dives)
+       - Context: @CLAUDE.md + discovered file patterns
+       - Mode: analysis (read-only)
+       - Expected: Clear, accurate answer with code references
+
+    3. Execution & Output:
+       - Execute CLI tool with assembled context
+       - Validate answer completeness
+       - Save to .workflow/active/WFS-[id]/.chat/chat-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
-The agent handles all phases internally.
+## Core Rules
 
-## Context Assembly
-
-**Always included**: `@CLAUDE.md @**/*CLAUDE.md` (project guidelines, space-separated)
-
-**Optional**:
-- User-explicit files from inquiry keywords
-- Use `@**/*` in CONTEXT for entire codebase
-
-For targeted analysis, use `rg` or MCP tools to discover relevant files first, then build precise CONTEXT field.
-
-## Command Template
-
-```bash
-cd . && gemini -p "
-PURPOSE: Answer user inquiry about codebase
-TASK: [user question]
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md [inferred files or @**/* for all files]
-EXPECTED: Direct answer, explanation, insights (NO code modification)
-RULES: Focus on clarity and accuracy
-"
-```
-
-## Examples
-
-**Basic Question (Standard Mode)**:
-```bash
-/cli:chat "analyze the authentication flow"
-# Executes: Gemini analysis
-# Returns: Explanation of auth flow, components involved, data flow
-```
-
-**Intelligent Q&A (Agent Mode)**:
-```bash
-/cli:chat --agent "how does JWT token refresh work in this codebase"
-# Phase 1: Understands inquiry = JWT refresh mechanism
-# Phase 2: Discovers JWT files, refresh logic, middleware patterns
-# Phase 3: Builds Q&A prompt with discovered implementation details
-# Phase 4: Executes Gemini with precise context for accurate answer
-# Phase 5: Saves conversation log with discovered context
-# Returns: Detailed answer with code references + execution log
-```
-
-**Architecture Question**:
-```bash
-/cli:chat --tool qwen -p "how does React component optimization work here"
-# Executes: Qwen architecture analysis
-# Returns: Component structure explanation, optimization patterns used
-```
-
-**Security Analysis**:
-```bash
-/cli:chat --tool codex "review security vulnerabilities"
-# Executes: Codex security analysis
-# Returns: Vulnerability assessment, security recommendations (NO automatic fixes)
-```
-
-**Enhanced Inquiry**:
-```bash
-/cli:chat --enhance "explain the login issue"
-# Step 1: Enhance to expand login context
-# Step 2: Analysis with expanded understanding
-# Returns: Detailed explanation of login flow and potential issues
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND query is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/chat-[timestamp].md`
-- **No active session OR unrelated query**:
-  - Save to `.workflow/.scratchpad/chat-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-api-refactor`, asking about API structure → `.chat/chat-20250105-143022.md`
-- No session, asking about build process → `.scratchpad/chat-build-process-20250105-143045.md`
-
-## Notes
-
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Scratchpad conversations preserved for future reference
+- **Read-only**: Provides answers, does NOT modify code
+- **Context**: `@CLAUDE.md` + inferred or all files (`@**/*`)
+- **Output**: `.workflow/active/WFS-[id]/.chat/chat-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -1,6 +1,6 @@
 ---
 name: cli-init
-description: Initialize CLI tool configurations (Gemini and Qwen) based on workspace analysis
+description: Generate .gemini/ and .qwen/ config directories with settings.json and ignore files based on workspace technology detection
 argument-hint: "[--tool gemini|qwen|all] [--output path] [--preview]"
 allowed-tools: Bash(*), Read(*), Write(*), Glob(*)
 ---
@@ -178,7 +178,7 @@ target/
 /cli:cli-init --tool all --output=.config/
 ```
 
-## EXECUTION INSTRUCTIONS ⚡ START HERE
+## EXECUTION INSTRUCTIONS - START HERE
 
 **When this command is triggered, follow these exact steps:**
 
@@ -209,7 +209,7 @@ bash(find . -name "Dockerfile" | head -1)
 ```bash
 # Create .gemini/ directory and settings.json
 mkdir -p .gemini
-echo '{"contextfilename": "CLAUDE.md"}' > .gemini/settings.json
+Write({file_path: '.gemini/settings.json', content: '{"contextfilename": "CLAUDE.md"}'})
 
 # Create .geminiignore file with detected technology rules
 # Backup existing files if present
@@ -219,7 +219,7 @@ echo '{"contextfilename": "CLAUDE.md"}' > .gemini/settings.json
 ```bash
 # Create .qwen/ directory and settings.json
 mkdir -p .qwen
-echo '{"contextfilename": "CLAUDE.md"}' > .qwen/settings.json
+Write({file_path: '.qwen/settings.json', content: '{"contextfilename": "CLAUDE.md"}'})
 
 # Create .qwenignore file with detected technology rules
 # Backup existing files if present
@@ -428,15 +428,6 @@ docker-compose.override.yml
 /cli:cli-init --tool all --preview
 ```
 
-## Key Benefits
-
-- **Automatic Detection**: No manual configuration needed
-- **Multi-Tool Support**: Configure Gemini and Qwen simultaneously
-- **Technology Aware**: Rules adapted to actual project stack
-- **Maintainable**: Clear sections for easy customization
-- **Consistent**: Follows gitignore syntax standards
-- **Safe**: Creates backups of existing files
-- **Flexible**: Initialize specific tools or all at once
 
 ## Tool Selection Guide
 

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

@@ -1,6 +1,6 @@
 ---
 name: codex-execute
-description: Automated task decomposition and execution with Codex using resume mechanism
+description: Multi-stage Codex execution with automatic task decomposition into grouped subtasks using resume mechanism for context continuity
 argument-hint: "[--verify-git] task description or task-id"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
@@ -257,12 +257,12 @@ TodoWrite({
 
 **When to Resume vs New Session**:
 ```
-✅ RESUME (same group):
+RESUME (same group):
   - Subtasks share files/modules
   - Logical continuation of previous work
   - Same architectural domain
 
-❌ NEW SESSION (different group):
+NEW SESSION (different group):
   - Independent task area
   - Different files/modules
   - Switching architectural domains
@@ -318,7 +318,7 @@ AskUserQuestion({
 
 **During Execution**:
 ```
-📊 Task Flow Diagram:
+Task Flow Diagram:
 [Group A: Auth Core]
   A1: Create user model ──┐
   A2: Add validation     ─┤─► [resume] ─► A3: Database schema
@@ -331,7 +331,7 @@ AskUserQuestion({
   C1: Unit tests ─────────────► [new session]
   C2: Integration tests ──────► [resume]
 
-📋 Task Decomposition:
+Task Decomposition:
   [Group A] 1. Create user model
   [Group A] 2. Add validation logic [resume]
   [Group A] 3. Implement database schema [resume]
@@ -341,28 +341,28 @@ AskUserQuestion({
   [Group C] 7. Unit tests [new session]
   [Group C] 8. Integration tests [resume]
 
-▶️  [Group A] Executing Subtask 1/8: Create user model
+[Group A] Executing Subtask 1/8: Create user model
   Starting new Codex session for Group A...
   [Codex output]
-  ✅ Subtask 1 completed
+  Subtask 1 completed
 
-🔍 Git Verification:
+Git Verification:
   M  src/models/user.ts
-  ✅ Changes verified
+  Changes verified
 
-▶️  [Group A] Executing Subtask 2/8: Add validation logic
+[Group A] Executing Subtask 2/8: Add validation logic
   Resuming Codex session (same group)...
   [Codex output]
-  ✅ Subtask 2 completed
+  Subtask 2 completed
 
-▶️  [Group B] Executing Subtask 4/8: Create auth endpoints
+[Group B] Executing Subtask 4/8: Create auth endpoints
   Starting NEW Codex session for Group B...
   [Codex output]
-  ✅ Subtask 4 completed
+  Subtask 4 completed
 ...
 
-✅ All Subtasks Completed
-📊 Summary: [file references, changes, next steps]
+All Subtasks Completed
+Summary: [file references, changes, next steps]
 ```
 
 **Final Summary**:
@@ -370,8 +370,8 @@ AskUserQuestion({
 # Task Execution Summary: [Task Description]
 
 ## Subtasks Completed
-1. ✅ [Subtask 1]: [files modified]
-2. ✅ [Subtask 2]: [files modified]
+1. [Subtask 1]: [files modified]
+2. [Subtask 2]: [files modified]
 ...
 
 ## Files Modified
@@ -468,9 +468,9 @@ AskUserQuestion({
 
 **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
+  - Execution log: `.workflow/active/WFS-[id]/.chat/codex-execute-[timestamp].md`
+  - Task summaries: `.workflow/active/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
+  - Task updates: `.workflow/active/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`)
@@ -478,7 +478,7 @@ AskUserQuestion({
 
 **Output Files** (during execution):
 ```
-.workflow/WFS-[session-id]/
+.workflow/active/WFS-[session-id]/
 ├── .chat/
 │   └── codex-execute-20250105-143022.md    # Full execution log with task flow
 ├── .summaries/
@@ -492,9 +492,9 @@ AskUserQuestion({
 
 **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)
+  - Log: `.workflow/active/WFS-auth-system/.chat/codex-execute-20250105-143022.md`
+  - Summaries: `.workflow/active/WFS-auth-system/.summaries/IMPL-001.{1,2,3}-summary.md`
+  - Task status: `.workflow/active/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`
 

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

@@ -1,6 +1,6 @@
 ---
 name: discuss-plan
-description: Orchestrates an iterative, multi-model discussion for planning and analysis without implementation.
+description: Multi-round collaborative planning using Gemini, Codex, and Claude synthesis with iterative discussion cycles (read-only, no code changes)
 argument-hint: "[--topic '...'] [--task-id '...'] [--rounds N]"
 allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 ---
@@ -167,9 +167,9 @@ TodoWrite({
 ## Output Routing
 
 -   **Primary Log**: Entire multi-round discussion logged to single file:
-    -   `.workflow/WFS-[id]/.chat/discuss-plan-[topic]-[timestamp].md`
+    -   `.workflow/active/WFS-[id]/.chat/discuss-plan-[topic]-[timestamp].md`
 -   **Final Plan**: Clean final version saved upon conclusion:
-    -   `.workflow/WFS-[id]/.summaries/plan-[topic].md`
+    -   `.workflow/active/WFS-[id]/.summaries/plan-[topic].md`
 -   **Scratchpad**: If no session active:
     -   `.workflow/.scratchpad/discuss-plan-[topic]-[timestamp].md`
 
@@ -279,11 +279,11 @@ Each round's output is structured as:
 
 | Command | Models | Rounds | Discussion | Implementation | Use Case |
 |---------|--------|--------|------------|----------------|----------|
-| `/cli:mode:plan` | Gemini | 1 | ❌ NO | ❌ NO | Single-model planning |
-| `/cli:analyze` | Gemini/Qwen | 1 | ❌ NO | ❌ NO | Code analysis |
-| `/cli:execute` | Any | 1 | ❌ NO | ✅ YES | Direct implementation |
-| `/cli:codex-execute` | Codex | 1 | ❌ NO | ✅ YES | Multi-stage implementation |
-| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | ✅ **YES** | ❌ **NO** | **Multi-perspective planning** |
+| `/cli:mode:plan` | Gemini | 1 | NO | NO | Single-model planning |
+| `/cli:analyze` | Gemini/Qwen | 1 | NO | NO | Code analysis |
+| `/cli:execute` | Any | 1 | NO | YES | Direct implementation |
+| `/cli:codex-execute` | Codex | 1 | NO | YES | Multi-stage implementation |
+| `/cli:discuss-plan` | **Gemini+Codex+Claude** | **Multiple** | **YES** | **NO** | **Multi-perspective planning** |
 
 ## Best Practices
 

.claude/commands/cli/execute.md

@@ -1,7 +1,7 @@
 ---
 name: execute
-description: Auto-execution of implementation tasks with YOLO permissions and intelligent context inference
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] description or task-id"
+description: Autonomous code implementation with YOLO auto-approval using Gemini/Qwen/Codex, supports task ID or description input with automatic file pattern detection
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] description or task-id"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -27,7 +27,7 @@ Execute implementation tasks with **YOLO permissions** (auto-approves all confir
 ### YOLO Permissions
 Auto-approves: file pattern inference, execution, **file modifications**, summary generation
 
-**⚠️ WARNING**: This command will make actual code changes without manual confirmation
+**WARNING**: This command will make actual code changes without manual confirmation
 
 ### Execution Modes
 
@@ -39,7 +39,7 @@ Auto-approves: file pattern inference, execution, **file modifications**, summar
 - Input: Workflow task identifier (e.g., `IMPL-001`)
 - Process: Task JSON parsing → Scope analysis → Execute
 
-**3. Agent Mode** (`--agent` flag):
+**3. Agent Mode** (default):
 - Input: Description or task-id
 - Process: 5-Phase Workflow → Context Discovery → Optimal Tool Selection → Execute
 
@@ -68,8 +68,7 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Select CLI tool (default: gemini, ignored in agent mode unless specified)
+- `--tool <codex|gemini|qwen>` - Select CLI tool (default: auto-select by agent based on complexity)
 - `--enhance` - Enhance input with `/enhance-prompt` first (Description Mode only)
 - `<description|task-id>` - Natural language description or task identifier
 - `--debug` - Verbose logging
@@ -77,106 +76,93 @@ Use `resume --last` when current task extends/relates to previous execution. See
 
 ## Workflow Integration
 
-**Session Management**: Auto-detects `.workflow/.active-*` marker
-- Active session: Save to `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
+**Session Management**: Auto-detects active session from `.workflow/active/` directory
+- Active session: Save to `.workflow/active/WFS-[id]/.chat/execute-[timestamp].md`
 - No session: Create new session or save to scratchpad
 
 **Task Integration**: Load from `.task/[TASK-ID].json`, update status, generate summary
 
-## Output Routing
+## Execution Flow
 
-**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`
+Uses **cli-execution-agent** (default) for automated implementation:
 
-**Output Files** (when active session exists):
-- Execution log: `.workflow/WFS-[id]/.chat/execute-[timestamp].md`
-- Task summary: `.workflow/WFS-[id]/.summaries/[TASK-ID]-summary.md` (if task ID)
-- Modified code: Project files per implementation
-
-**Examples**:
-- During session `WFS-auth-system`, executing `IMPL-001`:
-  - Log: `.workflow/WFS-auth-system/.chat/execute-20250105-143022.md`
-  - Summary: `.workflow/WFS-auth-system/.summaries/IMPL-001-summary.md`
-- No session, ad-hoc implementation:
-  - Log: `.workflow/.scratchpad/execute-jwt-auth-20250105-143045.md`
-
-## Execution Modes
-
-### Standard Mode (Default)
-```bash
-# Gemini/Qwen: MODE=write with --approval-mode yolo
-cd . && gemini --approval-mode yolo "
-PURPOSE: [implementation goal]
-TASK: [specific implementation]
-MODE: write
-CONTEXT: @CLAUDE.md [auto-detected files]
-EXPECTED: Working implementation with code changes
-RULES: [constraints] | Auto-approve all changes
-"
-
-# Codex: MODE=auto with danger-full-access
-codex -C . --full-auto exec "
-PURPOSE: [implementation goal]
-TASK: [specific implementation]
-MODE: auto
-CONTEXT: [auto-detected files]
-EXPECTED: Complete implementation with tests
-" --skip-git-repo-check -s danger-full-access
-```
-
-### Agent Mode (`--agent` flag)
-
-Delegate implementation to `cli-execution-agent` for intelligent execution with automated context discovery.
-
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Implement with automated context discovery and optimal tool selection",
+  description="Autonomous code implementation with YOLO auto-approval",
   prompt=`
     Task: ${description_or_task_id}
     Mode: execute
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${enhance_flag ? 'Enhance: true' : ''}
+    Tool: ${tool_flag || 'auto-select'}
+    Enhance: ${enhance_flag}
+    Task-ID: ${task_id}
 
-    Agent will autonomously:
-    - Discover implementation files and dependencies
-    - Assess complexity and select optimal tool
-    - Execute with YOLO permissions (auto-approve)
-    - Generate task summary if task-id provided
+    Execute autonomous code implementation with full modification permissions:
+
+    1. Task Analysis:
+       ${task_id ? '- Load task spec from .task/' + task_id + '.json' : ''}
+       - Parse requirements and implementation scope
+       - Classify complexity (simple/medium/complex)
+       - Extract keywords for context discovery
+
+    2. Context Discovery:
+       - Discover implementation files using MCP/ripgrep
+       - Identify existing patterns and conventions (CLAUDE.md)
+       - Map dependencies and integration points
+       - Gather related tests and documentation
+       - Auto-detect file patterns from keywords
+
+    3. Tool Selection & Execution:
+       - Complexity assessment:
+         * Simple/Medium → Gemini/Qwen (MODE=write, --approval-mode yolo)
+         * Complex → Codex (MODE=auto, --skip-git-repo-check -s danger-full-access)
+       - Tool preference: ${tool_flag || 'auto-select based on complexity'}
+       - Apply appropriate implementation template
+       - Execute with YOLO auto-approval (bypasses all confirmations)
+
+    4. Implementation:
+       - Modify/create/delete code files per requirements
+       - Follow existing code patterns and conventions
+       - Include comprehensive context in CLI command
+       - Ensure working implementation with proper error handling
+
+    5. Output & Documentation:
+       - Save execution log: .workflow/active/WFS-[id]/.chat/execute-[timestamp].md
+       ${task_id ? '- Generate task summary: .workflow/active/WFS-[id]/.summaries/' + task_id + '-summary.md' : ''}
+       ${task_id ? '- Update task status in .task/' + task_id + '.json' : ''}
+       - Document all code changes made
+
+    ⚠️ YOLO Mode: All file operations auto-approved without confirmation
   `
 )
 ```
 
-The agent handles all phases internally, including complexity-based tool selection.
+**Output**: `.workflow/active/WFS-[id]/.chat/execute-[timestamp].md` + `.workflow/active/WFS-[id]/.summaries/[TASK-ID]-summary.md` (or `.scratchpad/` if no session)
 
 ## Examples
 
-**Basic Implementation (Standard Mode)** (⚠️ modifies code):
+**Basic Implementation** (modifies code):
 ```bash
 /cli:execute "implement JWT authentication with middleware"
-# Executes: Creates auth middleware, updates routes, modifies config
+# Agent Phase 1: Classifies intent=execute, complexity=medium, keywords=['jwt', 'auth', 'middleware']
+# Agent Phase 2: Discovers auth patterns, existing middleware structure
+# Agent Phase 3: Selects Gemini (medium complexity)
+# Agent Phase 4: Executes with auto-approval
 # Result: NEW/MODIFIED code files with JWT implementation
 ```
 
-**Intelligent Implementation (Agent Mode)** (⚠️ modifies code):
+**Complex Implementation** (modifies code):
 ```bash
-/cli:execute --agent "implement OAuth2 authentication with token refresh"
-# Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
-# Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
-# Phase 3: Enhances prompt with discovered patterns and best practices
-# Phase 4: Selects Codex (complex task), executes with comprehensive context
-# Phase 5: Saves execution log + generates implementation summary
+/cli:execute "implement OAuth2 authentication with token refresh"
+# Agent Phase 1: Classifies intent=execute, complexity=complex, keywords=['oauth2', 'auth', 'token', 'refresh']
+# Agent Phase 2: MCP discovers auth patterns, existing middleware, JWT dependencies
+# Agent Phase 3: Enhances prompt with discovered patterns and best practices
+# Agent Phase 4: Selects Codex (complex task), executes with comprehensive context
+# Agent Phase 5: Saves execution log + generates implementation summary
 # Result: Complete OAuth2 implementation + detailed execution log
 ```
 
-**Enhanced Implementation** (⚠️ modifies code):
+**Enhanced Implementation** (modifies code):
 ```bash
 /cli:execute --enhance "implement JWT authentication"
 # Step 1: Enhance to expand requirements
@@ -184,7 +170,7 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Complete auth system with MODIFIED code files
 ```
 
-**Task Execution** (⚠️ modifies code):
+**Task Execution** (modifies code):
 ```bash
 /cli:execute IMPL-001
 # Reads: .task/IMPL-001.json for requirements
@@ -192,14 +178,14 @@ The agent handles all phases internally, including complexity-based tool selecti
 # Result: Code changes per task definition
 ```
 
-**Codex Implementation** (⚠️ modifies code):
+**Codex Implementation** (modifies code):
 ```bash
 /cli:execute --tool codex "optimize database queries"
 # Executes: Codex with full file access
 # Result: MODIFIED query code, new indexes, updated tests
 ```
 
-**Qwen Code Generation** (⚠️ modifies code):
+**Qwen Code Generation** (modifies code):
 ```bash
 /cli:execute --tool qwen --enhance "refactor auth module"
 # Step 1: Enhanced refactoring plan
@@ -211,11 +197,6 @@ The agent handles all phases internally, including complexity-based tool selecti
 
 | Command | Intent | Code Changes | Auto-Approve |
 |---------|--------|--------------|--------------|
-| `/cli:analyze` | Understand code | ❌ NO | N/A |
-| `/cli:chat` | Ask questions | ❌ NO | N/A |
-| `/cli:execute` | **Implement** | ✅ **YES** | ✅ **YES** |
-
-## Notes
-
-- Command templates, YOLO mode details, and session management: see intelligent-tools-strategy.md (loaded in memory)
-- **⚠️ Code Modification**: This command modifies code - execution logs document changes made
+| `/cli:analyze` | Understand code | NO | N/A |
+| `/cli:chat` | Ask questions | NO | N/A |
+| `/cli:execute` | **Implement** | **YES** | **YES** |

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

@@ -0,0 +1,96 @@
+---
+name: bug-diagnosis
+description: Read-only bug root cause analysis using Gemini/Qwen/Codex with systematic diagnosis template for fix suggestions
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] bug description"
+allowed-tools: SlashCommand(*), Bash(*), Task(*)
+---
+
+# CLI Mode: Bug Diagnosis (/cli:mode:bug-diagnosis)
+
+## Purpose
+
+Systematic bug diagnosis with root cause analysis template (`~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for bug diagnosis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex bug analysis
+
+## Parameters
+
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--enhance` - Enhance bug description with `/enhance-prompt`
+- `--cd "path"` - Target directory for focused diagnosis
+- `<bug-description>` (Required) - Bug description or error details
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+# Uses gemini by default, or specify explicitly
+--tool gemini
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
+
+## Execution Flow
+
+Uses **cli-execution-agent** (default) for automated bug diagnosis:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Bug root cause diagnosis with fix suggestions",
+  prompt=`
+    Task: ${bug_description}
+    Mode: bug-diagnosis
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt
+
+    Execute systematic bug diagnosis and root cause analysis:
+
+    1. Context Discovery:
+       - Locate error traces, stack traces, and log messages
+       - Find related code sections and affected modules
+       - Identify data flow paths leading to the bug
+       - Discover test cases related to bug area
+       - Use MCP/ripgrep for comprehensive context gathering
+
+    2. Root Cause Analysis:
+       - Apply diagnostic template methodology
+       - Trace execution to identify failure point
+       - Analyze state, data, and logic causing issue
+       - Document potential root causes with evidence
+       - Assess bug severity and impact scope
+
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex bugs)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* + error traces + affected code
+       - Mode: analysis (read-only)
+       - Template: analysis/01-diagnose-bug-root-cause.txt
+
+    4. Output Generation:
+       - Root cause diagnosis with evidence
+       - Fix suggestions and recommendations
+       - Prevention strategies
+       - Save to .workflow/active/WFS-[id]/.chat/bug-diagnosis-[timestamp].md (or .scratchpad/)
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Diagnoses bugs, does NOT modify code
+- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt`
+- **Output**: `.workflow/active/WFS-[id]/.chat/bug-diagnosis-[timestamp].md` (or `.scratchpad/` if no session)

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: code-analysis
-description: Deep code analysis and debugging using CLI tools with specialized template
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
+description: Read-only execution path tracing using Gemini/Qwen/Codex with specialized analysis template for call flow and optimization
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] analysis target"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -9,161 +9,90 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Systematic code analysis with execution path tracing template (`~/.claude/prompt-templates/code-analysis.md`).
+Systematic code analysis with execution path tracing template (`~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`).
+
+**Tool Selection**:
+- **gemini** (default) - Best for code analysis and tracing
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex analysis tasks
 
-**Supported Tools**: codex, gemini (default), qwen
 **Key Feature**: `--cd` flag for directory-scoped analysis
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
+- `--tool <gemini|qwen|codex>` - 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
 
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+/cli:mode:code-analysis --tool gemini "trace auth flow"
+# OR (default)
+/cli:mode:code-analysis "trace auth flow"
+```
+
+**Qwen** (Fallback):
+```bash
+/cli:mode:code-analysis --tool qwen "trace auth flow"
+```
+
+**Codex** (Alternative):
+```bash
+/cli:mode:code-analysis --tool codex "trace auth flow"
+```
+
 ## Execution Flow
 
-### Standard Mode (Default)
+Uses **cli-execution-agent** (default) for automated code analysis:
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[analysis-target]"` first
-3. Parse analysis target (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with code-analysis template
-6. Execute deep analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-
-### Agent Mode (`--agent` flag)
-
-Delegate code analysis to `cli-execution-agent` for intelligent execution path tracing with automated context discovery.
-
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Analyze code execution paths with automated context discovery",
+  description="Execution path tracing and call flow analysis",
   prompt=`
     Task: ${analysis_target}
-    Mode: code-analysis (execution tracing)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
-    Template: code-analysis
+    Mode: code-analysis
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt
 
-    Agent will autonomously:
-    - Discover execution paths and call flows
-    - Build analysis prompt with code-analysis template
-    - Execute deep tracing analysis
-    - Generate call diagrams and save log
+    Execute systematic code analysis with execution path tracing:
+
+    1. Context Discovery:
+       - Identify entry points and function signatures
+       - Trace call chains and execution flows
+       - Discover related files (implementations, dependencies, tests)
+       - Map data flow and state transformations
+       - Use MCP/ripgrep for comprehensive file discovery
+
+    2. Analysis Execution:
+       - Apply execution tracing template
+       - Generate call flow diagrams (textual)
+       - Document execution paths and branching logic
+       - Identify optimization opportunities
+
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex analysis)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* + discovered execution context
+       - Mode: analysis (read-only)
+       - Template: analysis/01-trace-code-execution.txt
+
+    4. Output Generation:
+       - Execution trace documentation
+       - Call flow analysis with diagrams
+       - Performance and optimization insights
+       - Save to .workflow/active/WFS-[id]/.chat/code-analysis-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
-The agent handles all phases internally.
-
 ## Core Rules
 
-1. **Analysis Only**: This command analyzes code and provides insights - it does NOT modify code
-2. **Tool Selection**: Use `--tool` value or default to gemini
-3. **Enhance First (if flagged)**: Execute `/enhance-prompt` before analysis
-4. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-5. **Template Required**: Always use code-analysis template
-6. **Session Output**: Save analysis results to session chat
-
-## Analysis Capabilities (via Template)
-
-- **Systematic Code Analysis**: Break down complex code into manageable parts
-- **Execution Path Tracing**: Track variable states and call stacks
-- **Control & Data Flow**: Understand code logic and data transformations
-- **Call Flow Visualization**: Diagram function calling sequences
-- **Logical Reasoning**: Explain "why" behind code behavior
-- **Debugging Insights**: Identify potential bugs or inefficiencies
-
-## Command Template
-
-```bash
-cd [directory] && gemini -p "
-PURPOSE: [analysis goal]
-TASK: Systematic code analysis and execution path tracing
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
-EXPECTED: Execution trace, call flow diagram, debugging insights
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on [aspect]
-"
-```
-
-## Examples
-
-**Basic Code Analysis (Standard Mode)**:
-```bash
-/cli:mode:code-analysis "trace authentication execution flow"
-# Executes: Gemini with code-analysis template
-# Returns: Execution trace, call diagram, debugging insights
-```
-
-**Intelligent Code Analysis (Agent Mode)**:
-```bash
-/cli:mode:code-analysis --agent "trace JWT token validation from request to database"
-# Phase 1: Classifies as deep analysis, keywords ['jwt', 'token', 'validation', 'database']
-# Phase 2: MCP discovers request handler → middleware → service → repository chain
-# Phase 3: Builds analysis prompt with code-analysis template + complete call path
-# Phase 4: Executes Gemini with traced execution paths
-# Phase 5: Saves detailed analysis with call flow diagrams and variable states
-# Returns: Complete execution trace + call diagram + data flow analysis
-```
-
-**Standard Template Example**:
-```bash
-cd . && gemini -p "
-PURPOSE: Trace authentication execution flow
-TASK: Analyze complete auth flow from request to response
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md
-EXPECTED: Step-by-step execution trace with call diagram, variable states
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on control flow
-"
-```
-
-**Directory-Specific Analysis**:
-```bash
-cd src/auth && gemini -p "
-PURPOSE: Understand JWT token validation logic
-TASK: Trace JWT validation from middleware to service layer
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md
-EXPECTED: Validation flow diagram, token lifecycle analysis
-RULES: $(cat ~/.claude/prompt-templates/code-analysis.md) | Focus on security
-"
-```
-
-## Code Tracing Workflow
-
-```bash
-# 1. Find entry points and related files
-rg "function.*authenticate|class.*AuthService" --files-with-matches
-rg "authenticate|login" -g "*.ts"
-
-# 2. Build call graph understanding
-# entry → middleware → service → repository
-
-# 3. Execute deep analysis (analysis only, no code changes)
-/cli:mode:code-analysis --cd "src" "trace execution from entry point"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND analysis is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/code-analysis-[timestamp].md`
-- **No active session OR standalone analysis**:
-  - Save to `.workflow/.scratchpad/code-analysis-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-auth-refactor`, analyzing auth flow → `.chat/code-analysis-20250105-143022.md`
-- No session, tracing request lifecycle → `.scratchpad/code-analysis-request-flow-20250105-143045.md`
-
-## Notes
-
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Template path: `~/.claude/prompt-templates/code-analysis.md`
-- Uses `@**/*` for in CONTEXT field for comprehensive code context
+- **Read-only**: Analyzes code, does NOT modify files
+- **Template**: `~/.claude/workflows/cli-templates/prompts/analysis/01-trace-code-execution.txt`
+- **Output**: `.workflow/active/WFS-[id]/.chat/code-analysis-[timestamp].md` (or `.scratchpad/` if no session)

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

@@ -0,0 +1,126 @@
+---
+name: document-analysis
+description: Read-only technical document/paper analysis using Gemini/Qwen/Codex with systematic comprehension template for insights extraction
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] document path or topic"
+allowed-tools: SlashCommand(*), Bash(*), Task(*), Read(*)
+---
+
+# CLI Mode: Document Analysis (/cli:mode:document-analysis)
+
+## Purpose
+
+Systematic analysis of technical documents, research papers, API documentation, and technical specifications.
+
+**Tool Selection**:
+- **gemini** (default) - Best for document comprehension and structure analysis
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for complex technical documents
+
+**Key Feature**: `--cd` flag for directory-scoped document discovery
+
+## Parameters
+
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--enhance` - Enhance analysis target with `/enhance-prompt`
+- `--cd "path"` - Target directory for document search
+- `<document-path-or-topic>` (Required) - File path or topic description
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+/cli:mode:document-analysis "README.md"
+/cli:mode:document-analysis --tool gemini "analyze API documentation"
+```
+
+**Qwen** (Fallback):
+```bash
+/cli:mode:document-analysis --tool qwen "docs/architecture.md"
+```
+
+**Codex** (Alternative):
+```bash
+/cli:mode:document-analysis --tool codex "research paper in docs/"
+```
+
+## Execution Flow
+
+Uses **cli-execution-agent** for automated document analysis:
+
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Systematic document comprehension and insights extraction",
+  prompt=`
+    Task: ${document_path_or_topic}
+    Mode: document-analysis
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
+    Template: ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-technical-document.txt
+
+    Execute systematic document analysis:
+
+    1. Document Discovery:
+       - Locate target document(s) via path or topic keywords
+       - Identify document type (README, API docs, research paper, spec, tutorial)
+       - Detect document format (Markdown, PDF, plain text, reStructuredText)
+       - Discover related documents (references, appendices, examples)
+       - Use MCP/ripgrep for comprehensive file discovery
+
+    2. Pre-Analysis Planning (Required):
+       - Determine document structure (sections, hierarchy, flow)
+       - Identify key components (abstract, methodology, implementation details)
+       - Map dependencies and cross-references
+       - Assess document scope and complexity
+       - Plan analysis approach based on document type
+
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for complex docs)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @{document_paths} + @CLAUDE.md + related files
+       - Mode: analysis (read-only)
+       - Template: analysis/02-analyze-technical-document.txt
+
+    4. Analysis Execution:
+       - Apply 6-field template structure (PURPOSE, TASK, MODE, CONTEXT, EXPECTED, RULES)
+       - Execute multi-phase analysis protocol with pre-planning
+       - Perform self-critique before final output
+       - Generate structured report with evidence-based insights
+
+    5. Output Generation:
+       - Comprehensive document analysis report
+       - Structured insights with section references
+       - Critical assessment with evidence
+       - Actionable recommendations
+       - Save to .workflow/active/WFS-[id]/.chat/doc-analysis-[timestamp].md (or .scratchpad/)
+  `
+)
+```
+
+## Core Rules
+
+- **Read-only**: Analyzes documents, does NOT modify files
+- **Evidence-based**: All claims must reference specific sections/pages
+- **Pre-planning**: Requires analysis approach planning before execution
+- **Precise language**: Direct, accurate wording - no persuasive embellishment
+- **Output**: `.workflow/active/WFS-[id]/.chat/doc-analysis-[timestamp].md` (or `.scratchpad/` if no session)
+
+## Document Types Supported
+
+| Type | Focus Areas | Key Outputs |
+|------|-------------|-------------|
+| README | Purpose, setup, usage | Integration steps, quick-start guide |
+| API Documentation | Endpoints, parameters, responses | API usage patterns, integration points |
+| Research Paper | Methodology, findings, validity | Applicable techniques, implementation feasibility |
+| Specification | Requirements, standards, constraints | Compliance checklist, implementation requirements |
+| Tutorial | Learning path, examples, exercises | Key concepts, practical applications |
+| Architecture Docs | System design, components, patterns | Design decisions, integration points, trade-offs |
+
+## Best Practices
+
+1. **Scope Definition**: Clearly define what aspects to analyze before starting
+2. **Layered Reading**: Structure/Overview → Details → Critical Analysis → Synthesis
+3. **Evidence Trail**: Track section references for all extracted information
+4. **Gap Identification**: Note missing information or unclear sections explicitly
+5. **Actionable Output**: Focus on insights that inform decisions or actions

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

@@ -1,7 +1,7 @@
 ---
 name: plan
-description: Project planning and architecture analysis using CLI tools
-argument-hint: "[--agent] [--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
+description: Read-only architecture planning using Gemini/Qwen/Codex with strategic planning template for modification plans and impact analysis
+argument-hint: "[--tool codex|gemini|qwen] [--enhance] [--cd path] topic"
 allowed-tools: SlashCommand(*), Bash(*), Task(*)
 ---
 
@@ -9,159 +9,85 @@ allowed-tools: SlashCommand(*), Bash(*), Task(*)
 
 ## Purpose
 
-Comprehensive planning and architecture analysis with strategic planning template (`~/.claude/prompt-templates/plan.md`).
+Strategic software architecture planning template (`~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`).
 
-**Supported Tools**: codex, gemini (default), qwen
-**Key Feature**: `--cd` flag for directory-scoped planning
+**Tool Selection**:
+- **gemini** (default) - Best for architecture planning
+- **qwen** - Fallback when Gemini unavailable
+- **codex** - Alternative for implementation planning
 
 ## Parameters
 
-- `--agent` - Use cli-execution-agent for automated context discovery (5-phase intelligent mode)
-- `--tool <codex|gemini|qwen>` - Tool selection (default: gemini, ignored in agent mode)
-- `--enhance` - Enhance topic with `/enhance-prompt` first
+- `--tool <gemini|qwen|codex>` - Tool selection (default: gemini)
+- `--enhance` - Enhance task with `/enhance-prompt`
 - `--cd "path"` - Target directory for focused planning
-- `<topic>` (Required) - Planning topic or architectural question
+- `<planning-task>` (Required) - Architecture planning task or modification requirements
+
+## Tool Usage
+
+**Gemini** (Primary):
+```bash
+--tool gemini  # or omit (default)
+```
+
+**Qwen** (Fallback):
+```bash
+--tool qwen
+```
+
+**Codex** (Alternative):
+```bash
+--tool codex
+```
 
 ## Execution Flow
 
-### Standard Mode (Default)
+Uses **cli-execution-agent** (default) for automated planning:
 
-1. **Parse tool selection**: Extract `--tool` flag (default: gemini)
-2. **If `--enhance` flag present**: Execute `/enhance-prompt "[topic]"` first
-3. Parse topic (original or enhanced)
-4. Detect target directory (from `--cd` or auto-infer)
-5. Build command for selected tool with planning template
-6. Execute analysis (read-only, no code modification)
-7. Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-
-### Agent Mode (`--agent` flag)
-
-Delegate planning to `cli-execution-agent` for intelligent strategic planning with automated architecture discovery.
-
-**Agent invocation**:
 ```javascript
 Task(
   subagent_type="cli-execution-agent",
-  description="Create strategic plan with automated architecture discovery",
+  description="Architecture planning with impact analysis",
   prompt=`
-    Task: ${planning_topic}
-    Mode: plan (strategic planning)
-    Tool Preference: ${tool_flag || 'auto-select'}
-    ${cd_flag ? `Directory Scope: ${cd_path}` : ''}
-    Template: plan
+    Task: ${planning_task}
+    Mode: plan
+    Tool: ${tool_flag || 'gemini'}
+    Directory: ${cd_path || '.'}
+    Enhance: ${enhance_flag}
+    Template: ~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt
 
-    Agent will autonomously:
-    - Discover project structure and existing architecture
-    - Build planning prompt with plan template
-    - Execute strategic planning analysis
-    - Generate implementation roadmap and save
+    Execute strategic architecture planning:
+
+    1. Context Discovery:
+       - Analyze current architecture structure
+       - Identify affected components and modules
+       - Map dependencies and integration points
+       - Assess modification impacts (scope, complexity, risks)
+
+    2. Planning Analysis:
+       - Apply strategic planning template
+       - Generate modification plan with phases
+       - Document architectural decisions and rationale
+       - Identify potential conflicts and mitigation strategies
+
+    3. CLI Command Construction:
+       - Tool: ${tool_flag || 'gemini'} (qwen fallback, codex for implementation guidance)
+       - Directory: cd ${cd_path || '.'} &&
+       - Context: @**/* (full architecture context)
+       - Mode: analysis (read-only, no code generation)
+       - Template: planning/01-plan-architecture-design.txt
+
+    4. Output Generation:
+       - Strategic modification plan
+       - Impact analysis and risk assessment
+       - Implementation roadmap
+       - Save to .workflow/active/WFS-[id]/.chat/plan-[timestamp].md (or .scratchpad/)
   `
 )
 ```
 
-The agent handles all phases internally.
-
 ## Core Rules
 
-1. **Analysis Only**: This command provides planning recommendations and insights - it does NOT modify code
-2. **Enhance First (if flagged)**: Execute `/enhance-prompt` before planning
-3. **Directory Context**: Use `cd` when `--cd` provided or auto-detected
-4. **Template Required**: Always use planning template
-5. **Session Output**: Save analysis results to session chat
-
-## Planning Capabilities (via Template)
-
-- Strategic architecture insights and recommendations
-- Implementation roadmaps and suggestions
-- Key technical decisions analysis
-- Risk assessment
-- Resource planning
-
-## Command Template
-
-```bash
-cd [directory] && gemini -p "
-PURPOSE: [planning goal from topic]
-TASK: Comprehensive planning and architecture analysis
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md [entire codebase in directory]
-EXPECTED: Strategic insights, implementation recommendations, key decisions
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on [topic area]
-"
-```
-
-## Examples
-
-**Basic Planning Analysis (Standard Mode)**:
-```bash
-/cli:mode:plan "design user dashboard architecture"
-# Executes: Gemini with planning template
-# Returns: Architecture recommendations, component design, roadmap
-```
-
-**Intelligent Planning (Agent Mode)**:
-```bash
-/cli:mode:plan --agent "design microservices architecture for payment system"
-# Phase 1: Classifies as architectural planning, keywords ['microservices', 'payment', 'architecture']
-# Phase 2: MCP discovers existing services, payment flows, integration patterns
-# Phase 3: Builds planning prompt with plan template + current architecture context
-# Phase 4: Executes Gemini with comprehensive project understanding
-# Phase 5: Saves planning document with implementation roadmap and migration strategy
-# Returns: Strategic architecture plan + implementation roadmap + risk assessment
-```
-
-**Standard Template Example**:
-```bash
-cd . && gemini -p "
-PURPOSE: Design user dashboard architecture
-TASK: Plan dashboard component structure and data flow
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md
-EXPECTED: Architecture recommendations, component design, data flow diagram
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Focus on scalability
-"
-```
-
-**Directory-Specific Planning**:
-```bash
-cd src/api && gemini -p "
-PURPOSE: Plan API refactoring strategy
-TASK: Analyze current API structure and recommend improvements
-MODE: analysis
-CONTEXT: @CLAUDE.md @**/*CLAUDE.md
-EXPECTED: Refactoring roadmap, breaking change analysis, migration plan
-RULES: $(cat ~/.claude/prompt-templates/plan.md) | Maintain backward compatibility
-"
-```
-
-## Planning Workflow
-
-```bash
-# 1. Discover project structure
-~/.claude/scripts/get_modules_by_depth.sh
-find . -name "*.ts" -type f
-
-# 2. Gather existing architecture info
-rg "architecture|design" --files-with-matches
-
-# 3. Execute planning analysis (analysis only, no code changes)
-/cli:mode:plan "topic for strategic planning"
-```
-
-## Output Routing
-
-**Output Destination Logic**:
-- **Active session exists AND planning is session-relevant**:
-  - Save to `.workflow/WFS-[id]/.chat/plan-[timestamp].md`
-- **No active session OR exploratory planning**:
-  - Save to `.workflow/.scratchpad/plan-[description]-[timestamp].md`
-
-**Examples**:
-- During active session `WFS-dashboard`, planning dashboard architecture → `.chat/plan-20250105-143022.md`
-- No session, exploring new feature idea → `.scratchpad/plan-feature-idea-20250105-143045.md`
-
-## Notes
-
-- Command templates and file patterns: see intelligent-tools-strategy.md (loaded in memory)
-- Template path: `~/.claude/prompt-templates/plan.md`
-- Uses `@**/*` for in CONTEXT field for comprehensive project context
+- **Read-only**: Creates modification plans, does NOT generate code
+- **Template**: `~/.claude/workflows/cli-templates/prompts/planning/01-plan-architecture-design.txt`
+- **Output**: `.workflow/active/WFS-[id]/.chat/plan-[timestamp].md` (or `.scratchpad/` if no session)

.claude/commands/enhance-prompt.md

@@ -1,37 +1,22 @@
 ---
 name: enhance-prompt
-description: Context-aware prompt enhancement using session memory and codebase analysis
+description: Enhanced prompt transformation using session memory and intent analysis with --enhance flag detection
 argument-hint: "user input to enhance"
 ---
 
 ## Overview
 
-Systematically enhances user prompts by combining session memory context with codebase patterns, translating ambiguous requests into actionable specifications.
+Systematically enhances user prompts by leveraging session memory context and intent analysis, translating ambiguous requests into actionable specifications.
 
 ## Core Protocol
 
 **Enhancement Pipeline:**
-`Intent Translation` → `Context Integration` → `Gemini Analysis (if needed)` → `Structured Output`
+`Intent Translation` → `Context Integration` → `Structured Output`
 
 **Context Sources:**
 - Session memory (conversation history, previous analysis)
-- Codebase patterns (via Gemini when triggered)
 - Implicit technical requirements
-
-## Gemini Trigger Logic
-
-```pseudo
-FUNCTION should_use_gemini(user_prompt):
-  critical_keywords = ["refactor", "migrate", "redesign", "auth", "payment", "security"]
-
-  RETURN (
-    prompt_affects_multiple_modules(user_prompt, threshold=3) OR
-    any_keyword_in_prompt(critical_keywords, user_prompt)
-  )
-END
-```
-
-**Gemini Integration:** ~/.claude/workflows/intelligent-tools-strategy.md
+- User intent patterns
 
 ## Enhancement Rules
 
@@ -47,22 +32,18 @@ END
 
 ### Context Integration Strategy
 
-**Session Memory First:**
+**Session Memory:**
 - Reference recent conversation context
 - Reuse previously identified patterns
 - Build on established understanding
-
-**Codebase Analysis (via Gemini):**
-- Only when complexity requires it
-- Focus on integration points
-- Identify existing patterns
+- Infer technical requirements from discussion
 
 **Example:**
 ```bash
 # User: "add login"
 # Session Memory: Previous auth discussion, JWT mentioned
 # Inferred: JWT-based auth, integrate with existing session management
-# Gemini (if multi-module): Analyze AuthService patterns, middleware structure
+# Action: Implement JWT authentication with session persistence
 ```
 
 ## Output Structure
@@ -76,7 +57,7 @@ ATTENTION: [Critical constraints]
 
 ### Output Examples
 
-**Simple (no Gemini):**
+**Example 1:**
 ```bash
 # Input: "fix login button"
 INTENT: Debug non-functional login button
@@ -85,28 +66,28 @@ ACTION: Check event binding → verify state updates → test auth flow
 ATTENTION: Preserve existing OAuth integration
 ```
 
-**Complex (with Gemini):**
+**Example 2:**
 ```bash
 # Input: "refactor payment code"
 INTENT: Restructure payment module for maintainability
-CONTEXT: Session memory - PCI compliance requirements
-         Gemini - PaymentService → StripeAdapter pattern identified
-ACTION: Extract reusable validators → isolate payment gateway logic
+CONTEXT: Session memory - PCI compliance requirements, Stripe integration patterns
+ACTION: Extract reusable validators → isolate payment gateway logic → maintain adapter pattern
 ATTENTION: Zero behavior change, maintain PCI compliance, full test coverage
 ```
 
-## Automatic Triggers
+## Enhancement Triggers
 
 - Ambiguous language: "fix", "improve", "clean up"
-- Multi-module impact (>3 modules)
+- Vague requests requiring clarification
+- Complex technical requirements
 - Architecture changes
 - Critical systems: auth, payment, security
-- Complex refactoring
+- Multi-step refactoring
 
 ## Key Principles
 
-1. **Memory First**: Leverage session context before analysis
-2. **Minimal Gemini**: Only when complexity demands it
-3. **Context Reuse**: Build on previous understanding
-4. **Clear Output**: Structured, actionable specifications
+1. **Session Memory First**: Leverage conversation context and established understanding
+2. **Context Reuse**: Build on previous discussions and decisions
+3. **Clear Output**: Structured, actionable specifications
+4. **Intent Clarification**: Transform vague requests into specific technical goals
 5. **Avoid Duplication**: Reference existing context, don't repeat

.claude/commands/memory/code-map-memory.md

@@ -0,0 +1,745 @@
+---
+name: code-map-memory
+description: 3-phase orchestrator: parse feature keyword → cli-explore-agent analyzes (Deep Scan dual-source) → orchestrator generates Mermaid docs + SKILL package (skips phase 2 if exists)
+argument-hint: "\"feature-keyword\" [--regenerate] [--tool <gemini|qwen>]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
+---
+
+# Code Flow Mapping Generator
+
+## Overview
+
+**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates code flow analysis to specialized cli-explore-agent. Orchestrator transforms agent's JSON analysis into Mermaid documentation.
+
+**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
+
+**Execution Paths**:
+- **Full Path**: All 3 phases (no existing codemap OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 3 (existing codemap found AND no `--regenerate` flag)
+- **Phase 3 Always Executes**: SKILL index is always generated or updated
+
+**Agent Responsibility** (cli-explore-agent):
+- Deep code flow analysis using dual-source strategy (Bash + Gemini CLI)
+- Returns structured JSON with architecture, functions, data flow, conditionals, patterns
+- NO file writing - analysis only
+
+**Orchestrator Responsibility**:
+- Provides feature keyword and analysis scope to agent
+- Transforms agent's JSON into Mermaid-enriched markdown documentation
+- Writes all files (5 docs + metadata.json + SKILL.md)
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **Feature-Specific SKILL**: Each feature creates independent `.claude/skills/codemap-{feature}/` package
+3. **Specialized Agent**: Phase 2a uses cli-explore-agent for professional code analysis (Deep Scan mode)
+4. **Orchestrator Documentation**: Phase 2b transforms agent JSON into Mermaid markdown files
+5. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+6. **No User Prompts**: Never ask user questions or wait for input between phases
+7. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+8. **Multi-Level Detail**: Generate 4 levels: architecture → function → data → conditional
+
+---
+
+## 3-Phase Execution
+
+### Phase 1: Parse Feature Keyword & Check Existing
+
+**Goal**: Normalize feature keyword, check existing codemap, prepare for analysis
+
+**Step 1: Parse Feature Keyword**
+```bash
+# Get feature keyword from argument
+FEATURE_KEYWORD="$1"
+
+# Normalize: lowercase, spaces to hyphens
+normalized_feature=$(echo "$FEATURE_KEYWORD" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr '_' '-')
+
+# Example: "User Authentication" → "user-authentication"
+# Example: "支付处理" → "支付处理" (keep non-ASCII)
+```
+
+**Step 2: Set Tool Preference**
+```bash
+# Default to gemini unless --tool specified
+TOOL="${tool_flag:-gemini}"
+```
+
+**Step 3: Check Existing Codemap**
+```bash
+# Define codemap directory
+CODEMAP_DIR=".claude/skills/codemap-${normalized_feature}"
+
+# Check if codemap exists
+bash(test -d "$CODEMAP_DIR" && echo "exists" || echo "not_exists")
+
+# Count existing files
+bash(find "$CODEMAP_DIR" -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Step 4: Skip Decision**
+```javascript
+if (existing_files > 0 && !regenerate_flag) {
+  SKIP_GENERATION = true
+  message = "Codemap already exists, skipping Phase 2. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  bash(rm -rf "$CODEMAP_DIR")
+  SKIP_GENERATION = false
+  message = "Regenerating codemap from scratch."
+} else {
+  SKIP_GENERATION = false
+  message = "No existing codemap found, generating new code flow analysis."
+}
+```
+
+**Output Variables**:
+- `FEATURE_KEYWORD`: Original feature keyword
+- `normalized_feature`: Normalized feature name for directory
+- `CODEMAP_DIR`: `.claude/skills/codemap-{feature}`
+- `TOOL`: CLI tool to use (gemini or qwen)
+- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
+
+**TodoWrite**:
+- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
+- If not skipping: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Code Flow Analysis & Documentation Generation
+
+**Skip Condition**: Skipped if `SKIP_GENERATION = true`
+
+**Goal**: Use cli-explore-agent for professional code analysis, then orchestrator generates Mermaid documentation
+
+**Architecture**: Phase 2a (Agent Analysis) → Phase 2b (Orchestrator Documentation)
+
+---
+
+#### Phase 2a: cli-explore-agent Analysis
+
+**Purpose**: Leverage specialized cli-explore-agent for deep code flow analysis
+
+**Agent Task Specification**:
+
+```
+Task(
+  subagent_type: "cli-explore-agent",
+  description: "Analyze code flow: {FEATURE_KEYWORD}",
+  prompt: "
+Perform Deep Scan analysis for feature: {FEATURE_KEYWORD}
+
+**Analysis Mode**: deep-scan (Dual-source: Bash structural scan + Gemini semantic analysis)
+
+**Analysis Objectives**:
+1. **Module Architecture**: Identify high-level module organization, interactions, and entry points
+2. **Function Call Chains**: Trace execution paths, call sequences, and parameter flows
+3. **Data Transformations**: Map data structure changes and transformation stages
+4. **Conditional Paths**: Document decision trees, branches, and error handling strategies
+5. **Design Patterns**: Discover architectural patterns and extract design intent
+
+**Scope**:
+- Feature: {FEATURE_KEYWORD}
+- CLI Tool: {TOOL} (gemini-2.5-pro or qwen coder-model)
+- File Discovery: MCP Code Index (preferred) + rg fallback
+- Target: 5-15 most relevant files
+
+**Expected Output Format**:
+Return comprehensive analysis as structured JSON:
+{
+  \"feature\": \"{FEATURE_KEYWORD}\",
+  \"analysis_metadata\": {
+    \"tool_used\": \"gemini|qwen\",
+    \"timestamp\": \"ISO_TIMESTAMP\",
+    \"analysis_mode\": \"deep-scan\"
+  },
+  \"files_analyzed\": [
+    {\"file\": \"path/to/file.ts\", \"relevance\": \"high|medium|low\", \"role\": \"brief description\"}
+  ],
+  \"architecture\": {
+    \"overview\": \"High-level description\",
+    \"modules\": [
+      {\"name\": \"ModuleName\", \"file\": \"file:line\", \"responsibility\": \"description\", \"dependencies\": [...]}
+    ],
+    \"interactions\": [
+      {\"from\": \"ModuleA\", \"to\": \"ModuleB\", \"type\": \"import|call|data-flow\", \"description\": \"...\"}
+    ],
+    \"entry_points\": [
+      {\"function\": \"main\", \"file\": \"file:line\", \"description\": \"...\"}
+    ]
+  },
+  \"function_calls\": {
+    \"call_chains\": [
+      {
+        \"chain_id\": 1,
+        \"description\": \"User authentication flow\",
+        \"sequence\": [
+          {\"function\": \"login\", \"file\": \"file:line\", \"calls\": [\"validateCredentials\", \"createSession\"]}
+        ]
+      }
+    ],
+    \"sequences\": [
+      {\"from\": \"Client\", \"to\": \"AuthService\", \"method\": \"login(username, password)\", \"returns\": \"Session\"}
+    ]
+  },
+  \"data_flow\": {
+    \"structures\": [
+      {\"name\": \"UserData\", \"stage\": \"input\", \"shape\": {\"username\": \"string\", \"password\": \"string\"}}
+    ],
+    \"transformations\": [
+      {\"from\": \"RawInput\", \"to\": \"ValidatedData\", \"transformer\": \"validateUser\", \"file\": \"file:line\"}
+    ]
+  },
+  \"conditional_logic\": {
+    \"branches\": [
+      {\"condition\": \"isAuthenticated\", \"file\": \"file:line\", \"true_path\": \"...\", \"false_path\": \"...\"}
+    ],
+    \"error_handling\": [
+      {\"error_type\": \"AuthenticationError\", \"handler\": \"handleAuthError\", \"file\": \"file:line\", \"recovery\": \"retry|fail\"}
+    ]
+  },
+  \"design_patterns\": [
+    {\"pattern\": \"Repository Pattern\", \"location\": \"src/repositories\", \"description\": \"...\"}
+  ],
+  \"recommendations\": [
+    \"Consider extracting authentication logic into separate module\",
+    \"Add error recovery for network failures\"
+  ]
+}
+
+**Critical Requirements**:
+- Use Deep Scan mode: Bash (Phase 1 - precise locations) + Gemini CLI (Phase 2 - semantic understanding) + Synthesis (Phase 3 - merge with attribution)
+- Focus exclusively on {FEATURE_KEYWORD} feature flow
+- Include file:line references for ALL findings
+- Extract design intent from code structure and comments
+- NO FILE WRITING - return JSON analysis only
+- Handle tool failures gracefully (Gemini → Qwen fallback, MCP → rg fallback)
+  "
+)
+```
+
+**Agent Output**: JSON analysis result with architecture, functions, data flow, conditionals, and patterns
+
+---
+
+#### Phase 2b: Orchestrator Documentation Generation
+
+**Purpose**: Transform cli-explore-agent JSON into Mermaid-enriched documentation
+
+**Input**: Agent's JSON analysis result
+
+**Process**:
+
+1. **Parse Agent Analysis**:
+   ```javascript
+   const analysis = JSON.parse(agentResult)
+   const { feature, files_analyzed, architecture, function_calls, data_flow, conditional_logic, design_patterns } = analysis
+   ```
+
+2. **Generate Mermaid Diagrams from Structured Data**:
+
+   **a) architecture-flow.md** (~3K tokens):
+   ```javascript
+   // Convert architecture.modules + architecture.interactions → Mermaid graph TD
+   const architectureMermaid = `
+   graph TD
+   ${architecture.modules.map(m => `    ${m.name}[${m.name}]`).join('\n')}
+   ${architecture.interactions.map(i => `    ${i.from} -->|${i.type}| ${i.to}`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/architecture-flow.md`,
+     content: `---
+feature: ${feature}
+level: architecture
+detail: high-level module interactions
+---
+# Architecture Flow: ${feature}
+
+## Overview
+${architecture.overview}
+
+## Module Architecture
+${architecture.modules.map(m => `### ${m.name}\n- **File**: ${m.file}\n- **Role**: ${m.responsibility}\n- **Dependencies**: ${m.dependencies.join(', ')}`).join('\n\n')}
+
+## Flow Diagram
+\`\`\`mermaid
+${architectureMermaid}
+\`\`\`
+
+## Key Interactions
+${architecture.interactions.map(i => `- **${i.from} → ${i.to}**: ${i.description}`).join('\n')}
+
+## Entry Points
+${architecture.entry_points.map(e => `- **${e.function}** (${e.file}): ${e.description}`).join('\n')}
+`
+   })
+   ```
+
+   **b) function-calls.md** (~5K tokens):
+   ```javascript
+   // Convert function_calls.sequences → Mermaid sequenceDiagram
+   const sequenceMermaid = `
+   sequenceDiagram
+   ${function_calls.sequences.map(s => `    ${s.from}->>${s.to}: ${s.method}`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/function-calls.md`,
+     content: `---
+feature: ${feature}
+level: function
+detail: function-level call sequences
+---
+# Function Call Chains: ${feature}
+
+## Call Sequence Diagram
+\`\`\`mermaid
+${sequenceMermaid}
+\`\`\`
+
+## Detailed Call Chains
+${function_calls.call_chains.map(chain => `
+### Chain ${chain.chain_id}: ${chain.description}
+${chain.sequence.map(fn => `- **${fn.function}** (${fn.file})\n  - Calls: ${fn.calls.join(', ')}`).join('\n')}
+`).join('\n')}
+
+## Parameters & Returns
+${function_calls.sequences.map(s => `- **${s.method}** → Returns: ${s.returns || 'void'}`).join('\n')}
+`
+   })
+   ```
+
+   **c) data-flow.md** (~4K tokens):
+   ```javascript
+   // Convert data_flow.transformations → Mermaid flowchart LR
+   const dataFlowMermaid = `
+   flowchart LR
+   ${data_flow.transformations.map((t, i) => `    Stage${i}[${t.from}] -->|${t.transformer}| Stage${i+1}[${t.to}]`).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/data-flow.md`,
+     content: `---
+feature: ${feature}
+level: data
+detail: data structure transformations
+---
+# Data Flow: ${feature}
+
+## Data Transformation Diagram
+\`\`\`mermaid
+${dataFlowMermaid}
+\`\`\`
+
+## Data Structures
+${data_flow.structures.map(s => `### ${s.name} (${s.stage})\n\`\`\`json\n${JSON.stringify(s.shape, null, 2)}\n\`\`\``).join('\n\n')}
+
+## Transformations
+${data_flow.transformations.map(t => `- **${t.from} → ${t.to}** via \`${t.transformer}\` (${t.file})`).join('\n')}
+`
+   })
+   ```
+
+   **d) conditional-paths.md** (~4K tokens):
+   ```javascript
+   // Convert conditional_logic.branches → Mermaid flowchart TD
+   const conditionalMermaid = `
+   flowchart TD
+       Start[Entry Point]
+   ${conditional_logic.branches.map((b, i) => `
+       Start --> Check${i}{${b.condition}}
+       Check${i} -->|Yes| Path${i}A[${b.true_path}]
+       Check${i} -->|No| Path${i}B[${b.false_path}]
+   `).join('\n')}
+   `
+
+   Write({
+     file_path: `${CODEMAP_DIR}/conditional-paths.md`,
+     content: `---
+feature: ${feature}
+level: conditional
+detail: decision trees and error paths
+---
+# Conditional Paths: ${feature}
+
+## Decision Tree
+\`\`\`mermaid
+${conditionalMermaid}
+\`\`\`
+
+## Branch Conditions
+${conditional_logic.branches.map(b => `- **${b.condition}** (${b.file})\n  - True: ${b.true_path}\n  - False: ${b.false_path}`).join('\n')}
+
+## Error Handling
+${conditional_logic.error_handling.map(e => `- **${e.error_type}**: Handler \`${e.handler}\` (${e.file}) - Recovery: ${e.recovery}`).join('\n')}
+`
+   })
+   ```
+
+   **e) complete-flow.md** (~8K tokens):
+   ```javascript
+   // Integrate all Mermaid diagrams
+   Write({
+     file_path: `${CODEMAP_DIR}/complete-flow.md`,
+     content: `---
+feature: ${feature}
+level: complete
+detail: integrated multi-level view
+---
+# Complete Flow: ${feature}
+
+## Integrated Flow Diagram
+\`\`\`mermaid
+graph TB
+    subgraph Architecture
+    ${architecture.modules.map(m => `    ${m.name}[${m.name}]`).join('\n')}
+    end
+
+    subgraph "Function Calls"
+    ${function_calls.call_chains[0]?.sequence.map(fn => `    ${fn.function}`).join('\n') || ''}
+    end
+
+    subgraph "Data Flow"
+    ${data_flow.structures.map(s => `    ${s.name}[${s.name}]`).join('\n')}
+    end
+\`\`\`
+
+## Complete Trace
+[Comprehensive end-to-end documentation combining all analysis layers]
+
+## Design Patterns Identified
+${design_patterns.map(p => `- **${p.pattern}** in ${p.location}: ${p.description}`).join('\n')}
+
+## Recommendations
+${analysis.recommendations.map(r => `- ${r}`).join('\n')}
+
+## Cross-References
+- [Architecture Flow](./architecture-flow.md) - High-level module structure
+- [Function Calls](./function-calls.md) - Detailed call chains
+- [Data Flow](./data-flow.md) - Data transformation stages
+- [Conditional Paths](./conditional-paths.md) - Decision trees and error handling
+`
+   })
+   ```
+
+3. **Write metadata.json**:
+   ```javascript
+   Write({
+     file_path: `${CODEMAP_DIR}/metadata.json`,
+     content: JSON.stringify({
+       feature: feature,
+       normalized_name: normalized_feature,
+       generated_at: new Date().toISOString(),
+       tool_used: analysis.analysis_metadata.tool_used,
+       files_analyzed: files_analyzed.map(f => f.file),
+       analysis_summary: {
+         total_files: files_analyzed.length,
+         modules_traced: architecture.modules.length,
+         functions_traced: function_calls.call_chains.reduce((sum, c) => sum + c.sequence.length, 0),
+         patterns_discovered: design_patterns.length
+       }
+     }, null, 2)
+   })
+   ```
+
+4. **Report Phase 2 Completion**:
+   ```
+   Phase 2 Complete: Code flow analysis and documentation generated
+
+   - Agent Analysis: cli-explore-agent with {TOOL}
+   - Files Analyzed: {count}
+   - Documentation Generated: 5 markdown files + metadata.json
+   - Location: {CODEMAP_DIR}
+   ```
+
+**Completion Criteria**:
+- cli-explore-agent task completed successfully with JSON result
+- 5 documentation files written with valid Mermaid diagrams
+- metadata.json written with analysis summary
+- All files properly formatted and cross-referenced
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Generate SKILL.md Index
+
+**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
+
+**Goal**: Read generated flow documentation and create SKILL.md index with progressive loading
+
+**Steps**:
+
+1. **Verify Generated Files**:
+   ```bash
+   bash(find "{CODEMAP_DIR}" -name "*.md" -type f | sort)
+   ```
+
+2. **Read metadata.json**:
+   ```javascript
+   Read({CODEMAP_DIR}/metadata.json)
+   // Extract: feature, normalized_name, files_analyzed, analysis_summary
+   ```
+
+3. **Read File Headers** (optional, first 30 lines):
+   ```javascript
+   Read({CODEMAP_DIR}/architecture-flow.md, limit: 30)
+   Read({CODEMAP_DIR}/function-calls.md, limit: 30)
+   // Extract overview and diagram counts
+   ```
+
+4. **Generate SKILL.md Index**:
+
+   Template structure:
+   ```yaml
+   ---
+   name: codemap-{normalized_feature}
+   description: Code flow mapping for {FEATURE_KEYWORD} feature (located at {project_path}). Load this SKILL when analyzing, tracing, or understanding {FEATURE_KEYWORD} execution flow, especially when no relevant context exists in memory.
+   version: 1.0.0
+   generated_at: {ISO_TIMESTAMP}
+   ---
+   # Code Flow Map: {FEATURE_KEYWORD}
+
+   ## Feature: `{FEATURE_KEYWORD}`
+
+   **Analysis Date**: {DATE}
+   **Tool Used**: {TOOL}
+   **Files Analyzed**: {COUNT}
+
+   ## Progressive Loading
+
+   ### Level 0: Quick Overview (~2K tokens)
+   - [Architecture Flow](./architecture-flow.md) - High-level module interactions
+
+   ### Level 1: Core Flows (~10K tokens)
+   - [Architecture Flow](./architecture-flow.md) - Module architecture
+   - [Function Calls](./function-calls.md) - Function call chains
+
+   ### Level 2: Complete Analysis (~20K tokens)
+   - [Architecture Flow](./architecture-flow.md)
+   - [Function Calls](./function-calls.md)
+   - [Data Flow](./data-flow.md) - Data transformations
+
+   ### Level 3: Deep Dive (~30K tokens)
+   - [Architecture Flow](./architecture-flow.md)
+   - [Function Calls](./function-calls.md)
+   - [Data Flow](./data-flow.md)
+   - [Conditional Paths](./conditional-paths.md) - Branches and error handling
+   - [Complete Flow](./complete-flow.md) - Integrated comprehensive view
+
+   ## Usage
+
+   Load this SKILL package when:
+   - Analyzing {FEATURE_KEYWORD} implementation
+   - Tracing execution flow for debugging
+   - Understanding code dependencies
+   - Planning refactoring or enhancements
+
+   ## Analysis Summary
+
+   - **Modules Traced**: {modules_traced}
+   - **Functions Traced**: {functions_traced}
+   - **Files Analyzed**: {total_files}
+
+   ## Mermaid Diagrams Included
+
+   - Architecture flow diagram (graph TD)
+   - Function call sequence diagram (sequenceDiagram)
+   - Data transformation flowchart (flowchart LR)
+   - Conditional decision tree (flowchart TD)
+   - Complete integrated diagram (graph TB)
+   ```
+
+5. **Write SKILL.md**:
+   ```javascript
+   Write({
+     file_path: `{CODEMAP_DIR}/SKILL.md`,
+     content: generatedIndexMarkdown
+   })
+   ```
+
+**Completion Criteria**:
+- SKILL.md index written
+- All documentation files verified
+- Progressive loading levels (0-3) properly structured
+- Mermaid diagram references included
+
+**TodoWrite**: Mark phase 3 completed
+
+**Final Report**:
+```
+Code Flow Mapping Complete
+
+Feature: {FEATURE_KEYWORD}
+Location: .claude/skills/codemap-{normalized_feature}/
+
+Files Generated:
+- SKILL.md (index)
+- architecture-flow.md (with Mermaid diagram)
+- function-calls.md (with Mermaid sequence diagram)
+- data-flow.md (with Mermaid flowchart)
+- conditional-paths.md (with Mermaid decision tree)
+- complete-flow.md (with integrated Mermaid diagram)
+- metadata.json
+
+Analysis:
+- Files analyzed: {count}
+- Modules traced: {count}
+- Functions traced: {count}
+
+Usage: Skill(command: "codemap-{normalized_feature}")
+```
+
+---
+
+## Implementation Details
+
+### TodoWrite Patterns
+
+**Initialization** (Before Phase 1):
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "in_progress", "activeForm": "Parsing feature keyword"},
+  {"content": "Agent analyzes code flow and generates files", "status": "pending", "activeForm": "Analyzing code flow"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
+]})
+```
+
+**Full Path** (SKIP_GENERATION = false):
+```javascript
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "in_progress", ...},
+  {"content": "Generate SKILL.md index", "status": "pending", ...}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "completed", ...}
+]})
+```
+
+**Skip Path** (SKIP_GENERATION = true):
+```javascript
+// After Phase 1 (skip Phase 2)
+TodoWrite({todos: [
+  {"content": "Parse feature keyword and check existing", "status": "completed", ...},
+  {"content": "Agent analyzes code flow and generates files", "status": "completed", ...},  // Skipped
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+```
+
+### Execution Flow
+
+**Full Path**:
+```
+User → TodoWrite Init → Phase 1 (parse) → Phase 2 (agent analyzes) → Phase 3 (write index) → Report
+```
+
+**Skip Path**:
+```
+User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
+```
+
+### Error Handling
+
+**Phase 1 Errors**:
+- Empty feature keyword: Report error, ask user to provide feature description
+- Invalid characters: Normalize and continue
+
+**Phase 2 Errors (Agent)**:
+- Agent task fails: Retry once, report if fails again
+- No files discovered: Warn user, ask for more specific feature keyword
+- CLI failures: Agent handles internally with retries
+- Invalid Mermaid syntax: Agent validates before writing
+
+**Phase 3 Errors**:
+- Write failures: Report which files failed
+- Missing files: Note in SKILL.md, suggest regeneration
+
+---
+
+## Parameters
+
+```bash
+/memory:code-map-memory "feature-keyword" [--regenerate] [--tool <gemini|qwen>]
+```
+
+**Arguments**:
+- **"feature-keyword"**: Feature or flow to analyze (required)
+  - Examples: `"user authentication"`, `"payment processing"`, `"数据导入流程"`
+  - Can be English, Chinese, or mixed
+  - Spaces and underscores normalized to hyphens
+- **--regenerate**: Force regenerate existing codemap (deletes and recreates)
+- **--tool**: CLI tool for analysis (default: gemini)
+  - `gemini`: Comprehensive flow analysis with gemini-2.5-pro
+  - `qwen`: Alternative with coder-model
+
+---
+
+## Examples
+
+**Generated File Structure** (for all examples):
+```
+.claude/skills/codemap-{feature}/
+├── SKILL.md                    # Index (Phase 3)
+├── architecture-flow.md        # Agent (Phase 2) - High-level flow
+├── function-calls.md           # Agent (Phase 2) - Function chains
+├── data-flow.md                # Agent (Phase 2) - Data transformations
+├── conditional-paths.md        # Agent (Phase 2) - Branches & errors
+├── complete-flow.md            # Agent (Phase 2) - Integrated view
+└── metadata.json               # Agent (Phase 2)
+```
+
+### Example 1: User Authentication Flow
+
+```bash
+/memory:code-map-memory "user authentication"
+```
+
+**Workflow**:
+1. Phase 1: Normalizes to "user-authentication", checks existing codemap
+2. Phase 2: Agent discovers auth-related files, executes CLI analysis, generates 5 flow docs with Mermaid
+3. Phase 3: Generates SKILL.md index with progressive loading
+
+**Output**: `.claude/skills/codemap-user-authentication/` with 6 files + metadata
+
+
+### Example 3: Regenerate with Qwen
+
+```bash
+/memory:code-map-memory "payment processing" --regenerate --tool qwen
+```
+
+**Workflow**:
+1. Phase 1: Deletes existing codemap due to --regenerate
+2. Phase 2: Agent uses qwen with coder-model for fresh analysis
+3. Phase 3: Generates updated SKILL.md
+
+---
+
+
+## Architecture
+
+```
+code-map-memory (orchestrator)
+  ├─ Phase 1: Parse & Check (bash commands, skip decision)
+  ├─ Phase 2: Code Analysis & Documentation (skippable)
+  │   ├─ Phase 2a: cli-explore-agent Analysis
+  │   │   └─ Deep Scan: Bash structural + Gemini semantic → JSON
+  │   └─ Phase 2b: Orchestrator Documentation
+  │       └─ Transform JSON → 5 Mermaid markdown files + metadata.json
+  └─ Phase 3: Write SKILL.md (index generation, always runs)
+
+Output: .claude/skills/codemap-{feature}/
+```

.claude/commands/memory/docs-full-cli.md

@@ -0,0 +1,471 @@
+---
+name: docs-full-cli
+description: Generate full project documentation using CLI execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
+argument-hint: "[path] [--tool <gemini|qwen|codex>]"
+---
+
+# Full Documentation Generation - CLI Mode (/memory:docs-full-cli)
+
+## Overview
+
+Orchestrates project-wide documentation generation using CLI-based execution with batched agents and automatic tool fallback.
+
+**Parameters**:
+- `path`: Target directory (default: current directory)
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+
+**Execution Flow**: Discovery → Plan Presentation → Execution → Verification
+
+## 3-Layer Architecture & Auto-Strategy Selection
+
+### Layer Definition & Strategy Assignment
+
+| Layer | Depth | Strategy | Purpose | Context Pattern |
+|-------|-------|----------|---------|----------------|
+| **Layer 3** (Deepest) | ≥3 | `full` | Generate docs for all subdirectories with code | `@**/*` (all files) |
+| **Layer 2** (Middle) | 1-2 | `single` | Current dir + child docs | `@*/API.md @*/README.md @*.{ts,tsx,js,...}` |
+| **Layer 1** (Top) | 0 | `single` | Current dir + child docs | `@*/API.md @*/README.md @*.{ts,tsx,js,...}` |
+
+**Generation Direction**: Layer 3 → Layer 2 → Layer 1 (bottom-up dependency flow)
+
+**Strategy Auto-Selection**: Strategies are automatically determined by directory depth - no user configuration needed.
+
+### Strategy Details
+
+#### Full Strategy (Layer 3 Only)
+- **Use Case**: Deepest directories with comprehensive file coverage
+- **Behavior**: Generates API.md + README.md for current directory AND subdirectories containing code
+- **Context**: All files in current directory tree (`@**/*`)
+- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
+
+
+#### Single Strategy (Layers 1-2)
+- **Use Case**: Upper layers that aggregate from existing documentation
+- **Behavior**: Generates API.md + README.md only in current directory
+- **Context**: Direct children docs + current directory code files
+- **Output**: `.workflow/docs/{project_name}/{path}/API.md` + `README.md`
+
+### Example Flow
+```
+src/auth/handlers/ (depth 3) → FULL STRATEGY
+  CONTEXT: @**/* (all files in handlers/ and subdirs)
+  GENERATES: .workflow/docs/project/src/auth/handlers/{API.md,README.md} + subdirs
+  ↓
+src/auth/ (depth 2) → SINGLE STRATEGY
+  CONTEXT: @*/API.md @*/README.md @*.ts (handlers docs + current code)
+  GENERATES: .workflow/docs/project/src/auth/{API.md,README.md} only
+  ↓
+src/ (depth 1) → SINGLE STRATEGY
+  CONTEXT: @*/API.md @*/README.md (auth docs, utils docs)
+  GENERATES: .workflow/docs/project/src/{API.md,README.md} only
+  ↓
+./ (depth 0) → SINGLE STRATEGY
+  CONTEXT: @*/API.md @*/README.md (src docs, tests docs)
+  GENERATES: .workflow/docs/project/{API.md,README.md} only
+```
+
+## Core Execution Rules
+
+1. **Analyze First**: Module discovery + folder classification before generation
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - **<20 modules**: Direct parallel execution (max 4 concurrent per layer)
+   - **≥20 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Layer Sequential**: Process layers 3→2→1 (bottom-up), parallel batches within layer
+6. **Safety Check**: Verify only docs files modified in .workflow/docs/
+7. **Layer-based Grouping**: Group modules by LAYER (not depth) for execution
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from generation script
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Execution Phases
+
+### Phase 1: Discovery & Analysis
+
+```javascript
+// Get project metadata
+Bash({command: "pwd && basename \"$(pwd)\" && git rev-parse --show-toplevel 2>/dev/null || pwd", run_in_background: false});
+
+// Get module structure with classification
+Bash({command: "~/.claude/scripts/get_modules_by_depth.sh list | ~/.claude/scripts/classify-folders.sh", run_in_background: false});
+
+// OR with path parameter
+Bash({command: "cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list | ~/.claude/scripts/classify-folders.sh", run_in_background: false});
+```
+
+**Parse output** `depth:N|path:<PATH>|type:<code|navigation>|...` to extract module paths, types, and count.
+
+**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack.
+
+### Phase 2: Plan Presentation
+
+**For <20 modules**:
+```
+Documentation Generation Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 7 modules
+  Execution: Direct parallel (< 20 modules threshold)
+  Project: myproject
+  Output: .workflow/docs/myproject/
+
+  Will generate docs for:
+  - ./core/interfaces (12 files, type: code) - depth 2 [Layer 2] - single strategy
+  - ./core (22 files, type: code) - depth 1 [Layer 2] - single strategy
+  - ./models (9 files, type: code) - depth 1 [Layer 2] - single strategy
+  - ./utils (12 files, type: navigation) - depth 1 [Layer 2] - single strategy
+  - . (5 files, type: code) - depth 0 [Layer 1] - single strategy
+
+  Documentation Strategy (Auto-Selected):
+  - Layer 2 (depth 1-2): API.md + README.md (current dir only, reference child docs)
+  - Layer 1 (depth 0): API.md + README.md (current dir only, reference child docs)
+
+  Output Structure:
+  - Code folders: API.md + README.md
+  - Navigation folders: README.md only
+
+  Auto-skipped: ./tests, __pycache__, node_modules (15 paths)
+  Execution order: Layer 2 → Layer 1
+  Estimated time: ~5-10 minutes
+
+  Confirm execution? (y/n)
+```
+
+**For ≥20 modules**:
+```
+Documentation Generation Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Total: 31 modules
+  Execution: Agent batch processing (4 modules/agent)
+  Project: myproject
+  Output: .workflow/docs/myproject/
+
+  Will generate docs for:
+  - ./src/features/auth (12 files, type: code) - depth 3 [Layer 3] - full strategy
+  - ./.claude/commands/cli (6 files, type: code) - depth 3 [Layer 3] - full strategy
+  - ./src/utils (8 files, type: code) - depth 2 [Layer 2] - single strategy
+  ...
+
+  Documentation Strategy (Auto-Selected):
+  - Layer 3 (depth ≥3): API.md + README.md (all subdirs with code)
+  - Layer 2 (depth 1-2): API.md + README.md (current dir only)
+  - Layer 1 (depth 0): API.md + README.md (current dir only)
+
+  Output Structure:
+  - Code folders: API.md + README.md
+  - Navigation folders: README.md only
+
+  Auto-skipped: ./tests, __pycache__, node_modules (15 paths)
+  Execution order: Layer 3 → Layer 2 → Layer 1
+
+  Agent allocation (by LAYER):
+  - Layer 3 (14 modules, depth ≥3): 4 agents [4, 4, 4, 2]
+  - Layer 2 (15 modules, depth 1-2): 4 agents [4, 4, 4, 3]
+  - Layer 1 (2 modules, depth 0): 1 agent [2]
+
+  Estimated time: ~15-25 minutes
+
+  Confirm execution? (y/n)
+```
+
+### Phase 3A: Direct Execution (<20 modules)
+
+**Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
+
+**CRITICAL**: All Bash commands use `run_in_background: false` for synchronous execution.
+
+```javascript
+let project_name = detect_project_name();
+
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+  let batches = batch_modules(modules_by_layer[layer], 4);
+
+  for (let batch of batches) {
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        let strategy = module.depth >= 3 ? "full" : "single";
+        for (let tool of tool_order) {
+          Bash({
+            command: `cd ${module.path} && ~/.claude/scripts/generate_module_docs.sh "${strategy}" "." "${project_name}" "${tool}"`,
+            run_in_background: false
+          });
+          if (bash_result.exit_code === 0) {
+            report(`✅ ${module.path} (Layer ${layer}) docs generated with ${tool}`);
+            return true;
+          }
+        }
+        report(`❌ FAILED: ${module.path} (Layer ${layer}) failed all tools`);
+        return false;
+      };
+    });
+    await Promise.all(parallel_tasks.map(task => task()));
+  }
+}
+```
+
+### Phase 3B: Agent Batch Execution (≥20 modules)
+
+**Strategy**: Batch modules into groups of 4, spawn memory-bridge agents per batch.
+
+```javascript
+// Group modules by LAYER and batch within each layer
+let modules_by_layer = group_by_layer(module_list);
+let tool_order = construct_tool_order(primary_tool);
+let project_name = detect_project_name();
+
+for (let layer of [3, 2, 1]) {
+  if (modules_by_layer[layer].length === 0) continue;
+
+  let batches = batch_modules(modules_by_layer[layer], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Generate docs for ${batch.length} modules in Layer ${layer}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, layer, project_name)
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);
+}
+```
+
+**Batch Worker Prompt Template**:
+```
+PURPOSE: Generate documentation for assigned modules with tool fallback
+
+TASK: Generate API.md + README.md for assigned modules using specified strategies.
+
+PROJECT: {{project_name}}
+OUTPUT: .workflow/docs/{{project_name}}/
+
+MODULES:
+{{module_path_1}} (strategy: {{strategy_1}}, type: {{folder_type_1}})
+{{module_path_2}} (strategy: {{strategy_2}}, type: {{folder_type_2}})
+...
+
+TOOLS (try in order): {{tool_1}}, {{tool_2}}, {{tool_3}}
+
+EXECUTION SCRIPT: ~/.claude/scripts/generate_module_docs.sh
+  - Accepts strategy parameter: full | single
+  - Accepts folder type detection: code | navigation
+  - Tool execution via direct CLI commands (gemini/qwen/codex)
+  - Output path: .workflow/docs/{{project_name}}/{module_path}/
+
+EXECUTION FLOW (for each module):
+  1. Tool fallback loop (exit on first success):
+     for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
+       Bash({
+         command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "{{strategy}}" "." "{{project_name}}" "${tool}"`,
+         run_in_background: false
+       })
+       exit_code=$?
+
+       if [ $exit_code -eq 0 ]; then
+         report "✅ {{module_path}} docs generated with $tool"
+         break
+       else
+         report "⚠️  {{module_path}} failed with $tool, trying next..."
+         continue
+       fi
+     done
+
+  2. Handle complete failure (all tools failed):
+     if [ $exit_code -ne 0 ]; then
+       report "❌ FAILED: {{module_path}} - all tools exhausted"
+       # Continue to next module (do not abort batch)
+     fi
+
+FOLDER TYPE HANDLING:
+  - code: Generate API.md + README.md
+  - navigation: Generate README.md only
+
+FAILURE HANDLING:
+  - Module-level isolation: One module's failure does not affect others
+  - Exit code detection: Non-zero exit code triggers next tool
+  - Exhaustion reporting: Log modules where all tools failed
+  - Batch continuation: Always process remaining modules
+
+REPORTING FORMAT:
+  Per-module status:
+    ✅ path/to/module docs generated with {tool}
+    ⚠️  path/to/module failed with {tool}, trying next...
+    ❌ FAILED: path/to/module - all tools exhausted
+```
+
+### Phase 4: Project-Level Documentation
+
+**After all module documentation is generated, create project-level documentation files.**
+
+```javascript
+let project_name = detect_project_name();
+let project_root = get_project_root();
+
+// Step 1: Generate Project README
+report("Generating project README.md...");
+for (let tool of tool_order) {
+  Bash({
+    command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "project-readme" "." "${project_name}" "${tool}"`,
+    run_in_background: false
+  });
+  if (bash_result.exit_code === 0) {
+    report(`✅ Project README generated with ${tool}`);
+    break;
+  }
+}
+
+// Step 2: Generate Architecture & Examples
+report("Generating ARCHITECTURE.md and EXAMPLES.md...");
+for (let tool of tool_order) {
+  Bash({
+    command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "project-architecture" "." "${project_name}" "${tool}"`,
+    run_in_background: false
+  });
+  if (bash_result.exit_code === 0) {
+    report(`✅ Architecture docs generated with ${tool}`);
+    break;
+  }
+}
+
+// Step 3: Generate HTTP API documentation (if API routes detected)
+Bash({command: 'rg "router\\.|@Get|@Post" -g "*.{ts,js,py}" 2>/dev/null && echo "API_FOUND" || echo "NO_API"', run_in_background: false});
+if (bash_result.stdout.includes("API_FOUND")) {
+  report("Generating HTTP API documentation...");
+  for (let tool of tool_order) {
+    Bash({
+      command: `cd ${project_root} && ~/.claude/scripts/generate_module_docs.sh "http-api" "." "${project_name}" "${tool}"`,
+      run_in_background: false
+    });
+    if (bash_result.exit_code === 0) {
+      report(`✅ HTTP API docs generated with ${tool}`);
+      break;
+    }
+  }
+}
+```
+
+**Expected Output**:
+```
+Project-Level Documentation:
+  ✅ README.md (project root overview)
+  ✅ ARCHITECTURE.md (system design)
+  ✅ EXAMPLES.md (usage examples)
+  ✅ api/README.md (HTTP API reference) [optional]
+```
+
+### Phase 5: Verification
+
+```javascript
+// Check documentation files created
+Bash({command: 'find .workflow/docs -type f -name "*.md" 2>/dev/null | wc -l', run_in_background: false});
+
+// Display structure
+Bash({command: 'tree -L 3 .workflow/docs/', run_in_background: false});
+```
+
+**Result Summary**:
+```
+Documentation Generation Summary:
+  Total: 31 | Success: 29 | Failed: 2
+  Tool usage: gemini: 25, qwen: 4, codex: 0
+  Failed: path1, path2
+
+  Generated documentation:
+    .workflow/docs/myproject/
+    ├── src/
+    │   ├── auth/
+    │   │   ├── API.md
+    │   │   └── README.md
+    │   └── utils/
+    │       └── README.md
+    └── README.md
+```
+
+## Error Handling
+
+**Batch Worker**: Tool fallback per module, batch isolation, clear status reporting
+**Coordinator**: Invalid path abort, user decline handling, verification with cleanup
+**Fallback Triggers**: Non-zero exit code, script timeout, unexpected output
+
+## Output Structure
+
+```
+.workflow/docs/{project_name}/
+├── src/                           # Mirrors source structure
+│   ├── modules/
+│   │   ├── README.md              # Navigation
+│   │   ├── auth/
+│   │   │   ├── API.md             # API signatures
+│   │   │   ├── README.md          # Module docs
+│   │   │   └── middleware/
+│   │   │       ├── API.md
+│   │   │       └── README.md
+│   │   └── api/
+│   │       ├── API.md
+│   │       └── README.md
+│   └── utils/
+│       └── README.md
+├── lib/
+│   └── core/
+│       ├── API.md
+│       └── README.md
+├── README.md                      # ✨ Project root overview (auto-generated)
+├── ARCHITECTURE.md                # ✨ System design (auto-generated)
+├── EXAMPLES.md                    # ✨ Usage examples (auto-generated)
+└── api/                           # ✨ Optional (auto-generated if HTTP API detected)
+    └── README.md                  # HTTP API reference
+```
+
+## Usage Examples
+
+```bash
+# Full project documentation generation
+/memory:docs-full-cli
+
+# Target specific directory
+/memory:docs-full-cli src/features/auth
+/memory:docs-full-cli .claude
+
+# Use specific tool
+/memory:docs-full-cli --tool qwen
+/memory:docs-full-cli src --tool qwen
+```
+
+## Key Advantages
+
+- **Efficiency**: 30 modules → 8 agents (73% reduction from sequential)
+- **Resilience**: 3-tier tool fallback per module
+- **Performance**: Parallel batches, no concurrency limits
+- **Observability**: Per-module tool usage, batch-level metrics
+- **Automation**: Zero configuration - strategy auto-selected by directory depth
+- **Path Mirroring**: Clear 1:1 mapping between source and documentation structure
+
+## Template Reference
+
+Templates used from `~/.claude/workflows/cli-templates/prompts/documentation/`:
+- `api.txt`: Code API documentation (Part A: Code API, Part B: HTTP API)
+- `module-readme.txt`: Module purpose, usage, dependencies
+- `folder-navigation.txt`: Navigation README for folders with subdirectories
+
+## Related Commands
+
+- `/memory:docs` - Agent-based documentation planning workflow
+- `/memory:docs-related-cli` - Update docs for changed modules only
+- `/workflow:execute` - Execute documentation tasks (when using agent mode)

.claude/commands/memory/docs-related-cli.md

@@ -0,0 +1,386 @@
+---
+name: docs-related-cli
+description: Generate/update documentation for git-changed modules using CLI execution with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <15 modules uses direct parallel
+argument-hint: "[--tool <gemini|qwen|codex>]"
+---
+
+# Related Documentation Generation - CLI Mode (/memory:docs-related-cli)
+
+## Overview
+
+Orchestrates context-aware documentation generation/update for changed modules using CLI-based execution with batched agents and automatic tool fallback (gemini→qwen→codex).
+
+**Parameters**:
+- `--tool <gemini|qwen|codex>`: Primary tool (default: gemini)
+
+**Execution Flow**:
+1. Change Detection → 2. Plan Presentation → 3. Batched Execution → 4. Verification
+
+## Core Rules
+
+1. **Detect Changes First**: Use git diff to identify affected modules
+2. **Wait for Approval**: Present plan, no execution without user confirmation
+3. **Execution Strategy**:
+   - **<15 modules**: Direct parallel execution (max 4 concurrent per depth, no agent overhead)
+   - **≥15 modules**: Agent batch processing (4 modules/agent, 73% overhead reduction)
+4. **Tool Fallback**: Auto-retry with fallback tools on failure
+5. **Depth Sequential**: Process depths N→0, parallel batches within depth (both modes)
+6. **Related Mode**: Generate/update only changed modules and their parent contexts
+7. **Single Strategy**: Always use `single` strategy (incremental update)
+
+## Tool Fallback Hierarchy
+
+```javascript
+--tool gemini  →  [gemini, qwen, codex]  // default
+--tool qwen    →  [qwen, gemini, codex]
+--tool codex   →  [codex, gemini, qwen]
+```
+
+**Trigger**: Non-zero exit code from generation script
+
+| Tool   | Best For                       | Fallback To    |
+|--------|--------------------------------|----------------|
+| gemini | Documentation, patterns        | qwen → codex   |
+| qwen   | Architecture, system design    | gemini → codex |
+| codex  | Implementation, code quality   | gemini → qwen  |
+
+## Phase 1: Change Detection & Analysis
+
+```javascript
+// Get project metadata
+Bash({command: "pwd && basename \"$(pwd)\" && git rev-parse --show-toplevel 2>/dev/null || pwd", run_in_background: false});
+
+// Detect changed modules
+Bash({command: "~/.claude/scripts/detect_changed_modules.sh list", run_in_background: false});
+
+// Cache git changes
+Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
+```
+
+**Parse output** `depth:N|path:<PATH>|change:<TYPE>|type:<code|navigation>` to extract affected modules.
+
+**Smart filter**: Auto-detect and skip tests/build/config/vendor based on project tech stack (Node.js/Python/Go/Rust/etc).
+
+**Fallback**: If no changes detected, use recent modules (first 10 by depth).
+
+## Phase 2: Plan Presentation
+
+**Present filtered plan**:
+```
+Related Documentation Generation Plan:
+  Tool: gemini (fallback: qwen → codex)
+  Changed: 4 modules | Batching: 4 modules/agent
+  Project: myproject
+  Output: .workflow/docs/myproject/
+
+  Will generate/update docs for:
+  - ./src/api/auth (5 files, type: code) [new module]
+  - ./src/api (12 files, type: code) [parent of changed auth/]
+  - ./src (8 files, type: code) [parent context]
+  - . (14 files, type: code) [root level]
+
+  Documentation Strategy:
+  - Strategy: single (all modules - incremental update)
+  - Output: API.md + README.md (code folders), README.md only (navigation folders)
+  - Context: Current dir code + child docs
+
+  Auto-skipped (12 paths):
+  - Tests: ./src/api/auth.test.ts (8 paths)
+  - Config: tsconfig.json (3 paths)
+  - Other: node_modules (1 path)
+
+  Agent allocation:
+  - Depth 3 (1 module): 1 agent [1]
+  - Depth 2 (1 module): 1 agent [1]
+  - Depth 1 (1 module): 1 agent [1]
+  - Depth 0 (1 module): 1 agent [1]
+
+  Estimated time: ~5-10 minutes
+
+  Confirm execution? (y/n)
+```
+
+**Decision logic**:
+- User confirms "y": Proceed with execution
+- User declines "n": Abort, no changes
+- <15 modules: Direct execution
+- ≥15 modules: Agent batch execution
+
+## Phase 3A: Direct Execution (<15 modules)
+
+**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead.
+
+**CRITICAL**: All Bash commands use `run_in_background: false` for synchronous execution.
+
+```javascript
+let project_name = detect_project_name();
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let batches = batch_modules(modules_by_depth[depth], 4);
+
+  for (let batch of batches) {
+    let parallel_tasks = batch.map(module => {
+      return async () => {
+        for (let tool of tool_order) {
+          Bash({
+            command: `cd ${module.path} && ~/.claude/scripts/generate_module_docs.sh "single" "." "${project_name}" "${tool}"`,
+            run_in_background: false
+          });
+          if (bash_result.exit_code === 0) {
+            report(`✅ ${module.path} docs generated with ${tool}`);
+            return true;
+          }
+        }
+        report(`❌ FAILED: ${module.path} failed all tools`);
+        return false;
+      };
+    });
+    await Promise.all(parallel_tasks.map(task => task()));
+  }
+}
+```
+
+## Phase 3B: Agent Batch Execution (≥15 modules)
+
+### Batching Strategy
+
+```javascript
+// Batch modules into groups of 4
+function batch_modules(modules, batch_size = 4) {
+  let batches = [];
+  for (let i = 0; i < modules.length; i += batch_size) {
+    batches.push(modules.slice(i, i + batch_size));
+  }
+  return batches;
+}
+// Examples: 10→[4,4,2] | 8→[4,4] | 3→[3]
+```
+
+### Coordinator Orchestration
+
+```javascript
+let modules_by_depth = group_by_depth(changed_modules);
+let tool_order = construct_tool_order(primary_tool);
+let project_name = detect_project_name();
+
+for (let depth of sorted_depths.reverse()) {  // N → 0
+  let batches = batch_modules(modules_by_depth[depth], 4);
+  let worker_tasks = [];
+
+  for (let batch of batches) {
+    worker_tasks.push(
+      Task(
+        subagent_type="memory-bridge",
+        description=`Generate docs for ${batch.length} modules at depth ${depth}`,
+        prompt=generate_batch_worker_prompt(batch, tool_order, depth, project_name, "related")
+      )
+    );
+  }
+
+  await parallel_execute(worker_tasks);  // Batches run in parallel
+}
+```
+
+### Batch Worker Prompt Template
+
+```
+PURPOSE: Generate/update documentation for assigned modules with tool fallback (related mode)
+
+TASK:
+Generate documentation for the following modules based on recent changes. For each module, try tools in order until success.
+
+PROJECT: {{project_name}}
+OUTPUT: .workflow/docs/{{project_name}}/
+
+MODULES:
+{{module_path_1}} (type: {{folder_type_1}})
+{{module_path_2}} (type: {{folder_type_2}})
+{{module_path_3}} (type: {{folder_type_3}})
+{{module_path_4}} (type: {{folder_type_4}})
+
+TOOLS (try in order):
+1. {{tool_1}}
+2. {{tool_2}}
+3. {{tool_3}}
+
+EXECUTION:
+For each module above:
+  1. Try tool 1:
+     Bash({
+       command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_1}}"`,
+       run_in_background: false
+     })
+     → Success: Report "✅ {{module_path}} docs generated with {{tool_1}}", proceed to next module
+     → Failure: Try tool 2
+  2. Try tool 2:
+     Bash({
+       command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_2}}"`,
+       run_in_background: false
+     })
+     → Success: Report "✅ {{module_path}} docs generated with {{tool_2}}", proceed to next module
+     → Failure: Try tool 3
+  3. Try tool 3:
+     Bash({
+       command: `cd "{{module_path}}" && ~/.claude/scripts/generate_module_docs.sh "single" "." "{{project_name}}" "{{tool_3}}"`,
+       run_in_background: false
+     })
+     → Success: Report "✅ {{module_path}} docs generated with {{tool_3}}", proceed to next module
+     → Failure: Report "❌ FAILED: {{module_path}} failed all tools", proceed to next module
+
+FOLDER TYPE HANDLING:
+  - code: Generate API.md + README.md
+  - navigation: Generate README.md only
+
+REPORTING:
+Report final summary with:
+- Total processed: X modules
+- Successful: Y modules
+- Failed: Z modules
+- Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
+```
+
+## Phase 4: Verification
+
+```javascript
+// Check documentation files created/updated
+Bash({command: 'find .workflow/docs -type f -name "*.md" 2>/dev/null | wc -l', run_in_background: false});
+
+// Display recent changes
+Bash({command: 'find .workflow/docs -type f -name "*.md" -mmin -60 2>/dev/null', run_in_background: false});
+```
+
+**Aggregate results**:
+```
+Documentation Generation Summary:
+  Total: 4 | Success: 4 | Failed: 0
+
+  Tool usage:
+  - gemini: 4 modules
+  - qwen: 0 modules (fallback)
+  - codex: 0 modules
+
+  Changes:
+  .workflow/docs/myproject/src/api/auth/API.md      (new)
+  .workflow/docs/myproject/src/api/auth/README.md   (new)
+  .workflow/docs/myproject/src/api/API.md           (updated)
+  .workflow/docs/myproject/src/api/README.md        (updated)
+  .workflow/docs/myproject/src/API.md               (updated)
+  .workflow/docs/myproject/src/README.md            (updated)
+  .workflow/docs/myproject/API.md                   (updated)
+  .workflow/docs/myproject/README.md                (updated)
+```
+
+## Execution Summary
+
+**Module Count Threshold**:
+- **<15 modules**: Coordinator executes Phase 3A (Direct Execution)
+- **≥15 modules**: Coordinator executes Phase 3B (Agent Batch Execution)
+
+**Agent Hierarchy** (for ≥15 modules):
+- **Coordinator**: Handles batch division, spawns worker agents per depth
+- **Worker Agents**: Each processes 4 modules with tool fallback (related mode)
+
+## Error Handling
+
+**Batch Worker**:
+- Tool fallback per module (auto-retry)
+- Batch isolation (failures don't propagate)
+- Clear per-module status reporting
+
+**Coordinator**:
+- No changes: Use fallback (recent 10 modules)
+- User decline: No execution
+- Verification fail: Report incomplete modules
+- Partial failures: Continue execution, report failed modules
+
+**Fallback Triggers**:
+- Non-zero exit code
+- Script timeout
+- Unexpected output
+
+## Output Structure
+
+```
+.workflow/docs/{project_name}/
+├── src/                           # Mirrors source structure
+│   ├── modules/
+│   │   ├── README.md
+│   │   ├── auth/
+│   │   │   ├── API.md             # Updated based on code changes
+│   │   │   └── README.md          # Updated based on code changes
+│   │   └── api/
+│   │       ├── API.md
+│   │       └── README.md
+│   └── utils/
+│       └── README.md
+└── README.md
+```
+
+## Usage Examples
+
+```bash
+# Daily development documentation update
+/memory:docs-related-cli
+
+# After feature work with specific tool
+/memory:docs-related-cli --tool qwen
+
+# Code quality documentation review after implementation
+/memory:docs-related-cli --tool codex
+```
+
+## Key Advantages
+
+**Efficiency**: 30 modules → 8 agents (73% reduction)
+**Resilience**: 3-tier fallback per module
+**Performance**: Parallel batches, no concurrency limits
+**Context-aware**: Updates based on actual git changes
+**Fast**: Only affected modules, not entire project
+**Incremental**: Single strategy for focused updates
+
+## Coordinator Checklist
+
+- Parse `--tool` (default: gemini)
+- Get project metadata (name, root)
+- Detect changed modules via detect_changed_modules.sh
+- **Smart filter modules** (auto-detect tech stack, skip tests/build/config/vendor)
+- Cache git changes
+- Apply fallback if no changes (recent 10 modules)
+- Construct tool fallback order
+- **Present filtered plan** with skip reasons and change types
+- **Wait for y/n confirmation**
+- Determine execution mode:
+  - **<15 modules**: Direct execution (Phase 3A)
+    - For each depth (N→0): Sequential module updates with tool fallback
+  - **≥15 modules**: Agent batch execution (Phase 3B)
+    - For each depth (N→0): Batch modules (4 per batch), spawn batch workers in parallel
+- Wait for depth/batch completion
+- Aggregate results
+- Verification check (documentation files created/updated)
+- Display summary + recent changes
+
+## Comparison with Full Documentation Generation
+
+| Aspect | Related Generation | Full Generation |
+|--------|-------------------|-----------------|
+| **Scope** | Changed modules only | All project modules |
+| **Speed** | Fast (minutes) | Slower (10-30 min) |
+| **Use case** | Daily development | Initial setup, major refactoring |
+| **Strategy** | `single` (all) | `full` (L3) + `single` (L1-2) |
+| **Trigger** | After commits | After setup or major changes |
+| **Batching** | 4 modules/agent | 4 modules/agent |
+| **Fallback** | gemini→qwen→codex | gemini→qwen→codex |
+| **Complexity threshold** | ≤15 modules | ≤20 modules |
+
+## Template Reference
+
+Templates used from `~/.claude/workflows/cli-templates/prompts/documentation/`:
+- `api.txt`: Code API documentation
+- `module-readme.txt`: Module purpose, usage, dependencies
+- `folder-navigation.txt`: Navigation README for folders
+
+## Related Commands
+
+- `/memory:docs-full-cli` - Full project documentation generation
+- `/memory:docs` - Agent-based documentation planning workflow
+- `/memory:update-related` - Update CLAUDE.md for changed modules

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

@@ -0,0 +1,182 @@
+---
+name: load-skill-memory
+description: Activate SKILL package (auto-detect from paths/keywords or manual) and intelligently load documentation based on task intent keywords
+argument-hint: "[skill_name] \"task intent description\""
+allowed-tools: Bash(*), Read(*), Skill(*)
+---
+
+# Memory Load SKILL Command (/memory:load-skill-memory)
+
+## 1. Overview
+
+The `memory:load-skill-memory` command **activates SKILL package** (auto-detect from task or manual specification) and intelligently loads documentation based on user's task intent. The system automatically determines which documentation files to read based on the intent description.
+
+**Core Philosophy**:
+- **Flexible Activation**: Auto-detect skill from task description/paths, or user explicitly specifies
+- **Intent-Driven Loading**: System analyzes task intent to determine documentation scope
+- **Intelligent Selection**: Automatically chooses appropriate documentation level and modules
+- **Direct Context Loading**: Loads selected documentation into conversation memory
+
+**When to Use**:
+- Manually activate a known SKILL package for a specific task
+- Load SKILL context when system hasn't auto-triggered it
+- Force reload SKILL documentation with specific intent focus
+
+**Note**: Normal SKILL activation happens automatically via description triggers or path mentions (system extracts skill name from file paths for intelligent triggering). Use this command only when manual activation is needed.
+
+## 2. Parameters
+
+- `[skill_name]` (Optional): Name of SKILL package to activate
+  - If omitted: System auto-detects from task description or file paths
+  - If specified: Direct activation of named SKILL package
+  - Example: `my_project`, `api_service`
+  - Must match directory name under `.claude/skills/`
+
+- `"task intent description"` (Required): Description of what you want to do
+  - Used for both: auto-detection (if skill_name omitted) and documentation scope selection
+  - **Analysis tasks**: "分析builder pattern实现", "理解参数系统架构"
+  - **Modification tasks**: "修改workflow逻辑", "增强thermal template功能"
+  - **Learning tasks**: "学习接口设计模式", "了解测试框架使用"
+  - **With paths**: "修改D:\projects\my_project\src\auth.py的认证逻辑" (auto-extracts `my_project`)
+
+## 3. Execution Flow
+
+### Step 1: Determine SKILL Name (if not provided)
+
+**Auto-Detection Strategy** (when skill_name parameter is omitted):
+1. **Path Extraction**: Scan task description for file paths
+   - Extract potential project names from path segments
+   - Example: `"修改D:\projects\my_project\src\auth.py"` → extracts `my_project`
+2. **Keyword Matching**: Match task keywords against SKILL descriptions
+   - Search for project-specific terms, domain keywords
+3. **Validation**: Check if extracted name matches `.claude/skills/{skill_name}/`
+
+**Result**: Either uses provided skill_name or auto-detected name for activation
+
+### Step 2: Activate SKILL and Analyze Intent
+
+**Activate SKILL Package**:
+```javascript
+Skill(command: "${skill_name}")  // Uses provided or auto-detected name
+```
+
+**What Happens After Activation**:
+1. If SKILL exists in memory: System reads `.claude/skills/${skill_name}/SKILL.md`
+2. If SKILL not found in memory: Error - SKILL package doesn't exist
+3. SKILL description triggers are loaded into memory
+4. Progressive loading mechanism becomes available
+5. Documentation structure is now accessible
+
+**Intent Analysis**:
+Based on task intent description, system determines:
+- **Action type**: analyzing, modifying, learning
+- **Scope**: specific module, architecture overview, complete system
+- **Depth**: quick reference, detailed API, full documentation
+
+### Step 3: Intelligent Documentation Loading
+
+**Loading Strategy**:
+
+The system automatically selects documentation based on intent keywords:
+
+1. **Quick Understanding** ("了解", "快速理解", "什么是"):
+   - Load: Level 0 (README.md only, ~2K tokens)
+   - Use case: Quick overview of capabilities
+
+2. **Specific Module Analysis** ("分析XXX模块", "理解XXX实现"):
+   - Load: Module-specific README.md + API.md (~5K tokens)
+   - Use case: Deep dive into specific component
+
+3. **Architecture Review** ("架构", "设计模式", "整体结构"):
+   - Load: README.md + ARCHITECTURE.md (~10K tokens)
+   - Use case: System design understanding
+
+4. **Implementation/Modification** ("修改", "增强", "实现"):
+   - Load: Relevant module docs + EXAMPLES.md (~15K tokens)
+   - Use case: Code modification with examples
+
+5. **Comprehensive Learning** ("学习", "完整了解", "深入理解"):
+   - Load: Level 3 (All documentation, ~40K tokens)
+   - Use case: Complete system mastery
+
+**Documentation Loaded into Memory**:
+After loading, the selected documentation content is available in conversation memory for subsequent operations.
+
+## 4. Usage Examples
+
+### Example 1: Manual Specification
+
+**User Command**:
+```bash
+/memory:load-skill-memory my_project "修改认证模块增加OAuth支持"
+```
+
+**Execution**:
+```javascript
+// Step 1: Use provided skill_name
+skill_name = "my_project"  // Directly from parameter
+
+// Step 2: Activate SKILL
+Skill(command: "my_project")
+
+// Step 3: Intent Analysis
+Keywords: ["修改", "认证模块", "增加", "OAuth"]
+Action: modifying (implementation)
+Scope: auth module + examples
+
+// Load documentation based on intent
+Read(.workflow/docs/my_project/auth/README.md)
+Read(.workflow/docs/my_project/auth/API.md)
+Read(.workflow/docs/my_project/EXAMPLES.md)
+```
+
+### Example 2: Auto-Detection from Path
+
+**User Command**:
+```bash
+/memory:load-skill-memory "修改D:\projects\my_project\src\services\api.py的接口逻辑"
+```
+
+**Execution**:
+```javascript
+// Step 1: Auto-detect skill_name from path
+Path detected: "D:\projects\my_project\src\services\api.py"
+Extracted: "my_project"
+Validated: .claude/skills/my_project/ exists ✓
+skill_name = "my_project"
+
+// Step 2: Activate SKILL
+Skill(command: "my_project")
+
+// Step 3: Intent Analysis
+Keywords: ["修改", "services", "接口逻辑"]
+Action: modifying (implementation)
+Scope: services module + examples
+
+// Load documentation based on intent
+Read(.workflow/docs/my_project/services/README.md)
+Read(.workflow/docs/my_project/services/API.md)
+Read(.workflow/docs/my_project/EXAMPLES.md)
+```
+
+## 5. Intent Keyword Mapping
+
+**Quick Reference**:
+- **Triggers**: "了解", "快速", "什么是", "简介"
+- **Loads**: README.md only (~2K)
+
+**Module-Specific**:
+- **Triggers**: "XXX模块", "XXX组件", "分析XXX"
+- **Loads**: Module README + API (~5K)
+
+**Architecture**:
+- **Triggers**: "架构", "设计", "整体结构", "系统设计"
+- **Loads**: README + ARCHITECTURE (~10K)
+
+**Implementation**:
+- **Triggers**: "修改", "增强", "实现", "开发", "集成"
+- **Loads**: Relevant module + EXAMPLES (~15K)
+
+**Comprehensive**:
+- **Triggers**: "完整", "深入", "全面", "学习整个"
+- **Loads**: All documentation (~40K)

.claude/commands/memory/load.md

@@ -1,6 +1,6 @@
 ---
 name: load
-description: Load project memory by delegating to agent, returns structured core content package for subsequent operations
+description: Delegate to universal-executor agent to analyze project via Gemini/Qwen CLI and return JSON core content package for task context
 argument-hint: "[--tool gemini|qwen] \"task context description\""
 allowed-tools: Task(*), Bash(*)
 examples:

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

@@ -0,0 +1,525 @@
+---
+name: skill-memory
+description: 4-phase autonomous orchestrator: check docs → /memory:docs planning → /workflow:execute → generate SKILL.md with progressive loading index (skips phases 2-3 if docs exist)
+argument-hint: "[path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Memory SKILL Package Generator
+
+## Orchestrator Role
+
+**Pure Orchestrator**: Execute documentation generation workflow, then generate SKILL.md index. Does NOT create task JSON files.
+
+**Auto-Continue Workflow**: This command runs **fully autonomously** once triggered. Each phase completes and automatically triggers the next phase without user interaction.
+
+**Execution Paths**:
+- **Full Path**: All 4 phases (no existing docs OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 4 (existing docs found AND no `--regenerate` flag)
+- **Phase 4 Always Executes**: SKILL.md index is never skipped, always generated or updated
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - delegates to /memory:docs
+3. **Parse Every Output**: Extract required data from each command output (session_id, task_count, file paths)
+4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+5. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+6. **Direct Generation**: Phase 4 directly generates SKILL.md using Write tool
+7. **No Manual Steps**: User should never be prompted for decisions between phases
+
+---
+
+## 4-Phase Execution
+
+### Phase 1: Prepare Arguments
+
+**Goal**: Parse command arguments and check existing documentation
+
+**Step 1: Get Target Path and Project Name**
+```bash
+# Get current directory (or use provided path)
+bash(pwd)
+
+# Get project name from directory
+bash(basename "$(pwd)")
+
+# Get project root
+bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
+```
+
+**Output**:
+- `target_path`: `/d/my_project`
+- `project_name`: `my_project`
+- `project_root`: `/d/my_project`
+
+**Step 2: Set Default Parameters**
+```bash
+# Default values (use these unless user specifies otherwise):
+# - tool: "gemini"
+# - mode: "full"
+# - regenerate: false (no --regenerate flag)
+# - cli_execute: false (no --cli-execute flag)
+```
+
+**Step 3: Check Existing Documentation**
+```bash
+# Check if docs directory exists
+bash(test -d .workflow/docs/my_project && echo "exists" || echo "not_exists")
+
+# Count existing documentation files
+bash(find .workflow/docs/my_project -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Output**:
+- `docs_exists`: `exists` or `not_exists`
+- `existing_docs`: `5` (or `0` if no docs)
+
+**Step 4: Determine Execution Path**
+
+**Decision Logic**:
+```javascript
+if (existing_docs > 0 && !regenerate_flag) {
+  // Documentation exists and no regenerate flag
+  SKIP_DOCS_GENERATION = true
+  message = "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  // Force regeneration: delete existing docs
+  bash(rm -rf .workflow/docs/my_project 2>/dev/null || true)
+  SKIP_DOCS_GENERATION = false
+  message = "Regenerating documentation from scratch."
+} else {
+  // No existing docs
+  SKIP_DOCS_GENERATION = false
+  message = "No existing documentation found, generating new documentation."
+}
+```
+
+**Summary Variables**:
+- `PROJECT_NAME`: `my_project`
+- `TARGET_PATH`: `/d/my_project`
+- `DOCS_PATH`: `.workflow/docs/my_project`
+- `TOOL`: `gemini` (default) or user-specified
+- `MODE`: `full` (default) or user-specified
+- `CLI_EXECUTE`: `false` (default) or `true` if --cli-execute flag
+- `REGENERATE`: `false` (default) or `true` if --regenerate flag
+- `EXISTING_DOCS`: Count of existing documentation files
+- `SKIP_DOCS_GENERATION`: `true` if skipping Phase 2/3, `false` otherwise
+
+**Completion & TodoWrite**:
+- If `SKIP_DOCS_GENERATION = true`: Mark phase 1 completed, phase 2&3 completed (skipped), phase 4 in_progress
+- If `SKIP_DOCS_GENERATION = false`: Mark phase 1 completed, phase 2 in_progress
+
+**Next Action**:
+- If skipping: Display skip message → Jump to Phase 4 (SKILL.md generation)
+- If not skipping: Display preparation results → Continue to Phase 2 (documentation planning)
+
+---
+
+### Phase 2: Call /memory:docs
+
+**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
+
+**Goal**: Trigger documentation generation workflow
+
+**Command**:
+```bash
+SlashCommand(command="/memory:docs [targetPath] --tool [tool] --mode [mode] [--cli-execute]")
+```
+
+**Example**:
+```bash
+/memory:docs /d/my_app --tool gemini --mode full
+/memory:docs /d/my_app --tool gemini --mode full --cli-execute
+```
+
+**Note**: The `--regenerate` flag is handled in Phase 1 by deleting existing documentation. This command always calls `/memory:docs` without the regenerate flag, relying on docs.md's built-in update detection.
+
+**Parse Output**:
+- Extract session ID: `WFS-docs-[timestamp]` (store as `docsSessionId`)
+- Extract task count (store as `taskCount`)
+
+**Completion Criteria**:
+- `/memory:docs` command executed successfully
+- Session ID extracted and stored
+- Task count retrieved
+- Task files created in `.workflow/[docsSessionId]/.task/`
+- workflow-session.json exists
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+**Next Action**: Display docs planning results (session ID, task count) → Auto-continue to Phase 3
+
+---
+
+### Phase 3: Execute Documentation Generation
+
+**Skip Condition**: This phase is **skipped if SKIP_DOCS_GENERATION = true** (documentation already exists without --regenerate flag)
+
+**Goal**: Execute documentation generation tasks
+
+**Command**:
+```bash
+SlashCommand(command="/workflow:execute")
+```
+
+**Note**: `/workflow:execute` automatically discovers active session from Phase 2
+
+**Completion Criteria**:
+- `/workflow:execute` command executed successfully
+- Documentation files generated in `.workflow/docs/[projectName]/`
+- All tasks marked as completed in session
+- At minimum: module documentation files exist (API.md and/or README.md)
+- For full mode: Project README, ARCHITECTURE, EXAMPLES files generated
+
+**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+
+**Next Action**: Display execution results (file count, module count) → Auto-continue to Phase 4
+
+---
+
+### Phase 4: Generate SKILL.md Index
+
+**Note**: This phase is **NEVER skipped** - it always executes to generate or update the SKILL index.
+
+**Step 1: Read Key Files** (Use Read tool)
+- `.workflow/docs/{project_name}/README.md` (required)
+- `.workflow/docs/{project_name}/ARCHITECTURE.md` (optional)
+
+**Step 2: Discover Structure**
+```bash
+bash(find .workflow/docs/{project_name} -name "*.md" | sed 's|.workflow/docs/{project_name}/||' | awk -F'/' '{if(NF>=2) print $1"/"$2}' | sort -u)
+```
+
+**Step 3: Generate Intelligent Description**
+
+Extract from README + structure: Function (capabilities), Modules (names), Keywords (API/CLI/auth/etc.)
+
+**Format**: `{Project} {core capabilities} (located at {project_path}). Load this SKILL when analyzing, modifying, or learning about {domain_description} or files under this path, especially when no relevant context exists in memory.`
+
+**Key Elements**:
+- **Path Reference**: Use `TARGET_PATH` from Phase 1 for precise location identification
+- **Domain Description**: Extract human-readable domain/feature area from README (e.g., "workflow management", "thermal modeling")
+- **Trigger Optimization**: Include project path, emphasize "especially when no relevant context exists in memory"
+- **Action Coverage**: analyzing (分析), modifying (修改), learning (了解)
+
+**Example**: "Workflow orchestration system with CLI tools and documentation generation (located at /d/Claude_dms3). Load this SKILL when analyzing, modifying, or learning about workflow management or files under this path, especially when no relevant context exists in memory."
+
+**Step 4: Write SKILL.md** (Use Write tool)
+```bash
+bash(mkdir -p .claude/skills/{project_name})
+```
+
+`.claude/skills/{project_name}/SKILL.md`:
+```yaml
+---
+name: {project_name}
+description: {intelligent description from Step 3}
+version: 1.0.0
+---
+# {Project Name} SKILL Package
+
+## Documentation: `../../../.workflow/docs/{project_name}/`
+
+## Progressive Loading
+### Level 0: Quick Start (~2K)
+- [README](../../../.workflow/docs/{project_name}/README.md)
+### Level 1: Core Modules (~8K)
+{Module READMEs}
+### Level 2: Complete (~25K)
+All modules + [Architecture](../../../.workflow/docs/{project_name}/ARCHITECTURE.md)
+### Level 3: Deep Dive (~40K)
+Everything + [Examples](../../../.workflow/docs/{project_name}/EXAMPLES.md)
+```
+
+**Completion Criteria**:
+- SKILL.md file created at `.claude/skills/{project_name}/SKILL.md`
+- Intelligent description generated from documentation
+- Progressive loading levels (0-3) properly structured
+- Module index includes all documented modules
+- All file references use relative paths
+
+**TodoWrite**: Mark phase 4 completed
+
+**Final Action**: Report completion summary to user
+
+**Return to User**:
+```
+SKILL Package Generation Complete
+
+Project: {project_name}
+Documentation: .workflow/docs/{project_name}/ ({doc_count} files)
+SKILL Index: .claude/skills/{project_name}/SKILL.md
+
+Generated:
+- {task_count} documentation tasks completed
+- SKILL.md with progressive loading (4 levels)
+- Module index with {module_count} modules
+
+Usage:
+- Load Level 0: Quick project overview (~2K tokens)
+- Load Level 1: Core modules (~8K tokens)
+- Load Level 2: Complete docs (~25K tokens)
+- Load Level 3: Everything (~40K tokens)
+```
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
+2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
+3. **Status-Driven Execution**: Check TodoList status after each phase:
+   - If next task is "pending" → Mark it "in_progress" and execute
+   - If all tasks are "completed" → Report final summary
+4. **Phase Completion Pattern**:
+   ```
+   Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
+   ```
+
+### TodoWrite Patterns
+
+#### Initialization (Before Phase 1)
+
+**FIRST ACTION**: Create TodoList with all 4 phases
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "in_progress", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "pending", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+```
+
+**SECOND ACTION**: Execute Phase 1 immediately
+
+#### Full Path (SKIP_DOCS_GENERATION = false)
+
+**After Phase 1**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "in_progress", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "pending", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 2
+```
+
+**After Phase 2**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "in_progress", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 3
+```
+
+**After Phase 3**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+// Auto-continue to Phase 4
+```
+
+**After Phase 4**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
+]})
+// Report completion summary to user
+```
+
+#### Skip Path (SKIP_DOCS_GENERATION = true)
+
+**After Phase 1** (detects existing docs, skips Phase 2 & 3):
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "in_progress", "activeForm": "Generating SKILL.md"}
+]})
+// Display skip message: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+// Jump directly to Phase 4
+```
+
+**After Phase 4**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Parse arguments and prepare", "status": "completed", "activeForm": "Parsing arguments"},
+  {"content": "Call /memory:docs to plan documentation", "status": "completed", "activeForm": "Calling /memory:docs"},
+  {"content": "Execute documentation generation", "status": "completed", "activeForm": "Executing documentation"},
+  {"content": "Generate SKILL.md index", "status": "completed", "activeForm": "Generating SKILL.md"}
+]})
+// Report completion summary to user
+```
+
+### Execution Flow Diagrams
+
+#### Full Path Flow
+```
+User triggers command
+  ↓
+[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
+  ↓
+[Execute] Phase 1: Parse arguments
+  ↓
+[TodoWrite] Phase 1 = completed, Phase 2 = in_progress
+  ↓
+[Execute] Phase 2: Call /memory:docs
+  ↓
+[TodoWrite] Phase 2 = completed, Phase 3 = in_progress
+  ↓
+[Execute] Phase 3: Call /workflow:execute
+  ↓
+[TodoWrite] Phase 3 = completed, Phase 4 = in_progress
+  ↓
+[Execute] Phase 4: Generate SKILL.md
+  ↓
+[TodoWrite] Phase 4 = completed
+  ↓
+[Report] Display completion summary
+```
+
+#### Skip Path Flow
+```
+User triggers command
+  ↓
+[TodoWrite] Initialize 4 phases (Phase 1 = in_progress)
+  ↓
+[Execute] Phase 1: Parse arguments, detect existing docs
+  ↓
+[TodoWrite] Phase 1 = completed, Phase 2&3 = completed (skipped), Phase 4 = in_progress
+  ↓
+[Display] Skip message: "Documentation already exists, skipping Phase 2 and Phase 3"
+  ↓
+[Execute] Phase 4: Generate SKILL.md (always runs)
+  ↓
+[TodoWrite] Phase 4 = completed
+  ↓
+[Report] Display completion summary
+```
+
+### Error Handling
+
+- If any phase fails, mark it as "in_progress" (not completed)
+- Report error details to user
+- Do NOT auto-continue to next phase on failure
+
+---
+
+## Parameters
+
+```bash
+/memory:skill-memory [path] [--tool <gemini|qwen|codex>] [--regenerate] [--mode <full|partial>] [--cli-execute]
+```
+
+- **path**: Target directory (default: current directory)
+- **--tool**: CLI tool for documentation (default: gemini)
+  - `gemini`: Comprehensive documentation
+  - `qwen`: Architecture analysis
+  - `codex`: Implementation validation
+- **--regenerate**: Force regenerate all documentation
+  - When enabled: Deletes existing `.workflow/docs/{project_name}/` before regeneration
+  - Ensures fresh documentation from source code
+- **--mode**: Documentation mode (default: full)
+  - `full`: Complete docs (modules + README + ARCHITECTURE + EXAMPLES)
+  - `partial`: Module docs only
+- **--cli-execute**: Enable CLI-based documentation generation (optional)
+  - When enabled: CLI generates docs directly in implementation_approach
+  - When disabled (default): Agent generates documentation content
+
+---
+
+## Examples
+
+### Example 1: Generate SKILL Package (Default)
+
+```bash
+/memory:skill-memory
+```
+
+**Workflow**:
+1. Phase 1: Detects current directory, checks existing docs
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full` (Agent Mode)
+3. Phase 3: Executes documentation generation via `/workflow:execute`
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 2: Regenerate with Qwen
+
+```bash
+/memory:skill-memory /d/my_app --tool qwen --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Parses target path, detects regenerate flag, deletes existing docs
+2. Phase 2: Calls `/memory:docs /d/my_app --tool qwen --mode full`
+3. Phase 3: Executes documentation regeneration
+4. Phase 4: Generates updated SKILL.md
+
+### Example 3: Partial Mode (Modules Only)
+
+```bash
+/memory:skill-memory --mode partial
+```
+
+**Workflow**:
+1. Phase 1: Detects partial mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode partial` (Agent Mode)
+3. Phase 3: Executes module documentation only
+4. Phase 4: Generates SKILL.md with module-only index
+
+### Example 4: CLI Execute Mode
+
+```bash
+/memory:skill-memory --cli-execute
+```
+
+**Workflow**:
+1. Phase 1: Detects CLI execute mode
+2. Phase 2: Calls `/memory:docs . --tool gemini --mode full --cli-execute` (CLI Mode)
+3. Phase 3: Executes CLI-based documentation generation
+4. Phase 4: Generates SKILL.md at `.claude/skills/{project_name}/SKILL.md`
+
+### Example 5: Skip Path (Existing Docs)
+
+```bash
+/memory:skill-memory
+```
+
+**Scenario**: Documentation already exists in `.workflow/docs/{project_name}/`
+
+**Workflow**:
+1. Phase 1: Detects existing docs (5 files), sets SKIP_DOCS_GENERATION = true
+2. Display: "Documentation already exists, skipping Phase 2 and Phase 3. Use --regenerate to force regeneration."
+3. Phase 4: Generates or updates SKILL.md index only (~5-10x faster)
+
+---
+
+
+
+## Architecture
+
+```
+skill-memory (orchestrator)
+  ├─ Phase 1: Prepare (bash commands, skip decision)
+  ├─ Phase 2: /memory:docs (task planning, skippable)
+  ├─ Phase 3: /workflow:execute (task execution, skippable)
+  └─ Phase 4: Write SKILL.md (direct file generation, always runs)
+
+No task JSON created by this command
+All documentation tasks managed by /memory:docs
+Smart skip logic: 5-10x faster when docs exist
+```

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

@@ -0,0 +1,396 @@
+---
+name: style-skill-memory
+description: Generate SKILL memory package from style reference for easy loading and consistent design system usage
+argument-hint: "[package-name] [--regenerate]"
+allowed-tools: Bash,Read,Write,TodoWrite
+auto-continue: true
+---
+
+# Memory: Style SKILL Memory Generator
+
+## Overview
+
+**Purpose**: Convert style reference package into SKILL memory for easy loading and context management.
+
+**Input**: Style reference package at `.workflow/reference_style/{package-name}/`
+
+**Output**: SKILL memory index at `.claude/skills/style-{package-name}/SKILL.md`
+
+**Use Case**: Load design system context when working with UI components, analyzing design patterns, or implementing style guidelines.
+
+**Key Features**:
+- Extracts primary design references (colors, typography, spacing, etc.)
+- Provides dynamic adjustment guidelines for design tokens
+- Includes prerequisites and tooling requirements (browsers, PostCSS, dark mode)
+- Progressive loading structure for efficient token usage
+- Complete implementation examples with React components
+- Interactive preview showcase
+
+---
+
+## Quick Reference
+
+### Command Syntax
+
+```bash
+/memory:style-skill-memory [package-name] [--regenerate]
+
+# Arguments
+package-name    Style reference package name (required)
+--regenerate    Force regenerate SKILL.md even if it exists (optional)
+```
+
+### Usage Examples
+
+```bash
+# Generate SKILL memory for package
+/memory:style-skill-memory main-app-style-v1
+
+# Regenerate SKILL memory
+/memory:style-skill-memory main-app-style-v1 --regenerate
+
+# Package name from current directory or default
+/memory:style-skill-memory
+```
+
+### Key Variables
+
+**Input Variables**:
+- `PACKAGE_NAME`: Style reference package name
+- `PACKAGE_DIR`: `.workflow/reference_style/${package_name}`
+- `SKILL_DIR`: `.claude/skills/style-${package_name}`
+- `REGENERATE`: `true` if --regenerate flag, `false` otherwise
+
+**Data Sources** (Phase 2):
+- `DESIGN_TOKENS_DATA`: Complete design-tokens.json content (from Read)
+- `LAYOUT_TEMPLATES_DATA`: Complete layout-templates.json content (from Read)
+- `ANIMATION_TOKENS_DATA`: Complete animation-tokens.json content (from Read, if exists)
+
+**Metadata** (Phase 2):
+- `COMPONENT_COUNT`: Total components
+- `UNIVERSAL_COUNT`: Universal components count
+- `SPECIALIZED_COUNT`: Specialized components count
+- `UNIVERSAL_COMPONENTS`: Universal component names (first 5)
+- `HAS_ANIMATIONS`: Whether animation-tokens.json exists
+
+**Analysis Output** (`DESIGN_ANALYSIS` - Phase 2):
+- `has_colors`: Colors exist
+- `color_semantic`: Has semantic naming (primary/secondary/accent)
+- `uses_oklch`: Uses modern color spaces (oklch, lab, etc.)
+- `has_dark_mode`: Has separate light/dark mode color tokens
+- `spacing_pattern`: Pattern type ("linear", "geometric", "custom")
+- `spacing_scale`: Actual scale values (e.g., [4, 8, 16, 32, 64])
+- `has_typography`: Typography system exists
+- `typography_hierarchy`: Has size scale for hierarchy
+- `uses_calc`: Uses calc() expressions in token values
+- `has_radius`: Border radius exists
+- `radius_style`: Style characteristic ("sharp" <4px, "moderate" 4-8px, "rounded" >8px)
+- `has_shadows`: Shadow system exists
+- `shadow_pattern`: Elevation naming pattern
+- `has_animations`: Animation tokens exist
+- `animation_range`: Duration range (fast to slow)
+- `easing_variety`: Types of easing functions
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Package not found | Invalid package name or doesn't exist | Run `/workflow:ui-design:codify-style` first |
+| SKILL already exists | SKILL.md already generated | Use `--regenerate` flag |
+| Missing layout-templates.json | Incomplete package | Verify package integrity, re-run codify-style |
+| Invalid JSON format | Corrupted package files | Regenerate package with codify-style |
+
+---
+
+## Execution Process
+
+### Phase 1: Validate Package
+
+**TodoWrite** (First Action):
+```json
+[
+  {
+    "content": "Validate package exists and check SKILL status",
+    "activeForm": "Validating package and SKILL status",
+    "status": "in_progress"
+  },
+  {
+    "content": "Read package data and analyze design system",
+    "activeForm": "Reading package data and analyzing design system",
+    "status": "pending"
+  },
+  {
+    "content": "Generate SKILL.md with design principles and token values",
+    "activeForm": "Generating SKILL.md with design principles and token values",
+    "status": "pending"
+  }
+]
+```
+
+**Step 1: Parse Package Name**
+
+```bash
+# Get package name from argument or auto-detect
+bash(echo "${package_name}" || basename "$(pwd)" | sed 's/^style-//')
+```
+
+**Step 2: Validate Package Exists**
+
+```bash
+bash(test -d .workflow/reference_style/${package_name} && echo "exists" || echo "missing")
+```
+
+**Error Handling**:
+```javascript
+if (package_not_exists) {
+  error("ERROR: Style reference package not found: ${package_name}")
+  error("HINT: Run '/workflow:ui-design:codify-style' first to create package")
+  error("Available packages:")
+  bash(ls -1 .workflow/reference_style/ 2>/dev/null || echo "  (none)")
+  exit(1)
+}
+```
+
+**Step 3: Check SKILL Already Exists**
+
+```bash
+bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "exists" || echo "missing")
+```
+
+**Decision Logic**:
+```javascript
+if (skill_exists && !regenerate_flag) {
+  echo("SKILL memory already exists for: ${package_name}")
+  echo("Use --regenerate to force regeneration")
+  exit(0)
+}
+
+if (regenerate_flag && skill_exists) {
+  echo("Regenerating SKILL memory for: ${package_name}")
+}
+```
+
+**TodoWrite Update**: Mark "Validate" as completed, "Read package data" as in_progress
+
+---
+
+### Phase 2: Read Package Data & Analyze Design System
+
+**Step 1: Read All JSON Files**
+
+```bash
+# Read layout templates
+Read(file_path=".workflow/reference_style/${package_name}/layout-templates.json")
+
+# Read design tokens
+Read(file_path=".workflow/reference_style/${package_name}/design-tokens.json")
+
+# Read animation tokens (if exists)
+bash(test -f .workflow/reference_style/${package_name}/animation-tokens.json && echo "exists" || echo "missing")
+Read(file_path=".workflow/reference_style/${package_name}/animation-tokens.json")  # if exists
+```
+
+**Step 2: Extract Metadata for Description**
+
+```bash
+# Count components and classify by type
+bash(jq '.layout_templates | length' layout-templates.json)
+bash(jq '[.layout_templates[] | select(.component_type == "universal")] | length' layout-templates.json)
+bash(jq '[.layout_templates[] | select(.component_type == "specialized")] | length' layout-templates.json)
+bash(jq -r '.layout_templates | to_entries[] | select(.value.component_type == "universal") | .key' layout-templates.json | head -5)
+```
+
+Store results in metadata variables (see [Key Variables](#key-variables))
+
+**Step 3: Analyze Design System for Dynamic Principles**
+
+Analyze design-tokens.json to extract characteristics and patterns:
+
+```bash
+# Color system characteristics
+bash(jq '.colors | keys' design-tokens.json)
+bash(jq '.colors | to_entries[0:2] | map(.value)' design-tokens.json)
+# Check for modern color spaces
+bash(jq '.colors | to_entries[] | .value | test("oklch|lab|lch")' design-tokens.json)
+# Check for dark mode variants
+bash(jq '.colors | keys | map(select(contains("dark") or contains("light")))' design-tokens.json)
+# → Store: has_colors, color_semantic, uses_oklch, has_dark_mode
+
+# Spacing pattern detection
+bash(jq '.spacing | to_entries | map(.value) | map(gsub("[^0-9.]"; "") | tonumber)' design-tokens.json)
+# Analyze pattern: linear (4-8-12-16) vs geometric (4-8-16-32) vs custom
+# → Store: spacing_pattern, spacing_scale
+
+# Typography characteristics
+bash(jq '.typography | keys | map(select(contains("family") or contains("weight")))' design-tokens.json)
+bash(jq '.typography | to_entries | map(select(.key | contains("size"))) | .[].value' design-tokens.json)
+# Check for calc() usage
+bash(jq '. | tostring | test("calc\\(")' design-tokens.json)
+# → Store: has_typography, typography_hierarchy, uses_calc
+
+# Border radius style
+bash(jq '.border_radius | to_entries | map(.value)' design-tokens.json)
+# Check range: small (sharp <4px) vs moderate (4-8px) vs large (rounded >8px)
+# → Store: has_radius, radius_style
+
+# Shadow characteristics
+bash(jq '.shadows | keys' design-tokens.json)
+bash(jq '.shadows | to_entries[0].value' design-tokens.json)
+# → Store: has_shadows, shadow_pattern
+
+# Animations (if available)
+bash(jq '.duration | to_entries | map(.value)' animation-tokens.json)
+bash(jq '.easing | keys' animation-tokens.json)
+# → Store: has_animations, animation_range, easing_variety
+```
+
+Store analysis results in `DESIGN_ANALYSIS` (see [Key Variables](#key-variables))
+
+**Note**: Analysis focuses on characteristics and patterns, not counts. Include technical feature detection (oklch, calc, dark mode) for Prerequisites section.
+
+**TodoWrite Update**: Mark "Read package data" as completed, "Generate SKILL.md" as in_progress
+
+---
+
+### Phase 3: Generate SKILL.md
+
+**Step 1: Create SKILL Directory**
+
+```bash
+bash(mkdir -p .claude/skills/style-${package_name})
+```
+
+**Step 2: Generate Intelligent Description**
+
+**Format**:
+```
+{package_name} project-independent design system with {universal_count} universal layout templates and interactive preview (located at .workflow/reference_style/{package_name}). Load when working with reusable UI components, design tokens, layout patterns, or implementing visual consistency. Excludes {specialized_count} project-specific components.
+```
+
+**Step 3: Load and Process SKILL.md Template**
+
+**⚠️ CRITICAL - Execute First**:
+```bash
+bash(cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/skill-md-template.md)
+```
+
+**Template Processing**:
+1. **Replace variables**: Substitute all `{variable}` placeholders with actual values from Phase 2
+2. **Generate dynamic sections**:
+   - **Prerequisites & Tooling**: Generate based on `DESIGN_ANALYSIS` technical features (oklch, calc, dark mode)
+   - **Design Principles**: Generate based on `DESIGN_ANALYSIS` characteristics
+   - **Complete Implementation Example**: Include React component example with token adaptation
+   - **Design Token Values**: Iterate `DESIGN_TOKENS_DATA`, `ANIMATION_TOKENS_DATA` and display all key-value pairs with DEFAULT annotations
+3. **Write to file**: Use Write tool to save to `.claude/skills/style-{package_name}/SKILL.md`
+
+**Variable Replacement Map**:
+- `{package_name}` → PACKAGE_NAME
+- `{intelligent_description}` → Generated description from Step 2
+- `{component_count}` → COMPONENT_COUNT
+- `{universal_count}` → UNIVERSAL_COUNT
+- `{specialized_count}` → SPECIALIZED_COUNT
+- `{universal_components_list}` → UNIVERSAL_COMPONENTS (comma-separated)
+- `{has_animations}` → HAS_ANIMATIONS
+
+**Dynamic Content Generation**:
+
+See template file for complete structure. Key dynamic sections:
+
+1. **Prerequisites & Tooling** (based on DESIGN_ANALYSIS technical features):
+   - IF uses_oklch → Include PostCSS plugin requirement (`postcss-oklab-function`)
+   - IF uses_calc → Include preprocessor requirement for calc() expressions
+   - IF has_dark_mode → Include dark mode implementation mechanism (class or media query)
+   - ALWAYS include browser support, jq installation, and local server setup
+
+2. **Design Principles** (based on DESIGN_ANALYSIS):
+   - IF has_colors → Include "Color System" principle with semantic pattern
+   - IF spacing_pattern detected → Include "Spatial Rhythm" with unified scale description (actual token values)
+   - IF has_typography_hierarchy → Include "Typographic System" with scale examples
+   - IF has_radius → Include "Shape Language" with style characteristic
+   - IF has_shadows → Include "Depth & Elevation" with elevation pattern
+   - IF has_animations → Include "Motion & Timing" with duration range
+   - ALWAYS include "Accessibility First" principle
+
+3. **Design Token Values** (iterate from read data):
+   - Colors: Iterate `DESIGN_TOKENS_DATA.colors`
+   - Typography: Iterate `DESIGN_TOKENS_DATA.typography`
+   - Spacing: Iterate `DESIGN_TOKENS_DATA.spacing`
+   - Border Radius: Iterate `DESIGN_TOKENS_DATA.border_radius` with calc() explanations
+   - Shadows: Iterate `DESIGN_TOKENS_DATA.shadows` with DEFAULT token annotations
+   - Animations (if available): Iterate `ANIMATION_TOKENS_DATA.duration` and `ANIMATION_TOKENS_DATA.easing`
+
+**Step 4: Verify SKILL.md Created**
+
+```bash
+bash(test -f .claude/skills/style-${package_name}/SKILL.md && echo "success" || echo "failed")
+```
+
+**TodoWrite Update**: Mark all todos as completed
+
+---
+
+### Completion Message
+
+Display a simple completion message with key information:
+
+```
+✅ SKILL memory generated for style package: {package_name}
+
+📁 Location: .claude/skills/style-{package_name}/SKILL.md
+
+📊 Package Summary:
+   - {component_count} components ({universal_count} universal, {specialized_count} specialized)
+   - Design tokens: colors, typography, spacing, shadows{animations_note}
+
+💡 Usage: /memory:load-skill-memory style-{package_name} "your task description"
+```
+
+Variables: `{package_name}`, `{component_count}`, `{universal_count}`, `{specialized_count}`, `{animations_note}` (", animations" if exists)
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **Check Before Generate**: Verify package exists before attempting SKILL generation
+2. **Respect Existing SKILL**: Don't overwrite unless --regenerate flag provided
+3. **Load Templates via cat**: Use `cat ~/.claude/workflows/cli-templates/memory/style-skill-memory/{template}` to load templates
+4. **Variable Substitution**: Replace all `{variable}` placeholders with actual values
+5. **Technical Feature Detection**: Analyze tokens for modern features (oklch, calc, dark mode) and generate appropriate Prerequisites section
+6. **Dynamic Content Generation**: Generate sections based on DESIGN_ANALYSIS characteristics
+7. **Unified Spacing Scale**: Use actual token values as primary scale reference, avoid contradictory pattern descriptions
+8. **Direct Iteration**: Iterate data structures (DESIGN_TOKENS_DATA, etc.) for token values
+9. **Annotate Special Tokens**: Add comments for DEFAULT tokens and calc() expressions
+10. **Embed jq Commands**: Include bash/jq commands in SKILL.md for dynamic loading
+11. **Progressive Loading**: Include all 3 levels (0-2) with specific jq commands
+12. **Complete Examples**: Include end-to-end implementation examples (React components)
+13. **Intelligent Description**: Extract component count and key features from metadata
+14. **Emphasize Flexibility**: Strongly warn against rigid copying - values are references for creative adaptation
+
+### Template Files Location
+
+
+```
+Phase 1: Validate
+  ├─ Parse package_name
+  ├─ Check PACKAGE_DIR exists
+  └─ Check SKILL_DIR exists (skip if exists and no --regenerate)
+
+Phase 2: Read & Analyze
+  ├─ Read design-tokens.json → DESIGN_TOKENS_DATA
+  ├─ Read layout-templates.json → LAYOUT_TEMPLATES_DATA
+  ├─ Read animation-tokens.json → ANIMATION_TOKENS_DATA (if exists)
+  ├─ Extract Metadata → COMPONENT_COUNT, UNIVERSAL_COUNT, etc.
+  └─ Analyze Design System → DESIGN_ANALYSIS (characteristics)
+
+Phase 3: Generate
+  ├─ Create SKILL directory
+  ├─ Generate intelligent description
+  ├─ Load SKILL.md template (cat command)
+  ├─ Replace variables and generate dynamic content
+  ├─ Write SKILL.md
+  ├─ Verify creation
+  ├─ Load completion message template (cat command)
+  └─ Display completion message
+```

.claude/commands/memory/tech-research.md

@@ -0,0 +1,477 @@
+---
+name: tech-research
+description: 3-phase orchestrator: extract tech stack from session/name → delegate to agent for Exa research and module generation → generate SKILL.md index (skips phase 2 if exists)
+argument-hint: "[session-id | tech-stack-name] [--regenerate] [--tool <gemini|qwen>]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Bash(*), Read(*), Write(*), Task(*)
+---
+
+# Tech Stack Research SKILL Generator
+
+## Overview
+
+**Pure Orchestrator with Agent Delegation**: Prepares context paths and delegates ALL work to agent. Agent produces files directly.
+
+**Auto-Continue Workflow**: Runs fully autonomously once triggered. Each phase completes and automatically triggers the next phase.
+
+**Execution Paths**:
+- **Full Path**: All 3 phases (no existing SKILL OR `--regenerate` specified)
+- **Skip Path**: Phase 1 → Phase 3 (existing SKILL found AND no `--regenerate` flag)
+- **Phase 3 Always Executes**: SKILL index is always generated or updated
+
+**Agent Responsibility**:
+- Agent does ALL the work: context reading, Exa research, content synthesis, file writing
+- Orchestrator only provides context paths and waits for completion
+
+## Core Rules
+
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 execution
+2. **Context Path Delegation**: Pass session directory or tech stack name to agent, let agent do discovery
+3. **Agent Produces Files**: Agent directly writes all module files, orchestrator does NOT parse agent output
+4. **Auto-Continue**: After completing each phase, update TodoWrite and immediately execute next phase
+5. **No User Prompts**: Never ask user questions or wait for input between phases
+6. **Track Progress**: Update TodoWrite after EVERY phase completion before starting next phase
+7. **Lightweight Index**: Phase 3 only generates SKILL.md index by reading existing files
+
+---
+
+## 3-Phase Execution
+
+### Phase 1: Prepare Context Paths
+
+**Goal**: Detect input mode, prepare context paths for agent, check existing SKILL
+
+**Input Mode Detection**:
+```bash
+# Get input parameter
+input="$1"
+
+# Detect mode
+if [[ "$input" == WFS-* ]]; then
+  MODE="session"
+  SESSION_ID="$input"
+  CONTEXT_PATH=".workflow/${SESSION_ID}"
+else
+  MODE="direct"
+  TECH_STACK_NAME="$input"
+  CONTEXT_PATH="$input"  # Pass tech stack name as context
+fi
+```
+
+**Check Existing SKILL**:
+```bash
+# For session mode, peek at session to get tech stack name
+if [[ "$MODE" == "session" ]]; then
+  bash(test -f ".workflow/${SESSION_ID}/workflow-session.json")
+  Read(.workflow/${SESSION_ID}/workflow-session.json)
+  # Extract tech_stack_name (minimal extraction)
+fi
+
+# Normalize and check
+normalized_name=$(echo "$TECH_STACK_NAME" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+bash(test -d ".claude/skills/${normalized_name}" && echo "exists" || echo "not_exists")
+bash(find ".claude/skills/${normalized_name}" -name "*.md" 2>/dev/null | wc -l || echo 0)
+```
+
+**Skip Decision**:
+```javascript
+if (existing_files > 0 && !regenerate_flag) {
+  SKIP_GENERATION = true
+  message = "Tech stack SKILL already exists, skipping Phase 2. Use --regenerate to force regeneration."
+} else if (regenerate_flag) {
+  bash(rm -rf ".claude/skills/${normalized_name}")
+  SKIP_GENERATION = false
+  message = "Regenerating tech stack SKILL from scratch."
+} else {
+  SKIP_GENERATION = false
+  message = "No existing SKILL found, generating new tech stack documentation."
+}
+```
+
+**Output Variables**:
+- `MODE`: `session` or `direct`
+- `SESSION_ID`: Session ID (if session mode)
+- `CONTEXT_PATH`: Path to session directory OR tech stack name
+- `TECH_STACK_NAME`: Extracted or provided tech stack name
+- `SKIP_GENERATION`: Boolean - whether to skip Phase 2
+
+**TodoWrite**:
+- If skipping: Mark phase 1 completed, phase 2 completed, phase 3 in_progress
+- If not skipping: Mark phase 1 completed, phase 2 in_progress
+
+---
+
+### Phase 2: Agent Produces All Files
+
+**Skip Condition**: Skipped if `SKIP_GENERATION = true`
+
+**Goal**: Delegate EVERYTHING to agent - context reading, Exa research, content synthesis, and file writing
+
+**Agent Task Specification**:
+
+```
+Task(
+  subagent_type: "general-purpose",
+  description: "Generate tech stack SKILL: {CONTEXT_PATH}",
+  prompt: "
+Generate a complete tech stack SKILL package with Exa research.
+
+**Context Provided**:
+- Mode: {MODE}
+- Context Path: {CONTEXT_PATH}
+
+**Templates Available**:
+- Module Format: ~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt
+- SKILL Index: ~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt
+
+**Your Responsibilities**:
+
+1. **Extract Tech Stack Information**:
+
+   IF MODE == 'session':
+     - Read `.workflow/active/{session_id}/workflow-session.json`
+     - Read `.workflow/active/{session_id}/.process/context-package.json`
+     - Extract tech_stack: {language, frameworks, libraries}
+     - Build tech stack name: \"{language}-{framework1}-{framework2}\"
+     - Example: \"typescript-react-nextjs\"
+
+   IF MODE == 'direct':
+     - Tech stack name = CONTEXT_PATH
+     - Parse composite: split by '-' delimiter
+     - Example: \"typescript-react-nextjs\" → [\"typescript\", \"react\", \"nextjs\"]
+
+2. **Execute Exa Research** (4-6 parallel queries):
+
+   Base Queries (always execute):
+   - mcp__exa__get_code_context_exa(query: \"{tech} core principles best practices 2025\", tokensNum: 8000)
+   - mcp__exa__get_code_context_exa(query: \"{tech} common patterns architecture examples\", tokensNum: 7000)
+   - mcp__exa__web_search_exa(query: \"{tech} configuration setup tooling 2025\", numResults: 5)
+   - mcp__exa__get_code_context_exa(query: \"{tech} testing strategies\", tokensNum: 5000)
+
+   Component Queries (if composite):
+   - For each additional component:
+     mcp__exa__get_code_context_exa(query: \"{main_tech} {component} integration\", tokensNum: 5000)
+
+3. **Read Module Format Template**:
+
+   Read template for structure guidance:
+   ```bash
+   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-module-format.txt)
+   ```
+
+4. **Synthesize Content into 6 Modules**:
+
+   Follow template structure from tech-module-format.txt:
+   - **principles.md** - Core concepts, philosophies (~3K tokens)
+   - **patterns.md** - Implementation patterns with code examples (~5K tokens)
+   - **practices.md** - Best practices, anti-patterns, pitfalls (~4K tokens)
+   - **testing.md** - Testing strategies, frameworks (~3K tokens)
+   - **config.md** - Setup, configuration, tooling (~3K tokens)
+   - **frameworks.md** - Framework integration (only if composite, ~4K tokens)
+
+   Each module follows template format:
+   - Frontmatter (YAML)
+   - Main sections with clear headings
+   - Code examples from Exa research
+   - Best practices sections
+   - References to Exa sources
+
+5. **Write Files Directly**:
+
+   ```javascript
+   // Create directory
+   bash(mkdir -p \".claude/skills/{tech_stack_name}\")
+
+   // Write each module file using Write tool
+   Write({ file_path: \".claude/skills/{tech_stack_name}/principles.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/patterns.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/practices.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/testing.md\", content: ... })
+   Write({ file_path: \".claude/skills/{tech_stack_name}/config.md\", content: ... })
+   // Write frameworks.md only if composite
+
+   // Write metadata.json
+   Write({
+     file_path: \".claude/skills/{tech_stack_name}/metadata.json\",
+     content: JSON.stringify({
+       tech_stack_name,
+       components,
+       is_composite,
+       generated_at: timestamp,
+       source: \"exa-research\",
+       research_summary: { total_queries, total_sources }
+     })
+   })
+   ```
+
+6. **Report Completion**:
+
+   Provide summary:
+   - Tech stack name
+   - Files created (count)
+   - Exa queries executed
+   - Sources consulted
+
+**CRITICAL**:
+- MUST read external template files before generating content (step 3 for modules, step 4 for index)
+- You have FULL autonomy - read files, execute Exa, synthesize content, write files
+- Do NOT return JSON or structured data - produce actual .md files
+- Handle errors gracefully (Exa failures, missing files, template read failures)
+- If tech stack cannot be determined, ask orchestrator to clarify
+  "
+)
+```
+
+**Completion Criteria**:
+- Agent task executed successfully
+- 5-6 modular files written to `.claude/skills/{tech_stack_name}/`
+- metadata.json written
+- Agent reports completion
+
+**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+
+---
+
+### Phase 3: Generate SKILL.md Index
+
+**Note**: This phase **ALWAYS executes** - generates or updates the SKILL index.
+
+**Goal**: Read generated module files and create SKILL.md index with loading recommendations
+
+**Steps**:
+
+1. **Verify Generated Files**:
+   ```bash
+   bash(find ".claude/skills/${TECH_STACK_NAME}" -name "*.md" -type f | sort)
+   ```
+
+2. **Read metadata.json**:
+   ```javascript
+   Read(.claude/skills/${TECH_STACK_NAME}/metadata.json)
+   // Extract: tech_stack_name, components, is_composite, research_summary
+   ```
+
+3. **Read Module Headers** (optional, first 20 lines):
+   ```javascript
+   Read(.claude/skills/${TECH_STACK_NAME}/principles.md, limit: 20)
+   // Repeat for other modules
+   ```
+
+4. **Read SKILL Index Template**:
+
+   ```javascript
+   Read(~/.claude/workflows/cli-templates/prompts/tech/tech-skill-index.txt)
+   ```
+
+5. **Generate SKILL.md Index**:
+
+   Follow template from tech-skill-index.txt with variable substitutions:
+   - `{TECH_STACK_NAME}`: From metadata.json
+   - `{MAIN_TECH}`: Primary technology
+   - `{ISO_TIMESTAMP}`: Current timestamp
+   - `{QUERY_COUNT}`: From research_summary
+   - `{SOURCE_COUNT}`: From research_summary
+   - Conditional sections for composite tech stacks
+
+   Template provides structure for:
+   - Frontmatter with metadata
+   - Overview and tech stack description
+   - Module organization (Core/Practical/Config sections)
+   - Loading recommendations (Quick/Implementation/Complete)
+   - Usage guidelines and auto-trigger keywords
+   - Research metadata and version history
+
+6. **Write SKILL.md**:
+   ```javascript
+   Write({
+     file_path: `.claude/skills/${TECH_STACK_NAME}/SKILL.md`,
+     content: generatedIndexMarkdown
+   })
+   ```
+
+**Completion Criteria**:
+- SKILL.md index written
+- All module files verified
+- Loading recommendations included
+
+**TodoWrite**: Mark phase 3 completed
+
+**Final Report**:
+```
+Tech Stack SKILL Package Complete
+
+Tech Stack: {TECH_STACK_NAME}
+Location: .claude/skills/{TECH_STACK_NAME}/
+
+Files: SKILL.md + 5-6 modules + metadata.json
+Exa Research: {queries} queries, {sources} sources
+
+Usage: Skill(command: "{TECH_STACK_NAME}")
+```
+
+---
+
+## Implementation Details
+
+### TodoWrite Patterns
+
+**Initialization** (Before Phase 1):
+```javascript
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "in_progress", "activeForm": "Preparing context paths"},
+  {"content": "Agent produces all module files", "status": "pending", "activeForm": "Agent producing files"},
+  {"content": "Generate SKILL.md index", "status": "pending", "activeForm": "Generating SKILL index"}
+]})
+```
+
+**Full Path** (SKIP_GENERATION = false):
+```javascript
+// After Phase 1
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "in_progress", ...},
+  {"content": "Generate SKILL.md index", "status": "pending", ...}
+]})
+
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},
+  {"content": "Generate SKILL.md index", "status": "completed", ...}
+]})
+```
+
+**Skip Path** (SKIP_GENERATION = true):
+```javascript
+// After Phase 1 (skip Phase 2)
+TodoWrite({todos: [
+  {"content": "Prepare context paths", "status": "completed", ...},
+  {"content": "Agent produces all module files", "status": "completed", ...},  // Skipped
+  {"content": "Generate SKILL.md index", "status": "in_progress", ...}
+]})
+```
+
+### Execution Flow
+
+**Full Path**:
+```
+User → TodoWrite Init → Phase 1 (prepare) → Phase 2 (agent writes files) → Phase 3 (write index) → Report
+```
+
+**Skip Path**:
+```
+User → TodoWrite Init → Phase 1 (detect existing) → Phase 3 (update index) → Report
+```
+
+### Error Handling
+
+**Phase 1 Errors**:
+- Invalid session ID: Report error, verify session exists
+- Missing context-package: Warn, fall back to direct mode
+- No tech stack detected: Ask user to specify tech stack name
+
+**Phase 2 Errors (Agent)**:
+- Agent task fails: Retry once, report if fails again
+- Exa API failures: Agent handles internally with retries
+- Incomplete results: Warn user, proceed with partial data if minimum sections available
+
+**Phase 3 Errors**:
+- Write failures: Report which files failed
+- Missing files: Note in SKILL.md, suggest regeneration
+
+---
+
+## Parameters
+
+```bash
+/memory:tech-research [session-id | "tech-stack-name"] [--regenerate] [--tool <gemini|qwen>]
+```
+
+**Arguments**:
+- **session-id | tech-stack-name**: Input source (auto-detected by WFS- prefix)
+  - Session mode: `WFS-user-auth-v2` - Extract tech stack from workflow
+  - Direct mode: `"typescript"`, `"typescript-react-nextjs"` - User specifies
+- **--regenerate**: Force regenerate existing SKILL (deletes and recreates)
+- **--tool**: Reserved for future CLI integration (default: gemini)
+
+---
+
+## Examples
+
+**Generated File Structure** (for all examples):
+```
+.claude/skills/{tech-stack}/
+├── SKILL.md           # Index (Phase 3)
+├── principles.md      # Agent (Phase 2)
+├── patterns.md        # Agent
+├── practices.md       # Agent
+├── testing.md         # Agent
+├── config.md          # Agent
+├── frameworks.md      # Agent (if composite)
+└── metadata.json      # Agent
+```
+
+### Direct Mode - Single Stack
+
+```bash
+/memory:tech-research "typescript"
+```
+
+**Workflow**:
+1. Phase 1: Detects direct mode, checks existing SKILL
+2. Phase 2: Agent executes 4 Exa queries, writes 5 modules
+3. Phase 3: Generates SKILL.md index
+
+### Direct Mode - Composite Stack
+
+```bash
+/memory:tech-research "typescript-react-nextjs"
+```
+
+**Workflow**:
+1. Phase 1: Decomposes into ["typescript", "react", "nextjs"]
+2. Phase 2: Agent executes 6 Exa queries (4 base + 2 components), writes 6 modules (adds frameworks.md)
+3. Phase 3: Generates SKILL.md index with framework integration
+
+### Session Mode - Extract from Workflow
+
+```bash
+/memory:tech-research WFS-user-auth-20251104
+```
+
+**Workflow**:
+1. Phase 1: Reads session, extracts tech stack: `python-fastapi-sqlalchemy`
+2. Phase 2: Agent researches Python + FastAPI + SQLAlchemy, writes 6 modules
+3. Phase 3: Generates SKILL.md index
+
+### Regenerate Existing
+
+```bash
+/memory:tech-research "react" --regenerate
+```
+
+**Workflow**:
+1. Phase 1: Deletes existing SKILL due to --regenerate
+2. Phase 2: Agent executes fresh Exa research (latest 2025 practices)
+3. Phase 3: Generates updated SKILL.md
+
+### Skip Path - Fast Update
+
+```bash
+/memory:tech-research "python"
+```
+
+**Scenario**: SKILL already exists with 7 files
+
+**Workflow**:
+1. Phase 1: Detects existing SKILL, sets SKIP_GENERATION = true
+2. Phase 2: **SKIPPED**
+3. Phase 3: Updates SKILL.md index only (5-10x faster)
+
+

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

@@ -1,6 +1,6 @@
 ---
 name: update-full
-description: Complete project-wide CLAUDE.md documentation update with agent-based parallel execution and tool fallback
+description: Update all CLAUDE.md files using layer-based execution (Layer 3→1) with batched agents (4 modules/agent) and gemini→qwen→codex fallback, <20 modules uses direct parallel
 argument-hint: "[--tool gemini|qwen|codex] [--path <directory>]"
 ---
 
@@ -36,13 +36,12 @@ Orchestrates project-wide CLAUDE.md updates using batched agent execution with a
 - **Use Case**: Deepest directories with unstructured file layouts
 - **Behavior**: Generates CLAUDE.md for current directory AND each subdirectory containing files
 - **Context**: All files in current directory tree (`@**/*`)
-- **Benefits**: Creates foundation documentation for upper layers to reference
+
 
 #### Single-Layer Strategy (Layers 1-2)
 - **Use Case**: Upper layers that aggregate from existing documentation
 - **Behavior**: Generates CLAUDE.md only for current directory
 - **Context**: Direct children CLAUDE.md files + current directory code files
-- **Benefits**: Minimal context consumption, clear layer separation
 
 ### Example Flow
 ```
@@ -95,14 +94,15 @@ src/ (depth 1) → SINGLE-LAYER STRATEGY
 
 ### Phase 1: Discovery & Analysis
 
-```bash
-# Cache git changes
-bash(git add -A 2>/dev/null || true)
+```javascript
+// Cache git changes
+Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
 
-# Get module structure
-bash(~/.claude/scripts/get_modules_by_depth.sh list)
-# OR with --path
-bash(cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list)
+// Get module structure
+Bash({command: "~/.claude/scripts/get_modules_by_depth.sh list", run_in_background: false});
+
+// OR with --path
+Bash({command: "cd <target-path> && ~/.claude/scripts/get_modules_by_depth.sh list", run_in_background: false});
 ```
 
 **Parse output** `depth:N|path:<PATH>|...` to extract module paths and count.
@@ -172,26 +172,23 @@ Update Plan:
 
 **Strategy**: Parallel execution within layer (max 4 concurrent), no agent overhead.
 
-```javascript
-// Group modules by LAYER (not depth)
-let modules_by_layer = group_by_layer(module_list);
-let tool_order = construct_tool_order(primary_tool);
+**CRITICAL**: All Bash commands use `run_in_background: false` for synchronous execution.
 
-// Process by LAYER (3 → 2 → 1), not by depth
+```javascript
 for (let layer of [3, 2, 1]) {
   if (modules_by_layer[layer].length === 0) continue;
-
   let batches = batch_modules(modules_by_layer[layer], 4);
 
   for (let batch of batches) {
     let parallel_tasks = batch.map(module => {
       return async () => {
-        // Auto-determine strategy based on depth
         let strategy = module.depth >= 3 ? "multi-layer" : "single-layer";
-
         for (let tool of tool_order) {
-          let exit_code = bash(`cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`);
-          if (exit_code === 0) {
+          Bash({
+            command: `cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "${strategy}" "." "${tool}"`,
+            run_in_background: false
+          });
+          if (bash_result.exit_code === 0) {
             report(`✅ ${module.path} (Layer ${layer}) updated with ${tool}`);
             return true;
           }
@@ -200,7 +197,6 @@ for (let layer of [3, 2, 1]) {
         return false;
       };
     });
-
     await Promise.all(parallel_tasks.map(task => task()));
   }
 }
@@ -255,7 +251,10 @@ EXECUTION SCRIPT: ~/.claude/scripts/update_module_claude.sh
 EXECUTION FLOW (for each module):
   1. Tool fallback loop (exit on first success):
      for tool in {{tool_1}} {{tool_2}} {{tool_3}}; do
-       bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}")
+       Bash({
+         command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "{{strategy}}" "." "${tool}"`,
+         run_in_background: false
+       })
        exit_code=$?
 
        if [ $exit_code -eq 0 ]; then
@@ -287,12 +286,12 @@ REPORTING FORMAT:
 ```
 ### Phase 4: Safety Verification
 
-```bash
-# Check only CLAUDE.md modified
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+```javascript
+// Check only CLAUDE.md files modified
+Bash({command: 'git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified"', run_in_background: false});
 
-# Display status
-bash(git status --short)
+// Display status
+Bash({command: "git status --short", run_in_background: false});
 ```
 
 **Result Summary**:

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

@@ -1,6 +1,6 @@
 ---
 name: update-related
-description: Context-aware CLAUDE.md documentation updates based on recent changes with agent-based execution and tool fallback
+description: Update CLAUDE.md for git-changed modules using batched agent execution (4 modules/agent) with gemini→qwen→codex fallback, <15 modules uses direct execution
 argument-hint: "[--tool gemini|qwen|codex]"
 ---
 
@@ -39,12 +39,12 @@ Orchestrates context-aware CLAUDE.md updates for changed modules using batched a
 
 ## Phase 1: Change Detection & Analysis
 
-```bash
-# Detect changed modules (no index refresh needed)
-bash(~/.claude/scripts/detect_changed_modules.sh list)
+```javascript
+// Detect changed modules
+Bash({command: "~/.claude/scripts/detect_changed_modules.sh list", run_in_background: false});
 
-# Cache git changes
-bash(git add -A 2>/dev/null || true)
+// Cache git changes
+Bash({command: "git add -A 2>/dev/null || true", run_in_background: false});
 ```
 
 **Parse output** `depth:N|path:<PATH>|change:<TYPE>` to extract affected modules.
@@ -89,47 +89,36 @@ Related Update Plan:
 
 ## Phase 3A: Direct Execution (<15 modules)
 
-**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead, tool fallback per module.
+**Strategy**: Parallel execution within depth (max 4 concurrent), no agent overhead.
+
+**CRITICAL**: All Bash commands use `run_in_background: false` for synchronous execution.
 
 ```javascript
-let modules_by_depth = group_by_depth(changed_modules);
-let tool_order = construct_tool_order(primary_tool);
-
 for (let depth of sorted_depths.reverse()) {  // N → 0
-  let modules = modules_by_depth[depth];
-  let batches = batch_modules(modules, 4);  // Split into groups of 4
+  let batches = batch_modules(modules_by_depth[depth], 4);
 
   for (let batch of batches) {
-    // Execute batch in parallel (max 4 concurrent)
     let parallel_tasks = batch.map(module => {
       return async () => {
-        let success = false;
         for (let tool of tool_order) {
-          let exit_code = bash(cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}");
-          if (exit_code === 0) {
-            report("${module.path} updated with ${tool}");
-            success = true;
-            break;
+          Bash({
+            command: `cd ${module.path} && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "${tool}"`,
+            run_in_background: false
+          });
+          if (bash_result.exit_code === 0) {
+            report(`✅ ${module.path} updated with ${tool}`);
+            return true;
           }
         }
-        if (!success) {
-          report("FAILED: ${module.path} failed all tools");
-        }
+        report(`❌ FAILED: ${module.path} failed all tools`);
+        return false;
       };
     });
-
-    await Promise.all(parallel_tasks.map(task => task()));  // Run batch in parallel
+    await Promise.all(parallel_tasks.map(task => task()));
   }
 }
 ```
 
-**Benefits**:
-- No agent startup overhead
-- Parallel execution within depth (max 4 concurrent)
-- Tool fallback still applies per module
-- Faster for small changesets (<15 modules)
-- Same batching strategy as Phase 3B but without agent layer
-
 ---
 
 ## Phase 3B: Agent Batch Execution (≥15 modules)
@@ -193,19 +182,27 @@ TOOLS (try in order):
 
 EXECUTION:
 For each module above:
-  1. cd "{{module_path}}"
-  2. Try tool 1:
-     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}")
-     → Success: Report "{{module_path}} updated with {{tool_1}}", proceed to next module
+  1. Try tool 1:
+     Bash({
+       command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_1}}"`,
+       run_in_background: false
+     })
+     → Success: Report "✅ {{module_path}} updated with {{tool_1}}", proceed to next module
      → Failure: Try tool 2
-  3. Try tool 2:
-     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}")
-     → Success: Report "{{module_path}} updated with {{tool_2}}", proceed to next module
+  2. Try tool 2:
+     Bash({
+       command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_2}}"`,
+       run_in_background: false
+     })
+     → Success: Report "✅ {{module_path}} updated with {{tool_2}}", proceed to next module
      → Failure: Try tool 3
-  4. Try tool 3:
-     bash(cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}")
-     → Success: Report "{{module_path}} updated with {{tool_3}}", proceed to next module
-     → Failure: Report "FAILED: {{module_path}} failed all tools", proceed to next module
+  3. Try tool 3:
+     Bash({
+       command: `cd "{{module_path}}" && ~/.claude/scripts/update_module_claude.sh "single-layer" "." "{{tool_3}}"`,
+       run_in_background: false
+     })
+     → Success: Report "✅ {{module_path}} updated with {{tool_3}}", proceed to next module
+     → Failure: Report "❌ FAILED: {{module_path}} failed all tools", proceed to next module
 
 REPORTING:
 Report final summary with:
@@ -213,30 +210,16 @@ Report final summary with:
 - Successful: Y modules
 - Failed: Z modules
 - Tool usage: {{tool_1}}:X, {{tool_2}}:Y, {{tool_3}}:Z
-- Detailed results for each module
 ```
 
-### Example Execution
-
-**Depth 3 (new module)**:
-```javascript
-Task(subagent_type="memory-bridge", batch=[./src/api/auth], mode="related")
-```
-
-**Benefits**:
-- 4 modules → 1 agent (75% reduction)
-- Parallel batches, sequential within batch
-- Each module gets full fallback chain
-- Context-aware updates based on git changes
-
 ## Phase 4: Safety Verification
 
-```bash
-# Check only CLAUDE.md modified
-bash(git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified")
+```javascript
+// Check only CLAUDE.md modified
+Bash({command: 'git diff --cached --name-only | grep -v "CLAUDE.md" || echo "Only CLAUDE.md files modified"', run_in_background: false});
 
-# Display statistics
-bash(git diff --stat)
+// Display statistics
+Bash({command: "git diff --stat", run_in_background: false});
 ```
 
 **Aggregate results**:

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

@@ -0,0 +1,517 @@
+---
+name: workflow-skill-memory
+description: Process WFS-* archived sessions using universal-executor agents with Gemini analysis to generate workflow-progress SKILL package (sessions-timeline, lessons, conflicts)
+argument-hint: "session <session-id> | all"
+allowed-tools: Task(*), TodoWrite(*), Bash(*), Read(*), Write(*)
+---
+
+# Workflow SKILL Memory Generator
+
+## Overview
+
+Generate SKILL package from archived workflow sessions using agent-driven analysis. Supports single-session incremental updates or parallel processing of all sessions.
+
+**Scope**: Only processes WFS-* workflow sessions. Other session types (e.g., doc sessions) are automatically ignored.
+
+## Usage
+
+```bash
+/memory:workflow-skill-memory session WFS-<session-id>   # Process single WFS session
+/memory:workflow-skill-memory all                        # Process all WFS sessions in parallel
+```
+
+## Execution Modes
+
+### Mode 1: Single Session (`session <session-id>`)
+
+**Purpose**: Incremental update - process one archived session and merge into existing SKILL package
+
+**Workflow**:
+1. **Validate session**: Check if session exists in `.workflow/.archives/{session-id}/`
+2. **Invoke agent**: Call `universal-executor` to analyze session and update SKILL documents
+3. **Agent tasks**:
+   - Read session data from `.workflow/.archives/{session-id}/`
+   - Extract lessons, conflicts, and outcomes
+   - Use Gemini for intelligent aggregation (optional)
+   - Update or create SKILL documents using templates
+   - Regenerate SKILL.md index
+
+**Command Example**:
+```bash
+/memory:workflow-skill-memory session WFS-user-auth
+```
+
+**Expected Output**:
+```
+Session WFS-user-auth processed
+Updated:
+- sessions-timeline.md (1 session added)
+- lessons-learned.md (3 lessons merged)
+- conflict-patterns.md (1 conflict added)
+- SKILL.md (index regenerated)
+```
+
+---
+
+### Mode 2: All Sessions (`all`)
+
+**Purpose**: Full regeneration - process all archived sessions in parallel for complete SKILL package
+
+**Workflow**:
+1. **List sessions**: Read manifest.json to get all archived session IDs
+2. **Parallel invocation**: Launch multiple `universal-executor` agents in parallel (one per session)
+3. **Agent coordination**:
+   - Each agent processes one session independently
+   - Agents use Gemini for analysis
+   - Agents collect data into JSON (no direct file writes)
+   - Final aggregator agent merges results and generates SKILL documents
+
+**Command Example**:
+```bash
+/memory:workflow-skill-memory all
+```
+
+**Expected Output**:
+```
+All sessions processed in parallel
+Sessions: 8 total
+Updated:
+- sessions-timeline.md (8 sessions)
+- lessons-learned.md (24 lessons aggregated)
+- conflict-patterns.md (12 conflicts documented)
+- SKILL.md (index regenerated)
+```
+
+---
+
+## Implementation Flow
+
+### Phase 1: Validation and Setup
+
+**Step 1.1: Parse Command Arguments**
+
+Extract mode and session ID:
+```javascript
+if (args === "all") {
+  mode = "all"
+} else if (args.startsWith("session ")) {
+  mode = "session"
+  session_id = args.replace("session ", "").trim()
+} else {
+  ERROR = "Invalid arguments. Usage: session <session-id> | all"
+  EXIT
+}
+```
+
+**Step 1.2: Validate Archive Directory**
+```bash
+bash(test -d .workflow/.archives && echo "exists" || echo "missing")
+```
+
+If missing, report error and exit.
+
+**Step 1.3: Mode-Specific Validation**
+
+**Single Session Mode**:
+```bash
+# Validate session ID format (must start with WFS-)
+if [[ ! "$session_id" =~ ^WFS- ]]; then
+  ERROR = "Invalid session ID format. Only WFS-* sessions are supported"
+  EXIT
+fi
+
+# Check if session exists
+bash(test -d .workflow/.archives/{session_id} && echo "exists" || echo "missing")
+```
+
+If missing, report error: "Session {session_id} not found in archives"
+
+**All Sessions Mode**:
+```bash
+# Read manifest and filter only WFS- sessions
+bash(cat .workflow/.archives/manifest.json | jq -r '.archives[].session_id | select(startswith("WFS-"))')
+```
+
+Store filtered session IDs in array. Ignore doc sessions and other non-WFS sessions.
+
+**Step 1.4: TodoWrite Initialization**
+
+**Single Session Mode**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Validate session existence", "status": "completed", "activeForm": "Validating session"},
+  {"content": "Invoke agent to process session", "status": "in_progress", "activeForm": "Invoking agent"},
+  {"content": "Verify SKILL package updated", "status": "pending", "activeForm": "Verifying update"}
+]})
+```
+
+**All Sessions Mode**:
+```javascript
+TodoWrite({todos: [
+  {"content": "Read manifest and list sessions", "status": "completed", "activeForm": "Reading manifest"},
+  {"content": "Invoke agents in parallel", "status": "in_progress", "activeForm": "Invoking agents"},
+  {"content": "Verify SKILL package regenerated", "status": "pending", "activeForm": "Verifying regeneration"}
+]})
+```
+
+---
+
+### Phase 2: Agent Invocation
+
+#### Single Session Mode - Agent Task
+
+Invoke `universal-executor` with session-specific task:
+
+**Agent Prompt Structure**:
+```
+Task: Process Workflow Session for SKILL Package
+
+Context:
+- Session ID: {session_id}
+- Session Path: .workflow/.archives/{session_id}/
+- Mode: Incremental update
+
+Objectives:
+
+1. Read session data:
+   - workflow-session.json (metadata)
+   - IMPL_PLAN.md (implementation summary)
+   - TODO_LIST.md (if exists)
+   - manifest.json entry for lessons
+
+2. Extract key information:
+   - Description, tags, metrics
+   - Lessons (successes, challenges, watch_patterns)
+   - Context package path (reference only)
+   - Key outcomes from IMPL_PLAN
+
+3. Use Gemini for aggregation (optional):
+   Command pattern:
+   cd .workflow/.archives/{session_id} && gemini -p "
+   PURPOSE: Extract lessons and conflicts from workflow session
+   TASK:
+   • Analyze IMPL_PLAN and lessons from manifest
+   • Identify success patterns and challenges
+   • Extract conflict patterns with resolutions
+   • Categorize by functional domain
+   MODE: analysis
+   CONTEXT: @IMPL_PLAN.md @workflow-session.json
+   EXPECTED: Structured lessons and conflicts in JSON format
+   RULES: Template reference from skill-aggregation.txt
+   "
+
+3.5. **Generate SKILL.md Description** (CRITICAL for auto-loading):
+
+   Read skill-index.txt template Section: "Description Field Generation"
+
+   Execute command to get project root:
+   ```bash
+   git rev-parse --show-toplevel  # Example output: /d/Claude_dms3
+   ```
+
+   Apply description format:
+   ```
+   Progressive workflow development history (located at {project_root}).
+   Load this SKILL when continuing development, analyzing past implementations,
+   or learning from workflow history, especially when no relevant context exists in memory.
+   ```
+
+   **Validation**:
+   - [ ] Path uses forward slashes (not backslashes)
+   - [ ] All three use cases present
+   - [ ] Trigger optimization phrase included
+   - [ ] Path is absolute (starts with / or drive letter)
+
+4. Read templates for formatting guidance:
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-sessions-timeline.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-lessons-learned.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-conflict-patterns.txt
+   - ~/.claude/workflows/cli-templates/prompts/workflow/skill-index.txt
+
+   **CRITICAL**: From skill-index.txt, read these sections:
+   - "Description Field Generation" - Rules for generating description
+   - "Variable Substitution Guide" - All required variables
+   - "Generation Instructions" - Step-by-step generation process
+   - "Validation Checklist" - Final validation steps
+
+5. Update SKILL documents:
+   - sessions-timeline.md: Append new session, update domain grouping
+   - lessons-learned.md: Merge lessons into categories, update frequencies
+   - conflict-patterns.md: Add conflicts, update recurring pattern frequencies
+   - SKILL.md: Regenerate index with updated counts
+
+   **For SKILL.md generation**:
+   - Follow "Generation Instructions" from skill-index.txt (Steps 1-7)
+   - Use git command for project_root: `git rev-parse --show-toplevel`
+   - Apply "Description Field Generation" rules
+   - Validate using "Validation Checklist"
+   - Increment version (patch level)
+
+6. Return result JSON:
+   {
+     "status": "success",
+     "session_id": "{session_id}",
+     "updates": {
+       "sessions_added": 1,
+       "lessons_merged": count,
+       "conflicts_added": count
+     }
+   }
+```
+
+---
+
+#### All Sessions Mode - Parallel Agent Tasks
+
+**Step 2.1: Launch parallel session analyzers**
+
+Invoke multiple agents in parallel (one message with multiple Task calls):
+
+**Per-Session Agent Prompt**:
+```
+Task: Extract Session Data for SKILL Package
+
+Context:
+- Session ID: {session_id}
+- Mode: Parallel analysis (no direct file writes)
+
+Objectives:
+
+1. Read session data (same as single mode)
+
+2. Extract key information (same as single mode)
+
+3. Use Gemini for analysis (same as single mode)
+
+4. Return structured data JSON:
+   {
+     "status": "success",
+     "session_id": "{session_id}",
+     "data": {
+       "metadata": {
+         "description": "...",
+         "archived_at": "...",
+         "tags": [...],
+         "metrics": {...}
+       },
+       "lessons": {
+         "successes": [...],
+         "challenges": [...],
+         "watch_patterns": [...]
+       },
+       "conflicts": [
+         {
+           "type": "architecture|dependencies|testing|performance",
+           "pattern": "...",
+           "resolution": "...",
+           "code_impact": [...]
+         }
+       ],
+       "impl_summary": "First 200 chars of IMPL_PLAN",
+       "context_package_path": "..."
+     }
+   }
+```
+
+**Step 2.2: Aggregate results**
+
+After all session agents complete, invoke aggregator agent:
+
+**Aggregator Agent Prompt**:
+```
+Task: Aggregate Session Results and Generate SKILL Package
+
+Context:
+- Mode: Full regeneration
+- Input: JSON results from {session_count} session agents
+
+Objectives:
+
+1. Aggregate all session data:
+   - Collect metadata from all sessions
+   - Merge lessons by category
+   - Group conflicts by type
+   - Sort sessions by date
+
+2. Use Gemini for final aggregation:
+   gemini -p "
+   PURPOSE: Aggregate lessons and conflicts from all workflow sessions
+   TASK:
+   • Group successes by functional domain
+   • Categorize challenges by severity (HIGH/MEDIUM/LOW)
+   • Identify recurring conflict patterns
+   • Calculate frequencies and prioritize
+   MODE: analysis
+   CONTEXT: [Provide aggregated JSON data]
+   EXPECTED: Final aggregated structure for SKILL documents
+   RULES: Template reference from skill-aggregation.txt
+   "
+
+3. Read templates for formatting (same 4 templates as single mode)
+
+4. Generate all SKILL documents:
+   - sessions-timeline.md (all sessions, sorted by date)
+   - lessons-learned.md (aggregated lessons with frequencies)
+   - conflict-patterns.md (recurring patterns with resolutions)
+   - SKILL.md (index with progressive loading)
+
+5. Write files to .claude/skills/workflow-progress/
+
+6. Return result JSON:
+   {
+     "status": "success",
+     "sessions_processed": count,
+     "files_generated": ["SKILL.md", "sessions-timeline.md", ...],
+     "summary": {
+       "total_sessions": count,
+       "functional_domains": [...],
+       "date_range": "...",
+       "lessons_count": count,
+       "conflicts_count": count
+     }
+   }
+```
+
+---
+
+### Phase 3: Verification
+
+**Step 3.1: Check SKILL Package Files**
+```bash
+bash(ls -lh .claude/skills/workflow-progress/)
+```
+
+Verify all 4 files exist:
+- SKILL.md
+- sessions-timeline.md
+- lessons-learned.md
+- conflict-patterns.md
+
+**Step 3.2: TodoWrite Completion**
+
+Mark all tasks as completed.
+
+**Step 3.3: Display Summary**
+
+**Single Session Mode**:
+```
+Session {session_id} processed successfully
+
+Updated:
+- sessions-timeline.md
+- lessons-learned.md
+- conflict-patterns.md
+- SKILL.md
+
+SKILL Location: .claude/skills/workflow-progress/SKILL.md
+```
+
+**All Sessions Mode**:
+```
+All sessions processed in parallel
+
+Sessions: {count} total
+Functional Domains: {domain_list}
+Date Range: {earliest} - {latest}
+
+Generated:
+- sessions-timeline.md ({count} sessions)
+- lessons-learned.md ({lessons_count} lessons)
+- conflict-patterns.md ({conflicts_count} conflicts)
+- SKILL.md (4-level progressive loading)
+
+SKILL Location: .claude/skills/workflow-progress/SKILL.md
+
+Usage:
+- Level 0: Quick refresh (~2K tokens)
+- Level 1: Recent history (~8K tokens)
+- Level 2: Complete analysis (~25K tokens)
+- Level 3: Deep dive (~40K tokens)
+```
+
+---
+
+## Agent Guidelines
+
+### Agent Capabilities
+
+**universal-executor agents can**:
+- Read files from `.workflow/.archives/`
+- Execute bash commands
+- Call Gemini CLI for intelligent analysis
+- Read template files for formatting guidance
+- Write SKILL package files (single mode) or return JSON (parallel mode)
+- Return structured results
+
+### Gemini Usage Pattern
+
+**When to use Gemini**:
+- Aggregating lessons from multiple sources
+- Identifying recurring patterns
+- Classifying conflicts by type and severity
+- Extracting structured data from IMPL_PLAN
+
+**Fallback Strategy**: If Gemini fails or times out, use direct file parsing with structured extraction logic.
+
+---
+
+## Template System
+
+### Template Files
+
+All templates located in: `~/.claude/workflows/cli-templates/prompts/workflow/`
+
+1. **skill-sessions-timeline.txt**: Format for sessions-timeline.md
+2. **skill-lessons-learned.txt**: Format for lessons-learned.md
+3. **skill-conflict-patterns.txt**: Format for conflict-patterns.md
+4. **skill-index.txt**: Format for SKILL.md index
+5. **skill-aggregation.txt**: Rules for Gemini aggregation (existing)
+
+### Template Usage in Agent
+
+**Agents read templates to understand**:
+- File structure and markdown format
+- Data sources (which files to read)
+- Update strategy (incremental vs full)
+- Formatting rules and conventions
+- Aggregation logic (for Gemini)
+
+**Templates are NOT shown in this command documentation** - agents read them directly as needed.
+
+---
+
+## Error Handling
+
+### Validation Errors
+- **No archives directory**: "Error: No workflow archives found at .workflow/.archives/"
+- **Invalid session ID format**: "Error: Invalid session ID format. Only WFS-* sessions are supported"
+- **Session not found**: "Error: Session {session_id} not found in archives"
+- **No WFS sessions in manifest**: "Error: No WFS-* workflow sessions found in manifest.json"
+
+### Agent Errors
+- If agent fails, report error message from agent result
+- If Gemini times out, agents use fallback direct parsing
+- If template read fails, agents use inline format
+
+### Recovery
+- Single session mode: Can be retried without affecting other sessions
+- All sessions mode: If one agent fails, others continue; retry failed sessions individually
+
+
+
+## Integration
+
+### Called by `/workflow:session:complete`
+
+Automatically invoked after session archival:
+```bash
+SlashCommand(command="/memory:workflow-skill-memory session {session_id}")
+```
+
+### Manual Invocation
+
+Users can manually process sessions:
+```bash
+/memory:workflow-skill-memory session WFS-custom-feature  # Single session
+/memory:workflow-skill-memory all                         # Full regeneration
+```

.claude/commands/task/breakdown.md

@@ -1,6 +1,6 @@
 ---
 name: breakdown
-description: Intelligent task decomposition with context-aware subtask generation
+description: Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order
 argument-hint: "task-id"
 ---
 
@@ -15,7 +15,7 @@ Breaks down complex tasks into executable subtasks with context inheritance and
 
 ## Core Features
 
-⚠️ **CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
+**CRITICAL**: Manual breakdown with safety controls to prevent file conflicts and task limit violations.
 
 ### Breakdown Process
 1. **Session Check**: Verify active session contains parent task
@@ -50,7 +50,7 @@ Interactive process:
 Task: Build authentication module
 Current total tasks: 6/10
 
-⚠️  MANUAL BREAKDOWN REQUIRED
+MANUAL BREAKDOWN REQUIRED
 Define subtasks manually (remaining capacity: 4 tasks):
 
 1. Enter subtask title: User authentication core
@@ -59,11 +59,11 @@ Define subtasks manually (remaining capacity: 4 tasks):
 2. Enter subtask title: OAuth integration
    Focus files: services/OAuthService.js, routes/oauth.js
 
-⚠️  FILE CONFLICT DETECTED:
+FILE CONFLICT DETECTED:
    - routes/auth.js appears in multiple subtasks
    - Recommendation: Merge related authentication routes
 
-⚠️  SIMILAR FUNCTIONALITY WARNING:
+SIMILAR FUNCTIONALITY WARNING:
    - "User authentication" and "OAuth integration" both handle auth
    - Consider combining into single task
 
@@ -83,10 +83,10 @@ AskUserQuestion({
 
 User selected: "Proceed with breakdown"
 
-✅ Task IMPL-1 broken down:
-▸ IMPL-1: Build authentication module (container)
-  ├── IMPL-1.1: User authentication core → @code-developer
-  └── IMPL-1.2: OAuth integration → @code-developer
+Task IMPL-1 broken down:
+IMPL-1: Build authentication module (container)
+  ├── IMPL-1.1: User authentication core -> @code-developer
+  └── IMPL-1.2: OAuth integration -> @code-developer
 
 Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 ```
@@ -167,45 +167,38 @@ Files updated: .task/IMPL-1.json + 2 subtask files + TODO_LIST.md
 ```bash
 /task:breakdown impl-1
 
-▸ impl-1: Build authentication (container)
-  ├── impl-1.1: Design schema → @planning-agent
-  ├── impl-1.2: Implement logic + tests → @code-developer
-  └── impl-1.3: Execute & fix tests → @test-fix-agent
+impl-1: Build authentication (container)
+  ├── impl-1.1: Design schema -> @planning-agent
+  ├── impl-1.2: Implement logic + tests -> @code-developer
+  └── impl-1.3: Execute & fix tests -> @test-fix-agent
 ```
 
 ## Error Handling
 
 ```bash
 # Task not found
-❌ Task IMPL-5 not found
+Task IMPL-5 not found
 
 # Already broken down
-⚠️ Task IMPL-1 already has subtasks
+Task IMPL-1 already has subtasks
 
 # Wrong status
-❌ Cannot breakdown completed task IMPL-2
+Cannot breakdown completed task IMPL-2
 
 # 10-task limit exceeded
-❌ Breakdown would exceed 10-task limit (current: 8, proposed: 4)
-   Suggestion: Re-scope project into smaller iterations
+Breakdown would exceed 10-task limit (current: 8, proposed: 4)
+Suggestion: Re-scope project into smaller iterations
 
 # File conflicts detected
-⚠️ File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
-   Recommendation: Merge subtasks or redistribute files
+File conflict: routes/auth.js appears in IMPL-1.1 and IMPL-1.2
+Recommendation: Merge subtasks or redistribute files
 
 # Similar functionality warning
-⚠️ Similar functions detected: "user login" and "authentication"
-   Consider consolidating related functionality
+Similar functions detected: "user login" and "authentication"
+Consider consolidating related functionality
 
 # Manual breakdown required
-❌ Automatic breakdown disabled. Use manual breakdown process.
+Automatic breakdown disabled. Use manual breakdown process.
 ```
 
-## Related Commands
-
-- `/task:create` - Create new tasks
-- `/task:execute` - Execute subtasks
-- `/workflow:status` - View task hierarchy
-- `/workflow:plan` - Plan within 10-task limit
-
 **System ensures**: Manual breakdown control with file cohesion enforcement, similar functionality detection, and 10-task limit compliance

.claude/commands/task/create.md

@@ -1,6 +1,6 @@
 ---
 name: create
-description: Create implementation tasks with automatic context awareness
+description: Generate task JSON from natural language description with automatic file pattern detection, scope inference, and dependency analysis
 argument-hint: "\"task title\""
 ---
 
@@ -37,7 +37,7 @@ Creates new implementation tasks with automatic context awareness and ID generat
 
 Output:
 ```
-✅ Task created: IMPL-1
+Task created: IMPL-1
 Title: Build authentication module
 Type: feature
 Agent: code-developer
@@ -73,7 +73,7 @@ Status: pending
 ### Analysis Triggers
 When implementation details incomplete:
 ```bash
-⚠️ Task requires analysis for implementation details
+Task requires analysis for implementation details
 Suggest running: gemini analysis for file locations and dependencies
 ```
 
@@ -117,16 +117,16 @@ Based on task type and title keywords:
 
 ```bash
 # No workflow session
-❌ No active workflow found
-→ Use: /workflow init "project name"
+No active workflow found
+Use: /workflow init "project name"
 
 # Duplicate task
-⚠️ Similar task exists: IMPL-3
-→ Continue anyway? (y/n)
+Similar task exists: IMPL-3
+Continue anyway? (y/n)
 
 # Max depth exceeded
-❌ Cannot create IMPL-1.2.1 (max 2 levels)
-→ Use: IMPL-2 for new main task
+Cannot create IMPL-1.2.1 (max 2 levels)
+Use: IMPL-2 for new main task
 ```
 
 ## Examples
@@ -135,7 +135,7 @@ Based on task type and title keywords:
 ```bash
 /task:create "Implement user authentication"
 
-✅ Created IMPL-1: Implement user authentication
+Created IMPL-1: Implement user authentication
 Type: feature
 Agent: code-developer
 Status: pending
@@ -145,14 +145,8 @@ Status: pending
 ```bash
 /task:create "Fix login validation bug" --type=bugfix
 
-✅ Created IMPL-2: Fix login validation bug
+Created IMPL-2: Fix login validation bug
 Type: bugfix
 Agent: code-developer
 Status: pending
-```
-
-## Related Commands
-
-- `/task:breakdown` - Break into subtasks
-- `/task:execute` - Execute with agent
-- `/context` - View task details
+```

.claude/commands/task/execute.md

@@ -1,15 +1,15 @@
 ---
 name: execute
-description: Execute tasks with appropriate agents and context-aware orchestration
+description: Execute task JSON using appropriate agent (@doc-generator/@implementation-agent/@test-agent) with pre-analysis context loading and status tracking
 argument-hint: "task-id"
 ---
 
-### 🚀 **Command Overview: `/task:execute`**
+## Command Overview: /task:execute
 
--   **Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
+**Purpose**: Executes tasks using intelligent agent selection, context preparation, and progress tracking.
 
 
-### ⚙️ **Execution Modes**
+## Execution Modes
 
 -   **auto (Default)**
     -   Fully autonomous execution with automatic agent selection.
@@ -22,7 +22,7 @@ argument-hint: "task-id"
     -   Optional manual review using `@universal-executor`.
     -   Used only when explicitly requested by user.
 
-### 🤖 **Agent Selection Logic**
+## Agent Selection Logic
 
 The system determines the appropriate agent for a task using the following logic.
 
@@ -52,11 +52,11 @@ FUNCTION select_agent(task, agent_override):
 END FUNCTION
 ```
 
-### 🔄 **Core Execution Protocol**
+## Core Execution Protocol
 
-`Pre-Execution` **->** `Execution` **->** `Post-Execution`
+`Pre-Execution` -> `Execution` -> `Post-Execution`
 
-### ✅ **Pre-Execution Protocol**
+### Pre-Execution Protocol
 
 `Validate Task & Dependencies` **->** `Prepare Execution Context` **->** `Coordinate with TodoWrite`
 
@@ -65,7 +65,7 @@ END FUNCTION
 -   **Session Context Injection**: Provides workflow directory paths to agents for TODO_LIST.md and summary management.
 -   **TodoWrite Coordination**: Generates execution Todos and checkpoints, syncing with `TODO_LIST.md`.
 
-### 🏁 **Post-Execution Protocol**
+### Post-Execution Protocol
 
 `Update Task Status` **->** `Generate Summary` **->** `Save Artifacts` **->** `Sync All Progress` **->** `Validate File Integrity`
 
@@ -73,7 +73,7 @@ END FUNCTION
 -   Creates a summary in `.summaries/`.
 -   Stores outputs and syncs progress across the entire workflow session.
 
-### 🧠 **Task & Subtask Execution Logic**
+### Task & Subtask Execution Logic
 
 This logic defines how single, multiple, or parent tasks are handled.
 
@@ -99,7 +99,7 @@ FUNCTION execute_task_command(task_id, mode, parallel_flag):
 END FUNCTION
 ```
 
-### 🛡️ **Error Handling & Recovery Logic**
+### Error Handling & Recovery Logic
 
 ```pseudo
 FUNCTION pre_execution_check(task):
@@ -124,7 +124,7 @@ END FUNCTION
 ```
 
 
-### 📄 **Simplified Context Structure (JSON)**
+### Simplified Context Structure (JSON)
 
 This is the simplified data structure loaded to provide context for task execution.
 
@@ -189,7 +189,7 @@ This is the simplified data structure loaded to provide context for task executi
       "pre_analysis": [
         {
           "action": "analyze patterns",
-          "template": "~/.claude/workflows/cli-templates/prompts/analysis/pattern.txt",
+          "template": "~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt",
           "method": "gemini"
         }
       ]
@@ -199,10 +199,10 @@ This is the simplified data structure loaded to provide context for task executi
     "session": "WFS-user-auth",
     "phase": "IMPLEMENT",
     "session_context": {
-      "workflow_directory": ".workflow/WFS-user-auth/",
-      "todo_list_location": ".workflow/WFS-user-auth/TODO_LIST.md",
-      "summaries_directory": ".workflow/WFS-user-auth/.summaries/",
-      "task_json_location": ".workflow/WFS-user-auth/.task/"
+      "workflow_directory": ".workflow/active/WFS-user-auth/",
+      "todo_list_location": ".workflow/active/WFS-user-auth/TODO_LIST.md",
+      "summaries_directory": ".workflow/active/WFS-user-auth/.summaries/",
+      "task_json_location": ".workflow/active/WFS-user-auth/.task/"
     }
   },
   "execution": {
@@ -213,7 +213,7 @@ This is the simplified data structure loaded to provide context for task executi
 }
 ```
 
-### 🎯 **Agent-Specific Context**
+### Agent-Specific Context
 
 Different agents receive context tailored to their function, including implementation details:
 
@@ -243,13 +243,13 @@ Different agents receive context tailored to their function, including implement
 - Dependency validation from implementation.context_notes.dependencies
 - Architecture compliance checks
 
-### 🗃️ **Simplified File Output**
+### Simplified File Output
 
 -   **Task JSON File (`.task/<task-id>.json`)**: Updated with status and last attempt time only.
 -   **Session File (`workflow-session.json`)**: Updated task stats (completed count).
 -   **Summary File**: Generated in `.summaries/` upon completion (optional).
 
-### 📝 **Simplified Summary Template**
+### Simplified Summary Template
 
 Optional summary file generated at `.summaries/IMPL-[task-id]-summary.md`.
 

.claude/commands/task/replan.md

@@ -1,12 +1,20 @@
 ---
 name: replan
-description: Replan individual tasks with detailed user input and change tracking
+description: Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json
 argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
 # Task Replan Command (/task:replan)
 
+> **⚠️ DEPRECATION NOTICE**: This command is maintained for backward compatibility. For new workflows, use `/workflow:replan` which provides:
+> - Session-level replanning with comprehensive artifact updates
+> - Interactive boundary clarification
+> - Updates to IMPL_PLAN.md, TODO_LIST.md, and session metadata
+> - Better integration with workflow sessions
+>
+> **Migration**: Replace `/task:replan IMPL-1 "changes"` with `/workflow:replan IMPL-1 "changes"`
+
 ## Overview
 Replans individual tasks or batch processes multiple tasks with change tracking and backup management.
 
@@ -14,9 +22,6 @@ Replans individual tasks or batch processes multiple tasks with change tracking
 - **Single Task Mode**: Replan one task with specific changes
 - **Batch Mode**: Process multiple tasks from action-plan verification report
 
-## Core Principles
-**Task System:** @~/.claude/workflows/task-core.md
-
 ## Key Features
 - **Single/Batch Operations**: Single task or multiple tasks from verification report
 - **Multiple Input Sources**: Text, files, or verification report
@@ -24,7 +29,7 @@ Replans individual tasks or batch processes multiple tasks with change tracking
 - **Change Documentation**: Track all modifications
 - **Progress Tracking**: TodoWrite integration for batch operations
 
-⚠️ **CRITICAL**: Validates active session before replanning
+**CRITICAL**: Validates active session before replanning
 
 ## Operation Modes
 
@@ -189,7 +194,7 @@ AskUserQuestion({
 
 User selected: "Yes, rollback"
 
-✅ Task rolled back to version 1.1
+Task rolled back to version 1.1
 ```
 
 ## Batch Processing with TodoWrite
@@ -201,7 +206,7 @@ When processing multiple tasks, automatically creates TodoWrite task list:
 **Batch Replan Progress**:
 - [x] IMPL-002: Add FR-12 draft saving acceptance criteria
 - [x] IMPL-003: Add FR-14 history tracking acceptance criteria
-- [⧗] IMPL-004: Add FR-09 response surface explicit coverage
+- [ ] IMPL-004: Add FR-09 response surface explicit coverage
 - [ ] IMPL-008: Add NFR performance validation steps
 ```
 
@@ -255,9 +260,9 @@ AskUserQuestion({
 
 User selected: "Yes, apply"
 
-✓ Version 1.2 created
-✓ Context updated
-✓ Backup saved to .task/backup/IMPL-1-v1.1.json
+Version 1.2 created
+Context updated
+Backup saved to .task/backup/IMPL-1-v1.1.json
 ```
 
 ### Single Task - File Input
@@ -267,14 +272,14 @@ User selected: "Yes, apply"
 Loading requirements.md...
 Applying specification changes...
 
-✓ Task updated with new requirements
-✓ Version 1.1 created
-✓ Backup saved to .task/backup/IMPL-2-v1.0.json
+Task updated with new requirements
+Version 1.1 created
+Backup saved to .task/backup/IMPL-2-v1.0.json
 ```
 
 ### Batch Mode - From Verification Report
 ```bash
-/task:replan --batch .workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
+/task:replan --batch .workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md
 
 Parsing verification report...
 Found 4 tasks requiring replanning:
@@ -286,23 +291,23 @@ Found 4 tasks requiring replanning:
 Creating task tracking list...
 
 Processing IMPL-002...
-✓ Backup created: .task/backup/IMPL-002-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-002-v1.0.json
+Updated to v1.1
 
 Processing IMPL-003...
-✓ Backup created: .task/backup/IMPL-003-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-003-v1.0.json
+Updated to v1.1
 
 Processing IMPL-004...
-✓ Backup created: .task/backup/IMPL-004-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-004-v1.0.json
+Updated to v1.1
 
 Processing IMPL-008...
-✓ Backup created: .task/backup/IMPL-008-v1.0.json
-✓ Updated to v1.1
+Backup created: .task/backup/IMPL-008-v1.0.json
+Updated to v1.1
 
-✅ Batch replan completed: 4/4 successful
-📋 Summary report saved
+Batch replan completed: 4/4 successful
+Summary report saved
 ```
 
 ### Batch Mode - Auto-detection
@@ -320,35 +325,35 @@ Entering batch mode...
 ### Single Task Errors
 ```bash
 # Task not found
-❌ Task IMPL-5 not found
-→ Check task ID with /workflow:status
+Task IMPL-5 not found
+Check task ID with /workflow:status
 
 # Task completed
-⚠️ Task IMPL-1 is completed (cannot replan)
-→ Create new task for additional work
+Task IMPL-1 is completed (cannot replan)
+Create new task for additional work
 
 # File not found
-❌ File requirements.md not found
-→ Check file path
+File requirements.md not found
+Check file path
 
 # No input provided
-❌ Please specify changes needed
-→ Provide text, file, or verification report
+Please specify changes needed
+Provide text, file, or verification report
 ```
 
 ### Batch Mode Errors
 ```bash
 # Invalid verification report
-❌ File does not contain valid verification report format
-→ Check report structure or use single task mode
+File does not contain valid verification report format
+Check report structure or use single task mode
 
 # Partial failures
-⚠️ Batch completed with errors: 3/4 successful
-→ Review error details in summary report
+Batch completed with errors: 3/4 successful
+Review error details in summary report
 
 # No replan recommendations found
-❌ Verification report contains no replan recommendations
-→ Check report content or use /workflow:action-plan-verify first
+Verification report contains no replan recommendations
+Check report content or use /workflow:action-plan-verify first
 ```
 
 ## Batch Mode Integration
@@ -429,16 +434,4 @@ TodoWrite({
 TodoWrite({
   todos: updateTaskStatus(taskId, "completed")
 });
-```
-
-## Related Commands
-
-- `/workflow:status` - View task structure and versions
-- `/workflow:action-plan-verify` - Generate verification report for batch mode
-- `/task:execute` - Execute replanned task
-- `/task:create` - Create new tasks
-- `/task:breakdown` - Break down complex tasks
-
-## Context
-
-$ARGUMENTS
+```

.claude/commands/version.md

@@ -1,6 +1,6 @@
 ---
 name: version
-description: Display version information and check for updates
+description: Display Claude Code version information and check for updates
 allowed-tools: Bash(*)
 ---
 
@@ -152,12 +152,12 @@ bash(printf "%s\n%s" "3.2.1" "3.2.2" | sort -V | tail -n 1)
 
 **Scenario 1: Up to date**
 ```
-✅ You are on the latest stable version (3.2.1)
+You are on the latest stable version (3.2.1)
 ```
 
 **Scenario 2: Upgrade available**
 ```
-⬆️ A newer stable version is available: v3.2.2
+A newer stable version is available: v3.2.2
 Your version: 3.2.1
 
 To upgrade:
@@ -167,7 +167,7 @@ Bash: bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-W
 
 **Scenario 3: Development version**
 ```
-✨ You are running a development version (3.4.0-dev)
+You are running a development version (3.4.0-dev)
 This is newer than the latest stable release (v3.3.0)
 ```
 
@@ -252,7 +252,3 @@ ERROR: version.json is invalid or corrupted
 
 ### 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

@@ -1,6 +1,6 @@
 ---
 name: action-plan-verify
-description: Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution
+description: Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation
 argument-hint: "[optional: --session session-id]"
 allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
 ---
@@ -32,7 +32,7 @@ Identify inconsistencies, duplications, ambiguities, and underspecified items be
 IF --session parameter provided:
     session_id = provided session
 ELSE:
-    CHECK: .workflow/.active-* marker files
+    CHECK: find .workflow/active/ -name "WFS-*" -type d
     IF active_session EXISTS:
         session_id = get_active_session()
     ELSE:
@@ -40,7 +40,7 @@ ELSE:
         EXIT
 
 # Derive absolute paths
-session_dir = .workflow/WFS-{session}
+session_dir = .workflow/active/WFS-{session}
 brainstorm_dir = session_dir/.brainstorming
 task_dir = session_dir/.task
 
@@ -242,10 +242,10 @@ Output a Markdown report (no file writes) with the following structure:
 
 | 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** |
+| 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)
@@ -264,7 +264,7 @@ Output a Markdown report (no file writes) with the following structure:
 
 ### Dependency Graph Issues
 
-**Circular Dependencies**: None detected ✅
+**Circular Dependencies**: None detected
 
 **Broken Dependencies**:
 - IMPL-2.3 depends on "IMPL-2.4" (non-existent)
@@ -323,17 +323,17 @@ Output a Markdown report (no file writes) with the following structure:
 #### Action Recommendations
 
 **If CRITICAL Issues Exist**:
-- ❌ **BLOCK EXECUTION** - Resolve critical issues before proceeding
+- **BLOCK EXECUTION** - Resolve critical issues before proceeding
 - Use TodoWrite to track all required fixes
 - Fix broken dependencies and circular references
 
 **If Only HIGH/MEDIUM/LOW Issues**:
-- ⚠️ **PROCEED WITH CAUTION** - Fix high-priority issues first
+- **PROCEED WITH CAUTION** - Fix high-priority issues first
 - Use TodoWrite to systematically track and complete all improvements
 
 #### TodoWrite-Based Remediation Workflow
 
-**Report Location**: `.workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
+**Report Location**: `.workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md`
 
 **Recommended Workflow**:
 1. **Create TodoWrite Task List**: Extract all findings from report
@@ -361,7 +361,7 @@ Priority Order:
 
 **Save Analysis Report**:
 ```bash
-report_path = ".workflow/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
+report_path = ".workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md"
 Write(report_path, full_report_content)
 ```
 
@@ -404,12 +404,12 @@ TodoWrite([
 **File Modification Workflow**:
 ```bash
 # For task JSON modifications:
-1. Read(.workflow/WFS-{session}/.task/IMPL-X.Y.json)
+1. Read(.workflow/active/WFS-{session}/.task/IMPL-X.Y.json)
 2. Edit() to apply fixes
 3. Mark todo as completed
 
 # For IMPL_PLAN modifications:
-1. Read(.workflow/WFS-{session}/IMPL_PLAN.md)
+1. Read(.workflow/active/WFS-{session}/IMPL_PLAN.md)
 2. Edit() to apply strategic changes
 3. Mark todo as completed
 ```

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

@@ -1,6 +1,6 @@
 ---
 name: api-designer
-description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points
+description: Generate or update api-designer/analysis.md addressing guidance-specification discussion points for API design perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -46,10 +46,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -162,7 +162,7 @@ IF update_mode = "incremental":
 
 ### Output Files
 ```
-.workflow/WFS-[topic]/.brainstorming/
+.workflow/active/WFS-[topic]/.brainstorming/
 ├── guidance-specification.md          # Input: Framework (if exists)
 └── api-designer/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
@@ -181,7 +181,7 @@ IF update_mode = "incremental":
 Session detection and selection:
 ```bash
 # Check for active sessions
-active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
+active_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
 if [ multiple_sessions ]; then
   prompt_user_to_select_session()
 else
@@ -280,7 +280,7 @@ TodoWrite tracking for two-step process:
 
 ### Output Location
 ```
-.workflow/WFS-{topic-slug}/.brainstorming/api-designer/
+.workflow/active/WFS-{topic-slug}/.brainstorming/api-designer/
 ├── analysis.md                 # Primary API design analysis
 ├── api-specification.md        # Detailed endpoint specifications (OpenAPI/Swagger)
 ├── data-contracts.md           # Request/response schemas and validation rules
@@ -531,7 +531,7 @@ Upon completion, update `workflow-session.json`:
       "api_designer": {
         "status": "completed",
         "completed_at": "timestamp",
-        "output_directory": ".workflow/WFS-{topic}/.brainstorming/api-designer/",
+        "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/api-designer/",
         "key_insights": ["endpoint_design", "versioning_strategy", "data_contracts"]
       }
     }

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

@@ -1,6 +1,6 @@
 ---
 name: artifacts
-description: Interactive clarification generating confirmed guidance specification
+description: Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis
 argument-hint: "topic or challenge description [--count N]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 ---
@@ -10,7 +10,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*)
 Six-phase workflow: **Automatic project context collection** → Extract topic challenges → Select roles → Generate task-specific questions → Detect conflicts → Generate confirmed guidance (declarative statements only).
 
 **Input**: `"GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]`
-**Output**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
+**Output**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (CONFIRMED/SELECTED format)
 **Core Principle**: Questions dynamically generated from project context + topic keywords/challenges, NOT from generic templates
 
 **Parameters**:
@@ -32,7 +32,7 @@ Six-phase workflow: **Automatic project context collection** → Extract topic c
 **Standalone Mode**:
 ```json
 [
-  {"content": "Initialize session (.workflow/.active-* check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
+  {"content": "Initialize session (.workflow/active/ session check, parse --count parameter)", "status": "pending", "activeForm": "Initializing"},
   {"content": "Phase 0: Automatic project context collection (call context-gather)", "status": "pending", "activeForm": "Phase 0 context collection"},
   {"content": "Phase 1: Extract challenges, output 2-4 task-specific questions, wait for user input", "status": "pending", "activeForm": "Phase 1 topic analysis"},
   {"content": "Phase 2: Recommend count+2 roles, output role selection, wait for user input", "status": "pending", "activeForm": "Phase 2 role selection"},
@@ -133,7 +133,7 @@ b) {role-name} ({中文名})
 ## Execution Phases
 
 ### Session Management
-- Check `.workflow/.active-*` markers first
+- Check `.workflow/active/` for existing sessions
 - Multiple sessions → Prompt selection | Single → Use it | None → Create `WFS-[topic-slug]`
 - Parse `--count N` parameter from user input (default: 3 if not specified)
 - Store decisions in `workflow-session.json` including count parameter
@@ -145,7 +145,7 @@ b) {role-name} ({中文名})
 **Detection Mechanism** (execute first):
 ```javascript
 // Check if context-package already exists
-const contextPackagePath = `.workflow/WFS-{session-id}/.process/context-package.json`;
+const contextPackagePath = `.workflow/active/WFS-{session-id}/.process/context-package.json`;
 
 if (file_exists(contextPackagePath)) {
   // Validate package
@@ -229,7 +229,7 @@ Report completion with statistics.
 
 **Steps**:
 1. **Load Phase 0 context** (if available):
-   - Read `.workflow/WFS-{session-id}/.process/context-package.json`
+   - Read `.workflow/active/WFS-{session-id}/.process/context-package.json`
    - Extract: tech_stack, existing modules, conflict_risk, relevant files
 
 2. **Deep topic analysis** (context-aware):
@@ -449,7 +449,7 @@ FOR each selected role:
 
 ## Output Document Template
 
-**File**: `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md`
+**File**: `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md`
 
 ```markdown
 # [Project] - Confirmed Guidance Specification
@@ -596,8 +596,7 @@ ELSE:
 ## File Structure
 
 ```
-.workflow/WFS-[topic]/
-├── .active-brainstorming
+.workflow/active/WFS-[topic]/
 ├── workflow-session.json              # Session metadata ONLY
 └── .brainstorming/
     └── guidance-specification.md      # Full guidance content

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

@@ -1,6 +1,6 @@
 ---
 name: auto-parallel
-description: Parallel brainstorming automation with dynamic role selection and concurrent execution
+description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives
 argument-hint: "topic or challenge description" [--count N]
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
@@ -9,22 +9,32 @@ allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), delegate to specialized commands/agents, and ensure complete execution through **automatic continuation**.
+**This command is a pure orchestrator**: Execute 3 phases in sequence (interactive framework → parallel role analysis → synthesis), coordinating specialized commands/agents through task attachment model.
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- Task agent execution **attaches analysis tasks** to orchestrator's TodoWrite
+- Phase 1: artifacts command attaches its internal tasks (Phase 1-5)
+- Phase 2: N conceptual-planning-agent tasks attached in parallel
+- Phase 3: synthesis command attaches its internal tasks
+- Orchestrator **executes these attached tasks** sequentially (Phase 1, 3) or in parallel (Phase 2)
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
 
 **Execution Model - Auto-Continue Workflow**:
 
 This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) handles user interaction, Phase 2 (role agents) runs in parallel.
 
 1. **User triggers**: `/workflow:brainstorm:auto-parallel "topic" [--count N]`
-2. **Phase 1 executes** → artifacts command (interactive framework) → Auto-continues
-3. **Phase 2 executes** → Parallel role agents (N agents run concurrently) → Auto-continues
-4. **Phase 3 executes** → Synthesis command → Reports final summary
+2. **Phase 1 executes** → artifacts command (tasks ATTACHED) → Auto-continues
+3. **Phase 2 executes** → Parallel role agents (N tasks ATTACHED concurrently) → Auto-continues
+4. **Phase 3 executes** → Synthesis command (tasks ATTACHED) → Reports final summary
 
 **Auto-Continue Mechanism**:
-- TodoList tracks current phase status
-- After Phase 1 (artifacts) completion, automatically load roles and launch Phase 2 agents
-- After Phase 2 (all agents) completion, automatically execute Phase 3 synthesis
-- Progress updates shown at each phase for visibility
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When Phase 1 (artifacts) finishes executing, automatically load roles and launch Phase 2 agents
+- When Phase 2 (all agents) finishes executing, automatically execute Phase 3 synthesis
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -32,23 +42,26 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 2. **No Preliminary Analysis**: Do not analyze topic before Phase 1 - artifacts handles all analysis
 3. **Parse Every Output**: Extract selected_roles from workflow-session.json after Phase 1
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite after every phase completion
-6. **TodoWrite Extension**: artifacts command EXTENDS parent TodoList (NOT replaces)
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **Task Attachment Model**: SlashCommand and Task invocations **attach** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
+8. **Parallel Execution**: Phase 2 attaches multiple agent tasks simultaneously for concurrent execution
 
 ## Usage
 
 ```bash
-/workflow:brainstorm:auto-parallel "<topic>" [--count N]
+/workflow:brainstorm:auto-parallel "<topic>" [--count N] [--style-skill package-name]
 ```
 
 **Recommended Structured Format**:
 ```bash
-/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N]
+/workflow:brainstorm:auto-parallel "GOAL: [objective] SCOPE: [boundaries] CONTEXT: [background]" [--count N] [--style-skill package-name]
 ```
 
 **Parameters**:
 - `topic` (required): Topic or challenge description (structured format recommended)
 - `--count N` (optional): Number of roles to select (default: 3, max: 9)
+- `--style-skill package-name` (optional): Style SKILL package to load for UI design (located at `.claude/skills/style-{package-name}/`)
 
 ## 3-Phase Execution
 
@@ -72,17 +85,39 @@ This workflow runs **fully autonomously** once triggered. Phase 1 (artifacts) ha
 **Validation**:
 - guidance-specification.md created with confirmed decisions
 - workflow-session.json contains selected_roles[] (metadata only, no content duplication)
-- Session directory `.workflow/WFS-{topic}/.brainstorming/` exists
+- Session directory `.workflow/active/WFS-{topic}/.brainstorming/` exists
 
-**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Phase 1.1: Topic analysis and question generation (artifacts)", "status": "in_progress", "activeForm": "Analyzing topic"},
+  {"content": "Phase 1.2: Role selection and user confirmation (artifacts)", "status": "pending", "activeForm": "Selecting roles"},
+  {"content": "Phase 1.3: Role questions and user decisions (artifacts)", "status": "pending", "activeForm": "Collecting role questions"},
+  {"content": "Phase 1.4: Conflict detection and resolution (artifacts)", "status": "pending", "activeForm": "Resolving conflicts"},
+  {"content": "Phase 1.5: Guidance specification generation (artifacts)", "status": "pending", "activeForm": "Generating guidance"},
+  {"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
 
-**After Phase 1**: Auto-continue to Phase 2 (role agent assignment)
+**Note**: SlashCommand invocation **attaches** artifacts' 5 internal tasks. Orchestrator **executes** these tasks sequentially.
 
-**⚠️ TodoWrite Coordination**: artifacts EXTENDS parent TodoList by:
-- Marking parent task "Execute artifacts..." as in_progress
-- APPENDING artifacts sub-tasks (Phase 1-5) after parent task
-- PRESERVING all other auto-parallel tasks (role agents, synthesis)
-- When artifacts Phase 5 completes, marking parent task as completed
+**Next Action**: Tasks attached → **Execute Phase 1.1-1.5** sequentially
+
+**TodoWrite Update (Phase 1 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "pending", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed to summary.
+
+**After Phase 1**: Auto-continue to Phase 2 (parallel role agent execution)
 
 ---
 
@@ -97,13 +132,13 @@ Execute {role-name} analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: {role-name}
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/{role}/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/{role}/
 TOPIC: {user-provided-topic}
 
 ## Flow Control Steps
 1. **load_topic_framework**
    - Action: Load structured topic discussion framework
-   - Command: Read(.workflow/WFS-{session}/.brainstorming/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -113,9 +148,15 @@ TOPIC: {user-provided-topic}
 
 3. **load_session_metadata**
    - Action: Load session metadata and original user intent
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context (contains original user prompt as PRIMARY reference)
 
+4. **load_style_skill** (ONLY for ui-designer role when style_skill_package exists)
+   - Action: Load style SKILL package for design system reference
+   - Command: Read(.claude/skills/style-{style_skill_package}/SKILL.md) AND Read(.workflow/reference_style/{style_skill_package}/design-tokens.json)
+   - Output: style_skill_content, design_tokens
+   - Usage: Apply design tokens in ui-designer analysis and artifacts
+
 ## Analysis Requirements
 **Primary Reference**: Original user prompt from workflow-session.json is authoritative
 **Framework Source**: Address all discussion points in guidance-specification.md from {role-name} perspective
@@ -143,8 +184,9 @@ TOPIC: {user-provided-topic}
 
 **Parallel Execution**:
 - Launch N agents simultaneously (one message with multiple Task calls)
+- Each agent task **attached** to orchestrator's TodoWrite
+- All agents execute concurrently, each attaching their own analysis sub-tasks
 - Each agent operates independently reading same guidance-specification.md
-- All agents update progress concurrently
 
 **Input**:
 - `selected_roles[]` from Phase 1
@@ -152,13 +194,39 @@ TOPIC: {user-provided-topic}
 - guidance-specification.md path
 
 **Validation**:
-- Each role creates `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
+- Each role creates `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (primary file)
 - If content is large (>800 lines), may split to `analysis-1.md`, `analysis-2.md` (max 3 files total)
 - **File naming pattern**: ALL files MUST start with `analysis` prefix (use `analysis*.md` for globbing)
 - **FORBIDDEN naming**: No `recommendations.md`, `recommendations-*.md`, or any non-`analysis` prefixed files
 - All N role analyses completed
 
-**TodoWrite**: Mark all N role agent tasks completed, phase 3 in_progress
+**TodoWrite Update (Phase 2 agents invoked - tasks attached in parallel)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Phase 2.1: Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
+  {"content": "Phase 2.2: Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
+  {"content": "Phase 2.3: Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Multiple Task invocations **attach** N role analysis tasks simultaneously. Orchestrator **executes** these tasks in parallel.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.N** concurrently
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "pending", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 2 parallel tasks completed and collapsed to summary.
 
 **After Phase 2**: Auto-continue to Phase 3 (synthesis)
 
@@ -177,16 +245,42 @@ TOPIC: {user-provided-topic}
 **Input**: `sessionId` from Phase 1
 
 **Validation**:
-- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
+- `.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` exists
 - Synthesis references all role analyses
 
-**TodoWrite**: Mark phase 3 completed
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Phase 3.1: Load role analysis files (synthesis)", "status": "in_progress", "activeForm": "Loading role analyses"},
+  {"content": "Phase 3.2: Integrate insights across roles (synthesis)", "status": "pending", "activeForm": "Integrating insights"},
+  {"content": "Phase 3.3: Generate synthesis specification (synthesis)", "status": "pending", "activeForm": "Generating synthesis"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** synthesis' internal tasks. Orchestrator **executes** these tasks sequentially.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
+  {"content": "Execute artifacts interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
+  {"content": "Execute parallel role analysis", "status": "completed", "activeForm": "Executing parallel role analysis"},
+  {"content": "Execute synthesis integration", "status": "completed", "activeForm": "Executing synthesis integration"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 **Return to User**:
 ```
 Brainstorming complete for session: {sessionId}
 Roles analyzed: {count}
-Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
+Synthesis: .workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md
 
 ✅ Next Steps:
 1. /workflow:concept-clarify --session {sessionId}  # Optional refinement
@@ -195,49 +289,41 @@ Synthesis: .workflow/WFS-{topic}/.brainstorming/synthesis-specification.md
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Parse --count parameter from user input", "status": "in_progress", "activeForm": "Parsing count parameter"},
-  {"content": "Execute artifacts command for interactive framework generation", "status": "pending", "activeForm": "Executing artifacts interactive framework"},
-  {"content": "Load selected_roles from workflow-session.json", "status": "pending", "activeForm": "Loading selected roles"},
-  // Role agent tasks added dynamically after Phase 1 based on selected_roles count
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for parallel brainstorming workflow with interactive framework generation and concurrent role analysis.
 
-// After Phase 1 (artifacts completes, roles loaded)
-// Note: artifacts EXTENDS this list by appending its Phase 1-5 sub-tasks
-TodoWrite({todos: [
-  {"content": "Parse --count parameter from user input", "status": "completed", "activeForm": "Parsing count parameter"},
-  {"content": "Execute artifacts command for interactive framework generation", "status": "completed", "activeForm": "Executing artifacts interactive framework"},
-  {"content": "Load selected_roles from workflow-session.json", "status": "in_progress", "activeForm": "Loading selected roles"},
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "pending", "activeForm": "Executing product-manager analysis"},
-  // ... (N role tasks based on --count parameter)
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+### Key Principles
 
-// After Phase 2 (all agents launched in parallel)
-TodoWrite({todos: [
-  // ... previous completed tasks
-  {"content": "Load selected_roles from workflow-session.json", "status": "completed", "activeForm": "Loading selected roles"},
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "in_progress", "activeForm": "Executing product-manager analysis"},
-  // ... (all N agents in_progress simultaneously)
-  {"content": "Execute synthesis command for final integration", "status": "pending", "activeForm": "Executing synthesis integration"}
-]})
+1. **Task Attachment** (when SlashCommand/Task invoked):
+   - Sub-command's or agent's internal tasks are **attached** to orchestrator's TodoWrite
+   - Phase 1: `/workflow:brainstorm:artifacts` attaches 5 internal tasks (Phase 1.1-1.5)
+   - Phase 2: Multiple `Task(conceptual-planning-agent)` calls attach N role analysis tasks simultaneously
+   - Phase 3: `/workflow:brainstorm:synthesis` attaches 3 internal tasks (Phase 3.1-3.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks (sequentially for Phase 1, 3; in parallel for Phase 2)
+
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 1.1-1.5 collapse to "Execute artifacts interactive framework generation: completed"
+   - Phase 2: Multiple role tasks collapse to "Execute parallel role analysis: completed"
+   - Phase 3: Synthesis tasks collapse to "Execute synthesis integration: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase 1 invoked (artifacts tasks ATTACHED) → Artifacts sub-tasks executed → Phase 1 completed (tasks COLLAPSED) → Phase 2 invoked (N role tasks ATTACHED in parallel) → Role analyses executed concurrently → Phase 2 completed (tasks COLLAPSED) → Phase 3 invoked (synthesis tasks ATTACHED) → Synthesis sub-tasks executed → Phase 3 completed (tasks COLLAPSED) → Workflow complete.
+
+### Brainstorming Workflow Specific Features
+
+- **Phase 1**: Interactive framework generation with user Q&A (SlashCommand attachment)
+- **Phase 2**: Parallel role analysis execution with N concurrent agents (Task agent attachments)
+- **Phase 3**: Cross-role synthesis integration (SlashCommand attachment)
+- **Dynamic Role Count**: `--count N` parameter determines number of Phase 2 parallel tasks (default: 3, max: 9)
+- **Mixed Execution**: Sequential (Phase 1, 3) and Parallel (Phase 2) task execution
 
-// After Phase 2 (all agents complete)
-TodoWrite({todos: [
-  // ... previous completed tasks
-  {"content": "Execute system-architect analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing system-architect analysis"},
-  {"content": "Execute ui-designer analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing ui-designer analysis"},
-  {"content": "Execute product-manager analysis [conceptual-planning-agent]", "status": "completed", "activeForm": "Executing product-manager analysis"},
-  {"content": "Execute synthesis command for final integration", "status": "in_progress", "activeForm": "Executing synthesis integration"}
-]})
-```
 
 ## Input Processing
 
@@ -255,6 +341,34 @@ ELSE:
 EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 ```
 
+**Style-Skill Parameter Parsing**:
+```javascript
+// Extract --style-skill from user input
+IF user_input CONTAINS "--style-skill":
+    EXTRACT style_skill_name FROM "--style-skill package-name" pattern
+
+    // Validate SKILL package exists
+    skill_path = ".claude/skills/style-{style_skill_name}/SKILL.md"
+    IF file_exists(skill_path):
+        style_skill_package = style_skill_name
+        style_reference_path = ".workflow/reference_style/{style_skill_name}"
+        echo("✓ Style SKILL package found: style-{style_skill_name}")
+        echo("  Design reference: {style_reference_path}")
+    ELSE:
+        echo("⚠ WARNING: Style SKILL package not found: {style_skill_name}")
+        echo("  Expected location: {skill_path}")
+        echo("  Continuing without style reference...")
+        style_skill_package = null
+ELSE:
+    style_skill_package = null
+    echo("No style-skill specified, ui-designer will use default workflow")
+
+// Store for Phase 2 ui-designer context
+CONTEXT_VARS:
+    - style_skill_package: {style_skill_package}
+    - style_reference_path: {style_reference_path}
+```
+
 **Topic Structuring**:
 1. **Already Structured** → Pass directly to artifacts
    ```
@@ -270,32 +384,34 @@ EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 
 ## Session Management
 
-**⚡ FIRST ACTION**: Check for `.workflow/.active-*` markers before Phase 1
+**⚡ FIRST ACTION**: Check `.workflow/active/` for existing sessions before Phase 1
 
 **Multiple Sessions Support**:
-- Different Claude instances can have different active brainstorming sessions
-- If multiple active sessions found, prompt user to select
-- If single active session found, use it
-- If no active session exists, create `WFS-[topic-slug]`
+- Different Claude instances can have different brainstorming sessions
+- If multiple sessions found, prompt user to select
+- If single session found, use it
+- If no session exists, create `WFS-[topic-slug]`
 
 **Session Continuity**:
-- MUST use selected active session for all phases
+- MUST use selected session for all phases
 - Each role's context stored in session directory
 - Session isolation: Each session maintains independent state
 
 ## Output Structure
 
 **Phase 1 Output**:
-- `.workflow/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
-- `.workflow/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps)
+- `.workflow/active/WFS-{topic}/.brainstorming/guidance-specification.md` (framework content)
+- `.workflow/active/WFS-{topic}/workflow-session.json` (metadata: selected_roles[], topic, timestamps, style_skill_package)
 
 **Phase 2 Output**:
-- `.workflow/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
+- `.workflow/active/WFS-{topic}/.brainstorming/{role}/analysis.md` (one per role)
+- `.superdesign/design_iterations/` (ui-designer artifacts, if --style-skill provided)
 
 **Phase 3 Output**:
-- `.workflow/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
+- `.workflow/active/WFS-{topic}/.brainstorming/synthesis-specification.md` (integrated analysis)
 
 **⚠️ Storage Separation**: Guidance content in .md files, metadata in .json (no duplication)
+**⚠️ Style References**: When --style-skill provided, workflow-session.json stores style_skill_package name, ui-designer loads from `.claude/skills/style-{package-name}/`
 
 ## Available Roles
 
@@ -322,8 +438,7 @@ EXECUTE: /workflow:brainstorm:artifacts "{topic}" --count {count_value}
 
 **File Structure**:
 ```
-.workflow/WFS-[topic]/
-├── .active-brainstorming
+.workflow/active/WFS-[topic]/
 ├── workflow-session.json              # Session metadata ONLY
 └── .brainstorming/
     ├── guidance-specification.md      # Framework (Phase 1)

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

@@ -1,6 +1,6 @@
 ---
 name: data-architect
-description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points
+description: Generate or update data-architect/analysis.md addressing guidance-specification discussion points for data architecture perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -47,10 +47,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -87,13 +87,13 @@ Execute data-architect analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: data-architect
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/data-architect/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/data-architect/
 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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -103,7 +103,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -163,7 +163,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/data-architect/
+.workflow/active/WFS-{session}/.brainstorming/data-architect/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -208,7 +208,7 @@ TodoWrite({
   "data_architect": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/data-architect/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/data-architect/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: product-manager
-description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points
+description: Generate or update product-manager/analysis.md addressing guidance-specification discussion points for product management perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -67,13 +67,13 @@ Execute product-manager analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: product-manager
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-manager/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/product-manager/
 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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/product-manager/
+.workflow/active/WFS-{session}/.brainstorming/product-manager/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -188,7 +188,7 @@ TodoWrite({
   "product_manager": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/product-manager/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/product-manager/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: product-owner
-description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points
+description: Generate or update product-owner/analysis.md addressing guidance-specification discussion points for product ownership perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -67,13 +67,13 @@ Execute product-owner analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: product-owner
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/product-owner/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/product-owner/
 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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/product-owner/
+.workflow/active/WFS-{session}/.brainstorming/product-owner/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -188,7 +188,7 @@ TodoWrite({
   "product_owner": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/product-owner/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/product-owner/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: scrum-master
-description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points
+description: Generate or update scrum-master/analysis.md addressing guidance-specification discussion points for Agile process perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -67,13 +67,13 @@ Execute scrum-master analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: scrum-master
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/scrum-master/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/scrum-master/
 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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/scrum-master/
+.workflow/active/WFS-{session}/.brainstorming/scrum-master/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -188,7 +188,7 @@ TodoWrite({
   "scrum_master": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/scrum-master/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/scrum-master/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: subject-matter-expert
-description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points
+description: Generate or update subject-matter-expert/analysis.md addressing guidance-specification discussion points for domain expertise perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -27,10 +27,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -67,13 +67,13 @@ 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/
+OUTPUT_LOCATION: .workflow/active/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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -83,7 +83,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -143,7 +143,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/subject-matter-expert/
+.workflow/active/WFS-{session}/.brainstorming/subject-matter-expert/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -188,7 +188,7 @@ TodoWrite({
   "subject_matter_expert": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/subject-matter-expert/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: synthesis
-description: Clarify and refine role analyses through intelligent Q&A and targeted updates
+description: Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent
 argument-hint: "[optional: --session session-id]"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*)
 ---
@@ -48,7 +48,7 @@ Three-phase workflow to eliminate ambiguities and enhance conceptual depth in ro
 
 ### Phase 1: Discovery & Validation
 
-1. **Detect Session**: Use `--session` parameter or `.workflow/.active-*` marker
+1. **Detect Session**: Use `--session` parameter or find `.workflow/active/WFS-*` directories
 2. **Validate Files**:
    - `guidance-specification.md` (optional, warn if missing)
    - `*/analysis*.md` (required, error if empty)
@@ -59,7 +59,7 @@ Three-phase workflow to eliminate ambiguities and enhance conceptual depth in ro
 **Main flow prepares file paths for Agent**:
 
 1. **Discover Analysis Files**:
-   - Glob(.workflow/WFS-{session}/.brainstorming/*/analysis*.md)
+   - Glob(.workflow/active/WFS-{session}/.brainstorming/*/analysis*.md)
    - Supports: analysis.md, analysis-1.md, analysis-2.md, analysis-3.md
    - Validate: At least one file exists (error if empty)
 
@@ -69,7 +69,7 @@ Three-phase workflow to eliminate ambiguities and enhance conceptual depth in ro
 
 3. **Pass to Agent** (Phase 3):
    - `session_id`
-   - `brainstorm_dir`: .workflow/WFS-{session}/.brainstorming/
+   - `brainstorm_dir`: .workflow/active/WFS-{session}/.brainstorming/
    - `role_analysis_paths`: ["product-manager/analysis.md", "system-architect/analysis-1.md", ...]
    - `participating_roles`: ["product-manager", "system-architect", ...]
 
@@ -361,7 +361,7 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content
 
 ## Output
 
-**Location**: `.workflow/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
+**Location**: `.workflow/active/WFS-{session}/.brainstorming/[role]/analysis*.md` (in-place updates)
 
 **Updated Structure**:
 ```markdown
@@ -381,6 +381,64 @@ Updated {role2}/analysis.md with Clarifications section + enhanced content
 - Ambiguities resolved, placeholders removed
 - Consistent terminology
 
+### Phase 6: Update Context Package
+
+**Purpose**: Sync updated role analyses to context-package.json to avoid stale cache
+
+**Operations**:
+```bash
+context_pkg_path = ".workflow/active/WFS-{session}/.process/context-package.json"
+
+# 1. Read existing package
+context_pkg = Read(context_pkg_path)
+
+# 2. Re-read brainstorm artifacts (now with synthesis enhancements)
+brainstorm_dir = ".workflow/active/WFS-{session}/.brainstorming"
+
+# 2.1 Update guidance-specification if exists
+IF exists({brainstorm_dir}/guidance-specification.md):
+    context_pkg.brainstorm_artifacts.guidance_specification.content = Read({brainstorm_dir}/guidance-specification.md)
+    context_pkg.brainstorm_artifacts.guidance_specification.updated_at = NOW()
+
+# 2.2 Update synthesis-specification if exists
+IF exists({brainstorm_dir}/synthesis-specification.md):
+    IF context_pkg.brainstorm_artifacts.synthesis_output:
+        context_pkg.brainstorm_artifacts.synthesis_output.content = Read({brainstorm_dir}/synthesis-specification.md)
+        context_pkg.brainstorm_artifacts.synthesis_output.updated_at = NOW()
+
+# 2.3 Re-read all role analysis files
+role_analysis_files = Glob({brainstorm_dir}/*/analysis*.md)
+context_pkg.brainstorm_artifacts.role_analyses = []
+
+FOR file IN role_analysis_files:
+    role_name = extract_role_from_path(file)  # e.g., "ui-designer"
+    relative_path = file.replace({brainstorm_dir}/, "")
+
+    context_pkg.brainstorm_artifacts.role_analyses.push({
+        "role": role_name,
+        "files": [{
+            "path": relative_path,
+            "type": "primary",
+            "content": Read(file),
+            "updated_at": NOW()
+        }]
+    })
+
+# 3. Update metadata
+context_pkg.metadata.updated_at = NOW()
+context_pkg.metadata.synthesis_timestamp = NOW()
+
+# 4. Write back
+Write(context_pkg_path, JSON.stringify(context_pkg, indent=2))
+
+REPORT: "✅ Updated context-package.json with synthesis results"
+```
+
+**TodoWrite Update**:
+```json
+{"content": "Update context package with synthesis results", "status": "completed", "activeForm": "Updating context package"}
+```
+
 ## Session Metadata
 
 Update `workflow-session.json`:

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

@@ -1,6 +1,6 @@
 ---
 name: system-architect
-description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points
+description: Generate or update system-architect/analysis.md addressing guidance-specification discussion points for system architecture perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -46,10 +46,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -162,7 +162,7 @@ IF update_mode = "incremental":
 
 ### Output Files
 ```
-.workflow/WFS-[topic]/.brainstorming/
+.workflow/active/WFS-[topic]/.brainstorming/
 ├── guidance-specification.md          # Input: Framework (if exists)
 └── system-architect/
     └── analysis.md            # ★ OUTPUT: Framework-based analysis
@@ -186,8 +186,8 @@ IF update_mode = "incremental":
 ### ⚠️ Session Management - FIRST STEP
 Session detection and selection:
 ```bash
-# Check for active sessions
-active_sessions=$(find .workflow -name ".active-*" 2>/dev/null)
+# Check for existing sessions
+existing_sessions=$(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
 if [ multiple_sessions ]; then
   prompt_user_to_select_session()
 else
@@ -279,7 +279,7 @@ TodoWrite tracking for two-step process:
 
 ### Output Location
 ```
-.workflow/WFS-{topic-slug}/.brainstorming/system-architect/
+.workflow/active/WFS-{topic-slug}/.brainstorming/system-architect/
 ├── analysis.md                 # Primary architecture analysis
 ├── architecture-design.md      # Detailed system design and diagrams
 ├── technology-stack.md         # Technology stack recommendations and justifications
@@ -340,7 +340,7 @@ Upon completion, update `workflow-session.json`:
       "system_architect": {
         "status": "completed",
         "completed_at": "timestamp",
-        "output_directory": ".workflow/WFS-{topic}/.brainstorming/system-architect/",
+        "output_directory": ".workflow/active/WFS-{topic}/.brainstorming/system-architect/",
         "key_insights": ["scalability_bottleneck", "architecture_pattern", "technology_recommendation"]
       }
     }

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

@@ -1,6 +1,6 @@
 ---
 name: ui-designer
-description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points
+description: Generate or update ui-designer/analysis.md addressing guidance-specification discussion points for UI design perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -48,10 +48,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -88,13 +88,13 @@ Execute ui-designer analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: ui-designer
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ui-designer/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/ui-designer/
 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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -104,7 +104,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -164,7 +164,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/ui-designer/
+.workflow/active/WFS-{session}/.brainstorming/ui-designer/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -209,7 +209,7 @@ TodoWrite({
   "ui_designer": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/ui-designer/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: ux-expert
-description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points
+description: Generate or update ux-expert/analysis.md addressing guidance-specification discussion points for UX perspective
 argument-hint: "optional topic - uses existing framework if available"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ---
@@ -48,10 +48,10 @@ allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*)
 ### Phase 1: Session & Framework Detection
 ```bash
 # Check active session and framework
-CHECK: .workflow/.active-* marker files
+CHECK: find .workflow/active/ -name "WFS-*" -type d
 IF active_session EXISTS:
     session_id = get_active_session()
-    brainstorm_dir = .workflow/WFS-{session}/.brainstorming/
+    brainstorm_dir = .workflow/active/WFS-{session}/.brainstorming/
 
     CHECK: brainstorm_dir/guidance-specification.md
     IF EXISTS:
@@ -88,13 +88,13 @@ Execute ux-expert analysis for existing topic framework
 
 ## Context Loading
 ASSIGNED_ROLE: ux-expert
-OUTPUT_LOCATION: .workflow/WFS-{session}/.brainstorming/ux-expert/
+OUTPUT_LOCATION: .workflow/active/WFS-{session}/.brainstorming/ux-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/guidance-specification.md)
+   - Command: Read(.workflow/active/WFS-{session}/.brainstorming/guidance-specification.md)
    - Output: topic_framework_content
 
 2. **load_role_template**
@@ -104,7 +104,7 @@ ANALYSIS_MODE: {framework_mode ? "framework_based" : "standalone"}
 
 3. **load_session_metadata**
    - Action: Load session metadata and existing context
-   - Command: Read(.workflow/WFS-{session}/workflow-session.json)
+   - Command: Read(.workflow/active/WFS-{session}/workflow-session.json)
    - Output: session_context
 
 ## Analysis Requirements
@@ -164,7 +164,7 @@ TodoWrite({
 
 ### Framework-Based Analysis
 ```
-.workflow/WFS-{session}/.brainstorming/ux-expert/
+.workflow/active/WFS-{session}/.brainstorming/ux-expert/
 └── analysis.md    # Structured analysis addressing guidance-specification.md discussion points
 ```
 
@@ -209,7 +209,7 @@ TodoWrite({
   "ux_expert": {
     "status": "completed",
     "framework_addressed": true,
-    "output_location": ".workflow/WFS-{session}/.brainstorming/ux-expert/analysis.md",
+    "output_location": ".workflow/active/WFS-{session}/.brainstorming/ux-expert/analysis.md",
     "framework_reference": "@../guidance-specification.md"
   }
 }

.claude/commands/workflow/execute.md

@@ -1,13 +1,13 @@
 ---
 name: execute
-description: Coordinate agents for existing workflow tasks with automatic discovery
+description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking
 argument-hint: "[--resume-session=\"session-id\"]"
 ---
 
 # Workflow Execute Command
 
 ## Overview
-Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption**, providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
+Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption** (except initial session selection if multiple active sessions exist), providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking.
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
 
@@ -15,130 +15,170 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 
 **Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
 
-| Metric | Before | After | Improvement |
-|--------|--------|-------|-------------|
-| **Initial Load** | All task JSONs (~2,300 lines) | TODO_LIST.md only (~650 lines) | **72% reduction** |
-| **Startup Time** | Seconds | Milliseconds | **~90% faster** |
-| **Memory** | All tasks | 1-2 tasks | **90% less** |
-| **Scalability** | 10-20 tasks | 100+ tasks | **5-10x** |
+**Loading Strategy**:
+- **TODO_LIST.md**: Read in Phase 2 (task metadata, status, dependencies)
+- **IMPL_PLAN.md**: Read existence in Phase 2, parse execution strategy when needed
+- **Task JSONs**: Complete lazy loading (read only during execution)
 
 ## Core Rules
 **Complete entire workflow autonomously without user interruption, using TodoWrite for comprehensive progress tracking.**
-**Execute all discovered pending tasks sequentially until workflow completion or blocking dependency.**
+**Execute all discovered pending tasks until workflow completion or blocking dependency.**
 **Auto-complete session when all tasks finished: Call `/workflow:session:complete` upon workflow completion.**
+**ONE AGENT = ONE TASK JSON: Each agent instance executes exactly one task JSON file - never batch multiple tasks into single agent execution.**
 
 ## Core Responsibilities
 - **Session Discovery**: Identify and select active workflow sessions
-- **Task Dependency Resolution**: Analyze task relationships and execution order
+- **Execution Strategy Parsing**: Extract execution model from IMPL_PLAN.md
 - **TodoWrite Progress Tracking**: Maintain real-time execution status throughout entire workflow
 - **Agent Orchestration**: Coordinate specialized agents with complete context
-- **Flow Control Execution**: Execute pre-analysis steps and context accumulation
 - **Status Synchronization**: Update task JSON files and workflow state
 - **Autonomous Completion**: Continue execution until all tasks complete or reach blocking state
 - **Session Auto-Complete**: Call `/workflow:session:complete` when all workflow tasks finished
 
 ## Execution Philosophy
-- **Discovery-first**: Auto-discover existing plans and tasks
-- **Status-aware**: Execute only ready tasks with resolved dependencies
-- **Context-rich**: Provide complete task JSON and accumulated context to agents
-- **Progress tracking**: **Continuous TodoWrite updates throughout entire workflow execution**
-- **Flow control**: Sequential step execution with variable passing
-- **Autonomous completion**: **Execute all tasks without user interruption until workflow complete**
-
-## Flow Control Execution
-**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
-
-### Orchestrator Responsibility
-- Pass complete task JSON to agent (including `flow_control` block)
-- Provide session paths for artifact access
-- Monitor agent completion
-
-### Agent Responsibility
-- Parse `flow_control.pre_analysis` array from JSON
-- Execute steps sequentially with variable substitution
-- Accumulate context from artifacts and dependencies
-- Follow error handling per `step.on_error`
-- Complete implementation using accumulated context
-
-**Orchestrator does NOT execute flow control steps - Agent interprets and executes them from JSON.**
+- **Progress tracking**: Continuous TodoWrite updates throughout entire workflow execution
+- **Autonomous completion**: Execute all tasks without user interruption until workflow complete
 
 ## Execution Lifecycle
 
-### Resume Mode Detection
-**Special Flag Processing**: When `--resume-session="session-id"` is provided:
-1. **Skip Discovery Phase**: Use provided session ID directly
-2. **Load Specified Session**: Read session state from `.workflow/{session-id}/`
-3. **Direct TodoWrite Generation**: Skip to Phase 3 (Planning) immediately
-4. **Accelerated Execution**: Enter agent coordination without validation delays
+### Phase 1: Discovery
+**Applies to**: Normal mode only (skipped in resume mode)
 
-### Phase 1: Discovery (Normal Mode Only)
-1. **Check Active Sessions**: Find `.workflow/.active-*` markers
-2. **Select Session**: If multiple found, prompt user selection
-3. **Load Session Metadata**: Read `workflow-session.json` ONLY (minimal context)
-4. **DO NOT read task JSONs yet** - defer until execution phase
+**Purpose**: Find and select active workflow session with user confirmation when multiple sessions exist
 
-**Note**: In resume mode, this phase is completely skipped.
+**Process**:
+
+#### Step 1.1: Count Active Sessions
+```bash
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
+```
+
+#### Step 1.2: Handle Session Selection
+
+**Case A: No Sessions** (count = 0)
+```
+ERROR: No active workflow sessions found
+Run /workflow:plan "task description" to create a session
+```
+
+**Case B: Single Session** (count = 1)
+```bash
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
+```
+Auto-select and continue to Phase 2.
+
+**Case C: Multiple Sessions** (count > 1)
+
+List sessions with metadata and prompt user selection:
+```bash
+bash(for dir in .workflow/active/WFS-*/; do
+  session=$(basename "$dir")
+  project=$(jq -r '.project // "Unknown"' "$dir/workflow-session.json" 2>/dev/null)
+  total=$(grep -c "^- \[" "$dir/TODO_LIST.md" 2>/dev/null || echo "0")
+  completed=$(grep -c "^- \[x\]" "$dir/TODO_LIST.md" 2>/dev/null || echo "0")
+  [ "$total" -gt 0 ] && progress=$((completed * 100 / total)) || progress=0
+  echo "${session} | ${project} | ${completed}/${total} tasks (${progress}%)"
+done)
+```
+
+Use AskUserQuestion to present formatted options:
+```
+Multiple active workflow sessions detected. Please select one:
+
+1. WFS-auth-system | Authentication System | 3/5 tasks (60%)
+2. WFS-payment-module | Payment Integration | 0/8 tasks (0%)
+
+Enter number, full session ID, or partial match:
+```
+
+Parse user input (supports: number "1", full ID "WFS-auth-system", or partial "auth"), validate selection, and continue to Phase 2.
+
+#### Step 1.3: Load Session Metadata
+```bash
+bash(cat .workflow/active/${sessionId}/workflow-session.json)
+```
+
+**Output**: Store session metadata in memory
+**DO NOT read task JSONs yet** - defer until execution phase (lazy loading)
+
+**Resume Mode**: This entire phase is skipped when `--resume-session="session-id"` flag is provided.
+
+### Phase 2: Planning Document Analysis
+**Applies to**: Normal mode only (skipped in resume mode)
 
-### Phase 2: Planning Document Analysis (Normal Mode Only)
 **Optimized to avoid reading all task JSONs upfront**
 
-1. **Read IMPL_PLAN.md**: Understand overall strategy, task breakdown summary, dependencies
+**Process**:
+1. **Check IMPL_PLAN.md**: Verify file exists and has valid structure (defer detailed parsing to Phase 4)
 2. **Read TODO_LIST.md**: Get current task statuses and execution progress
 3. **Extract Task Metadata**: Parse task IDs, titles, and dependency relationships from TODO_LIST.md
 4. **Build Execution Queue**: Determine ready tasks based on TODO_LIST.md status and dependencies
 
-**Key Optimization**: Use IMPL_PLAN.md and TODO_LIST.md as primary sources instead of reading all task JSONs
+**Key Optimization**: Use IMPL_PLAN.md (existence check only) and TODO_LIST.md as primary sources instead of reading all task JSONs. Detailed IMPL_PLAN.md parsing happens in Phase 4A.
 
-**Note**: In resume mode, this phase is also skipped as session analysis was already completed by `/workflow:status`.
+**Resume Mode**: When `--resume-session` flag is provided, **session discovery** (Phase 1) is skipped, but **task metadata loading** (TODO_LIST.md reading) still occurs in Phase 3 for TodoWrite generation.
 
-### Phase 3: TodoWrite Generation (Resume Mode Entry Point)
-**This is where resume mode directly enters after skipping Phases 1 & 2**
+### Phase 3: TodoWrite Generation
+**Applies to**: Both normal and resume modes (resume mode entry point)
 
+**Process**:
 1. **Create TodoWrite List**: Generate task list from TODO_LIST.md (not from task JSONs)
    - Parse TODO_LIST.md to extract all tasks with current statuses
    - Identify first pending task with met dependencies
    - Generate comprehensive TodoWrite covering entire workflow
-2. **Mark Initial Status**: Set first ready task as `in_progress` in TodoWrite
-3. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
-4. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
+2. **Prepare Session Context**: Inject workflow paths for agent use (using provided session-id)
+3. **Validate Prerequisites**: Ensure IMPL_PLAN.md and TODO_LIST.md exist and are valid
 
 **Resume Mode Behavior**:
-- Load existing TODO_LIST.md directly from `.workflow/{session-id}/`
+- Load existing TODO_LIST.md directly from `.workflow/active/{session-id}/`
 - Extract current progress from TODO_LIST.md
 - Generate TodoWrite from TODO_LIST.md state
 - Proceed immediately to agent execution (Phase 4)
 
-### Phase 4: Execution (Lazy Task Loading)
-**Key Optimization**: Read task JSON **only when needed** for execution
+### Phase 4: Execution Strategy Selection & Task Execution
+**Applies to**: Both normal and resume modes
 
-1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
-2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
-3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
-4. **Pass Task with Flow Control**: Include complete task JSON with `pre_analysis` steps for agent execution
-5. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
-6. **Monitor Progress**: Track agent execution and handle errors without user interruption
-7. **Collect Results**: Gather implementation results and outputs
-8. **Update TODO_LIST.md**: Mark current task as completed in TODO_LIST.md
-9. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat from step 1
+**Step 4A: Parse Execution Strategy from IMPL_PLAN.md**
+
+Read IMPL_PLAN.md Section 4 to extract:
+- **Execution Model**: Sequential | Parallel | Phased | TDD Cycles
+- **Parallelization Opportunities**: Which tasks can run in parallel
+- **Serialization Requirements**: Which tasks must run sequentially
+- **Critical Path**: Priority execution order
+
+If IMPL_PLAN.md lacks execution strategy, use intelligent fallback (analyze task structure).
+
+**Step 4B: Execute Tasks with Lazy Loading**
+
+**Key Optimization**: Read task JSON **only when needed** for execution
 
 **Execution Loop Pattern**:
 ```
 while (TODO_LIST.md has pending tasks) {
   next_task_id = getTodoWriteInProgressTask()
-  task_json = Read(.workflow/{session}/.task/{next_task_id}.json)  // Lazy load
+  task_json = Read(.workflow/session/{session}/.task/{next_task_id}.json)  // Lazy load
   executeTaskWithAgent(task_json)
   updateTodoListMarkCompleted(next_task_id)
   advanceTodoWriteToNextTask()
 }
 ```
 
-**Benefits**:
-- Reduces initial context loading by ~90%
-- Only reads task JSON when actually executing
-- Scales better for workflows with many tasks
-- Faster startup time for workflow execution
+**Execution Process per Task**:
+1. **Identify Next Task**: From TodoWrite, get the next `in_progress` task ID
+2. **Load Task JSON on Demand**: Read `.task/{task-id}.json` for current task ONLY
+3. **Validate Task Structure**: Ensure all 5 required fields exist (id, title, status, meta, context, flow_control)
+4. **Launch Agent**: Invoke specialized agent with complete context including flow control steps
+5. **Monitor Progress**: Track agent execution and handle errors without user interruption
+6. **Collect Results**: Gather implementation results and outputs
+7. **Continue Workflow**: Identify next pending task from TODO_LIST.md and repeat
+
+**Note**: TODO_LIST.md updates are handled by agents (e.g., code-developer.md), not by the orchestrator.
+
 
 ### Phase 5: Completion
+**Applies to**: Both normal and resume modes
+
+**Process**:
 1. **Update Task Status**: Mark completed tasks in JSON files
 2. **Generate Summary**: Create task summary in `.summaries/`
 3. **Update TodoWrite**: Mark current task complete, advance to next
@@ -146,34 +186,53 @@ while (TODO_LIST.md has pending tasks) {
 5. **Check Workflow Complete**: Verify all tasks are completed
 6. **Auto-Complete Session**: Call `/workflow:session:complete` when all tasks finished
 
-## Task Discovery & Queue Building
+## Execution Strategy (IMPL_PLAN-Driven)
 
-### Session Discovery Process (Normal Mode - Optimized)
-```
-├── Check for .active-* markers in .workflow/
-├── If multiple active sessions found → Prompt user to select
-├── Locate selected session's workflow folder
-├── Load session metadata: workflow-session.json (minimal context)
-├── Read IMPL_PLAN.md (strategy overview and task summary)
-├── Read TODO_LIST.md (current task statuses and dependencies)
-├── Parse TODO_LIST.md to extract task metadata (NO JSON loading)
-├── Build execution queue from TODO_LIST.md
-└── Generate TodoWrite from TODO_LIST.md state
-```
+### Strategy Priority
 
-**Key Change**: Task JSONs are NOT loaded during discovery - they are loaded lazily during execution
+**IMPL_PLAN-Driven Execution (Recommended)**:
+1. **Read IMPL_PLAN.md execution strategy** (Section 4: Implementation Strategy)
+2. **Follow explicit guidance**:
+   - Execution Model (Sequential/Parallel/Phased/TDD)
+   - Parallelization Opportunities (which tasks can run in parallel)
+   - Serialization Requirements (which tasks must run sequentially)
+   - Critical Path (priority execution order)
+3. **Use TODO_LIST.md for status tracking** only
+4. **IMPL_PLAN decides "HOW"**, execute.md implements it
 
-### Resume Mode Process (--resume-session flag - Optimized)
-```
-├── Use provided session-id directly (skip discovery)
-├── Validate .workflow/{session-id}/ directory exists
-├── Read TODO_LIST.md for current progress
-├── Parse TODO_LIST.md to extract task IDs and statuses
-├── Generate TodoWrite from TODO_LIST.md (prioritize in-progress/pending tasks)
-└── Enter Phase 4 (Execution) with lazy task JSON loading
-```
+**Intelligent Fallback (When IMPL_PLAN lacks execution details)**:
+1. **Analyze task structure**:
+   - Check `meta.execution_group` in task JSONs
+   - Analyze `depends_on` relationships
+   - Understand task complexity and risk
+2. **Apply smart defaults**:
+   - No dependencies + same execution_group → Parallel
+   - Has dependencies → Sequential (wait for deps)
+   - Critical/high-risk tasks → Sequential
+3. **Conservative approach**: When uncertain, prefer sequential execution
 
-**Key Change**: Completely skip IMPL_PLAN.md and task JSON loading - use TODO_LIST.md only
+### Execution Models
+
+#### 1. Sequential Execution
+**When**: IMPL_PLAN specifies "Sequential" OR no clear parallelization guidance
+**Pattern**: Execute tasks one by one in TODO_LIST order
+**TodoWrite**: ONE task marked as `in_progress` at a time
+
+#### 2. Parallel Execution
+**When**: IMPL_PLAN specifies "Parallel" with clear parallelization opportunities
+**Pattern**: Execute independent task groups concurrently by launching multiple agent instances
+**TodoWrite**: MULTIPLE tasks (in same batch) marked as `in_progress` simultaneously
+**Agent Instantiation**: Launch one agent instance per task (respects ONE AGENT = ONE TASK JSON rule)
+
+#### 3. Phased Execution
+**When**: IMPL_PLAN specifies "Phased" with phase breakdown
+**Pattern**: Execute tasks in phases, respect phase boundaries
+**TodoWrite**: Within each phase, follow Sequential or Parallel rules
+
+#### 4. Intelligent Fallback
+**When**: IMPL_PLAN lacks execution strategy details
+**Pattern**: Analyze task structure and apply smart defaults
+**TodoWrite**: Follow Sequential or Parallel rules based on analysis
 
 ### Task Status Logic
 ```
@@ -182,155 +241,36 @@ completed → skip
 blocked → skip until dependencies clear
 ```
 
-## Batch Execution with Dependency Graph
-
-### Parallel Execution Algorithm
-**Core principle**: Execute independent tasks concurrently in batches based on dependency graph.
-
-#### Algorithm Steps (Optimized with Lazy Loading)
-```javascript
-function executeBatchWorkflow(sessionId) {
-  // 1. Build dependency graph from TODO_LIST.md (NOT task JSONs)
-  const graph = buildDependencyGraphFromTodoList(`.workflow/${sessionId}/TODO_LIST.md`);
-
-  // 2. Process batches until graph is empty
-  while (!graph.isEmpty()) {
-    // 3. Identify current batch (tasks with in-degree = 0)
-    const batch = graph.getNodesWithInDegreeZero();
-
-    // 4. Load task JSONs ONLY for current batch (lazy loading)
-    const batchTaskJsons = batch.map(taskId =>
-      Read(`.workflow/${sessionId}/.task/${taskId}.json`)
-    );
-
-    // 5. Check for parallel execution opportunities
-    const parallelGroups = groupByExecutionGroup(batchTaskJsons);
-
-    // 6. Execute batch concurrently
-    await Promise.all(
-      parallelGroups.map(group => executeBatch(group))
-    );
-
-    // 7. Update graph: remove completed tasks and their edges
-    graph.removeNodes(batch);
-
-    // 8. Update TODO_LIST.md and TodoWrite to reflect completed batch
-    updateTodoListAfterBatch(batch);
-    updateTodoWriteAfterBatch(batch);
-  }
-
-  // 9. All tasks complete - auto-complete session
-  SlashCommand("/workflow:session:complete");
-}
-
-function buildDependencyGraphFromTodoList(todoListPath) {
-  const todoContent = Read(todoListPath);
-  const tasks = parseTodoListTasks(todoContent);
-  const graph = new DirectedGraph();
-
-  tasks.forEach(task => {
-    graph.addNode(task.id, { id: task.id, title: task.title, status: task.status });
-    task.dependencies?.forEach(depId => graph.addEdge(depId, task.id));
-  });
-
-  return graph;
-}
-
-function parseTodoListTasks(todoContent) {
-  // Parse: - [ ] **IMPL-001**: Task title → [📋](./.task/IMPL-001.json)
-  const taskPattern = /- \[([ x])\] \*\*([A-Z]+-\d+(?:\.\d+)?)\*\*: (.+?) →/g;
-  const tasks = [];
-  let match;
-
-  while ((match = taskPattern.exec(todoContent)) !== null) {
-    tasks.push({
-      status: match[1] === 'x' ? 'completed' : 'pending',
-      id: match[2],
-      title: match[3]
-    });
-  }
-
-  return tasks;
-}
-
-function groupByExecutionGroup(tasks) {
-  const groups = {};
-
-  tasks.forEach(task => {
-    const groupId = task.meta.execution_group || task.id;
-    if (!groups[groupId]) groups[groupId] = [];
-    groups[groupId].push(task);
-  });
-
-  return Object.values(groups);
-}
-
-async function executeBatch(tasks) {
-  // Execute all tasks in batch concurrently
-  return Promise.all(
-    tasks.map(task => executeTask(task))
-  );
-}
-```
-
-#### Execution Group Rules
-1. **Same `execution_group` ID** → Execute in parallel (independent, different contexts)
-2. **No `execution_group` (null)** → Execute sequentially (has dependencies)
-3. **Different `execution_group` IDs** → Execute in parallel (independent batches)
-4. **Same `context_signature`** → Should have been merged (warning if not)
-
-#### Parallel Execution Example
-```
-Batch 1 (no dependencies):
-  - IMPL-1.1 (execution_group: "parallel-auth-api") → Agent 1
-  - IMPL-1.2 (execution_group: "parallel-ui-comp") → Agent 2
-  - IMPL-1.3 (execution_group: "parallel-db-schema") → Agent 3
-
-Wait for Batch 1 completion...
-
-Batch 2 (depends on Batch 1):
-  - IMPL-2.1 (execution_group: null, depends_on: [IMPL-1.1, IMPL-1.2]) → Agent 1
-
-Wait for Batch 2 completion...
-
-Batch 3 (independent of Batch 2):
-  - IMPL-3.1 (execution_group: "parallel-tests-1") → Agent 1
-  - IMPL-3.2 (execution_group: "parallel-tests-2") → Agent 2
-```
-
 ## TodoWrite Coordination
-**Comprehensive workflow tracking** with immediate status updates throughout entire execution without user interruption:
 
-#### TodoWrite Workflow Rules
-1. **Initial Creation**: Generate TodoWrite from discovered pending tasks for entire workflow
-   - **Normal Mode**: Create from discovery results
-   - **Resume Mode**: Create from existing session state and current progress
-2. **Parallel Task Support**:
-   - **Single-task execution**: Mark ONLY ONE task as `in_progress` at a time
-   - **Batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
-   - **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
-3. **Immediate Updates**: Update status after each task/batch completion without user interruption
-4. **Status Synchronization**: Sync with JSON task files after updates
-5. **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
+### TodoWrite Rules (Unified)
 
-#### Resume Mode TodoWrite Generation
-**Special behavior when `--resume-session` flag is present**:
-- Load existing session progress from `.workflow/{session-id}/TODO_LIST.md`
-- Identify currently in-progress or next pending task
-- Generate TodoWrite starting from interruption point
-- Preserve completed task history in TodoWrite display
-- Focus on remaining pending tasks for execution
+**Rule 1: Initial Creation**
+- **Normal Mode**: Generate TodoWrite from discovered pending tasks for entire workflow
+- **Resume Mode**: Generate from existing session state and current progress
 
-#### TodoWrite Tool Usage
-**Use Claude Code's built-in TodoWrite tool** to track workflow progress in real-time:
+**Rule 2: In-Progress Task Count (Execution-Model-Dependent)**
+- **Sequential execution**: Mark ONLY ONE task as `in_progress` at a time
+- **Parallel batch execution**: Mark ALL tasks in current batch as `in_progress` simultaneously
+- **Execution group indicator**: Show `[execution_group: group-id]` for parallel tasks
 
+**Rule 3: Status Updates**
+- **Immediate Updates**: Update status after each task/batch completion without user interruption
+- **Status Synchronization**: Sync with JSON task files after updates
+- **Continuous Tracking**: Maintain TodoWrite throughout entire workflow execution until completion
+
+**Rule 4: Workflow Completion Check**
+- When all tasks marked `completed`, auto-call `/workflow:session:complete`
+
+### TodoWrite Tool Usage
+
+**Example 1: Sequential Execution**
 ```javascript
-// Example 1: Sequential execution (traditional)
 TodoWrite({
   todos: [
     {
       content: "Execute IMPL-1.1: Design auth schema [code-developer] [FLOW_CONTROL]",
-      status: "in_progress",  // Single task in progress
+      status: "in_progress",  // ONE task in progress
       activeForm: "Executing IMPL-1.1: Design auth schema"
     },
     {
@@ -340,8 +280,10 @@ TodoWrite({
     }
   ]
 });
+```
 
-// Example 2: Batch execution (parallel tasks with execution_group)
+**Example 2: Parallel Batch Execution**
+```javascript
 TodoWrite({
   todos: [
     {
@@ -366,255 +308,50 @@ TodoWrite({
     }
   ]
 });
-
-// Example 3: After batch completion
-TodoWrite({
-  todos: [
-    {
-      content: "Execute IMPL-1.1: Build Auth API [code-developer] [execution_group: parallel-auth-api]",
-      status: "completed",  // Batch completed
-      activeForm: "Executing IMPL-1.1: Build Auth API"
-    },
-    {
-      content: "Execute IMPL-1.2: Build User UI [code-developer] [execution_group: parallel-ui-comp]",
-      status: "completed",  // Batch completed
-      activeForm: "Executing IMPL-1.2: Build User UI"
-    },
-    {
-      content: "Execute IMPL-1.3: Setup Database [code-developer] [execution_group: parallel-db-schema]",
-      status: "completed",  // Batch completed
-      activeForm: "Executing IMPL-1.3: Setup Database"
-    },
-    {
-      content: "Execute IMPL-2.1: Integration Tests [test-fix-agent]",
-      status: "in_progress",  // Next batch started
-      activeForm: "Executing IMPL-2.1: Integration Tests"
-    }
-  ]
-});
 ```
 
-**TodoWrite Integration Rules**:
-- **Continuous Workflow Tracking**: Use TodoWrite tool throughout entire workflow execution
-- **Real-time Updates**: Immediate progress tracking without user interruption
-- **Single Active Task**: Only ONE task marked as `in_progress` at any time
-- **Immediate Completion**: Mark tasks `completed` immediately after finishing
-- **Status Sync**: Sync TodoWrite status with JSON task files after each update
-- **Full Execution**: Continue TodoWrite tracking until all workflow tasks complete
-- **Workflow Completion Check**: When all tasks marked `completed`, auto-call `/workflow:session:complete`
+## Agent Execution Pattern
 
-#### TODO_LIST.md Update Timing
-**Single source of truth for task status** - enables lazy loading by providing task metadata without reading JSONs
+### Flow Control Execution
+**[FLOW_CONTROL]** marker indicates task JSON contains `flow_control.pre_analysis` steps for context preparation.
 
-- **Before Agent Launch**: Mark task as `in_progress` (⚠️)
-- **After Task Complete**: Mark as `completed` (✅), advance to next
-- **On Error**: Keep as `in_progress`, add error note
-- **Workflow Complete**: Call `/workflow:session:complete`
+**Note**: Orchestrator does NOT execute flow control steps - Agent interprets and executes them autonomously.
 
-### 3. Agent Context Management
-**Comprehensive context preparation** for autonomous agent execution:
+### Agent Prompt Template
+**Dynamic Generation**: Before agent invocation, read task JSON and extract key requirements.
 
-#### Context Sources (Priority Order)
-1. **Complete Task JSON**: Full task definition including all fields and artifacts
-2. **Artifacts Context**: Brainstorming outputs and role analysess from task.context.artifacts
-3. **Flow Control Context**: Accumulated outputs from pre_analysis steps (including artifact loading)
-4. **Dependency Summaries**: Previous task completion summaries
-5. **Session Context**: Workflow paths and session metadata
-6. **Inherited Context**: Parent task context and shared variables
-
-#### Context Assembly Process
-```
-1. Load Task JSON → Base context (including artifacts array)
-2. Load Artifacts → Synthesis specifications and brainstorming outputs
-3. Execute Flow Control → Accumulated context (with artifact loading steps)
-4. Load Dependencies → Dependency context
-5. Prepare Session Paths → Session context
-6. Combine All → Complete agent context with artifact integration
-```
-
-#### Agent Context Package Structure
-```json
-{
-  "task": { /* Complete task JSON with artifacts array */ },
-  "artifacts": {
-    "synthesis_specification": { "path": "{{from context-package.json → brainstorm_artifacts.synthesis_output.path}}", "priority": "highest" },
-    "guidance_specification": { "path": "{{from context-package.json → brainstorm_artifacts.guidance_specification.path}}", "priority": "medium" },
-    "role_analyses": [ /* From context-package.json → brainstorm_artifacts.role_analyses[] */ ],
-    "conflict_resolution": { "path": "{{from context-package.json → brainstorm_artifacts.conflict_resolution.path}}", "conditional": true }
-  },
-  "flow_context": {
-    "step_outputs": {
-      "synthesis_specification": "...",
-      "individual_artifacts": "...",
-      "pattern_analysis": "...",
-      "dependency_context": "..."
-    }
-  },
-  "session": {
-    "workflow_dir": ".workflow/WFS-session/",
-    "context_package_path": ".workflow/WFS-session/.process/context-package.json",
-    "todo_list_path": ".workflow/WFS-session/TODO_LIST.md",
-    "summaries_dir": ".workflow/WFS-session/.summaries/",
-    "task_json_path": ".workflow/WFS-session/.task/IMPL-1.1.json"
-  },
-  "dependencies": [ /* Task summaries from depends_on */ ],
-  "inherited": { /* Parent task context */ }
-}
-```
-
-#### Context Validation Rules
-- **Task JSON Complete**: All 5 fields present and valid, including artifacts array in context
-- **Artifacts Available**: All artifacts loaded from context-package.json
-- **Flow Control Ready**: All pre_analysis steps completed including artifact loading steps
-- **Dependencies Loaded**: All depends_on summaries available
-- **Session Paths Valid**: All workflow paths exist and accessible (verified via context-package.json)
-- **Agent Assignment**: Valid agent type specified in meta.agent
-
-### 4. Agent Execution Pattern
-**Structured agent invocation** with complete context and clear instructions:
-
-#### Agent Prompt Template
 ```bash
 Task(subagent_type="{meta.agent}",
-     prompt="**EXECUTE TASK FROM JSON**
+     prompt="Execute task: {task.title}
 
-     ## Task JSON Location
-     {session.task_json_path}
+     {[FLOW_CONTROL]}
 
-     ## Instructions
-     1. **Load Complete Task JSON**: Read and validate all fields (id, title, status, meta, context, flow_control)
-     2. **Execute Flow Control**: If `flow_control.pre_analysis` exists, execute steps sequentially:
-        - Load artifacts (role analysis documents, role analyses) using commands in each step
-        - Accumulate context from step outputs using variable substitution [variable_name]
-        - Handle errors per step.on_error (skip_optional | fail | retry_once)
-     3. **Implement Solution**: Follow `flow_control.implementation_approach` using accumulated context
-     4. **Complete Task**:
-        - Update task status: `jq '.status = \"completed\"' {session.task_json_path} > temp.json && mv temp.json {session.task_json_path}`
-        - Update TODO_LIST.md: Mark task as [x] completed in {session.todo_list_path}
-        - Generate summary: {session.summaries_dir}/{task.id}-summary.md
-        - Check workflow completion and call `/workflow:session:complete` if all tasks done
+     **Task Objectives** (from task JSON):
+     {task.context.objective}
 
-     ## Context Sources (All from JSON)
-     - Requirements: `context.requirements`
-     - Focus Paths: `context.focus_paths`
-     - Acceptance: `context.acceptance`
-     - Artifacts: `context.artifacts` (synthesis specs, brainstorming outputs)
-     - Dependencies: `context.depends_on`
-     - Target Files: `flow_control.target_files`
+     **Expected Deliverables** (from task JSON):
+     {task.context.deliverables}
 
-     ## Session Paths
+     **Quality Standards** (from task JSON):
+     {task.context.acceptance_criteria}
+
+     **MANDATORY FIRST STEPS**:
+     1. Read complete task JSON: {session.task_json_path}
+     2. Load context package: {session.context_package_path}
+
+     Follow complete execution guidelines in @.claude/agents/{meta.agent}.md
+
+     **Session Paths**:
      - Workflow Dir: {session.workflow_dir}
      - TODO List: {session.todo_list_path}
-     - Summaries: {session.summaries_dir}
-     - Flow Context: {flow_context.step_outputs}
+     - Summaries Dir: {session.summaries_dir}
+     - Context Package: {session.context_package_path}
 
-     **Complete JSON structure is authoritative - load and follow it exactly.**"),
-     description="Execute task: {task.id}")
+     **Success Criteria**: Complete all objectives, meet all quality standards, deliver all outputs as specified above.",
+     description="Executing: {task.title}")
 ```
 
-#### Agent JSON Loading Specification
-**MANDATORY AGENT PROTOCOL**: All agents must follow this exact loading sequence:
-
-1. **JSON Loading**: First action must be `cat {session.task_json_path}`
-2. **Field Validation**: Verify all 5 required fields exist: `id`, `title`, `status`, `meta`, `context`, `flow_control`
-3. **Structure Parsing**: Parse nested fields correctly:
-   - `meta.type` and `meta.agent` (NOT flat `task_type`)
-   - `context.requirements`, `context.focus_paths`, `context.acceptance`
-   - `context.depends_on`, `context.inherited`
-   - `flow_control.pre_analysis` array, `flow_control.target_files`
-4. **Flow Control Execution**: If `flow_control.pre_analysis` exists, execute steps sequentially
-5. **Status Management**: Update JSON status upon completion
-
-**JSON Field Reference**:
-```json
-{
-  "id": "IMPL-1.2",
-  "title": "Task title",
-  "status": "pending|active|completed|blocked",
-  "meta": {
-    "type": "feature|bugfix|refactor|test-gen|test-fix|docs",
-    "agent": "@code-developer|@test-fix-agent|@universal-executor"
-  },
-  "context": {
-    "requirements": ["req1", "req2"],
-    "focus_paths": ["src/path1", "src/path2"],
-    "acceptance": ["criteria1", "criteria2"],
-    "depends_on": ["IMPL-1.1"],
-    "inherited": { "from": "parent", "context": ["info"] },
-    "artifacts": [
-      {
-        "type": "synthesis_specification",
-        "source": "context-package.json → brainstorm_artifacts.synthesis_output",
-        "path": "{{loaded dynamically from context-package.json}}",
-        "priority": "highest",
-        "contains": "complete_integrated_specification"
-      },
-      {
-        "type": "individual_role_analysis",
-        "source": "context-package.json → brainstorm_artifacts.role_analyses[]",
-        "path": "{{loaded dynamically from context-package.json}}",
-        "note": "Supports analysis*.md pattern (analysis.md, analysis-01.md, analysis-api.md, etc.)",
-        "priority": "low",
-        "contains": "role_specific_analysis_fallback"
-      }
-    ]
-  },
-  "flow_control": {
-    "pre_analysis": [
-      {
-        "step": "load_synthesis_specification",
-        "action": "Load synthesis specification from context-package.json",
-        "commands": [
-          "Read(.workflow/WFS-[session]/.process/context-package.json)",
-          "Extract(brainstorm_artifacts.synthesis_output.path)",
-          "Read(extracted path)"
-        ],
-        "output_to": "synthesis_specification",
-        "on_error": "skip_optional"
-      },
-      {
-        "step": "step_name",
-        "command": "bash_command",
-        "output_to": "variable",
-        "on_error": "skip_optional|fail|retry_once"
-      }
-    ],
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Implement task following role analyses",
-        "description": "Implement '[title]' following role analyses. PRIORITY: Use role analysis documents as primary requirement source. When implementation needs technical details (e.g., API schemas, caching configs, design tokens), refer to artifacts[] for detailed specifications from original role analyses.",
-        "modification_points": [
-          "Apply consolidated requirements from role analysis documents",
-          "Follow technical guidelines from synthesis",
-          "Consult artifacts for implementation details when needed",
-          "Integrate with existing patterns"
-        ],
-        "logic_flow": [
-          "Load role analyses",
-          "Parse architecture and requirements",
-          "Implement following specification",
-          "Consult artifacts for technical details when needed",
-          "Validate against acceptance criteria"
-        ],
-        "depends_on": [],
-        "output": "implementation"
-      }
-    ],
-    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
-  }
-}
-```
-
-#### Execution Flow
-1. **Load Task JSON**: Agent reads and validates complete JSON structure
-2. **Execute Flow Control**: Agent runs pre_analysis steps if present
-3. **Prepare Implementation**: Agent uses implementation_approach from JSON
-4. **Launch Implementation**: Agent follows focus_paths and target_files
-5. **Update Status**: Agent marks JSON status as completed
-6. **Generate Summary**: Agent creates completion summary
-
-#### Agent Assignment Rules
+### Agent Assignment Rules
 ```
 meta.agent specified → Use specified agent
 meta.agent missing → Infer from meta.type:
@@ -625,18 +362,12 @@ meta.agent missing → Infer from meta.type:
   - "docs" → @doc-generator
 ```
 
-#### Error Handling During Execution
-- **Agent Failure**: Retry once with adjusted context
-- **Flow Control Error**: Skip optional steps, fail on critical
-- **Context Missing**: Reload from JSON files and retry
-- **Timeout**: Mark as blocked, continue with next task
-
 ## Workflow File Structure Reference
 ```
-.workflow/WFS-[topic-slug]/
+.workflow/active/WFS-[topic-slug]/
 ├── workflow-session.json     # Session state and metadata
 ├── IMPL_PLAN.md             # Planning document and requirements
-├── TODO_LIST.md             # Progress tracking (auto-updated)
+├── TODO_LIST.md             # Progress tracking (updated by agents)
 ├── .task/                   # Task definitions (JSON only)
 │   ├── IMPL-1.json          # Main task definitions
 │   └── IMPL-1.1.json        # Subtask definitions
@@ -644,78 +375,26 @@ meta.agent missing → Infer from meta.type:
 │   ├── IMPL-1-summary.md    # Task completion details
 │   └── IMPL-1.1-summary.md  # Subtask completion details
 └── .process/                # Planning artifacts
+    ├── context-package.json # Smart context package
     └── ANALYSIS_RESULTS.md  # Planning analysis results
 ```
 
 ## Error Handling & Recovery
 
-### Discovery Phase Errors
-| Error | Cause | Resolution | Command |
-|-------|-------|------------|---------|
-| No active session | No `.active-*` markers found | Create or resume session | `/workflow:plan "project"` |
-| Multiple sessions | Multiple `.active-*` markers | Select specific session | Manual choice prompt |
-| Corrupted session | Invalid JSON files | Recreate session structure | `/workflow:session:status --validate` |
-| Missing task files | Broken task references | Regenerate tasks | `/task:create` or repair |
+### Common Errors & Recovery
 
-### Execution Phase Errors
-| Error | Cause | Recovery Strategy | Max Attempts |
-|-------|-------|------------------|--------------|
+| Error Type | Cause | Recovery Strategy | Max Attempts |
+|-----------|-------|------------------|--------------|
+| **Discovery Errors** |
+| No active session | No sessions in `.workflow/active/` | Create or resume session: `/workflow:plan "project"` | N/A |
+| Multiple sessions | Multiple sessions in `.workflow/active/` | Prompt user selection | N/A |
+| Corrupted session | Invalid JSON files | Recreate session structure or validate files | N/A |
+| **Execution Errors** |
 | Agent failure | Agent crash/timeout | Retry with simplified context | 2 |
 | Flow control error | Command failure | Skip optional, fail critical | 1 per step |
 | Context loading error | Missing dependencies | Reload from JSON, use defaults | 3 |
 | JSON file corruption | File system issues | Restore from backup/recreate | 1 |
 
-### Recovery Procedures
-
-#### Session Recovery
-```bash
-# Check session integrity
-find .workflow -name ".active-*" | while read marker; do
-  session=$(basename "$marker" | sed 's/^\.active-//')
-  if [ ! -d ".workflow/$session" ]; then
-    echo "Removing orphaned marker: $marker"
-    rm "$marker"
-  fi
-done
-
-# Recreate corrupted session files
-if [ ! -f ".workflow/$session/workflow-session.json" ]; then
-  echo '{"session_id":"'$session'","status":"active"}' > ".workflow/$session/workflow-session.json"
-fi
-```
-
-#### Task Recovery
-```bash
-# Validate task JSON integrity
-for task_file in .workflow/$session/.task/*.json; do
-  if ! jq empty "$task_file" 2>/dev/null; then
-    echo "Corrupted task file: $task_file"
-    # Backup and regenerate or restore from backup
-  fi
-done
-
-# Fix missing dependencies
-missing_deps=$(jq -r '.context.depends_on[]?' .workflow/$session/.task/*.json | sort -u)
-for dep in $missing_deps; do
-  if [ ! -f ".workflow/$session/.task/$dep.json" ]; then
-    echo "Missing dependency: $dep - creating placeholder"
-  fi
-done
-```
-
-#### Context Recovery
-```bash
-# Reload context from available sources
-if [ -f ".workflow/$session/.process/ANALYSIS_RESULTS.md" ]; then
-  echo "Reloading planning context..."
-fi
-
-# Restore from documentation if available
-if [ -d ".workflow/docs/" ]; then
-  echo "Using documentation context as fallback..."
-fi
-```
-
 ### Error Prevention
 - **Pre-flight Checks**: Validate session integrity before execution
 - **Backup Strategy**: Create task snapshots before major operations
@@ -723,16 +402,3 @@ fi
 - **Dependency Validation**: Check all depends_on references exist
 - **Context Verification**: Ensure all required context is available
 
-## Usage Examples
-
-### Basic Usage
-```bash
-/workflow:execute          # Execute all pending tasks autonomously
-/workflow:session:status           # Check progress
-/task:execute IMPL-1.2     # Execute specific task
-```
-
-### Integration
-- **Planning**: `/workflow:plan` → `/workflow:execute` → `/workflow:review`
-- **Recovery**: `/workflow:status --validate` → `/workflow:execute`
-

.claude/commands/workflow/init.md

@@ -0,0 +1,160 @@
+---
+name: init
+description: Initialize project-level state with intelligent project analysis using cli-explore-agent
+argument-hint: "[--regenerate]"
+examples:
+  - /workflow:init
+  - /workflow:init --regenerate
+---
+
+# Workflow Init Command (/workflow:init)
+
+## Overview
+Initialize `.workflow/project.json` with comprehensive project understanding by delegating analysis to **cli-explore-agent**.
+
+**Note**: This command may be called by other workflow commands. Upon completion, return immediately to continue the calling workflow without interrupting the task flow.
+
+## Usage
+```bash
+/workflow:init                 # Initialize (skip if exists)
+/workflow:init --regenerate    # Force regeneration
+```
+
+## Implementation
+
+### Step 1: Check Existing State
+
+```bash
+bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
+```
+
+**If EXISTS and no --regenerate**: Exit early
+```
+Project already initialized at .workflow/project.json
+Use /workflow:init --regenerate to rebuild
+Use /workflow:status --project to view state
+```
+
+### Step 2: Get Project Metadata
+
+```bash
+bash(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
+bash(git rev-parse --show-toplevel 2>/dev/null || pwd)
+bash(mkdir -p .workflow)
+```
+
+### Step 3: Invoke cli-explore-agent
+
+**For --regenerate**: Backup and preserve existing data
+```bash
+bash(cp .workflow/project.json .workflow/project.json.backup)
+```
+
+**Delegate analysis to agent**:
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  description="Deep project analysis",
+  prompt=`
+Analyze project for workflow initialization and generate .workflow/project.json.
+
+## Output Schema Reference
+~/.claude/workflows/cli-templates/schemas/project-json-schema.json
+
+## Task
+Generate complete project.json with:
+- project_name: ${projectName}
+- initialized_at: current ISO timestamp
+- overview: {description, technology_stack, architecture, key_components, entry_points, metrics}
+- features: ${regenerate ? 'preserve from backup' : '[] (empty)'}
+- statistics: ${regenerate ? 'preserve from backup' : '{total_features: 0, total_sessions: 0, last_updated}'}
+- memory_resources: {skills, documentation, module_docs, gaps, last_scanned}
+- _metadata: {initialized_by: "cli-explore-agent", analysis_timestamp, analysis_mode}
+
+## Analysis Requirements
+
+**Technology Stack**:
+- Languages: File counts, mark primary
+- Frameworks: From package.json, requirements.txt, go.mod, etc.
+- Build tools: npm, cargo, maven, webpack, vite
+- Test frameworks: jest, pytest, go test, junit
+
+**Architecture**:
+- Style: MVC, microservices, layered (from structure & imports)
+- Layers: presentation, business-logic, data-access
+- Patterns: singleton, factory, repository
+- Key components: 5-10 modules {name, path, description, importance}
+
+**Metrics**:
+- total_files: Source files (exclude tests/configs)
+- lines_of_code: Use find + wc -l
+- module_count: Use ~/.claude/scripts/get_modules_by_depth.sh
+- complexity: low | medium | high
+
+**Entry Points**:
+- main: index.ts, main.py, main.go
+- cli_commands: package.json scripts, Makefile targets
+- api_endpoints: HTTP/REST routes (if applicable)
+
+**Memory Resources**:
+- skills: Scan .claude/skills/ → [{name, type, path}]
+- documentation: Scan .workflow/docs/ → [{name, path, has_readme, has_architecture}]
+- module_docs: Find **/CLAUDE.md (exclude node_modules, .git)
+- gaps: Identify missing resources
+
+## Execution
+1. Structural scan: get_modules_by_depth.sh, find, wc -l
+2. Semantic analysis: Gemini for patterns/architecture
+3. Synthesis: Merge findings
+4. ${regenerate ? 'Merge with preserved features/statistics from .workflow/project.json.backup' : ''}
+5. Write JSON: Write('.workflow/project.json', jsonContent)
+6. Report: Return brief completion summary
+
+Project root: ${projectRoot}
+`
+)
+```
+
+### Step 4: Display Summary
+
+```javascript
+const projectJson = JSON.parse(Read('.workflow/project.json'));
+
+console.log(`
+✓ Project initialized successfully
+
+## Project Overview
+Name: ${projectJson.project_name}
+Description: ${projectJson.overview.description}
+
+### Technology Stack
+Languages: ${projectJson.overview.technology_stack.languages.map(l => l.name).join(', ')}
+Frameworks: ${projectJson.overview.technology_stack.frameworks.join(', ')}
+
+### Architecture
+Style: ${projectJson.overview.architecture.style}
+Components: ${projectJson.overview.key_components.length} core modules
+
+### Metrics
+Files: ${projectJson.overview.metrics.total_files}
+LOC: ${projectJson.overview.metrics.lines_of_code}
+Complexity: ${projectJson.overview.metrics.complexity}
+
+### Memory Resources
+SKILL Packages: ${projectJson.memory_resources.skills.length}
+Documentation: ${projectJson.memory_resources.documentation.length}
+Module Docs: ${projectJson.memory_resources.module_docs.length}
+Gaps: ${projectJson.memory_resources.gaps.join(', ') || 'none'}
+
+---
+Project state: .workflow/project.json
+${regenerate ? 'Backup: .workflow/project.json.backup' : ''}
+`);
+```
+
+## Error Handling
+
+**Agent Failure**: Fall back to basic initialization with placeholder overview
+**Missing Tools**: Agent uses Qwen fallback or bash-only
+**Empty Project**: Create minimal JSON with all gaps identified

.claude/commands/workflow/lite-execute.md

@@ -0,0 +1,585 @@
+---
+name: lite-execute
+description: Execute tasks based on in-memory plan, prompt description, or file content
+argument-hint: "[--in-memory] [\"task description\"|file-path]"
+allowed-tools: TodoWrite(*), Task(*), Bash(*)
+---
+
+# Workflow Lite-Execute Command (/workflow:lite-execute)
+
+## Overview
+
+Flexible task execution command supporting three input modes: in-memory plan (from lite-plan), direct prompt description, or file content. Handles execution orchestration, progress tracking, and optional code review.
+
+**Core capabilities:**
+- Multi-mode input (in-memory plan, prompt description, or file path)
+- Execution orchestration (Agent or Codex) with full context
+- Live progress tracking via TodoWrite at execution call level
+- Optional code review with selected tool (Gemini, Agent, or custom)
+- Context continuity across multiple executions
+- Intelligent format detection (Enhanced Task JSON vs plain text)
+
+## Usage
+
+### Command Syntax
+```bash
+/workflow:lite-execute [FLAGS] <INPUT>
+
+# Flags
+--in-memory                Use plan from memory (called by lite-plan)
+
+# Arguments
+<input>                    Task description string, or path to file (required)
+```
+
+## Input Modes
+
+### Mode 1: In-Memory Plan
+
+**Trigger**: Called by lite-plan after Phase 4 approval with `--in-memory` flag
+
+**Input Source**: `executionContext` global variable set by lite-plan
+
+**Content**: Complete execution context (see Data Structures section)
+
+**Behavior**:
+- Skip execution method selection (already set by lite-plan)
+- Directly proceed to execution with full context
+- All planning artifacts available (exploration, clarifications, plan)
+
+### Mode 2: Prompt Description
+
+**Trigger**: User calls with task description string
+
+**Input**: Simple task description (e.g., "Add unit tests for auth module")
+
+**Behavior**:
+- Store prompt as `originalUserInput`
+- Create simple execution plan from prompt
+- AskUserQuestion: Select execution method (Agent/Codex/Auto)
+- AskUserQuestion: Select code review tool (Skip/Gemini/Agent/Other)
+- Proceed to execution with `originalUserInput` included
+
+**User Interaction**:
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Select execution method:",
+      header: "Execution",
+      multiSelect: false,
+      options: [
+        { label: "Agent", description: "@code-developer agent" },
+        { label: "Codex", description: "codex CLI tool" },
+        { label: "Auto", description: "Auto-select based on complexity" }
+      ]
+    },
+    {
+      question: "Enable code review after execution?",
+      header: "Code Review",
+      multiSelect: false,
+      options: [
+        { label: "Skip", description: "No review" },
+        { label: "Gemini Review", description: "Gemini CLI tool" },
+        { label: "Agent Review", description: "Current agent review" }
+      ]
+    }
+  ]
+})
+```
+
+### Mode 3: File Content
+
+**Trigger**: User calls with file path
+
+**Input**: Path to file containing task description or Enhanced Task JSON
+
+**Step 1: Read and Detect Format**
+
+```javascript
+fileContent = Read(filePath)
+
+// Attempt JSON parsing
+try {
+  jsonData = JSON.parse(fileContent)
+
+  // Check if Enhanced Task JSON from lite-plan
+  if (jsonData.meta?.workflow === "lite-plan") {
+    // Extract plan data
+    planObject = {
+      summary: jsonData.context.plan.summary,
+      approach: jsonData.context.plan.approach,
+      tasks: jsonData.context.plan.tasks,
+      estimated_time: jsonData.meta.estimated_time,
+      recommended_execution: jsonData.meta.recommended_execution,
+      complexity: jsonData.meta.complexity
+    }
+    explorationContext = jsonData.context.exploration || null
+    clarificationContext = jsonData.context.clarifications || null
+    originalUserInput = jsonData.title
+
+    isEnhancedTaskJson = true
+  } else {
+    // Valid JSON but not Enhanced Task JSON - treat as plain text
+    originalUserInput = fileContent
+    isEnhancedTaskJson = false
+  }
+} catch {
+  // Not valid JSON - treat as plain text prompt
+  originalUserInput = fileContent
+  isEnhancedTaskJson = false
+}
+```
+
+**Step 2: Create Execution Plan**
+
+If `isEnhancedTaskJson === true`:
+- Use extracted `planObject` directly
+- Skip planning, use lite-plan's existing plan
+- User still selects execution method and code review
+
+If `isEnhancedTaskJson === false`:
+- Treat file content as prompt (same behavior as Mode 2)
+- Create simple execution plan from content
+
+**Step 3: User Interaction**
+
+- AskUserQuestion: Select execution method (Agent/Codex/Auto)
+- AskUserQuestion: Select code review tool
+- Proceed to execution with full context
+
+## Execution Process
+
+### Workflow Overview
+
+```
+Input Processing → Mode Detection
+    |
+    v
+[Mode 1] --in-memory: Load executionContext → Skip selection
+[Mode 2] Prompt: Create plan → User selects method + review
+[Mode 3] File: Detect format → Extract plan OR treat as prompt → User selects
+    |
+    v
+Execution & Progress Tracking
+    ├─ Step 1: Initialize execution tracking
+    ├─ Step 2: Create TodoWrite execution list
+    ├─ Step 3: Launch execution (Agent or Codex)
+    ├─ Step 4: Track execution progress
+    └─ Step 5: Code review (optional)
+    |
+    v
+Execution Complete
+```
+
+## Detailed Execution Steps
+
+### Step 1: Initialize Execution Tracking
+
+**Operations**:
+- Initialize result tracking for multi-execution scenarios
+- Set up `previousExecutionResults` array for context continuity
+
+```javascript
+// Initialize result tracking
+previousExecutionResults = []
+```
+
+### Step 2: Task Grouping & Batch Creation
+
+**Dependency Analysis & Grouping Algorithm**:
+```javascript
+// Infer dependencies: same file → sequential, keywords (use/integrate) → sequential
+function inferDependencies(tasks) {
+  return tasks.map((task, i) => {
+    const deps = []
+    const file = task.file || task.title.match(/in\s+([^\s:]+)/)?.[1]
+    const keywords = (task.description || task.title).toLowerCase()
+
+    for (let j = 0; j < i; j++) {
+      const prevFile = tasks[j].file || tasks[j].title.match(/in\s+([^\s:]+)/)?.[1]
+      if (file && prevFile === file) deps.push(j)  // Same file
+      else if (/use|integrate|call|import/.test(keywords)) deps.push(j)  // Keyword dependency
+    }
+    return { ...task, taskIndex: i, dependencies: deps }
+  })
+}
+
+// Group into batches: independent → parallel [P1,P2...], dependent → sequential [S1,S2...]
+function createExecutionCalls(tasks, executionMethod) {
+  const tasksWithDeps = inferDependencies(tasks)
+  const maxBatch = executionMethod === "Codex" ? 4 : 7
+  const calls = []
+  const processed = new Set()
+
+  // Parallel: independent tasks, different files, max batch size
+  const parallelGroups = []
+  tasksWithDeps.forEach(t => {
+    if (t.dependencies.length === 0 && !processed.has(t.taskIndex)) {
+      const group = [t]
+      processed.add(t.taskIndex)
+      tasksWithDeps.forEach(o => {
+        if (!o.dependencies.length && !processed.has(o.taskIndex) &&
+            group.length < maxBatch && t.file !== o.file) {
+          group.push(o)
+          processed.add(o.taskIndex)
+        }
+      })
+      parallelGroups.push(group)
+    }
+  })
+
+  // Sequential: dependent tasks, batch when deps satisfied
+  const remaining = tasksWithDeps.filter(t => !processed.has(t.taskIndex))
+  while (remaining.length > 0) {
+    const batch = remaining.filter((t, i) =>
+      i < maxBatch && t.dependencies.every(d => processed.has(d))
+    )
+    if (!batch.length) break
+    batch.forEach(t => processed.add(t.taskIndex))
+    calls.push({ executionType: "sequential", groupId: `S${calls.length + 1}`, tasks: batch })
+    remaining.splice(0, remaining.length, ...remaining.filter(t => !processed.has(t.taskIndex)))
+  }
+
+  // Combine results
+  return [
+    ...parallelGroups.map((g, i) => ({
+      method: executionMethod, executionType: "parallel", groupId: `P${i+1}`,
+      taskSummary: g.map(t => t.title).join(' | '), tasks: g
+    })),
+    ...calls.map(c => ({ ...c, method: executionMethod, taskSummary: c.tasks.map(t => t.title).join(' → ') }))
+  ]
+}
+
+executionCalls = createExecutionCalls(planObject.tasks, executionMethod).map(c => ({ ...c, id: `[${c.groupId}]` }))
+
+TodoWrite({
+  todos: executionCalls.map(c => ({
+    content: `${c.executionType === "parallel" ? "⚡" : "→"} ${c.id} (${c.tasks.length} tasks)`,
+    status: "pending",
+    activeForm: `Executing ${c.id}`
+  }))
+})
+```
+
+### Step 3: Launch Execution
+
+**Execution Flow**: Parallel batches concurrently → Sequential batches in order
+```javascript
+const parallel = executionCalls.filter(c => c.executionType === "parallel")
+const sequential = executionCalls.filter(c => c.executionType === "sequential")
+
+// Phase 1: Launch all parallel batches (single message with multiple tool calls)
+if (parallel.length > 0) {
+  TodoWrite({ todos: executionCalls.map(c => ({ status: c.executionType === "parallel" ? "in_progress" : "pending" })) })
+  parallelResults = await Promise.all(parallel.map(c => executeBatch(c)))
+  previousExecutionResults.push(...parallelResults)
+  TodoWrite({ todos: executionCalls.map(c => ({ status: parallel.includes(c) ? "completed" : "pending" })) })
+}
+
+// Phase 2: Execute sequential batches one by one
+for (const call of sequential) {
+  TodoWrite({ todos: executionCalls.map(c => ({ status: c === call ? "in_progress" : "..." })) })
+  result = await executeBatch(call)
+  previousExecutionResults.push(result)
+  TodoWrite({ todos: executionCalls.map(c => ({ status: "completed" or "pending" })) })
+}
+```
+
+**Option A: Agent Execution**
+
+When to use:
+- `executionMethod = "Agent"`
+- `executionMethod = "Auto" AND complexity = "Low"`
+
+Agent call format:
+```javascript
+function formatTaskForAgent(task, index) {
+  return `
+### Task ${index + 1}: ${task.title}
+**File**: ${task.file}
+**Action**: ${task.action}
+**Description**: ${task.description}
+
+**Implementation Steps**:
+${task.implementation.map((step, i) => `${i + 1}. ${step}`).join('\n')}
+
+**Reference**:
+- Pattern: ${task.reference.pattern}
+- Example Files: ${task.reference.files.join(', ')}
+- Guidance: ${task.reference.examples}
+
+**Acceptance Criteria**:
+${task.acceptance.map((criterion, i) => `${i + 1}. ${criterion}`).join('\n')}
+`
+}
+
+Task(
+  subagent_type="code-developer",
+  description="Implement planned tasks",
+  prompt=`
+  ${originalUserInput ? `## Original User Request\n${originalUserInput}\n\n` : ''}
+
+  ## Implementation Plan
+
+  **Summary**: ${planObject.summary}
+  **Approach**: ${planObject.approach}
+
+  ## Task Breakdown (${planObject.tasks.length} tasks)
+  ${planObject.tasks.map((task, i) => formatTaskForAgent(task, i)).join('\n')}
+
+  ${previousExecutionResults.length > 0 ? `\n## Previous Execution Results\n${previousExecutionResults.map(result => `
+[${result.executionId}] ${result.status}
+Tasks: ${result.tasksSummary}
+Completion: ${result.completionSummary}
+Outputs: ${result.keyOutputs || 'See git diff'}
+${result.notes ? `Notes: ${result.notes}` : ''}
+  `).join('\n---\n')}` : ''}
+
+  ## Code Context
+  ${explorationContext || "No exploration performed"}
+
+  ${clarificationContext ? `\n## Clarifications\n${JSON.stringify(clarificationContext, null, 2)}` : ''}
+
+  ${executionContext?.session?.artifacts ? `\n## Planning Artifacts
+  Detailed planning context available in:
+  ${executionContext.session.artifacts.exploration ? `- Exploration: ${executionContext.session.artifacts.exploration}` : ''}
+  - Plan: ${executionContext.session.artifacts.plan}
+  - Task: ${executionContext.session.artifacts.task}
+
+  Read these files for detailed architecture, patterns, and constraints.` : ''}
+
+  ## Requirements
+  MUST complete ALL ${planObject.tasks.length} tasks listed above in this single execution.
+  Return only after all tasks are fully implemented and tested.
+  `
+)
+```
+
+**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section)
+
+**Option B: CLI Execution (Codex)**
+
+When to use:
+- `executionMethod = "Codex"`
+- `executionMethod = "Auto" AND complexity = "Medium" or "High"`
+
+**Artifact Path Delegation**:
+- Include artifact file paths in CLI prompt for enhanced context
+- Codex can read artifact files for detailed planning information
+- Example: Reference exploration.json for architecture patterns
+
+Command format:
+```bash
+function formatTaskForCodex(task, index) {
+  return `
+${index + 1}. ${task.title} (${task.file})
+   Action: ${task.action}
+   What: ${task.description}
+   How:
+${task.implementation.map((step, i) => `   ${i + 1}. ${step}`).join('\n')}
+   Reference: ${task.reference.pattern} (see ${task.reference.files.join(', ')})
+   Guidance: ${task.reference.examples}
+   Verify:
+${task.acceptance.map((criterion, i) => `   - ${criterion}`).join('\n')}
+`
+}
+
+codex --full-auto exec "
+${originalUserInput ? `## Original User Request\n${originalUserInput}\n\n` : ''}
+
+## Implementation Plan
+
+TASK: ${planObject.summary}
+APPROACH: ${planObject.approach}
+
+### Task Breakdown (${planObject.tasks.length} tasks)
+${planObject.tasks.map((task, i) => formatTaskForCodex(task, i)).join('\n')}
+
+${previousExecutionResults.length > 0 ? `\n### Previous Execution Results\n${previousExecutionResults.map(result => `
+[${result.executionId}] ${result.status}
+Tasks: ${result.tasksSummary}
+Status: ${result.completionSummary}
+Outputs: ${result.keyOutputs || 'See git diff'}
+${result.notes ? `Notes: ${result.notes}` : ''}
+`).join('\n---\n')}
+
+IMPORTANT: Review previous results. Build on completed work. Avoid duplication.
+` : ''}
+
+### Code Context from Exploration
+${explorationContext ? `
+Project Structure: ${explorationContext.project_structure || 'Standard structure'}
+Relevant Files: ${explorationContext.relevant_files?.join(', ') || 'TBD'}
+Current Patterns: ${explorationContext.patterns || 'Follow existing conventions'}
+Integration Points: ${explorationContext.dependencies || 'None specified'}
+Constraints: ${explorationContext.constraints || 'None'}
+` : 'No prior exploration - analyze codebase as needed'}
+
+${clarificationContext ? `\n### User Clarifications\n${Object.entries(clarificationContext).map(([q, a]) => `${q}: ${a}`).join('\n')}` : ''}
+
+${executionContext?.session?.artifacts ? `\n### Planning Artifact Files
+Detailed planning context available in session folder:
+${executionContext.session.artifacts.exploration ? `- Exploration: ${executionContext.session.artifacts.exploration}` : ''}
+- Plan: ${executionContext.session.artifacts.plan}
+- Task: ${executionContext.session.artifacts.task}
+
+Read these files for complete architecture details, code patterns, and integration constraints.
+` : ''}
+
+## Requirements
+MUST complete ALL ${planObject.tasks.length} tasks listed above in this single execution.
+Return only after all tasks are fully implemented and tested.
+
+Complexity: ${planObject.complexity}
+" --skip-git-repo-check -s danger-full-access
+```
+
+**Execution with tracking**:
+```javascript
+// Launch CLI in foreground (NOT background)
+bash_result = Bash(
+  command=cli_command,
+  timeout=600000  // 10 minutes
+)
+
+// Update TodoWrite when execution completes
+```
+
+**Result Collection**: After completion, analyze output and collect result following `executionResult` structure
+
+### Step 4: Progress Tracking
+
+Progress tracked at batch level (not individual task level). Icons: ⚡ (parallel, concurrent), → (sequential, one-by-one)
+
+### Step 5: Code Review (Optional)
+
+**Skip Condition**: Only run if `codeReviewTool ≠ "Skip"`
+
+**Review Focus**: Verify implementation against task.json acceptance criteria
+- Read task.json from session artifacts for acceptance criteria
+- Check each acceptance criterion is fulfilled
+- Validate code quality and identify issues
+- Ensure alignment with planned approach
+
+**Operations**:
+- Agent Review: Current agent performs direct review (read task.json for acceptance criteria)
+- Gemini Review: Execute gemini CLI with review prompt (task.json in CONTEXT)
+- Custom tool: Execute specified CLI tool (qwen, codex, etc.) with task.json reference
+
+**Unified Review Template** (All tools use same standard):
+
+**Review Criteria**:
+- **Acceptance Criteria**: Verify each criterion from task.json `context.acceptance`
+- **Code Quality**: Analyze quality, identify issues, suggest improvements
+- **Plan Alignment**: Validate implementation matches planned approach
+
+**Shared Prompt Template** (used by all CLI tools):
+```
+PURPOSE: Code review for implemented changes against task.json acceptance criteria
+TASK: • Verify task.json acceptance criteria fulfillment • Analyze code quality • Identify issues • Suggest improvements • Validate plan adherence
+MODE: analysis
+CONTEXT: @**/* @{task.json} @{plan.json} [@{exploration.json}] | Memory: Review lite-execute changes against task.json requirements
+EXPECTED: Quality assessment with acceptance criteria verification, issue identification, and recommendations. Explicitly check each acceptance criterion from task.json.
+RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-review-code-quality.txt) | Focus on task.json acceptance criteria and plan adherence | analysis=READ-ONLY
+```
+
+**Tool-Specific Execution** (Apply shared prompt template above):
+
+```bash
+# Method 1: Agent Review (current agent)
+# - Read task.json: ${executionContext.session.artifacts.task}
+# - Apply unified review criteria (see Shared Prompt Template)
+# - Report findings directly
+
+# Method 2: Gemini Review (recommended)
+gemini -p "[Shared Prompt Template with artifacts]"
+# CONTEXT includes: @**/* @${task.json} @${plan.json} [@${exploration.json}]
+
+# Method 3: Qwen Review (alternative)
+qwen -p "[Shared Prompt Template with artifacts]"
+# Same prompt as Gemini, different execution engine
+
+# Method 4: Codex Review (autonomous)
+codex --full-auto exec "[Verify task.json acceptance criteria at ${task.json}]" --skip-git-repo-check -s danger-full-access
+```
+
+**Implementation Note**: Replace `[Shared Prompt Template with artifacts]` placeholder with actual template content, substituting:
+- `@{task.json}` → `@${executionContext.session.artifacts.task}`
+- `@{plan.json}` → `@${executionContext.session.artifacts.plan}`
+- `[@{exploration.json}]` → `@${executionContext.session.artifacts.exploration}` (if exists)
+
+## Best Practices
+
+**Input Modes**: In-memory (lite-plan), prompt (standalone), file (JSON/text)
+**Batch Limits**: Agent 7 tasks, CLI 4 tasks
+**Execution**: Parallel batches use single Claude message with multiple tool calls (no concurrency limit)
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing executionContext | --in-memory without context | Error: "No execution context found. Only available when called by lite-plan." |
+| File not found | File path doesn't exist | Error: "File not found: {path}. Check file path." |
+| Empty file | File exists but no content | Error: "File is empty: {path}. Provide task description." |
+| Invalid Enhanced Task JSON | JSON missing required fields | Warning: "Missing required fields. Treating as plain text." |
+| Malformed JSON | JSON parsing fails | Treat as plain text (expected for non-JSON files) |
+| Execution failure | Agent/Codex crashes | Display error, save partial progress, suggest retry |
+| Codex unavailable | Codex not installed | Show installation instructions, offer Agent execution |
+
+## Data Structures
+
+### executionContext (Input - Mode 1)
+
+Passed from lite-plan via global variable:
+
+```javascript
+{
+  planObject: {
+    summary: string,
+    approach: string,
+    tasks: [...],
+    estimated_time: string,
+    recommended_execution: string,
+    complexity: string
+  },
+  explorationContext: {...} | null,
+  clarificationContext: {...} | null,
+  executionMethod: "Agent" | "Codex" | "Auto",
+  codeReviewTool: "Skip" | "Gemini Review" | "Agent Review" | string,
+  originalUserInput: string,
+
+  // Session artifacts location (saved by lite-plan)
+  session: {
+    id: string,                        // Session identifier: {taskSlug}-{shortTimestamp}
+    folder: string,                    // Session folder path: .workflow/.lite-plan/{session-id}
+    artifacts: {
+      exploration: string | null,      // exploration.json path (if exploration performed)
+      plan: string,                    // plan.json path (always present)
+      task: string                     // task.json path (always exported)
+    }
+  }
+}
+```
+
+**Artifact Usage**:
+- Artifact files contain detailed planning context
+- Pass artifact paths to CLI tools and agents for enhanced context
+- See execution options below for usage examples
+
+### executionResult (Output)
+
+Collected after each execution call completes:
+
+```javascript
+{
+  executionId: string,                 // e.g., "[Agent-1]", "[Codex-1]"
+  status: "completed" | "partial" | "failed",
+  tasksSummary: string,                // Brief description of tasks handled
+  completionSummary: string,           // What was completed
+  keyOutputs: string,                  // Files created/modified, key changes
+  notes: string                        // Important context for next execution
+}
+```
+
+Appended to `previousExecutionResults` array for context continuity in multi-execution scenarios.

.claude/commands/workflow/lite-fix.md

@@ -0,0 +1,760 @@
+---
+name: lite-fix
+description: Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents
+argument-hint: "[--hotfix] \"bug description or issue reference\""
+allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Read(*), Bash(*)
+---
+
+# Workflow Lite-Fix Command (/workflow:lite-fix)
+
+## Overview
+
+Fast-track bug fixing workflow optimized for quick diagnosis, targeted fixes, and streamlined verification. Automatically adjusts process complexity based on impact assessment.
+
+**Core capabilities:**
+- Rapid root cause diagnosis with intelligent code search
+- Automatic severity assessment and adaptive workflow
+- Fix strategy selection (immediate patch vs comprehensive refactor)
+- Risk-aware verification (smoke tests to full suite)
+- Optional hotfix mode for production incidents with branch management
+- Automatic follow-up task generation for hotfixes
+
+## Usage
+
+### Command Syntax
+```bash
+/workflow:lite-fix [FLAGS] <BUG_DESCRIPTION>
+
+# Flags
+--hotfix, -h               Production hotfix mode (creates hotfix branch, auto follow-up)
+
+# Arguments
+<bug-description>          Bug description or issue reference (required)
+```
+
+### Modes
+
+| Mode | Time Budget | Use Case | Workflow Characteristics |
+|------|-------------|----------|--------------------------|
+| **Default** | Auto-adapt (15min-4h) | All standard bugs | Intelligent severity assessment + adaptive process |
+| **Hotfix** (`--hotfix`) | 15-30 min | Production outage | Minimal diagnosis + hotfix branch + auto follow-up |
+
+### Examples
+
+```bash
+# Default mode: Automatically adjusts based on impact
+/workflow:lite-fix "User avatar upload fails with 413 error"
+/workflow:lite-fix "Shopping cart randomly loses items at checkout"
+
+# Hotfix mode: Production incident
+/workflow:lite-fix --hotfix "Payment gateway 5xx errors"
+```
+
+## Execution Process
+
+### Workflow Overview
+
+```
+Bug Input → Diagnosis (Phase 1) → Impact Assessment (Phase 2)
+        ↓
+    Severity Auto-Detection → Fix Planning (Phase 3)
+        ↓
+    Verification Strategy (Phase 4) → User Confirmation (Phase 5) → Execution (Phase 6)
+```
+
+### Phase Summary
+
+| Phase | Default Mode | Hotfix Mode |
+|-------|--------------|-------------|
+| 1. Diagnosis | Adaptive search depth | Minimal (known issue) |
+| 2. Impact Assessment | Full risk scoring | Critical path only |
+| 3. Fix Planning | Strategy options based on complexity | Single surgical fix |
+| 4. Verification | Test level matches risk score | Smoke tests only |
+| 5. User Confirmation | 3 dimensions | 2 dimensions |
+| 6. Execution | Via lite-execute | Via lite-execute + monitoring |
+
+---
+
+## Detailed Phase Execution
+
+### Phase 1: Diagnosis & Root Cause Analysis
+
+**Goal**: Identify root cause and affected code paths
+
+**Session Folder Setup**:
+```javascript
+// Generate session identifiers for artifact storage
+const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // YYYY-MM-DD-HH-mm-ss
+const sessionId = `${bugSlug}-${shortTimestamp}`
+const sessionFolder = `.workflow/.lite-fix/${sessionId}`
+```
+
+**Execution Strategy**:
+
+**Default Mode** - Adaptive search:
+- **High confidence keywords** (e.g., specific error messages): Direct grep search (5min)
+- **Medium confidence**: cli-explore-agent with focused search (10-15min)
+- **Low confidence** (vague symptoms): cli-explore-agent with broad search (20min)
+
+```javascript
+// Confidence-based strategy selection
+if (has_specific_error_message || has_file_path_hint) {
+  // Quick targeted search
+  grep -r '${error_message}' src/ --include='*.ts' -n | head -10
+  git log --oneline --since='1 week ago' -- '*affected*'
+} else {
+  // Deep exploration
+  Task(subagent_type="cli-explore-agent", prompt=`
+    Bug: ${bug_description}
+    Execute diagnostic search:
+    1. Search error patterns and similar issues
+    2. Trace execution path in affected modules
+    3. Check recent changes
+    Return: Root cause hypothesis, affected paths, reproduction steps
+  `)
+}
+```
+
+**Hotfix Mode** - Minimal search:
+```bash
+Read(suspected_file)  # User typically knows the file
+git blame ${suspected_file}
+```
+
+**Output Structure**:
+```javascript
+diagnosisContext = {
+  symptom: string,
+  error_message: string | null,
+  keywords: string[],
+  confidence_level: "high" | "medium" | "low",
+  root_cause: {
+    file: "src/auth/tokenValidator.ts",
+    line_range: "45-52",
+    issue: "Token expiration check uses wrong comparison",
+    introduced_by: "commit abc123"
+  },
+  reproduction_steps: ["Login", "Wait 15min", "Access protected route"],
+  affected_scope: {
+    users: "All authenticated users",
+    features: ["login", "API access"],
+    data_risk: "none"
+  }
+}
+
+// Save diagnosis results for CLI/agent access in lite-execute
+const diagnosisFile = `${sessionFolder}/diagnosis.json`
+Write(diagnosisFile, JSON.stringify(diagnosisContext, null, 2))
+```
+
+**Output**: `diagnosisContext` (in-memory)
+**Artifact**: Saved to `{sessionFolder}/diagnosis.json` for CLI/agent use
+
+**TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
+
+---
+
+### Phase 2: Impact Assessment & Severity Auto-Detection
+
+**Goal**: Quantify blast radius and auto-determine severity
+
+**Risk Score Calculation**:
+```javascript
+risk_score = (user_impact × 0.4) + (system_risk × 0.3) + (business_impact × 0.3)
+
+// Auto-severity mapping
+if (risk_score >= 8.0) severity = "critical"
+else if (risk_score >= 5.0) severity = "high"
+else if (risk_score >= 3.0) severity = "medium"
+else severity = "low"
+
+// Workflow adaptation
+if (severity >= "high") {
+  diagnosis_depth = "focused"
+  test_strategy = "smoke_and_critical"
+  review_optional = true
+} else {
+  diagnosis_depth = "comprehensive"
+  test_strategy = "full_suite"
+  review_optional = false
+}
+```
+
+**Assessment Output**:
+```javascript
+impactContext = {
+  affected_users: {
+    count: "5000 active users (100%)",
+    severity: "high"
+  },
+  system_risk: {
+    availability: "degraded_30%",
+    cascading_failures: "possible_logout_storm"
+  },
+  business_impact: {
+    revenue: "medium",
+    reputation: "high",
+    sla_breach: "yes"
+  },
+  risk_score: 7.1,
+  severity: "high",
+  workflow_adaptation: {
+    test_strategy: "focused_integration",
+    review_required: false,
+    time_budget: "1_hour"
+  }
+}
+
+// Save impact assessment for CLI/agent access
+const impactFile = `${sessionFolder}/impact.json`
+Write(impactFile, JSON.stringify(impactContext, null, 2))
+```
+
+**Output**: `impactContext` (in-memory)
+**Artifact**: Saved to `{sessionFolder}/impact.json` for CLI/agent use
+
+**Hotfix Mode**: Skip detailed assessment, assume critical
+
+**TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
+
+---
+
+### Phase 3: Fix Planning & Strategy Selection
+
+**Goal**: Generate fix options with trade-off analysis
+
+**Strategy Generation**:
+
+**Default Mode** - Complexity-adaptive:
+- **Low risk score (<5.0)**: Generate 2-3 strategy options for user selection
+- **High risk score (≥5.0)**: Generate single best strategy for speed
+
+```javascript
+strategies = generateFixStrategies(root_cause, risk_score)
+
+if (risk_score >= 5.0 || mode === "hotfix") {
+  // Single best strategy
+  return strategies[0]  // Fastest viable fix
+} else {
+  // Multiple options with trade-offs
+  return strategies  // Let user choose
+}
+```
+
+**Example Strategies**:
+```javascript
+// Low risk: Multiple options
+[
+  {
+    strategy: "immediate_patch",
+    description: "Fix comparison operator",
+    estimated_time: "15 minutes",
+    risk: "low",
+    pros: ["Quick fix"],
+    cons: ["Doesn't address underlying issue"]
+  },
+  {
+    strategy: "comprehensive_fix",
+    description: "Refactor token validation logic",
+    estimated_time: "2 hours",
+    risk: "medium",
+    pros: ["Addresses root cause"],
+    cons: ["Longer implementation"]
+  }
+]
+
+// High risk or hotfix: Single option
+{
+  strategy: "surgical_fix",
+  description: "Minimal change to fix comparison",
+  files: ["src/auth/tokenValidator.ts:47"],
+  estimated_time: "5 minutes",
+  risk: "minimal"
+}
+```
+
+**Complexity Assessment**:
+```javascript
+if (complexity === "high" && risk_score < 5.0) {
+  suggestCommand("/workflow:plan --mode bugfix")
+  return  // Escalate to full planning
+}
+
+// Save fix plan for CLI/agent access
+const planFile = `${sessionFolder}/fix-plan.json`
+Write(planFile, JSON.stringify(fixPlan, null, 2))
+```
+
+**Output**: `fixPlan` (in-memory)
+**Artifact**: Saved to `{sessionFolder}/fix-plan.json` for CLI/agent use
+
+**TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress
+
+---
+
+### Phase 4: Verification Strategy
+
+**Goal**: Define testing approach based on severity
+
+**Adaptive Test Strategy**:
+
+| Risk Score | Test Scope | Duration | Automation |
+|------------|------------|----------|------------|
+| **< 3.0** (Low) | Full test suite | 15-20 min | `npm test` |
+| **3.0-5.0** (Medium) | Focused integration | 8-12 min | `npm test -- affected-module.test.ts` |
+| **5.0-8.0** (High) | Smoke + critical | 5-8 min | `npm test -- critical.smoke.test.ts` |
+| **≥ 8.0** (Critical) | Smoke only | 2-5 min | `npm test -- smoke.test.ts` |
+| **Hotfix** | Production smoke | 2-3 min | `npm test -- production.smoke.test.ts` |
+
+**Branch Strategy**:
+
+**Default Mode**:
+```javascript
+{
+  type: "feature_branch",
+  base: "main",
+  name: "fix/token-expiration-edge-case",
+  merge_target: "main"
+}
+```
+
+**Hotfix Mode**:
+```javascript
+{
+  type: "hotfix_branch",
+  base: "production_tag_v2.3.1",  // ⚠️ From production tag
+  name: "hotfix/token-validation-fix",
+  merge_target: ["main", "production"]  // Dual merge
+}
+```
+
+**TodoWrite**: Mark Phase 4 completed, Phase 5 in_progress
+
+---
+
+### Phase 5: User Confirmation & Execution Selection
+
+**Adaptive Confirmation Dimensions**:
+
+**Default Mode** - 3 dimensions (adapted by risk score):
+
+```javascript
+dimensions = [
+  {
+    question: "Confirm fix approach?",
+    options: ["Proceed", "Modify", "Escalate to /workflow:plan"]
+  },
+  {
+    question: "Execution method:",
+    options: ["Agent", "CLI Tool (Codex/Gemini)", "Manual (plan only)"]
+  },
+  {
+    question: "Verification level:",
+    options: adaptedByRiskScore()  // Auto-suggest based on Phase 2
+  }
+]
+
+// If risk_score >= 5.0, auto-skip code review dimension
+// If risk_score < 5.0, add optional code review dimension
+if (risk_score < 5.0) {
+  dimensions.push({
+    question: "Post-fix review:",
+    options: ["Gemini", "Skip"]
+  })
+}
+```
+
+**Hotfix Mode** - 2 dimensions (minimal):
+```javascript
+[
+  {
+    question: "Confirm hotfix deployment:",
+    options: ["Deploy", "Stage First", "Abort"]
+  },
+  {
+    question: "Post-deployment monitoring:",
+    options: ["Real-time (15 min)", "Passive (alerts only)"]
+  }
+]
+```
+
+**TodoWrite**: Mark Phase 5 completed, Phase 6 in_progress
+
+---
+
+### Phase 6: Execution Dispatch & Follow-up
+
+**Export Enhanced Task JSON**:
+
+```javascript
+const taskId = `BUGFIX-${shortTimestamp}`
+const taskFile = `${sessionFolder}/task.json`
+
+const enhancedTaskJson = {
+  id: taskId,
+  title: bug_description,
+  status: "pending",
+
+  meta: {
+    type: "bugfix",
+    created_at: new Date().toISOString(),
+    severity: impactContext.severity,
+    risk_score: impactContext.risk_score,
+    estimated_time: fixPlan.estimated_time,
+    workflow: mode === "hotfix" ? "lite-fix-hotfix" : "lite-fix",
+    session_id: sessionId,
+    session_folder: sessionFolder
+  },
+
+  context: {
+    requirements: [bug_description],
+    diagnosis: diagnosisContext,
+    impact: impactContext,
+    plan: fixPlan,
+    verification_strategy: verificationStrategy,
+    branch_strategy: branchStrategy
+  }
+}
+
+Write(taskFile, JSON.stringify(enhancedTaskJson, null, 2))
+```
+
+**Dispatch to lite-execute**:
+
+```javascript
+executionContext = {
+  mode: "bugfix",
+  severity: impactContext.severity,
+  planObject: fixPlan,
+  diagnosisContext: diagnosisContext,
+  impactContext: impactContext,
+  verificationStrategy: verificationStrategy,
+  branchStrategy: branchStrategy,
+  executionMethod: user_selection.execution_method,
+
+  // Session artifacts location
+  session: {
+    id: sessionId,
+    folder: sessionFolder,
+    artifacts: {
+      diagnosis: `${sessionFolder}/diagnosis.json`,
+      impact: `${sessionFolder}/impact.json`,
+      plan: `${sessionFolder}/fix-plan.json`,
+      task: `${sessionFolder}/task.json`
+    }
+  }
+}
+
+SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")
+```
+
+**Hotfix Auto Follow-up**:
+
+```javascript
+if (mode === "hotfix") {
+  follow_up_tasks = [
+    {
+      id: `FOLLOWUP-${taskId}-comprehensive`,
+      title: "Replace hotfix with comprehensive fix",
+      priority: "high",
+      due_date: "within_3_days",
+      description: "Refactor quick hotfix into proper solution with full test coverage"
+    },
+    {
+      id: `FOLLOWUP-${taskId}-postmortem`,
+      title: "Incident postmortem",
+      priority: "medium",
+      due_date: "within_1_week",
+      sections: ["Timeline", "Root cause", "Prevention measures"]
+    }
+  ]
+
+  Write(`${sessionFolder}/followup.json`, follow_up_tasks)
+
+  console.log(`
+  ⚠️ Hotfix follow-up tasks generated:
+  - Comprehensive fix: ${follow_up_tasks[0].id} (due in 3 days)
+  - Postmortem: ${follow_up_tasks[1].id} (due in 1 week)
+  - Location: ${sessionFolder}/followup.json
+  `)
+}
+}
+```
+
+**TodoWrite**: Mark Phase 6 completed
+
+---
+
+## Data Structures
+
+### diagnosisContext
+```javascript
+{
+  symptom: string,
+  error_message: string | null,
+  keywords: string[],
+  confidence_level: "high" | "medium" | "low",  // Search confidence
+  root_cause: {
+    file: string,
+    line_range: string,
+    issue: string,
+    introduced_by: string
+  },
+  reproduction_steps: string[],
+  affected_scope: {...}
+}
+```
+
+### impactContext
+```javascript
+{
+  affected_users: { count: string, severity: string },
+  system_risk: { availability: string, cascading_failures: string },
+  business_impact: { revenue: string, reputation: string, sla_breach: string },
+  risk_score: number,  // 0-10
+  severity: "low" | "medium" | "high" | "critical",
+  workflow_adaptation: {
+    diagnosis_depth: string,
+    test_strategy: string,
+    review_optional: boolean,
+    time_budget: string
+  }
+}
+```
+
+### fixPlan
+```javascript
+{
+  strategy: string,
+  summary: string,
+  tasks: [{
+    title: string,
+    file: string,
+    action: "Update" | "Create" | "Delete",
+    implementation: string[],
+    verification: string[]
+  }],
+  estimated_time: string,
+  recommended_execution: "Agent" | "CLI" | "Manual"
+}
+```
+
+### executionContext
+
+Context passed to lite-execute via --in-memory (Phase 6):
+
+```javascript
+{
+  mode: "bugfix",
+  severity: "high" | "medium" | "low" | "critical",
+
+  // Core data objects
+  planObject: {...},           // Complete fixPlan (see above)
+  diagnosisContext: {...},     // Complete diagnosisContext (see above)
+  impactContext: {...},        // Complete impactContext (see above)
+
+  // Verification and branch strategies
+  verificationStrategy: {...},
+  branchStrategy: {...},
+  executionMethod: "Agent" | "CLI" | "Manual",
+
+  // Session artifacts location (for lite-execute to access saved files)
+  session: {
+    id: string,                // Session identifier: {bugSlug}-{shortTimestamp}
+    folder: string,            // Session folder path: .workflow/.lite-fix/{session-id}
+    artifacts: {
+      diagnosis: string,       // diagnosis.json path
+      impact: string,          // impact.json path
+      plan: string,            // fix-plan.json path
+      task: string             // task.json path
+    }
+  }
+}
+```
+
+### Enhanced Task JSON Export
+
+Task JSON structure exported in Phase 6:
+
+```json
+{
+  "id": "BUGFIX-{timestamp}",
+  "title": "Original bug description",
+  "status": "pending",
+
+  "meta": {
+    "type": "bugfix",
+    "created_at": "ISO timestamp",
+    "severity": "low|medium|high|critical",
+    "risk_score": 7.1,
+    "estimated_time": "X minutes",
+    "workflow": "lite-fix|lite-fix-hotfix",
+    "session_id": "{bugSlug}-{shortTimestamp}",
+    "session_folder": ".workflow/.lite-fix/{session-id}"
+  },
+
+  "context": {
+    "requirements": ["Original bug description"],
+    "diagnosis": {/* diagnosisContext */},
+    "impact": {/* impactContext */},
+    "plan": {/* fixPlan */},
+    "verification_strategy": {/* test strategy */},
+    "branch_strategy": {/* branch strategy */}
+  }
+}
+```
+
+**Schema Notes**:
+- Aligns with Enhanced Task JSON Schema (6-field structure)
+- `context_package_path` omitted (not used by lite-fix)
+- `flow_control` omitted (handled by lite-execute)
+
+---
+
+## Best Practices
+
+### When to Use Default Mode
+
+**Use for all standard bugs:**
+- Automatically adapts to severity (no manual mode selection needed)
+- Risk score determines workflow complexity
+- Handles 90% of bug fixing scenarios
+
+**Typical scenarios:**
+- UI bugs, logic errors, edge cases
+- Performance issues (non-critical)
+- Integration failures
+- Data validation bugs
+
+### When to Use Hotfix Mode
+
+**Only use for production incidents:**
+- Production is down or critically degraded
+- Revenue/reputation at immediate risk
+- SLA breach occurring
+- Issue is well-understood (minimal diagnosis needed)
+
+**Hotfix characteristics:**
+- Creates hotfix branch from production tag
+- Minimal diagnosis (assumes known issue)
+- Smoke tests only
+- Auto-generates follow-up tasks
+- Requires incident tracking
+
+### Branching Strategy
+
+**Default Mode (feature branch)**:
+```bash
+# Standard feature branch workflow
+git checkout -b fix/issue-description main
+# ... implement fix
+git checkout main && git merge fix/issue-description
+```
+
+**Hotfix Mode (dual merge)**:
+```bash
+# ✅ Correct: Branch from production tag
+git checkout -b hotfix/fix-name v2.3.1
+
+# Merge to both targets
+git checkout main && git merge hotfix/fix-name
+git checkout production && git merge hotfix/fix-name
+git tag v2.3.2
+
+# ❌ Wrong: Branch from main
+git checkout -b hotfix/fix-name main  # Contains unreleased code!
+```
+
+---
+
+## Error Handling
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Root cause unclear | Vague symptoms | Extend diagnosis time or use /cli:mode:bug-diagnosis |
+| Multiple potential causes | Complex interaction | Use /cli:discuss-plan for analysis |
+| Fix too complex | High-risk refactor | Escalate to /workflow:plan --mode bugfix |
+| High risk score but unsure | Uncertain severity | Default mode will adapt, proceed normally |
+
+---
+
+## Session Folder Structure
+
+Each lite-fix execution creates a dedicated session folder to organize all artifacts:
+
+```
+.workflow/.lite-fix/{bug-slug}-{short-timestamp}/
+├── diagnosis.json    # Phase 1: Root cause analysis
+├── impact.json       # Phase 2: Impact assessment
+├── fix-plan.json     # Phase 3: Fix strategy
+├── task.json         # Phase 6: Enhanced Task JSON
+└── followup.json     # Hotfix mode only: Follow-up tasks
+```
+
+**Folder Naming Convention**:
+- `{bug-slug}`: First 40 characters of bug description, lowercased, non-alphanumeric replaced with `-`
+- `{short-timestamp}`: YYYY-MM-DD-HH-mm-ss format
+- Example: `.workflow/.lite-fix/user-avatar-upload-fails-413-2025-01-15-14-30-45/`
+
+**File Contents**:
+- `diagnosis.json`: Complete diagnosisContext object (Phase 1)
+- `impact.json`: Complete impactContext object (Phase 2)
+- `fix-plan.json`: Complete fixPlan object (Phase 3)
+- `task.json`: Enhanced Task JSON with all context (Phase 6)
+- `followup.json`: Follow-up tasks (hotfix mode only)
+
+**Access Patterns**:
+- **lite-fix**: Creates folder and writes all artifacts during execution, passes paths via `executionContext.session.artifacts`
+- **lite-execute**: Reads artifact paths from `executionContext.session.artifacts`
+- **User**: Can inspect artifacts for debugging or reference
+- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution
+
+
+
+**Legacy Cache** (deprecated, use session folder instead):
+```
+.workflow/.lite-fix-cache/
+└── diagnosis-cache/
+    └── ${bug_hash}.json
+```
+
+
+## Quality Gates
+
+**Before execution** (auto-checked):
+- [ ] Root cause identified (>70% confidence for default, >90% for hotfix)
+- [ ] Impact scope defined
+- [ ] Fix strategy reviewed
+- [ ] Verification plan matches risk level
+
+**Hotfix-specific**:
+- [ ] Production tag identified
+- [ ] Rollback plan documented
+- [ ] Follow-up tasks generated
+- [ ] Monitoring configured
+
+---
+
+## When to Use lite-fix
+
+✅ **Perfect for:**
+- Any bug with clear symptoms
+- Localized fixes (1-5 files)
+- Known technology stack
+- Time-sensitive but not catastrophic (default mode adapts)
+- Production incidents (use --hotfix)
+
+❌ **Not suitable for:**
+- Root cause completely unclear → use `/cli:mode:bug-diagnosis` first
+- Requires architectural changes → use `/workflow:plan`
+- Complex legacy code without tests → use `/workflow:plan --legacy-refactor`
+- Performance deep-dive → use `/workflow:plan --performance-optimization`
+- Data migration → use `/workflow:plan --data-migration`
+
+---
+
+**Last Updated**: 2025-11-20
+**Version**: 2.0.0
+**Status**: Design Document (Simplified)

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

@@ -0,0 +1,359 @@
+---
+name: lite-plan
+description: Lightweight interactive planning workflow with in-memory planning, code exploration, and execution dispatch to lite-execute after user confirmation
+argument-hint: "[-e|--explore] \"task description\"|file.md"
+allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)
+---
+
+# Workflow Lite-Plan Command (/workflow:lite-plan)
+
+## Overview
+
+Intelligent lightweight planning command with dynamic workflow adaptation based on task complexity. Focuses on planning phases (exploration, clarification, planning, confirmation) and delegates execution to `/workflow:lite-execute`.
+
+**Core capabilities:**
+- Intelligent task analysis with automatic exploration detection
+- Dynamic code exploration (cli-explore-agent) when codebase understanding needed
+- Interactive clarification after exploration to gather missing information
+- Adaptive planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity
+- Two-step confirmation: plan display → multi-dimensional input collection
+- Execution dispatch with complete context handoff to lite-execute
+
+## Usage
+
+```bash
+/workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
+
+# Flags
+-e, --explore              Force code exploration phase (overrides auto-detection)
+
+# Arguments
+<task-description>         Task description or path to .md file (required)
+```
+
+## Execution Process
+
+```
+User Input → Task Analysis & Exploration Decision (Phase 1)
+          ↓
+     Clarification (Phase 2, optional)
+          ↓
+     Complexity Assessment & Planning (Phase 3)
+          ↓
+     Task Confirmation & Execution Selection (Phase 4)
+          ↓
+     Dispatch to Execution (Phase 5)
+```
+
+## Implementation
+
+### Phase 1: Task Analysis & Exploration Decision
+
+**Session Setup**:
+```javascript
+const taskSlug = task_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
+const shortTimestamp = timestamp.substring(0, 19).replace('T', '-')
+const sessionId = `${taskSlug}-${shortTimestamp}`
+const sessionFolder = `.workflow/.lite-plan/${sessionId}`
+
+bash(`mkdir -p ${sessionFolder}`)
+```
+
+**Decision Logic**:
+```javascript
+needsExploration = (
+  flags.includes('--explore') || flags.includes('-e') ||
+  task.mentions_specific_files ||
+  task.requires_codebase_context ||
+  task.needs_architecture_understanding ||
+  task.modifies_existing_code
+)
+```
+
+**If exploration needed** - Invoke cli-explore-agent:
+
+```javascript
+Task(
+  subagent_type="cli-explore-agent",
+  description="Analyze codebase for task context",
+  prompt=`
+Analyze codebase for task context and generate exploration.json.
+
+## Output Schema Reference
+~/.claude/workflows/cli-templates/schemas/explore-json-schema.json
+
+## Task Description
+${task_description}
+
+## Requirements
+Generate exploration.json with:
+- project_structure: Architecture and module organization
+- relevant_files: File paths to be affected
+- patterns: Code patterns, conventions, styles
+- dependencies: External/internal module dependencies
+- integration_points: Task connections with existing code
+- constraints: Technical limitations/requirements
+- clarification_needs: Ambiguities requiring user input
+- _metadata: timestamp, task_description, source
+
+## Execution
+1. Structural scan: get_modules_by_depth.sh, find, rg
+2. Semantic analysis: Gemini for patterns/architecture
+3. Write JSON: Write('${sessionFolder}/exploration.json', jsonContent)
+4. Return brief completion summary
+
+Time Limit: 60 seconds
+`
+)
+```
+
+**Output**: `${sessionFolder}/exploration.json` (if exploration performed)
+
+---
+
+### Phase 2: Clarification (Optional)
+
+**Skip if**: No exploration or `clarification_needs` is empty
+
+**If clarification needed**:
+```javascript
+const exploration = JSON.parse(Read(`${sessionFolder}/exploration.json`))
+
+if (exploration.clarification_needs?.length > 0) {
+  AskUserQuestion({
+    questions: exploration.clarification_needs.map(need => ({
+      question: `${need.context}\n\n${need.question}`,
+      header: "Clarification",
+      multiSelect: false,
+      options: need.options.map(opt => ({
+        label: opt,
+        description: `Use ${opt} approach`
+      }))
+    }))
+  })
+}
+```
+
+**Output**: `clarificationContext` (in-memory)
+
+---
+
+### Phase 3: Complexity Assessment & Planning
+
+**Complexity Assessment**:
+```javascript
+complexityScore = {
+  file_count: exploration?.relevant_files?.length || 0,
+  integration_points: exploration?.dependencies?.length || 0,
+  architecture_changes: exploration?.constraints?.includes('architecture'),
+  task_scope: estimated_steps > 5
+}
+
+// Low: score < 3, Medium: 3-5, High: > 5
+```
+
+**Low Complexity** - Direct planning by Claude:
+- Generate plan directly, write to `${sessionFolder}/plan.json`
+- No agent invocation
+
+**Medium/High Complexity** - Invoke cli-lite-planning-agent:
+
+```javascript
+Task(
+  subagent_type="cli-lite-planning-agent",
+  description="Generate detailed implementation plan",
+  prompt=`
+Generate implementation plan and write plan.json.
+
+## Output Schema Reference
+~/.claude/workflows/cli-templates/schemas/plan-json-schema.json
+
+## Task Description
+${task_description}
+
+## Exploration Context
+${sessionFolder}/exploration.json (if exists)
+
+## User Clarifications
+${JSON.stringify(clarificationContext) || "None"}
+
+## Complexity Level
+${complexity}
+
+## Requirements
+Generate plan.json with:
+- summary: 2-3 sentence overview
+- approach: High-level implementation strategy
+- tasks: 3-10 structured tasks with:
+  - title, file, action, description
+  - implementation (3-7 steps)
+  - reference (pattern, files, examples)
+  - acceptance (2-4 criteria)
+- estimated_time, recommended_execution, complexity
+- _metadata: timestamp, source, planning_mode
+
+## Execution
+1. Execute CLI planning using Gemini (Qwen fallback)
+2. Parse output and structure plan
+3. Write JSON: Write('${sessionFolder}/plan.json', jsonContent)
+4. Return brief completion summary
+`
+)
+```
+
+**Output**: `${sessionFolder}/plan.json`
+
+---
+
+### Phase 4: Task Confirmation & Execution Selection
+
+**Step 4.1: Display Plan**
+```javascript
+const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
+
+console.log(`
+## Implementation Plan
+
+**Summary**: ${plan.summary}
+**Approach**: ${plan.approach}
+
+**Tasks** (${plan.tasks.length}):
+${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')}
+
+**Complexity**: ${plan.complexity}
+**Estimated Time**: ${plan.estimated_time}
+**Recommended**: ${plan.recommended_execution}
+`)
+```
+
+**Step 4.2: Collect Confirmation**
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`,
+      header: "Confirm",
+      multiSelect: true,
+      options: [
+        { label: "Allow", description: "Proceed as-is" },
+        { label: "Modify", description: "Adjust before execution" },
+        { label: "Cancel", description: "Abort workflow" }
+      ]
+    },
+    {
+      question: "Execution method:",
+      header: "Execution",
+      multiSelect: false,
+      options: [
+        { label: "Agent", description: "@code-developer agent" },
+        { label: "Codex", description: "codex CLI tool" },
+        { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` }
+      ]
+    },
+    {
+      question: "Code review after execution?",
+      header: "Review",
+      multiSelect: false,
+      options: [
+        { label: "Gemini Review", description: "Gemini CLI" },
+        { label: "Agent Review", description: "@code-reviewer" },
+        { label: "Skip", description: "No review" }
+      ]
+    }
+  ]
+})
+```
+
+---
+
+### Phase 5: Dispatch to Execution
+
+**Step 5.1: Generate task.json** (by command, not agent)
+
+```javascript
+const taskId = `LP-${shortTimestamp}`
+const exploration = file_exists(`${sessionFolder}/exploration.json`)
+  ? JSON.parse(Read(`${sessionFolder}/exploration.json`))
+  : null
+const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
+
+const taskJson = {
+  id: taskId,
+  title: task_description,
+  status: "pending",
+
+  meta: {
+    type: "planning",
+    created_at: new Date().toISOString(),
+    complexity: plan.complexity,
+    estimated_time: plan.estimated_time,
+    recommended_execution: plan.recommended_execution,
+    workflow: "lite-plan",
+    session_id: sessionId,
+    session_folder: sessionFolder
+  },
+
+  context: {
+    requirements: [task_description],
+    plan: {
+      summary: plan.summary,
+      approach: plan.approach,
+      tasks: plan.tasks
+    },
+    exploration: exploration,
+    clarifications: clarificationContext || null,
+    focus_paths: exploration?.relevant_files || [],
+    acceptance: plan.tasks.flatMap(t => t.acceptance)
+  }
+}
+
+Write(`${sessionFolder}/task.json`, JSON.stringify(taskJson, null, 2))
+```
+
+**Step 5.2: Store executionContext**
+
+```javascript
+executionContext = {
+  planObject: plan,
+  explorationContext: exploration,
+  clarificationContext: clarificationContext || null,
+  executionMethod: userSelection.execution_method,
+  codeReviewTool: userSelection.code_review_tool,
+  originalUserInput: task_description,
+  session: {
+    id: sessionId,
+    folder: sessionFolder,
+    artifacts: {
+      exploration: exploration ? `${sessionFolder}/exploration.json` : null,
+      plan: `${sessionFolder}/plan.json`,
+      task: `${sessionFolder}/task.json`
+    }
+  }
+}
+```
+
+**Step 5.3: Dispatch**
+
+```javascript
+SlashCommand(command="/workflow:lite-execute --in-memory")
+```
+
+## Session Folder Structure
+
+```
+.workflow/.lite-plan/{task-slug}-{timestamp}/
+├── exploration.json    # If exploration performed (by cli-explore-agent)
+├── plan.json           # Always created (by agent or direct planning)
+└── task.json           # Always created (by command)
+```
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Exploration agent failure | Skip exploration, continue with task description only |
+| Planning agent failure | Fallback to direct planning by Claude |
+| Clarification timeout | Use exploration findings as-is |
+| Confirmation timeout | Save context, display resume instructions |
+| Modify loop > 3 times | Suggest breaking task or using /workflow:plan |

.claude/commands/workflow/plan.md

@@ -1,7 +1,7 @@
 ---
 name: plan
-description: Orchestrate 5-phase planning workflow with quality gate, executing commands and passing context between phases
-argument-hint: "[--agent] [--cli-execute] \"text description\"|file.md"
+description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
+argument-hint: "[--cli-execute] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -20,18 +20,21 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 2. **Phase 1 executes** → Session discovery → Auto-continues
 3. **Phase 2 executes** → Context gathering → Auto-continues
 4. **Phase 3 executes** (optional, if conflict_risk ≥ medium) → Conflict resolution → Auto-continues
-5. **Phase 4 executes** (task-generate-agent if --agent) → Task generation → Reports final summary
+5. **Phase 4 executes** → Task generation (task-generate-agent) → Reports final summary
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
 
 **Auto-Continue Mechanism**:
-- TodoList tracks current phase status
-- After each phase completion, automatically executes next pending phase
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
 - All phases run autonomously without user interaction (clarification handled in brainstorm phase)
 - Progress updates shown at each phase for visibility
-
-**Execution Modes**:
-- **Manual Mode** (default): Use `/workflow:tools:task-generate`
-- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-agent`
-- **CLI Execute Mode** (`--cli-execute`): Generate tasks with Codex execution commands
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -39,8 +42,9 @@ This workflow runs **fully autonomously** once triggered. Phase 3 (conflict reso
 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/agent output for next phase
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite after every phase completion
-6. **Agent Delegation**: Phase 3 uses cli-execution-agent for autonomous intelligent analysis
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+7. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 5-Phase Execution
 
@@ -66,7 +70,9 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **Validation**:
 - Session ID successfully extracted
-- Session directory `.workflow/[sessionId]/` exists
+- Session directory `.workflow/active/[sessionId]/` exists
+
+**Note**: Session directory contains `workflow-session.json` (metadata). Do NOT look for `manifest.json` here - it only exists in `.workflow/archives/` for archived sessions.
 
 **TodoWrite**: Mark phase 1 completed, phase 2 in_progress
 
@@ -83,15 +89,41 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **Parse Output**:
 - Extract: context-package.json path (store as `contextPath`)
-- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
+- Typical pattern: `.workflow/active/[sessionId]/.process/context-package.json`
 
 **Validation**:
 - Context package path extracted
 - File exists and is valid JSON
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+<!-- TodoWrite: When context-gather invoked, INSERT 3 context-gather tasks, mark first as in_progress -->
 
-**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Phase 2.1: Analyze codebase structure (context-gather)", "status": "in_progress", "activeForm": "Analyzing codebase structure"},
+  {"content": "Phase 2.2: Identify integration points (context-gather)", "status": "pending", "activeForm": "Identifying integration points"},
+  {"content": "Phase 2.3: Generate context package (context-gather)", "status": "pending", "activeForm": "Generating context package"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** context-gather's 3 tasks. Orchestrator **executes** these tasks sequentially.
+
+<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**After Phase 2**: Return to user showing Phase 2 results, then auto-continue to Phase 3/4 (depending on conflict_risk)
 
 ---
 
@@ -111,13 +143,41 @@ CONTEXT: Existing user database schema, REST API endpoints
 - Verify: CONFLICT_RESOLUTION.md file path (if executed)
 
 **Validation**:
-- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
+- File `.workflow/active/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
 
 **Skip Behavior**:
 - If conflict_risk is "none" or "low", skip directly to Phase 3.5
 - Display: "No significant conflicts detected, proceeding to clarification"
 
-**TodoWrite**: Mark phase 3 completed (if executed) or skipped, phase 3.5 in_progress
+<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "Phase 3.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "Phase 3.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks sequentially.
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
+  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 **After Phase 3**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 3.5
 
@@ -153,88 +213,103 @@ CONTEXT: Existing user database schema, REST API endpoints
 
 **Relationship with Brainstorm Phase**:
 - If brainstorm role analyses exist ([role]/analysis.md files), Phase 3 analysis incorporates them as input
-- **⚠️ User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations
+- **User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations
 - **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights
 - **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence
 - Task generation translates high-level role analyses into concrete, actionable work items
 - **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md
 
-**Command Selection**:
-- Manual: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
-- Agent: `SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")`
-- CLI Execute: Add `--cli-execute` flag to either command
-
-**Flag Combination**:
-- `--cli-execute` alone: Manual task generation with CLI execution
-- `--agent --cli-execute`: Agent task generation with CLI execution
-
-**Command Examples**:
+**Command**:
 ```bash
-# Manual with CLI execution
-/workflow:tools:task-generate --session WFS-auth --cli-execute
+# Default (agent mode)
+SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")
 
-# Agent with CLI execution
-/workflow:tools:task-generate-agent --session WFS-auth --cli-execute
+# With CLI execution
+SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId] --cli-execute")
 ```
 
+**Flag**:
+- `--cli-execute`: Generate tasks with Codex execution commands
+
 **Input**: `sessionId` from Phase 1
 
 **Validation**:
-- `.workflow/[sessionId]/IMPL_PLAN.md` exists
-- `.workflow/[sessionId]/.task/IMPL-*.json` exists (at least one)
-- `.workflow/[sessionId]/TODO_LIST.md` exists
+- `.workflow/active/[sessionId]/IMPL_PLAN.md` exists
+- `.workflow/active/[sessionId]/.task/IMPL-*.json` exists (at least one)
+- `.workflow/active/[sessionId]/TODO_LIST.md` exists
 
-**TodoWrite**: Mark phase 4 completed
+<!-- TodoWrite: When task-generate-agent invoked, ATTACH 1 agent task -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - agent task attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task-generate-agent", "status": "in_progress", "activeForm": "Executing task-generate-agent"}
+]
+```
+
+**Note**: Single agent task attached. Agent autonomously completes discovery, planning, and output generation internally.
+
+<!-- TodoWrite: After agent completes, mark task as completed -->
+
+**TodoWrite Update (Phase 4 completed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute task-generate-agent", "status": "completed", "activeForm": "Executing task-generate-agent"}
+]
+```
+
+**Note**: Agent task completed. No collapse needed (single task).
 
 **Return to User**:
 ```
 Planning complete for session: [sessionId]
 Tasks generated: [count]
-Plan: .workflow/[sessionId]/IMPL_PLAN.md
+Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
 
-✅ Recommended Next Steps:
+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
+Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (before Phase 1)
-// Note: Phase 3 todo only added dynamically after Phase 2 if conflict_risk ≥ medium
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  // Phase 3 todo added dynamically after Phase 2 if conflict_risk ≥ medium
-  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for real-time visibility into workflow execution.
 
-// After Phase 2 (if conflict_risk ≥ medium, insert Phase 3 todo)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Resolve conflicts and apply fixes", "status": "in_progress", "activeForm": "Resolving conflicts"},
-  {"content": "Execute task generation", "status": "pending", "activeForm": "Executing task generation"}
-]})
+### Key Principles
 
-// After Phase 2 (if conflict_risk is none/low, skip Phase 3, go directly to Phase 4)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
-]})
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - **Phase 2, 3**: Multiple sub-tasks attached (e.g., Phase 2.1, 2.2, 2.3)
+   - **Phase 4**: Single agent task attached (e.g., "Execute task-generate-agent")
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-// After Phase 3 (if executed), continue to Phase 4
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Resolve conflicts and apply fixes", "status": "completed", "activeForm": "Resolving conflicts"},
-  {"content": "Execute task generation", "status": "in_progress", "activeForm": "Executing task generation"}
-]})
-```
+2. **Task Collapse** (after sub-tasks complete):
+   - **Applies to Phase 2, 3**: Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Execute context gathering: completed"
+   - **Phase 4**: No collapse needed (single task, just mark completed)
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After completion, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary for Phase 2/3, or marked completed for Phase 4) → Next phase begins → Repeat until all phases complete.
+
+
+
+**Note**: See individual Phase descriptions for detailed TodoWrite Update examples:
+- **Phase 2, 3**: Multiple sub-tasks with attach/collapse pattern
+- **Phase 4**: Single agent task (no collapse needed)
 
 ## Input Processing
 
@@ -296,7 +371,7 @@ Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
     ↓ Output: Modified brainstorm artifacts (NO report file)
     ↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
     ↓
-Phase 4: task-generate[--agent] --session sessionId
+Phase 4: task-generate-agent --session sessionId [--cli-execute]
     ↓ Input: sessionId + resolved brainstorm artifacts + session memory
     ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
     ↓
@@ -309,11 +384,56 @@ Return summary to user
 - Brainstorming artifacts (potentially modified by Phase 3)
 - Session-specific configuration
 
-**Structured Description Benefits**:
-- **Clarity**: Clear separation of goal, scope, and context
-- **Consistency**: Same format across all phases
-- **Traceability**: Easy to track what was requested
-- **Precision**: Better context gathering and analysis
+
+## Execution Flow Diagram
+
+```
+User triggers: /workflow:plan "Build authentication system"
+  ↓
+[TodoWrite Init] 3 orchestrator-level tasks
+  ↓
+Phase 1: Session Discovery
+  → sessionId extracted
+  ↓
+Phase 2: Context Gathering (SlashCommand invoked)
+  → ATTACH 3 tasks: ← ATTACHED
+    - Phase 2.1: Analyze codebase structure
+    - Phase 2.2: Identify integration points
+    - Phase 2.3: Generate context package
+  → Execute Phase 2.1-2.3
+  → COLLAPSE tasks ← COLLAPSED
+  → contextPath + conflict_risk extracted
+  ↓
+Conditional Branch: Check conflict_risk
+  ├─ IF conflict_risk ≥ medium:
+  │   Phase 3: Conflict Resolution (SlashCommand invoked)
+  │     → ATTACH 3 tasks: ← ATTACHED
+  │       - Phase 3.1: Detect conflicts with CLI analysis
+  │       - Phase 3.2: Present conflicts to user
+  │       - Phase 3.3: Apply resolution strategies
+  │     → Execute Phase 3.1-3.3
+  │     → COLLAPSE tasks ← COLLAPSED
+  │
+  └─ ELSE: Skip Phase 3, proceed to Phase 4
+  ↓
+Phase 4: Task Generation (SlashCommand invoked)
+  → ATTACH 1 agent task: ← ATTACHED
+    - Execute task-generate-agent
+  → Agent autonomously completes internally:
+    (discovery → planning → output)
+  → Outputs: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
+  ↓
+Return summary to user
+```
+
+**Key Points**:
+- **← ATTACHED**: Tasks attached to TodoWrite when SlashCommand invoked
+  - Phase 2, 3: Multiple sub-tasks
+  - Phase 4: Single agent task
+- **← COLLAPSED**: Sub-tasks collapsed to summary after completion (Phase 2, 3 only)
+- **Phase 4**: Single agent task, no collapse (just mark completed)
+- **Conditional Branch**: Phase 3 only executes if conflict_risk ≥ medium
+- **Continuous Flow**: No user intervention between phases
 
 ## Error Handling
 
@@ -323,24 +443,23 @@ Return summary to user
 
 ## Coordinator Checklist
 
-✅ **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
-✅ Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
-✅ Execute Phase 1 immediately with structured description
-✅ Parse session ID from Phase 1 output, store in memory
-✅ Pass session ID and structured description to Phase 2 command
-✅ Parse context path from Phase 2 output, store in memory
-✅ **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
-✅ **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
-✅ Wait for Phase 3 completion (if executed), verify CONFLICT_RESOLUTION.md created
-✅ **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
-✅ **Build Phase 4 command** based on flags:
-  - Base command: `/workflow:tools:task-generate` (or `-agent` if `--agent` flag)
-  - Add `--session [sessionId]`
+- **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT)
+- Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2)
+- Execute Phase 1 immediately with structured description
+- Parse session ID from Phase 1 output, store in memory
+- Pass session ID and structured description to Phase 2 command
+- Parse context path from Phase 2 output, store in memory
+- **Extract conflict_risk from context-package.json**: Determine Phase 3 execution
+- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
+- Wait for Phase 3 to finish executing (if executed), verify CONFLICT_RESOLUTION.md created
+- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
+- **Build Phase 4 command**:
+  - Base command: `/workflow:tools:task-generate-agent --session [sessionId]`
   - Add `--cli-execute` if flag present
-✅ Pass session ID to Phase 4 command
-✅ Verify all Phase 4 outputs
-✅ Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
-✅ After each phase, automatically continue to next phase based on TodoList status
+- Pass session ID to Phase 4 command
+- Verify all Phase 4 outputs
+- Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
+- After each phase, automatically continue to next phase based on TodoList status
 
 ## Structure Template Reference
 
@@ -368,3 +487,21 @@ CONSTRAINTS: [Limitations or boundaries]
 # Phase 2
 /workflow:tools:context-gather --session WFS-123 "GOAL: Build authentication\nSCOPE: JWT, login, registration\nCONTEXT: REST API"
 ```
+
+## Related Commands
+
+**Prerequisite Commands**:
+- `/workflow:brainstorm:artifacts` - Optional: Generate role-based analyses before planning (if complex requirements need multiple perspectives)
+- `/workflow:brainstorm:synthesis` - Optional: Refine brainstorm analyses with clarifications
+
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create or discover workflow session
+- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
+- `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
+- `/compact` - Phase 3: Memory optimization (if context approaching limits)
+- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach
+
+**Follow-up Commands**:
+- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution
+- `/workflow:status` - Review task breakdown and current progress
+- `/workflow:execute` - Begin implementation of generated tasks

.claude/commands/workflow/replan.md

@@ -0,0 +1,470 @@
+---
+name: replan
+description: Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning
+argument-hint: "[--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
+allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
+---
+
+# Workflow Replan Command
+
+## Overview
+Intelligently replans workflow sessions or individual tasks with interactive boundary clarification and comprehensive artifact updates.
+
+**Core Capabilities**:
+- **Session Replan**: Updates multiple artifacts (IMPL_PLAN.md, TODO_LIST.md, task JSONs)
+- **Task Replan**: Focused updates within session context
+- **Interactive Clarification**: Guided questioning to define modification boundaries
+- **Impact Analysis**: Automatic detection of affected files and dependencies
+- **Backup Management**: Preserves previous versions with restore capability
+
+## Operation Modes
+
+### Session Replan Mode
+
+```bash
+# Auto-detect active session
+/workflow:replan "添加双因素认证支持"
+
+# Explicit session
+/workflow:replan --session WFS-oauth "添加双因素认证支持"
+
+# File-based input
+/workflow:replan --session WFS-oauth requirements-update.md
+
+# Interactive mode
+/workflow:replan --interactive
+```
+
+### Task Replan Mode
+
+```bash
+# Direct task update
+/workflow:replan IMPL-1 "修改为使用 OAuth2.0 标准"
+
+# Task with explicit session
+/workflow:replan --session WFS-oauth IMPL-2 "增加单元测试覆盖率到 90%"
+
+# Interactive mode
+/workflow:replan IMPL-1 --interactive
+```
+
+## Execution Lifecycle
+
+### Phase 1: Mode Detection & Session Discovery
+
+**Process**:
+1. **Detect Operation Mode**:
+   - Check if task ID provided (IMPL-N or IMPL-N.M format) → Task mode
+   - Otherwise → Session mode
+
+2. **Discover/Validate Session**:
+   - Use `--session` flag if provided
+   - Otherwise auto-detect from `.workflow/active/`
+   - Validate session exists
+
+3. **Load Session Context**:
+   - Read `workflow-session.json`
+   - List existing tasks
+   - Read `IMPL_PLAN.md` and `TODO_LIST.md`
+
+**Output**: Session validated, context loaded, mode determined
+
+---
+
+### Phase 2: Interactive Requirement Clarification
+
+**Purpose**: Define modification scope through guided questioning
+
+#### Session Mode Questions
+
+**Q1: Modification Scope**
+```javascript
+Options:
+- 仅更新任务细节 (tasks_only)
+- 修改规划方案 (plan_update)
+- 重构任务结构 (task_restructure)
+- 全面重规划 (comprehensive)
+```
+
+**Q2: Affected Modules** (if scope >= plan_update)
+```javascript
+Options: Dynamically generated from existing tasks' focus_paths
+- 认证模块 (src/auth)
+- 用户管理 (src/user)
+- 全部模块
+```
+
+**Q3: Task Changes** (if scope >= task_restructure)
+```javascript
+Options:
+- 添加新任务
+- 删除现有任务
+- 合并任务
+- 拆分任务
+- 仅更新内容
+```
+
+**Q4: Dependency Changes**
+```javascript
+Options:
+- 是,需要重新梳理依赖
+- 否,保持现有依赖
+```
+
+#### Task Mode Questions
+
+**Q1: Update Type**
+```javascript
+Options:
+- 需求和验收标准 (requirements & acceptance)
+- 实现方案 (implementation_approach)
+- 文件范围 (focus_paths)
+- 依赖关系 (depends_on)
+- 全部更新
+```
+
+**Q2: Ripple Effect**
+```javascript
+Options:
+- 是,需要同步更新依赖任务
+- 否,仅影响当前任务
+- 不确定,请帮我分析
+```
+
+**Output**: User selections stored, modification boundaries defined
+
+---
+
+### Phase 3: Impact Analysis & Planning
+
+**Step 3.1: Analyze Required Changes**
+
+Determine affected files based on clarification:
+
+```typescript
+interface ImpactAnalysis {
+  affected_files: {
+    impl_plan: boolean;
+    todo_list: boolean;
+    session_meta: boolean;
+    tasks: string[];
+  };
+
+  operations: {
+    type: 'create' | 'update' | 'delete' | 'merge' | 'split';
+    target: string;
+    reason: string;
+  }[];
+
+  backup_strategy: {
+    timestamp: string;
+    files: string[];
+  };
+}
+```
+
+**Step 3.2: Generate Modification Plan**
+
+```markdown
+## 修改计划
+
+### 影响范围
+- [ ] IMPL_PLAN.md: 更新技术方案第 3 节
+- [ ] TODO_LIST.md: 添加 2 个新任务,删除 1 个废弃任务
+- [ ] IMPL-001.json: 更新实现方案
+- [ ] workflow-session.json: 更新任务计数
+
+### 变更操作
+1. **创建**: IMPL-004.json (双因素认证实现)
+2. **更新**: IMPL-001.json (添加 2FA 准备工作)
+3. **删除**: IMPL-003.json (已被新方案替代)
+```
+
+**Step 3.3: User Confirmation**
+
+```javascript
+Options:
+- 确认执行: 开始应用所有修改
+- 调整计划: 重新回答问题调整范围
+- 取消操作: 放弃本次重规划
+```
+
+**Output**: Modification plan confirmed or adjusted
+
+---
+
+### Phase 4: Backup Creation
+
+**Process**:
+
+1. **Create Backup Directory**:
+```bash
+timestamp=$(date -u +"%Y-%m-%dT%H-%M-%S")
+backup_dir=".workflow/active/$SESSION_ID/.process/backup/replan-$timestamp"
+mkdir -p "$backup_dir"
+```
+
+2. **Backup All Affected Files**:
+   - IMPL_PLAN.md
+   - TODO_LIST.md
+   - workflow-session.json
+   - Affected task JSONs
+
+3. **Create Backup Manifest**:
+```markdown
+# Replan Backup Manifest
+
+**Timestamp**: {timestamp}
+**Reason**: {replan_reason}
+**Scope**: {modification_scope}
+
+## Restoration Command
+cp {backup_dir}/* .workflow/active/{session}/
+```
+
+**Output**: All files safely backed up with manifest
+
+---
+
+### Phase 5: Apply Modifications
+
+**Step 5.1: Update IMPL_PLAN.md** (if needed)
+
+Use Edit tool to modify specific sections:
+- Update affected technical sections
+- Update modification date
+
+**Step 5.2: Update TODO_LIST.md** (if needed)
+
+- Add new tasks with `[ ]` checkbox
+- Mark deleted tasks as `[x] ~~task~~ (已废弃)`
+- Update modified task descriptions
+
+**Step 5.3: Update Task JSONs**
+
+For each affected task:
+```typescript
+const updated_task = {
+  ...task,
+  context: {
+    ...task.context,
+    requirements: [...updated_requirements],
+    acceptance: [...updated_acceptance]
+  },
+  flow_control: {
+    ...task.flow_control,
+    implementation_approach: [...updated_steps]
+  }
+};
+
+Write({
+  file_path: `.workflow/active/${SESSION_ID}/.task/${task_id}.json`,
+  content: JSON.stringify(updated_task, null, 2)
+});
+```
+
+**Step 5.4: Create New Tasks** (if needed)
+
+Generate complete task JSON with all required fields:
+- id, title, status
+- meta (type, agent)
+- context (requirements, focus_paths, acceptance)
+- flow_control (pre_analysis, implementation_approach, target_files)
+
+**Step 5.5: Delete Obsolete Tasks** (if needed)
+
+Move to backup instead of hard delete:
+```bash
+mv ".workflow/active/$SESSION_ID/.task/{task-id}.json" "$backup_dir/"
+```
+
+**Step 5.6: Update Session Metadata**
+
+Update workflow-session.json:
+- progress.current_tasks
+- progress.last_replan
+- replan_history array
+
+**Output**: All modifications applied, artifacts updated
+
+---
+
+### Phase 6: Verification & Summary
+
+**Step 6.1: Verify Consistency**
+
+1. Validate all task JSONs are valid JSON
+2. Check task count within limits (max 10)
+3. Verify dependency graph is acyclic
+
+**Step 6.2: Generate Change Summary**
+
+```markdown
+## 重规划完成
+
+### 会话信息
+- **Session**: {session-id}
+- **时间**: {timestamp}
+- **备份**: {backup-path}
+
+### 变更摘要
+**范围**: {scope}
+**原因**: {reason}
+
+### 修改的文件
+- ✓ IMPL_PLAN.md: {changes}
+- ✓ TODO_LIST.md: {changes}
+- ✓ Task JSONs: {count} files updated
+
+### 任务变更
+- **新增**: {task-ids}
+- **删除**: {task-ids}
+- **更新**: {task-ids}
+
+### 回滚方法
+cp {backup-path}/* .workflow/active/{session}/
+```
+
+**Output**: Summary displayed, replan complete
+
+---
+
+## TodoWrite Progress Tracking
+
+### Session Mode Progress
+
+```json
+[
+  {"content": "检测模式和发现会话", "status": "completed", "activeForm": "检测模式和发现会话"},
+  {"content": "交互式需求明确", "status": "completed", "activeForm": "交互式需求明确"},
+  {"content": "影响分析和计划生成", "status": "completed", "activeForm": "影响分析和计划生成"},
+  {"content": "创建备份", "status": "completed", "activeForm": "创建备份"},
+  {"content": "更新会话产出文件", "status": "completed", "activeForm": "更新会话产出文件"},
+  {"content": "验证一致性", "status": "completed", "activeForm": "验证一致性"}
+]
+```
+
+### Task Mode Progress
+
+```json
+[
+  {"content": "检测会话和加载任务", "status": "completed", "activeForm": "检测会话和加载任务"},
+  {"content": "交互式更新确认", "status": "completed", "activeForm": "交互式更新确认"},
+  {"content": "应用任务修改", "status": "completed", "activeForm": "应用任务修改"}
+]
+```
+
+## Error Handling
+
+### Session Errors
+
+```bash
+# No active session found
+ERROR: No active session found
+Run /workflow:session:start to create a session
+
+# Session not found
+ERROR: Session WFS-invalid not found
+Available sessions: [list]
+
+# No changes specified
+WARNING: No modifications specified
+Use --interactive mode or provide requirements
+```
+
+### Task Errors
+
+```bash
+# Task not found
+ERROR: Task IMPL-999 not found in session
+Available tasks: [list]
+
+# Task completed
+WARNING: Task IMPL-001 is completed
+Consider creating new task for additional work
+
+# Circular dependency
+ERROR: Circular dependency detected
+Resolve dependency conflicts before proceeding
+```
+
+### Validation Errors
+
+```bash
+# Task limit exceeded
+ERROR: Replan would create 12 tasks (limit: 10)
+Consider: combining tasks, splitting sessions, or removing tasks
+
+# Invalid JSON
+ERROR: Generated invalid JSON
+Backup preserved, rolling back changes
+```
+
+## File Structure
+
+```
+.workflow/active/WFS-session-name/
+├── workflow-session.json
+├── IMPL_PLAN.md
+├── TODO_LIST.md
+├── .task/
+│   ├── IMPL-001.json
+│   ├── IMPL-002.json
+│   └── IMPL-003.json
+└── .process/
+    ├── context-package.json
+    └── backup/
+        └── replan-{timestamp}/
+            ├── MANIFEST.md
+            ├── IMPL_PLAN.md
+            ├── TODO_LIST.md
+            ├── workflow-session.json
+            └── IMPL-*.json
+```
+
+## Examples
+
+### Session Replan - Add Feature
+
+```bash
+/workflow:replan "添加双因素认证支持"
+
+# Interactive clarification
+Q: 修改范围?
+A: 全面重规划
+
+Q: 受影响模块?
+A: 认证模块, API接口
+
+Q: 任务变更?
+A: 添加新任务, 更新内容
+
+# Execution
+✓ 创建备份
+✓ 更新 IMPL_PLAN.md
+✓ 更新 TODO_LIST.md
+✓ 创建 IMPL-004.json
+✓ 更新 IMPL-001.json, IMPL-002.json
+
+重规划完成! 新增 1 任务,更新 2 任务
+```
+
+### Task Replan - Update Requirements
+
+```bash
+/workflow:replan IMPL-001 "支持 OAuth2.0 标准"
+
+# Interactive clarification
+Q: 更新部分?
+A: 需求和验收标准, 实现方案
+
+Q: 影响其他任务?
+A: 是,需要同步更新依赖任务
+
+# Execution
+✓ 创建备份
+✓ 更新 IMPL-001.json
+✓ 更新 IMPL-002.json (依赖任务)
+
+任务重规划完成! 更新 2 个任务
+```

.claude/commands/workflow/resume.md

@@ -1,93 +0,0 @@
----
-name: resume
-description: Intelligent workflow session resumption with automatic progress analysis
-argument-hint: "session-id for workflow session to resume"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
----
-
-# Sequential Workflow Resume Command
-
-## Usage
-```bash
-/workflow:resume "<session-id>"
-```
-
-## Purpose
-**Sequential command coordination for workflow resumption** by first analyzing current session status, then continuing execution with special resume context. This command orchestrates intelligent session resumption through two-step process.
-
-## Command Coordination Workflow
-
-### Phase 1: Status Analysis
-1. **Call status command**: Execute `/workflow:status` to analyze current session state
-2. **Verify session information**: Check session ID, progress, and current task status
-3. **Identify resume point**: Determine where workflow was interrupted
-
-### Phase 2: Resume Execution
-1. **Call execute with resume flag**: Execute `/workflow:execute --resume-session="{session-id}"`
-2. **Pass session context**: Provide analyzed session information to execute command
-3. **Direct agent execution**: Skip discovery phase, directly enter TodoWrite and agent execution
-
-## Implementation Protocol
-
-### Sequential Command Execution
-```bash
-# Phase 1: Analyze current session status
-SlashCommand(command="/workflow:status")
-
-# Phase 2: Resume execution with special flag
-SlashCommand(command="/workflow:execute --resume-session=\"{session-id}\"")
-```
-
-### Progress Tracking
-```javascript
-TodoWrite({
-  todos: [
-    {
-      content: "Analyze current session status and progress",
-      status: "in_progress",
-      activeForm: "Analyzing session status"
-    },
-    {
-      content: "Resume workflow execution with session context",
-      status: "pending",
-      activeForm: "Resuming workflow execution"
-    }
-  ]
-});
-```
-
-## Resume Information Flow
-
-### Status Analysis Results
-The `/workflow:status` command provides:
-- **Session ID**: Current active session identifier
-- **Current Progress**: Completed, in-progress, and pending tasks
-- **Interruption Point**: Last executed task and next pending task
-- **Session State**: Overall workflow status
-
-### Execute Command Context
-The special `--resume-session` flag tells `/workflow:execute`:
-- **Skip Discovery**: Don't search for sessions, use provided session ID
-- **Direct Execution**: Go straight to TodoWrite generation and agent launching
-- **Context Restoration**: Use existing session state and summaries
-- **Resume Point**: Continue from identified interruption point
-
-## Error Handling
-
-### Session Validation Failures
-- **Session not found**: Report missing session, suggest available sessions
-- **Session inactive**: Recommend activating session first
-- **Status command fails**: Retry once, then report analysis failure
-
-### Execute Resumption Failures
-- **No pending tasks**: Report workflow completion status
-- **Execute command fails**: Report resumption failure, suggest manual intervention
-
-## Success Criteria
-1. **Status analysis complete**: Session state properly analyzed and reported
-2. **Execute command launched**: Resume execution started with proper context
-3. **Agent coordination**: TodoWrite and agent execution initiated successfully
-4. **Context preservation**: Session state and progress properly maintained
-
----
-*Sequential command coordination for workflow session resumption*

.claude/commands/workflow/review.md

@@ -1,20 +1,20 @@
 ---
 name: review
-description: Optional specialized review (security, architecture, docs) for completed implementation
+description: Post-implementation review with specialized types (security/architecture/action-items/quality) using analysis agents and Gemini
 argument-hint: "[--type=security|architecture|action-items|quality] [optional: session-id]"
 ---
 
-### 🚀 Command Overview: `/workflow:review`
+## Command Overview: /workflow:review
 
 **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).
 
 ## Philosophy: "Tests Are the Review"
 
-- ✅ **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)
+- **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)
 
 ## Review Types
 
@@ -39,18 +39,18 @@ argument-hint: "[--type=security|architecture|action-items|quality] [optional: s
 if [ -n "$SESSION_ARG" ]; then
     sessionId="$SESSION_ARG"
 else
-    sessionId=$(find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//')
+    sessionId=$(find .workflow/active/ -name "WFS-*" -type d | head -1 | xargs basename)
 fi
 
 # Step 2: Validation
-if [ ! -d ".workflow/${sessionId}" ]; then
-    echo "❌ Session ${sessionId} not found"
+if [ ! -d ".workflow/active/${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"
+if [ ! -d ".workflow/active/${sessionId}/.summaries" ] || [ -z "$(find .workflow/active/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
+    echo "No completed implementation found. Complete implementation first"
     exit 1
 fi
 
@@ -59,7 +59,7 @@ review_type="${TYPE_ARG:-quality}"
 
 # Redirect docs review to specialized command
 if [ "$review_type" = "docs" ]; then
-    echo "💡 For documentation generation, please use:"
+    echo "For documentation generation, please use:"
     echo "   /workflow:tools:docs"
     echo ""
     echo "The docs command provides:"
@@ -73,20 +73,20 @@ fi
 # BASH_EXECUTION_STOPS → MODEL_ANALYSIS_BEGINS
 ```
 
-### 🧠 Model Analysis Phase
+### 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
+   cat .workflow/active/${sessionId}/.summaries/IMPL-*.md
 
    # Load test results (if available)
-   cat .workflow/${sessionId}/.summaries/TEST-FIX-*.md 2>/dev/null
+   cat .workflow/active/${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
+   git log --since="$(cat .workflow/active/${sessionId}/workflow-session.json | jq -r .created_at)" --name-only --pretty=format: | sort -u
    ```
 
 2. **Perform Specialized Review**: Based on `review_type`
@@ -99,7 +99,7 @@ After bash validation, the model takes control to:
      ```
    - Use Gemini for security analysis:
      ```bash
-     cd .workflow/${sessionId} && gemini -p "
+     cd .workflow/active/${sessionId} && gemini -p "
      PURPOSE: Security audit of completed implementation
      TASK: Review code for security vulnerabilities, insecure patterns, auth/authz issues
      CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -111,7 +111,7 @@ After bash validation, the model takes control to:
    **Architecture Review** (`--type=architecture`):
    - Use Qwen for architecture analysis:
      ```bash
-     cd .workflow/${sessionId} && qwen -p "
+     cd .workflow/active/${sessionId} && qwen -p "
      PURPOSE: Architecture compliance review
      TASK: Evaluate adherence to architectural patterns, identify technical debt, review design decisions
      CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -123,7 +123,7 @@ After bash validation, the model takes control to:
    **Quality Review** (`--type=quality`):
    - Use Gemini for code quality:
      ```bash
-     cd .workflow/${sessionId} && gemini -p "
+     cd .workflow/active/${sessionId} && gemini -p "
      PURPOSE: Code quality and best practices review
      TASK: Assess code readability, maintainability, adherence to best practices
      CONTEXT: @.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -136,14 +136,14 @@ After bash validation, the model takes control to:
    - Verify all requirements and acceptance criteria met:
      ```bash
      # Load task requirements and acceptance criteria
-     find .workflow/${sessionId}/.task -name "IMPL-*.json" -exec jq -r '
+     find .workflow/active/${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} && gemini -p "
+     cd .workflow/active/${sessionId} && gemini -p "
      PURPOSE: Verify all requirements and acceptance criteria are met
      TASK: Cross-check implementation summaries against original requirements
      CONTEXT: @.task/IMPL-*.json,.summaries/IMPL-*.md,../.. @../../CLAUDE.md
@@ -195,7 +195,7 @@ After bash validation, the model takes control to:
 4. **Output Files**:
    ```bash
    # Save review report
-   Write(.workflow/${sessionId}/REVIEW-${review_type}.md)
+   Write(.workflow/active/${sessionId}/REVIEW-${review_type}.md)
 
    # Update session metadata
    # (optional) Update workflow-session.json with review status
@@ -205,7 +205,7 @@ After bash validation, the model takes control to:
    ```bash
    # If architecture or quality issues found, suggest memory update
    if [ "$review_type" = "architecture" ] || [ "$review_type" = "quality" ]; then
-       echo "💡 Consider updating project documentation:"
+       echo "Consider updating project documentation:"
        echo "   /update-memory-related"
    fi
    ```
@@ -226,7 +226,7 @@ After bash validation, the model takes control to:
 /workflow:review --type=docs
 ```
 
-## ✨ Features
+## Features
 
 - **Simple Validation**: Check session exists and has completed tasks
 - **No Complex Orchestration**: Direct analysis, no multi-phase pipeline
@@ -240,10 +240,10 @@ After bash validation, the model takes control to:
 
 ```
 Standard Workflow:
-  plan → execute → test-gen → execute ✅
+  plan -> execute -> test-gen -> execute (complete)
 
 Optional Review (when needed):
-  plan → execute → test-gen → execute → review (security/architecture/docs)
+  plan -> execute -> test-gen -> execute -> review (security/architecture/docs)
 ```
 
 **When to Use**:
@@ -256,11 +256,3 @@ Optional Review (when needed):
 - 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 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

@@ -1,6 +1,6 @@
 ---
 name: complete
-description: Mark the active workflow session as complete and remove active flag
+description: Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag
 examples:
   - /workflow:session:complete
   - /workflow:session:complete --detailed
@@ -9,7 +9,7 @@ examples:
 # Complete Workflow Session (/workflow:session:complete)
 
 ## Overview
-Mark the currently active workflow session as complete, update its status, and remove the active flag marker.
+Mark the currently active workflow session as complete, analyze it for lessons learned, move it to the archive directory, and remove the active flag marker.
 
 ## Usage
 ```bash
@@ -19,87 +19,461 @@ Mark the currently active workflow session as complete, update its status, and r
 
 ## Implementation Flow
 
-### Step 1: Find Active Session
+### Phase 1: Pre-Archival Preparation (Transactional Setup)
+
+**Purpose**: Find active session, create archiving marker to prevent concurrent operations. Session remains in active location for agent processing.
+
+#### Step 1.1: Find Active Session and Get Name
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
-```
+# Find active session directory
+bash(find .workflow/active/ -name "WFS-*" -type d | head -1)
 
-### Step 2: Get Session Name
+# Extract session name from directory path
+bash(basename .workflow/active/WFS-session-name)
+```
+**Output**: Session name `WFS-session-name`
+
+#### Step 1.2: Check for Existing Archiving Marker (Resume Detection)
 ```bash
-basename .workflow/.active-WFS-session-name | sed 's/^\.active-//'
+# Check if session is already being archived
+bash(test -f .workflow/active/WFS-session-name/.archiving && echo "RESUMING" || echo "NEW")
 ```
 
-### Step 3: Update Session Status
+**If RESUMING**:
+- Previous archival attempt was interrupted
+- Skip to Phase 2 to resume agent analysis
+
+**If NEW**:
+- Continue to Step 1.3
+
+#### Step 1.3: Create Archiving Marker
 ```bash
-jq '.status = "completed"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+# Mark session as "archiving in progress"
+bash(touch .workflow/active/WFS-session-name/.archiving)
+```
+**Purpose**:
+- Prevents concurrent operations on this session
+- Enables recovery if archival fails
+- Session remains in `.workflow/active/` for agent analysis
+
+**Result**: Session still at `.workflow/active/WFS-session-name/` with `.archiving` marker
+
+### Phase 2: Agent Analysis (In-Place Processing)
+
+**Purpose**: Agent analyzes session WHILE STILL IN ACTIVE LOCATION. Generates metadata but does NOT move files or update manifest.
+
+#### Agent Invocation
+
+Invoke `universal-executor` agent to analyze session and prepare archive metadata.
+
+**Agent Task**:
+```
+Task(
+  subagent_type="universal-executor",
+  description="Analyze session for archival",
+  prompt=`
+Analyze workflow session for archival preparation. Session is STILL in active location.
+
+## Context
+- Session: .workflow/active/WFS-session-name/
+- Status: Marked as archiving (.archiving marker present)
+- Location: Active sessions directory (NOT archived yet)
+
+## Tasks
+
+1. **Extract session data** from workflow-session.json
+   - session_id, description/topic, started_at, completed_at, status
+   - If status != "completed", update it with timestamp
+
+2. **Count files**: tasks (.task/*.json) and summaries (.summaries/*.md)
+
+3. **Generate lessons**: Use gemini with ~/.claude/workflows/cli-templates/prompts/archive/analysis-simple.txt
+   - Return: {successes, challenges, watch_patterns}
+
+4. **Build archive entry**:
+   - Calculate: duration_hours, success_rate, tags (3-5 keywords)
+   - Construct complete JSON with session_id, description, archived_at, metrics, tags, lessons
+   - Include archive_path: ".workflow/archives/WFS-session-name" (future location)
+
+5. **Extract feature metadata** (for Phase 4):
+   - Parse IMPL_PLAN.md for title (first # heading)
+   - Extract description (first paragraph, max 200 chars)
+   - Generate feature tags (3-5 keywords from content)
+
+6. **Return result**: Complete metadata package for atomic commit
+   {
+     "status": "success",
+     "session_id": "WFS-session-name",
+     "archive_entry": {
+       "session_id": "...",
+       "description": "...",
+       "archived_at": "...",
+       "archive_path": ".workflow/archives/WFS-session-name",
+       "metrics": {...},
+       "tags": [...],
+       "lessons": {...}
+     },
+     "feature_metadata": {
+       "title": "...",
+       "description": "...",
+       "tags": [...]
+     }
+   }
+
+## Important Constraints
+- DO NOT move or delete any files
+- DO NOT update manifest.json yet
+- Session remains in .workflow/active/ during analysis
+- Return complete metadata package for orchestrator to commit atomically
+
+## Error Handling
+- On failure: return {"status": "error", "task": "...", "message": "..."}
+- Do NOT modify any files on error
+  `
+)
 ```
 
-### Step 4: Add Completion Timestamp
+**Expected Output**:
+- Agent returns complete metadata package
+- Session remains in `.workflow/active/` with `.archiving` marker
+- No files moved or manifests updated yet
+
+### Phase 3: Atomic Commit (Transactional File Operations)
+
+**Purpose**: Atomically commit all changes. Only execute if Phase 2 succeeds.
+
+#### Step 3.1: Create Archive Directory
 ```bash
-jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+bash(mkdir -p .workflow/archives/)
 ```
 
-### Step 5: Count Final Statistics
+#### Step 3.2: Move Session to Archive
 ```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
+bash(mv .workflow/active/WFS-session-name .workflow/archives/WFS-session-name)
 ```
+**Result**: Session now at `.workflow/archives/WFS-session-name/`
 
-### Step 6: Remove Active Marker
+#### Step 3.3: Update Manifest
 ```bash
-rm .workflow/.active-WFS-session-name
+# Read current manifest (or create empty array if not exists)
+bash(test -f .workflow/archives/manifest.json && cat .workflow/archives/manifest.json || echo "[]")
 ```
 
-## Simple Bash Commands
+**JSON Update Logic**:
+```javascript
+// Read agent result from Phase 2
+const agentResult = JSON.parse(agentOutput);
+const archiveEntry = agentResult.archive_entry;
 
-### Basic Operations
-- **Find active session**: `find .workflow/ -name ".active-*" -type f`
-- **Get session name**: `basename marker | sed 's/^\.active-//'`
-- **Update status**: `jq '.status = "completed"' session.json > temp.json`
-- **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
-- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
-- **Remove marker**: `rm .workflow/.active-session`
+// Read existing manifest
+let manifest = [];
+try {
+  const manifestContent = Read('.workflow/archives/manifest.json');
+  manifest = JSON.parse(manifestContent);
+} catch {
+  manifest = []; // Initialize if not exists
+}
 
-### Completion Result
-```
-Session WFS-user-auth completed
-- Status: completed
-- Started: 2025-09-15T10:00:00Z
-- Completed: 2025-09-15T16:30:00Z
-- Duration: 6h 30m
-- Total tasks: 8
-- Completed tasks: 8
-- Success rate: 100%
+// Append new entry
+manifest.push(archiveEntry);
+
+// Write back
+Write('.workflow/archives/manifest.json', JSON.stringify(manifest, null, 2));
 ```
 
-### Detailed Summary (--detailed flag)
-```
-Session Completion Summary:
-├── Session: WFS-user-auth
-├── Project: User authentication system
-├── Total time: 6h 30m
-├── Tasks completed: 8/8 (100%)
-├── Files generated: 24 files
-├── Summaries created: 8 summaries
-├── Status: All tasks completed successfully
-└── Location: .workflow/WFS-user-auth/
-```
-
-### Error Handling
+#### Step 3.4: Remove Archiving Marker
 ```bash
-# No active session
-find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
+bash(rm .workflow/archives/WFS-session-name/.archiving)
+```
+**Result**: Clean archived session without temporary markers
 
-# Incomplete tasks
-task_count=$(find .task/ -name "*.json" -type f | wc -l)
-summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
-test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
+**Output Confirmation**:
+```
+✓ Session "${sessionId}" archived successfully
+  Location: .workflow/archives/WFS-session-name/
+  Lessons: ${archiveEntry.lessons.successes.length} successes, ${archiveEntry.lessons.challenges.length} challenges
+  Manifest: Updated with ${manifest.length} total sessions
 ```
 
-## Related Commands
-- `/workflow:session:list` - View all sessions including completed
-- `/workflow:session:start` - Start new session
-- `/workflow:status` - Check completion status before completing
+### Phase 4: Update Project Feature Registry
+
+**Purpose**: Record completed session as a project feature in `.workflow/project.json`.
+
+**Execution**: Uses feature metadata from Phase 2 agent result to update project registry.
+
+#### Step 4.1: Check Project State Exists
+```bash
+bash(test -f .workflow/project.json && echo "EXISTS" || echo "SKIP")
+```
+
+**If SKIP**: Output warning and skip Phase 4
+```
+WARNING: No project.json found. Run /workflow:session:start to initialize.
+```
+
+#### Step 4.2: Extract Feature Information from Agent Result
+
+**Data Processing** (Uses Phase 2 agent output):
+```javascript
+// Extract feature metadata from agent result
+const agentResult = JSON.parse(agentOutput);
+const featureMeta = agentResult.feature_metadata;
+
+// Data already prepared by agent:
+const title = featureMeta.title;
+const description = featureMeta.description;
+const tags = featureMeta.tags;
+
+// Create feature ID (lowercase slug)
+const featureId = title.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 50);
+```
+
+#### Step 4.3: Update project.json
+
+```bash
+# Read current project state
+bash(cat .workflow/project.json)
+```
+
+**JSON Update Logic**:
+```javascript
+// Read existing project.json (created by /workflow:init)
+// Note: overview field is managed by /workflow:init, not modified here
+const projectMeta = JSON.parse(Read('.workflow/project.json'));
+const currentTimestamp = new Date().toISOString();
+const currentDate = currentTimestamp.split('T')[0]; // YYYY-MM-DD
+
+// Extract tags from IMPL_PLAN.md (simple keyword extraction)
+const tags = extractTags(planContent); // e.g., ["auth", "security"]
+
+// Build feature object with complete metadata
+const newFeature = {
+  id: featureId,
+  title: title,
+  description: description,
+  status: "completed",
+  tags: tags,
+  timeline: {
+    created_at: currentTimestamp,
+    implemented_at: currentDate,
+    updated_at: currentTimestamp
+  },
+  traceability: {
+    session_id: sessionId,
+    archive_path: archivePath, // e.g., ".workflow/archives/WFS-auth-system"
+    commit_hash: getLatestCommitHash() || "" // Optional: git rev-parse HEAD
+  },
+  docs: [],      // Placeholder for future doc links
+  relations: []  // Placeholder for feature dependencies
+};
+
+// Add new feature to array
+projectMeta.features.push(newFeature);
+
+// Update statistics
+projectMeta.statistics.total_features = projectMeta.features.length;
+projectMeta.statistics.total_sessions += 1;
+projectMeta.statistics.last_updated = currentTimestamp;
+
+// Write back
+Write('.workflow/project.json', JSON.stringify(projectMeta, null, 2));
+```
+
+**Helper Functions**:
+```javascript
+// Extract tags from IMPL_PLAN.md content
+function extractTags(planContent) {
+  const tags = [];
+
+  // Look for common keywords
+  const keywords = {
+    'auth': /authentication|login|oauth|jwt/i,
+    'security': /security|encrypt|hash|token/i,
+    'api': /api|endpoint|rest|graphql/i,
+    'ui': /component|page|interface|frontend/i,
+    'database': /database|schema|migration|sql/i,
+    'test': /test|testing|spec|coverage/i
+  };
+
+  for (const [tag, pattern] of Object.entries(keywords)) {
+    if (pattern.test(planContent)) {
+      tags.push(tag);
+    }
+  }
+
+  return tags.slice(0, 5); // Max 5 tags
+}
+
+// Get latest git commit hash (optional)
+function getLatestCommitHash() {
+  try {
+    const result = Bash({
+      command: "git rev-parse --short HEAD 2>/dev/null",
+      description: "Get latest commit hash"
+    });
+    return result.trim();
+  } catch {
+    return "";
+  }
+}
+```
+
+#### Step 4.4: Output Confirmation
+
+```
+✓ Feature "${title}" added to project registry
+  ID: ${featureId}
+  Session: ${sessionId}
+  Location: .workflow/project.json
+```
+
+**Error Handling**:
+- If project.json malformed: Output error, skip update
+- If feature_metadata missing from agent result: Skip Phase 4
+- If extraction fails: Use minimal defaults
+
+**Phase 4 Total Commands**: 1 bash read + JSON manipulation
+
+## Error Recovery
+
+### If Agent Fails (Phase 2)
+
+**Symptoms**:
+- Agent returns `{"status": "error", ...}`
+- Agent crashes or times out
+- Analysis incomplete
+
+**Recovery Steps**:
+```bash
+# Session still in .workflow/active/WFS-session-name
+# Remove archiving marker
+bash(rm .workflow/active/WFS-session-name/.archiving)
+```
+
+**User Notification**:
+```
+ERROR: Session archival failed during analysis phase
+Reason: [error message from agent]
+Session remains active in: .workflow/active/WFS-session-name
+
+Recovery:
+1. Fix any issues identified in error message
+2. Retry: /workflow:session:complete
+
+Session state: SAFE (no changes committed)
+```
+
+### If Move Fails (Phase 3)
+
+**Symptoms**:
+- `mv` command fails
+- Permission denied
+- Disk full
+
+**Recovery Steps**:
+```bash
+# Archiving marker still present
+# Session still in .workflow/active/ (move failed)
+# No manifest updated yet
+```
+
+**User Notification**:
+```
+ERROR: Session archival failed during move operation
+Reason: [mv error message]
+Session remains in: .workflow/active/WFS-session-name
+
+Recovery:
+1. Fix filesystem issues (permissions, disk space)
+2. Retry: /workflow:session:complete
+   - System will detect .archiving marker
+   - Will resume from Phase 2 (agent analysis)
+
+Session state: SAFE (analysis complete, ready to retry move)
+```
+
+### If Manifest Update Fails (Phase 3)
+
+**Symptoms**:
+- JSON parsing error
+- Write permission denied
+- Session moved but manifest not updated
+
+**Recovery Steps**:
+```bash
+# Session moved to .workflow/archives/WFS-session-name
+# Manifest NOT updated
+# Archiving marker still present in archived location
+```
+
+**User Notification**:
+```
+ERROR: Session archived but manifest update failed
+Reason: [error message]
+Session location: .workflow/archives/WFS-session-name
+
+Recovery:
+1. Fix manifest.json issues (syntax, permissions)
+2. Manual manifest update:
+   - Add archive entry from agent output
+   - Remove .archiving marker: rm .workflow/archives/WFS-session-name/.archiving
+
+Session state: PARTIALLY COMPLETE (session archived, manifest needs update)
+```
+
+## Workflow Execution Strategy
+
+### Transactional Four-Phase Approach
+
+**Phase 1: Pre-Archival Preparation** (Marker creation)
+- Find active session and extract name
+- Check for existing `.archiving` marker (resume detection)
+- Create `.archiving` marker if new
+- **No data processing** - just state tracking
+- **Total**: 2-3 bash commands (find + marker check/create)
+
+**Phase 2: Agent Analysis** (Read-only data processing)
+- Extract all session data from active location
+- Count tasks and summaries
+- Generate lessons learned analysis
+- Extract feature metadata from IMPL_PLAN.md
+- Build complete archive + feature metadata package
+- **No file modifications** - pure analysis
+- **Total**: 1 agent invocation
+
+**Phase 3: Atomic Commit** (Transactional file operations)
+- Create archive directory
+- Move session to archive location
+- Update manifest.json with archive entry
+- Remove `.archiving` marker
+- **All-or-nothing**: Either all succeed or session remains in safe state
+- **Total**: 4 bash commands + JSON manipulation
+
+**Phase 4: Project Registry Update** (Optional feature tracking)
+- Check project.json exists
+- Use feature metadata from Phase 2 agent result
+- Build feature object with complete traceability
+- Update project statistics
+- **Independent**: Can fail without affecting archival
+- **Total**: 1 bash read + JSON manipulation
+
+### Transactional Guarantees
+
+**State Consistency**:
+- Session NEVER in inconsistent state
+- `.archiving` marker enables safe resume
+- Agent failure leaves session in recoverable state
+- Move/manifest operations grouped in Phase 3
+
+**Failure Isolation**:
+- Phase 1 failure: No changes made
+- Phase 2 failure: Session still active, can retry
+- Phase 3 failure: Clear error state, manual recovery documented
+- Phase 4 failure: Does not affect archival success
+
+**Resume Capability**:
+- Detect interrupted archival via `.archiving` marker
+- Resume from Phase 2 (skip marker creation)
+- Idempotent operations (safe to retry)
+
+

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

@@ -1,6 +1,6 @@
 ---
 name: list
-description: List all workflow sessions with status
+description: List all workflow sessions with status filtering, shows session metadata and progress information
 examples:
   - /workflow:session:list
 ---
@@ -19,35 +19,35 @@ Display all workflow sessions with their current status, progress, and metadata.
 
 ### Step 1: Find All Sessions
 ```bash
-ls .workflow/WFS-* 2>/dev/null
+ls .workflow/active/WFS-* 2>/dev/null
 ```
 
 ### Step 2: Check Active Session
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
+find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1
 ```
 
 ### Step 3: Read Session Metadata
 ```bash
-jq -r '.session_id, .status, .project' .workflow/WFS-session/workflow-session.json
+jq -r '.session_id, .status, .project' .workflow/active/WFS-session/workflow-session.json
 ```
 
 ### Step 4: Count Task Progress
 ```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
+find .workflow/active/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
+find .workflow/active/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ### Step 5: Get Creation Time
 ```bash
-jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
+jq -r '.created_at // "unknown"' .workflow/active/WFS-session/workflow-session.json
 ```
 
 ## Simple Bash Commands
 
 ### Basic Operations
-- **List sessions**: `find .workflow/ -maxdepth 1 -type d -name "WFS-*"`
-- **Find active**: `find .workflow/ -name ".active-*" -type f`
+- **List sessions**: `find .workflow/active/ -name "WFS-*" -type d`
+- **Find active**: `find .workflow/active/ -name "WFS-*" -type d`
 - **Read session data**: `jq -r '.session_id, .status' session.json`
 - **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
 - **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
@@ -59,19 +59,19 @@ jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
 ```
 Workflow Sessions:
 
-✅ WFS-oauth-integration (ACTIVE)
+[ACTIVE] WFS-oauth-integration
    Project: OAuth2 authentication system
    Status: active
    Progress: 3/8 tasks completed
    Created: 2025-09-15T10:30:00Z
 
-⏸️ WFS-user-profile (PAUSED)
+[PAUSED] WFS-user-profile
    Project: User profile management
    Status: paused
    Progress: 1/5 tasks completed
    Created: 2025-09-14T14:15:00Z
 
-📁 WFS-database-migration (COMPLETED)
+[COMPLETED] WFS-database-migration
    Project: Database schema migration
    Status: completed
    Progress: 4/4 tasks completed
@@ -81,24 +81,16 @@ Total: 3 sessions (1 active, 1 paused, 1 completed)
 ```
 
 ### Status Indicators
-- **✅**: Active session
-- **⏸️**: Paused session
-- **📁**: Completed session
-- **❌**: Error/corrupted session
+- **[ACTIVE]**: Active session
+- **[PAUSED]**: Paused session
+- **[COMPLETED]**: Completed session
+- **[ERROR]**: Error/corrupted session
 
 ### Quick Commands
 ```bash
 # Count all sessions
-ls .workflow/WFS-* | wc -l
-
-# Show only active
-ls .workflow/.active-* | basename | sed 's/^\.active-//'
+ls .workflow/active/WFS-* | wc -l
 
 # Show recent sessions
-ls -t .workflow/WFS-*/workflow-session.json | head -3
-```
-
-## Related Commands
-- `/workflow:session:start` - Create new session
-- `/workflow:session:switch` - Switch to different session
-- `/workflow:session:status` - Detailed session info
+ls -t .workflow/active/WFS-*/workflow-session.json | head -3
+```

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

@@ -1,6 +1,6 @@
 ---
 name: resume
-description: Resume the most recently paused workflow session
+description: Resume the most recently paused workflow session with automatic session discovery and status update
 ---
 
 # Resume Workflow Session (/workflow:session:resume)
@@ -17,45 +17,39 @@ Resume the most recently paused workflow session, restoring all context and stat
 
 ### Step 1: Find Paused Sessions
 ```bash
-ls .workflow/WFS-* 2>/dev/null
+ls .workflow/active/WFS-* 2>/dev/null
 ```
 
 ### Step 2: Check Session Status
 ```bash
-jq -r '.status' .workflow/WFS-session/workflow-session.json
+jq -r '.status' .workflow/active/WFS-session/workflow-session.json
 ```
 
 ### Step 3: Find Most Recent Paused
 ```bash
-ls -t .workflow/WFS-*/workflow-session.json | head -1
+ls -t .workflow/active/WFS-*/workflow-session.json | head -1
 ```
 
 ### Step 4: Update Session Status
 ```bash
-jq '.status = "active"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
+jq '.status = "active"' .workflow/active/WFS-session/workflow-session.json > temp.json
+mv temp.json .workflow/active/WFS-session/workflow-session.json
 ```
 
 ### Step 5: Add Resume Timestamp
 ```bash
-jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/WFS-session/workflow-session.json > temp.json
-mv temp.json .workflow/WFS-session/workflow-session.json
-```
-
-### Step 6: Create Active Marker
-```bash
-touch .workflow/.active-WFS-session-name
+jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"' .workflow/active/WFS-session/workflow-session.json > temp.json
+mv temp.json .workflow/active/WFS-session/workflow-session.json
 ```
 
 ## Simple Bash Commands
 
 ### Basic Operations
-- **List sessions**: `ls .workflow/WFS-*`
+- **List sessions**: `ls .workflow/active/WFS-*`
 - **Check status**: `jq -r '.status' session.json`
-- **Find recent**: `ls -t .workflow/*/workflow-session.json | head -1`
+- **Find recent**: `ls -t .workflow/active/*/workflow-session.json | head -1`
 - **Update status**: `jq '.status = "active"' session.json > temp.json`
 - **Add timestamp**: `jq '.resumed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Create marker**: `touch .workflow/.active-session`
 
 ### Resume Result
 ```
@@ -64,9 +58,4 @@ Session WFS-user-auth resumed
 - Paused at: 2025-09-15T14:30:00Z
 - Resumed at: 2025-09-15T15:45:00Z
 - Ready for: /workflow:execute
-```
-
-## Related Commands
-- `/workflow:session:pause` - Pause current session
-- `/workflow:execute` - Continue workflow execution
-- `/workflow:session:list` - Show all sessions
+```

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

@@ -1,6 +1,6 @@
 ---
 name: start
-description: Discover existing sessions or start a new workflow session with intelligent session management
+description: Discover existing sessions or start new workflow session with intelligent session management and conflict detection
 argument-hint: [--auto|--new] [optional: task description for new session]
 examples:
   - /workflow:session:start
@@ -13,6 +13,35 @@ examples:
 ## Overview
 Manages workflow sessions with three operation modes: discovery (manual), auto (intelligent), and force-new.
 
+**Dual Responsibility**:
+1. **Project-level initialization** (first-time only): Creates `.workflow/project.json` for feature registry
+2. **Session-level initialization** (always): Creates session directory structure
+
+## Step 0: Initialize Project State (First-time Only)
+
+**Executed before all modes** - Ensures project-level state file exists by calling `/workflow:init`.
+
+### Check and Initialize
+```bash
+# Check if project state exists
+bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
+```
+
+**If NOT_FOUND**, delegate to `/workflow:init`:
+```javascript
+// Call workflow:init for intelligent project analysis
+SlashCommand({command: "/workflow:init"});
+
+// Wait for init completion
+// project.json will be created with comprehensive project overview
+```
+
+**Output**:
+- If EXISTS: `PROJECT_STATE: initialized`
+- If NOT_FOUND: Calls `/workflow:init` → creates `.workflow/project.json` with full project analysis
+
+**Note**: `/workflow:init` uses cli-explore-agent to build comprehensive project understanding (technology stack, architecture, key components). This step runs once per project. Subsequent executions skip initialization.
+
 ## Mode 1: Discovery Mode (Default)
 
 ### Usage
@@ -20,19 +49,14 @@ Manages workflow sessions with three operation modes: discovery (manual), auto (
 /workflow:session:start
 ```
 
-### Step 1: Check Active Sessions
+### Step 1: List Active Sessions
 ```bash
-bash(ls .workflow/.active-* 2>/dev/null)
+bash(ls -1 .workflow/active/ 2>/dev/null | head -5)
 ```
 
-### Step 2: List All Sessions
+### Step 2: Display Session Metadata
 ```bash
-bash(ls -1 .workflow/WFS-* 2>/dev/null | head -5)
-```
-
-### Step 3: Display Session Metadata
-```bash
-bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json)
+bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json)
 ```
 
 ### Step 4: User Decision
@@ -49,7 +73,7 @@ Present session information and wait for user to select or create session.
 
 ### Step 1: Check Active Sessions Count
 ```bash
-bash(ls .workflow/.active-* 2>/dev/null | wc -l)
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | wc -l)
 ```
 
 ### Step 2a: No Active Sessions → Create New
@@ -58,15 +82,12 @@ bash(ls .workflow/.active-* 2>/dev/null | wc -l)
 bash(echo "implement OAuth2 auth" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
 
 # Create directory structure
-bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.process)
-bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.task)
-bash(mkdir -p .workflow/WFS-implement-oauth2-auth/.summaries)
+bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.process)
+bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.task)
+bash(mkdir -p .workflow/active/WFS-implement-oauth2-auth/.summaries)
 
 # Create metadata
-bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/WFS-implement-oauth2-auth/workflow-session.json)
-
-# Mark as active
-bash(touch .workflow/.active-WFS-implement-oauth2-auth)
+bash(echo '{"session_id":"WFS-implement-oauth2-auth","project":"implement OAuth2 auth","status":"planning"}' > .workflow/active/WFS-implement-oauth2-auth/workflow-session.json)
 ```
 
 **Output**: `SESSION_ID: WFS-implement-oauth2-auth`
@@ -74,10 +95,10 @@ bash(touch .workflow/.active-WFS-implement-oauth2-auth)
 ### Step 2b: Single Active Session → Check Relevance
 ```bash
 # Extract session ID
-bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.active-//')
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
 
 # Read project name from metadata
-bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
+bash(cat .workflow/active/WFS-promptmaster-platform/workflow-session.json | grep -o '"project":"[^"]*"' | cut -d'"' -f4)
 
 # Check keyword match (manual comparison)
 # If task contains project keywords → Reuse session
@@ -90,7 +111,7 @@ bash(cat .workflow/WFS-promptmaster-platform/workflow-session.json | grep -o '"p
 ### Step 2c: Multiple Active Sessions → Use First
 ```bash
 # Get first active session
-bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.active-//')
+bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1 | xargs basename)
 
 # Output warning and session ID
 # WARNING: Multiple active sessions detected
@@ -110,25 +131,19 @@ bash(ls .workflow/.active-* 2>/dev/null | head -1 | xargs basename | sed 's/^\.a
 bash(echo "fix login bug" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
 
 # Check if exists, add counter if needed
-bash(ls .workflow/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
+bash(ls .workflow/active/WFS-fix-login-bug 2>/dev/null && echo "WFS-fix-login-bug-2" || echo "WFS-fix-login-bug")
 ```
 
 ### Step 2: Create Session Structure
 ```bash
-bash(mkdir -p .workflow/WFS-fix-login-bug/.process)
-bash(mkdir -p .workflow/WFS-fix-login-bug/.task)
-bash(mkdir -p .workflow/WFS-fix-login-bug/.summaries)
+bash(mkdir -p .workflow/active/WFS-fix-login-bug/.process)
+bash(mkdir -p .workflow/active/WFS-fix-login-bug/.task)
+bash(mkdir -p .workflow/active/WFS-fix-login-bug/.summaries)
 ```
 
 ### Step 3: Create Metadata
 ```bash
-bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/WFS-fix-login-bug/workflow-session.json)
-```
-
-### Step 4: Mark Active and Clean Old Markers
-```bash
-bash(rm .workflow/.active-* 2>/dev/null)
-bash(touch .workflow/.active-WFS-fix-login-bug)
+bash(echo '{"session_id":"WFS-fix-login-bug","project":"fix login bug","status":"planning"}' > .workflow/active/WFS-fix-login-bug/workflow-session.json)
 ```
 
 **Output**: `SESSION_ID: WFS-fix-login-bug`
@@ -173,48 +188,8 @@ SlashCommand(command="/workflow:session:start")
 SlashCommand(command="/workflow:session:start --new \"experimental feature\"")
 ```
 
-## Simple Bash Commands
-
-### Basic Operations
-```bash
-# Check active sessions
-bash(ls .workflow/.active-*)
-
-# List all sessions
-bash(ls .workflow/WFS-*)
-
-# Read session metadata
-bash(cat .workflow/WFS-[session-id]/workflow-session.json)
-
-# Create session directories
-bash(mkdir -p .workflow/WFS-[session-id]/.process)
-bash(mkdir -p .workflow/WFS-[session-id]/.task)
-bash(mkdir -p .workflow/WFS-[session-id]/.summaries)
-
-# Mark session as active
-bash(touch .workflow/.active-WFS-[session-id])
-
-# Clean active markers
-bash(rm .workflow/.active-*)
-```
-
-### Generate Session Slug
-```bash
-bash(echo "Task Description" | sed 's/[^a-zA-Z0-9]/-/g' | tr '[:upper:]' '[:lower:]' | cut -c1-50)
-```
-
-### Create Metadata JSON
-```bash
-bash(echo '{"session_id":"WFS-test","project":"test project","status":"planning"}' > .workflow/WFS-test/workflow-session.json)
-```
-
 ## Session ID Format
 - Pattern: `WFS-[lowercase-slug]`
 - Characters: `a-z`, `0-9`, `-` only
 - Max length: 50 characters
-- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)
-
-## Related Commands
-- `/workflow:plan` - Uses `--auto` mode for session management
-- `/workflow:execute` - Uses discovery mode for session selection
-- `/workflow:session:status` - Shows detailed session information
+- Uniqueness: Add numeric suffix if collision (`WFS-auth-2`, `WFS-auth-3`)

.claude/commands/workflow/status.md

@@ -1,47 +1,185 @@
 ---
 name: workflow:status
-description: Generate on-demand views from JSON task data
-argument-hint: "[optional: task-id]"
+description: Generate on-demand views for project overview and workflow tasks with optional task-id filtering for detailed view
+argument-hint: "[optional: --project|task-id|--validate|--dashboard]"
 ---
 
 # 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.
+Generates on-demand views from project and session data. Supports multiple modes:
+1. **Project Overview** (`--project`): Shows completed features and project statistics
+2. **Workflow Tasks** (default): Shows current session task progress
+3. **HTML Dashboard** (`--dashboard`): Generates interactive HTML task board with active and archived sessions
+
+No synchronization needed - all views are calculated from current JSON state.
 
 ## Usage
 ```bash
-/workflow:status                    # Show current workflow overview
+/workflow:status                    # Show current workflow session overview
+/workflow:status --project          # Show project-level feature registry
 /workflow:status impl-1             # Show specific task details
 /workflow:status --validate         # Validate workflow integrity
+/workflow:status --dashboard        # Generate HTML dashboard board
 ```
 
 ## Implementation Flow
 
+### Mode Selection
+
+**Check for --project flag**:
+- If `--project` flag present → Execute **Project Overview Mode**
+- Otherwise → Execute **Workflow Session Mode** (default)
+
+## Project Overview Mode
+
+### Step 1: Check Project State
+```bash
+bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")
+```
+
+**If NOT_FOUND**:
+```
+No project state found.
+Run /workflow:session:start to initialize project.
+```
+
+### Step 2: Read Project Data
+```bash
+bash(cat .workflow/project.json)
+```
+
+### Step 3: Parse and Display
+
+**Data Processing**:
+```javascript
+const projectData = JSON.parse(Read('.workflow/project.json'));
+const features = projectData.features || [];
+const stats = projectData.statistics || {};
+const overview = projectData.overview || null;
+
+// Sort features by implementation date (newest first)
+const sortedFeatures = features.sort((a, b) =>
+  new Date(b.implemented_at) - new Date(a.implemented_at)
+);
+```
+
+**Output Format** (with extended overview):
+```
+## Project: ${projectData.project_name}
+Initialized: ${projectData.initialized_at}
+
+${overview ? `
+### Overview
+${overview.description}
+
+**Technology Stack**:
+${overview.technology_stack.languages.map(l => `- ${l.name}${l.primary ? ' (primary)' : ''}: ${l.file_count} files`).join('\n')}
+Frameworks: ${overview.technology_stack.frameworks.join(', ')}
+
+**Architecture**:
+Style: ${overview.architecture.style}
+Patterns: ${overview.architecture.patterns.join(', ')}
+
+**Key Components** (${overview.key_components.length}):
+${overview.key_components.map(c => `- ${c.name} (${c.path})\n  ${c.description}`).join('\n')}
+
+**Metrics**:
+- Files: ${overview.metrics.total_files}
+- Lines of Code: ${overview.metrics.lines_of_code}
+- Complexity: ${overview.metrics.complexity}
+
+---
+` : ''}
+
+### Completed Features (${stats.total_features})
+
+${sortedFeatures.map(f => `
+- ${f.title} (${f.timeline?.implemented_at || f.implemented_at})
+  ${f.description}
+  Tags: ${f.tags?.join(', ') || 'none'}
+  Session: ${f.traceability?.session_id || f.session_id}
+  Archive: ${f.traceability?.archive_path || 'unknown'}
+  ${f.traceability?.commit_hash ? `Commit: ${f.traceability.commit_hash}` : ''}
+`).join('\n')}
+
+### Project Statistics
+- Total Features: ${stats.total_features}
+- Total Sessions: ${stats.total_sessions}
+- Last Updated: ${stats.last_updated}
+
+### Quick Access
+- View session details: /workflow:status
+- Archive query: jq '.archives[] | select(.session_id == "SESSION_ID")' .workflow/archives/manifest.json
+- Documentation: .workflow/docs/${projectData.project_name}/
+
+### Query Commands
+# Find by tag
+cat .workflow/project.json | jq '.features[] | select(.tags[] == "auth")'
+
+# View archive
+cat ${feature.traceability.archive_path}/IMPL_PLAN.md
+
+# List all tags
+cat .workflow/project.json | jq -r '.features[].tags[]' | sort -u
+```
+
+**Empty State**:
+```
+## Project: ${projectData.project_name}
+Initialized: ${projectData.initialized_at}
+
+No features completed yet.
+
+Complete your first workflow session to add features:
+1. /workflow:plan "feature description"
+2. /workflow:execute
+3. /workflow:session:complete
+```
+
+### Step 4: Show Recent Sessions (Optional)
+
+```bash
+# List 5 most recent archived sessions
+bash(ls -1t .workflow/archives/WFS-* 2>/dev/null | head -5 | xargs -I {} basename {})
+```
+
+**Output**:
+```
+### Recent Sessions
+- WFS-auth-system (archived)
+- WFS-payment-flow (archived)
+- WFS-user-dashboard (archived)
+
+Use /workflow:session:complete to archive current session.
+```
+
+## Workflow Session Mode (Default)
+
 ### Step 1: Find Active Session
 ```bash
-find .workflow/ -name ".active-*" -type f 2>/dev/null | head -1
+find .workflow/active/ -name "WFS-*" -type d 2>/dev/null | head -1
 ```
 
 ### Step 2: Load Session Data
 ```bash
-cat .workflow/WFS-session/workflow-session.json
+cat .workflow/active/WFS-session/workflow-session.json
 ```
 
 ### Step 3: Scan Task Files
 ```bash
-find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
+find .workflow/active/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
 ```
 
 ### Step 4: Generate Task Status
 ```bash
-cat .workflow/WFS-session/.task/impl-1.json | jq -r '.status'
+cat .workflow/active/WFS-session/.task/impl-1.json | jq -r '.status'
 ```
 
 ### Step 5: Count Task Progress
 ```bash
-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
+find .workflow/active/WFS-session/.task/ -name "*.json" -type f | wc -l
+find .workflow/active/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ### Step 6: Display Overview
@@ -51,74 +189,140 @@ find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 **Progress**: 3/8 tasks completed
 
 ## Active Tasks
-- [⚠️] impl-1: Current task in progress
+- [IN PROGRESS] impl-1: Current task in progress
 - [ ] impl-2: Next pending task
 
 ## Completed Tasks
-- [✅] impl-0: Setup completed
+- [COMPLETED] impl-0: Setup completed
 ```
 
-## Simple Bash Commands
+## Dashboard Mode (HTML Board)
 
-### Basic Operations
-- **Find active session**: `find .workflow/ -name ".active-*" -type f`
-- **Read session info**: `cat .workflow/session/workflow-session.json`
-- **List tasks**: `find .workflow/session/.task/ -name "*.json" -type f`
-- **Check task status**: `cat task.json | jq -r '.status'`
-- **Count completed**: `find .summaries/ -name "*.md" -type f | wc -l`
-
-### Task Status Check
-- **pending**: Not started yet
-- **active**: Currently in progress
-- **completed**: Finished with summary
-- **blocked**: Waiting for dependencies
-
-### Validation Commands
+### Step 1: Check for --dashboard flag
 ```bash
-# Check session exists
-test -f .workflow/.active-* && echo "Session active"
-
-# Validate task files
-for f in .workflow/session/.task/*.json; do jq empty "$f" && echo "Valid: $f"; done
-
-# Check summaries match
-find .task/ -name "*.json" -type f | wc -l
-find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l
+# If --dashboard flag present → Execute Dashboard Mode
 ```
 
-## Simple Output Format
+### Step 2: Collect Workflow Data
 
-### Default Overview
-```
-Session: WFS-user-auth
-Status: ACTIVE
-Progress: 5/12 tasks
+**Collect Active Sessions**:
+```bash
+# Find all active sessions
+find .workflow/active/ -name "WFS-*" -type d 2>/dev/null
 
-Current: impl-3 (Building API endpoints)
-Next: impl-4 (Adding authentication)
-Completed: impl-1, impl-2
+# For each active session, read metadata and tasks
+for session in $(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null); do
+  cat "$session/workflow-session.json"
+  find "$session/.task/" -name "*.json" -type f 2>/dev/null
+done
 ```
 
-### Task Details
-```
-Task: impl-1
-Title: Build authentication module
-Status: completed
-Agent: code-developer
-Created: 2025-09-15
-Completed: 2025-09-15
-Summary: .summaries/impl-1-summary.md
+**Collect Archived Sessions**:
+```bash
+# Find all archived sessions
+find .workflow/archives/ -name "WFS-*" -type d 2>/dev/null
+
+# Read manifest if exists
+cat .workflow/archives/manifest.json 2>/dev/null
+
+# For each archived session, read metadata
+for archive in $(find .workflow/archives/ -name "WFS-*" -type d 2>/dev/null); do
+  cat "$archive/workflow-session.json" 2>/dev/null
+  # Count completed tasks
+  find "$archive/.task/" -name "*.json" -type f 2>/dev/null | wc -l
+done
 ```
 
-### Validation Results
-```
-✅ Session file valid
-✅ 8 task files found
-✅ 3 summaries found
-⚠️ 5 tasks pending completion
+### Step 3: Process and Structure Data
+
+**Build data structure for dashboard**:
+```javascript
+const dashboardData = {
+  activeSessions: [],
+  archivedSessions: [],
+  generatedAt: new Date().toISOString()
+};
+
+// Process active sessions
+for each active_session in active_sessions:
+  const sessionData = JSON.parse(Read(active_session/workflow-session.json));
+  const tasks = [];
+
+  // Load all tasks for this session
+  for each task_file in find(active_session/.task/*.json):
+    const taskData = JSON.parse(Read(task_file));
+    tasks.push({
+      task_id: taskData.task_id,
+      title: taskData.title,
+      status: taskData.status,
+      type: taskData.type
+    });
+
+  dashboardData.activeSessions.push({
+    session_id: sessionData.session_id,
+    project: sessionData.project,
+    status: sessionData.status,
+    created_at: sessionData.created_at || sessionData.initialized_at,
+    tasks: tasks
+  });
+
+// Process archived sessions
+for each archived_session in archived_sessions:
+  const sessionData = JSON.parse(Read(archived_session/workflow-session.json));
+  const taskCount = bash(find archived_session/.task/*.json | wc -l);
+
+  dashboardData.archivedSessions.push({
+    session_id: sessionData.session_id,
+    project: sessionData.project,
+    archived_at: sessionData.completed_at || sessionData.archived_at,
+    taskCount: parseInt(taskCount),
+    archive_path: archived_session
+  });
 ```
 
-## Related Commands
-- `/workflow:execute` - Uses this for task discovery
-- `/workflow:resume` - Uses this for progress analysis
-- `/workflow:session:status` - Shows session metadata
+### Step 4: Generate HTML from Template
+
+**Load template and inject data**:
+```javascript
+// Read the HTML template
+const template = Read("~/.claude/templates/workflow-dashboard.html");
+
+// Prepare data for injection
+const dataJson = JSON.stringify(dashboardData, null, 2);
+
+// Replace placeholder with actual data
+const htmlContent = template.replace('{{WORKFLOW_DATA}}', dataJson);
+
+// Ensure .workflow directory exists
+bash(mkdir -p .workflow);
+```
+
+### Step 5: Write HTML File
+
+```bash
+# Write the generated HTML to .workflow/dashboard.html
+Write({
+  file_path: ".workflow/dashboard.html",
+  content: htmlContent
+})
+```
+
+### Step 6: Display Success Message
+
+```markdown
+Dashboard generated successfully!
+
+Location: .workflow/dashboard.html
+
+Open in browser:
+  file://$(pwd)/.workflow/dashboard.html
+
+Features:
+- 📊 Active sessions overview
+- 📦 Archived sessions history
+- 🔍 Search and filter
+- 📈 Progress tracking
+- 🎨 Dark/light theme
+
+Refresh data: Re-run /workflow:status --dashboard
+```

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

@@ -1,7 +1,7 @@
 ---
 name: tdd-plan
-description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
-argument-hint: "[--agent] \"feature description\"|file.md"
+description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
+argument-hint: "[--cli-execute] \"feature description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -9,11 +9,24 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Execute 5 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation.
+**This command is a pure orchestrator**: Execute 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
 
 **Execution Modes**:
-- **Manual Mode** (default): Use `/workflow:tools:task-generate-tdd`
-- **Agent Mode** (`--agent`): Use `/workflow:tools:task-generate-tdd --agent`
+- **Agent Mode** (default): Use `/workflow:tools:task-generate-tdd` (autonomous agent-driven)
+- **CLI Mode** (`--cli-execute`): Use `/workflow:tools:task-generate-tdd --cli-execute` (Gemini/Qwen)
+
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
 
 ## Core Rules
 
@@ -21,9 +34,10 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 2. **No Preliminary Analysis**: Do not read files before Phase 1
 3. **Parse Every Output**: Extract required data for next phase
 4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically
-5. **Track Progress**: Update TodoWrite after every phase completion
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 6. **TDD Context**: All descriptions include "TDD:" prefix
-7. **Quality Gate**: Phase 4 conflict resolution (optional, auto-triggered) validates compatibility before task generation
+7. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+8. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 6-Phase Execution (with Conflict Resolution)
 
@@ -56,7 +70,7 @@ TEST_FOCUS: [Test scenarios]
 
 **Parse Output**:
 - Extract: context-package.json path (store as `contextPath`)
-- Typical pattern: `.workflow/[sessionId]/.process/context-package.json`
+- Typical pattern: `.workflow/active/[sessionId]/.process/context-package.json`
 
 **Validation**:
 - Context package path extracted
@@ -77,17 +91,45 @@ TEST_FOCUS: [Test scenarios]
 - Related components and integration points
 - Test framework detection
 
-**Parse**: Extract testContextPath (`.workflow/[sessionId]/.process/test-context-package.json`)
+**Parse**: Extract testContextPath (`.workflow/active/[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
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
-**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4
+<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Phase 3.1: Detect test framework and conventions (test-context-gather)", "status": "in_progress", "activeForm": "Detecting test framework"},
+  {"content": "Phase 3.2: Analyze existing test coverage (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "Phase 3.3: Identify coverage gaps (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
+
+**After Phase 3**: Return to user showing test coverage results, then auto-continue to Phase 4/5 (depending on conflict_risk)
 
 ---
 
@@ -107,13 +149,47 @@ TEST_FOCUS: [Test scenarios]
 - Verify: CONFLICT_RESOLUTION.md file path (if executed)
 
 **Validation**:
-- File `.workflow/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
+- File `.workflow/active/[sessionId]/.process/CONFLICT_RESOLUTION.md` exists (if executed)
 
 **Skip Behavior**:
 - If conflict_risk is "none" or "low", skip directly to Phase 5
 - Display: "No significant conflicts detected, proceeding to TDD task generation"
 
-**TodoWrite**: Mark phase 4 completed (if executed) or skipped, phase 5 in_progress
+<!-- TodoWrite: If conflict_risk ≥ medium, INSERT 3 conflict-resolution tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 4.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
+  {"content": "Phase 4.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
+  {"content": "Phase 4.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** conflict-resolution's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
+  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 **After Phase 4**: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5
 
@@ -129,8 +205,8 @@ TEST_FOCUS: [Test scenarios]
 
 ### Phase 5: TDD Task Generation
 **Command**:
-- Manual: `/workflow:tools:task-generate-tdd --session [sessionId]`
-- Agent: `/workflow:tools:task-generate-tdd --session [sessionId] --agent`
+- Agent Mode (default): `/workflow:tools:task-generate-tdd --session [sessionId]`
+- CLI Mode (`--cli-execute`): `/workflow:tools:task-generate-tdd --session [sessionId] --cli-execute`
 
 **Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
 
@@ -145,6 +221,40 @@ TEST_FOCUS: [Test scenarios]
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
 - Task count ≤10 (compliance with task limit)
 
+<!-- TodoWrite: When task-generate-tdd invoked, INSERT 3 task-generate-tdd tasks -->
+
+**TodoWrite Update (Phase 5 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Phase 5.1: Discovery - analyze TDD requirements (task-generate-tdd)", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
+  {"content": "Phase 5.2: Planning - design Red-Green-Refactor cycles (task-generate-tdd)", "status": "pending", "activeForm": "Designing TDD cycles"},
+  {"content": "Phase 5.3: Output - generate IMPL tasks with internal TDD phases (task-generate-tdd)", "status": "pending", "activeForm": "Generating TDD tasks"},
+  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** task-generate-tdd's 3 tasks. Orchestrator **executes** these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.
+
+**Next Action**: Tasks attached → **Execute Phase 5.1-5.3** sequentially
+
+<!-- TodoWrite: After Phase 5 tasks complete, REMOVE Phase 5.1-5.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 5 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
+  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
+  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
+  {"content": "Execute TDD task generation", "status": "completed", "activeForm": "Executing TDD task generation"},
+  {"content": "Validate TDD structure", "status": "in_progress", "activeForm": "Validating TDD structure"}
+]
+```
+
+**Note**: Phase 5 tasks completed and collapsed to summary. Each generated IMPL task contains complete Red-Green-Refactor cycle internally.
+
 ### Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)
 **Internal validation first, then recommend external verification**
 
@@ -171,20 +281,20 @@ Total tasks: [M] (1 task per simple feature + subtasks for complex features)
 Task breakdown:
 - Simple features: [K] tasks (IMPL-1 to IMPL-K)
 - Complex features: [L] features with [P] subtasks
-- Total task count: [M] (within 10-task limit ✅)
+- Total task count: [M] (within 10-task limit)
 
 Structure:
-- IMPL-1: {Feature 1 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
-- IMPL-2: {Feature 2 Name} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
+- IMPL-2: {Feature 2 Name} (Internal: Red → Green → Refactor)
 - IMPL-3: {Complex Feature} (Container)
-  - IMPL-3.1: {Sub-feature A} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
-  - IMPL-3.2: {Sub-feature B} (Internal: 🔴 Red → 🟢 Green → 🔵 Refactor)
+  - IMPL-3.1: {Sub-feature A} (Internal: Red → Green → Refactor)
+  - IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor)
 [...]
 
 Plans generated:
-- Unified Implementation Plan: .workflow/[sessionId]/IMPL_PLAN.md
+- Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
   (includes TDD Implementation Tasks section with workflow_type: "tdd")
-- Task List: .workflow/[sessionId]/TODO_LIST.md
+- Task List: .workflow/active/[sessionId]/TODO_LIST.md
   (with internal TDD phase indicators)
 
 TDD Configuration:
@@ -192,55 +302,95 @@ TDD Configuration:
 - Green phase includes test-fix cycle (max 3 iterations)
 - Auto-revert on max iterations reached
 
-✅ Recommended Next Steps:
+Recommended Next Steps:
 1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
 2. /workflow:execute --session [sessionId]  # Start TDD execution
 3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
 
-⚠️ Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
+Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
 ```
 
 ## TodoWrite Pattern
 
-```javascript
-// Initialize (Phase 4 added dynamically after Phase 3 if conflict_risk ≥ medium)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
-  // Phase 4 todo added dynamically after Phase 3 if conflict_risk ≥ medium
-  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+**Core Concept**: Dynamic task attachment and collapse for TDD workflow with test coverage analysis and Red-Green-Refactor cycle generation.
 
-// After Phase 3 (if conflict_risk ≥ medium, insert Phase 4 todo)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute conflict resolution", "status": "in_progress", "activeForm": "Executing conflict resolution"},
-  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+### Key Principles
 
-// After Phase 3 (if conflict_risk is none/low, skip Phase 4, go directly to Phase 5)
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 3.1, 3.2, 3.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-// After Phase 4 (if executed), continue to Phase 5
-TodoWrite({todos: [
-  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
-  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
-  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
-  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
-  {"content": "Execute TDD task generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
-  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
-]})
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 3.1-3.3 collapse to "Execute test coverage analysis: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.
+
+### TDD-Specific Features
+
+- **Phase 3**: Test coverage analysis detects existing patterns and gaps
+- **Phase 5**: Generated IMPL tasks contain internal Red-Green-Refactor cycles
+- **Conditional Phase 4**: Conflict resolution only if conflict_risk ≥ medium
+
+
+
+**Note**: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.
+
+## Execution Flow Diagram
+
+```
+TDD Workflow Orchestrator
+│
+├─ Phase 1: Session Discovery
+│  └─ /workflow:session:start --auto
+│     └─ Returns: sessionId
+│
+├─ Phase 2: Context Gathering
+│  └─ /workflow:tools:context-gather
+│     └─ Returns: context-package.json path
+│
+├─ Phase 3: Test Coverage Analysis                    ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-context-gather
+│     ├─ Phase 3.1: Detect test framework
+│     ├─ Phase 3.2: Analyze existing test coverage
+│     └─ Phase 3.3: Identify coverage gaps
+│     └─ Returns: test-context-package.json           ← COLLAPSED
+│
+├─ Phase 4: Conflict Resolution (conditional)
+│  IF conflict_risk ≥ medium:
+│  └─ /workflow:tools:conflict-resolution             ← ATTACHED (3 tasks)
+│     ├─ Phase 4.1: Detect conflicts with CLI
+│     ├─ Phase 4.2: Present conflicts to user
+│     └─ Phase 4.3: Apply resolution strategies
+│     └─ Returns: CONFLICT_RESOLUTION.md              ← COLLAPSED
+│  ELSE:
+│  └─ Skip to Phase 5
+│
+├─ Phase 5: TDD Task Generation                       ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:task-generate-tdd
+│     ├─ Phase 5.1: Discovery - analyze TDD requirements
+│     ├─ Phase 5.2: Planning - design Red-Green-Refactor cycles
+│     └─ Phase 5.3: Output - generate IMPL tasks with internal TDD phases
+│     └─ Returns: IMPL-*.json, IMPL_PLAN.md           ← COLLAPSED
+│        (Each IMPL task contains internal Red-Green-Refactor cycle)
+│
+└─ Phase 6: TDD Structure Validation
+   └─ Internal validation + summary returned
+   └─ Recommend: /workflow:action-plan-verify
+
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
+• TDD-specific: Each generated IMPL task contains complete Red-Green-Refactor cycle
 ```
 
 ## Input Processing
@@ -259,111 +409,22 @@ Convert user input to TDD-structured format:
 - **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.
+**Prerequisite Commands**:
+- None - TDD planning is self-contained (can optionally run brainstorm commands before)
 
-### Key Improvements
+**Called by This Command** (6 phases):
+- `/workflow:session:start` - Phase 1: Create or discover TDD workflow session
+- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase
+- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
+- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
+- `/compact` - Phase 4: Memory optimization (if context approaching limits)
+- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks with agent-driven approach (default, autonomous)
+- `/workflow:tools:task-generate-tdd --cli-execute` - Phase 5: Generate TDD tasks with CLI tools (Gemini/Qwen, when `--cli-execute` flag used)
 
-#### 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 (Optimized) |
-|--------|----------|---------------------|
-| **Phases** | 6 (with test coverage) | 7 (added concept verification) |
-| **Context** | Greenfield assumption | Existing codebase aware |
-| **Task Structure** | 1 feature = 3 tasks (TEST/IMPL/REFACTOR) | 1 feature = 1 task (internal TDD cycle) |
-| **Task Count** | 5 features = 15 tasks | 5 features = 5 tasks (70% reduction) |
-| **Green Phase** | Single implementation | Iterative with fix cycle |
-| **Failure Handling** | Manual intervention | Auto-diagnose + fix + revert |
-| **Test Analysis** | None | Deep coverage analysis |
-| **Feedback Loop** | Post-execution | During Green phase |
-| **Task Management** | High overhead (15 tasks) | Low overhead (5 tasks) |
-| **Execution Efficiency** | Frequent context switching | Continuous context per feature |
-
-### Migration Notes
-
-**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 Implementation Tasks section)
-├── TODO_LIST.md (with internal TDD phase indicators)
-├── .process/
-│   ├── context-package.json
-│   ├── test-context-package.json
-│   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
-│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
-└── .task/
-    ├── IMPL-1.json (Complete TDD task: Red-Green-Refactor internally)
-    ├── IMPL-2.json (Complete TDD task)
-    ├── IMPL-3.json (Complex feature container, if needed)
-    ├── IMPL-3.1.json (Complex feature subtask, if needed)
-    └── IMPL-3.2.json (Complex feature subtask, if needed)
-```
-
-**File Count Comparison**:
-- **Old structure**: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
-- **New structure**: 5 features = 5 task files (IMPL-N × 5)
-- **Complex features**: Add container + subtasks only when necessary
-
-**Configuration Options** (in IMPL tasks):
-- `meta.max_iterations`: Fix attempts (default: 3)
-- `meta.use_codex`: Auto-fix mode (default: false)
+**Follow-up Commands**:
+- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
+- `/workflow:status` - Review TDD task breakdown
+- `/workflow:execute` - Begin TDD implementation
+- `/workflow:tdd-verify` - Post-execution: Verify TDD compliance and generate quality report
 

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

@@ -1,6 +1,6 @@
 ---
 name: tdd-verify
-description: Verify TDD workflow compliance and generate quality report
+description: Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis
 
 argument-hint: "[optional: WFS-session-id]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
@@ -28,7 +28,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
 sessionId = argument
 
 # Else auto-detect active session
-find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
+find .workflow/active/ -name "WFS-*" -type d | head -1 | sed 's/.*\///'
 ```
 
 **Extract**: sessionId
@@ -44,18 +44,18 @@ find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'
 
 ```bash
 # Load all task JSONs
-find .workflow/{sessionId}/.task/ -name '*.json'
+find .workflow/active/{sessionId}/.task/ -name '*.json'
 
 # Extract task IDs
-find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.id' {} \;
+find .workflow/active/{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[]?' {} \;
+find .workflow/active/{sessionId}/.task/ -name 'IMPL-*.json' -exec jq -r '.context.depends_on[]?' {} \;
+find .workflow/active/{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' {} \;
+find .workflow/active/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;
+find .workflow/active/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 ```
 
 **Validation**:
@@ -82,9 +82,9 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 - 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
+- `.workflow/active/{sessionId}/.process/test-results.json` exists
+- `.workflow/active/{sessionId}/.process/coverage-report.json` exists
+- `.workflow/active/{sessionId}/.process/tdd-cycle-report.md` exists
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
@@ -97,7 +97,7 @@ find .workflow/{sessionId}/.task/ -name '*.json' -exec jq -r '.meta.agent' {} \;
 cd project-root && gemini -p "
 PURPOSE: Generate TDD compliance report
 TASK: Analyze TDD workflow execution and generate quality report
-CONTEXT: @{.workflow/{sessionId}/.task/*.json,.workflow/{sessionId}/.summaries/*,.workflow/{sessionId}/.process/tdd-cycle-report.md}
+CONTEXT: @{.workflow/active/{sessionId}/.task/*.json,.workflow/active/{sessionId}/.summaries/*,.workflow/active/{sessionId}/.process/tdd-cycle-report.md}
 EXPECTED:
 - TDD compliance score (0-100)
 - Chain completeness verification
@@ -106,7 +106,7 @@ EXPECTED:
 - 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
+" > .workflow/active/{sessionId}/TDD_COMPLIANCE_REPORT.md
 ```
 
 **Output**: TDD_COMPLIANCE_REPORT.md
@@ -118,14 +118,14 @@ RULES: Focus on TDD best practices and workflow adherence. Be specific about vio
 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)
+[COMPLETE] Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
+[COMPLETE] Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
+[INCOMPLETE] 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
+All TEST tasks produced failing tests
+All IMPL tasks made tests pass
+All REFACTOR tasks maintained green tests
 
 ## Coverage Metrics
 Line Coverage: {percentage}%
@@ -134,7 +134,7 @@ Function Coverage: {percentage}%
 
 ## Compliance Score: {score}/100
 
-Detailed report: .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md
+Detailed report: .workflow/active/{sessionId}/TDD_COMPLIANCE_REPORT.md
 
 Recommendations:
 - Complete missing REFACTOR-3.1 task
@@ -168,7 +168,7 @@ TodoWrite({todos: [
 
 ### Chain Validation Algorithm
 ```
-1. Load all task JSONs from .workflow/{sessionId}/.task/
+1. Load all task JSONs from .workflow/active/{sessionId}/.task/
 2. Extract task IDs and group by feature number
 3. For each feature:
    - Check TEST-N.M exists
@@ -202,7 +202,7 @@ Final Score: Max(0, Base Score - Deductions)
 
 ## Output Files
 ```
-.workflow/{session-id}/
+.workflow/active/{session-id}/
 ├── TDD_COMPLIANCE_REPORT.md     # Comprehensive compliance report ⭐
 └── .process/
     ├── test-results.json         # From tdd-coverage-analysis
@@ -215,8 +215,8 @@ Final Score: Max(0, Base Score - Deductions)
 ### 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 |
+| No active session | No WFS-* directories | Provide session-id explicitly |
+| Multiple active sessions | Multiple WFS-* directories | Provide session-id explicitly |
 | Session not found | Invalid session-id | Check available sessions |
 
 ### Validation Errors
@@ -271,20 +271,20 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 ## Chain Analysis
 
 ### Feature 1: {Feature Name}
-**Status**: ✅ Complete
+**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
+- **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
+**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
+- **Red Phase**: Test created and failed
+- **Green Phase**: Implementation seems over-engineered
+- **Refactor Phase**: Missing
 
 **Issues**:
 - REFACTOR-2.1 task not completed
@@ -306,16 +306,16 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 ## TDD Cycle Validation
 
 ### Red Phase (Write Failing Test)
-- ✅ {N}/{total} features had failing tests initially
-- ⚠️ Feature 3: No evidence of initial test failure
+- {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
+- {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
+- {N}/{total} features completed refactoring
+- Feature 2, 4: Refactoring step skipped
 
 ## Best Practices Assessment
 
@@ -351,8 +351,3 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 {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-cycle-execute.md

@@ -1,6 +1,6 @@
 ---
 name: test-cycle-execute
-description: Execute test-fix workflow with dynamic task generation and iterative fix cycles
+description: Execute test-fix workflow with dynamic task generation and iterative fix cycles until test pass rate >= 95% or max iterations reached. Uses @cli-planning-agent for failure analysis and task generation.
 argument-hint: "[--resume-session=\"session-id\"] [--max-iterations=N]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ---
@@ -10,10 +10,13 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*)
 ## Overview
 Orchestrates dynamic test-fix workflow execution through iterative cycles of testing, analysis, and fixing. **Unlike standard execute, this command dynamically generates intermediate tasks** during execution based on test results and CLI analysis, enabling adaptive problem-solving.
 
-**⚠️ CRITICAL - Orchestrator Boundary**:
+**Quality Gate**: Iterates until test pass rate >= 95% (with criticality assessment) or 100% for full approval.
+
+**CRITICAL - Orchestrator Boundary**:
 - This command is the **ONLY place** where test failures are handled
-- All CLI analysis (Gemini/Qwen), fix task generation (IMPL-fix-N.json), and iteration management happen HERE
-- Agents (@test-fix-agent) only execute single tasks and return results
+- All failure analysis and fix task generation delegated to **@cli-planning-agent**
+- Orchestrator calculates pass rate, assesses criticality, and manages iteration loop
+- @test-fix-agent executes tests and applies fixes, reports results back
 - **Do NOT handle test failures in main workflow or other commands** - always delegate to this orchestrator
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery and continues from interruption point.
@@ -35,46 +38,55 @@ Orchestrates dynamic test-fix workflow execution through iterative cycles of tes
 
 ### Agent Coordination
 - **@code-developer**: Understands requirements, generates implementations
-- **@test-fix-agent**: Executes tests, applies fixes, validates results
-- **CLI Tools (Gemini/Qwen)**: Analyzes failures, suggests fix strategies
+- **@test-fix-agent**: Executes tests, applies fixes, validates results, assigns criticality
+- **@cli-planning-agent**: Executes CLI analysis (Gemini/Qwen), parses results, generates fix task JSONs
 
 ## Core Rules
-1. **Dynamic Task Generation**: Create intermediate fix tasks based on test failures
-2. **Iterative Execution**: Repeat test-fix cycles until success or max iterations
-3. **CLI-Driven Analysis**: Use Gemini/Qwen to analyze failures and plan fixes
-4. **Agent Delegation**: All execution delegated to specialized agents
-5. **Context Accumulation**: Each iteration builds on previous attempt context
-6. **Autonomous Completion**: Continue until all tests pass without user interruption
+1. **Dynamic Task Generation**: Create intermediate fix tasks via @cli-planning-agent based on test failures
+2. **Iterative Execution**: Repeat test-fix cycles until pass rate >= 95% (with criticality assessment) or max iterations
+3. **Pass Rate Threshold**: Target 95%+ pass rate; 100% for full approval; assess criticality for 95-100% range
+4. **Agent-Based Analysis**: Delegate CLI execution and task generation to @cli-planning-agent
+5. **Agent Delegation**: All execution delegated to specialized agents (@cli-planning-agent, @test-fix-agent)
+6. **Context Accumulation**: Each iteration builds on previous attempt context
+7. **Autonomous Completion**: Continue until pass rate >= 95% without user interruption
 
 ## Core Responsibilities
 - **Session Discovery**: Identify test-fix workflow sessions
 - **Task Queue Management**: Maintain dynamic task queue with runtime additions
 - **Test Execution**: Run tests through @test-fix-agent
-- **Failure Analysis**: Use CLI tools to diagnose test failures
-- **Fix Task Generation**: Create intermediate fix tasks dynamically
-- **Iteration Control**: Manage fix cycles with max iteration limits
-- **Context Propagation**: Pass failure context and fix history between iterations
+- **Pass Rate Calculation**: Calculate test pass rate from test-results.json (passed/total * 100)
+- **Criticality Assessment**: Evaluate failure severity using test-results.json criticality field
+- **Threshold Decision**: Determine if pass rate >= 95% with criticality consideration
+- **Failure Analysis Delegation**: Invoke @cli-planning-agent for CLI analysis and task generation
+- **Iteration Control**: Manage fix cycles with max iteration limits (5 default)
+- **Context Propagation**: Pass failure context and fix history to @cli-planning-agent
 - **Progress Tracking**: TodoWrite updates for entire iteration cycle
-- **Session Auto-Complete**: Call `/workflow:session:complete` when all tests pass
+- **Session Auto-Complete**: Call `/workflow:session:complete` when pass rate >= 95% (or 100%)
 
 ## Responsibility Matrix
 
-**⚠️ CRITICAL - Clear division of labor between orchestrator and agents:**
+**CRITICAL - Clear division of labor between orchestrator and agents:**
 
-| Responsibility | test-cycle-execute (Orchestrator) | @test-fix-agent (Executor) |
-|----------------|----------------------------|---------------------------|
-| Manage iteration loop | ✅ Controls loop flow | ❌ Executes single task |
-| Run CLI analysis (Gemini/Qwen) | ✅ Runs between agent tasks | ❌ Not involved |
-| Generate IMPL-fix-N.json | ✅ Creates task files | ❌ Not involved |
-| Run tests | ❌ Delegates to agent | ✅ Executes test command |
-| Apply fixes | ❌ Delegates to agent | ✅ Modifies code |
-| Detect test failures | ✅ Analyzes results and decides next action | ✅ Executes tests and reports outcomes |
-| Add tasks to queue | ✅ Manages queue | ❌ Not involved |
-| Update iteration state | ✅ Maintains overall iteration state | ✅ Updates individual task status only |
+| Responsibility | test-cycle-execute (Orchestrator) | @cli-planning-agent | @test-fix-agent (Executor) |
+|----------------|----------------------------|---------------------|---------------------------|
+| Manage iteration loop | Yes - Controls loop flow | No - Not involved | No - Executes single task |
+| Calculate pass rate | Yes - From test-results.json | No - Not involved | No - Reports test results |
+| Assess criticality | Yes - From test-results.json | No - Not involved | Yes - Assigns criticality in test results |
+| Run CLI analysis (Gemini/Qwen) | No - Delegates to cli-planning-agent | Yes - Executes CLI internally | No - Not involved |
+| Parse CLI output | No - Delegated | Yes - Extracts fix strategy | No - Not involved |
+| Generate IMPL-fix-N.json | No - Delegated | Yes - Creates task files | No - Not involved |
+| Run tests | No - Delegates to agent | No - Not involved | Yes - Executes test command |
+| Apply fixes | No - Delegates to agent | No - Not involved | Yes - Modifies code |
+| Detect test failures | Yes - Analyzes pass rate and decides next action | No - Not involved | Yes - Executes tests and reports outcomes |
+| Add tasks to queue | Yes - Manages queue | No - Returns task ID | No - Not involved |
+| Update iteration state | Yes - Maintains overall iteration state | No - Not involved | Yes - Updates individual task status only |
 
-**Key Principle**: Orchestrator manages the "what" and "when"; agents execute the "how".
+**Key Principles**:
+- Orchestrator manages the "what" (iteration flow, threshold decisions) and "when" (task scheduling)
+- @cli-planning-agent executes the "analysis" (CLI execution, result parsing, task generation)
+- @test-fix-agent executes the "how" (run tests, apply fixes)
 
-**⚠️ ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
+**ENFORCEMENT**: If test failures occur outside this orchestrator, do NOT handle them inline - always call `/workflow:test-cycle-execute` instead.
 
 ## Execution Lifecycle
 
@@ -97,17 +109,29 @@ For each task in queue:
   1. [Orchestrator] Load task JSON and context
   2. [Orchestrator] Determine task type (test-gen, test-fix, fix-iteration)
   3. [Orchestrator] Execute task through appropriate agent
-  4. [Orchestrator] Collect agent results and check exit conditions
-  5. If test failures detected:
-     a. [Orchestrator] Run CLI analysis (Gemini/Qwen)
-     b. [Orchestrator] Generate fix task JSON (IMPL-fix-N.json)
+  4. [Orchestrator] Collect agent results from .process/test-results.json
+  5. [Orchestrator] Calculate test pass rate:
+     a. Parse test-results.json: passRate = (passed / total) * 100
+     b. Assess failure criticality (from test-results.json)
+     c. Evaluate fix effectiveness (NEW):
+        - Compare passRate with previous iteration
+        - If passRate decreased by >10%: REGRESSION detected
+        - If regression: Rollback last fix, skip to next strategy
+  6. [Orchestrator] Make threshold decision:
+     IF passRate === 100%:
+       → SUCCESS: Mark task complete, update TodoWrite, continue
+     ELSE IF passRate >= 95%:
+       → REVIEW: Check failure criticality
+       → If all failures are "low" criticality: PARTIAL SUCCESS (approve with note)
+       → If any "high" or "medium" criticality: Enter fix loop (step 7)
+     ELSE IF passRate < 95%:
+       → FAILED: Enter fix loop (step 7)
+  7. If entering fix loop (pass rate < 95% OR critical failures exist):
+     a. [Orchestrator] Invoke @cli-planning-agent with failure context
+     b. [Agent] Executes CLI analysis + generates IMPL-fix-N.json
      c. [Orchestrator] Insert fix task at front of queue
      d. [Orchestrator] Continue loop
-  6. If test success:
-     a. [Orchestrator] Mark task complete
-     b. [Orchestrator] Update TodoWrite
-     c. [Orchestrator] Continue to next task
-  7. [Orchestrator] Check max iterations limit
+  8. [Orchestrator] Check max iterations limit (abort if exceeded)
 ```
 
 **Note**: The orchestrator controls the loop. Agents execute individual tasks and return results.
@@ -119,33 +143,33 @@ For each task in queue:
 #### Iteration Structure
 ```
 Iteration N (managed by test-cycle-execute orchestrator):
-├── 1. Test Execution
+├── 1. Test Execution & Pass Rate Validation
 │   ├── [Orchestrator] Launch @test-fix-agent with test task
-│   ├── [Agent] Run test suite
-│   ├── [Agent] Collect failures and report back
-│   └── [Orchestrator] Receive failure report
-├── 2. Failure Analysis
-│   ├── [Orchestrator] Run CLI tool (Gemini/Qwen)
-│   ├── [CLI Tool] Analyze error messages and failure context
-│   ├── [CLI Tool] Identify root causes
-│   └── [CLI Tool] Generate fix strategy → saved to iteration-N-analysis.md
-├── 3. Fix Task Generation
-│   ├── [Orchestrator] Parse CLI analysis results
-│   ├── [Orchestrator] Create IMPL-fix-N.json with:
-│   │   ├── meta.agent: "@test-fix-agent"
-│   │   ├── Failure context (content, not just path)
-│   │   └── Fix strategy from CLI analysis
-│   └── [Orchestrator] Insert into task queue (front position)
-├── 4. Fix Execution
-│   ├── [Orchestrator] Launch @test-fix-agent with fix task
-│   ├── [Agent] Load fix strategy from task context
-│   ├── [Agent] Apply fixes to code/tests
+│   ├── [Agent] Run test suite and save results to test-results.json
+│   ├── [Agent] Report completion back to orchestrator
+│   ├── [Orchestrator] Calculate pass rate: (passed / total) * 100
+│   └── [Orchestrator] Assess failure criticality from test-results.json
+├── 2. Failure Analysis & Task Generation (via @cli-planning-agent)
+│   ├── [Orchestrator] Assemble failure context package (tests, errors, pass_rate)
+│   ├── [Orchestrator] Invoke @cli-planning-agent with context
+│   ├── [@cli-planning-agent] Execute CLI tool (Gemini/Qwen) internally
+│   ├── [@cli-planning-agent] Parse CLI output for root causes and fix strategy
+│   ├── [@cli-planning-agent] Generate IMPL-fix-N.json with structured task
+│   ├── [@cli-planning-agent] Save analysis to iteration-N-analysis.md
+│   └── [Orchestrator] Receive task ID and insert into queue (front position)
+├── 3. Fix Execution
+│   ├── [Orchestrator] Launch @test-fix-agent with IMPL-fix-N task
+│   ├── [Agent] Load fix strategy from task.context.fix_strategy
+│   ├── [Agent] Apply surgical fixes to identified files
 │   └── [Agent] Report completion
-└── 5. Re-test
+└── 4. Re-test
     └── [Orchestrator] Return to step 1 with updated code
 ```
 
-**Key**: Orchestrator runs CLI analysis between agent tasks, then generates new fix tasks.
+**Key Changes**:
+- CLI analysis + task generation encapsulated in @cli-planning-agent
+- Pass rate calculation added to test execution step
+- Orchestrator only assembles context and invokes agent
 
 #### Iteration Task JSON Template
 ```json
@@ -185,13 +209,13 @@ Iteration N (managed by test-cycle-execute orchestrator):
     "pre_analysis": [
       {
         "step": "load_failure_context",
-        "command": "Read(.workflow/{session}/.process/iteration-{N-1}-failures.json)",
+        "command": "Read(.workflow/session/{session}/.process/iteration-{N-1}-failures.json)",
         "output_to": "previous_failures",
         "on_error": "skip_optional"
       },
       {
         "step": "load_fix_strategy",
-        "command": "Read(.workflow/{session}/.process/iteration-{N}-strategy.md)",
+        "command": "Read(.workflow/session/{session}/.process/iteration-{N}-strategy.md)",
         "output_to": "fix_strategy",
         "on_error": "fail"
       }
@@ -220,74 +244,167 @@ Iteration N (managed by test-cycle-execute orchestrator):
 }
 ```
 
-### Phase 4: CLI Analysis Integration
+### Phase 4: Agent-Based Failure Analysis & Task Generation
 
-**Orchestrator executes CLI analysis between agent tasks:**
+**Orchestrator delegates CLI analysis and task generation to @cli-planning-agent:**
 
-#### When Test Failures Occur
-1. **[Orchestrator]** Detects failures from agent test execution output
-2. **[Orchestrator]** Collects failure context from `.process/test-results.json` and logs
-3. **[Orchestrator]** Executes Gemini/Qwen CLI tool with failure context
-4. **[Orchestrator]** Interprets CLI tool output to extract fix strategy
-5. **[Orchestrator]** Saves analysis to `.process/iteration-N-analysis.md`
-6. **[Orchestrator]** Generates `IMPL-fix-N.json` with strategy content (not just path)
+#### When Test Failures Occur (Pass Rate < 95% OR Critical Failures)
+1. **[Orchestrator]** Detects failures from test-results.json
+2. **[Orchestrator]** Check for repeated failures (NEW):
+   - Compare failed_tests with previous 2 iterations
+   - If same test failed 3 times consecutively: Mark as "stuck"
+   - If >50% of failures are "stuck": Switch analysis strategy or abort
+3. **[Orchestrator]** Extracts failure context:
+   - Failed tests with criticality assessment
+   - Error messages and stack traces
+   - Current pass rate
+   - Previous iteration attempts (if any)
+   - Stuck test markers (NEW)
+4. **[Orchestrator]** Assembles context package for @cli-planning-agent
+5. **[Orchestrator]** Invokes @cli-planning-agent via Task tool
+6. **[@cli-planning-agent]** Executes internally:
+   - Runs Gemini/Qwen CLI analysis with bug diagnosis template
+   - Parses CLI output to extract root causes and fix strategy
+   - Generates `IMPL-fix-N.json` with structured task definition
+   - Saves analysis report to `.process/iteration-N-analysis.md`
+   - Saves raw CLI output to `.process/iteration-N-cli-output.txt`
+7. **[Orchestrator]** Receives task ID from agent and inserts into queue
 
-**Note**: The orchestrator executes CLI analysis tools and processes their output. CLI tools provide analysis, orchestrator manages the workflow.
+**Key Change**: CLI execution + result parsing + task generation are now encapsulated in @cli-planning-agent, simplifying orchestrator logic.
 
-#### CLI Analysis Command (executed by orchestrator)
-```bash
-cd {project_root} && gemini -p "
-PURPOSE: Analyze test failures and generate fix strategy
-TASK: Review test failures and identify root causes
-MODE: analysis
-CONTEXT: @test files @ implementation files
+#### Agent Invocation Pattern (executed by orchestrator)
+```javascript
+Task(
+  subagent_type="cli-planning-agent",
+  description=`Analyze test failures and generate fix task (iteration ${currentIteration})`,
+  prompt=`
+    ## Task Objective
+    Analyze test failures and generate structured fix task JSON for iteration ${currentIteration}
 
-[Test failure context and requirements...]
+    ## MANDATORY FIRST STEPS
+    1. Read test results: {session.test_results_path}
+    2. Read test output: {session.test_output_path}
+    3. Read iteration state: {session.iteration_state_path}
+    4. Read fix history (if exists): {session.fix_history_path}
 
-EXPECTED: Detailed fix strategy in markdown format
-RULES: Focus on minimal changes, avoid over-engineering
-"
+    ## Session Paths
+    - Workflow Dir: {session.workflow_dir}
+    - Test Results: {session.test_results_path}
+    - Test Output: {session.test_output_path}
+    - Iteration State: {session.iteration_state_path}
+    - Fix History: {session.fix_history_path}
+    - Task Output Dir: {session.task_dir}
+    - Analysis Output: {session.process_dir}/iteration-${currentIteration}-analysis.md
+    - CLI Output: {session.process_dir}/iteration-${currentIteration}-cli-output.txt
+
+    ## Context Metadata
+    - Session ID: ${sessionId}
+    - Current Iteration: ${currentIteration}
+    - Max Iterations: ${maxIterations}
+    - Current Pass Rate: ${passRate}%
+
+    ## CLI Configuration
+    - Tool: gemini (fallback: qwen)
+    - Model: gemini-3-pro-preview-11-2025
+    - Template: 01-diagnose-bug-root-cause.txt
+    - Timeout: 2400000ms
+
+    ## Expected Deliverables
+    1. Task JSON file: {session.task_dir}/IMPL-fix-${currentIteration}.json
+    2. Analysis report: {session.process_dir}/iteration-${currentIteration}-analysis.md
+    3. CLI raw output: {session.process_dir}/iteration-${currentIteration}-cli-output.txt
+    4. Return task ID to orchestrator
+
+    ## Quality Standards
+    - Fix strategy must include specific modification points (file:function:lines)
+    - Analysis must identify root causes, not just symptoms
+    - Task JSON must be valid and complete with all required fields
+    - All deliverables saved to specified paths
+
+    ## Success Criteria
+    Generate valid IMPL-fix-${currentIteration}.json with:
+    - Concrete fix strategy with modification points
+    - Root cause analysis from CLI tool
+    - All required task JSON fields (id, title, status, meta, context, flow_control)
+    - Return task ID for orchestrator to queue
+  `
+)
 ```
 
-#### Analysis Output Structure
+#### Agent Response Format
+**Agent must return structured response with deliverable paths:**
+
+```javascript
+{
+  "status": "success",
+  "task_id": "IMPL-fix-${iteration}",
+  "deliverables": {
+    "task_json": ".workflow/${session}/.task/IMPL-fix-${iteration}.json",
+    "analysis_report": ".workflow/${session}/.process/iteration-${iteration}-analysis.md",
+    "cli_output": ".workflow/${session}/.process/iteration-${iteration}-cli-output.txt"
+  },
+  "summary": {
+    "root_causes": ["Authentication token validation missing", "Null check missing"],
+    "modification_points": [
+      "src/auth/client.ts:sendRequest:45-50",
+      "src/validators/user.ts:validateUser:23-25"
+    ],
+    "estimated_complexity": "low",
+    "expected_pass_rate_improvement": "85% → 95%"
+  }
+}
+```
+
+**Orchestrator validates all deliverable paths exist before proceeding.**
+
+#### Generated Analysis Report Structure
+The @cli-planning-agent generates `.process/iteration-N-analysis.md`:
+
 ```markdown
-# Test Failure Analysis - Iteration {N}
+---
+iteration: N
+analysis_type: test-failure
+cli_tool: gemini
+model: gemini-3-pro-preview-11-2025
+timestamp: 2025-11-10T10:00:00Z
+pass_rate: 85.0%
+---
+
+# Test Failure Analysis - Iteration N
+
+## Summary
+- **Failed Tests**: 2
+- **Pass Rate**: 85.0% (Target: 95%+)
+- **Root Causes Identified**: 2
+- **Modification Points**: 2
+
+## Failed Tests Details
+
+### test_auth_flow
+- **Error**: Expected 200, got 401
+- **File**: tests/test_auth.test.ts:45
+- **Criticality**: high
+
+### test_data_validation
+- **Error**: TypeError: Cannot read property 'name' of undefined
+- **File**: tests/test_validators.test.ts:23
+- **Criticality**: medium
 
 ## Root Cause Analysis
-1. **Test: test_auth_flow**
-   - Error: `Expected 200, got 401`
-   - Root Cause: Missing authentication token in request headers
-   - Affected Code: `src/auth/client.ts:45`
-
-2. **Test: test_data_validation**
-   - Error: `TypeError: Cannot read property 'name' of undefined`
-   - Root Cause: Null check missing before property access
-   - Affected Code: `src/validators/user.ts:23`
+[CLI output: 根本原因分析 section]
 
 ## Fix Strategy
+[CLI output: 详细修复建议 section]
 
-### Priority 1: Authentication Issue
-- **File**: src/auth/client.ts
-- **Function**: sendRequest (line 45)
-- **Change**: Add token header: `headers['Authorization'] = 'Bearer ' + token`
-- **Verification**: Run test_auth_flow
+## Modification Points
+- `src/auth/client.ts:sendRequest:45-50` - Add authentication token header
+- `src/validators/user.ts:validateUser:23-25` - Add null check before property access
 
-### Priority 2: Null Check
-- **File**: src/validators/user.ts
-- **Function**: validateUser (line 23)
-- **Change**: Add check: `if (!user?.name) return false`
-- **Verification**: Run test_data_validation
+## Expected Outcome
+[CLI output: 验证建议 section]
 
-## Verification Plan
-1. Apply fixes in order
-2. Run test suite after each fix
-3. Check for regressions
-4. Validate all tests pass
-
-## Risk Assessment
-- Low risk: Changes are surgical and isolated
-- No breaking changes expected
-- Existing tests should remain green
+## CLI Raw Output
+See: `.process/iteration-N-cli-output.txt`
 ```
 
 ### Phase 5: Task Queue Management
@@ -321,27 +438,56 @@ After IMPL-fix-2 execution (success):
 #### Success Conditions
 - All initial tasks completed
 - All generated fix tasks completed
-- All tests passing
+- **Test pass rate === 100%** (all tests passing)
 - No pending tasks in queue
 
+#### Partial Success Conditions (NEW)
+- All initial tasks completed
+- Test pass rate >= 95% AND < 100%
+- All failures are "low" criticality (flaky tests, env-specific issues)
+- **Automatic Approval with Warning**: System auto-approves but marks session with review flag
+- Note: Generate completion summary with detailed warnings about low-criticality failures
+
 #### Completion Steps
 1. **Final Validation**: Run full test suite one more time
-2. **Update Session State**: Mark all tasks completed
-3. **Generate Summary**: Create session completion summary
-4. **Update TodoWrite**: Mark all items completed
-5. **Auto-Complete**: Call `/workflow:session:complete`
+2. **Calculate Final Pass Rate**: Parse test-results.json
+3. **Assess Completion Status**:
+   - If pass_rate === 100% → Full Success
+   - If pass_rate >= 95% + all "low" criticality → Partial Success (add review note)
+   - If pass_rate >= 95% + any "high"/"medium" criticality → Continue iteration
+   - If pass_rate < 95% → Failure
+4. **Update Session State**: Mark all tasks completed (or blocked if failure)
+5. **Generate Summary**: Create session completion summary with pass rate metrics
+6. **Update TodoWrite**: Mark all items completed
+7. **Auto-Complete**: Call `/workflow:session:complete` (for Full or Partial Success)
 
 #### Failure Conditions
-- Max iterations reached without success
-- Unrecoverable test failures
+- Max iterations (5) reached without achieving 95% pass rate
+- **Test pass rate < 95% after max iterations** (NEW)
+- Pass rate >= 95% but critical failures exist and max iterations reached
+- Unrecoverable test failures (infinite loop detection)
 - Agent execution errors
 
 #### Failure Handling
-1. **Document State**: Save current iteration context
-2. **Generate Report**: Create failure analysis report
-3. **Preserve Context**: Keep all iteration logs
+1. **Document State**: Save current iteration context with final pass rate
+2. **Generate Failure Report**: Include:
+   - Final pass rate (e.g., "85% after 5 iterations")
+   - Remaining failures with criticality assessment
+   - Iteration history and attempted fixes
+   - CLI analysis quality (normal/degraded)
+   - Recommendations for manual intervention
+3. **Preserve Context**: Keep all iteration logs and analysis reports
 4. **Mark Blocked**: Update task status to blocked
-5. **Return Control**: Return to user with detailed report
+5. **Return Control**: Return to user with detailed failure report
+
+#### Degraded Analysis Handling (NEW)
+When @cli-planning-agent returns `status: "degraded"` (both Gemini and Qwen failed):
+1. **Log Warning**: Record CLI analysis failure in iteration-state.json
+2. **Assess Risk**: Check if degraded analysis is acceptable:
+   - If iteration < 3 AND pass_rate improved: Accept degraded analysis, continue
+   - If iteration >= 3 OR pass_rate stagnant: Skip iteration, mark as blocked
+3. **User Notification**: Include CLI failure in completion summary
+4. **Fallback Strategy**: Use basic pattern matching from fix-history.json
 
 ## TodoWrite Coordination
 
@@ -385,59 +531,60 @@ TodoWrite({
 4. **Iteration Complete**: Mark iteration item completed
 5. **All Complete**: Mark parent task completed
 
-## Agent Context Package
+## Agent Context Loading
 
-**Generated by test-cycle-execute orchestrator before launching agents.**
+**Orchestrator provides file paths, agents load content themselves.**
 
-The orchestrator assembles this context package from:
-- Task JSON file (IMPL-*.json)
-- Iteration state files
-- Test results and failure context
-- Session metadata
+### Path References Provided to Agents
 
-This package is passed to agents via the Task tool's prompt context.
+**Orchestrator passes these paths via Task tool prompt:**
 
-### Enhanced Context for Test-Fix Agent
-```json
+```javascript
 {
-  "task": { /* IMPL-fix-N.json */ },
-  "iteration_context": {
-    "current_iteration": N,
-    "max_iterations": 5,
-    "previous_attempts": [
-      {
-        "iteration": N-1,
-        "failures": ["test1", "test2"],
-        "fixes_attempted": ["fix1", "fix2"],
-        "result": "partial_success"
-      }
-    ],
-    "failure_analysis": {
-      "source": "gemini_cli",
-      "analysis_file": ".process/iteration-N-analysis.md",
-      "fix_strategy": { /* from CLI */ }
-    }
-  },
-  "test_context": {
-    "test_framework": "jest|pytest|...",
-    "test_files": ["path/to/test1.test.ts"],
-    "test_command": "npm test",
-    "coverage_target": 80
-  },
-  "session": {
-    "workflow_dir": ".workflow/WFS-test-{session}/",
-    "iteration_state_file": ".process/iteration-state.json",
-    "test_results_file": ".process/test-results.json",
-    "fix_history_file": ".process/fix-history.json"
-  }
+  // Primary Task Definition
+  "task_json_path": ".workflow/active/WFS-test-{session}/.task/IMPL-fix-N.json",
+
+  // Iteration Context Paths
+  "iteration_state_path": ".workflow/active/WFS-test-{session}/.process/iteration-state.json",
+  "fix_history_path": ".workflow/active/WFS-test-{session}/.process/fix-history.json",
+
+  // Test Context Paths
+  "test_results_path": ".workflow/active/WFS-test-{session}/.process/test-results.json",
+  "test_output_path": ".workflow/active/WFS-test-{session}/.process/test-output.log",
+  "test_context_path": ".workflow/active/WFS-test-{session}/.process/TEST_ANALYSIS_RESULTS.md",
+
+  // Analysis & Strategy Paths (for fix-iteration tasks)
+  "analysis_path": ".workflow/active/WFS-test-{session}/.process/iteration-N-analysis.md",
+  "cli_output_path": ".workflow/active/WFS-test-{session}/.process/iteration-N-cli-output.txt",
+
+  // Session Management Paths
+  "workflow_dir": ".workflow/active/WFS-test-{session}/",
+  "summaries_dir": ".workflow/active/WFS-test-{session}/.summaries/",
+  "todo_list_path": ".workflow/active/WFS-test-{session}/TODO_LIST.md",
+
+  // Metadata (simple values, not file content)
+  "session_id": "WFS-test-{session}",
+  "current_iteration": N,
+  "max_iterations": 5
 }
 ```
 
+### Agent Loading Sequence
+
+**Agents must load files in this order:**
+
+1. **Task JSON** (`task_json_path`) - Get task definition, requirements, fix strategy
+2. **Iteration State** (`iteration_state_path`) - Understand current iteration context
+3. **Test Results** (`test_results_path`) - Analyze current test status
+4. **Test Output** (`test_output_path`) - Review detailed test execution logs
+5. **Analysis Report** (`analysis_path`, for fix tasks) - Load CLI-generated fix strategy
+6. **Fix History** (`fix_history_path`) - Review previous fix attempts to avoid repetition
+
 ## File Structure
 
 ### Test-Fix Session Files
 ```
-.workflow/WFS-test-{session}/
+.workflow/active/WFS-test-{session}/
 ├── workflow-session.json          # Session metadata with workflow_type
 ├── IMPL_PLAN.md                   # Test plan
 ├── TODO_LIST.md                   # Progress tracking
@@ -498,77 +645,66 @@ This package is passed to agents via the Task tool's prompt context.
 
 ## Agent Prompt Template
 
-**Unified template for all agent tasks (orchestrator invokes with Task tool):**
+**Dynamic Generation**: Before agent invocation, orchestrator reads task JSON and extracts key requirements.
 
 ```bash
 Task(subagent_type="{meta.agent}",
-     prompt="**TASK EXECUTION: {task.title}**
+     prompt="Execute task: {task.title}
 
-     ## STEP 1: Load Complete Task JSON
-     **MANDATORY**: First load the complete task JSON from: {session.task_json_path}
+     {[FLOW_CONTROL]}
 
-     cat {session.task_json_path}
+     **Task Objectives** (from task JSON):
+     {task.context.requirements}
 
-     **CRITICAL**: Validate all required fields present
+     **Expected Deliverables**:
+     - For test-gen: Test files in target directories, test coverage report
+     - For test-fix: Test execution results saved to test-results.json, test-output.log
+     - For test-fix-iteration: Fixed code files, updated test results, iteration summary
 
-     ## STEP 2: Task Context (From Loaded JSON)
-     **ID**: {task.id}
-     **Type**: {task.meta.type}
-     **Agent**: {task.meta.agent}
+     **Quality Standards**:
+     - All tests must execute without errors
+     - Test results must be saved in structured JSON format
+     - All deliverables must be saved to specified paths
+     - Task status must be updated in task JSON
 
-     ## STEP 3: Execute Task Based on Type
+     **MANDATORY FIRST STEPS**:
+     1. Read complete task JSON: {session.task_json_path}
+     2. Load iteration state (if applicable): {session.iteration_state_path}
+     3. Load test context: {session.test_context_path}
 
-     ### For test-gen (IMPL-001):
-     - Generate tests based on TEST_ANALYSIS_RESULTS.md
-     - Follow test framework conventions
-     - Create test files in target_files
+     Follow complete execution guidelines in @.claude/agents/{meta.agent}.md
 
-     ### For test-fix (IMPL-002):
-     - Run test suite: {test_command}
-     - Collect results to .process/test-results.json
-     - Report results to orchestrator (do NOT analyze failures)
-     - Orchestrator will handle failure detection and iteration decisions
-     - If success: Mark complete
+     **Session Paths** (use these for all file operations):
+     - Workflow Dir: {session.workflow_dir}
+     - Task JSON: {session.task_json_path}
+     - TODO List: {session.todo_list_path}
+     - Summaries Dir: {session.summaries_dir}
+     - Test Results: {session.test_results_path}
+     - Test Output Log: {session.test_output_path}
+     - Iteration State: {session.iteration_state_path}
+     - Fix History: {session.fix_history_path}
 
-     ### For test-fix-iteration (IMPL-fix-N):
-     - Load fix strategy from context.fix_strategy (CONTENT, not path)
-     - Apply surgical fixes to identified files
-     - Return results to orchestrator
-     - Do NOT run tests independently - orchestrator manages all test execution
-     - Do NOT handle failures - orchestrator analyzes and decides next iteration
+     **Critical Rules**:
+     - For test-fix tasks: Run tests and save results, do NOT analyze failures
+     - For fix-iteration tasks: Apply fixes from task JSON, do NOT run tests independently
+     - Orchestrator manages iteration loop and failure analysis
+     - Return results to orchestrator for next-step decisions
 
-     ## STEP 4: Implementation Context (From JSON)
-     **Requirements**: {context.requirements}
-     **Fix Strategy**: {context.fix_strategy} (full content provided in task JSON)
-     **Failure Context**: {context.failure_context}
-     **Iteration History**: {context.inherited.iteration_history}
-
-     ## STEP 5: Flow Control Execution
-     If flow_control.pre_analysis exists, execute steps sequentially
-
-     ## STEP 6: Agent Completion
-     1. Execute task following implementation_approach
-     2. Update task status in JSON
-     3. Update TODO_LIST.md
-     4. Generate summary in .summaries/
-     5. **CRITICAL**: Save results for orchestrator to analyze
-
-     **Output Requirements**:
-     - test-results.json: Structured test results
-     - test-output.log: Full test output
-     - iteration-state.json: Current iteration state (if applicable)
-     - task-summary.md: Completion summary
-
-     **Return to Orchestrator**: Agent completes and returns. Orchestrator decides next action.
-     "),
-     description="Execute {task.type} task with JSON validation")
+     **Success Criteria**:
+     - Complete all task objectives as specified in task JSON
+     - Deliver all required outputs to specified paths
+     - Update task status and TODO_LIST.md
+     - Generate completion summary in .summaries/
+     ",
+     description="Executing: {task.title}")
 ```
 
-**Key Points**:
-- Agent executes single task and returns
-- Orchestrator analyzes results and decides next step
-- Fix strategy content (not path) embedded in task JSON by orchestrator
-- Agent does not manage iteration loop
+**Key Changes from Previous Version**:
+1. **Paths over Content**: Provide JSON paths for agent to read, not embedded content
+2. **MANDATORY FIRST STEPS**: Explicit requirement to load task JSON and context
+3. **Complete Session Paths**: All file paths provided for agent operations
+4. **Emphasized Deliverables**: Clear deliverable requirements per task type
+5. **Simplified Structure**: Removed type-specific instructions (agent reads from JSON)
 
 ## Error Handling & Recovery
 
@@ -586,7 +722,7 @@ Task(subagent_type="{meta.agent}",
 #### Resume from Interruption
 ```bash
 # Load iteration state
-iteration_state=$(cat .workflow/{session}/.process/iteration-state.json)
+iteration_state=$(cat .workflow/session/{session}/.process/iteration-state.json)
 current_iteration=$(jq -r '.current_iteration' <<< "$iteration_state")
 
 # Determine resume point
@@ -605,7 +741,7 @@ fi
 git revert HEAD
 
 # Remove failed fix task
-rm .workflow/{session}/.task/IMPL-fix-{N}.json
+rm .workflow/session/{session}/.task/IMPL-fix-{N}.json
 
 # Restore iteration state
 jq '.current_iteration -= 1' iteration-state.json > temp.json
@@ -653,10 +789,3 @@ mv temp.json iteration-state.json
 5. **Verify No Regressions**: Check all tests pass, not just previously failing ones
 6. **Preserve Context**: All iteration artifacts saved for debugging
 
-## Related Commands
-
-- `/workflow:test-fix-gen` - Planning phase (creates initial tasks)
-- `/workflow:execute` - Standard workflow execution (no dynamic iteration)
-- `/workflow:status` - Check progress and iteration state
-- `/workflow:session:complete` - Mark session complete (auto-called on success)
-- `/task:create` - Manually create additional tasks if needed

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

@@ -1,6 +1,6 @@
 ---
 name: test-fix-gen
-description: Create independent test-fix workflow session from existing implementation (session or prompt-based)
+description: Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning
 argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -13,7 +13,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 This command creates an independent test-fix workflow session for existing code. It orchestrates a 5-phase process to analyze implementation, generate test requirements, and create executable test generation and fix tasks.
 
-**⚠️ CRITICAL - Command Scope**:
+**CRITICAL - Command Scope**:
 - **This command ONLY generates task JSON files** (IMPL-001.json, IMPL-002.json)
 - **Does NOT execute tests or apply fixes** - all execution happens in separate orchestrator
 - **Must call `/workflow:test-cycle-execute`** after this command to actually run tests and fixes
@@ -58,6 +58,19 @@ This command is a **pure planning coordinator**:
 - Creates independent test workflow session
 - **All execution delegated to `/workflow:test-cycle-execute`**
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 ---
 
 ## Usage
@@ -128,9 +141,11 @@ This command is a **pure planning coordinator**:
 3. **Parse Every Output**: Extract required data from each phase for next phase
 4. **Sequential Execution**: Each phase depends on previous phase's output
 5. **Complete All Phases**: Do not return until Phase 5 completes
-6. **Track Progress**: Update TodoWrite after every phase
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 7. **Automatic Detection**: Mode auto-detected from input pattern
 8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+9. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+10. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ### 5-Phase Execution
 
@@ -202,9 +217,25 @@ This command is a **pure planning coordinator**:
 **Expected Behavior**:
 - Use Gemini to analyze coverage gaps and implementation
 - Study existing test patterns and conventions
-- Generate test requirements for missing test files
-- Design test generation strategy
-- Generate `TEST_ANALYSIS_RESULTS.md`
+- Generate **multi-layered test requirements** (L0: Static Analysis, L1: Unit, L2: Integration, L3: E2E)
+- Design test generation strategy with quality assurance criteria
+- Generate `TEST_ANALYSIS_RESULTS.md` with structured test layers
+
+**Enhanced Test Requirements**:
+For each targeted file/function, Gemini MUST generate:
+1. **L0: Static Analysis Requirements**:
+   - Linting rules to enforce (ESLint, Prettier)
+   - Type checking requirements (TypeScript)
+   - Anti-pattern detection rules
+2. **L1: Unit Test Requirements**:
+   - Happy path scenarios (valid inputs → expected outputs)
+   - Negative path scenarios (invalid inputs → error handling)
+   - Edge cases (null, undefined, 0, empty strings/arrays)
+3. **L2: Integration Test Requirements**:
+   - Successful component interactions
+   - Failure handling scenarios (service unavailable, timeout)
+4. **L3: E2E Test Requirements** (if applicable):
+   - Key user journeys from start to finish
 
 **Parse Output**:
 - Verify `.workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md` created
@@ -213,9 +244,18 @@ This command is a **pure planning coordinator**:
 - TEST_ANALYSIS_RESULTS.md exists with complete sections:
   - Coverage Assessment
   - Test Framework & Conventions
-  - Test Requirements by File
+  - **Multi-Layered Test Plan** (NEW):
+    - L0: Static Analysis Plan
+    - L1: Unit Test Plan
+    - L2: Integration Test Plan
+    - L3: E2E Test Plan (if applicable)
+  - Test Requirements by File (with layer annotations)
   - Test Generation Strategy
   - Implementation Targets
+  - Quality Assurance Criteria (NEW):
+    - Minimum coverage thresholds
+    - Required test types per function
+    - Acceptance criteria for test quality
   - Success Criteria
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
@@ -232,16 +272,18 @@ This command is a **pure planning coordinator**:
 - `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
 
 **Expected Behavior**:
-- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
-- Generate **minimum 2 task JSON files** (expandable based on complexity):
+- Parse TEST_ANALYSIS_RESULTS.md from Phase 3 (multi-layered test plan)
+- Generate **minimum 3 task JSON files** (expandable based on complexity):
   - **IMPL-001.json**: Test Understanding & Generation (`@code-developer`)
+  - **IMPL-001.5-review.json**: Test Quality Gate (`@test-fix-agent`) ← **NEW**
   - **IMPL-002.json**: Test Execution & Fix Cycle (`@test-fix-agent`)
   - **IMPL-003+**: Additional tasks if needed for complex projects
-- Generate `IMPL_PLAN.md` with test strategy
+- Generate `IMPL_PLAN.md` with multi-layered test strategy
 - Generate `TODO_LIST.md` with task checklist
 
 **Parse Output**:
 - Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.5-review.json` exists ← **NEW**
 - Verify `.workflow/[testSessionId]/.task/IMPL-002.json` exists
 - Verify additional `.task/IMPL-*.json` if applicable
 - Verify `IMPL_PLAN.md` and `TODO_LIST.md` created
@@ -262,11 +304,16 @@ Test Session: [testSessionId]
 
 Tasks Created:
 - IMPL-001: Test Understanding & Generation (@code-developer)
+- IMPL-001.5: Test Quality Gate - Static Analysis & Coverage (@test-fix-agent) ← NEW
 - IMPL-002: Test Execution & Fix Cycle (@test-fix-agent)
 [- IMPL-003+: Additional tasks if applicable]
 
+Test Strategy: Multi-Layered (L0: Static, L1: Unit, L2: Integration, L3: E2E)
 Test Framework: [detected framework]
 Test Files to Generate: [count]
+Quality Thresholds:
+- Minimum Coverage: 80%
+- Static Analysis: Zero critical issues
 Max Fix Iterations: 5
 Fix Mode: [Manual|Codex Automated]
 
@@ -274,69 +321,143 @@ Review artifacts:
 - Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 
-⚠️ CRITICAL - Next Steps:
-1. Review IMPL_PLAN.md
+CRITICAL - Next Steps:
+1. Review IMPL_PLAN.md (now includes multi-layered test strategy)
 2. **MUST execute: /workflow:test-cycle-execute**
    - This command only generated task JSON files
    - Test execution and fix iterations happen in test-cycle-execute
    - Do NOT attempt to run tests or fixes in main workflow
+3. IMPL-001.5 will validate test quality before fix cycle begins
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
-**⚠️ BOUNDARY NOTE**:
+**BOUNDARY NOTE**:
 - Command completes here - only task JSON files generated
 - All test execution, failure detection, CLI analysis, fix generation happens in `/workflow:test-cycle-execute`
 - This command does NOT handle test failures or apply fixes
 
 ---
 
-### TodoWrite Progress Tracking
+### TodoWrite Pattern
 
-Track all 5 phases:
+**Core Concept**: Dynamic task attachment and collapse for test-fix-gen workflow with dual-mode support (Session Mode and Prompt Mode).
 
-```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"}
-]})
-```
+#### Key Principles
+
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` (Session Mode) or `/workflow:tools:context-gather` (Prompt Mode) attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
+
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Gather test coverage context: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED with mode-specific context gathering) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+#### Test-Fix-Gen Specific Features
+
+- **Dual-Mode Support**: Automatic mode detection based on input pattern
+  - **Session Mode**: Input pattern `WFS-*` → uses `test-context-gather` for cross-session context
+  - **Prompt Mode**: Text or file path → uses `context-gather` for direct codebase analysis
+- **Phase 2**: Mode-specific context gathering (session summaries vs codebase analysis)
+- **Phase 3**: Multi-layered test requirements analysis (L0: Static, L1: Unit, L2: Integration, L3: E2E)
+- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
+- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
 
-Update status to `in_progress` when starting each phase, `completed` when done.
 
 ---
 
 ## Task Specifications
 
-Generates minimum 2 tasks (expandable for complex projects):
+Generates minimum 3 tasks (expandable for complex projects):
 
 ### IMPL-001: Test Understanding & Generation
 
 **Agent**: `@code-developer`
 
-**Purpose**: Understand source implementation and generate test files
+**Purpose**: Understand source implementation and generate test files following multi-layered test strategy
 
 **Task Configuration**:
 - Task ID: `IMPL-001`
 - `meta.type: "test-gen"`
 - `meta.agent: "@code-developer"`
-- `context.requirements`: Understand source implementation and generate tests
+- `context.requirements`: Understand source implementation and generate tests across all layers (L0-L3)
 - `flow_control.target_files`: Test files to create from TEST_ANALYSIS_RESULTS.md section 5
 
 **Execution Flow**:
 1. **Understand Phase**:
    - Load TEST_ANALYSIS_RESULTS.md and test context
    - Understand source code implementation patterns
-   - Analyze test requirements and conventions
-   - Identify test scenarios and edge cases
+   - Analyze multi-layered test requirements (L0: Static, L1: Unit, L2: Integration, L3: E2E)
+   - Identify test scenarios, edge cases, and error paths
 2. **Generation Phase**:
-   - Generate test files following existing patterns
-   - Ensure test coverage aligns with requirements
+   - Generate L1 unit test files following existing patterns
+   - Generate L2 integration test files (if applicable)
+   - Generate L3 E2E test files (if applicable)
+   - Ensure test coverage aligns with multi-layered requirements
+   - Include both positive and negative test cases
 3. **Verification Phase**:
    - Verify test completeness and correctness
+   - Ensure each test has meaningful assertions
+   - Check for test anti-patterns (tests without assertions, overly broad mocks)
+
+### IMPL-001.5: Test Quality Gate ← **NEW**
+
+**Agent**: `@test-fix-agent`
+
+**Purpose**: Validate test quality before entering fix cycle - prevent "hollow tests" from becoming the source of truth
+
+**Task Configuration**:
+- Task ID: `IMPL-001.5-review`
+- `meta.type: "test-quality-review"`
+- `meta.agent: "@test-fix-agent"`
+- `context.depends_on: ["IMPL-001"]`
+- `context.requirements`: Validate generated tests meet quality standards
+- `context.quality_config`: Load from `.claude/workflows/test-quality-config.json`
+
+**Execution Flow**:
+1. **L0: Static Analysis**:
+   - Run linting on test files (ESLint, Prettier)
+   - Check for test anti-patterns:
+     - Tests without assertions (`expect()` missing)
+     - Empty test bodies (`it('should...', () => {})`)
+     - Disabled tests without justification (`it.skip`, `xit`)
+   - Verify TypeScript type safety (if applicable)
+2. **Coverage Analysis**:
+   - Run coverage analysis on generated tests
+   - Calculate coverage percentage for target source files
+   - Identify uncovered branches and edge cases
+3. **Test Quality Metrics**:
+   - Verify minimum coverage threshold met (default: 80%)
+   - Verify all critical functions have negative test cases
+   - Verify integration tests cover key component interactions
+4. **Quality Gate Decision**:
+   - **PASS**: Coverage ≥ 80%, zero critical anti-patterns → Proceed to IMPL-002
+   - **FAIL**: Coverage < 80% OR critical anti-patterns found → Loop back to IMPL-001 with feedback
+
+**Acceptance Criteria**:
+- Static analysis: Zero critical issues
+- Test coverage: ≥ 80% for target files
+- Test completeness: All targeted functions have unit tests
+- Negative test coverage: Each public API has at least one error handling test
+- Integration coverage: Key component interactions have integration tests (if applicable)
+
+**Failure Handling**:
+If quality gate fails:
+1. Generate detailed feedback report (`.process/test-quality-report.md`)
+2. Update IMPL-001 task with specific improvement requirements
+3. Trigger IMPL-001 re-execution with enhanced context
+4. Maximum 2 quality gate retries before escalating to user
 
 ### IMPL-002: Test Execution & Fix Cycle
 
@@ -384,7 +505,7 @@ Generates minimum 2 tasks (expandable for complex projects):
 
 ### Output Files Structure
 
-Created in `.workflow/WFS-test-[session]/`:
+Created in `.workflow/active/WFS-test-[session]/`:
 
 ```
 WFS-test-[session]/
@@ -412,18 +533,62 @@ WFS-test-[session]/
 - `workflow_type: "test_session"`
 - No `source_session_id` field
 
-### Complete Data Flow
+### Execution Flow Diagram
 
-**Example Command**: `/workflow:test-fix-gen WFS-user-auth`
+```
+Test-Fix-Gen Workflow Orchestrator (Dual-Mode Support)
+│
+├─ Phase 1: Create Test Session
+│  ├─ Session Mode: /workflow:session:start --new (with source_session_id)
+│  └─ Prompt Mode: /workflow:session:start --new (without source_session_id)
+│     └─ Returns: testSessionId (WFS-test-[slug])
+│
+├─ Phase 2: Gather Context                                   ← ATTACHED (3 tasks)
+│  ├─ Session Mode: /workflow:tools:test-context-gather
+│  │  └─ Load source session summaries + analyze coverage
+│  └─ Prompt Mode: /workflow:tools:context-gather
+│     └─ Analyze codebase from description
+│     ├─ Phase 2.1: Load context and analyze coverage
+│     ├─ Phase 2.2: Detect test framework and conventions
+│     └─ Phase 2.3: Generate context package
+│     └─ Returns: [test-]context-package.json                ← COLLAPSED
+│
+├─ Phase 3: Test Generation Analysis                         ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-concept-enhanced
+│     ├─ Phase 3.1: Analyze coverage gaps with Gemini
+│     ├─ Phase 3.2: Study existing test patterns
+│     └─ Phase 3.3: Generate test generation strategy
+│     └─ Returns: TEST_ANALYSIS_RESULTS.md                   ← COLLAPSED
+│
+├─ Phase 4: Generate Test Tasks                              ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-task-generate
+│     ├─ Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md
+│     ├─ Phase 4.2: Generate task JSONs (IMPL-001, IMPL-002)
+│     └─ Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md
+│     └─ Returns: Task JSONs and plans                       ← COLLAPSED
+│
+└─ Phase 5: Return Summary
+   └─ Command ends, control returns to user
 
-**Phase Execution Chain**:
-1. Phase 1: `session-start` → `WFS-test-user-auth`
-2. Phase 2: `test-context-gather` → `test-context-package.json`
-3. Phase 3: `test-concept-enhanced` → `TEST_ANALYSIS_RESULTS.md`
-4. Phase 4: `test-task-generate` → `IMPL-001.json` + `IMPL-002.json` (+ additional if needed)
-5. Phase 5: Return summary
+Artifacts Created:
+├── .workflow/active/WFS-test-[session]/
+│   ├── workflow-session.json
+│   ├── IMPL_PLAN.md
+│   ├── TODO_LIST.md
+│   ├── .task/
+│   │   ├── IMPL-001.json (test understanding & generation)
+│   │   ├── IMPL-002.json (test execution & fix cycle)
+│   │   └── IMPL-003.json (optional: test review & certification)
+│   └── .process/
+│       ├── [test-]context-package.json
+│       └── TEST_ANALYSIS_RESULTS.md
 
-**Command completes after Phase 5**
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
+• Dual-Mode: Session Mode and Prompt Mode share same attachment pattern
+• Command Boundary: Execution delegated to /workflow:test-cycle-execute
+```
 
 ---
 
@@ -462,25 +627,23 @@ WFS-test-[session]/
    - Use `--use-codex` for autonomous fix application
    - Use `--cli-execute` for enhanced generation capabilities
 
-### Related Commands
+## Related Commands
 
-**Planning Phase**:
-- `/workflow:plan` - Create implementation workflow
-- `/workflow:session:start` - Initialize workflow session
+**Prerequisite Commands**:
+- `/workflow:plan` or `/workflow:execute` - Complete implementation session (for Session Mode)
+- None for Prompt Mode (ad-hoc test generation)
 
-**Context Gathering**:
-- `/workflow:tools:test-context-gather` - Session-based context (Phase 2 for session mode)
-- `/workflow:tools:context-gather` - Prompt-based context (Phase 2 for prompt mode)
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create independent test workflow session
+- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
+- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
+- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
 
-**Analysis & Task Generation**:
-- `/workflow:tools:test-concept-enhanced` - Gemini test analysis (Phase 3)
-- `/workflow:tools:test-task-generate` - Generate test tasks (Phase 4)
+**Follow-up Commands**:
+- `/workflow:status` - Review generated test tasks
+- `/workflow:test-cycle-execute` - Execute test generation and iterative fix cycles
+- `/workflow:execute` - Standard execution of generated test tasks
 
-**Execution**:
-- `/workflow:test-cycle-execute` - Execute test-fix workflow (recommended for IMPL-002)
-- `/workflow:execute` - Execute standard workflow tasks
-- `/workflow:status` - Check task progress
-
-**Review & Management**:
-- `/workflow:review` - Review workflow results
-- `/workflow:session:complete` - Mark session complete

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

@@ -1,6 +1,6 @@
 ---
 name: test-gen
-description: Create independent test-fix workflow session by analyzing completed implementation
+description: Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks
 argument-hint: "[--use-codex] [--cli-execute] source-session-id"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
@@ -18,13 +18,26 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - **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
 
+**Task Attachment Model**:
+- SlashCommand invocation **expands workflow** by attaching sub-tasks to current TodoWrite
+- When a sub-command is invoked (e.g., `/workflow:tools:test-context-gather`), its internal tasks are attached to the orchestrator's TodoWrite
+- Orchestrator **executes these attached tasks** sequentially
+- After completion, attached tasks are **collapsed** back to high-level phase summary
+- This is **task expansion**, not external delegation
+
+**Auto-Continue Mechanism**:
+- TodoList tracks current phase status and dynamically manages task attachment/collapse
+- When each phase finishes executing, automatically execute next pending phase
+- All phases run autonomously without user interaction
+- **⚠️ CONTINUOUS EXECUTION** - Do not stop until all phases complete
+
 **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
 
-**⚠️ Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
+**Command Scope**: This command ONLY prepares test workflow artifacts. It does NOT execute tests or implementation. Task execution requires separate user action.
 
 ## Core Rules
 
@@ -33,10 +46,12 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 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 5 completes (summary returned)
-6. **Track Progress**: Update TodoWrite after every phase completion
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
 7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
 8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
-9. **⚠️ Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
+9. **Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
+10. **Task Attachment Model**: SlashCommand invocation **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
+11. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
 
 ## 5-Phase Execution
 
@@ -89,7 +104,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 - Test framework detected
 - Test conventions documented
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+<!-- TodoWrite: When test-context-gather invoked, INSERT 3 test-context-gather tasks -->
+
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Phase 2.1: Load source session summaries (test-context-gather)", "status": "in_progress", "activeForm": "Loading source session summaries"},
+  {"content": "Phase 2.2: Analyze test coverage with MCP tools (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
+  {"content": "Phase 2.3: Identify coverage gaps and framework (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-context-gather's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 2.1-2.3** sequentially
+
+<!-- TodoWrite: After Phase 2 tasks complete, REMOVE Phase 2.1-2.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "pending", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
 
 ---
 
@@ -121,7 +168,39 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
   - Implementation Targets (test files to create)
   - Success Criteria
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+<!-- TodoWrite: When test-concept-enhanced invoked, INSERT 3 concept-enhanced tasks -->
+
+**TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Phase 3.1: Analyze coverage gaps with Gemini (test-concept-enhanced)", "status": "in_progress", "activeForm": "Analyzing coverage gaps"},
+  {"content": "Phase 3.2: Study existing test patterns (test-concept-enhanced)", "status": "pending", "activeForm": "Studying test patterns"},
+  {"content": "Phase 3.3: Generate test generation strategy (test-concept-enhanced)", "status": "pending", "activeForm": "Generating test strategy"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-concept-enhanced's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 3.1-3.3** sequentially
+
+<!-- TodoWrite: After Phase 3 tasks complete, REMOVE Phase 3.1-3.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 3 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "pending", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 3 tasks completed and collapsed to summary.
 
 ---
 
@@ -173,17 +252,49 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
   - 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
+<!-- TodoWrite: When test-task-generate invoked, INSERT 3 test-task-generate tasks -->
+
+**TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md (test-task-generate)", "status": "in_progress", "activeForm": "Parsing test analysis"},
+  {"content": "Phase 4.2: Generate IMPL-001.json and IMPL-002.json (test-task-generate)", "status": "pending", "activeForm": "Generating task JSONs"},
+  {"content": "Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md (test-task-generate)", "status": "pending", "activeForm": "Generating plan documents"},
+  {"content": "Return workflow summary", "status": "pending", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** test-task-generate's 3 tasks. Orchestrator **executes** these tasks.
+
+**Next Action**: Tasks attached → **Execute Phase 4.1-4.3** sequentially
+
+<!-- TodoWrite: After Phase 4 tasks complete, REMOVE Phase 4.1-4.3, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 4 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather test coverage context", "status": "completed", "activeForm": "Gathering test coverage context"},
+  {"content": "Analyze test requirements with Gemini", "status": "completed", "activeForm": "Analyzing test requirements"},
+  {"content": "Generate test generation and execution tasks", "status": "completed", "activeForm": "Generating test tasks"},
+  {"content": "Return workflow summary", "status": "in_progress", "activeForm": "Returning workflow summary"}
+]
+```
+
+**Note**: Phase 4 tasks completed and collapsed to summary.
 
 ---
 
-### Phase 5: Return Summary (⚠️ Command Ends Here)
+### Phase 5: Return Summary (Command Ends Here)
 
-**⚠️ Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
+**Important**: This is the final phase of `/workflow:test-gen`. The command completes and returns control to the user. No automatic execution occurs.
 
 **Return to User**:
 ```
-✅ Test workflow preparation complete!
+Test workflow preparation complete!
 
 Source Session: [sourceSessionId]
 Test Session: [testSessionId]
@@ -198,56 +309,91 @@ Test Framework: [detected framework]
 Test Files to Generate: [count]
 Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
 
-📋 Review Generated Artifacts:
+Review Generated Artifacts:
 - Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
 - Task list: .workflow/[testSessionId]/TODO_LIST.md
 - Analysis: .workflow/[testSessionId]/.process/TEST_ANALYSIS_RESULTS.md
 
-⚠️ Ready for execution. Use appropriate workflow commands to proceed.
+Ready for execution. Use appropriate workflow commands to proceed.
 ```
 
 **TodoWrite**: Mark phase 5 completed
 
-**⚠️ Command Boundary**: After this phase, the command terminates and returns to user prompt.
+**Command Boundary**: After this phase, the command terminates and returns to user prompt.
 
 ---
 
 ## TodoWrite Pattern
 
-Track progress through 5 phases:
+**Core Concept**: Dynamic task attachment and collapse for test-gen workflow with cross-session context gathering and test generation strategy.
 
-```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"}
-]})
-```
+### Key Principles
 
-Update status to `in_progress` when starting each phase, mark `completed` when done.
+1. **Task Attachment** (when SlashCommand invoked):
+   - Sub-command's internal tasks are **attached** to orchestrator's TodoWrite
+   - Example: `/workflow:tools:test-context-gather` attaches 3 sub-tasks (Phase 2.1, 2.2, 2.3)
+   - First attached task marked as `in_progress`, others as `pending`
+   - Orchestrator **executes** these attached tasks sequentially
 
-## Data Flow
+2. **Task Collapse** (after sub-tasks complete):
+   - Remove detailed sub-tasks from TodoWrite
+   - **Collapse** to high-level phase summary
+   - Example: Phase 2.1-2.3 collapse to "Gather test coverage context: completed"
+   - Maintains clean orchestrator-level view
+
+3. **Continuous Execution**:
+   - After collapse, automatically proceed to next pending phase
+   - No user intervention required between phases
+   - TodoWrite dynamically reflects current execution state
+
+**Lifecycle Summary**: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins → Repeat until all phases complete.
+
+### Test-Gen Specific Features
+
+- **Phase 2**: Cross-session context gathering from source implementation session
+- **Phase 3**: Test requirements analysis with Gemini for generation strategy
+- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
+- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+
+
+
+**Note**: See individual Phase descriptions (Phase 2, 3, 4) for detailed TodoWrite Update examples with full JSON structures.
+
+## Execution Flow Diagram
 
 ```
-┌─────────────────────────────────────────────────────────┐
-│ /workflow:test-gen WFS-user-auth                        │
-├─────────────────────────────────────────────────────────┤
-│ Phase 1: session-start → WFS-test-user-auth            │
-│   ↓                                                     │
-│ Phase 2: test-context-gather → test-context-package.json│
-│   ↓                                                     │
-│ Phase 3: test-concept-enhanced → TEST_ANALYSIS_RESULTS.md│
-│   ↓                                                     │
-│ Phase 4: test-task-generate → IMPL-001.json + IMPL-002.json│
-│   ↓                                                     │
-│ Phase 5: Return summary                                │
-└─────────────────────────────────────────────────────────┘
-         ⚠️ COMMAND ENDS - Control returns to user
+Test-Gen Workflow Orchestrator
+│
+├─ Phase 1: Create Test Session
+│  └─ /workflow:session:start --new
+│     └─ Returns: testSessionId (WFS-test-[source])
+│
+├─ Phase 2: Gather Test Context                           ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-context-gather
+│     ├─ Phase 2.1: Load source session summaries
+│     ├─ Phase 2.2: Analyze test coverage with MCP tools
+│     └─ Phase 2.3: Identify coverage gaps and framework
+│     └─ Returns: test-context-package.json               ← COLLAPSED
+│
+├─ Phase 3: Test Generation Analysis                      ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-concept-enhanced
+│     ├─ Phase 3.1: Analyze coverage gaps with Gemini
+│     ├─ Phase 3.2: Study existing test patterns
+│     └─ Phase 3.3: Generate test generation strategy
+│     └─ Returns: TEST_ANALYSIS_RESULTS.md                ← COLLAPSED
+│
+├─ Phase 4: Generate Test Tasks                           ← ATTACHED (3 tasks)
+│  └─ /workflow:tools:test-task-generate
+│     ├─ Phase 4.1: Parse TEST_ANALYSIS_RESULTS.md
+│     ├─ Phase 4.2: Generate IMPL-001.json and IMPL-002.json
+│     └─ Phase 4.3: Generate IMPL_PLAN.md and TODO_LIST.md
+│     └─ Returns: Task JSONs and plans                    ← COLLAPSED
+│
+└─ Phase 5: Return Summary
+   └─ Command ends, control returns to user
 
 Artifacts Created:
-├── .workflow/WFS-test-[session]/
+├── .workflow/active/WFS-test-[session]/
 │   ├── workflow-session.json
 │   ├── IMPL_PLAN.md
 │   ├── TODO_LIST.md
@@ -257,6 +403,10 @@ Artifacts Created:
 │   └── .process/
 │       ├── test-context-package.json
 │       └── TEST_ANALYSIS_RESULTS.md
+
+Key Points:
+• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
+• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
 ```
 
 ## Session Metadata
@@ -290,7 +440,7 @@ See `/workflow:tools:test-task-generate` for complete task JSON schemas.
 
 ## Output Files
 
-Created in `.workflow/WFS-test-[session]/`:
+Created in `.workflow/active/WFS-test-[session]/`:
 - `workflow-session.json` - Session metadata
 - `.process/test-context-package.json` - Coverage analysis
 - `.process/TEST_ANALYSIS_RESULTS.md` - Test requirements
@@ -330,8 +480,18 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
 
 ## Related Commands
 
-- `/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
+**Prerequisite Commands**:
+- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
+
+**Called by This Command** (5 phases):
+- `/workflow:session:start` - Phase 1: Create independent test workflow session
+- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
+- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
+- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
+- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
+
+**Follow-up Commands**:
+- `/workflow:status` - Review generated test tasks
+- `/workflow:test-cycle-execute` - Execute test generation and fix cycles
+- `/workflow:execute` - Execute generated test tasks

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

@@ -1,16 +1,16 @@
 ---
 name: conflict-resolution
-description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis
+description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
 argument-hint: "--session WFS-session-id --context path/to/context-package.json"
 examples:
-  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/WFS-auth/.process/context-package.json
-  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/WFS-payment/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/active/WFS-auth/.process/context-package.json
+  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json
 ---
 
 # Conflict Resolution Command
 
 ## Purpose
-Analyzes conflicts between implementation plans and existing codebase, generating multiple resolution strategies.
+Analyzes conflicts between implementation plans and existing codebase, **including module scenario uniqueness detection**, generating multiple resolution strategies with **iterative clarification until boundaries are clear**.
 
 **Scope**: Detection and strategy generation only - NO code modification or task creation.
 
@@ -21,10 +21,14 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
 | Responsibility | Description |
 |---------------|-------------|
 | **Detect Conflicts** | Analyze plan vs existing code inconsistencies |
+| **Scenario Uniqueness** | **NEW**: Search and compare new modules with existing modules for functional overlaps |
 | **Generate Strategies** | Provide 2-4 resolution options per conflict |
+| **Iterative Clarification** | **NEW**: Ask unlimited questions until scenario boundaries are clear and unique |
+| **Agent Re-analysis** | **NEW**: Dynamically update strategies based on user clarifications |
 | **CLI Analysis** | Use Gemini/Qwen (Claude fallback) |
-| **User Decision** | Present options, never auto-apply |
-| **Single Output** | `CONFLICT_RESOLUTION.md` with findings |
+| **User Decision** | Present options ONE BY ONE, never auto-apply |
+| **Direct Text Output** | Output questions via text directly, NEVER use bash echo/printf |
+| **Structured Data** | JSON output for programmatic processing, NO file generation |
 
 ## Conflict Categories
 
@@ -48,6 +52,13 @@ Analyzes conflicts between implementation plans and existing codebase, generatin
 - Setup conflicts
 - Breaking updates
 
+### 5. Module Scenario Overlap
+- **NEW**: Functional overlap between new and existing modules
+- Scenario boundary ambiguity
+- Duplicate responsibility detection
+- Module merge/split decisions
+- **Requires iterative clarification until uniqueness confirmed**
+
 ## Execution Flow
 
 ### Phase 1: Validation
@@ -72,23 +83,31 @@ Task(subagent_type="cli-execution-agent", prompt=`
 
   ### 1. Load Context
   - Read existing files from conflict_detection.existing_files
-  - Load plan from .workflow/{session_id}/.process/context-package.json
+  - Load plan from .workflow/active/{session_id}/.process/context-package.json
   - Extract role analyses and requirements
 
-  ### 2. Execute CLI Analysis
+  ### 2. Execute CLI Analysis (Enhanced with Scenario Uniqueness Detection)
 
   Primary (Gemini):
   cd {project_root} && gemini -p "
-  PURPOSE: Detect conflicts between plan and codebase
+  PURPOSE: Detect conflicts between plan and codebase, including module scenario overlaps
   TASK:
   • Compare architectures
   • Identify breaking API changes
   • Detect data model incompatibilities
   • Assess dependency conflicts
+  • **NEW: Analyze module scenario uniqueness**
+    - Extract new module functionality from plan
+    - Search all existing modules with similar functionality
+    - Compare scenario coverage and identify overlaps
+    - Generate clarification questions for boundary definition
   MODE: analysis
-  CONTEXT: @{existing_files} @.workflow/{session_id}/**/*
-  EXPECTED: Conflict list with severity ratings
-  RULES: Focus on breaking changes and migration needs
+  CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/{session_id}/**/*
+  EXPECTED: Conflict list with severity ratings, including ModuleOverlap conflicts with:
+    - Existing module list with scenarios
+    - Overlap analysis matrix
+    - Targeted clarification questions
+  RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on breaking changes, migration needs, and functional overlaps | analysis=READ-ONLY
   "
 
   Fallback: Qwen (same prompt) → Claude (manual analysis)
@@ -97,9 +116,11 @@ Task(subagent_type="cli-execution-agent", prompt=`
 
   Template per conflict:
   - Severity: Critical/High/Medium
-  - Category: Architecture/API/Data/Dependency
+  - Category: Architecture/API/Data/Dependency/ModuleOverlap
   - Affected files + impact
+  - **For ModuleOverlap**: Include overlap_analysis with existing modules and scenarios
   - Options with pros/cons, effort, risk
+  - **For ModuleOverlap strategies**: Add clarification_needed questions for boundary definition
   - Recommended strategy + rationale
 
   ### 4. Return Structured Conflict Data
@@ -115,10 +136,10 @@ Task(subagent_type="cli-execution-agent", prompt=`
         "id": "CON-001",
         "brief": "一行中文冲突摘要",
         "severity": "Critical|High|Medium",
-        "category": "Architecture|API|Data|Dependency",
+        "category": "Architecture|API|Data|Dependency|ModuleOverlap",
         "affected_files": [
-          ".workflow/{session}/.brainstorm/guidance-specification.md",
-          ".workflow/{session}/.brainstorm/system-architect/analysis.md"
+          ".workflow/active/{session}/.brainstorm/guidance-specification.md",
+          ".workflow/active/{session}/.brainstorm/system-architect/analysis.md"
         ],
         "description": "详细描述冲突 - 什么不兼容",
         "impact": {
@@ -127,6 +148,23 @@ Task(subagent_type="cli-execution-agent", prompt=`
           "migration_required": true|false,
           "estimated_effort": "人天估计"
         },
+        "overlap_analysis": {
+          "// NOTE": "仅当 category=ModuleOverlap 时需要此字段",
+          "new_module": {
+            "name": "新模块名称",
+            "scenarios": ["场景1", "场景2", "场景3"],
+            "responsibilities": "职责描述"
+          },
+          "existing_modules": [
+            {
+              "file": "src/existing/module.ts",
+              "name": "现有模块名称",
+              "scenarios": ["场景A", "场景B"],
+              "overlap_scenarios": ["重叠场景1", "重叠场景2"],
+              "responsibilities": "现有模块职责"
+            }
+          ]
+        },
         "strategies": [
           {
             "name": "策略名称（中文）",
@@ -136,9 +174,15 @@ Task(subagent_type="cli-execution-agent", prompt=`
             "effort": "时间估计",
             "pros": ["优点1", "优点2"],
             "cons": ["缺点1", "缺点2"],
+            "clarification_needed": [
+              "// NOTE: 仅当需要用户进一步澄清时需要此字段（尤其是 ModuleOverlap）",
+              "新模块的核心职责边界是什么？",
+              "如何与现有模块 X 协作？",
+              "哪些场景应该由新模块处理？"
+            ],
             "modifications": [
               {
-                "file": ".workflow/{session}/.brainstorm/guidance-specification.md",
+                "file": ".workflow/active/{session}/.brainstorm/guidance-specification.md",
                 "section": "## 2. System Architect Decisions",
                 "change_type": "update",
                 "old_content": "原始内容片段（用于定位）",
@@ -146,7 +190,7 @@ Task(subagent_type="cli-execution-agent", prompt=`
                 "rationale": "为什么这样改"
               },
               {
-                "file": ".workflow/{session}/.brainstorm/system-architect/analysis.md",
+                "file": ".workflow/active/{session}/.brainstorm/system-architect/analysis.md",
                 "section": "## Design Decisions",
                 "change_type": "update",
                 "old_content": "原始内容片段",
@@ -203,155 +247,251 @@ Task(subagent_type="cli-execution-agent", prompt=`
 `)
 ```
 
-**Agent Internal Flow**:
+**Agent Internal Flow** (Enhanced):
 ```
 1. Load context package
 2. Check conflict_risk (exit if none/low)
 3. Read existing files + plan artifacts
-4. Run CLI analysis (Gemini→Qwen→Claude)
-5. Parse conflict findings
-6. Generate 2-4 strategies per conflict with modifications
+4. Run CLI analysis (Gemini→Qwen→Claude) with enhanced tasks:
+   - Standard conflict detection (Architecture/API/Data/Dependency)
+   - **NEW: Module scenario uniqueness detection**
+     * Extract new module functionality from plan
+     * Search all existing modules with similar keywords/functionality
+     * Compare scenario coverage and responsibilities
+     * Identify functional overlaps and boundary ambiguities
+     * Generate ModuleOverlap conflicts with overlap_analysis
+5. Parse conflict findings (including ModuleOverlap category)
+6. Generate 2-4 strategies per conflict:
+   - Include modifications for each strategy
+   - **For ModuleOverlap**: Add clarification_needed questions for boundary definition
 7. Return JSON to stdout (NOT file write)
 8. Return execution log path
 ```
 
-### Phase 3: User Confirmation via Text Interaction
+### Phase 3: Iterative User Interaction with Clarification Loop
 
-**Command parses agent JSON output and presents conflicts to user via text**:
+**Execution Flow**:
+```
+FOR each conflict (逐个处理，无数量限制):
+  clarified = false
+  round = 0
+  userClarifications = []
+
+  WHILE (!clarified && round < 10):
+    round++
+
+    // 1. Display conflict (包含所有关键字段)
+    - category, id, brief, severity, description
+    - IF ModuleOverlap: 展示 overlap_analysis
+      * new_module: {name, scenarios, responsibilities}
+      * existing_modules[]: {file, name, scenarios, overlap_scenarios, responsibilities}
+
+    // 2. Display strategies (2-4个策略 + 自定义选项)
+    - FOR each strategy: {name, approach, complexity, risk, effort, pros, cons}
+      * IF clarification_needed: 展示待澄清问题列表
+    - 自定义选项: {suggestions: modification_suggestions[]}
+
+    // 3. User selects strategy
+    userChoice = readInput()
+
+    IF userChoice == "自定义":
+      customConflicts.push({id, brief, category, suggestions, overlap_analysis})
+      clarified = true
+      BREAK
+
+    selectedStrategy = strategies[userChoice]
+
+    // 4. Clarification loop
+    IF selectedStrategy.clarification_needed.length > 0:
+      // 收集澄清答案
+      FOR each question:
+        answer = readInput()
+        userClarifications.push({question, answer})
+
+      // Agent 重新分析
+      reanalysisResult = Task(cli-execution-agent, prompt={
+        冲突信息: {id, brief, category, 策略}
+        用户澄清: userClarifications[]
+        场景分析: overlap_analysis (if ModuleOverlap)
+
+        输出: {
+          uniqueness_confirmed: bool,
+          rationale: string,
+          updated_strategy: {name, approach, complexity, risk, effort, modifications[]},
+          remaining_questions: [] (如果仍有歧义)
+        }
+      })
+
+      IF reanalysisResult.uniqueness_confirmed:
+        selectedStrategy = updated_strategy
+        selectedStrategy.clarifications = userClarifications
+        clarified = true
+      ELSE:
+        // 更新澄清问题，继续下一轮
+        selectedStrategy.clarification_needed = remaining_questions
+    ELSE:
+      clarified = true
+
+    resolvedConflicts.push({conflict, strategy: selectedStrategy})
+  END WHILE
+END FOR
+
+// Build output
+selectedStrategies = resolvedConflicts.map(r => ({
+  conflict_id, strategy, clarifications[]
+}))
+```
+
+**Key Data Structures**:
 
 ```javascript
-// 1. Parse agent JSON output
-const conflictData = JSON.parse(agentOutput);
-const conflicts = conflictData.conflicts; // No 4-conflict limit
-
-// 2. Format conflicts as text output (max 10 per round)
-const batchSize = 10;
-const batches = chunkArray(conflicts, batchSize);
-
-for (const [batchIdx, batch] of batches.entries()) {
-  const totalBatches = batches.length;
-
-  // Output batch header
-  console.log(`===== 冲突解决 (第 ${batchIdx + 1}/${totalBatches} 轮) =====\n`);
-
-  // Output each conflict in batch
-  batch.forEach((conflict, idx) => {
-    const questionNum = batchIdx * batchSize + idx + 1;
-    console.log(`【问题${questionNum} - ${conflict.category}】${conflict.id}: ${conflict.brief}`);
-
-    conflict.strategies.forEach((strategy, sIdx) => {
-      const optionLetter = String.fromCharCode(97 + sIdx); // a, b, c, ...
-      console.log(`${optionLetter}) ${strategy.name}`);
-      console.log(`   说明：${strategy.approach}`);
-      console.log(`   复杂度: ${strategy.complexity} | 风险: ${strategy.risk} | 工作量: ${strategy.effort}`);
-    });
-
-    // Add custom option
-    const customLetter = String.fromCharCode(97 + conflict.strategies.length);
-    console.log(`${customLetter}) 自定义修改`);
-    console.log(`   说明：根据修改建议自行处理，不应用预设策略`);
-
-    // Show modification suggestions
-    if (conflict.modification_suggestions && conflict.modification_suggestions.length > 0) {
-      console.log(`   修改建议：`);
-      conflict.modification_suggestions.forEach(suggestion => {
-        console.log(`   - ${suggestion}`);
-      });
-    }
-    console.log();
-  });
-
-  console.log(`请回答 (格式: 1a 2b 3c...)：`);
-
-  // Wait for user input
-  const userInput = await readUserInput();
-
-  // Parse answers
-  const answers = parseUserAnswers(userInput, batch);
+// Custom conflict tracking
+customConflicts[] = {
+  id, brief, category,
+  suggestions: modification_suggestions[],
+  overlap_analysis: { new_module{}, existing_modules[] }  // ModuleOverlap only
 }
 
-// 3. Build selected strategies (exclude custom selections)
-const selectedStrategies = answers.filter(a => !a.isCustom).map(a => a.strategy);
-const customConflicts = answers.filter(a => a.isCustom).map(a => ({
-  id: a.conflict.id,
-  brief: a.conflict.brief,
-  suggestions: a.conflict.modification_suggestions
-}));
+// Agent re-analysis prompt output
+{
+  uniqueness_confirmed: bool,
+  rationale: string,
+  updated_strategy: {
+    name, approach, complexity, risk, effort,
+    modifications: [{file, section, change_type, old_content, new_content, rationale}]
+  },
+  remaining_questions: string[]
+}
 ```
 
-**Text Output Example**:
+**Text Output Example** (展示关键字段):
+
 ```markdown
-===== 冲突解决 (第 1/1 轮) =====
+============================================================
+冲突 1/3 - 第 1 轮
+============================================================
+【ModuleOverlap】CON-001: 新增用户认证服务与现有模块功能重叠
+严重程度: High | 描述: 计划中的 UserAuthService 与现有 AuthManager 场景重叠
 
-【问题1 - Architecture】CON-001: 现有认证系统与计划不兼容
-a) 渐进式迁移
-   说明：保留现有系统，逐步迁移到新方案
-   复杂度: Medium | 风险: Low | 工作量: 3-5天
-b) 完全重写
-   说明：废弃旧系统，从零实现新认证
-   复杂度: High | 风险: Medium | 工作量: 7-10天
-c) 自定义修改
-   说明：根据修改建议自行处理，不应用预设策略
-   修改建议：
-   - 评估现有认证系统的兼容性，考虑是否可以通过适配器模式桥接
-   - 检查JWT token格式和验证逻辑是否需要调整
-   - 确保用户会话管理与新架构保持一致
+--- 场景重叠分析 ---
+新模块: UserAuthService | 场景: 登录, Token验证, 权限, MFA
+现有模块: AuthManager (src/auth/AuthManager.ts) | 重叠: 登录, Token验证
 
-【问题2 - Data】CON-002: 数据库 schema 冲突
-a) 添加迁移脚本
-   说明：创建数据库迁移脚本处理 schema 变更
-   复杂度: Low | 风险: Low | 工作量: 1-2天
-b) 自定义修改
-   说明：根据修改建议自行处理，不应用预设策略
-   修改建议：
-   - 检查现有表结构是否支持新增字段，避免破坏性变更
-   - 考虑使用数据库版本控制工具（如Flyway或Liquibase）
-   - 准备数据迁移和回滚策略
+--- 解决策略 ---
+1) 合并 (Low复杂度 | Low风险 | 2-3天)
+   ⚠️ 需澄清: AuthManager是否能承担MFA？
 
-请回答 (格式: 1a 2b)：
+2) 拆分边界 (Medium复杂度 | Medium风险 | 4-5天)
+   ⚠️ 需澄清: 基础/高级认证边界? Token验证归谁?
+
+3) 自定义修改
+   建议: 评估扩展性; 策略模式分离; 定义接口边界
+
+请选择 (1-3): > 2
+
+--- 澄清问答 (第1轮) ---
+Q: 基础/高级认证边界?
+A: 基础=密码登录+token验证, 高级=MFA+OAuth+SSO
+
+Q: Token验证归谁?
+A: 统一由 AuthManager 负责
+
+🔄 重新分析...
+✅ 唯一性已确认 | 理由: 边界清晰 - AuthManager(基础+token), UserAuthService(MFA+OAuth+SSO)
+
+============================================================
+冲突 2/3 - 第 1 轮 [下一个冲突]
+============================================================
 ```
 
-**User Input Examples**:
-- `1a 2a` → Conflict 1: 渐进式迁移, Conflict 2: 添加迁移脚本
-- `1b 2b` → Conflict 1: 完全重写, Conflict 2: 自定义修改
-- `1c 2c` → Both choose custom modification (user handles manually with suggestions)
+**Loop Characteristics**: 逐个处理 | 无限轮次(max 10) | 动态问题生成 | Agent重新分析判断唯一性 | ModuleOverlap场景边界澄清
 
 ### Phase 4: Apply Modifications
 
 ```javascript
-// 1. Extract modifications from selected strategies
+// 1. Extract modifications from resolved strategies
 const modifications = [];
-selectedStrategies.forEach(strategy => {
-  if (strategy !== "skip") {
-    modifications.push(...strategy.modifications);
+selectedStrategies.forEach(item => {
+  if (item.strategy && item.strategy.modifications) {
+    modifications.push(...item.strategy.modifications.map(mod => ({
+      ...mod,
+      conflict_id: item.conflict_id,
+      clarifications: item.clarifications
+    })));
   }
 });
 
+console.log(`\n正在应用 ${modifications.length} 个修改...`);
+
 // 2. Apply each modification using Edit tool
-modifications.forEach(mod => {
-  if (mod.change_type === "update") {
-    Edit({
-      file_path: mod.file,
-      old_string: mod.old_content,
-      new_string: mod.new_content
-    });
+const appliedModifications = [];
+const failedModifications = [];
+
+modifications.forEach((mod, idx) => {
+  try {
+    console.log(`[${idx + 1}/${modifications.length}] 修改 ${mod.file}...`);
+
+    if (mod.change_type === "update") {
+      Edit({
+        file_path: mod.file,
+        old_string: mod.old_content,
+        new_string: mod.new_content
+      });
+    } else if (mod.change_type === "add") {
+      // Handle addition - append or insert based on section
+      const fileContent = Read(mod.file);
+      const updated = insertContentAfterSection(fileContent, mod.section, mod.new_content);
+      Write(mod.file, updated);
+    } else if (mod.change_type === "remove") {
+      Edit({
+        file_path: mod.file,
+        old_string: mod.old_content,
+        new_string: ""
+      });
+    }
+
+    appliedModifications.push(mod);
+    console.log(`  ✓ 成功`);
+  } catch (error) {
+    console.log(`  ✗ 失败: ${error.message}`);
+    failedModifications.push({ ...mod, error: error.message });
   }
-  // Handle "add" and "remove" similarly
 });
 
-// 3. Update context-package.json
+// 3. Update context-package.json with resolution details
 const contextPackage = JSON.parse(Read(contextPath));
 contextPackage.conflict_detection.conflict_risk = "resolved";
-contextPackage.conflict_detection.resolved_conflicts = conflicts.map(c => c.id);
+contextPackage.conflict_detection.resolved_conflicts = selectedStrategies.map(s => ({
+  conflict_id: s.conflict_id,
+  strategy_name: s.strategy.name,
+  clarifications: s.clarifications
+}));
+contextPackage.conflict_detection.custom_conflicts = customConflicts.map(c => c.id);
 contextPackage.conflict_detection.resolved_at = new Date().toISOString();
 Write(contextPath, JSON.stringify(contextPackage, null, 2));
 
-// 4. Output custom conflict summary (if any)
+// 4. Output custom conflict summary with overlap analysis (if any)
 if (customConflicts.length > 0) {
-  console.log("\n===== 需要自定义处理的冲突 =====\n");
+  console.log(`\n${'='.repeat(60)}`);
+  console.log(`需要自定义处理的冲突 (${customConflicts.length})`);
+  console.log(`${'='.repeat(60)}\n`);
+
   customConflicts.forEach(conflict => {
-    console.log(`【${conflict.id}】${conflict.brief}`);
-    console.log("修改建议：");
+    console.log(`【${conflict.category}】${conflict.id}: ${conflict.brief}`);
+
+    // Show overlap analysis for ModuleOverlap conflicts
+    if (conflict.category === 'ModuleOverlap' && conflict.overlap_analysis) {
+      console.log(`\n场景重叠信息:`);
+      console.log(`  新模块: ${conflict.overlap_analysis.new_module.name}`);
+      console.log(`  场景: ${conflict.overlap_analysis.new_module.scenarios.join(', ')}`);
+      console.log(`\n  与以下模块重叠:`);
+      conflict.overlap_analysis.existing_modules.forEach(mod => {
+        console.log(`    - ${mod.name} (${mod.file})`);
+        console.log(`      重叠场景: ${mod.overlap_scenarios.join(', ')}`);
+      });
+    }
+
+    console.log(`\n修改建议:`);
     conflict.suggestions.forEach(suggestion => {
       console.log(`  - ${suggestion}`);
     });
@@ -359,25 +499,43 @@ if (customConflicts.length > 0) {
   });
 }
 
-// 5. Return summary
+// 5. Output failure summary (if any)
+if (failedModifications.length > 0) {
+  console.log(`\n⚠️ 部分修改失败 (${failedModifications.length}):`);
+  failedModifications.forEach(mod => {
+    console.log(`  - ${mod.file}: ${mod.error}`);
+  });
+}
+
+// 6. Return summary
 return {
-  resolved: modifications.length,
-  custom: customConflicts.length,
-  modified_files: [...new Set(modifications.map(m => m.file))],
-  custom_conflicts: customConflicts
+  total_conflicts: conflicts.length,
+  resolved_with_strategy: selectedStrategies.length,
+  custom_handling: customConflicts.length,
+  modifications_applied: appliedModifications.length,
+  modifications_failed: failedModifications.length,
+  modified_files: [...new Set(appliedModifications.map(m => m.file))],
+  custom_conflicts: customConflicts,
+  clarification_records: selectedStrategies.filter(s => s.clarifications.length > 0)
 };
 ```
 
 **Validation**:
 ```
-✓ Agent returns valid JSON structure
-✓ Text output displays all conflicts (max 10 per round)
-✓ User selections captured correctly
+✓ Agent returns valid JSON structure with ModuleOverlap conflicts
+✓ Conflicts processed ONE BY ONE (not in batches)
+✓ ModuleOverlap conflicts include overlap_analysis field
+✓ Strategies with clarification_needed display questions
+✓ User selections captured correctly per conflict
+✓ Clarification loop continues until uniqueness confirmed
+✓ Agent re-analysis returns uniqueness_confirmed and updated_strategy
+✓ Maximum 10 rounds per conflict safety limit enforced
 ✓ Edit tool successfully applies modifications
 ✓ guidance-specification.md updated
 ✓ Role analyses (*.md) updated
-✓ context-package.json marked as resolved
-✓ Agent log saved to .workflow/{session_id}/.chat/
+✓ context-package.json marked as resolved with clarification records
+✓ Custom conflicts display overlap_analysis for manual handling
+✓ Agent log saved to .workflow/active/{session_id}/.chat/
 ```
 
 ## Output Format: Agent JSON Response
@@ -434,38 +592,45 @@ If Edit tool fails mid-application:
 
 **Output**:
 - Modified files:
-  - `.workflow/{session_id}/.brainstorm/guidance-specification.md`
-  - `.workflow/{session_id}/.brainstorm/{role}/analysis.md`
-  - `.workflow/{session_id}/.process/context-package.json` (conflict_risk → resolved)
+  - `.workflow/active/{session_id}/.brainstorm/guidance-specification.md`
+  - `.workflow/active/{session_id}/.brainstorm/{role}/analysis.md`
+  - `.workflow/active/{session_id}/.process/context-package.json` (conflict_risk → resolved)
 - NO report file generation
 
 **User Interaction**:
-- Text-based strategy selection (max 10 conflicts per round)
+- **Iterative conflict processing**: One conflict at a time, not in batches
 - Each conflict: 2-4 strategy options + "自定义修改" option (with suggestions)
+- **Clarification loop**: Unlimited questions per conflict until uniqueness confirmed (max 10 rounds)
+- **ModuleOverlap conflicts**: Display overlap_analysis with existing modules
+- **Agent re-analysis**: Dynamic strategy updates based on user clarifications
 
 ### Success Criteria
 ```
-✓ CLI analysis returns valid JSON structure
-✓ Conflicts presented in batches (max 10 per round)
+✓ CLI analysis returns valid JSON structure with ModuleOverlap category
+✓ Agent performs scenario uniqueness detection (searches existing modules)
+✓ Conflicts processed ONE BY ONE with iterative clarification
 ✓ Min 2 strategies per conflict with modifications
+✓ ModuleOverlap conflicts include overlap_analysis with existing modules
+✓ Strategies requiring clarification include clarification_needed questions
 ✓ Each conflict includes 2-5 modification_suggestions
-✓ Text output displays all conflicts correctly with suggestions
-✓ User selections captured and processed
+✓ Text output displays conflict with overlap analysis (if ModuleOverlap)
+✓ User selections captured per conflict
+✓ Clarification loop continues until uniqueness confirmed (unlimited rounds, max 10)
+✓ Agent re-analysis with user clarifications updates strategy
+✓ Uniqueness confirmation based on clear scenario boundaries
 ✓ Edit tool applies modifications successfully
-✓ Custom conflicts displayed with suggestions for manual handling
+✓ Custom conflicts displayed with overlap_analysis for manual handling
 ✓ guidance-specification.md updated with resolved conflicts
 ✓ Role analyses (*.md) updated with resolved conflicts
-✓ context-package.json marked as "resolved"
+✓ context-package.json marked as "resolved" with clarification records
 ✓ No CONFLICT_RESOLUTION.md file generated
-✓ Modification summary includes custom conflict count
-✓ Agent log saved to .workflow/{session_id}/.chat/
+✓ Modification summary includes:
+  - Total conflicts
+  - Resolved with strategy (count)
+  - Custom handling (count)
+  - Clarification records
+  - Overlap analysis for custom ModuleOverlap conflicts
+✓ Agent log saved to .workflow/active/{session_id}/.chat/
 ✓ Error handling robust (validate/retry/degrade)
 ```
 
-## Related Commands
-| Command | Relationship |
-|---------|--------------|
-| `/workflow:tools:context-gather` | Generates input conflict_detection data |
-| `/workflow:plan` | Auto-triggers this when risk ≥ medium |
-| `/workflow:tools:task-generate` | Uses resolved conflicts from updated brainstorm files |
-| `/workflow:brainstorm:artifacts` | Generates guidance-specification.md (modified by this command) |

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

@@ -1,6 +1,6 @@
 ---
 name: gather
-description: Intelligently collect project context using context-search-agent based on task description and package into standardized JSON
+description: Intelligently collect project context using context-search-agent based on task description, packages into standardized JSON
 argument-hint: "--session WFS-session-id \"task description\""
 examples:
   - /workflow:tools:context-gather --session WFS-user-auth "Implement user authentication system"
@@ -22,7 +22,7 @@ Orchestrator command that invokes `context-search-agent` to gather comprehensive
 - **Agent Delegation**: Delegate all discovery to `context-search-agent` for autonomous execution
 - **Detection-First**: Check for existing context-package before executing
 - **Plan Mode**: Full comprehensive analysis (vs lightweight brainstorm mode)
-- **Standardized Output**: Generate `.workflow/{session}/.process/context-package.json`
+- **Standardized Output**: Generate `.workflow/active/{session}/.process/context-package.json`
 
 ## Execution Flow
 
@@ -57,8 +57,6 @@ Task(
   subagent_type="context-search-agent",
   description="Gather comprehensive context for plan",
   prompt=`
-You are executing as context-search-agent (.claude/agents/context-search-agent.md).
-
 ## Execution Mode
 **PLAN MODE** (Comprehensive) - Full Phase 1-3 execution
 
@@ -71,31 +69,35 @@ You are executing as context-search-agent (.claude/agents/context-search-agent.m
 Execute complete context-search-agent workflow for implementation planning:
 
 ### Phase 1: Initialization & Pre-Analysis
-1. **Detection**: Check for existing context-package (early exit if valid)
-2. **Foundation**: Initialize code-index, get project structure, load docs
-3. **Analysis**: Extract keywords, determine scope, classify complexity
+1. **Project State Loading**: Read and parse `.workflow/project.json`. Use its `overview` section as the foundational `project_context`. This is your primary source for architecture, tech stack, and key components. If file doesn't exist, proceed with fresh analysis.
+2. **Detection**: Check for existing context-package (early exit if valid)
+3. **Foundation**: Initialize code-index, get project structure, load docs
+4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state
 
 ### Phase 2: Multi-Source Context Discovery
-Execute all 3 discovery tracks:
-- **Track 1**: Reference documentation (CLAUDE.md, architecture docs)
-- **Track 2**: Web examples (use Exa MCP for unfamiliar tech/APIs)
-- **Track 3**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
+Execute all 4 discovery tracks:
+- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
+- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
+- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
+- **Track 4**: Codebase analysis (5-layer discovery: files, content, patterns, deps, config/tests)
 
 ### Phase 3: Synthesis, Assessment & Packaging
 1. Apply relevance scoring and build dependency graph
-2. Synthesize 3-source data (docs > code > web)
-3. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
-4. Perform conflict detection with risk assessment
-5. Generate and validate context-package.json
+2. **Synthesize 4-source data**: Merge findings from all sources (archive > docs > code > web). **Prioritize the context from `project.json`** for architecture and tech stack unless code analysis reveals it's outdated.
+3. **Populate `project_context`**: Directly use the `overview` from `project.json` to fill the `project_context` section of the output `context-package.json`. Include technology_stack, architecture, key_components, and entry_points.
+4. Integrate brainstorm artifacts (if .brainstorming/ exists, read content)
+5. Perform conflict detection with risk assessment
+6. **Inject historical conflicts** from archive analysis into conflict_detection
+7. Generate and validate context-package.json
 
 ## Output Requirements
 Complete context-package.json with:
 - **metadata**: task_description, keywords, complexity, tech_stack, session_id
-- **project_context**: architecture_patterns, coding_conventions, tech_stack
+- **project_context**: architecture_patterns, coding_conventions, tech_stack (sourced from `project.json` overview)
 - **assets**: {documentation[], source_code[], config[], tests[]} with relevance scores
 - **dependencies**: {internal[], external[]} with dependency graph
 - **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
-- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy}
+- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
 
 ## Quality Validation
 Before completion verify:
@@ -137,39 +139,121 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`
 
 **Key Sections**:
 - **metadata**: Session info, keywords, complexity, tech stack
-- **project_context**: Architecture patterns, conventions, tech stack
+- **project_context**: Architecture patterns, conventions, tech stack (populated from `project.json` overview)
 - **assets**: Categorized files with relevance scores (documentation, source_code, config, tests)
 - **dependencies**: Internal and external dependency graphs
 - **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
-- **conflict_detection**: Risk assessment with mitigation strategies
+- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
 
-## Usage Examples
+## Historical Archive Analysis
 
-### Basic Usage
+### Track 1: Query Archive Manifest
+
+The context-search-agent MUST perform historical archive analysis as Track 1 in Phase 2:
+
+**Step 1: Check for Archive Manifest**
 ```bash
-/workflow:tools:context-gather --session WFS-auth-feature "Implement JWT authentication with refresh tokens"
+# Check if archive manifest exists
+if [[ -f .workflow/archives/manifest.json ]]; then
+  # Manifest available for querying
+fi
 ```
-## Success Criteria
 
-- ✅ Valid context-package.json generated in `.workflow/{session}/.process/`
-- ✅ Contains >80% relevant files based on task keywords
-- ✅ Execution completes within 2 minutes
-- ✅ All required schema fields present and valid
-- ✅ Conflict risk accurately assessed
-- ✅ Agent reports completion with statistics
+**Step 2: Extract Task Keywords**
+```javascript
+// From current task description, extract key entities and operations
+const keywords = extractKeywords(task_description);
+// Examples: ["User", "model", "authentication", "JWT", "reporting"]
+```
 
-## Error Handling
+**Step 3: Search Archive for Relevant Sessions**
+```javascript
+// Query manifest for sessions with matching tags or descriptions
+const relevantArchives = archives.filter(archive => {
+  return archive.tags.some(tag => keywords.includes(tag)) ||
+         keywords.some(kw => archive.description.toLowerCase().includes(kw.toLowerCase()));
+});
+```
 
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Package validation failed | Invalid session_id in existing package | Re-run agent to regenerate |
-| Agent execution timeout | Large codebase or slow MCP | Increase timeout, check code-index status |
-| Missing required fields | Agent incomplete execution | Check agent logs, verify schema compliance |
-| File count exceeds limit | Too many relevant files | Agent should auto-prioritize top 50 by relevance |
+**Step 4: Extract Watch Patterns**
+```javascript
+// For each relevant archive, check watch_patterns for applicability
+const historicalConflicts = [];
+
+relevantArchives.forEach(archive => {
+  archive.lessons.watch_patterns?.forEach(pattern => {
+    // Check if pattern trigger matches current task
+    if (isPatternRelevant(pattern.pattern, task_description)) {
+      historicalConflicts.push({
+        source_session: archive.session_id,
+        pattern: pattern.pattern,
+        action: pattern.action,
+        files_to_check: pattern.related_files,
+        archived_at: archive.archived_at
+      });
+    }
+  });
+});
+```
+
+**Step 5: Inject into Context Package**
+```json
+{
+  "conflict_detection": {
+    "risk_level": "medium",
+    "risk_factors": ["..."],
+    "affected_modules": ["..."],
+    "mitigation_strategy": "...",
+    "historical_conflicts": [
+      {
+        "source_session": "WFS-auth-feature",
+        "pattern": "When modifying User model",
+        "action": "Check reporting-service and auditing-service dependencies",
+        "files_to_check": ["src/models/User.ts", "src/services/reporting.ts"],
+        "archived_at": "2025-09-16T09:00:00Z"
+      }
+    ]
+  }
+}
+```
+
+### Risk Level Escalation
+
+If `historical_conflicts` array is not empty, minimum risk level should be "medium":
+
+```javascript
+if (historicalConflicts.length > 0 && currentRisk === "low") {
+  conflict_detection.risk_level = "medium";
+  conflict_detection.risk_factors.push(
+    `${historicalConflicts.length} historical conflict pattern(s) detected from past sessions`
+  );
+}
+```
+
+### Archive Query Algorithm
+
+```markdown
+1. IF .workflow/archives/manifest.json does NOT exist → Skip Track 1, continue to Track 2
+2. IF manifest exists:
+   a. Load manifest.json
+   b. Extract keywords from task_description (nouns, verbs, technical terms)
+   c. Filter archives where:
+      - ANY tag matches keywords (case-insensitive) OR
+      - description contains keywords (case-insensitive substring match)
+   d. For each relevant archive:
+      - Read lessons.watch_patterns array
+      - Check if pattern.pattern keywords overlap with task_description
+      - If relevant: Add to historical_conflicts array
+   e. IF historical_conflicts.length > 0:
+      - Set risk_level = max(current_risk, "medium")
+      - Add to risk_factors
+3. Continue to Track 2 (reference documentation)
+```
 
 ## Notes
 
 - **Detection-first**: Always check for existing package before invoking agent
+- **Project.json integration**: Agent reads `.workflow/project.json` as primary source for project context, avoiding redundant analysis
 - **Agent autonomy**: Agent handles all discovery logic per `.claude/agents/context-search-agent.md`
 - **No redundancy**: This command is a thin orchestrator, all logic in agent
 - **Plan-specific**: Use this for implementation planning; brainstorm mode uses direct agent call

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

@@ -1,362 +1,120 @@
 ---
 name: task-generate-agent
-description: Autonomous task generation using action-planning-agent with discovery and output phases
+description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation
 argument-hint: "--session WFS-session-id [--cli-execute]"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
   - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
 ---
 
-# Autonomous Task Generation Command
+# Generate Implementation Plan Command
 
 ## Overview
-Autonomous task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes.
+Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent. This command produces **planning artifacts only** - it does NOT execute code implementation. Actual code implementation requires separate execution command (e.g., /workflow:execute).
 
 ## Core Philosophy
-- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
-- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
+- **Planning Only**: Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT implement code
+- **Agent-Driven Document Generation**: Delegate plan generation to action-planning-agent
+- **Progressive Loading**: Load context incrementally (Core → Selective → On-Demand) due to analysis.md file size
+- **Two-Phase Flow**: Discovery (context gathering) → Output (planning document generation)
 - **Memory-First**: Reuse loaded documents from conversation memory
+- **Smart Selection**: Load synthesis_output OR guidance + relevant role analyses, NOT all role analyses
 - **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
-- **Pre-Selected Templates**: Command selects correct template based on `--cli-execute` flag **before** invoking agent
-- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
 
-## Execution Lifecycle
+## Document Generation Lifecycle
 
-### Phase 1: Discovery & Context Loading
-**⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
+### Phase 1: Context Preparation (Command Responsibility)
 
-**Agent Context Package**:
-```javascript
-{
-  "session_id": "WFS-[session-id]",
-  "execution_mode": "agent-mode" | "cli-execute-mode",  // Determined by flag
-  "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
-                           | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
-  // Path selected by command based on --cli-execute flag, agent reads it
-  "session_metadata": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/workflow-session.json
-  },
-  "brainstorm_artifacts": {
-    // Loaded from context-package.json → brainstorm_artifacts section
-    "role_analyses": [
-      {
-        "role": "system-architect",
-        "files": [{"path": "...", "type": "primary|supplementary"}]
-      }
-    ],
-    "guidance_specification": {"path": "...", "exists": true},
-    "synthesis_output": {"path": "...", "exists": true},
-    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
-  },
-  "context_package_path": ".workflow/{session-id}/.process/context-package.json",
-  "context_package": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/{session-id}/.process/context-package.json
-  },
-  "mcp_capabilities": {
-    "code_index": true,
-    "exa_code": true,
-    "exa_web": true
-  }
-}
+**Command prepares session paths and metadata for planning document generation.**
+
+**Session Path Structure**:
+```
+.workflow/active/WFS-{session-id}/
+├── workflow-session.json          # Session metadata
+├── .process/
+│   └── context-package.json       # Context package with artifact catalog
+├── .task/                         # Output: Task JSON files
+├── IMPL_PLAN.md                   # Output: Implementation plan
+└── TODO_LIST.md                   # Output: TODO list
 ```
 
-**Discovery Actions**:
-1. **Load Session Context** (if not in memory)
-   ```javascript
-   if (!memory.has("workflow-session.json")) {
-     Read(.workflow/{session-id}/workflow-session.json)
-   }
-   ```
+**Command Preparation**:
+1. **Assemble Session Paths** for agent prompt:
+   - `session_metadata_path`
+   - `context_package_path`
+   - Output directory paths
 
-2. **Load Context Package** (if not in memory)
-   ```javascript
-   if (!memory.has("context-package.json")) {
-     Read(.workflow/{session-id}/.process/context-package.json)
-   }
-   ```
+2. **Provide Metadata** (simple values):
+   - `session_id`
+   - `execution_mode` (agent-mode | cli-execute-mode)
+   - `mcp_capabilities` (available MCP tools)
 
-3. **Extract & Load Role Analyses** (from context-package.json)
-   ```javascript
-   // Extract role analysis paths from context package
-   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
-     .flatMap(role => role.files.map(f => f.path));
+### Phase 2: Planning Document Generation (Agent Responsibility)
 
-   // Load each role analysis file
-   roleAnalysisPaths.forEach(path => Read(path));
-   ```
-
-4. **Load Conflict Resolution** (from context-package.json, if exists)
-   ```javascript
-   if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
-     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
-   }
-   ```
-
-5. **Code Analysis with Native Tools** (optional - enhance understanding)
-   ```bash
-   # Find relevant files for task context
-   find . -name "*auth*" -type f
-   rg "authentication|oauth" -g "*.ts"
-   ```
-
-6. **MCP External Research** (optional - gather best practices)
-   ```javascript
-   // Get external examples for implementation
-   mcp__exa__get_code_context_exa(
-     query="TypeScript JWT authentication best practices",
-     tokensNum="dynamic"
-   )
-   ```
-
-### Phase 2: Agent Execution (Document Generation)
-
-**Pre-Agent Template Selection** (Command decides path before invoking agent):
-```javascript
-// Command checks flag and selects template PATH (not content)
-const templatePath = hasCliExecuteFlag
-  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
-  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
-```
+**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.
 
 **Agent Invocation**:
 ```javascript
 Task(
   subagent_type="action-planning-agent",
-  description="Generate task JSON and implementation plan",
+  description="Generate planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
   prompt=`
-## Execution Context
+## TASK OBJECTIVE
+Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
 
-**Session ID**: WFS-{session-id}
-**Execution Mode**: {agent-mode | cli-execute-mode}
-**Task JSON Template Path**: {template_path}
+IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.
 
-## Phase 1: Discovery Results (Provided Context)
+CRITICAL: Follow the progressive loading strategy defined in agent specification (load analysis.md files incrementally due to file size)
 
-### Session Metadata
-{session_metadata_content}
+## SESSION PATHS
+Input:
+  - Session Metadata: .workflow/active/{session-id}/workflow-session.json
+  - Context Package: .workflow/active/{session-id}/.process/context-package.json
 
-### Role Analyses (Enhanced by Synthesis)
-{role_analyses_content}
-- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
+Output:
+  - Task Dir: .workflow/active/{session-id}/.task/
+  - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
+  - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
 
-### Artifacts Inventory
-- **Guidance Specification**: {guidance_spec_path}
-- **Role Analyses**: {role_analyses_list}
+## CONTEXT METADATA
+Session ID: {session-id}
+Planning Mode: {agent-mode | cli-execute-mode}
+MCP Capabilities: {exa_code, exa_web, code_index}
 
-### Context Package
-{context_package_summary}
-- Includes conflict_risk assessment
+## EXPECTED DELIVERABLES
+1. Task JSON Files (.task/IMPL-*.json)
+   - 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
+   - Quantified requirements with explicit counts
+   - Artifacts integration from context package
+   - Flow control with pre_analysis steps
 
-### Conflict Resolution (Conditional)
-If conflict_risk was medium/high, modifications have been applied to:
-- **guidance-specification.md**: Design decisions updated to resolve conflicts
-- **Role analyses (*.md)**: Recommendations adjusted for compatibility
-- **context-package.json**: Marked as "resolved" with conflict IDs
-- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
+2. Implementation Plan (IMPL_PLAN.md)
+   - Context analysis and artifact references
+   - Task breakdown and execution strategy
+   - Complete structure per agent definition
 
-### MCP Analysis Results (Optional)
-**Code Structure**: {mcp_code_index_results}
-**External Research**: {mcp_exa_research_results}
+3. TODO List (TODO_LIST.md)
+   - Hierarchical structure (containers, pending, completed markers)
+   - Links to task JSONs and summaries
+   - Matches task JSON hierarchy
 
-## Phase 2: Document Generation Task
+## QUALITY STANDARDS
+Hard Constraints:
+  - Task count <= 12 (hard limit - request re-scope if exceeded)
+  - All requirements quantified (explicit counts and enumerated lists)
+  - Acceptance criteria measurable (include verification commands)
+  - Artifact references mapped from context package
+  - All documents follow agent-defined structure
 
-### Task Decomposition Standards
-**Core Principle**: Task Merging Over Decomposition
-- **Merge Rule**: Execute together when possible
-- **Decompose Only When**:
-  - Excessive workload (>2500 lines or >6 files)
-  - Different tech stacks or domains
-  - Sequential dependency blocking
-  - Parallel execution needed
-
-**Task Limits**:
-- **Maximum 10 tasks** (hard limit)
-- **Function-based**: Complete units (logic + UI + tests + config)
-- **Hierarchy**: Flat (≤5) | Two-level (6-10) | Re-scope (>10)
-
-### Required Outputs
-
-#### 1. Task JSON Files (.task/IMPL-*.json)
-**Location**: .workflow/{session-id}/.task/
-**Template**: Read from the template path provided above
-
-**Task JSON Template Loading**:
-\`\`\`
-Read({template_path})
-\`\`\`
-
-**Important**:
-- Read the template from the path provided in context
-- Use the template structure exactly as written
-- Replace placeholder variables ({synthesis_spec_path}, {role_analysis_path}, etc.) with actual session-specific paths
-- Include MCP tool integration in pre_analysis steps
-- Map artifacts based on task domain (UI → ui-designer, Backend → system-architect)
-
-#### 2. IMPL_PLAN.md
-**Location**: .workflow/{session-id}/IMPL_PLAN.md
-
-**IMPL_PLAN Template**:
-\`\`\`
-$(cat ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt)
-\`\`\`
-
-**Important**:
-- Use the template above for IMPL_PLAN.md generation
-- Replace all {placeholder} variables with actual session-specific values
-- Populate CCW Workflow Context based on actual phase progression
-- Extract content from role analyses and context-package.json
-- List all detected brainstorming artifacts with correct paths (role analyses, guidance-specification.md)
-- Include conflict resolution status if CONFLICT_RESOLUTION.md exists
-
-#### 3. TODO_LIST.md
-**Location**: .workflow/{session-id}/TODO_LIST.md
-**Structure**:
-\`\`\`markdown
-# Tasks: {Session Topic}
-
-## Task Progress
-▸ **IMPL-001**: [Main Task Group] → [📋](./.task/IMPL-001.json)
-  - [ ] **IMPL-001.1**: [Subtask] → [📋](./.task/IMPL-001.1.json)
-  - [ ] **IMPL-001.2**: [Subtask] → [📋](./.task/IMPL-001.2.json)
-
-- [ ] **IMPL-002**: [Simple Task] → [📋](./.task/IMPL-002.json)
-
-## Status Legend
-- \`▸\` = Container task (has subtasks)
-- \`- [ ]\` = Pending leaf task
-- \`- [x]\` = Completed leaf task
-\`\`\`
-
-### Execution Instructions for Agent
-
-**Agent Task**: Generate task JSON files, IMPL_PLAN.md, and TODO_LIST.md based on analysis results
-
-**Note**: The correct task JSON template path has been pre-selected by the command based on the `--cli-execute` flag and is provided in the context as `{template_path}`.
-
-**Step 1: Load Task JSON Template**
-- Read template from the provided path: `Read({template_path})`
-- This template is already the correct one based on execution mode
-
-**Step 2: Extract and Decompose Tasks**
-- Parse role analysis.md files for requirements, design specs, and task recommendations
-- Review synthesis enhancements and clarifications in role analyses
-- Apply conflict resolution strategies (if CONFLICT_RESOLUTION.md exists)
-- Apply task merging rules (merge when possible, decompose only when necessary)
-- Map artifacts to tasks based on domain (UI → ui-designer, Backend → system-architect, Data → data-architect)
-- Ensure task count ≤10
-
-**Step 3: Generate Task JSON Files**
-- Use the template structure from Step 1
-- Create .task/IMPL-*.json files with proper structure
-- Replace all {placeholder} variables with actual session paths
-- Embed artifacts array with brainstorming outputs
-- Include MCP tool integration in pre_analysis steps
-
-**Step 4: Create IMPL_PLAN.md**
-- Use IMPL_PLAN template
-- Populate all sections with session-specific content
-- List artifacts with priorities and usage guidelines
-- Document execution strategy and dependencies
-
-**Step 5: Generate TODO_LIST.md**
-- Create task progress checklist matching generated JSONs
-- Use proper status indicators (▸, [ ], [x])
-- Link to task JSON files
-
-**Step 6: Update Session State**
-- Update workflow-session.json with task count and artifact inventory
-- Mark session ready for execution
-
-### MCP Enhancement Examples
-
-**Code Index Usage**:
-\`\`\`javascript
-// Discover authentication-related files
-bash(find . -name "*auth*" -type f)
-
-// Search for OAuth patterns
-bash(rg "oauth|jwt|authentication" -g "*.{ts,js}")
-
-// Get file summary for key components
-bash(rg "^(class|function|export|interface)" src/auth/index.ts)
-\`\`\`
-
-**Exa Research Usage**:
-\`\`\`javascript
-// Get best practices for task implementation
-mcp__exa__get_code_context_exa(
-  query="TypeScript OAuth2 implementation patterns",
-  tokensNum="dynamic"
-)
-
-// Research specific API usage
-mcp__exa__get_code_context_exa(
-  query="Express.js JWT middleware examples",
-  tokensNum=5000
-)
-\`\`\`
-
-### Quality Validation
-
-Before completion, verify:
-- [ ] All task JSON files created in .task/ directory
-- [ ] Each task JSON has 5 required fields
-- [ ] Artifact references correctly mapped
-- [ ] Flow control includes artifact loading steps
-- [ ] MCP tool integration added where appropriate
-- [ ] IMPL_PLAN.md follows required structure
-- [ ] TODO_LIST.md matches task JSONs
-- [ ] Dependency graph is acyclic
-- [ ] Task count within limits (≤10)
-- [ ] Session state updated
-
-## Output
-
-Generate all three documents and report completion status:
-- Task JSON files created: N files
-- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
-- MCP enhancements: code-index, exa-research
-- Session ready for execution: /workflow:execute
+## SUCCESS CRITERIA
+- All planning documents generated successfully:
+  - Task JSONs valid and saved to .task/ directory
+  - IMPL_PLAN.md created with complete structure
+  - TODO_LIST.md generated matching task JSONs
+- Return completion status with document count and task breakdown summary
 `
 )
 ```
 
-
-### Agent Context Passing
-
-**Memory-Aware Context Assembly**:
-```javascript
-// Assemble context package for agent
-const agentContext = {
-  session_id: "WFS-[id]",
-
-  // Use memory if available, else load
-  session_metadata: memory.has("workflow-session.json")
-    ? memory.get("workflow-session.json")
-    : Read(.workflow/WFS-[id]/workflow-session.json),
-
-  context_package_path: ".workflow/WFS-[id]/.process/context-package.json",
-
-  context_package: memory.has("context-package.json")
-    ? memory.get("context-package.json")
-    : Read(".workflow/WFS-[id]/.process/context-package.json"),
-
-  // Extract brainstorm artifacts from context package
-  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
-
-  // Load role analyses using paths from context package
-  role_analyses: brainstorm_artifacts.role_analyses
-    .flatMap(role => role.files)
-    .map(file => Read(file.path)),
-
-  // Load conflict resolution if exists (from context package)
-  conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
-    ? Read(brainstorm_artifacts.conflict_resolution.path)
-    : null,
-
-  // Optional MCP enhancements
-  mcp_analysis: executeMcpDiscovery()
-}
-```
+、

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

@@ -1,14 +1,28 @@
 ---
 name: task-generate-tdd
-description: Generate TDD task chains with Red-Green-Refactor dependencies
-argument-hint: "--session WFS-session-id [--agent]"
-allowed-tools: Read(*), Write(*), Bash(gemini:*), TodoWrite(*)
+description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
+argument-hint: "--session WFS-session-id [--cli-execute]"
+examples:
+  - /workflow:tools:task-generate-tdd --session WFS-auth
+  - /workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
 ---
 
-# TDD Task Generation Command
+# Autonomous TDD Task Generation Command
 
 ## Overview
-Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.
+Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes. Generates complete Red-Green-Refactor cycles contained within each task.
+
+## Core Philosophy
+- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
+- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
+- **Memory-First**: Reuse loaded documents from conversation memory
+- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
+- **Pre-Selected Templates**: Command selects correct TDD template based on `--cli-execute` flag **before** invoking agent
+- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
+- **TDD-First**: Every feature starts with a failing test (Red phase)
+- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
+- **Quantification-Enforced**: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations
 
 ## Task Strategy & Philosophy
 
@@ -16,11 +30,6 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
 - **1 feature = 1 task** containing complete TDD cycle internally
 - Each task executes Red-Green-Refactor phases sequentially
 - Task count = Feature count (typically 5 features = 5 tasks)
-- **Benefits**:
-  - 70% reduction in task management overhead
-  - Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
-  - Simpler dependency management
-  - Maintains TDD rigor through internal phase structure
 
 **Previous Approach** (Deprecated):
 - 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
@@ -44,362 +53,333 @@ Generate TDD-specific tasks from analysis results with complete Red-Green-Refact
 - **Current approach**: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
 - **Complex features**: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary
 
-### Core Principles
-- **TDD-First**: Every feature starts with a failing test (Red phase)
-- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
-- **Phase-Explicit**: Internal phases clearly marked in flow_control.implementation_approach
-- **Task Merging**: Prefer single task per feature over decomposition
-- **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 feature-complete tasks with internal TDD cycles (1 task per simple feature)
-- Apply task merging strategy by default, create subtasks only when complexity requires
-- Generate IMPL_PLAN.md with TDD Implementation Tasks section
-- Generate TODO_LIST.md with internal TDD phase indicators
-- Update session state for TDD execution with task count compliance
-
 ## Execution Lifecycle
 
-### Phase 1: Input Validation & Discovery
-**Memory-First Rule**: Skip file loading if documents already in conversation memory
+### Phase 1: Discovery & Context Loading
+**⚡ 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. **Conflict Resolution Check** (NEW - Priority Input)
-   - If CONFLICT_RESOLUTION.md exists → Load selected strategies
-   - Else: Skip to brainstorming artifacts
-   - Path: `.workflow/{session_id}/.process/CONFLICT_RESOLUTION.md`
-
-3. **Artifact Discovery**
-   - If artifact inventory in memory → Skip scanning
-   - Else: Scan `.workflow/{session_id}/.brainstorming/` directory
-   - Detect: role analysis documents, guidance-specification.md, role analyses
-
-4. **Context Package Loading**
-   - Load `.workflow/{session_id}/.process/context-package.json`
-   - Load `.workflow/{session_id}/.process/test-context-package.json` (if exists)
-
-### Phase 2: TDD Task JSON Generation
-
-**Input Sources** (priority order):
-1. **Conflict Resolution** (if exists): `.process/CONFLICT_RESOLUTION.md` - Selected resolution strategies
-2. **Brainstorming Artifacts**: Role analysis documents (system-architect, product-owner, etc.)
-3. **Context Package**: `.process/context-package.json` - Project structure and requirements
-4. **Test Context**: `.process/test-context-package.json` - Existing test patterns
-
-**TDD Task Structure includes**:
-- Feature list with testable requirements
-- Test cases for Red phase
-- Implementation requirements for Green phase (with test-fix cycle)
-- Refactoring opportunities
-- Task dependencies and execution order
-- Conflict resolution decisions (if applicable)
-
-### Phase 3: Task JSON & IMPL_PLAN.md Generation
-
-#### Task Structure (Feature-Complete with Internal TDD)
-For each feature, generate task(s) with ID format:
-- **IMPL-N** - Single task containing complete TDD cycle (Red-Green-Refactor)
-- **IMPL-N.M** - Sub-tasks only when feature is complex (>2500 lines or technical blocking)
-
-**Task Dependency Rules**:
-- **Sequential features**: IMPL-2 depends_on ["IMPL-1"] if Feature 2 needs Feature 1
-- **Independent features**: No dependencies, can execute in parallel
-- **Complex features**: IMPL-N.2 depends_on ["IMPL-N.1"] for subtask ordering
-
-**Agent Assignment**:
-- **All IMPL tasks** → `@code-developer` (handles full TDD cycle)
-- Agent executes Red, Green, Refactor phases sequentially within task
-
-**Meta Fields**:
-- `meta.type`: "feature" (TDD-driven feature implementation)
-- `meta.agent`: "@code-developer"
-- `meta.tdd_workflow`: true (enables TDD-specific flow)
-- `meta.tdd_phase`: Not used (phases are in flow_control.implementation_approach)
-- `meta.max_iterations`: 3 (for Green phase test-fix cycle)
-- `meta.use_codex`: false (manual fixes by default)
-
-#### Task JSON Structure Reference
-
-**Simple Feature Task (IMPL-N.json)** - Recommended for most features:
-```json
+**Agent Context Package**:
+```javascript
 {
-  "id": "IMPL-N",                                  // Task identifier
-  "title": "Feature description with TDD",         // Human-readable title
-  "status": "pending",                             // pending | in_progress | completed | container
-  "context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
-  "meta": {
-    "type": "feature",                             // Task type
-    "agent": "@code-developer",                    // Assigned agent
-    "tdd_workflow": true,                          // REQUIRED: Enables TDD flow
-    "max_iterations": 3,                           // Green phase test-fix cycle limit
-    "use_codex": false                             // false=manual fixes, true=Codex automated fixes
+  "session_id": "WFS-[session-id]",
+  "execution_mode": "agent-mode" | "cli-execute-mode",  // Determined by flag
+  "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
+                           | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
+  // Path selected by command based on --cli-execute flag, agent reads it
+  "workflow_type": "tdd",
+  "session_metadata": {
+    // If in memory: use cached content
+    // Else: Load from .workflow/active//{session-id}/workflow-session.json
   },
-  "context": {
-    "requirements": [                              // Feature requirements with TDD phases
-      "Feature description",
-      "Red: Test scenarios to write",
-      "Green: Implementation approach with test-fix cycle",
-      "Refactor: Code quality improvements"
-    ],
-    "tdd_cycles": [                                // OPTIONAL: Detailed test cycles
+  "brainstorm_artifacts": {
+    // Loaded from context-package.json → brainstorm_artifacts section
+    "role_analyses": [
       {
-        "cycle": 1,
-        "feature": "Specific functionality",
-        "test_focus": "What to test",
-        "expected_failure": "Why test should fail initially"
+        "role": "system-architect",
+        "files": [{"path": "...", "type": "primary|supplementary"}]
       }
     ],
-    "focus_paths": ["src/path/", "tests/path/"],  // Files to modify
-    "acceptance": [                                // Success criteria
-      "All tests pass (Red → Green)",
-      "Code refactored (Refactor complete)",
-      "Test coverage ≥80%"
-    ],
-    "depends_on": []                               // Task dependencies
+    "guidance_specification": {"path": "...", "exists": true},
+    "synthesis_output": {"path": "...", "exists": true},
+    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
   },
-  "flow_control": {
-    "pre_analysis": [                              // OPTIONAL: Pre-execution checks
-      {
-        "step": "check_test_framework",
-        "action": "Verify test framework",
-        "command": "bash(npm list jest)",
-        "output_to": "test_framework_info",
-        "on_error": "warn"
-      }
-    ],
-    "implementation_approach": [                   // REQUIRED: 3 TDD phases
-      {
-        "step": 1,
-        "title": "RED Phase: Write failing tests",
-        "tdd_phase": "red",                        // REQUIRED: Phase identifier
-        "description": "Write comprehensive failing tests",
-        "modification_points": ["Files/changes to make"],
-        "logic_flow": ["Step-by-step process"],
-        "acceptance": ["Phase success criteria"],
-        "depends_on": [],
-        "output": "failing_tests"
-      },
-      {
-        "step": 2,
-        "title": "GREEN Phase: Implement to pass tests",
-        "tdd_phase": "green",                      // REQUIRED: Phase identifier
-        "description": "Minimal implementation with test-fix cycle",
-        "modification_points": ["Implementation files"],
-        "logic_flow": [
-          "Implement minimal code",
-          "Run tests",
-          "If fail → Enter iteration loop (max 3):",
-          "  1. Extract failure messages",
-          "  2. Gemini bug-fix diagnosis",
-          "  3. Apply fixes",
-          "  4. Rerun tests",
-          "If max_iterations → Auto-revert"
-        ],
-        "acceptance": ["All tests pass"],
-        "command": "bash(npm test -- tests/path/)",
-        "depends_on": [1],
-        "output": "passing_implementation"
-      },
-      {
-        "step": 3,
-        "title": "REFACTOR Phase: Improve code quality",
-        "tdd_phase": "refactor",                   // REQUIRED: Phase identifier
-        "description": "Refactor while keeping tests green",
-        "modification_points": ["Quality improvements"],
-        "logic_flow": ["Incremental refactoring with test verification"],
-        "acceptance": ["Tests still pass", "Code quality improved"],
-        "command": "bash(npm run lint && npm test)",
-        "depends_on": [2],
-        "output": "refactored_implementation"
-      }
-    ],
-    "post_completion": [                           // OPTIONAL: Final verification
-      {
-        "step": "verify_full_tdd_cycle",
-        "action": "Confirm complete TDD cycle",
-        "command": "bash(npm test && echo 'TDD complete')",
-        "output_to": "final_validation",
-        "on_error": "fail"
-      }
-    ],
-    "error_handling": {                            // OPTIONAL: Error recovery
-      "green_phase_max_iterations": {
-        "action": "revert_all_changes",
-        "commands": ["bash(git reset --hard HEAD)"],
-        "report": "Generate failure report"
-      }
-    }
+  "context_package_path": ".workflow/active//{session-id}/.process/context-package.json",
+  "context_package": {
+    // If in memory: use cached content
+    // Else: Load from .workflow/active//{session-id}/.process/context-package.json
+  },
+  "test_context_package_path": ".workflow/active//{session-id}/.process/test-context-package.json",
+  "test_context_package": {
+    // Existing test patterns and coverage analysis
+  },
+  "mcp_capabilities": {
+    "code_index": true,
+    "exa_code": true,
+    "exa_web": true
   }
 }
 ```
 
-**Key JSON Fields Summary**:
-- `meta.tdd_workflow`: Must be `true`
-- `meta.max_iterations`: Green phase fix cycle limit (default: 3)
-- `meta.use_codex`: Automated fixes (false=manual, true=Codex)
-- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase`: "red", "green", "refactor"
-- `context.tdd_cycles`: Optional detailed test cycle specifications
-- `context.parent`: Required for subtasks (IMPL-N.M)
+**Discovery Actions**:
+1. **Load Session Context** (if not in memory)
+   ```javascript
+   if (!memory.has("workflow-session.json")) {
+     Read(.workflow/active//{session-id}/workflow-session.json)
+   }
+   ```
 
-#### IMPL_PLAN.md Structure
+2. **Load Context Package** (if not in memory)
+   ```javascript
+   if (!memory.has("context-package.json")) {
+     Read(.workflow/active//{session-id}/.process/context-package.json)
+   }
+   ```
 
-Generate IMPL_PLAN.md with 8-section structure:
+3. **Load Test Context Package** (if not in memory)
+   ```javascript
+   if (!memory.has("test-context-package.json")) {
+     Read(.workflow/active//{session-id}/.process/test-context-package.json)
+   }
+   ```
 
-**Frontmatter** (required fields):
-```yaml
----
-identifier: WFS-{session-id}
-source: "User requirements" | "File: path"
-conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md  # if exists
-context_package: .workflow/{session-id}/.process/context-package.json
-context_package_path: .workflow/{session-id}/.process/context-package.json
-test_context: .workflow/{session-id}/.process/test-context-package.json  # if exists
-workflow_type: "tdd"
-verification_history:
-  conflict_resolution: "executed | skipped" # based on conflict_risk
-  action_plan_verify: "pending"
-phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
-feature_count: N
-task_count: N  # ≤10 total
-task_breakdown:
-  simple_features: K
-  complex_features: L
-  total_subtasks: M
-tdd_workflow: true
----
+4. **Extract & Load Role Analyses** (from context-package.json)
+   ```javascript
+   // Extract role analysis paths from context package
+   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
+     .flatMap(role => role.files.map(f => f.path));
+
+   // Load each role analysis file
+   roleAnalysisPaths.forEach(path => Read(path));
+   ```
+
+5. **Load Conflict Resolution** (from context-package.json, if exists)
+   ```javascript
+   if (contextPackage.brainstorm_artifacts.conflict_resolution?.exists) {
+     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
+   }
+   ```
+
+6. **Code Analysis with Native Tools** (optional - enhance understanding)
+   ```bash
+   # Find relevant test files and patterns
+   find . -name "*test*" -type f
+   rg "describe|it\(|test\(" -g "*.ts"
+   ```
+
+7. **MCP External Research** (optional - gather TDD best practices)
+   ```javascript
+   // Get external TDD examples and patterns
+   mcp__exa__get_code_context_exa(
+     query="TypeScript TDD best practices Red-Green-Refactor",
+     tokensNum="dynamic"
+   )
+   ```
+
+### Phase 2: Agent Execution (Document Generation)
+
+**Pre-Agent Template Selection** (Command decides path before invoking agent):
+```javascript
+// Command checks flag and selects template PATH (not content)
+const templatePath = hasCliExecuteFlag
+  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
+  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
 ```
 
-**8 Sections Structure**:
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="action-planning-agent",
+  description="Generate TDD task JSON and implementation plan",
+  prompt=`
+## Execution Context
 
-```markdown
-# Implementation Plan: {Project Title}
+**Session ID**: WFS-{session-id}
+**Workflow Type**: TDD
+**Execution Mode**: {agent-mode | cli-execute-mode}
+**Task JSON Template Path**: {template_path}
 
-## 1. Summary
-- Core requirements and objectives (2-3 paragraphs)
-- TDD-specific technical approach
+## Phase 1: Discovery Results (Provided Context)
 
-## 2. Context Analysis
-- CCW Workflow Context (Phase progression, Quality gates)
-- Context Package Summary (Focus paths, Test context)
-- Project Profile (Type, Scale, Tech Stack, Timeline)
-- Module Structure (Directory tree)
-- Dependencies (Primary, Testing, Development)
-- Patterns & Conventions
+### Session Metadata
+{session_metadata_content}
 
-## 3. Brainstorming Artifacts Reference
-- Artifact Usage Strategy
-  - CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
-  - role analysis documents (primary reference)
-  - test-context-package.json (test patterns)
-  - context-package.json (smart context)
-- Artifact Priority in Development
+### Role Analyses (Enhanced by Synthesis)
+{role_analyses_content}
+- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
 
-## 4. Implementation Strategy
-- Execution Strategy (TDD Cycles: Red-Green-Refactor)
-- Architectural Approach
-- Key Dependencies (Task dependency graph)
-- Testing Strategy (Coverage targets, Quality gates)
+### Artifacts Inventory
+- **Guidance Specification**: {guidance_spec_path}
+- **Role Analyses**: {role_analyses_list}
 
-## 5. TDD Implementation Tasks
-- Feature-by-Feature TDD Tasks
-  - Each task: IMPL-N with internal Red → Green → Refactor
-  - Dependencies and complexity metrics
-- Complex Feature Examples (when subtasks needed)
-- TDD Task Breakdown Summary
+### Context Package
+{context_package_summary}
+- Includes conflict_risk assessment
 
-## 6. Implementation Plan (Detailed Phased Breakdown)
-- Execution Strategy (feature-by-feature sequential)
-- Phase breakdown (Phase 1, Phase 2, etc.)
-- Resource Requirements (Team, Dependencies, Infrastructure)
+### Test Context Package
+{test_context_package_summary}
+- Existing test patterns, framework config, coverage analysis
 
-## 7. Risk Assessment & Mitigation
-- Risk table (Risk, Impact, Probability, Mitigation, Owner)
-- Critical Risks (TDD-specific)
-- Monitoring Strategy
+### Conflict Resolution (Conditional)
+If conflict_risk was medium/high, modifications have been applied to:
+- **guidance-specification.md**: Design decisions updated to resolve conflicts
+- **Role analyses (*.md)**: Recommendations adjusted for compatibility
+- **context-package.json**: Marked as "resolved" with conflict IDs
+- NO separate CONFLICT_RESOLUTION.md file (conflicts resolved in-place)
 
-## 8. Success Criteria
-- Functional Completeness
-- Technical Quality (Test coverage ≥80%)
-- Operational Readiness
-- TDD Compliance
+### MCP Analysis Results (Optional)
+**Code Structure**: {mcp_code_index_results}
+**External Research**: {mcp_exa_research_results}
+
+## Phase 2: TDD Document Generation Task
+
+**Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent.
+
+Refer to: @.claude/agents/action-planning-agent.md for:
+- TDD Task Decomposition Standards
+- Red-Green-Refactor Cycle Requirements
+- Quantification Requirements (MANDATORY)
+- 5-Field Task JSON Schema
+- IMPL_PLAN.md Structure (TDD variant)
+- TODO_LIST.md Format
+- TDD Execution Flow & Quality Validation
+
+### TDD-Specific Requirements Summary
+
+#### Task Structure Philosophy
+- **1 feature = 1 task** containing complete TDD cycle internally
+- Each task executes Red-Green-Refactor phases sequentially
+- Task count = Feature count (typically 5 features = 5 tasks)
+- Subtasks only when complexity >2500 lines or >6 files per cycle
+- **Maximum 10 tasks** (hard limit for TDD workflows)
+
+#### TDD Cycle Mapping
+- **Simple features**: IMPL-N with internal Red-Green-Refactor phases
+- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks)
+- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage
+
+#### Required Outputs Summary
+
+##### 1. TDD Task JSON Files (.task/IMPL-*.json)
+- **Location**: `.workflow/active//{session-id}/.task/`
+- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
+- **Schema**: 5-field structure with TDD-specific metadata
+  - `meta.tdd_workflow`: true (REQUIRED)
+  - `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
+  - `meta.use_codex`: false (manual fixes by default)
+  - `context.tdd_cycles`: Array with quantified test cases and coverage
+  - `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
+    1. Red Phase (`tdd_phase: "red"`): Write failing tests
+    2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
+    3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
+- **Details**: See action-planning-agent.md § TDD Task JSON Generation
+
+##### 2. IMPL_PLAN.md (TDD Variant)
+- **Location**: `.workflow/active//{session-id}/IMPL_PLAN.md`
+- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
+- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
+- **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
+- **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
+
+##### 3. TODO_LIST.md
+- **Location**: `.workflow/active//{session-id}/TODO_LIST.md`
+- **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
+- **Status**: ▸ (container), [ ] (pending), [x] (completed)
+- **Details**: See action-planning-agent.md § TODO List Generation
+
+### Quantification Requirements (MANDATORY)
+
+**Core Rules**:
+1. **Explicit Test Case Counts**: Red phase specifies exact number with enumerated list
+2. **Quantified Coverage**: Acceptance includes measurable percentage (e.g., ">=85%")
+3. **Detailed Implementation Scope**: Green phase enumerates files, functions, line counts
+4. **Enumerated Refactoring Targets**: Refactor phase lists specific improvements with counts
+
+**TDD Phase Formats**:
+- **Red Phase**: "Write N test cases: [test1, test2, ...]"
+- **Green Phase**: "Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"
+- **Refactor Phase**: "Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"
+- **Acceptance**: "All N tests pass with >=X% coverage: verify by [test command]"
+
+**Validation Checklist**:
+- [ ] Every Red phase specifies exact test case count with enumerated list
+- [ ] Every Green phase enumerates files, functions, and estimated line counts
+- [ ] Every Refactor phase lists specific improvements with counts
+- [ ] Every acceptance criterion includes measurable coverage percentage
+- [ ] tdd_cycles array contains test_count and test_cases for each cycle
+- [ ] No vague language ("comprehensive", "complete", "thorough")
+
+### Agent Execution Summary
+
+**Key Steps** (Detailed instructions in action-planning-agent.md):
+1. Load task JSON template from provided path
+2. Extract and decompose features with TDD cycles
+3. Generate TDD task JSON files enforcing quantification requirements
+4. Create IMPL_PLAN.md using TDD template variant
+5. Generate TODO_LIST.md with TDD phase indicators
+6. Update session state with TDD metadata
+
+**Quality Gates** (Full checklist in action-planning-agent.md):
+- ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
+- ✓ Task count ≤10 (hard limit)
+- ✓ Each task has meta.tdd_workflow: true
+- ✓ Each task has exactly 3 implementation steps with tdd_phase field
+- ✓ Green phase includes test-fix cycle logic
+- ✓ Artifact references mapped correctly
+- ✓ MCP tool integration added
+- ✓ Documents follow TDD template structure
+
+## Output
+
+Generate all three documents and report completion status:
+- TDD task JSON files created: N files (IMPL-*.json)
+- TDD cycles configured: N cycles with quantified test cases
+- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
+- Test context integrated: existing patterns and coverage
+- MCP enhancements: code-index, exa-research
+- Session ready for TDD execution: /workflow:execute
+`
+)
 ```
 
-### Phase 4: TODO_LIST.md Generation
+### Agent Context Passing
 
-Generate task list with internal TDD phase indicators:
+**Memory-Aware Context Assembly**:
+```javascript
+// Assemble context package for agent
+const agentContext = {
+  session_id: "WFS-[id]",
+  workflow_type: "tdd",
 
-**For Simple Features (1 task per feature)**:
-```markdown
-## TDD Implementation Tasks
+  // Use memory if available, else load
+  session_metadata: memory.has("workflow-session.json")
+    ? memory.get("workflow-session.json")
+    : Read(.workflow/active/WFS-[id]/workflow-session.json),
 
-### Feature 1: {Feature Name}
-- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
-  - Internal phases: Red → Green → Refactor
-  - Dependencies: None
+  context_package_path: ".workflow/active/WFS-[id]/.process/context-package.json",
 
-### Feature 2: {Feature Name}
-- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
-  - Internal phases: Red → Green → Refactor
-  - Dependencies: IMPL-1
-```
+  context_package: memory.has("context-package.json")
+    ? memory.get("context-package.json")
+    : Read(".workflow/active/WFS-[id]/.process/context-package.json"),
 
-**For Complex Features (with subtasks)**:
-```markdown
-### Feature 3: {Complex Feature Name}
-▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
-  - [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
-    - Internal phases: Red → Green → Refactor
-  - [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
-    - Internal phases: Red → Green → Refactor
-    - Dependencies: IMPL-3.1
-```
+  test_context_package_path: ".workflow/active/WFS-[id]/.process/test-context-package.json",
 
-**Status Legend**:
-```markdown
-## Status Legend
-- ▸ = Container task (has subtasks)
-- [ ] = Pending task
-- [x] = Completed task
-- Red = Write failing tests
-- Green = Implement to pass tests (with test-fix cycle)
-- Refactor = Improve code quality
-```
+  test_context_package: memory.has("test-context-package.json")
+    ? memory.get("test-context-package.json")
+    : Read(".workflow/active/WFS-[id]/.process/test-context-package.json"),
 
-### Phase 5: Session State Update
+  // Extract brainstorm artifacts from context package
+  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
 
-Update workflow-session.json with TDD metadata:
-```json
-{
-  "workflow_type": "tdd",
-  "feature_count": 5,
-  "task_count": 5,
-  "task_breakdown": {
-    "simple_features": 4,
-    "complex_features": 1,
-    "total_subtasks": 2
-  },
-  "tdd_workflow": true,
-  "task_limit_compliance": true
+  // Load role analyses using paths from context package
+  role_analyses: brainstorm_artifacts.role_analyses
+    .flatMap(role => role.files)
+    .map(file => Read(file.path)),
+
+  // Load conflict resolution if exists (from context package)
+  conflict_resolution: brainstorm_artifacts.conflict_resolution?.exists
+    ? Read(brainstorm_artifacts.conflict_resolution.path)
+    : null,
+
+  // Optional MCP enhancements
+  mcp_analysis: executeMcpDiscovery()
 }
 ```
 
-**Task Count Calculation**:
-- **Simple features**: 1 task each (IMPL-N with internal TDD cycle)
-- **Complex features**: 1 container + M subtasks (IMPL-N + IMPL-N.M)
-- **Total**: Simple feature count + Complex feature subtask count
-- **Example**: 4 simple + 1 complex (with 2 subtasks) = 6 total tasks (not 15)
+## TDD Task Structure Reference
+
+This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
+
+**Quick Reference**:
+- Each TDD task contains complete Red-Green-Refactor cycle
+- Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks)
+- Required metadata: `meta.tdd_workflow: true`, `meta.max_iterations: 3`
+- Flow control: Exactly 3 steps with `tdd_phase` field (red, green, refactor)
+- Context: `tdd_cycles` array with quantified test cases and coverage
+- See Phase 2 agent prompt for full schema and requirements
 
 ## Output Files Structure
 ```
-.workflow/{session-id}/
+.workflow/active//{session-id}/
 ├── IMPL_PLAN.md                     # Unified plan with TDD Implementation Tasks section
 ├── TODO_LIST.md                     # Progress tracking with internal TDD phase indicators
 ├── .task/
@@ -464,52 +444,30 @@ Update workflow-session.json with TDD metadata:
 
 ## Integration & Usage
 
-### Command Chain
-- **Called By**: `/workflow:tdd-plan` (Phase 4)
-- **Calls**: Gemini CLI for TDD breakdown
-- **Followed By**: `/workflow:execute`, `/workflow:tdd-verify`
+**Command Chain**:
+- Called by: `/workflow:tdd-plan` (Phase 4)
+- Invokes: `action-planning-agent` for autonomous task generation
+- Followed by: `/workflow:execute`, `/workflow:tdd-verify`
 
-### Basic Usage
+**Basic Usage**:
 ```bash
-# Manual mode (default)
+# Agent mode (default, autonomous execution)
 /workflow:tools:task-generate-tdd --session WFS-auth
 
-# Agent mode (autonomous task generation)
-/workflow:tools:task-generate-tdd --session WFS-auth --agent
+# CLI tool mode (use Gemini/Qwen for generation)
+/workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
 ```
 
-### Expected Output
-```
-TDD task generation complete for session: WFS-auth
+**Execution Modes**:
+- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
+- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen with cli-mode task template
 
-Features analyzed: 5
-Total tasks: 5 (1 task per feature with internal TDD cycles)
-
-Task breakdown:
-- Simple features: 4 tasks (IMPL-1 to IMPL-4)
-- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
-- Total task count: 6 (within 10-task limit)
-
-Structure:
-- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
-- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
-- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
-- IMPL-4: Role Management (Internal: Red → Green → Refactor)
-- IMPL-5: Payment System (Container)
-  - IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
-  - IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)
-
-Plans generated:
-- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
-- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)
-
-TDD Configuration:
-- Each task contains complete Red-Green-Refactor cycle
-- Green phase includes test-fix cycle (max 3 iterations)
-- Auto-revert on max iterations reached
-
-Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth
-```
+**Output**:
+- TDD task JSON files in `.task/` directory (IMPL-N.json format)
+- IMPL_PLAN.md with TDD Implementation Tasks section
+- TODO_LIST.md with internal TDD phase indicators
+- Session state updated with task count and TDD metadata
+- MCP enhancements integrated (if available)
 
 ## Test Coverage Analysis Integration
 
@@ -536,19 +494,9 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
    - **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/tdd-coverage-analysis.md

@@ -1,6 +1,6 @@
 ---
 name: tdd-coverage-analysis
-description: Analyze test coverage and TDD cycle execution
+description: Analyze test coverage and TDD cycle execution with Red-Green-Refactor compliance verification
 argument-hint: "--session WFS-session-id"
 allowed-tools: Read(*), Write(*), Bash(*)
 ---
@@ -21,7 +21,7 @@ Analyze test coverage and verify Red-Green-Refactor cycle execution for TDD work
 
 ### Phase 1: Extract Test Tasks
 ```bash
-find .workflow/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
+find .workflow/active/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;
 ```
 
 **Output**: List of test directories/files from all TEST tasks
@@ -29,20 +29,20 @@ find .workflow/{session_id}/.task/ -name 'TEST-*.json' -exec jq -r '.context.foc
 ### Phase 2: Run Test Suite
 ```bash
 # Node.js/JavaScript
-npm test -- --coverage --json > .workflow/{session_id}/.process/test-results.json
+npm test -- --coverage --json > .workflow/active/{session_id}/.process/test-results.json
 
 # Python
-pytest --cov --json-report > .workflow/{session_id}/.process/test-results.json
+pytest --cov --json-report > .workflow/active/{session_id}/.process/test-results.json
 
 # Other frameworks (detect from project)
-[test_command] --coverage --json-output .workflow/{session_id}/.process/test-results.json
+[test_command] --coverage --json-output .workflow/active/{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
+jq '.coverage' .workflow/active/{session_id}/.process/test-results.json > .workflow/active/{session_id}/.process/coverage-report.json
 ```
 
 **Extract**:
@@ -58,7 +58,7 @@ 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
+cat .workflow/active/{session_id}/.summaries/TEST-N.M-summary.md
 ```
 
 Verify:
@@ -69,7 +69,7 @@ Verify:
 **2. Green Phase Verification**
 ```bash
 # Check IMPL task summary
-cat .workflow/{session_id}/.summaries/IMPL-N.M-summary.md
+cat .workflow/active/{session_id}/.summaries/IMPL-N.M-summary.md
 ```
 
 Verify:
@@ -80,7 +80,7 @@ Verify:
 **3. Refactor Phase Verification**
 ```bash
 # Check REFACTOR task summary
-cat .workflow/{session_id}/.summaries/REFACTOR-N.M-summary.md
+cat .workflow/active/{session_id}/.summaries/REFACTOR-N.M-summary.md
 ```
 
 Verify:
@@ -90,7 +90,7 @@ Verify:
 
 ### Phase 5: Generate Analysis Report
 
-Create `.workflow/{session_id}/.process/tdd-cycle-report.md`:
+Create `.workflow/active/{session_id}/.process/tdd-cycle-report.md`:
 
 ```markdown
 # TDD Cycle Analysis - {Session ID}
@@ -146,7 +146,7 @@ Create `.workflow/{session_id}/.process/tdd-cycle-report.md`:
 
 ## Output Files
 ```
-.workflow/{session-id}/
+.workflow/active//{session-id}/
 └── .process/
     ├── test-results.json         # Raw test execution results
     ├── coverage-report.json      # Parsed coverage data
@@ -272,10 +272,6 @@ Function Coverage: 91%
 
 Overall Compliance: 93/100
 
-Detailed report: .workflow/WFS-auth/.process/tdd-cycle-report.md
+Detailed report: .workflow/active/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

@@ -1,15 +1,15 @@
 ---
 name: test-concept-enhanced
-description: Analyze test requirements and generate test generation strategy using Gemini
+description: Coordinate test analysis workflow using cli-execution-agent to generate test strategy via Gemini
 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
+  - /workflow:tools:test-concept-enhanced --session WFS-test-auth --context .workflow/active/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.
+Workflow coordinator that delegates test analysis to cli-execution-agent. Agent executes 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
@@ -19,18 +19,19 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
 - **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
+- Coordinate test analysis workflow using cli-execution-agent
+- Validate test-context-package.json prerequisites
+- Execute Gemini analysis via agent for test strategy generation
+- Validate agent outputs (gemini-test-analysis.md, TEST_ANALYSIS_RESULTS.md)
 
 ## Execution Lifecycle
 
-### Phase 1: Validation & Preparation
+### Phase 1: Context Preparation (Command Responsibility)
+
+**Command prepares session context and validates prerequisites.**
 
 1. **Session Validation**
-   - Load `.workflow/{test_session_id}/workflow-session.json`
+   - Load `.workflow/active/{test_session_id}/workflow-session.json`
    - Verify test session type is "test-gen"
    - Extract source session reference
 
@@ -40,428 +41,100 @@ Specialized analysis tool for test generation workflows that uses Gemini to anal
    - 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
+   - **Simple** (1-3 files): Single Gemini analysis
+   - **Medium** (4-6 files): Comprehensive analysis
+   - **Complex** (>6 files): Modular analysis approach
 
-### Phase 2: Gemini Test Analysis
+### Phase 2: Test Analysis Execution (Agent Responsibility)
 
-**Tool Configuration**:
-```bash
-cd .workflow/{test_session_id}/.process && gemini -p "
-PURPOSE: Analyze test coverage gaps and design comprehensive test generation strategy
-TASK: Study implementation context, existing tests, and generate test requirements for missing coverage
-MODE: analysis
-CONTEXT: @{.workflow/{test_session_id}/.process/test-context-package.json}
+**Purpose**: Analyze test coverage gaps and generate comprehensive test strategy.
 
-**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
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="cli-execution-agent",
+  description="Analyze test coverage gaps and generate test strategy",
+  prompt=`
+## TASK OBJECTIVE
+Analyze test requirements and generate comprehensive test generation strategy using Gemini CLI
 
-**ANALYSIS REQUIREMENTS**:
+## EXECUTION CONTEXT
+Session: {test_session_id}
+Source Session: {source_session_id}
+Working Dir: .workflow/active/{test_session_id}/.process
+Template: ~/.claude/workflows/cli-templates/prompts/test/test-concept-analysis.txt
 
-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
+## EXECUTION STEPS
+1. Execute Gemini analysis:
+   cd .workflow/active/{test_session_id}/.process && gemini -p "$(cat ~/.claude/workflows/cli-templates/prompts/test/test-concept-analysis.txt)" --approval-mode yolo
 
-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
+2. Generate TEST_ANALYSIS_RESULTS.md:
+   Synthesize gemini-test-analysis.md into standardized format for task generation
+   Include: coverage assessment, test framework, test requirements, generation strategy, implementation targets
 
-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)
+## EXPECTED OUTPUTS
+1. gemini-test-analysis.md - Raw Gemini analysis
+2. TEST_ANALYSIS_RESULTS.md - Standardized test requirements document
 
-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
+## QUALITY VALIDATION
+- Both output files exist and are complete
+- All required sections present in TEST_ANALYSIS_RESULTS.md
+- Test requirements are actionable and quantified
+- Test scenarios cover happy path, errors, edge cases
+- Dependencies and mocks clearly identified
+`
+)
 ```
 
-**Output Location**: `.workflow/{test_session_id}/.process/gemini-test-analysis.md`
+**Output Files**:
+- `.workflow/active/{test_session_id}/.process/gemini-test-analysis.md`
+- `.workflow/active/{test_session_id}/.process/TEST_ANALYSIS_RESULTS.md`
 
-### Phase 3: Results Synthesis
+### Phase 3: Output Validation (Command Responsibility)
 
-1. **Output Validation**
-   - Verify `gemini-test-analysis.md` exists and is complete
-   - Validate all required sections present
-   - Check test requirements are actionable
+**Command validates agent outputs.**
 
-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`
+- Verify `gemini-test-analysis.md` exists and is complete
+- Validate `TEST_ANALYSIS_RESULTS.md` generated by agent
+- Check required sections present
+- Confirm test requirements are actionable
 
 ## 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 |
+| Error | Resolution |
+|-------|------------|
+| Missing context package | Run test-context-gather first |
+| No coverage gaps | Skip test generation, proceed to execution |
+| No test framework detected | Configure test framework |
+| Invalid source session | 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 |
+### Execution Errors
+| Error | Recovery |
+|-------|----------|
+| Gemini timeout | Reduce scope, analyze by module |
+| Output incomplete | Retry with focused analysis |
+| No output file | 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
+**Fallback Strategy**: Generate basic TEST_ANALYSIS_RESULTS.md from context package if Gemini fails
 
-## Performance Optimization
+## Integration & Usage
 
-- **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
+### Command Chain
+- **Called By**: `/workflow:test-gen` (Phase 4: Analysis)
+- **Requires**: `test-context-package.json` from `/workflow:tools:test-context-gather`
+- **Followed By**: `/workflow:tools:test-task-generate`
 
-## Integration
+### Performance
+- Focused analysis: Only analyze files with missing tests
+- Pattern reuse: Study existing tests for quick extraction
+- Timeout: 20-minute limit for analysis
 
-### Called By
-- `/workflow:test-gen` (Phase 4: Analysis)
+### Success Criteria
+- Valid TEST_ANALYSIS_RESULTS.md generated
+- All missing tests documented with actionable requirements
+- Test scenarios cover happy path, errors, edge cases, integration
+- Dependencies and mocks clearly identified
+- Test generation strategy is practical
+- Output follows existing test conventions
 
-### 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

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

@@ -1,695 +1,224 @@
 ---
 name: test-task-generate
-description: Generate test-fix task JSON with iterative test-fix-retest cycle specification
+description: Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests
 argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
 examples:
   - /workflow:tools:test-task-generate --session WFS-test-auth
   - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
   - /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
-  - /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth
 ---
 
-# Test Task Generation Command
+# Generate Test Planning Documents 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).
-
-## Execution Modes
-
-### Test Generation (IMPL-001)
-- **Agent Mode (Default)**: @code-developer generates tests within agent context
-- **CLI Execute Mode (`--cli-execute`)**: Use Codex CLI for autonomous test generation
-
-### Test Fix (IMPL-002)
-- **Manual Mode (Default)**: Gemini diagnosis → user applies fixes
-- **Codex Mode (`--use-codex`)**: Gemini diagnosis → Codex applies fixes with resume mechanism
+Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent. This command produces **test planning artifacts only** - it does NOT execute tests or implement code. Actual test execution requires separate execution command (e.g., /workflow:test-cycle-execute).
 
 ## 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
+- **Planning Only**: Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - does NOT execute tests
+- **Agent-Driven Document Generation**: Delegate test plan generation to action-planning-agent
+- **Two-Phase Flow**: Context Preparation (command) → Test Document Generation (agent)
+- **Memory-First**: Reuse loaded documents from conversation memory
+- **MCP-Enhanced**: Use MCP tools for test pattern research and analysis
+- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root
+- **Leverage Existing Test Infrastructure**: Prioritize using established testing frameworks and tools present in the project
 
-## 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
+## Test-Specific Execution Modes
 
-## Execution Lifecycle
+### Test Generation (IMPL-001)
+- **Agent Mode** (default): @code-developer generates tests within agent context
+- **CLI Execute Mode** (`--cli-execute`): Use Codex CLI for autonomous test generation
 
-### Phase 1: Input Validation & Discovery
+### Test Execution & Fix (IMPL-002+)
+- **Manual Mode** (default): Gemini diagnosis → user applies fixes
+- **Codex Mode** (`--use-codex`): Gemini diagnosis → Codex applies fixes with resume mechanism
 
-1. **Parameter Parsing**
-   - Parse `--use-codex` flag from command arguments → Controls IMPL-002 fix mode
-   - Parse `--cli-execute` flag from command arguments → Controls IMPL-001 generation mode
-   - Store flag values for task JSON generation
+## Document Generation Lifecycle
 
-2. **Test Session Validation**
-   - Load `.workflow/{test-session-id}/workflow-session.json`
-   - Verify `workflow_type: "test_session"`
-   - Extract `source_session_id` from metadata
+### Phase 1: Context Preparation (Command Responsibility)
 
-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
+**Command prepares test session paths and metadata for planning document generation.**
 
-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": [
-          "bash(find . -name \"*.test.*\" -type f)",
-          "bash(# Read first 2 existing test files as examples)",
-          "bash(test_files=$(find . -name \"*.test.*\" -type f | head -2))",
-          "bash(for f in $test_files; do echo \"=== $f ===\"&& cat \"$f\"; done)"
-        ],
-        "output_to": "existing_test_patterns",
-        "on_error": "skip_optional"
-      }
-    ],
-    // Agent Mode (Default): Agent implements tests
-    "implementation_approach": [
-      {
-        "step": 1,
-        "title": "Generate comprehensive test suite",
-        "description": "Generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md. Follow test generation strategy and create all test files listed in section 5 (Implementation Targets).",
-        "modification_points": [
-          "Read TEST_ANALYSIS_RESULTS.md sections 3 and 4",
-          "Study existing test patterns",
-          "Create test files with all required scenarios",
-          "Implement happy path, error handling, edge case, and integration tests",
-          "Add required mocks and fixtures"
-        ],
-        "logic_flow": [
-          "Read TEST_ANALYSIS_RESULTS.md section 3 (Test Requirements by File)",
-          "Read TEST_ANALYSIS_RESULTS.md section 4 (Test Generation Strategy)",
-          "Study existing test patterns from test_context.test_framework.conventions",
-          "For each test file in section 5 (Implementation Targets): Create test file with specified scenarios, Implement happy path tests, Implement error handling tests, Implement edge case tests, Implement integration tests (if specified), Add required mocks and fixtures",
-          "Follow test framework conventions and project standards",
-          "Ensure all tests are executable and syntactically valid"
-        ],
-        "depends_on": [],
-        "output": "test_suite"
-      }
-    ],
-
-    // CLI Execute Mode (--cli-execute): Use Codex command (alternative format shown below)
-    "implementation_approach": [{
-      "step": 1,
-      "title": "Generate tests using Codex",
-      "description": "Use Codex CLI to autonomously generate comprehensive test suite based on TEST_ANALYSIS_RESULTS.md",
-      "modification_points": [
-        "Codex loads TEST_ANALYSIS_RESULTS.md and existing test patterns",
-        "Codex generates all test files listed in analysis section 5",
-        "Codex ensures tests follow framework conventions"
-      ],
-      "logic_flow": [
-        "Start new Codex session",
-        "Pass TEST_ANALYSIS_RESULTS.md to Codex",
-        "Codex studies existing test patterns",
-        "Codex generates comprehensive test suite",
-        "Codex validates test syntax and executability"
-      ],
-      "command": "bash(codex -C [focus_paths] --full-auto exec \"PURPOSE: Generate comprehensive test suite TASK: Create test files based on TEST_ANALYSIS_RESULTS.md section 5 MODE: write CONTEXT: @.workflow/WFS-test-[session]/.process/TEST_ANALYSIS_RESULTS.md @.workflow/WFS-test-[session]/.process/test-context-package.json EXPECTED: All test files with happy path, error handling, edge cases, integration tests RULES: Follow test framework conventions, ensure tests are executable\" --skip-git-repo-check -s danger-full-access)",
-      "depends_on": [],
-      "output": "test_generation"
-    }],
-    "target_files": [
-      "{test_file_1 from TEST_ANALYSIS_RESULTS.md section 5}",
-      "{test_file_2 from TEST_ANALYSIS_RESULTS.md section 5}",
-      "{test_file_N from TEST_ANALYSIS_RESULTS.md section 5}"
-    ]
-  }
-}
+**Test Session Path Structure**:
 ```
-
-#### 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": [
-          "bash(find . -name \"*.test.*\" -type f)",
-          "bash(rg \"test|describe|it|def test_\" -g \"*.test.*\")",
-          "bash(# Count implementation files vs test files)",
-          "bash(impl_count=$(find [changed_files_dirs] -type f \\( -name '*.ts' -o -name '*.js' -o -name '*.py' \\) ! -name '*.test.*' 2>/dev/null | wc -l))",
-          "bash(test_count=$(find . -name \"*.test.*\" -type f | 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": [
-      {
-        "step": 1,
-        "title": "Execute iterative test-fix-retest cycle",
-        "description": "Execute iterative test-fix-retest cycle using Gemini diagnosis (bug-fix template) and manual fixes (Codex only if meta.use_codex=true). Max 5 iterations with automatic revert on failure.",
-        "test_fix_cycle": {
-          "max_iterations": 5,
-          "cycle_pattern": "test → gemini_diagnose → manual_fix (or codex if needed) → retest",
-          "tools": {
-            "test_execution": "bash(test_command)",
-            "diagnosis": "gemini (MODE: analysis, uses bug-fix template)",
-            "fix_application": "manual (default) or codex exec resume --last (if explicitly needed)",
-            "verification": "bash(test_command) + regression_check"
-          },
-          "exit_conditions": {
-            "success": "all_tests_pass",
-            "failure": "max_iterations_reached",
-            "error": "test_command_not_found"
-          }
-        },
-        "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 && gemini \"",
-        "      PURPOSE: Diagnose test failure iteration [N] and propose minimal fix",
-        "      TASK: Systematic bug analysis and fix recommendations for test failure",
-        "      MODE: analysis",
-        "      CONTEXT: @CLAUDE.md,**/*CLAUDE.md",
-        "               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"
-          }
-        },
-        "depends_on": [],
-        "output": "test_fix_results"
-      }
-    ],
-    "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
+.workflow/active/WFS-test-{session-id}/
+├── workflow-session.json          # Test session metadata
 ├── .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
+│   ├── TEST_ANALYSIS_RESULTS.md   # Test requirements and strategy
+│   ├── test-context-package.json  # Test patterns and coverage
+│   └── context-package.json       # General context artifacts
+├── .task/                         # Output: Test task JSON files
+├── IMPL_PLAN.md                   # Output: Test implementation plan
+└── TODO_LIST.md                   # Output: Test TODO list
 ```
 
-## Error Handling
+**Command Preparation**:
+1. **Assemble Test Session Paths** for agent prompt:
+   - `session_metadata_path`
+   - `test_analysis_results_path` (REQUIRED)
+   - `test_context_package_path`
+   - Output directory paths
 
-### 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 |
+2. **Provide Metadata** (simple values):
+   - `session_id`
+   - `execution_mode` (agent-mode | cli-execute-mode)
+   - `use_codex` flag (true | false)
+   - `source_session_id` (if exists)
+   - `mcp_capabilities` (available MCP tools)
 
-### 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 |
+### Phase 2: Test Document Generation (Agent Responsibility)
 
-### Generation Errors
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Invalid JSON structure | Template error | Fix task generation logic |
-| Missing required fields | Incomplete metadata | Validate session metadata |
+**Purpose**: Generate test-specific IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT test execution.
+
+**Agent Invocation**:
+```javascript
+Task(
+  subagent_type="action-planning-agent",
+  description="Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
+  prompt=`
+## TASK OBJECTIVE
+Generate test planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for test workflow session
+
+IMPORTANT: This is TEST PLANNING ONLY - you are generating planning documents, NOT executing tests.
+
+CRITICAL:
+- Use existing test frameworks and utilities from the project
+- Follow the progressive loading strategy defined in your agent specification (load context incrementally from memory-first approach)
+
+## AGENT CONFIGURATION REFERENCE
+All test task generation rules, schemas, and quality standards are defined in your agent specification:
+@.claude/agents/action-planning-agent.md
+
+Refer to your specification for:
+- Test Task JSON Schema (6-field structure with test-specific metadata)
+- Test IMPL_PLAN.md Structure (test_session variant with test-fix cycle)
+- TODO_LIST.md Format (with test phase indicators)
+- Progressive Loading Strategy (memory-first, load TEST_ANALYSIS_RESULTS.md as primary source)
+- Quality Validation Rules (task count limits, requirement quantification)
+
+## SESSION PATHS
+Input:
+  - Session Metadata: .workflow/active/{test-session-id}/workflow-session.json
+  - TEST_ANALYSIS_RESULTS: .workflow/active/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md (REQUIRED - primary requirements source)
+  - Test Context Package: .workflow/active/{test-session-id}/.process/test-context-package.json
+  - Context Package: .workflow/active/{test-session-id}/.process/context-package.json
+  - Source Session Summaries: .workflow/active/{source-session-id}/.summaries/IMPL-*.md (if exists)
+
+Output:
+  - Task Dir: .workflow/active/{test-session-id}/.task/
+  - IMPL_PLAN: .workflow/active/{test-session-id}/IMPL_PLAN.md
+  - TODO_LIST: .workflow/active/{test-session-id}/TODO_LIST.md
+
+## CONTEXT METADATA
+Session ID: {test-session-id}
+Workflow Type: test_session
+Planning Mode: {agent-mode | cli-execute-mode}
+Use Codex: {true | false}
+Source Session: {source-session-id} (if exists)
+MCP Capabilities: {exa_code, exa_web, code_index}
+
+## TEST-SPECIFIC REQUIREMENTS SUMMARY
+(Detailed specifications in your agent definition)
+
+### Task Structure Requirements
+- Minimum 2 tasks: IMPL-001 (test generation) + IMPL-002 (test execution & fix)
+- Expandable for complex projects: Add IMPL-003+ (per-module, integration, E2E tests)
+
+Task Configuration:
+  IMPL-001 (Test Generation):
+    - meta.type: "test-gen"
+    - meta.agent: "@code-developer" (agent-mode) OR CLI execution (cli-execute-mode)
+    - meta.test_framework: Specify existing framework (e.g., "jest", "vitest", "pytest")
+    - flow_control: Test generation strategy from TEST_ANALYSIS_RESULTS.md
+
+  IMPL-002+ (Test Execution & Fix):
+    - meta.type: "test-fix"
+    - meta.agent: "@test-fix-agent"
+    - meta.use_codex: true/false (based on flag)
+    - flow_control: Test-fix cycle with iteration limits and diagnosis configuration
+
+### Test-Fix Cycle Specification (IMPL-002+)
+Required flow_control fields:
+  - max_iterations: 5
+  - diagnosis_tool: "gemini"
+  - diagnosis_template: "~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt"
+  - fix_mode: "manual" OR "codex" (based on use_codex flag)
+  - cycle_pattern: "test → gemini_diagnose → fix → retest"
+  - exit_conditions: ["all_tests_pass", "max_iterations_reached"]
+  - auto_revert_on_failure: true
+
+### TEST_ANALYSIS_RESULTS.md Mapping
+PRIMARY requirements source - extract and map to task JSONs:
+  - Test framework config → meta.test_framework (use existing framework from project)
+  - Existing test utilities → flow_control.reusable_test_tools (discovered test helpers, fixtures, mocks)
+  - Test runner commands → flow_control.test_commands (from package.json or pytest config)
+  - Coverage targets → meta.coverage_target
+  - Test requirements → context.requirements (quantified with explicit counts)
+  - Test generation strategy → IMPL-001 flow_control.implementation_approach
+  - Implementation targets → context.files_to_test (absolute paths)
+
+## EXPECTED DELIVERABLES
+1. Test Task JSON Files (.task/IMPL-*.json)
+   - 6-field schema with quantified requirements from TEST_ANALYSIS_RESULTS.md
+   - Test-specific metadata: type, agent, use_codex, test_framework, coverage_target
+   - flow_control includes: reusable_test_tools, test_commands (from project config)
+   - Artifact references from test-context-package.json
+   - Absolute paths in context.files_to_test
+
+2. Test Implementation Plan (IMPL_PLAN.md)
+   - Template: ~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt
+   - Test-specific frontmatter: workflow_type="test_session", test_framework, source_session_id
+   - Test-Fix-Retest Cycle section with diagnosis configuration
+   - Source session context integration (if applicable)
+
+3. TODO List (TODO_LIST.md)
+   - Hierarchical structure with test phase containers
+   - Links to task JSONs with status markers
+   - Matches task JSON hierarchy
+
+## QUALITY STANDARDS
+Hard Constraints:
+  - Task count: minimum 2, maximum 12
+  - All requirements quantified from TEST_ANALYSIS_RESULTS.md
+  - Test framework matches existing project framework
+  - flow_control includes reusable_test_tools and test_commands from project
+  - use_codex flag correctly set in IMPL-002+ tasks
+  - Absolute paths for all focus_paths
+  - Acceptance criteria include verification commands
+
+## SUCCESS CRITERIA
+- All test planning documents generated successfully
+- Return completion status: task count, test framework, coverage targets, source session status
+`
+)
+```
 
 ## Integration & Usage
 
 ### Command Chain
-- **Called By**: `/workflow:test-gen` (Phase 4)
-- **Calls**: None (terminal command)
-- **Followed By**: `/workflow:execute` (user-triggered)
+- **Called By**: `/workflow:test-gen` (Phase 4), `/workflow:test-fix-gen` (Phase 4)
+- **Invokes**: `action-planning-agent` for test planning document generation
+- **Followed By**: `/workflow:test-cycle-execute` or `/workflow:execute` (user-triggered)
 
-### Basic Usage
+### Usage Examples
 ```bash
-# Manual fix mode (default)
+# Agent mode (default)
 /workflow:tools:test-task-generate --session WFS-test-auth
 
-# Automated Codex fix mode
+# With automated Codex fixes
 /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
+
+# CLI execution mode for test generation
+/workflow:tools:test-task-generate --cli-execute --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
+- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode test generation
+- **--use-codex**: `meta.use_codex=true` (Codex automated fixes in IMPL-002+)
+- **--cli-execute**: CLI tool execution mode for IMPL-001 test generation
+- **Both flags**: CLI generation + automated Codex fixes
 
-## 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.
+### Output
+- Test task JSON files in `.task/` directory (minimum 2)
+- IMPL_PLAN.md with test strategy and fix cycle specification
+- TODO_LIST.md with test phase indicators
+- Session ready for test execution

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

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

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

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

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

@@ -0,0 +1,652 @@
+---
+name: workflow:ui-design:codify-style
+description: Orchestrator to extract styles from code and generate shareable reference package with preview (automatic file discovery)
+argument-hint: "<path> [--package-name <name>] [--output-dir <path>] [--overwrite]"
+allowed-tools: SlashCommand,Bash,Read,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Codify Style (Orchestrator)
+
+## Overview & Execution Model
+
+**Fully autonomous orchestrator**: Coordinates style extraction from codebase and generates shareable reference packages.
+
+**Pure Orchestrator Pattern**: Does NOT directly execute agent tasks. Delegates to specialized commands:
+1. `/workflow:ui-design:import-from-code` - Extract styles from source code
+2. `/workflow:ui-design:reference-page-generator` - Generate versioned reference package with interactive preview
+
+**Output**: Shareable, versioned style reference package at `.workflow/reference_style/{package-name}/`
+
+**Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
+1. User triggers: `/workflow:ui-design:codify-style <path> --package-name <name>`
+2. Phase 0: Parameter validation & preparation → **IMMEDIATELY triggers Phase 1**
+3. Phase 1 (import-from-code) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 2
+4. Phase 2 (reference-page-generator) → **Attach 4 tasks → Execute tasks → Collapse** → Auto-continues to Phase 3
+5. Phase 3 (cleanup & verification) → **Execute orchestrator task** → Reports completion
+
+**Phase Transition Mechanism**:
+- **Phase 0 (Validation)**: Validate parameters, prepare workspace → IMMEDIATELY triggers Phase 1
+- **Phase 1-2 (Task Attachment)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these tasks itself.
+- **Task Execution**: Orchestrator runs attached tasks sequentially, updating TodoWrite as each completes
+- **Task Collapse**: After all attached tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing completed tasks
+- No user interaction required after initial command
+
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until reaching Phase 3.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
+
+## Core Rules
+
+1. **Start Immediately**: TodoWrite initialization → Phase 0 validation → Phase 1 execution
+2. **No Task JSON**: This command does not create task JSON files - pure orchestrator pattern
+3. **Parse & Pass**: Extract required data from each command output (design run path, metadata)
+4. **Intelligent Validation**: Smart parameter validation with user-friendly error messages
+5. **Safety First**: Package overwrite protection, existence checks, fallback error handling
+6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+7. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+8. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 3.
+
+---
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:codify-style <path> [OPTIONS]
+
+# Required
+<path>                  Source code directory to analyze
+
+# Optional
+--package-name <name>   Custom name for the style reference package
+                        (default: auto-generated from directory name)
+--output-dir <path>     Output directory (default: .workflow/reference_style)
+--overwrite             Overwrite existing package without prompting
+```
+
+**Note**: File discovery is fully automatic. The command will scan the source directory and find all style-related files (CSS, SCSS, JS, HTML) automatically.
+
+---
+
+## 4-Phase Execution
+
+### Phase 0: Intelligent Parameter Validation & Session Preparation
+
+**Goal**: Validate parameters, check safety constraints, prepare session, and get user confirmation
+
+**TodoWrite** (First Action):
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Orchestrator tracks only high-level phases. Sub-command details shown when executed.
+
+**Step 0a: Parse and Validate Required Parameters**
+
+```bash
+# Parse positional path parameter (first non-flag argument)
+source_path = FIRST_POSITIONAL_ARG
+
+# Validate source path
+IF NOT source_path:
+    REPORT: "❌ ERROR: Missing required parameter: <path>"
+    REPORT: "USAGE: /workflow:ui-design:codify-style <path> [OPTIONS]"
+    REPORT: "EXAMPLE: /workflow:ui-design:codify-style ./src"
+    REPORT: "EXAMPLE: /workflow:ui-design:codify-style ./app --package-name design-system-v2"
+    EXIT 1
+
+# Validate source path existence
+TRY:
+    source_exists = Bash(test -d "${source_path}" && echo "exists" || echo "not_exists")
+    IF source_exists != "exists":
+        REPORT: "❌ ERROR: Source directory not found: ${source_path}"
+        REPORT: "Please provide a valid directory path."
+        EXIT 1
+CATCH error:
+    REPORT: "❌ ERROR: Cannot validate source path: ${error}"
+    EXIT 1
+
+source = source_path
+STORE: source
+
+# Auto-generate package name if not provided
+IF NOT --package-name:
+    # Extract directory name from path
+    dir_name = Bash(basename "${source}")
+    # Normalize to package name format (lowercase, replace special chars with hyphens)
+    normalized_name = dir_name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+    # Add version suffix
+    package_name = "${normalized_name}-style-v1"
+
+    ELSE:
+    package_name = --package-name
+
+    # Validate custom package name format (lowercase, alphanumeric, hyphens only)
+    IF NOT package_name MATCHES /^[a-z0-9][a-z0-9-]*$/:
+        REPORT: "❌ ERROR: Invalid package name format: ${package_name}"
+        REPORT: "Requirements:"
+        REPORT: "  • Must start with lowercase letter or number"
+        REPORT: "  • Only lowercase letters, numbers, and hyphens allowed"
+        REPORT: "  • No spaces or special characters"
+        REPORT: "EXAMPLES: main-app-style-v1, design-system-v2, component-lib-v1"
+        EXIT 1
+
+STORE: package_name, output_dir (default: ".workflow/reference_style"), overwrite_flag
+```
+
+**Step 0b: Intelligent Package Safety Check**
+
+```bash
+# Set default output directory
+output_dir = --output-dir OR ".workflow/reference_style"
+package_path = "${output_dir}/${package_name}"
+
+TRY:
+    package_exists = Bash(test -d "${package_path}" && echo "exists" || echo "not_exists")
+
+    IF package_exists == "exists":
+        IF NOT --overwrite:
+            REPORT: "❌ ERROR: Package '${package_name}' already exists at ${package_path}/"
+            REPORT: "Use --overwrite flag to replace, or choose a different package name"
+            EXIT 1
+        ELSE:
+            REPORT: "⚠️  Overwriting existing package: ${package_name}"
+
+CATCH error:
+    REPORT: "⚠️  Warning: Cannot check package existence: ${error}"
+    REPORT: "Continuing with package creation..."
+```
+
+**Step 0c: Session Preparation**
+
+```bash
+# Create temporary workspace for processing
+TRY:
+    # Step 1: Ensure .workflow directory exists and generate unique ID
+    Bash(mkdir -p .workflow)
+    temp_id = Bash(echo "codify-temp-$(date +%Y%m%d-%H%M%S)")
+
+    # Step 2: Create temporary directory
+    Bash(mkdir -p ".workflow/${temp_id}")
+
+    # Step 3: Get absolute path using bash
+    design_run_path = Bash(cd ".workflow/${temp_id}" && pwd)
+
+CATCH error:
+    REPORT: "❌ ERROR: Failed to create temporary workspace: ${error}"
+    EXIT 1
+
+STORE: temp_id, design_run_path
+```
+
+**Summary Variables**:
+- `SOURCE`: Validated source directory path
+- `PACKAGE_NAME`: Validated package name (lowercase, alphanumeric, hyphens)
+- `PACKAGE_PATH`: Full output path `${output_dir}/${package_name}`
+- `OUTPUT_DIR`: `.workflow/reference_style` (default) or user-specified
+- `OVERWRITE`: `true` if --overwrite flag present
+- `CSS/SCSS/JS/HTML/STYLE_FILES`: Optional glob patterns
+- `TEMP_ID`: `codify-temp-{timestamp}` (temporary workspace identifier)
+- `DESIGN_RUN_PATH`: Absolute path to temporary workspace
+
+<!-- TodoWrite: Update Phase 0 → completed, Phase 1 → in_progress, INSERT import-from-code tasks -->
+
+**TodoWrite Update (Phase 1 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1.0: Discover and categorize code files (import-from-code)", "status": "in_progress", "activeForm": "Discovering code files"},
+  {"content": "Phase 1.1: Style Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting style tokens"},
+  {"content": "Phase 1.2: Animation Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting animation tokens"},
+  {"content": "Phase 1.3: Layout Agent extraction (import-from-code)", "status": "pending", "activeForm": "Extracting layout patterns"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: SlashCommand invocation **attaches** import-from-code's 4 tasks to current workflow. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 1.0-1.3** sequentially
+
+---
+
+### Phase 1: Style Extraction from Source Code
+
+**Goal**: Extract design tokens, style patterns, and component styles from codebase
+
+**Command Construction**:
+
+```bash
+# Build command with required parameters only
+# Use temp_id as design-id since it's the workspace directory name
+command = "/workflow:ui-design:import-from-code" +
+          " --design-id \"${temp_id}\"" +
+          " --source \"${source}\""
+```
+
+**Execute Command (Task Attachment Pattern)**:
+
+```bash
+TRY:
+    # SlashCommand invocation ATTACHES import-from-code's 4 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 1.0: Discover and categorize code files
+    #   2. Phase 1.1: Style Agent extraction
+    #   3. Phase 1.2: Animation Agent extraction
+    #   4. Phase 1.3: Layout Agent extraction
+    SlashCommand(command)
+
+    # After executing all attached tasks, verify extraction outputs
+    tokens_path = "${design_run_path}/style-extraction/style-1/design-tokens.json"
+    guide_path = "${design_run_path}/style-extraction/style-1/style-guide.md"
+
+    tokens_exists = Bash(test -f "${tokens_path}" && echo "exists" || echo "missing")
+    guide_exists = Bash(test -f "${guide_path}" && echo "exists" || echo "missing")
+
+    IF tokens_exists != "exists" OR guide_exists != "exists":
+        REPORT: "⚠️  WARNING: Expected extraction files not found"
+        REPORT: "Continuing with available outputs..."
+
+CATCH error:
+    REPORT: "❌ ERROR: Style extraction failed"
+    REPORT: "Error: ${error}"
+    REPORT: "Possible cause: Source directory contains no style files"
+    Bash(rm -rf .workflow/${temp_id})
+    EXIT 1
+```
+
+**Example Command**:
+```bash
+# Automatic file discovery
+/workflow:ui-design:import-from-code --design-id codify-temp-20250111-123456 --source ./src
+```
+
+**Completion Criteria**:
+- ✅ `import-from-code` command executed successfully
+- ✅ Design run created at `${design_run_path}`
+- ✅ Required files exist:
+  - `design-tokens.json` - Complete design token system
+  - `style-guide.md` - Style documentation
+- ⭕ Optional files:
+  - `animation-tokens.json` - Animation specifications
+  - `component-patterns.json` - Component catalog
+
+<!-- TodoWrite: REMOVE Phase 1.0-1.3 tasks, INSERT reference-page-generator tasks -->
+
+**TodoWrite Update (Phase 2 SlashCommand invoked - tasks attached)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2.0: Setup and validation (reference-page-generator)", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 2.1: Prepare component data (reference-page-generator)", "status": "pending", "activeForm": "Copying layout templates"},
+  {"content": "Phase 2.2: Generate preview pages (reference-page-generator)", "status": "pending", "activeForm": "Generating preview"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 1 tasks completed and collapsed. SlashCommand invocation **attaches** reference-page-generator's 3 tasks. Orchestrator **executes** these tasks itself.
+
+**Next Action**: Tasks attached → **Execute Phase 2.0-2.2** sequentially
+
+---
+
+### Phase 2: Reference Package Generation
+
+**Goal**: Generate shareable reference package with interactive preview and documentation
+
+**Command Construction**:
+
+```bash
+command = "/workflow:ui-design:reference-page-generator " +
+          "--design-run \"${design_run_path}\" " +
+          "--package-name \"${package_name}\" " +
+          "--output-dir \"${output_dir}\""
+```
+
+**Execute Command (Task Attachment Pattern)**:
+
+```bash
+TRY:
+    # SlashCommand invocation ATTACHES reference-page-generator's 3 tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself:
+    #   1. Phase 2.0: Setup and validation
+    #   2. Phase 2.1: Prepare component data
+    #   3. Phase 2.2: Generate preview pages
+    SlashCommand(command)
+
+    # After executing all attached tasks, verify package outputs
+    required_files = [
+        "layout-templates.json",
+        "design-tokens.json",
+        "preview.html",
+        "preview.css"
+    ]
+
+    missing_files = []
+    FOR file IN required_files:
+        file_path = "${package_path}/${file}"
+        exists = Bash(test -f "${file_path}" && echo "exists" || echo "missing")
+        IF exists != "exists":
+            missing_files.append(file)
+
+    IF missing_files.length > 0:
+        REPORT: "⚠️  WARNING: Some expected files are missing"
+        REPORT: "Package may be incomplete. Continuing with cleanup..."
+
+CATCH error:
+    REPORT: "❌ ERROR: Reference package generation failed"
+    REPORT: "Error: ${error}"
+    Bash(rm -rf .workflow/${temp_id})
+    EXIT 1
+```
+
+**Example Command**:
+```bash
+/workflow:ui-design:reference-page-generator \
+  --design-run .workflow/codify-temp-20250111-123456 \
+  --package-name main-app-style-v1 \
+  --output-dir .workflow/reference_style
+```
+
+**Completion Criteria**:
+- ✅ `reference-page-generator` executed successfully
+- ✅ Reference package created at `${package_path}/`
+- ✅ All required files present:
+  - `layout-templates.json` - Layout templates from design run
+  - `design-tokens.json` - Complete design token system
+  - `preview.html` - Interactive multi-component showcase
+  - `preview.css` - Showcase styling
+- ⭕ Optional files:
+  - `animation-tokens.json` - Animation specifications (if available from extraction)
+
+<!-- TodoWrite: REMOVE Phase 2.0-2.2 tasks, restore to orchestrator view -->
+
+**TodoWrite Update (Phase 2 completed - tasks collapsed)**:
+```json
+[
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "completed", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "completed", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "completed", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "in_progress", "activeForm": "Cleanup and verification"}
+]
+```
+
+**Note**: Phase 2 tasks completed and collapsed to summary.
+
+**Next Action**: TodoWrite restored → **Execute Phase 3** (orchestrator's own task)
+
+---
+
+### Phase 3: Cleanup & Verification
+
+**Goal**: Clean up temporary workspace and report completion
+
+**Operations**:
+
+```bash
+# Cleanup temporary workspace
+TRY:
+    Bash(rm -rf .workflow/${temp_id})
+CATCH error:
+    # Silent failure - not critical
+
+# Quick verification
+package_exists = Bash(test -d "${package_path}" && echo "exists" || echo "missing")
+
+IF package_exists != "exists":
+    REPORT: "❌ ERROR: Package generation failed - directory not found"
+    EXIT 1
+
+# Get absolute path and component count for final report
+absolute_package_path = Bash(cd "${package_path}" && pwd 2>/dev/null || echo "${package_path}")
+component_count = Bash(jq -r '.layout_templates | length // "unknown"' "${package_path}/layout-templates.json" 2>/dev/null || echo "unknown")
+anim_exists = Bash(test -f "${package_path}/animation-tokens.json" && echo "✓" || echo "○")
+```
+
+<!-- TodoWrite: Update Phase 3 → completed -->
+
+**Final Action**: Display completion summary to user
+
+---
+
+## Completion Message
+
+```
+✅ Style reference package generated successfully
+
+📦 Package: {package_name}
+📂 Location: {absolute_package_path}/
+📄 Source: {source}
+📊 Components: {component_count}
+
+Files: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
+
+Preview: file://{absolute_package_path}/preview.html
+
+Next: /memory:style-skill-memory {package_name}
+```
+
+---
+
+## TodoWrite Pattern
+
+```javascript
+// Initialize IMMEDIATELY at the start to track orchestrator workflow (4 high-level tasks)
+TodoWrite({todos: [
+  {"content": "Phase 0: Validate parameters and prepare session", "status": "in_progress", "activeForm": "Validating parameters"},
+  {"content": "Phase 1: Style extraction from source code (import-from-code)", "status": "pending", "activeForm": "Extracting styles"},
+  {"content": "Phase 2: Reference package generation (reference-page-generator)", "status": "pending", "activeForm": "Generating package"},
+  {"content": "Phase 3: Cleanup and verify package", "status": "pending", "activeForm": "Cleanup and verification"}
+]})
+
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// 1. INITIAL STATE: 4 orchestrator-level tasks only
+//
+// 2. PHASE 1 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+//    - TodoWrite expands to: Phase 0 (completed) + 4 import-from-code tasks + Phase 2 + Phase 3
+//    - Orchestrator EXECUTES these 4 tasks sequentially (Phase 1.0 → 1.1 → 1.2 → 1.3)
+//    - First attached task marked as in_progress
+//
+// 3. PHASE 1 TASKS COMPLETED:
+//    - All 4 import-from-code tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 1 summary
+//    - TodoWrite becomes: Phase 0-1 (completed) + Phase 2 + Phase 3
+//
+// 4. PHASE 2 SlashCommand INVOCATION:
+//    - SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
+//    - TodoWrite expands to: Phase 0-1 (completed) + 3 reference-page-generator tasks + Phase 3
+//    - Orchestrator EXECUTES these 3 tasks sequentially (Phase 2.0 → 2.1 → 2.2)
+//
+// 5. PHASE 2 TASKS COMPLETED:
+//    - All 3 reference-page-generator tasks executed and completed
+//    - COLLAPSE completed tasks into Phase 2 summary
+//    - TodoWrite returns to: Phase 0-2 (completed) + Phase 3 (in_progress)
+//
+// 6. PHASE 3 EXECUTION:
+//    - Orchestrator's own task (no SlashCommand attachment)
+//    - Mark Phase 3 as completed
+//    - Final state: All 4 orchestrator tasks completed
+
+// ✓ Dynamic attachment/collapse maintains clarity
+```
+
+---
+
+## Execution Flow Diagram
+
+```
+User triggers: /workflow:ui-design:codify-style ./src --package-name my-style-v1
+  ↓
+[TodoWrite Init] 4 orchestrator-level tasks
+  ├─ Phase 0: Validate parameters and prepare session (in_progress)
+  ├─ Phase 1: Style extraction from source code (pending)
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Phase 0] Parameter validation & preparation
+  ├─ Parse positional path parameter
+  ├─ Validate source directory exists
+  ├─ Auto-generate or validate package name
+  ├─ Check package overwrite protection
+  ├─ Create temporary workspace
+  └─ Display configuration summary
+  ↓
+[Phase 0 Complete] → TodoWrite: Phase 0 → completed
+  ↓
+[Phase 1 Invoke] → SlashCommand(/workflow:ui-design:import-from-code) ATTACHES 4 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1.0: Discover and categorize code files (in_progress)  ← ATTACHED
+  ├─ Phase 1.1: Style Agent extraction (pending)                   ← ATTACHED
+  ├─ Phase 1.2: Animation Agent extraction (pending)               ← ATTACHED
+  ├─ Phase 1.3: Layout Agent extraction (pending)                  ← ATTACHED
+  ├─ Phase 2: Reference package generation (pending)
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 1.0] → Discover files (orchestrator executes this)
+  ↓
+[Execute Phase 1.1-1.3] → Run 3 agents in parallel (orchestrator executes these)
+  └─ Outputs: design-tokens.json, style-guide.md, animation-tokens.json, layout-templates.json
+  ↓
+[Phase 1 Complete] → TodoWrite: COLLAPSE Phase 1.0-1.3 into Phase 1 summary
+  ↓
+[Phase 2 Invoke] → SlashCommand(/workflow:ui-design:reference-page-generator) ATTACHES 3 tasks
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)        ← COLLAPSED
+  ├─ Phase 2.0: Setup and validation (in_progress)                 ← ATTACHED
+  ├─ Phase 2.1: Prepare component data (pending)                   ← ATTACHED
+  ├─ Phase 2.2: Generate preview pages (pending)                   ← ATTACHED
+  └─ Phase 3: Cleanup and verify package (pending)
+  ↓
+[Execute Phase 2.0] → Setup and validation (orchestrator executes this)
+  ↓
+[Execute Phase 2.1] → Prepare component data (orchestrator executes this)
+  ↓
+[Execute Phase 2.2] → Generate preview pages (orchestrator executes this)
+  └─ Outputs: layout-templates.json, design-tokens.json, animation-tokens.json (optional), preview.html, preview.css
+  ↓
+[Phase 2 Complete] → TodoWrite: COLLAPSE Phase 2.0-2.2 into Phase 2 summary
+  ├─ Phase 0 (completed)
+  ├─ Phase 1: Style extraction from source code (completed)
+  ├─ Phase 2: Reference package generation (completed)             ← COLLAPSED
+  └─ Phase 3: Cleanup and verify package (in_progress)
+  ↓
+[Execute Phase 3] → Orchestrator's own task (no attachment needed)
+  ├─ Remove temporary workspace (.workflow/codify-temp-{timestamp}/)
+  ├─ Verify package directory
+  ├─ Extract component count
+  └─ Display completion summary
+  ↓
+[Phase 3 Complete] → TodoWrite: Phase 3 → completed
+  ├─ Phase 0 (completed)
+  ├─ Phase 1 (completed)
+  ├─ Phase 2 (completed)
+  └─ Phase 3 (completed)
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing --source or --package-name | Required parameters not provided | Provide both flags |
+| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
+| import-from-code failed | Source path invalid or no files found | Verify source path, check glob patterns |
+| reference-page-generator failed | Design run incomplete | Check import-from-code output, verify extraction files |
+| Package verification failed | Output directory creation failed | Check file permissions |
+
+### Error Recovery
+
+- If Phase 2 fails: Cleanup temporary session and report error
+- If Phase 3 fails: Keep design run for debugging, report error
+- User can manually inspect `${design_run_path}` if needed
+
+---
+
+## Implementation Details
+
+### Critical Rules
+
+1. **No User Prompts Between Phases**: Never ask user questions or wait for input between phases
+2. **Immediate Phase Transition**: After TodoWrite update, immediately execute next phase command
+3. **Status-Driven Execution**: Check TodoList status after each phase
+4. **Phase Completion Pattern**:
+   ```
+   Phase N completes → Update TodoWrite (N=completed, N+1=in_progress) → Execute Phase N+1
+   ```
+
+### Parameter Pass-Through
+
+Only essential parameters are passed to `import-from-code`:
+- `--design-id` → temporary design run ID (auto-generated)
+- `--source` → user-specified source directory
+
+File discovery is fully automatic - no glob patterns needed.
+
+### Output Directory Structure
+
+```
+.workflow/
+├── reference_style/              # Default output directory
+│   └── {package-name}/
+│       ├── layout-templates.json
+│       ├── design-tokens.json
+│       ├── animation-tokens.json (optional)
+│       ├── preview.html
+│       └── preview.css
+│
+└── codify-temp-{timestamp}/      # Temporary workspace (cleaned up after completion)
+    ├── style-extraction/
+    ├── animation-extraction/
+    └── layout-extraction/
+```
+
+---
+
+
+
+## Architecture
+
+```
+codify-style (orchestrator - simplified interface)
+  ├─ Phase 0: Intelligent Validation
+  │   ├─ Parse positional path parameter
+  │   ├─ Auto-generate package name (if not provided)
+  │   ├─ Safety checks (overwrite protection)
+  │   └─ User confirmation
+  ├─ Phase 1: /workflow:ui-design:import-from-code (style extraction)
+  │   ├─ Extract design tokens from source code
+  │   ├─ Generate style guide
+  │   └─ Extract component patterns
+  ├─ Phase 2: /workflow:ui-design:reference-page-generator (reference package)
+  │   ├─ Generate shareable package
+  │   ├─ Create interactive preview
+  │   └─ Generate documentation
+  └─ Phase 3: Cleanup & Verification
+      ├─ Remove temporary workspace
+      ├─ Verify package integrity
+      └─ Report completion
+
+Design Principles:
+✓ No task JSON created by this command
+✓ All extraction delegated to import-from-code
+✓ All packaging delegated to reference-page-generator
+✓ Pure orchestration with intelligent defaults
+✓ Single path parameter for maximum simplicity
+```

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

@@ -1,11 +1,11 @@
 ---
-name: update
-description: Update brainstorming artifacts with finalized design system references
+name: design-sync
+description: Synchronize finalized design system references to brainstorming artifacts, preparing them for /workflow:plan consumption
 argument-hint: --session <session_id> [--selected-prototypes "<list>"]
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
-# Design Update Command
+# Design Sync Command
 
 ## Overview
 
@@ -25,10 +25,10 @@ Synchronize finalized design system references to brainstorming artifacts, prepa
 
 ```bash
 # Validate session
-CHECK: .workflow/.active-* marker files; VALIDATE: session_id matches active session
+CHECK: find .workflow/active/ -name "WFS-*" -type d; VALIDATE: session_id matches active session
 
 # Verify design artifacts in latest design run
-latest_design = find_latest_path_matching(".workflow/WFS-{session}/design-*")
+latest_design = find_latest_path_matching(".workflow/active/WFS-{session}/design-run-*")
 
 # Detect design system structure
 IF exists({latest_design}/style-extraction/style-1/design-tokens.json):
@@ -51,7 +51,7 @@ REPORT: "Found {count} design artifacts, {prototype_count} prototypes"
 
 ```bash
 # Check if role analysis documents contains current design run reference
-synthesis_spec_path = ".workflow/WFS-{session}/.brainstorming/role analysis documents"
+synthesis_spec_path = ".workflow/active/WFS-{session}/.brainstorming/role analysis documents"
 current_design_run = basename(latest_design)  # e.g., "design-run-20250109-143022"
 
 IF exists(synthesis_spec_path):
@@ -68,8 +68,8 @@ IF exists(synthesis_spec_path):
 
 ```bash
 # Load target brainstorming artifacts (files to be updated)
-Read(.workflow/WFS-{session}/.brainstorming/role analysis documents)
-IF exists(.workflow/WFS-{session}/.brainstorming/ui-designer/analysis.md): Read(analysis.md)
+Read(.workflow/active/WFS-{session}/.brainstorming/role analysis documents)
+IF exists(.workflow/active/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:
@@ -89,8 +89,8 @@ Update `.brainstorming/role analysis documents` with design system references.
 ## UI/UX Guidelines
 
 ### Design System Reference
-**Finalized Design Tokens**: @../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../design-{run_id}/{style_guide_path}
+**Finalized Design Tokens**: @../{design_id}/{design_tokens_path}
+**Style Guide**: @../{design_id}/{style_guide_path}
 **Design System Mode**: {design_system_mode}
 
 ### Implementation Requirements
@@ -101,19 +101,19 @@ Update `.brainstorming/role analysis documents` with design system references.
 
 ### Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../design-{run_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
+- **{page_name}**: @../{design_id}/prototypes/{prototype}.html | Layout: {layout_strategy from notes}
 }
 
 ### Design System Assets
 ```json
-{"design_tokens": "design-{run_id}/{design_tokens_path}", "style_guide": "design-{run_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "design-{run_id}/prototypes/{prototype}.html"}]}
+{"design_tokens": "{design_id}/{design_tokens_path}", "style_guide": "{design_id}/{style_guide_path}", "design_system_mode": "{design_system_mode}", "prototypes": [{FOR each: "{design_id}/prototypes/{prototype}.html"}]}
 ```
 ```
 
 **Implementation**:
 ```bash
 # Option 1: Edit existing section
-Edit(file_path=".workflow/WFS-{session}/.brainstorming/role analysis documents",
+Edit(file_path=".workflow/active/WFS-{session}/.brainstorming/role analysis documents",
      old_string="## UI/UX Guidelines\n[existing content]",
      new_string="## UI/UX Guidelines\n\n[new design reference content]")
 
@@ -128,15 +128,15 @@ IF section not found:
 
 ```bash
 # Always update ui-designer
-ui_designer_files = Glob(".workflow/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
+ui_designer_files = Glob(".workflow/active/WFS-{session}/.brainstorming/ui-designer/analysis*.md")
 
 # Conditionally update other roles
 has_animations = exists({latest_design}/animation-extraction/animation-tokens.json)
 has_layouts = exists({latest_design}/layout-extraction/layout-templates.json)
 
-IF has_animations: ux_expert_files = Glob(".workflow/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
-IF has_layouts: architect_files = Glob(".workflow/WFS-{session}/.brainstorming/system-architect/analysis*.md")
-IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/product-manager/analysis*.md")
+IF has_animations: ux_expert_files = Glob(".workflow/active/WFS-{session}/.brainstorming/ux-expert/analysis*.md")
+IF has_layouts: architect_files = Glob(".workflow/active/WFS-{session}/.brainstorming/system-architect/analysis*.md")
+IF selected_list: pm_files = Glob(".workflow/active/WFS-{session}/.brainstorming/product-manager/analysis*.md")
 ```
 
 **Content Templates**:
@@ -145,9 +145,9 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Design System Implementation Reference
 
-**Design Tokens**: @../../design-{run_id}/{design_tokens_path}
-**Style Guide**: @../../design-{run_id}/{style_guide_path}
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Design Tokens**: @../../{design_id}/{design_tokens_path}
+**Style Guide**: @../../{design_id}/{style_guide_path}
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -156,8 +156,8 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Animation & Interaction Reference
 
-**Animations**: @../../design-{run_id}/animation-extraction/animation-tokens.json
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Animations**: @../../{design_id}/animation-extraction/animation-tokens.json
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -166,7 +166,7 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Layout Structure Reference
 
-**Layout Templates**: @../../design-{run_id}/layout-extraction/layout-templates.json
+**Layout Templates**: @../../{design_id}/layout-extraction/layout-templates.json
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -175,7 +175,7 @@ IF selected_list: pm_files = Glob(".workflow/WFS-{session}/.brainstorming/produc
 ```markdown
 ## Prototype Validation Reference
 
-**Prototypes**: {FOR each: @../../design-{run_id}/prototypes/{prototype}.html}
+**Prototypes**: {FOR each: @../../{design_id}/prototypes/{prototype}.html}
 
 *Reference added by /workflow:ui-design:update*
 ```
@@ -197,8 +197,8 @@ Create or update `.brainstorming/ui-designer/design-system-reference.md`:
 ## 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 Tokens**: @../../{design_id}/{design_tokens_path}
+**Style Guide**: @../../{design_id}/{style_guide_path}
 **Design System Mode**: {design_system_mode}
 
 ## Implementation Guidelines
@@ -209,13 +209,13 @@ This style guide references the finalized design system from the design refineme
 
 ## Reference Prototypes
 {FOR each selected_prototype:
-- **{page_name}**: @../../design-{run_id}/prototypes/{prototype}.html
+- **{page_name}**: @../../{design_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}
+- Design Tokens: @../../{design_id}/{design_tokens_path}
+- Style Guide: @../../{design_id}/{style_guide_path}
 
 ---
 *Auto-generated by /workflow:ui-design:update | Last updated: {timestamp}*
@@ -223,11 +223,72 @@ For complete token definitions and usage examples, see:
 
 **Implementation**:
 ```bash
-Write(file_path=".workflow/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
+Write(file_path=".workflow/active/WFS-{session}/.brainstorming/ui-designer/design-system-reference.md",
       content="[generated content with @ references]")
 ```
 
-### Phase 5: Completion
+### Phase 5: Update Context Package
+
+**Purpose**: Sync design system references to context-package.json
+
+**Operations**:
+```bash
+context_pkg_path = ".workflow/active/WFS-{session}/.process/context-package.json"
+
+# 1. Read existing package
+context_pkg = Read(context_pkg_path)
+
+# 2. Update brainstorm_artifacts (role analyses now contain @ design references)
+brainstorm_dir = ".workflow/active/WFS-{session}/.brainstorming"
+role_analysis_files = Glob({brainstorm_dir}/*/analysis*.md)
+
+context_pkg.brainstorm_artifacts.role_analyses = []
+FOR file IN role_analysis_files:
+    role_name = extract_role_from_path(file)
+    relative_path = file.replace({brainstorm_dir}/, "")
+
+    context_pkg.brainstorm_artifacts.role_analyses.push({
+        "role": role_name,
+        "files": [{
+            "path": relative_path,
+            "type": "primary",
+            "content": Read(file),  # Contains @ design system references
+            "updated_at": NOW()
+        }]
+    })
+
+# 3. Add design_system_references field
+context_pkg.design_system_references = {
+    "design_run_id": design_id,
+    "tokens": `${design_id}/${design_tokens_path}`,
+    "style_guide": `${design_id}/${style_guide_path}`,
+    "prototypes": selected_list.map(p => `${design_id}/prototypes/${p}.html`),
+    "updated_at": NOW()
+}
+
+# 4. Optional: Add animations and layouts if they exist
+IF exists({latest_design}/animation-extraction/animation-tokens.json):
+    context_pkg.design_system_references.animations = `${design_id}/animation-extraction/animation-tokens.json`
+
+IF exists({latest_design}/layout-extraction/layout-templates.json):
+    context_pkg.design_system_references.layouts = `${design_id}/layout-extraction/layout-templates.json`
+
+# 5. Update metadata
+context_pkg.metadata.updated_at = NOW()
+context_pkg.metadata.design_sync_timestamp = NOW()
+
+# 6. Write back
+Write(context_pkg_path, JSON.stringify(context_pkg, indent=2))
+
+REPORT: "✅ Updated context-package.json with design system references"
+```
+
+**TodoWrite Update**:
+```json
+{"content": "Update context package with design references", "status": "completed", "activeForm": "Updating context package"}
+```
+
+### Phase 6: Completion
 
 ```javascript
 TodoWrite({todos: [
@@ -259,7 +320,7 @@ Next: /workflow:plan [--agent] "<task description>"
 
 **Updated Files**:
 ```
-.workflow/WFS-{session}/.brainstorming/
+.workflow/active/WFS-{session}/.brainstorming/
 ├── role analysis documents              # Updated with UI/UX Guidelines section
 ├── ui-designer/
 │   ├── analysis*.md                     # Updated with design system references
@@ -271,24 +332,24 @@ Next: /workflow:plan [--agent] "<task description>"
 
 **@ Reference Format** (role analysis documents):
 ```
-@../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../design-{run_id}/style-extraction/style-1/style-guide.md
-@../design-{run_id}/prototypes/{prototype}.html
+@../{design_id}/style-extraction/style-1/design-tokens.json
+@../{design_id}/style-extraction/style-1/style-guide.md
+@../{design_id}/prototypes/{prototype}.html
 ```
 
 **@ Reference Format** (ui-designer/design-system-reference.md):
 ```
-@../../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../../design-{run_id}/style-extraction/style-1/style-guide.md
-@../../design-{run_id}/prototypes/{prototype}.html
+@../../{design_id}/style-extraction/style-1/design-tokens.json
+@../../{design_id}/style-extraction/style-1/style-guide.md
+@../../{design_id}/prototypes/{prototype}.html
 ```
 
 **@ Reference Format** (role analysis.md files):
 ```
-@../../design-{run_id}/style-extraction/style-1/design-tokens.json
-@../../design-{run_id}/animation-extraction/animation-tokens.json
-@../../design-{run_id}/layout-extraction/layout-templates.json
-@../../design-{run_id}/prototypes/{prototype}.html
+@../../{design_id}/style-extraction/style-1/design-tokens.json
+@../../{design_id}/animation-extraction/animation-tokens.json
+@../../{design_id}/layout-extraction/layout-templates.json
+@../../{design_id}/prototypes/{prototype}.html
 ```
 
 ## Integration with /workflow:plan
@@ -307,9 +368,9 @@ After this update, `/workflow:plan` will discover design assets through:
   "task_id": "IMPL-001",
   "context": {
     "design_system": {
-      "tokens": "design-{run_id}/style-extraction/style-1/design-tokens.json",
-      "style_guide": "design-{run_id}/style-extraction/style-1/style-guide.md",
-      "prototypes": ["design-{run_id}/prototypes/dashboard-variant-1.html"]
+      "tokens": "{design_id}/style-extraction/style-1/design-tokens.json",
+      "style_guide": "{design_id}/style-extraction/style-1/style-guide.md",
+      "prototypes": ["{design_id}/prototypes/dashboard-variant-1.html"]
     }
   }
 }
@@ -349,15 +410,3 @@ After update, verify:
 - **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/commands/workflow/ui-design/explore-auto.md

@@ -1,7 +1,7 @@
 ---
 name: explore-auto
-description: Exploratory UI design workflow with style-centric batch generation
-argument-hint: "[--prompt "<desc>"] [--images "<glob>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>] [--batch-plan]""
+description: Interactive exploratory UI design workflow with style-centric batch generation, creates design variants from prompts/images with parallel execution and user selection
+argument-hint: "[--input "<value>"] [--targets "<list>"] [--target-type "page|component"] [--session <id>] [--style-variants <count>] [--layout-variants <count>]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*), Task(conceptual-planning-agent)
 ---
 
@@ -18,35 +18,58 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 
 **Autonomous Flow** (⚠️ CONTINUOUS EXECUTION - DO NOT STOP):
 1. User triggers: `/workflow:ui-design:explore-auto [params]`
-2. Phase 0c: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 1**
-3. Phase 1 (style-extract) → **WAIT for completion** → Auto-continues
-4. Phase 2.3 (animation-extract, optional) → **WAIT for completion** → Auto-continues
-5. Phase 2.5 (layout-extract) → **WAIT for completion** → Auto-continues
-6. **Phase 3 (ui-assembly)** → **WAIT for completion** → Auto-continues
-7. Phase 4 (design-update) → **WAIT for completion** → Auto-continues
-8. Phase 5 (batch-plan, optional) → Reports completion
+2. Phase 5: Target confirmation → User confirms → **IMMEDIATELY triggers Phase 7**
+3. Phase 7 (style-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 8
+4. Phase 8 (animation-extract, conditional):
+   - **IF should_extract_animation**: **Attach tasks → Execute → Collapse** → Auto-continues to Phase 9
+   - **ELSE**: Skip (use code import) → Auto-continues to Phase 9
+5. Phase 9 (layout-extract) → **Attach tasks → Execute → Collapse** → Auto-continues to Phase 10
+6. **Phase 10 (ui-assembly)** → **Attach tasks → Execute → Collapse** → Workflow complete
 
 **Phase Transition Mechanism**:
-- **Phase 0c (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 1
-- **Phase 1-5 (Autonomous)**: `SlashCommand` is BLOCKING - execution pauses until completion
-- Upon each phase completion: Automatically process output and execute next phase
-- No additional user interaction after Phase 0c confirmation
+- **Phase 5 (User Interaction)**: User confirms targets → IMMEDIATELY triggers Phase 7
+- **Phase 7-10 (Autonomous)**: `SlashCommand` invocation **ATTACHES** tasks to current workflow
+- **Task Execution**: Orchestrator **EXECUTES** these attached tasks itself
+- **Task Collapse**: After tasks complete, collapse them into phase summary
+- **Phase Transition**: Automatically execute next phase after collapsing
+- No additional user interaction after Phase 5 confirmation
 
-**Auto-Continue Mechanism**: TodoWrite tracks phase status. Upon each phase completion, you MUST immediately construct and execute the next phase command. No user intervention required. The workflow is NOT complete until reaching Phase 4 (or Phase 5 if --batch-plan).
+**Auto-Continue Mechanism**: TodoWrite tracks phase status with dynamic task attachment/collapse. After executing all attached tasks, you MUST immediately collapse them, restore phase summary, and execute the next phase. No user intervention required. The workflow is NOT complete until Phase 10 (UI assembly) finishes.
+
+**Task Attachment Model**: SlashCommand invocation is NOT delegation - it's task expansion. The orchestrator executes these attached tasks itself, not waiting for external completion.
 
 **Target Type Detection**: Automatically inferred from prompt/targets, or explicitly set via `--target-type`.
 
 ## Core Rules
 
-1. **Start Immediately**: TodoWrite initialization → Phase 1 execution
+1. **Start Immediately**: TodoWrite initialization → Phase 7 execution
 2. **No Preliminary Validation**: Sub-commands handle their own validation
 3. **Parse & Pass**: Extract data from each output for next phase
 4. **Default to All**: When selecting variants/prototypes, use ALL generated items
-5. **Track Progress**: Update TodoWrite after each phase
-6. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After each SlashCommand completes, you MUST wait for completion, then immediately execute the next phase. Workflow is NOT complete until Phase 4 (or Phase 5 if --batch-plan).
+5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
+6. **⚠️ CRITICAL: Task Attachment Model** - SlashCommand invocation **ATTACHES** tasks to current workflow. Orchestrator **EXECUTES** these attached tasks itself, not waiting for external completion. This is NOT delegation - it's task expansion.
+7. **⚠️ CRITICAL: DO NOT STOP** - This is a continuous multi-phase workflow. After executing all attached tasks, you MUST immediately collapse them and execute the next phase. Workflow is NOT complete until Phase 10 (UI assembly) finishes.
 
 ## Parameter Requirements
 
+**Recommended Parameter**:
+- `--input "<value>"`: Unified input source (auto-detects type)
+  - **Glob pattern** (images): `"design-refs/*"`, `"screenshots/*.png"`
+  - **File/directory path** (code): `"./src/components"`, `"/path/to/styles"`
+  - **Text description** (prompt): `"modern dashboard with 3 styles"`, `"minimalist design"`
+  - **Combination**: `"design-refs/* modern dashboard"` (glob + description)
+  - Multiple inputs: Separate with `|` → `"design-refs/*|modern style"`
+
+**Detection Logic**:
+- Contains `*` or matches existing files → **glob pattern** (images)
+- Existing file/directory path → **code import**
+- Pure text without paths → **design prompt**
+- Contains `|` separator → **multiple inputs** (glob|prompt or path|prompt)
+
+**Legacy Parameters** (deprecated, use `--input` instead):
+- `--images "<glob>"`: Reference image paths (shows deprecation warning)
+- `--prompt "<description>"`: Design description (shows deprecation warning)
+
 **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)
@@ -56,19 +79,16 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
   - **Tablet**: 768×1024px - Hybrid touch/mouse layouts
   - **Responsive**: 1920×1080px base with mobile-first breakpoints
 - `--session <id>`: Workflow session ID (standalone mode if omitted)
-- `--images "<glob>"`: Reference image paths (default: `design-refs/*`)
-- `--prompt "<description>"`: Design style and target description
 - `--style-variants <count>`: Style variants (default: inferred from prompt or 3, range: 1-5)
 - `--layout-variants <count>`: Layout variants per style (default: inferred or 3, range: 1-5)
-- `--batch-plan`: Auto-generate implementation tasks after design-update
 
-**Legacy Parameters** (maintained for backward compatibility):
+**Legacy Target 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
+- Must provide: `--input` OR (legacy: `--images`/`--prompt`) OR `--targets`
+- `--input` can combine multiple input types
 - If `--targets` not provided, intelligently inferred from prompt/session
 
 **Supported Target Types**:
@@ -105,87 +125,109 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Glob(*), Write(*
 **Integrated vs. Standalone**:
 - `--session` flag determines session integration or standalone execution
 
-## 6-Phase Execution
+## 10-Phase Execution
 
-### Phase 0a: Intelligent Prompt Parsing
+### Phase 1: Parameter Parsing & Input Detection
+
+**Unified Principle**: Detect → Classify → Store (avoid string concatenation and escaping)
+
+**Step 1: Parameter Normalization**
 ```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
+# Legacy parameters (deprecated)
+IF --images OR --prompt:
+    WARN: "⚠️ --images/--prompt deprecated. Use --input"
+    images_input = --images; prompt_text = --prompt
 
-VALIDATE: 1 <= style_variants <= 5, 1 <= layout_variants <= 5
+# Unified --input (split by "|")
+ELSE IF --input:
+    FOR part IN split(--input, "|"):
+        IF "*" IN part OR glob_exists(part): images_input = part
+        ELSE IF path_exists(part): prompt_text += part
+        ELSE: prompt_text += part
 ```
 
-### Phase 0a-2: Device Type Inference
+**Step 2: Design Source Detection**
 ```bash
-# Device type inference
-device_type = "auto"
+code_base_path = extract_first_valid_path(prompt_text)
+has_visual_input = (images_input AND glob_exists(images_input))
 
-# Step 1: Explicit parameter (highest priority)
-IF --device-type AND --device-type != "auto":
-    device_type = --device-type
-    device_source = "explicit"
-ELSE:
-    # Step 2: Prompt analysis
-    IF --prompt:
-        device_keywords = {
-            "desktop": ["desktop", "web", "laptop", "widescreen", "large screen"],
-            "mobile": ["mobile", "phone", "smartphone", "ios", "android"],
-            "tablet": ["tablet", "ipad", "medium screen"],
-            "responsive": ["responsive", "adaptive", "multi-device", "cross-platform"]
-        }
-        detected_device = detect_device_from_prompt(--prompt, device_keywords)
-        IF detected_device:
-            device_type = detected_device
-            device_source = "prompt_inference"
-
-    # Step 3: Target type inference
-    IF device_type == "auto":
-        # Components are typically desktop-first, pages can vary
-        device_type = target_type == "component" ? "desktop" : "responsive"
-        device_source = "target_type_inference"
-
-STORE: device_type, device_source
+design_source = classify_source(code_base_path, has_visual_input):
+    • code + visual → "hybrid"
+    • code only → "code_only"
+    • visual/prompt → "visual_only"
+    • none → ERROR
 ```
 
-**Device Type Presets**:
-- **Desktop**: 1920×1080px - Mouse-driven, spacious layouts
-- **Mobile**: 375×812px - Touch-friendly, compact layouts
-- **Tablet**: 768×1024px - Hybrid touch/mouse layouts
-- **Responsive**: 1920×1080px base with mobile-first breakpoints
+**Stored Variables**: `design_source`, `code_base_path`, `has_visual_input`, `images_input`, `prompt_text`
 
-**Detection Keywords**:
-- Prompt contains "mobile", "phone", "smartphone" → mobile
-- Prompt contains "tablet", "ipad" → tablet
-- Prompt contains "desktop", "web", "laptop" → desktop
-- Prompt contains "responsive", "adaptive" → responsive
-- Otherwise: Inferred from target type (components→desktop, pages→responsive)
+---
+
+### Phase 2: Intelligent Prompt Parsing
+
+**Unified Principle**: explicit > inferred > default
 
-### 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}"
+# Variant counts (priority chain)
+style_variants = --style-variants OR extract_number(prompt_text, "style") OR 3
+layout_variants = --layout-variants OR extract_number(prompt_text, "layout") OR 3
 
-Bash(mkdir -p "${base_path}/{style-extraction,style-consolidation,prototypes}")
+VALIDATE: 1 ≤ variants ≤ 5
+```
+
+**Stored Variables**: `style_variants`, `layout_variants`
+
+---
+
+### Phase 3: Device Type Inference
+
+**Unified Principle**: explicit > prompt keywords > target_type > default
+
+```bash
+# Device type (priority chain)
+device_type = --device-type (if != "auto")
+           OR detect_keywords(prompt_text, ["mobile", "desktop", "tablet", "responsive"])
+           OR infer_from_target(target_type)  # component→desktop, page→responsive
+           OR "responsive"
+
+device_source = track_detection_source()
+```
+
+**Detection Keywords**: mobile, phone, smartphone → mobile | desktop, web, laptop → desktop | tablet, ipad → tablet | responsive, adaptive → responsive
+
+**Device Presets**: Desktop (1920×1080) | Mobile (375×812) | Tablet (768×1024) | Responsive (1920×1080 + breakpoints)
+
+**Stored Variables**: `device_type`, `device_source`
+
+### Phase 4: Run Initialization & Directory Setup
+```bash
+design_id = "design-run-$(date +%Y%m%d)-$RANDOM"
+relative_base_path = --session ? ".workflow/active/WFS-{session}/${design_id}" : ".workflow/${design_id}"
+
+# Create directory and convert to absolute path
+Bash(mkdir -p "${relative_base_path}/style-extraction")
+Bash(mkdir -p "${relative_base_path}/prototypes")
+base_path=$(cd "${relative_base_path}" && pwd)
 
 Write({base_path}/.run-metadata.json): {
-  "run_id": "${run_id}", "session_id": "${session_id}", "timestamp": "...",
+  "design_id": "${design_id}", "session_id": "${session_id}", "timestamp": "...",
   "workflow": "ui-design:auto",
   "architecture": "style-centric-batch-generation",
   "parameters": { "style_variants": ${style_variants}, "layout_variants": ${layout_variants},
                   "targets": "${inferred_target_list}", "target_type": "${target_type}",
-                  "prompt": "${prompt_text}", "images": "${images_pattern}",
+                  "prompt": "${prompt_text}", "images": "${images_input}",
+                  "input": "${--input}",
                   "device_type": "${device_type}", "device_source": "${device_source}" },
   "status": "in_progress",
   "performance_mode": "optimized"
 }
+
+# Initialize default flags for animation extraction logic
+animation_complete = false  # Default: always extract animations unless code import proves complete
+needs_visual_supplement = false  # Will be set to true in hybrid mode
+skip_animation_extraction = false  # User preference for code import scenario
 ```
 
-### Phase 0c: Unified Target Inference with Intelligent Type Detection
+### Phase 5: 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"
@@ -198,8 +240,8 @@ ELSE IF --targets:
     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
+ELSE IF prompt_text:
+    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"
@@ -250,7 +292,7 @@ MATCH user_input:
 
 STORE: inferred_target_list, target_type, target_inference_source
 
-# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 1
+# ⚠️ CRITICAL: User confirmation complete, IMMEDIATELY initialize TodoWrite and execute Phase 7
 # This is the only user interaction point in the workflow
 # After this point, all subsequent phases execute automatically without user intervention
 ```
@@ -267,175 +309,245 @@ detect_target_type(target_list):
     RETURN "component" IF component_matches > page_matches ELSE "page"
 ```
 
-### Phase 1: Style Extraction
+### Phase 6: Code Import & Completeness Assessment (Conditional)
 ```bash
-command = "/workflow:ui-design:style-extract --base-path \"{base_path}\" " +
-          (--images ? "--images \"{images}\" " : "") +
-          (--prompt ? "--prompt \"{prompt}\" " : "") +
-          "--mode explore --variants {style_variants}"
-SlashCommand(command)
+IF design_source IN ["code_only", "hybrid"]:
+    REPORT: "🔍 Phase 6: Code Import ({design_source})"
+    command = "/workflow:ui-design:import-from-code --design-id \"{design_id}\" --source \"{code_base_path}\""
 
-# Output: {style_variants} style cards with design_attributes
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2.3 (auto-continue)
+    TRY:
+        # SlashCommand invocation ATTACHES import-from-code's tasks to current workflow
+        # Orchestrator will EXECUTE these attached tasks itself:
+        #   - Phase 0: Discover and categorize code files
+        #   - Phase 1.1-1.3: Style/Animation/Layout Agent extraction
+        SlashCommand(command)
+    CATCH error:
+        WARN: "⚠️ Code import failed: {error}"
+        WARN: "Cleaning up incomplete import directories"
+        Bash(rm -rf "{base_path}/style-extraction" "{base_path}/animation-extraction" "{base_path}/layout-extraction" 2>/dev/null)
+
+        IF design_source == "code_only":
+            REPORT: "Cannot proceed with code-only mode after import failure"
+            EXIT 1
+        ELSE:  # hybrid mode
+            WARN: "Continuing with visual-only mode"
+            design_source = "visual_only"
+
+    # Check file existence and assess completeness
+    style_exists = exists("{base_path}/style-extraction/style-1/design-tokens.json")
+    animation_exists = exists("{base_path}/animation-extraction/animation-tokens.json")
+    layout_count = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
+    layout_exists = (layout_count > 0)
+
+    style_complete = false
+    animation_complete = false
+    layout_complete = false
+    missing_categories = []
+
+    # Style completeness check
+    IF style_exists:
+        tokens = Read("{base_path}/style-extraction/style-1/design-tokens.json")
+        style_complete = (
+            tokens.colors?.brand && tokens.colors?.surface &&
+            tokens.typography?.font_family && tokens.spacing &&
+            Object.keys(tokens.colors.brand || {}).length >= 3 &&
+            Object.keys(tokens.spacing || {}).length >= 8
+        )
+        IF NOT style_complete AND tokens._metadata?.completeness?.missing_categories:
+            missing_categories.extend(tokens._metadata.completeness.missing_categories)
+    ELSE:
+        missing_categories.push("style tokens")
+
+    # Animation completeness check
+    IF animation_exists:
+        anim = Read("{base_path}/animation-extraction/animation-tokens.json")
+        animation_complete = (
+            anim.duration && anim.easing &&
+            Object.keys(anim.duration || {}).length >= 3 &&
+            Object.keys(anim.easing || {}).length >= 3
+        )
+        IF NOT animation_complete AND anim._metadata?.completeness?.missing_items:
+            missing_categories.extend(anim._metadata.completeness.missing_items)
+    ELSE:
+        missing_categories.push("animation tokens")
+
+    # Layout completeness check
+    IF layout_exists:
+        # Read first layout file to verify structure
+        first_layout = bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | head -1)
+        layout_data = Read(first_layout)
+        layout_complete = (
+            layout_count >= 1 &&
+            layout_data.template?.dom_structure &&
+            layout_data.template?.css_layout_rules
+        )
+        IF NOT layout_complete:
+            missing_categories.push("complete layout structure")
+    ELSE:
+        missing_categories.push("layout templates")
+
+    needs_visual_supplement = false
+
+    IF design_source == "code_only" AND NOT (style_complete AND layout_complete):
+        REPORT: "⚠️  Missing: {', '.join(missing_categories)}"
+        REPORT: "Options: 'continue' | 'supplement: <images>' | 'cancel'"
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+            "continue" → needs_visual_supplement = false
+            "supplement: ..." → needs_visual_supplement = true; --images = extract_path(user_response)
+            "cancel" → EXIT 0
+            default → needs_visual_supplement = false
+    ELSE IF design_source == "hybrid":
+        needs_visual_supplement = true
+
+    # Animation reuse confirmation (code import with complete animations)
+    IF design_source == "code_only" AND animation_complete:
+        REPORT: "✅ Complete animation system detected (from code import)"
+        REPORT: "   Duration scales: {duration_count} | Easing functions: {easing_count}"
+        REPORT: ""
+        REPORT: "Options:"
+        REPORT: "  • 'reuse' (default) - Reuse existing animation system"
+        REPORT: "  • 'regenerate' - Regenerate animation system (interactive)"
+        REPORT: "  • 'cancel' - Cancel workflow"
+        user_response = WAIT_FOR_USER_INPUT()
+        MATCH user_response:
+            "reuse" → skip_animation_extraction = true
+            "regenerate" → skip_animation_extraction = false
+            "cancel" → EXIT 0
+            default → skip_animation_extraction = true  # Default: reuse
+
+    STORE: needs_visual_supplement, style_complete, animation_complete, layout_complete, skip_animation_extraction
 ```
 
-### Phase 2.3: Animation Extraction (Optional - Interactive Mode)
+### Phase 7: Style Extraction
 ```bash
-# Animation extraction for motion design patterns
-REPORT: "🚀 Phase 2.3: Animation Extraction (interactive mode)"
-REPORT: "   → Mode: Interactive specification"
-REPORT: "   → Purpose: Define motion design patterns"
+IF design_source == "visual_only" OR needs_visual_supplement:
+    REPORT: "🎨 Phase 7: Style Extraction (variants: {style_variants})"
+    command = "/workflow:ui-design:style-extract --design-id \"{design_id}\" " +
+              (images_input ? "--images \"{images_input}\" " : "") +
+              (prompt_text ? "--prompt \"{prompt_text}\" " : "") +
+              "--variants {style_variants} --interactive"
 
-command = "/workflow:ui-design:animation-extract --base-path \"{base_path}\" --mode interactive"
+    # SlashCommand invocation ATTACHES style-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
+    SlashCommand(command)
 
-SlashCommand(command)
+    # After executing all attached tasks, collapse them into phase summary
+ELSE:
+    REPORT: "✅ Phase 7: Style (Using Code Import)"
+```
+
+### Phase 8: Animation Extraction
+```bash
+# Determine if animation extraction is needed
+should_extract_animation = false
+
+IF (design_source == "visual_only" OR needs_visual_supplement):
+    # Pure visual input or hybrid mode requiring visual supplement
+    should_extract_animation = true
+ELSE IF NOT animation_complete:
+    # Code import but animations are incomplete
+    should_extract_animation = true
+ELSE IF design_source == "code_only" AND animation_complete AND NOT skip_animation_extraction:
+    # Code import with complete animations, but user chose to regenerate
+    should_extract_animation = true
+
+IF should_extract_animation:
+    REPORT: "🚀 Phase 8: Animation Extraction"
+
+    # Build command with available inputs
+    command_parts = [f"/workflow:ui-design:animation-extract --design-id \"{design_id}\""]
+
+    IF images_input:
+        command_parts.append(f"--images \"{images_input}\"")
+
+    IF prompt_text:
+        command_parts.append(f"--prompt \"{prompt_text}\"")
+
+    command_parts.append("--interactive")
+
+    command = " ".join(command_parts)
+
+    # SlashCommand invocation ATTACHES animation-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
+    SlashCommand(command)
+
+    # After executing all attached tasks, collapse them into phase summary
+ELSE:
+    REPORT: "✅ Phase 8: Animation (Using Code Import)"
 
 # Output: animation-tokens.json + animation-guide.md
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 2.5 (auto-continue)
+# When phase finishes, IMMEDIATELY execute Phase 9 (auto-continue)
 ```
 
-### Phase 2.5: Layout Extraction
+### Phase 9: Layout Extraction
 ```bash
 targets_string = ",".join(inferred_target_list)
-command = "/workflow:ui-design:layout-extract --base-path \"{base_path}\" " +
-          (--images ? "--images \"{images}\" " : "") +
-          (--prompt ? "--prompt \"{prompt}\" " : "") +
-          "--targets \"{targets_string}\" " +
-          "--mode explore --variants {layout_variants} " +
-          "--device-type \"{device_type}\""
 
-REPORT: "🚀 Phase 2.5: Layout Extraction (explore mode)"
-REPORT: "   → Targets: {targets_string}"
-REPORT: "   → Layout variants: {layout_variants}"
-REPORT: "   → Device: {device_type}"
+IF (design_source == "visual_only" OR needs_visual_supplement) OR (NOT layout_complete):
+    REPORT: "🚀 Phase 9: Layout Extraction ({targets_string}, variants: {layout_variants}, device: {device_type})"
+    command = "/workflow:ui-design:layout-extract --design-id \"{design_id}\" " +
+              (images_input ? "--images \"{images_input}\" " : "") +
+              (prompt_text ? "--prompt \"{prompt_text}\" " : "") +
+              "--targets \"{targets_string}\" --variants {layout_variants} --device-type \"{device_type}\" --interactive"
 
-SlashCommand(command)
+    # SlashCommand invocation ATTACHES layout-extract's tasks to current workflow
+    # Orchestrator will EXECUTE these attached tasks itself
+    SlashCommand(command)
 
-# Output: layout-templates.json with {targets × layout_variants} layout structures
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 3 (auto-continue)
+    # After executing all attached tasks, collapse them into phase summary
+ELSE:
+    REPORT: "✅ Phase 9: Layout (Using Code Import)"
 ```
 
-### Phase 3: UI Assembly
+### Phase 10: UI Assembly
 ```bash
-command = "/workflow:ui-design:generate --base-path \"{base_path}\" " +
-          "--style-variants {style_variants} --layout-variants {layout_variants}"
+command = "/workflow:ui-design:generate --design-id \"{design_id}\"" + (--session ? " --session {session_id}" : "")
 
 total = style_variants × layout_variants × len(inferred_target_list)
 
-REPORT: "🚀 Phase 3: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
+REPORT: "🚀 Phase 10: UI Assembly | Matrix: {s}×{l}×{n} = {total} prototypes"
 REPORT: "   → Pure assembly: Combining layout templates + design tokens"
 REPORT: "   → Device: {device_type} (from layout templates)"
 REPORT: "   → Assembly tasks: {total} combinations"
 
+# SlashCommand invocation ATTACHES generate's tasks to current workflow
+# Orchestrator will EXECUTE these attached tasks itself
 SlashCommand(command)
 
-# SlashCommand blocks until phase complete
-# Upon completion, IMMEDIATELY execute Phase 4 (auto-continue)
-# Output:
+# After executing all attached tasks, collapse them into phase summary
+# Workflow complete - generate command handles preview file generation (compare.html, PREVIEW.md)
+# Output (generated by generate command):
 # - {target}-style-{s}-layout-{l}.html (assembled prototypes)
 # - {target}-style-{s}-layout-{l}.css
 # - compare.html (interactive matrix view)
 # - PREVIEW.md (usage instructions)
 ```
 
-### Phase 4: Design System Integration
-```bash
-command = "/workflow:ui-design:update" + (--session ? " --session {session_id}" : "")
-SlashCommand(command)
-
-# SlashCommand blocks until phase complete
-# Upon completion:
-#   - If --batch-plan flag present: IMMEDIATELY execute Phase 5 (auto-continue)
-#   - If no --batch-plan: Workflow complete, display final report
-```
-
-### Phase 5: Batch Task Generation (Optional)
-```bash
-IF --batch-plan:
-    FOR target IN inferred_target_list:
-        task_desc = "Implement {target} {target_type} based on design system"
-        SlashCommand("/workflow:plan --agent \"{task_desc}\"")
-```
-
 ## TodoWrite Pattern
 ```javascript
-// Initialize IMMEDIATELY after Phase 0c user confirmation to track multi-phase execution
+// Initialize IMMEDIATELY after Phase 5 user confirmation to track multi-phase execution (4 orchestrator-level tasks)
 TodoWrite({todos: [
-  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing..."},
-  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing..."},
-  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing..."},
-  {"content": "Execute design integration", "status": "pending", "activeForm": "Executing..."}
+  {"content": "Execute style extraction", "status": "in_progress", "activeForm": "Executing style extraction"},
+  {"content": "Execute animation extraction", "status": "pending", "activeForm": "Executing animation extraction"},
+  {"content": "Execute layout extraction", "status": "pending", "activeForm": "Executing layout extraction"},
+  {"content": "Execute UI assembly", "status": "pending", "activeForm": "Executing UI assembly"}
 ]})
 
-// ⚠️ CRITICAL: After EACH SlashCommand completion (Phase 1-5), you MUST:
-// 1. SlashCommand blocks and returns when phase is complete
-// 2. Update current phase: status → "completed"
-// 3. Update next phase: status → "in_progress"
-// 4. IMMEDIATELY execute next phase SlashCommand (auto-continue)
-// This ensures continuous workflow tracking and prevents premature stopping
-```
-
-## Key Features
-
-- **🚀 Performance**: Style-centric batch generation with S agent calls
-- **🎨 Style-Aware**: HTML structure adapts to design_attributes
-- **✅ Perfect Consistency**: Each style by single agent
-- **📦 Autonomous**: No user intervention required between phases
-- **🧠 Intelligent**: Parses natural language, infers targets/types
-- **🔄 Reproducible**: Deterministic flow with isolated run directories
-- **🎯 Flexible**: Supports pages, components, or mixed targets
-
-## Examples
-
-### 1. Page Mode (Prompt Inference)
-```bash
-/workflow:ui-design:explore-auto --prompt "Modern blog: home, article, author"
-# Result: 27 prototypes (3×3×3) - responsive layouts (default)
-```
-
-### 2. Mobile-First Design
-```bash
-/workflow:ui-design:explore-auto --prompt "Mobile shopping app: home, product, cart" --device-type mobile
-# Result: 27 prototypes (3×3×3) - mobile layouts (375×812px)
-```
-
-### 3. Desktop Application
-```bash
-/workflow:ui-design:explore-auto --targets "dashboard,analytics,settings" --device-type desktop --style-variants 2 --layout-variants 2
-# Result: 12 prototypes (2×2×3) - desktop layouts (1920×1080px)
-```
-
-### 4. Tablet Interface
-```bash
-/workflow:ui-design:explore-auto --prompt "Educational app for tablets" --device-type tablet --targets "courses,lessons,profile"
-# Result: 27 prototypes (3×3×3) - tablet layouts (768×1024px)
-```
-
-### 5. Custom Matrix with Session
-```bash
-/workflow:ui-design:explore-auto --session WFS-ecommerce --images "refs/*.png" --style-variants 2 --layout-variants 2
-# Result: 2×2×N prototypes - device type inferred from session
-```
-
-### 6. Component Mode (Desktop)
-```bash
-/workflow:ui-design:explore-auto --targets "navbar,hero" --target-type "component" --device-type desktop --style-variants 3 --layout-variants 2
-# Result: 12 prototypes (3×2×2) - desktop components
-```
-
-### 7. Intelligent Parsing + Batch Planning
-```bash
-/workflow:ui-design:explore-auto --prompt "Create 4 styles with 2 layouts for mobile dashboard and settings" --batch-plan
-# Result: 16 prototypes (4×2×2) + auto-generated tasks - mobile-optimized (inferred from prompt)
-```
-
-### 8. Large Scale Responsive
-```bash
-/workflow:ui-design:explore-auto --targets "home,dashboard,settings,profile" --device-type responsive --style-variants 3 --layout-variants 3
-# Result: 36 prototypes (3×3×4) - responsive layouts
+// ⚠️ CRITICAL: Dynamic TodoWrite task attachment strategy:
+//
+// **Key Concept**: SlashCommand invocation ATTACHES tasks to current workflow.
+// Orchestrator EXECUTES these attached tasks itself, not waiting for external completion.
+//
+// Phase 7-10 SlashCommand Invocation Pattern:
+// 1. SlashCommand invocation ATTACHES sub-command tasks to TodoWrite
+// 2. TodoWrite expands to include attached tasks
+// 3. Orchestrator EXECUTES attached tasks sequentially
+// 4. After all attached tasks complete, COLLAPSE them into phase summary
+// 5. Update next phase to in_progress
+// 6. IMMEDIATELY execute next phase (auto-continue)
+// 7. After Phase 10 completes, workflow finishes (generate command handles preview files)
+//
 ```
 
 ## Completion Output
@@ -446,34 +558,37 @@ Architecture: Style-Centric Batch Generation
 Run ID: {run_id} | Session: {session_id or "standalone"}
 Type: {icon} {target_type} | Device: {device_type} | Matrix: {s}×{l}×{n} = {total} prototypes
 
-Phase 1: {s} complete design systems (style-extract)
-Phase 2: {n×l} layout templates (layout-extract explore mode)
+Phase 7: {s} complete design systems (style-extract with multi-select)
+Phase 9: {n×l} layout templates (layout-extract with multi-select)
   - Device: {device_type} layouts
   - {n} targets × {l} layout variants = {n×l} structural templates
-Phase 3: UI Assembly (generate)
+  - User-selected concepts generated in parallel
+Phase 10: UI Assembly (generate)
   - Pure assembly: layout templates + design tokens
   - {s}×{l}×{n} = {total} final prototypes
-Phase 4: Brainstorming artifacts updated
-[Phase 5: {n} implementation tasks created]  # if --batch-plan
+  - Preview files: compare.html, PREVIEW.md (auto-generated by generate command)
 
 Assembly Process:
 ✅ Separation of Concerns: Layout (structure) + Style (tokens) kept separate
 ✅ Layout Extraction: {n×l} reusable structural templates
+✅ Multi-Selection Workflow: User selects multiple variants from generated options
 ✅ Pure Assembly: No design decisions in generate phase
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 Design Quality:
 ✅ Token-Driven Styling: 100% var() usage
-✅ Structural Variety: {l} distinct layouts per target
-✅ Style Variety: {s} independent design systems
+✅ Structural Variety: {l} distinct layouts per target (user-selected)
+✅ Style Variety: {s} independent design systems (user-selected)
 ✅ Device-Optimized: Layouts designed for {device_type}
 
 📂 {base_path}/
   ├── .intermediates/          (Intermediate analysis files)
-  │   ├── style-analysis/      (computed-styles.json, design-space-analysis.json)
-  │   └── layout-analysis/     (dom-structure-*.json, inspirations/*.txt)
+  │   ├── style-analysis/      (analysis-options.json with embedded user_selection, computed-styles.json if URL mode)
+  │   ├── animation-analysis/  (analysis-options.json with embedded user_selection, animations-*.json if URL mode)
+  │   └── layout-analysis/     (analysis-options.json with embedded user_selection, dom-structure-*.json if URL mode)
   ├── style-extraction/        ({s} complete design systems)
-  ├── layout-extraction/       ({n×l} layout templates + layout-space-analysis.json)
+  ├── animation-extraction/    (animation-tokens.json, animation-guide.md)
+  ├── layout-extraction/       ({n×l} layout template files: layout-{target}-{variant}.json)
   ├── prototypes/              ({total} assembled prototypes)
   └── .run-metadata.json       (includes device type)
 
@@ -489,6 +604,6 @@ Design Quality:
   - Layout plans stored as structured JSON
   - Optimized for {device_type} viewing
 
-Next: [/workflow:execute] OR [Open compare.html → Select → /workflow:plan]
+Next: Open compare.html to preview all design variants
 ```
 

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

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

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

@@ -1,7 +1,7 @@
 ---
 name: generate
-description: Assemble UI prototypes by combining layout templates with design tokens (pure assembler)
-argument-hint: [--base-path <path>] [--session <id>] [--style-variants <count>] [--layout-variants <count>]
+description: Assemble UI prototypes by combining layout templates with design tokens (default animation support), pure assembler without new content generation
+argument-hint: [--design-id <id>] [--session <id>]
 allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 ---
 
@@ -11,7 +11,7 @@ allowed-tools: TodoWrite(*), Read(*), Write(*), Task(ui-design-agent), Bash(*)
 Pure assembler that combines pre-extracted layout templates with design tokens to generate UI prototypes (`style × layout × targets`). No layout design logic - purely combines existing components.
 
 **Strategy**: Pure Assembly
-- **Input**: `layout-templates.json` + `design-tokens.json` (+ reference images if available)
+- **Input**: `layout-*.json` files + `design-tokens.json` (+ reference images if available)
 - **Process**: Combine structure (DOM) with style (tokens)
 - **Output**: Complete HTML/CSS prototypes
 - **No Design Logic**: All layout and style decisions already made
@@ -25,23 +25,48 @@ Pure assembler that combines pre-extracted layout templates with design tokens t
 
 ### Step 1: Resolve Base Path & Parse Configuration
 ```bash
-# Determine working directory
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/active/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 
 # Get style count
-bash(ls {base_path}/style-extraction/style-* -d | wc -l)
+bash(ls "$base_path"/style-extraction/style-* -d | wc -l)
 
 # Image reference auto-detected from layout template source_image_path
 ```
 
 ### Step 2: Load Layout Templates
 ```bash
-# Check layout templates exist
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# Check layout templates exist (multi-file pattern)
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
 
-# Load layout templates
-Read({base_path}/layout-extraction/layout-templates.json)
-# Extract: targets, layout_variants count, device_type, template structures
+# Get list of all layout files
+bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null)
+
+# Load each layout template file
+FOR each layout_file in layout_files:
+    template_data = Read(layout_file)
+    # Extract: target, variant_id, device_type, dom_structure, css_layout_rules
+
+# Aggregate: targets[], layout_variants count, device_type, all template structures
 ```
 
 **Output**: `base_path`, `style_variants`, `layout_templates[]`, `targets[]`, `device_type`
@@ -74,32 +99,103 @@ ELSE:
 
 ## Phase 2: Assembly (Agent)
 
-**Executor**: `Task(ui-design-agent)` × `T × S × L` tasks (can be batched)
+**Executor**: `Task(ui-design-agent)` grouped by `target × style` (max 10 layouts per agent, max 6 concurrent agents)
 
-### Step 1: Launch Assembly Tasks
-```bash
-bash(mkdir -p {base_path}/prototypes)
+**⚠️ Core Principle**: **Each agent processes ONLY ONE style** (but can process multiple layouts for that style)
+
+### Agent Grouping Strategy
+
+**Grouping Rules**:
+1. **Style Isolation**: Each agent processes ONLY ONE style (never mixed)
+2. **Balanced Distribution**: Layouts evenly split (e.g., 12→6+6, not 10+2)
+3. **Target Separation**: Different targets use different agents
+
+**Distribution Formula**:
+```
+agents_needed = ceil(layout_count / MAX_LAYOUTS_PER_AGENT)
+base_count = floor(layout_count / agents_needed)
+remainder = layout_count % agents_needed
+# First 'remainder' agents get (base_count + 1), others get base_count
 ```
 
-For each `target × style_id × layout_id`:
+**Examples** (MAX=10):
+
+| Scenario | Result | Explanation |
+|----------|--------|-------------|
+| 3 styles × 3 layouts | 3 agents | Each style: 1 agent (3 layouts) |
+| 3 styles × 12 layouts | 6 agents | Each style: 2 agents (6+6 layouts) |
+| 2 styles × 5 layouts × 2 targets | 4 agents | Each (target, style): 1 agent (5 layouts) |
+
+### Step 1: Calculate Agent Grouping Plan
+```bash
+bash(mkdir -p {base_path}/prototypes)
+
+MAX_LAYOUTS_PER_AGENT = 10
+MAX_PARALLEL = 6
+
+agent_groups = []
+FOR each target in targets:
+  FOR each style_id in [1..S]:
+    layouts_for_this_target_style = filter layouts by current target
+    layout_count = len(layouts_for_this_target_style)
+
+    # Balanced distribution (e.g., 12 layouts → 6+6)
+    agents_needed = ceil(layout_count / MAX_LAYOUTS_PER_AGENT)
+    base_count = floor(layout_count / agents_needed)
+    remainder = layout_count % agents_needed
+
+    layout_chunks = []
+    start_idx = 0
+    FOR i in range(agents_needed):
+      chunk_size = base_count + 1 if i < remainder else base_count
+      layout_chunks.append(layouts[start_idx : start_idx + chunk_size])
+      start_idx += chunk_size
+
+    FOR each chunk in layout_chunks:
+      agent_groups.append({
+        target: target,           # Single target
+        style_id: style_id,       # Single style
+        layout_ids: chunk         # Balanced layouts (≤10)
+      })
+
+total_agents = len(agent_groups)
+total_batches = ceil(total_agents / MAX_PARALLEL)
+
+TodoWrite({todos: [
+  {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
+  {content: "Batch 1/{total_batches}: Assemble up to 6 agent groups", status: "in_progress", activeForm: "Assembling batch 1"},
+  {content: "Batch 2/{total_batches}: Assemble up to 6 agent groups", status: "pending", activeForm: "Assembling batch 2"},
+  ... (continue for all batches)
+]})
+```
+
+### Step 2: Launch Batched Assembly Tasks
+
+For each batch (up to 6 parallel agents per batch):
+For each agent group `{target, style_id, layout_ids[]}` in current batch:
 ```javascript
 Task(ui-design-agent): `
   [LAYOUT_STYLE_ASSEMBLY]
-  🎯 Assembly task: {target} × Style-{style_id} × Layout-{layout_id}
-  Combine: Pre-extracted layout structure + design tokens → Final HTML/CSS
+  🎯 {target} × Style-{style_id} × Layouts-{layout_ids}
+  ⚠️ CONSTRAINT: Use ONLY style-{style_id}/design-tokens.json (never mix styles)
 
-  TARGET: {target} | STYLE: {style_id} | LAYOUT: {layout_id}
+  TARGET: {target} | STYLE: {style_id} | LAYOUTS: {layout_ids} (max 10)
   BASE_PATH: {base_path}
 
   ## Inputs (READ ONLY - NO DESIGN DECISIONS)
-  1. Layout Template:
-     Read("{base_path}/layout-extraction/layout-templates.json")
-     Find template where: target={target} AND variant_id="layout-{layout_id}"
-     Extract: dom_structure, css_layout_rules, device_type, source_image_path
+  1. Layout Templates (LOOP THROUGH):
+     FOR each layout_id in layout_ids:
+       Read("{base_path}/layout-extraction/layout-{target}-{layout_id}.json")
+       This file contains the specific layout template for this target and variant.
+       Extract: dom_structure, css_layout_rules, device_type, source_image_path (from template field)
 
-  2. Design Tokens:
+  2. Design Tokens (SHARED - READ ONCE):
      Read("{base_path}/style-extraction/style-{style_id}/design-tokens.json")
-     Extract: ALL token values (colors, typography, spacing, borders, shadows, breakpoints)
+     Extract: ALL token values including:
+       * colors, typography (with combinations), spacing, opacity
+       * border_radius, shadows, breakpoints
+       * component_styles (button, card, input variants)
+     Note: typography.combinations, opacity, and component_styles fields contain preset configurations using var() references
 
   3. Animation Tokens (OPTIONAL):
      IF exists("{base_path}/animation-extraction/animation-tokens.json"):
@@ -117,51 +213,70 @@ Task(ui-design-agent): `
      ELSE:
        Use generic placeholder content
 
-  ## Assembly Process
-  1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
-     - Recursively build from template.dom_structure
-     - Add: <!DOCTYPE html>, <head>, <meta viewport>
-     - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
-     - Inject placeholder content:
-       * Default: Use Lorem ipsum, generic sample data
-       * If reference image available: Generate more contextually appropriate placeholders
-         (e.g., realistic headings, meaningful text snippets that match the visual context)
-     - Preserve all attributes from dom_structure
+  ## Assembly Process (LOOP FOR EACH LAYOUT)
+  FOR each layout_id in layout_ids:
 
-  2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
-     - Start with template.css_layout_rules
-     - Replace ALL var(--*) with actual token values from design-tokens.json
-       Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
-       Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
-     - Add visual styling using design tokens:
-       * Colors: tokens.colors.*
-       * Typography: tokens.typography.*
-       * Shadows: tokens.shadows.*
-       * Border radius: tokens.border_radius.*
-     - IF has_animations == true: Inject animation tokens
-       * Add CSS Custom Properties for animations at :root level:
-         --duration-instant, --duration-fast, --duration-normal, etc.
-         --easing-linear, --easing-ease-out, etc.
-       * Add @keyframes rules from animation_tokens.keyframes
-       * Add interaction classes (.button-hover, .card-hover) from animation_tokens.interactions
-       * Add utility classes (.transition-color, .transition-transform) from animation_tokens.transitions
-       * Include prefers-reduced-motion media query for accessibility
-     - Device-optimized for template.device_type
+    1. Build HTML: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html
+       - Recursively build from template.dom_structure
+       - Add: <!DOCTYPE html>, <head>, <meta viewport>
+       - CSS link: <link href="{target}-style-{style_id}-layout-{layout_id}.css">
+       - Inject placeholder content:
+         * Default: Use Lorem ipsum, generic sample data
+         * If reference image available: Generate more contextually appropriate placeholders
+           (e.g., realistic headings, meaningful text snippets that match the visual context)
+       - Preserve all attributes from dom_structure
+
+    2. Build CSS: {base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.css
+       - Start with template.css_layout_rules
+       - Replace ALL var(--*) with actual token values from design-tokens.json
+         Example: var(--spacing-4) → 1rem (from tokens.spacing.4)
+         Example: var(--breakpoint-md) → 768px (from tokens.breakpoints.md)
+         Example: var(--opacity-80) → 0.8 (from tokens.opacity.80)
+       - Add visual styling using design tokens:
+         * Colors: tokens.colors.*
+         * Typography: tokens.typography.* (including combinations)
+         * Opacity: tokens.opacity.*
+         * Shadows: tokens.shadows.*
+         * Border radius: tokens.border_radius.*
+       - IF tokens.component_styles exists: Add component style classes
+         * Generate classes for button variants (.btn-primary, .btn-secondary)
+         * Generate classes for card variants (.card-default, .card-interactive)
+         * Generate classes for input variants (.input-default, .input-focus, .input-error)
+         * Use var() references that resolve to actual token values
+       - IF tokens.typography.combinations exists: Add typography preset classes
+         * Generate classes for typography presets (.text-heading-primary, .text-body-regular, .text-caption)
+         * Use var() references for family, size, weight, line-height, letter-spacing
+       - IF has_animations == true: Inject animation tokens (ONCE, shared across layouts)
+         * Add CSS Custom Properties for animations at :root level:
+           --duration-instant, --duration-fast, --duration-normal, etc.
+           --easing-linear, --easing-ease-out, etc.
+         * Add @keyframes rules from animation_tokens.keyframes
+         * Add interaction classes (.button-hover, .card-hover) from animation_tokens.interactions
+         * Add utility classes (.transition-color, .transition-transform) from animation_tokens.transitions
+         * Include prefers-reduced-motion media query for accessibility
+       - Device-optimized for template.device_type
+
+    3. Write files IMMEDIATELY after each layout completes
 
   ## Assembly Rules
-  - ✅ Pure assembly: Combine existing structure + existing style
-  - ❌ NO layout design decisions (structure pre-defined)
-  - ❌ NO style design decisions (tokens pre-defined)
+  - ✅ Pure assembly: Combine pre-extracted structure + tokens
+  - ❌ NO design decisions (layout/style pre-defined)
+  - ✅ Read tokens ONCE, apply to all layouts in this batch
   - ✅ Replace var() with actual values
-  - ✅ Add placeholder content only
-  - Write files IMMEDIATELY
-  - CSS filename MUST match HTML <link href="...">
+  - ✅ CSS filename MUST match HTML <link href="...">
+
+  ## Output
+  - Files: {len(layout_ids) × 2} (HTML + CSS pairs)
+  - Each layout generates 2 files independently
 `
+
+# After each batch completes
+TodoWrite: Mark current batch completed, next batch in_progress
 ```
 
-### Step 2: Verify Generated Files
+### Step 3: Verify Generated Files
 ```bash
-# Count expected vs found
+# Count expected vs found (should equal S × L × T)
 bash(ls {base_path}/prototypes/{target}-style-*-layout-*.html | wc -l)
 
 # Validate samples
@@ -169,7 +284,7 @@ Read({base_path}/prototypes/{target}-style-{style_id}-layout-{layout_id}.html)
 # Check: <!DOCTYPE html>, correct CSS href, sufficient CSS length
 ```
 
-**Output**: `S × L × T × 2` files verified
+**Output**: `total_files = S × L × T × 2` files verified (HTML + CSS pairs)
 
 ## Phase 3: Generate Preview Files
 
@@ -196,10 +311,10 @@ bash(ls {base_path}/prototypes/compare.html {base_path}/prototypes/index.html {b
 ```javascript
 TodoWrite({todos: [
   {content: "Setup and validation", status: "completed", activeForm: "Loading design systems"},
-  {content: "Load layout templates", status: "completed", activeForm: "Reading layout templates"},
-  {content: "Assembly (agent)", status: "completed", activeForm: "Assembling prototypes"},
-  {content: "Verify files", status: "completed", activeForm: "Validating output"},
-  {content: "Generate previews", status: "completed", activeForm: "Creating preview files"}
+  {content: "Batch 1/{total_batches}: Assemble 6 tasks", status: "completed", activeForm: "Assembling batch 1"},
+  {content: "Batch 2/{total_batches}: Assemble 6 tasks", status: "completed", activeForm: "Assembling batch 2"},
+  ... (all batches completed)
+  {content: "Verify files & generate previews", status: "completed", activeForm: "Creating previews"}
 ]});
 ```
 
@@ -209,33 +324,41 @@ TodoWrite({todos: [
 
 Configuration:
 - Style Variants: {style_variants}
-- Layout Variants: {layout_variants} (from layout-templates.json)
+- Layout Variants: {layout_variants} (from layout-*.json files)
 - Device Type: {device_type}
 - Targets: {targets}
 - Total Prototypes: {S × L × T}
 - Image Reference: Auto-detected (uses source images when available in layout templates)
+- Animation Support: {has_animations ? 'Enabled (animation-tokens.json loaded)' : 'Not available'}
 
 Assembly Process:
 - Pure assembly: Combined pre-extracted layouts + design tokens
-- No design decisions: All structure and style pre-defined
-- Assembly tasks: T×S×L = {T}×{S}×{L} = {T×S×L} combinations
+- Agent grouping: target × style (max 10 layouts per agent)
+- Balanced distribution: Layouts evenly split (e.g., 12 → 6+6, not 10+2)
+
+Batch Execution:
+- Total agents: {total_agents} (each processes ONE style only)
+- Batches: {total_batches} (max 6 agents parallel)
+- Token efficiency: Read once per agent, apply to all layouts
 
 Quality:
 - Structure: From layout-extract (DOM, CSS layout rules)
 - Style: From style-extract (design tokens)
 - CSS: Token values directly applied (var() replaced)
 - Device-optimized: Layouts match device_type from templates
+- Animations: {has_animations ? 'CSS custom properties and @keyframes injected' : 'Static styles only'}
 
 Generated Files:
 {base_path}/prototypes/
-├── _templates/
-│   └── layout-templates.json (input, pre-extracted)
 ├── {target}-style-{s}-layout-{l}.html ({S×L×T} prototypes)
 ├── {target}-style-{s}-layout-{l}.css
 ├── compare.html (interactive matrix)
 ├── index.html (navigation)
 └── PREVIEW.md (instructions)
 
+Input Files (from layout-extraction/):
+├── layout-{target}-{variant}.json (multiple files, one per target-variant combination)
+
 Preview:
 1. Open compare.html (recommended)
 2. Open index.html
@@ -249,7 +372,7 @@ Next: /workflow:ui-design:update
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Count style variants
 bash(ls {base_path}/style-extraction/style-* -d | wc -l)
@@ -257,8 +380,11 @@ bash(ls {base_path}/style-extraction/style-* -d | wc -l)
 
 ### Validation Commands
 ```bash
-# Check layout templates exist
-bash(test -f {base_path}/layout-extraction/layout-templates.json && echo "exists")
+# Check layout templates exist (multi-file pattern)
+bash(find {base_path}/layout-extraction -name "layout-*.json" -print -quit | grep -q . && echo "exists")
+
+# Count layout files
+bash(ls {base_path}/layout-extraction/layout-*.json 2>/dev/null | wc -l)
 
 # Check design tokens exist
 bash(test -f {base_path}/style-extraction/style-1/design-tokens.json && echo "valid")
@@ -284,10 +410,10 @@ bash(~/.claude/scripts/ui-generate-preview.sh "{base_path}/prototypes")
 ```
 {base_path}/
 ├── layout-extraction/
-│   └── layout-templates.json      # Input (from layout-extract)
+│   └── layout-{target}-{variant}.json  # Input (multiple files from layout-extract)
 ├── style-extraction/
 │   └── style-{s}/
-│       ├── design-tokens.json     # Input (from style-extract)
+│       ├── design-tokens.json          # Input (from style-extract)
 │       └── style-guide.md
 └── prototypes/
     ├── {target}-style-{s}-layout-{l}.html  # Assembled prototypes
@@ -316,7 +442,7 @@ ERROR: Script permission denied
 
 ### Recovery Strategies
 - **Partial success**: Keep successful assembly combinations
-- **Invalid template structure**: Validate layout-templates.json
+- **Invalid template structure**: Validate layout-*.json files
 - **Invalid tokens**: Validate design-tokens.json structure
 
 ## Quality Checklist
@@ -332,18 +458,17 @@ ERROR: Script permission denied
 ## Key Features
 
 - **Pure Assembly**: No design decisions, only combination
-- **Separation of Concerns**: Layout (structure) + Style (tokens) kept separate until final assembly
-- **Token Resolution**: var() placeholders replaced with actual values
-- **Pre-validated**: Inputs already validated by extract/consolidate
-- **Efficient**: Simple assembly vs complex generation
+- **Token Resolution**: var() → actual values
+- **Efficient Grouping**: target × style (max 10 layouts/agent, balanced split)
+- **Style Isolation**: Each agent processes ONE style only
 - **Production-Ready**: Semantic, accessible, token-driven
 
 ## Integration
 
 **Prerequisites**:
 - `/workflow:ui-design:style-extract` → `design-tokens.json` + `style-guide.md`
-- `/workflow:ui-design:layout-extract` → `layout-templates.json`
+- `/workflow:ui-design:layout-extract` → `layout-{target}-{variant}.json` files
 
-**Input**: `layout-templates.json` + `design-tokens.json`
+**Input**: `layout-*.json` files + `design-tokens.json`
 **Output**: S×L×T prototypes for `/workflow:ui-design:update`
 **Called by**: `/workflow:ui-design:explore-auto`, `/workflow:ui-design:imitate-auto`

.claude/commands/workflow/ui-design/import-from-code.md

@@ -0,0 +1,518 @@
+---
+name: workflow:ui-design:import-from-code
+description: Import design system from code files (CSS/JS/HTML/SCSS) with automatic file discovery and parallel agent analysis
+argument-hint: "[--design-id <id>] [--session <id>] [--source <path>]"
+allowed-tools: Read,Write,Bash,Glob,Grep,Task,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Import from Code
+
+## Overview
+
+Extract design system tokens from source code files (CSS/SCSS/JS/TS/HTML) using parallel agent analysis. Each agent can reference any file type for cross-source token extraction, and directly generates completeness reports with findings and gaps.
+
+**Key Characteristics**:
+- Executes parallel agent analysis (3 agents: Style, Animation, Layout)
+- Each agent can read ALL file types (CSS/SCSS/JS/TS/HTML) for cross-reference
+- Direct completeness reporting without synthesis phase
+- Graceful failure handling with detailed missing content analysis
+- Returns concrete analysis results with recommendations
+
+## Core Functionality
+
+- **File Discovery**: Auto-discover or target specific CSS/SCSS/JS/HTML files
+- **Parallel Analysis**: 3 agents extract tokens simultaneously with cross-file-type support
+- **Completeness Reporting**: Each agent reports found tokens, missing content, and recommendations
+- **Cross-Source Extraction**: Agents can reference any file type (e.g., Style agent can read JS theme configs)
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:import-from-code [FLAGS]
+
+# Flags
+--design-id <id>        Design run ID to import into (must exist)
+--session <id>          Session ID (uses latest design run in session)
+--source <path>         Source code directory to analyze (required)
+```
+
+**Note**: All file discovery is automatic. The command will scan the source directory and find all relevant style files (CSS, SCSS, JS, HTML) automatically.
+
+## Execution Process
+
+### Step 1: Setup & File Discovery
+
+**Purpose**: Initialize session, discover and categorize code files
+
+**Operations**:
+
+```bash
+# 1. Determine base path with priority: --design-id > --session > error
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+  if [ -z "$relative_path" ]; then
+    echo "ERROR: Design run not found: $DESIGN_ID"
+    echo "HINT: Run '/workflow:ui-design:list' to see available design runs"
+    exit 1
+  fi
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/active/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+  if [ -z "$relative_path" ]; then
+    echo "ERROR: No design run found in session: $SESSION_ID"
+    echo "HINT: Create a design run first or provide --design-id"
+    exit 1
+  fi
+else
+  echo "ERROR: Must provide --design-id or --session parameter"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+design_id=$(basename "$base_path")
+
+# 2. Initialize directories
+source="${source:-.}"
+intermediates_dir="${base_path}/.intermediates/import-analysis"
+mkdir -p "$intermediates_dir"
+
+echo "[Phase 0] File Discovery Started"
+echo "  Design ID: $design_id"
+echo "  Source: $source"
+echo "  Output: $base_path"
+
+# 3. Discover files using script
+discovery_file="${intermediates_dir}/discovered-files.json"
+~/.claude/scripts/discover-design-files.sh "$source" "$discovery_file"
+
+echo "  Output: $discovery_file"
+```
+
+<!-- TodoWrite: Initialize todo list -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 发现和分类代码文件", "status": "in_progress", "activeForm": "发现代码文件"},
+  {"content": "Phase 1.1: Style Agent - 提取视觉token及代码片段 (design-tokens.json + code_snippets)", "status": "pending", "activeForm": "提取视觉token"},
+  {"content": "Phase 1.2: Animation Agent - 提取动画token及代码片段 (animation-tokens.json + code_snippets)", "status": "pending", "activeForm": "提取动画token"},
+  {"content": "Phase 1.3: Layout Agent - 提取布局模式及代码片段 (layout-templates.json + code_snippets)", "status": "pending", "activeForm": "提取布局模式"}
+]
+```
+
+**File Discovery Behavior**:
+
+- **Automatic discovery**: Intelligently scans source directory for all style-related files
+- **Supported file types**: CSS, SCSS, JavaScript, TypeScript, HTML
+- **Smart filtering**: Finds theme-related JS/TS files (e.g., tailwind.config.js, theme.js, styled-components)
+- **Exclusions**: Automatically excludes `node_modules/`, `dist/`, `.git/`, and build directories
+- **Output**: Single JSON file `discovered-files.json` in `.intermediates/import-analysis/`
+  - Structure: `{ "css": [...], "js": [...], "html": [...], "counts": {...}, "discovery_time": "..." }`
+  - Generated via bash commands using `find` + JSON formatting
+
+<!-- TodoWrite: Update Phase 0 → completed, Phase 1.1-1.3 → in_progress (all 3 agents in parallel) -->
+
+---
+
+### Step 2: Parallel Agent Analysis
+
+**Purpose**: Three agents analyze all file types in parallel, each producing completeness-report.json
+
+**Operations**:
+- **Style Agent**: Extracts visual tokens (colors, typography, spacing) from ALL files (CSS/SCSS/JS/HTML)
+- **Animation Agent**: Extracts animations/transitions from ALL files
+- **Layout Agent**: Extracts layout patterns/component structures from ALL files
+
+**Validation**:
+- Each agent can reference any file type (not restricted to single type)
+- Direct output: Each agent generates completeness-report.json with findings + missing content
+- No synthesis needed: Agents produce final output directly
+
+```bash
+echo "[Phase 1] Starting parallel agent analysis (3 agents)"
+```
+
+#### Style Agent Task (design-tokens.json, style-guide.md)
+
+**Agent Task**:
+
+```javascript
+Task(subagent_type="ui-design-agent",
+     prompt="[STYLE_TOKENS_EXTRACTION]
+  Extract visual design tokens from code files using code import extraction pattern.
+
+  MODE: style-extraction | SOURCE: ${source} | BASE_PATH: ${base_path}
+
+  ## Input Files
+
+  **Discovered Files**: ${intermediates_dir}/discovered-files.json
+  $(cat \"${intermediates_dir}/discovered-files.json\" 2>/dev/null | grep -E '(count|files)' | head -30)
+
+  ## Code Import Extraction Strategy
+
+  **Step 0: Fast Conflict Detection** (Use Bash/Grep for quick global scan)
+  - Quick scan: \`rg --color=never -n "^\\s*--primary:|^\\s*--secondary:|^\\s*--accent:" --type css ${source}\` to find core color definitions with line numbers
+  - Semantic search: \`rg --color=never -B3 -A1 "^\\s*--primary:" --type css ${source}\` to capture surrounding context and comments
+  - Core token scan: Search for --primary, --secondary, --accent, --background patterns to detect all theme-critical definitions
+  - Pattern: rg → Extract values → Compare → If different → Read full context with comments → Record conflict
+  - Alternative (if many files): Execute CLI analysis for comprehensive report:
+    \`\`\`bash
+    cd ${source} && gemini -p \"
+    PURPOSE: Detect color token conflicts across all CSS/SCSS/JS files
+    TASK: • Scan all files for color definitions • Identify conflicting values • Extract semantic comments
+    MODE: analysis
+    CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
+    EXPECTED: JSON report listing conflicts with file:line, values, semantic context
+    RULES: Focus on core tokens | Report ALL variants | analysis=READ-ONLY
+    \"
+    \`\`\`
+
+  **Step 1: Load file list**
+  - Read(${intermediates_dir}/discovered-files.json)
+  - Extract: file_types.css.files, file_types.js.files, file_types.html.files
+
+  **Step 2: Cross-source token extraction**
+  - CSS/SCSS: Colors, typography, spacing, shadows, borders
+  - JavaScript/TypeScript: Theme configs (Tailwind, styled-components, CSS-in-JS)
+  - HTML: Inline styles, usage patterns
+
+  **Step 3: Validation and Conflict Detection**
+  - Report missing tokens WITHOUT inference (mark as "missing" in _metadata.completeness)
+  - Detect and report inconsistent values across files (list ALL variants with file:line sources)
+  - Report missing categories WITHOUT auto-filling (document gaps for manual review)
+  - CRITICAL: Verify core tokens (primary, secondary, accent) against semantic comments in source code
+
+  ## Output Files
+
+  **Target Directory**: ${base_path}/style-extraction/style-1/
+
+  **Files to Generate**:
+  1. **design-tokens.json**
+     - Follow [DESIGN_SYSTEM_GENERATION_TASK] standard token structure
+     - Add \"_metadata.extraction_source\": \"code_import\"
+     - Add \"_metadata.files_analyzed\": {css, js, html file lists}
+     - Add \"_metadata.completeness\": {status, missing_categories, recommendations}
+     - Add \"_metadata.conflicts\": Array of conflicting definitions (MANDATORY if conflicts exist)
+     - Add \"_metadata.code_snippets\": Map of code snippets (see below)
+     - Add \"_metadata.usage_recommendations\": Usage patterns from code (see below)
+     - Include \"source\" field for each token (e.g., \"file.css:23\")
+
+  **Code Snippet Recording**:
+  - For each extracted token, record the actual code snippet in `_metadata.code_snippets`
+  - Structure:
+    ```json
+    \"code_snippets\": {
+      \"file.css:23\": {
+        \"lines\": \"23-27\",
+        \"snippet\": \":root {\\n  --color-primary: oklch(0.5555 0.15 270);\\n  /* Primary brand color */\\n  --color-primary-hover: oklch(0.6 0.15 270);\\n}\",
+        \"context\": \"css-variable\"
+      }
+    }
+    ```
+  - Context types: \"css-variable\" | \"css-class\" | \"js-object\" | \"js-theme-config\" | \"inline-style\"
+  - Record complete code blocks with all dependencies and relevant comments
+  - Typical ranges: Simple declarations (1-5 lines), Utility classes (5-15 lines), Complete configs (15-50 lines)
+  - Preserve original formatting and indentation
+
+  **Conflict Detection and Reporting**:
+  - When the same token is defined differently across multiple files, record in `_metadata.conflicts`
+  - Follow Agent schema for conflicts array structure (see ui-design-agent.md)
+  - Each conflict MUST include: token_name, category, all definitions with context, selected_value, selection_reason
+  - Selection priority:
+    1. Definitions with semantic comments explaining intent (/* Blue theme */, /* Primary brand color */)
+    2. Definitions that align with overall color scheme described in comments
+    3. When in doubt, report ALL variants and flag for manual review in completeness.recommendations
+
+  **Usage Recommendations Generation**:
+  - Analyze code usage patterns to extract `_metadata.usage_recommendations` (see ui-design-agent.md schema)
+  - **Typography recommendations**:
+    * `common_sizes`: Identify most frequent font size usage (e.g., \"body_text\": \"base (1rem)\")
+    * `common_combinations`: Extract heading+body pairings from actual usage (e.g., h1 with p tags)
+  - **Spacing recommendations**:
+    * `size_guide`: Categorize spacing values into tight/normal/loose based on frequency
+    * `common_patterns`: Extract frequent padding/margin combinations from components
+  - Analysis method: Scan code for class/style usage frequency, extract patterns from component implementations
+  - Optional: If insufficient usage data, mark fields as empty arrays/objects with note in completeness.recommendations
+
+  ## Code Import Specific Requirements
+  - ✅ Read discovered-files.json FIRST to get file paths
+  - ✅ Track extraction source for each token (file:line)
+  - ✅ Record complete code snippets in _metadata.code_snippets (complete blocks with dependencies/comments)
+  - ✅ Include completeness assessment in _metadata
+  - ✅ Report inconsistent values with ALL source locations in _metadata.conflicts (DO NOT auto-normalize or choose)
+  - ✅ CRITICAL: Verify core theme tokens (primary, secondary, accent) match source code semantic intent
+  - ✅ When conflicts exist, prefer definitions with semantic comments explaining intent
+  - ❌ NO inference, NO smart filling, NO automatic conflict resolution
+  - ❌ NO external research or web searches (code-only extraction)
+")
+```
+
+#### Animation Agent Task (animation-tokens.json, animation-guide.md)
+
+**Agent Task**:
+
+```javascript
+Task(subagent_type="ui-design-agent",
+     prompt="[ANIMATION_TOKEN_GENERATION_TASK]
+  Extract animation tokens from code files using code import extraction pattern.
+
+  MODE: animation-extraction | SOURCE: ${source} | BASE_PATH: ${base_path}
+
+  ## Input Files
+
+  **Discovered Files**: ${intermediates_dir}/discovered-files.json
+  $(cat \"${intermediates_dir}/discovered-files.json\" 2>/dev/null | grep -E '(count|files)' | head -30)
+
+  ## Code Import Extraction Strategy
+
+  **Step 0: Fast Animation Discovery** (Use Bash/Grep for quick pattern detection)
+  - Quick scan: \`rg --color=never -n "@keyframes|animation:|transition:" --type css ${source}\` to find animation definitions with line numbers
+  - Framework detection: \`rg --color=never "framer-motion|gsap|@react-spring|react-spring" --type js --type ts ${source}\` to detect animation frameworks
+  - Pattern categorization: \`rg --color=never -B2 -A5 "@keyframes" --type css ${source}\` to extract keyframe animations with context
+  - Pattern: rg → Identify animation types → Map framework usage → Prioritize extraction targets
+  - Alternative (if complex framework mix): Execute CLI analysis for comprehensive report:
+    \`\`\`bash
+    cd ${source} && gemini -p \"
+    PURPOSE: Detect animation frameworks and patterns
+    TASK: • Identify frameworks • Map animation patterns • Categorize by complexity
+    MODE: analysis
+    CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts
+    EXPECTED: JSON report listing frameworks, animation types, file locations
+    RULES: Focus on framework consistency | Map all animations | analysis=READ-ONLY
+    \"
+    \`\`\`
+
+  **Step 1: Load file list**
+  - Read(${intermediates_dir}/discovered-files.json)
+  - Extract: file_types.css.files, file_types.js.files, file_types.html.files
+
+  **Step 2: Cross-source animation extraction**
+  - CSS/SCSS: @keyframes, transitions, animation properties
+  - JavaScript/TypeScript: Animation frameworks (Framer Motion, GSAP), CSS-in-JS
+  - HTML: Inline styles, data-animation attributes
+
+  **Step 3: Framework detection & normalization**
+  - Detect animation frameworks used (css-animations | framer-motion | gsap | none)
+  - Normalize into semantic token system
+  - Cross-reference CSS animations with JS configs
+
+  ## Output Files
+
+  **Target Directory**: ${base_path}/animation-extraction/
+
+  **Files to Generate**:
+  1. **animation-tokens.json**
+     - Follow [ANIMATION_TOKEN_GENERATION_TASK] standard structure
+     - Add \"_metadata.framework_detected\"
+     - Add \"_metadata.files_analyzed\"
+     - Add \"_metadata.completeness\"
+     - Add \"_metadata.code_snippets\": Map of code snippets (same format as Style Agent)
+     - Include \"source\" field for each token
+
+  **Code Snippet Recording**:
+  - Record actual animation/transition code in `_metadata.code_snippets`
+  - Context types: \"css-keyframes\" | \"css-transition\" | \"js-animation\" | \"framer-motion\" | \"gsap\"
+  - Record complete blocks: @keyframes animations (10-30 lines), transition configs (5-15 lines), JS animation objects (15-50 lines)
+  - Include all animation steps, timing functions, and related comments
+  - Preserve original formatting and framework-specific syntax
+
+  ## Code Import Specific Requirements
+  - ✅ Read discovered-files.json FIRST to get file paths
+  - ✅ Detect animation framework if present
+  - ✅ Track extraction source for each token (file:line)
+  - ✅ Record complete code snippets in _metadata.code_snippets (complete animation blocks with all steps/timing)
+  - ✅ Normalize framework-specific syntax into standard tokens
+  - ❌ NO external research or web searches (code-only extraction)
+")
+```
+
+#### Layout Agent Task (layout-templates.json, layout-guide.md)
+
+**Agent Task**:
+
+```javascript
+Task(subagent_type="ui-design-agent",
+     prompt="[LAYOUT_TEMPLATE_GENERATION_TASK]
+  Extract layout patterns from code files using code import extraction pattern.
+
+  MODE: layout-extraction | SOURCE: ${source} | BASE_PATH: ${base_path}
+
+  ## Input Files
+
+  **Discovered Files**: ${intermediates_dir}/discovered-files.json
+  $(cat \"${intermediates_dir}/discovered-files.json\" 2>/dev/null | grep -E '(count|files)' | head -30)
+
+  ## Code Import Extraction Strategy
+
+  **Step 0: Fast Component Discovery** (Use Bash/Grep for quick component scan)
+  - Layout pattern scan: \`rg --color=never -n "display:\\s*(grid|flex)|grid-template" --type css ${source}\` to find layout systems
+  - Component class scan: \`rg --color=never "class.*=.*\\"[^\"]*\\b(btn|button|card|input|modal|dialog|dropdown)" --type html --type js --type ts ${source}\` to identify UI components
+  - Universal component heuristic: Components appearing in 3+ files = universal, <3 files = specialized
+  - Pattern: rg → Count occurrences → Classify by frequency → Prioritize universal components
+  - Alternative (if large codebase): Execute CLI analysis for comprehensive categorization:
+    \`\`\`bash
+    cd ${source} && gemini -p \"
+    PURPOSE: Classify components as universal vs specialized
+    TASK: • Identify UI components • Classify reusability • Map layout systems
+    MODE: analysis
+    CONTEXT: @**/*.css @**/*.scss @**/*.js @**/*.ts @**/*.html
+    EXPECTED: JSON report categorizing components, layout patterns, naming conventions
+    RULES: Focus on component reusability | Identify layout systems | analysis=READ-ONLY
+    \"
+    \`\`\`
+
+  **Step 1: Load file list**
+  - Read(${intermediates_dir}/discovered-files.json)
+  - Extract: file_types.css.files, file_types.js.files, file_types.html.files
+
+  **Step 2: Cross-source layout extraction**
+  - CSS/SCSS: Grid systems, flexbox utilities, layout classes, media queries
+  - JavaScript/TypeScript: Layout components (React/Vue), grid configs
+  - HTML: Semantic structure, component hierarchies
+
+  **Component Classification** (MUST annotate in extraction):
+  - **Universal Components**: Reusable multi-component templates (buttons, inputs, cards, modals, etc.)
+  - **Specialized Components**: Module-specific components from code (feature-specific layouts, custom widgets, domain components)
+
+  **Step 3: System identification**
+  - Detect naming convention (BEM | SMACSS | utility-first | css-modules)
+  - Identify layout system (12-column | flexbox | css-grid | custom)
+  - Extract responsive strategy and breakpoints
+
+  ## Output Files
+
+  **Target Directory**: ${base_path}/layout-extraction/
+
+  **Files to Generate**:
+
+  1. **layout-templates.json**
+     - Follow [LAYOUT_TEMPLATE_GENERATION_TASK] standard structure
+     - Add \"extraction_metadata\" section:
+       * extraction_source: \"code_import\"
+       * naming_convention: detected convention
+       * layout_system: {type, confidence, source_files}
+       * responsive: {breakpoints, mobile_first, source}
+       * completeness: {status, missing_items, recommendations}
+       * code_snippets: Map of code snippets (same format as Style Agent)
+     - For each component in \"layout_templates\":
+       * Include \"source\" field (file:line)
+       * **Include \"component_type\" field: \"universal\" | \"specialized\"**
+       * dom_structure with semantic HTML5
+       * css_layout_rules using var() placeholders
+       * Add \"description\" field explaining component purpose and classification rationale
+       * **Add \"usage_guide\" field for universal components** (see ui-design-agent.md schema):
+         - common_sizes: Extract size variants (small/medium/large) from code
+         - variant_recommendations: Document when to use each variant (primary/secondary/etc)
+         - usage_context: List typical usage scenarios from actual implementation
+         - accessibility_tips: Extract ARIA patterns and a11y notes from code
+
+  **Code Snippet Recording**:
+  - Record actual layout/component code in `extraction_metadata.code_snippets`
+  - Context types: \"css-grid\" | \"css-flexbox\" | \"css-utility\" | \"html-structure\" | \"react-component\"
+  - Record complete blocks: Utility classes (5-15 lines), HTML structures (10-30 lines), React components (20-100 lines)
+  - For components: include HTML structure + associated CSS rules + component logic
+  - Preserve original formatting and framework-specific syntax
+
+  ## Code Import Specific Requirements
+  - ✅ Read discovered-files.json FIRST to get file paths
+  - ✅ Detect and document naming conventions
+  - ✅ Identify layout system with confidence level
+  - ✅ Extract component variants and states from usage patterns
+  - ✅ **Classify each component as \"universal\" or \"specialized\"** based on:
+    * Universal: Reusable across multiple features (buttons, inputs, cards, modals)
+    * Specialized: Feature-specific or domain-specific (checkout form, dashboard widget)
+  - ✅ Record complete code snippets in extraction_metadata.code_snippets (complete components/structures)
+  - ✅ **Document classification rationale** in component description
+  - ✅ **Generate usage_guide for universal components** (REQUIRED):
+    * Analyze code to extract size variants (scan for size-related classes/props)
+    * Document variant usage from code comments and implementation patterns
+    * List usage contexts from component instances in codebase
+    * Extract accessibility patterns from ARIA attributes and a11y comments
+    * If insufficient data, populate with minimal valid structure and note in completeness
+  - ❌ NO external research or web searches (code-only extraction)
+")
+```
+
+**Wait for All Agents**:
+
+```bash
+# Note: Agents run in parallel and write separate completeness reports
+# Each agent generates its own completeness-report.json directly
+# No synthesis phase needed
+echo "[Phase 1] Parallel agent analysis complete"
+```
+
+<!-- TodoWrite: Update Phase 1.1-1.3 → completed (all 3 agents complete together) -->
+
+---
+
+## Output Files
+
+### Generated Files
+
+**Location**: `${base_path}/`
+
+**Directory Structure**:
+```
+${base_path}/
+├── style-extraction/
+│   └── style-1/
+│       └── design-tokens.json       # Production-ready design tokens with code snippets
+├── animation-extraction/
+│   └── animation-tokens.json        # Animation/transition tokens with code snippets
+├── layout-extraction/
+│   └── layout-templates.json        # Layout patterns with code snippets
+└── .intermediates/
+    └── import-analysis/
+        └── discovered-files.json    # All discovered files (JSON format)
+```
+
+**Files**:
+1. **style-extraction/style-1/design-tokens.json**
+   - Production-ready design tokens
+   - Categories: colors, typography, spacing, opacity, border_radius, shadows, breakpoints
+   - Metadata: extraction_source, files_analyzed, completeness assessment, **code_snippets**
+   - **Code snippets**: Complete code blocks from source files (CSS variables, theme configs, inline styles)
+
+2. **animation-extraction/animation-tokens.json**
+   - Animation tokens: duration, easing, transitions, keyframes, interactions
+   - Framework detection: css-animations, framer-motion, gsap, etc.
+   - Metadata: extraction_source, completeness assessment, **code_snippets**
+   - **Code snippets**: Complete animation blocks (@keyframes, transition configs, JS animations)
+
+3. **layout-extraction/layout-templates.json**
+   - Layout templates for each discovered component
+   - Extraction metadata: naming_convention, layout_system, responsive strategy, **code_snippets**
+   - Component patterns with DOM structure and CSS rules
+   - **Code snippets**: Complete component/structure code (HTML, CSS utilities, React components)
+
+**Intermediate Files**: `.intermediates/import-analysis/`
+- `discovered-files.json` - All discovered files in JSON format with counts and metadata
+
+---
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| No files discovered | Wrong --source path or no style files in directory | Verify --source parameter points to correct directory with style files |
+| Agent reports "failed" status | No tokens found in any file | Review file content, check if files contain design tokens |
+| Empty completeness reports | Files exist but contain no extractable tokens | Manually verify token definitions in source files |
+| Missing file type | File extensions not recognized | Check that files use standard extensions (.css, .scss, .js, .ts, .html) |
+
+---
+
+## Best Practices
+
+1. **Point to the right directory**: Use `--source` to specify the directory containing your style files (e.g., `./src`, `./app`, `./styles`)
+2. **Let automatic discovery work**: The command will find all relevant files - no need to specify patterns
+3. **Specify target design run**: Use `--design-id` for existing design run or `--session` to use session's latest design run (one of these is required)
+4. **Cross-reference agent reports**: Compare all three completeness reports (style, animation, layout) to identify gaps
+5. **Review missing content**: Check `_metadata.completeness` field in reports for actionable improvements
+6. **Verify file discovery**: Check `${base_path}/.intermediates/import-analysis/discovered-files.json` if agents report no data

.claude/commands/workflow/ui-design/reference-page-generator.md

@@ -0,0 +1,333 @@
+---
+name: workflow:ui-design:reference-page-generator
+description: Generate multi-component reference pages and documentation from design run extraction
+argument-hint: "[--design-run <path>] [--package-name <name>] [--output-dir <path>]"
+allowed-tools: Read,Write,Bash,Task,TodoWrite
+auto-continue: true
+---
+
+# UI Design: Reference Page Generator
+
+## Overview
+
+Converts design run extraction results into shareable reference package with:
+- Interactive multi-component preview (preview.html + preview.css)
+- Component layout templates (layout-templates.json)
+
+**Role**: Takes existing design run (from `import-from-code` or other extraction commands) and generates preview pages for easy reference.
+
+## Usage
+
+### Command Syntax
+
+```bash
+/workflow:ui-design:reference-page-generator [FLAGS]
+
+# Flags
+--design-run <path>      Design run directory path (required)
+--package-name <name>    Package name for reference (required)
+--output-dir <path>      Output directory (default: .workflow/reference_style)
+```
+
+---
+
+## Execution Process
+
+### Phase 0: Setup & Validation
+
+**Purpose**: Validate inputs, prepare output directory
+
+**Operations**:
+
+```bash
+# 1. Validate required parameters
+if [ -z "$design_run" ] || [ -z "$package_name" ]; then
+  echo "ERROR: --design-run and --package-name are required"
+  echo "USAGE: /workflow:ui-design:reference-page-generator --design-run <path> --package-name <name>"
+  exit 1
+fi
+
+# 2. Validate package name format (lowercase, alphanumeric, hyphens only)
+if ! [[ "$package_name" =~ ^[a-z0-9][a-z0-9-]*$ ]]; then
+  echo "ERROR: Invalid package name. Use lowercase, alphanumeric, and hyphens only."
+  echo "EXAMPLE: main-app-style-v1"
+  exit 1
+fi
+
+# 3. Validate design run exists
+if [ ! -d "$design_run" ]; then
+  echo "ERROR: Design run not found: $design_run"
+  echo "HINT: Run '/workflow:ui-design:import-from-code' first to create design run"
+  exit 1
+fi
+
+# 4. Check required extraction files exist
+required_files=(
+  "$design_run/style-extraction/style-1/design-tokens.json"
+  "$design_run/layout-extraction/layout-templates.json"
+)
+
+for file in "${required_files[@]}"; do
+  if [ ! -f "$file" ]; then
+    echo "ERROR: Required file not found: $file"
+    echo "HINT: Ensure design run has style and layout extraction results"
+    exit 1
+  fi
+done
+
+# 5. Setup output directory and validate
+output_dir="${output_dir:-.workflow/reference_style}"
+package_dir="${output_dir}/${package_name}"
+
+# Check if package directory exists and is not empty
+if [ -d "$package_dir" ] && [ "$(ls -A $package_dir 2>/dev/null)" ]; then
+  # Directory exists - check if it's a valid package or just a directory
+  if [ -f "$package_dir/metadata.json" ]; then
+    # Valid package - safe to overwrite
+    existing_version=$(jq -r '.version // "unknown"' "$package_dir/metadata.json" 2>/dev/null || echo "unknown")
+    echo "INFO: Overwriting existing package '$package_name' (version: $existing_version)"
+  else
+    # Directory exists but not a valid package
+    echo "ERROR: Directory '$package_dir' exists but is not a valid package"
+    echo "Use a different package name or remove the directory manually"
+    exit 1
+  fi
+fi
+
+mkdir -p "$package_dir"
+
+echo "[Phase 0] Setup Complete"
+echo "  Design Run: $design_run"
+echo "  Package: $package_name"
+echo "  Output: $package_dir"
+```
+
+<!-- TodoWrite: Initialize todo list -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
+  {"content": "Phase 1: 准备组件数据", "status": "in_progress", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "pending", "activeForm": "生成预览"}
+]
+```
+
+---
+
+### Phase 1: Prepare Component Data
+
+**Purpose**: Copy required files from design run to package directory
+
+**Operations**:
+
+```bash
+echo "[Phase 1] Preparing component data from design run"
+
+# 1. Copy layout templates as component patterns
+cp "${design_run}/layout-extraction/layout-templates.json" "${package_dir}/layout-templates.json"
+
+if [ ! -f "${package_dir}/layout-templates.json" ]; then
+  echo "ERROR: Failed to copy layout templates"
+  exit 1
+fi
+
+# Count components from layout templates
+component_count=$(jq -r '.layout_templates | length // 0' "${package_dir}/layout-templates.json" 2>/dev/null || echo 0)
+echo "  ✓ Layout templates copied (${component_count} components)"
+
+# 2. Copy design tokens (required for preview generation)
+cp "${design_run}/style-extraction/style-1/design-tokens.json" "${package_dir}/design-tokens.json"
+
+if [ ! -f "${package_dir}/design-tokens.json" ]; then
+  echo "ERROR: Failed to copy design tokens"
+  exit 1
+fi
+echo "  ✓ Design tokens copied"
+
+# 3. Copy animation tokens if exists (optional)
+if [ -f "${design_run}/animation-extraction/animation-tokens.json" ]; then
+  cp "${design_run}/animation-extraction/animation-tokens.json" "${package_dir}/animation-tokens.json"
+  echo "  ✓ Animation tokens copied"
+else
+  echo "  ○ Animation tokens not found (optional)"
+fi
+
+echo "[Phase 1] Component data preparation complete"
+```
+
+<!-- TodoWrite: Mark Phase 1 complete, start Phase 2 -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "in_progress", "activeForm": "生成预览"}
+]
+```
+
+---
+
+### Phase 2: Preview Generation (Final Phase)
+
+**Purpose**: Generate interactive multi-component preview (preview.html + preview.css)
+
+**Agent Task**:
+
+```javascript
+Task(ui-design-agent): `
+  [PREVIEW_SHOWCASE_GENERATION]
+  Generate interactive multi-component showcase panel for reference package
+
+  PACKAGE_DIR: ${package_dir} | PACKAGE_NAME: ${package_name}
+
+  ## Input Files (MUST READ ALL)
+
+  1. ${package_dir}/layout-templates.json (component layout patterns - REQUIRED)
+  2. ${package_dir}/design-tokens.json (design tokens - REQUIRED)
+  3. ${package_dir}/animation-tokens.json (optional, if exists)
+
+  ## Generation Task
+
+  Create interactive showcase with these sections:
+
+  ### Section 1: Colors
+  - Display all color categories as color swatches
+  - Show hex/rgb values
+  - Group by: brand, semantic, surface, text, border
+
+  ### Section 2: Typography
+  - Display typography scale (font sizes, weights)
+  - Show typography combinations if available
+  - Include font family examples
+  - **Display usage recommendations** (from design-tokens.json _metadata.usage_recommendations.typography):
+    * Common sizes table (small_text, body_text, heading)
+    * Common combinations with use cases
+
+  ### Section 3: Components
+  - Render all components from layout-templates.json (use layout_templates field)
+  - **Universal Components**: Display reusable multi-component showcases (buttons, inputs, cards, etc.)
+    * **Display usage_guide** (from layout-templates.json):
+      - Common sizes table with dimensions and use cases
+      - Variant recommendations (when to use primary/secondary/etc)
+      - Usage context list (typical scenarios)
+      - Accessibility tips checklist
+  - **Specialized Components**: Display module-specific components from code (feature-specific layouts, custom widgets)
+  - Display all variants side-by-side
+  - Show DOM structure with proper styling
+  - Include usage code snippets in <details> tags
+  - Clearly label component types (universal vs specialized)
+
+  ### Section 4: Spacing & Layout
+  - Visual spacing scale
+  - Border radius examples
+  - Shadow depth examples
+  - **Display spacing recommendations** (from design-tokens.json _metadata.usage_recommendations.spacing):
+    * Size guide table (tight/normal/loose categories)
+    * Common patterns with use cases and pixel values
+
+  ### Section 5: Animations (if available)
+  - Animation duration examples
+  - Easing function demonstrations
+
+  ## Output Requirements
+
+  Generate 2 files:
+  1. ${package_dir}/preview.html
+  2. ${package_dir}/preview.css
+
+  ### preview.html Structure:
+  - Complete standalone HTML file
+  - Responsive design with mobile-first approach
+  - Sticky navigation for sections
+  - Interactive component demonstrations
+  - Code snippets in collapsible <details> elements
+  - Footer with package metadata
+
+  ### preview.css Structure:
+  - CSS Custom Properties from design-tokens.json
+  - Typography combination classes
+  - Component classes from layout-templates.json
+  - Preview page layout styles
+  - Interactive demo styles
+
+  ## Critical Requirements
+  - ✅ Read ALL input files (layout-templates.json, design-tokens.json, animation-tokens.json if exists)
+  - ✅ Generate complete, interactive showcase HTML
+  - ✅ All CSS uses var() references to design tokens
+  - ✅ Display ALL components from layout-templates.json
+  - ✅ **Separate universal components from specialized components** in the showcase
+  - ✅ Display component DOM structures with proper styling
+  - ✅ Include usage code snippets
+  - ✅ Label each component type clearly (Universal / Specialized)
+  - ✅ **Display usage recommendations** when available:
+    - Typography: common_sizes, common_combinations (from _metadata.usage_recommendations)
+    - Components: usage_guide for universal components (from layout-templates)
+    - Spacing: size_guide, common_patterns (from _metadata.usage_recommendations)
+  - ✅ Gracefully handle missing usage data (display sections only if data exists)
+  - ✅ Use Write() to save both files:
+    - ${package_dir}/preview.html
+    - ${package_dir}/preview.css
+  - ❌ NO external research or MCP calls
+`
+```
+
+<!-- TodoWrite: Mark all complete -->
+
+**TodoWrite**:
+```json
+[
+  {"content": "Phase 0: 验证和准备", "status": "completed", "activeForm": "验证参数"},
+  {"content": "Phase 1: 准备组件数据", "status": "completed", "activeForm": "复制布局模板"},
+  {"content": "Phase 2: 生成预览页面", "status": "completed", "activeForm": "生成预览"}
+]
+```
+
+---
+
+## Output Structure
+
+```
+${output_dir}/
+└── ${package_name}/
+    ├── layout-templates.json    # Layout templates (copied from design run)
+    ├── design-tokens.json       # Design tokens (copied from design run)
+    ├── animation-tokens.json    # Animation tokens (copied from design run, optional)
+    ├── preview.html             # Interactive showcase (NEW)
+    └── preview.css              # Showcase styling (NEW)
+```
+
+## Completion Message
+
+```
+✅ Preview package generated!
+
+Package: {package_name}
+Location: {package_dir}
+
+Files:
+✓ layout-templates.json    {component_count} components
+✓ design-tokens.json       Design tokens
+✓ animation-tokens.json    Animation tokens {if exists: "✓" else: "○ (not found)"}
+✓ preview.html             Interactive showcase
+✓ preview.css              Showcase styling
+
+Open preview:
+  file://{absolute_path_to_package_dir}/preview.html
+```
+
+## Error Handling
+
+### Common Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| Missing --design-run or --package-name | Required parameters not provided | Provide both flags |
+| Invalid package name | Contains uppercase, special chars | Use lowercase, alphanumeric, hyphens only |
+| Design run not found | Incorrect path or design run doesn't exist | Verify design run path, run import-from-code first |
+| Missing extraction files | Design run incomplete | Ensure design run has style-extraction and layout-extraction results |
+| Layout templates copy failed | layout-templates.json not found | Run import-from-code with Layout Agent first |
+| Preview generation failed | Invalid design tokens | Check design-tokens.json format |
+
+---
+

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

@@ -1,20 +1,22 @@
 ---
 name: style-extract
-description: Extract design style from reference images or text prompts using Claude's analysis
-argument-hint: "[--base-path <path>] [--session <id>] [--images "<glob>"] [--urls "<list>"] [--prompt "<desc>"] [--mode <imitate|explore>] [--variants <count>]"
-allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), mcp__chrome-devtools__navigate_page(*), mcp__chrome-devtools__evaluate_script(*)
+description: Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode
+argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
+allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*)
 ---
 
 # Style Extraction Command
 
 ## Overview
-Extract design style from reference images or text prompts using Claude's built-in analysis. Directly generates production-ready design systems with complete `design-tokens.json` and `style-guide.md` for each variant.
+Extract design style from reference images or text prompts using Claude's built-in analysis. Supports two modes:
+1. **Exploration Mode** (default): Generate multiple contrasting design variants
+2. **Refinement Mode** (`--refine`): Refine a single existing design through detailed adjustments
 
 **Strategy**: AI-Driven Design Space Exploration
 - **Claude-Native**: 100% Claude analysis, no external tools
-- **Direct Output**: Complete design systems (design-tokens.json + style-guide.md)
+- **Direct Output**: Complete design systems (design-tokens.json)
 - **Flexible Input**: Images, text prompts, or both (hybrid mode)
-- **Maximum Contrast**: AI generates maximally divergent design directions
+- **Dual Mode**: Exploration (multiple contrasting variants) or Refinement (single design fine-tuning)
 - **Production-Ready**: WCAG AA compliant, OKLCH colors, semantic naming
 
 ## Phase 0: Setup & Input Validation
@@ -22,98 +24,46 @@ Extract design style from reference images or text prompts using Claude's built-
 ### Step 1: Detect Input Mode, Extraction Mode & Base Path
 ```bash
 # Detect input source
-# Priority: --urls + --images + --prompt → hybrid-url | --urls + --images → url-image | --urls → url | --images + --prompt → hybrid | --images → image | --prompt → text
+# Priority: --images + --prompt → hybrid | --images → image | --prompt → text
 
-# Parse URLs if provided (format: "target:url,target:url,...")
-IF --urls:
-    url_list = []
-    FOR pair IN split(--urls, ","):
-        IF ":" IN pair:
-            target, url = pair.split(":", 1)
-            url_list.append({target: target.strip(), url: url.strip()})
-        ELSE:
-            # Single URL without target
-            url_list.append({target: "page", url: pair.strip()})
+# Detect refinement mode
+refine_mode = --refine OR false
 
-    has_urls = true
-    primary_url = url_list[0].url  # First URL as primary source
+# Set variants count
+# Refinement mode: Force variants_count = 1 (ignore user-provided --variants)
+# Exploration mode: Use --variants or default to 3 (range: 1-5)
+IF refine_mode:
+    variants_count = 1
+    REPORT: "🔧 Refinement mode enabled: Will generate 1 refined design system"
 ELSE:
-    has_urls = false
-
-# Determine extraction mode
-# Priority: --mode parameter → default "imitate"
-extraction_mode = --mode OR "imitate"  # "imitate" or "explore"
-
-# Set variants count based on mode
-IF extraction_mode == "imitate":
-    variants_count = 1  # Force single variant for imitate mode (ignore --variants)
-ELSE IF extraction_mode == "explore":
-    variants_count = --variants OR 3  # Default to 3 for explore mode
+    variants_count = --variants OR 3
     VALIDATE: 1 <= variants_count <= 5
+    REPORT: "🔍 Exploration mode: Will generate {variants_count} contrasting design directions"
 
-# Determine base path
-bash(find .workflow -type d -name "design-*" | head -1)  # Auto-detect
-# OR use --base-path / --session parameters
+# Determine base path with priority: --design-id > --session > auto-detect
+if [ -n "$DESIGN_ID" ]; then
+  # Exact match by design ID
+  relative_path=$(find .workflow -name "${DESIGN_ID}" -type d -print -quit)
+elif [ -n "$SESSION_ID" ]; then
+  # Latest in session
+  relative_path=$(find .workflow/active/WFS-$SESSION_ID -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+else
+  # Latest globally
+  relative_path=$(find .workflow -name "design-run-*" -type d -printf "%T@ %p\n" 2>/dev/null | sort -nr | head -1 | cut -d' ' -f2)
+fi
+
+# Validate and convert to absolute path
+if [ -z "$relative_path" ] || [ ! -d "$relative_path" ]; then
+  echo "❌ ERROR: Design run not found"
+  echo "💡 HINT: Run '/workflow:ui-design:list' to see available design runs"
+  exit 1
+fi
+
+base_path=$(cd "$relative_path" && pwd)
+bash(echo "✓ Base path: $base_path")
 ```
 
-### Step 2: Extract Computed Styles (URL Mode - Auto-Trigger)
-```bash
-# AUTO-TRIGGER: If URLs are available (from --urls parameter or capture metadata), automatically extract real CSS values
-# This provides accurate design tokens to supplement visual analysis
-
-# Priority 1: Check for --urls parameter
-IF has_urls:
-    url_to_extract = primary_url
-    url_source = "--urls parameter"
-
-# Priority 2: Check for URL metadata from capture phase
-ELSE IF exists({base_path}/.metadata/capture-urls.json):
-    capture_urls = Read({base_path}/.metadata/capture-urls.json)
-    url_to_extract = capture_urls[0]  # Use first URL
-    url_source = "capture metadata"
-ELSE:
-    url_to_extract = null
-
-# Execute extraction if URL available
-IF url_to_extract AND mcp_chrome_devtools_available:
-    REPORT: "🔍 Auto-triggering URL mode: Extracting computed styles from {url_source}"
-    REPORT: "   URL: {url_to_extract}"
-
-    # Read extraction script
-    script_content = Read(~/.claude/scripts/extract-computed-styles.js)
-
-    # Open page in Chrome DevTools
-    mcp__chrome-devtools__navigate_page(url=url_to_extract)
-
-    # Execute extraction script directly
-    result = mcp__chrome-devtools__evaluate_script(function=script_content)
-
-    # Save computed styles to intermediates directory
-    bash(mkdir -p {base_path}/.intermediates/style-analysis)
-    Write({base_path}/.intermediates/style-analysis/computed-styles.json, result)
-
-    computed_styles_available = true
-    REPORT: "   ✅ Computed styles extracted and saved"
-ELSE:
-    computed_styles_available = false
-    IF url_to_extract:
-        REPORT: "⚠️ Chrome DevTools MCP not available, falling back to visual analysis"
-```
-
-**Extraction Script Reference**: `~/.claude/scripts/extract-computed-styles.js`
-
-**Usage**: Read the script file and use content directly in `mcp__chrome-devtools__evaluate_script()`
-
-**Script returns**:
-- `metadata`: Extraction timestamp, URL, method
-- `tokens`: Organized design tokens (colors, borderRadii, shadows, fontSizes, fontWeights, spacing)
-
-**Benefits**:
-- ✅ Pixel-perfect accuracy for border-radius, box-shadow, padding, etc.
-- ✅ Eliminates guessing from visual analysis
-- ✅ Provides ground truth for design tokens
-
-### Step 3: Load Inputs
+### Step 2: Load Inputs
 ```bash
 # For image mode
 bash(ls {images_pattern})  # Expand glob pattern
@@ -138,74 +88,133 @@ IF exists: SKIP to completion
 
 ---
 
-**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`, `has_urls`, `url_list[]`, `computed_styles_available`
+**Phase 0 Output**: `input_mode`, `base_path`, `extraction_mode`, `variants_count`, `loaded_images[]` or `prompt_guidance`
 
-## Phase 1: Design Direction Generation (Explore Mode Only)
+## Phase 1: Design Direction or Refinement Options Generation
 
-### Step 1: Check Extraction Mode
-```bash
-# Check extraction mode
-# extraction_mode == "imitate" → skip this phase
-# extraction_mode == "explore" → execute this phase
-```
-
-**If imitate mode**: Skip to Phase 2
-
-### Step 2: Load Project Context (Explore Mode)
+### Step 1: Load Project Context
 ```bash
 # Load brainstorming context if available
 bash(test -f {base_path}/.brainstorming/role analysis documents && cat it)
+
+# Load existing design system if refinement mode
+IF refine_mode:
+    existing_tokens = Read({base_path}/style-extraction/style-1/design-tokens.json)
 ```
 
-### Step 3: Generate Design Direction Options (Agent Task 1)
+### Step 2: Generate Options (Agent Task 1 - Mode-Specific)
 **Executor**: `Task(ui-design-agent)`
 
-Launch agent to generate `variants_count` design direction options with previews:
+**Exploration Mode** (default): Generate contrasting design directions
+**Refinement Mode** (`--refine`): Generate refinement options for existing design
 
 ```javascript
-Task(ui-design-agent): `
-  [DESIGN_DIRECTION_GENERATION_TASK]
-  Generate {variants_count} maximally contrasting design directions with visual previews
+// Conditional agent task based on refine_mode
+IF NOT refine_mode:
+    // EXPLORATION MODE
+    Task(ui-design-agent): `
+      [DESIGN_DIRECTION_GENERATION_TASK]
+      Generate {variants_count} maximally contrasting design directions with visual previews
 
-  SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
+      SESSION: {session_id} | MODE: explore | BASE_PATH: {base_path}
 
-  ## Input Analysis
-  - User prompt: {prompt_guidance}
-  - Visual references: {loaded_images if available}
-  - Project context: {brainstorming_context if available}
+      ## Input Analysis
+      - User prompt: {prompt_guidance}
+      - Visual references: {loaded_images if available}
+      - Project context: {brainstorming_context if available}
 
-  ## Analysis Rules
-  - Analyze 6D attribute space: color saturation, visual weight, formality, organic/geometric, innovation, density
-  - Generate {variants_count} directions with MAXIMUM contrast
-  - Each direction must be distinctly different (min distance score: 0.7)
+      ## Analysis Rules
+      - Analyze 6D attribute space: color saturation, visual weight, formality, organic/geometric, innovation, density
+      - Generate {variants_count} directions with MAXIMUM contrast
+      - Each direction must be distinctly different (min distance score: 0.7)
 
-  ## Generate for EACH Direction
-  1. **Core Philosophy**:
-     - philosophy_name (2-3 words, e.g., "Minimalist & Airy")
-     - design_attributes (6D scores 0-1)
-     - search_keywords (3-5 keywords)
-     - anti_keywords (2-3 keywords to avoid)
-     - rationale (why this is distinct from others)
+      ## Generate for EACH Direction
+      1. **Core Philosophy**:
+         - philosophy_name (2-3 words, e.g., "Minimalist & Airy")
+         - design_attributes (6D scores 0-1)
+         - search_keywords (3-5 keywords)
+         - anti_keywords (2-3 keywords to avoid)
+         - rationale (why this is distinct from others)
 
-  2. **Visual Preview Elements**:
-     - primary_color (OKLCH format)
-     - secondary_color (OKLCH format)
-     - accent_color (OKLCH format)
-     - font_family_heading (specific font name)
-     - font_family_body (specific font name)
-     - border_radius_base (e.g., "0.5rem")
-     - mood_description (1-2 sentences describing the feel)
+      2. **Visual Preview Elements**:
+         - primary_color (OKLCH format)
+         - secondary_color (OKLCH format)
+         - accent_color (OKLCH format)
+         - font_family_heading (specific font name)
+         - font_family_body (specific font name)
+         - border_radius_base (e.g., "0.5rem")
+         - mood_description (1-2 sentences describing the feel)
 
-  ## Output
-  Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+      ## Output
+      Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
 
-  Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
+      Use schema from INTERACTIVE-DATA-SPEC.md (Style Extract: analysis-options.json)
 
-  CRITICAL: Use Write() tool immediately after generating complete JSON
-`
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
+ELSE:
+    // REFINEMENT MODE
+    Task(ui-design-agent): `
+      [DESIGN_REFINEMENT_OPTIONS_TASK]
+      Generate refinement options for existing design system
+
+      SESSION: {session_id} | MODE: refine | BASE_PATH: {base_path}
+
+      ## Existing Design System
+      - design-tokens.json: {existing_tokens}
+
+      ## Input Guidance
+      - User prompt: {prompt_guidance}
+      - Visual references: {loaded_images if available}
+
+      ## Refinement Categories
+      Generate 8-12 refinement options across these categories:
+
+      1. **Intensity/Degree Adjustments** (2-3 options):
+         - Color intensity: more vibrant ↔ more muted
+         - Visual weight: bolder ↔ lighter
+         - Density: more compact ↔ more spacious
+
+      2. **Specific Attribute Tuning** (3-4 options):
+         - Border radius: sharper corners ↔ rounder edges
+         - Shadow depth: subtler shadows ↔ deeper elevation
+         - Typography scale: tighter scale ↔ more contrast
+         - Spacing scale: tighter rhythm ↔ more breathing room
+
+      3. **Context-Specific Variations** (2-3 options):
+         - Dark mode optimization
+         - Mobile-specific adjustments
+         - High-contrast accessibility mode
+
+      4. **Component-Level Customization** (1-2 options):
+         - Button styling emphasis
+         - Card/container treatment
+         - Form input refinements
+
+      ## Output Format
+      Each option:
+      - category: "intensity|attribute|context|component"
+      - option_id: unique identifier
+      - label: Short descriptive name (e.g., "More Vibrant Colors")
+      - description: What changes (2-3 sentences)
+      - preview_changes: Key token adjustments preview
+      - impact_scope: Which tokens affected
+
+      ## Output
+      Write single JSON file: {base_path}/.intermediates/style-analysis/analysis-options.json
+
+      Use refinement schema:
+      {
+        "mode": "refinement",
+        "base_design": "style-1",
+        "refinement_options": [array of refinement options]
+      }
+
+      CRITICAL: Use Write() tool immediately after generating complete JSON
+    `
 ```
 
-### Step 4: Verify Options File Created
+### Step 3: Verify Options File Created
 ```bash
 bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json && echo "created")
 
@@ -217,20 +226,44 @@ bash(cat {base_path}/.intermediates/style-analysis/analysis-options.json | grep
 
 ---
 
-## Phase 1.5: User Confirmation (Explore Mode Only - INTERACTIVE)
+## Phase 1.5: User Confirmation (Optional - Triggered by --interactive)
 
-**Purpose**: Allow user to select preferred design direction(s) before generating full design systems
+**Purpose**:
+- **Exploration Mode**: Allow user to select preferred design direction(s)
+- **Refinement Mode**: Allow user to select refinement options to apply
 
-### Step 1: Load and Present Options
+**Trigger Condition**: Execute this phase ONLY if `--interactive` flag is present
+
+### Step 1: Check Interactive Flag
+```bash
+# Skip this entire phase if --interactive flag is not present
+IF NOT --interactive:
+    SKIP to Phase 2
+    IF refine_mode:
+        REPORT: "ℹ️ Non-interactive refinement mode: Will apply all suggested refinements"
+    ELSE:
+        REPORT: "ℹ️ Non-interactive mode: Will generate all {variants_count} variants"
+
+REPORT: "🎯 Interactive mode enabled: User selection required"
+```
+
+### Step 2: Load and Present Options (Mode-Specific)
 ```bash
 # Read options file
 options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
 
-# Parse design directions
-design_directions = options.design_directions
+# Branch based on mode
+IF NOT refine_mode:
+    # EXPLORATION MODE
+    design_directions = options.design_directions
+ELSE:
+    # REFINEMENT MODE
+    refinement_options = options.refinement_options
 ```
 
-### Step 2: Present Options to User
+### Step 3: Present Options to User (Mode-Specific)
+
+**Exploration Mode**:
 ```
 📋 Design Direction Options
 
@@ -263,14 +296,39 @@ Please select the direction(s) you'd like to develop into complete design system
 ═══════════════════════════════════════════════════
 ```
 
-### Step 3: Capture User Selection
+**Refinement Mode**:
+```
+📋 Design Refinement Options
+
+We've analyzed your existing design system and generated refinement options.
+Please select the refinement(s) you'd like to apply.
+
+Base Design: style-1
+
+{FOR each option in refinement_options grouped by category:
+  ━━━ {category_name} ━━━
+
+  {FOR each refinement in category_options:
+    [{refinement.option_id}] {refinement.label}
+    {refinement.description}
+    Preview: {refinement.preview_changes}
+    Affects: {refinement.impact_scope}
+  }
+}
+
+═══════════════════════════════════════════════════
+```
+
+### Step 4: Capture User Selection and Update Analysis JSON
+
+**Exploration Mode Interaction**:
 ```javascript
-// Use AskUserQuestion tool for selection
+// Use AskUserQuestion tool for multi-selection
 AskUserQuestion({
   questions: [{
-    question: "Which design direction would you like to develop into a complete design system?",
+    question: "Which design direction(s) would you like to develop into complete design systems?",
     header: "Style Choice",
-    multiSelect: false,  // Single selection for Phase 1
+    multiSelect: true,  // Multi-selection enabled
     options: [
       {FOR each direction:
         label: "Option {direction.index}: {direction.philosophy_name}",
@@ -280,166 +338,212 @@ AskUserQuestion({
   }]
 })
 
-// Parse user response (e.g., "Option 1: Minimalist & Airy")
-selected_option_text = user_answer
+// Parse user response (array of selections)
+selected_options = user_answer
 
 // Check for user cancellation
-IF selected_option_text == null OR selected_option_text == "":
+IF selected_options == null OR selected_options.length == 0:
     REPORT: "⚠️ User canceled selection. Workflow terminated."
     EXIT workflow
 
-// Extract option index from response format "Option N: Name"
-match = selected_option_text.match(/Option (\d+):/)
-IF match:
-    selected_index = parseInt(match[1])
-ELSE:
-    ERROR: "Invalid selection format. Expected 'Option N: ...' format"
-    EXIT workflow
-```
+// Extract option indices
+selected_indices = []
+FOR each selected_option_text IN selected_options:
+    match = selected_option_text.match(/Option (\d+):/)
+    IF match:
+        selected_indices.push(parseInt(match[1]))
 
-### Step 4: Write User Selection File
-```bash
-# Create user selection JSON
-selection_data = {
-  "metadata": {
-    "selected_at": "{current_timestamp}",
-    "selection_type": "single",
-    "session_id": "{session_id}"
-  },
-  "selected_indices": [selected_index],
-  "refinements": {
-    "enabled": false
-  }
+REPORT: "✅ Selected {selected_indices.length} design direction(s)"
+
+// Update analysis-options.json
+options_file = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": NOW(),
+  "selected_indices": selected_indices,
+  "selection_count": selected_indices.length
 }
-
-# Write to file
-bash(echo '{selection_data}' > {base_path}/.intermediates/style-analysis/user-selection.json)
-
-# Verify
-bash(test -f {base_path}/.intermediates/style-analysis/user-selection.json && echo "saved")
+Write({base_path}/.intermediates/style-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
 ```
 
-### Step 5: Confirmation Message
+**Refinement Mode Interaction**:
+```javascript
+// Use AskUserQuestion tool for multi-selection of refinements
+AskUserQuestion({
+  questions: [{
+    question: "Which refinement(s) would you like to apply to your design system?",
+    header: "Refinements",
+    multiSelect: true,  // Multi-selection enabled
+    options: [
+      {FOR each refinement:
+        label: "{refinement.label}",
+        description: "{refinement.description} (Affects: {refinement.impact_scope})"
+      }
+    ]
+  }]
+})
+
+// Parse user response
+selected_refinements = user_answer
+
+// Check for user cancellation
+IF selected_refinements == null OR selected_refinements.length == 0:
+    REPORT: "⚠️ User canceled selection. Workflow terminated."
+    EXIT workflow
+
+// Extract refinement option_ids
+selected_option_ids = []
+FOR each selected_text IN selected_refinements:
+    # Match against refinement labels to find option_ids
+    FOR each refinement IN refinement_options:
+        IF refinement.label IN selected_text:
+            selected_option_ids.push(refinement.option_id)
+
+REPORT: "✅ Selected {selected_option_ids.length} refinement(s)"
+
+// Update analysis-options.json
+options_file = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
+options_file.user_selection = {
+  "selected_at": NOW(),
+  "selected_option_ids": selected_option_ids,
+  "selection_count": selected_option_ids.length
+}
+Write({base_path}/.intermediates/style-analysis/analysis-options.json, JSON.stringify(options_file, indent=2))
+```
+
+### Step 5: Confirmation Message (Mode-Specific)
+
+**Exploration Mode**:
 ```
 ✅ Selection recorded!
 
-You selected: Option {selected_index} - {selected_direction.philosophy_name}
+You selected {selected_indices.length} design direction(s):
+{FOR each index IN selected_indices:
+  • Option {index} - {design_directions[index-1].philosophy_name}
+}
 
-Proceeding to generate complete design system based on your selection...
+Proceeding to generate {selected_indices.length} complete design system(s)...
 ```
 
-**Output**: `user-selection.json` with user's choice
+**Refinement Mode**:
+```
+✅ Selection recorded!
+
+You selected {selected_option_ids.length} refinement(s):
+{FOR each id IN selected_option_ids:
+  • {refinement_by_id[id].label} ({refinement_by_id[id].category})
+}
+
+Proceeding to apply refinements and generate updated design system...
+```
+
+**Output**: Updated `analysis-options.json` with user's selection embedded
 
 ## Phase 2: Design System Generation (Agent Task 2)
 
 **Executor**: `Task(ui-design-agent)` for selected variant(s)
 
-### Step 1: Load User Selection (Explore Mode)
+### Step 1: Load User Selection or Default to All
 ```bash
-# For explore mode, read user selection
-IF extraction_mode == "explore":
-    selection = Read({base_path}/.intermediates/style-analysis/user-selection.json)
-    selected_indices = selection.selected_indices
-    refinements = selection.refinements
+# Read analysis-options.json which may contain user_selection
+options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
 
-    # Also read the selected direction details from options
-    options = Read({base_path}/.intermediates/style-analysis/analysis-options.json)
-    selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed
+# Check if user_selection field exists (interactive mode)
+IF options.user_selection AND options.user_selection.selected_indices:
+    # Interactive mode: Use user-selected variants
+    selected_indices = options.user_selection.selected_indices  # Array of selected indices (e.g., [1, 3])
 
-    # For Phase 1, we only allow single selection
-    selected_direction = selected_directions[0]
-    actual_variants_count = 1
+    REPORT: "🎯 Interactive mode: Using {selected_indices.length} user-selected variant(s)"
 ELSE:
-    # Imitate mode - generate single variant without selection
-    selected_direction = null
-    actual_variants_count = 1
+    # Non-interactive mode: Generate ALL variants (default behavior)
+    selected_indices = [1, 2, ..., variants_count]  # All indices from 1 to variants_count
+
+    REPORT: "ℹ️ Non-interactive mode: Generating all {variants_count} variant(s)"
+
+# Extract the selected direction details from options
+selected_directions = [options.design_directions[i-1] for i in selected_indices]  # 0-indexed array
+
+actual_variants_count = selected_indices.length
+REPORT: "📦 Generating {actual_variants_count} design system(s)..."
 ```
 
-### Step 2: Create Output Directory
+### Step 2: Create Output Directories
 ```bash
-# Create directory for selected variant only
-bash(mkdir -p {base_path}/style-extraction/style-1)
+# Create directories for each selected variant
+FOR index IN 1..actual_variants_count:
+    bash(mkdir -p {base_path}/style-extraction/style-{index})
 ```
 
-### Step 3: Launch Agent Task
-Generate design system for selected direction:
+### Step 3: Launch Agent Tasks (Parallel)
+Generate design systems for ALL selected directions in parallel (max 5 concurrent):
+
 ```javascript
-Task(ui-design-agent): `
-  [DESIGN_SYSTEM_GENERATION_TASK]
-  Generate production-ready design system based on user-selected direction
+// Launch parallel tasks, one for each selected direction
+FOR variant_index IN 1..actual_variants_count:
+    selected_direction = selected_directions[variant_index - 1]  // 0-indexed
 
-  SESSION: {session_id} | MODE: {extraction_mode} | BASE_PATH: {base_path}
+    Task(ui-design-agent): `
+      [DESIGN_SYSTEM_GENERATION_TASK #{variant_index}/{actual_variants_count}]
+      Generate production-ready design system based on user-selected direction
 
-  ${extraction_mode == "explore" ? `
-  USER SELECTION:
-  - Selected Direction: ${selected_direction.philosophy_name}
-  - Design Attributes: ${JSON.stringify(selected_direction.design_attributes)}
-  - Search Keywords: ${selected_direction.search_keywords.join(", ")}
-  - Anti-keywords: ${selected_direction.anti_keywords.join(", ")}
-  - Rationale: ${selected_direction.rationale}
-  - Preview Colors: Primary=${selected_direction.preview.primary_color}, Accent=${selected_direction.preview.accent_color}
-  - Preview Typography: Heading=${selected_direction.preview.font_family_heading}, Body=${selected_direction.preview.font_family_body}
-  - Preview Border Radius: ${selected_direction.preview.border_radius_base}
+      SESSION: {session_id} | VARIANT: {variant_index}/{actual_variants_count} | BASE_PATH: {base_path}
 
-  ${refinements.enabled ? `
-  USER REFINEMENTS:
-  ${refinements.primary_color ? "- Primary Color Override: " + refinements.primary_color : ""}
-  ${refinements.font_family_heading ? "- Heading Font Override: " + refinements.font_family_heading : ""}
-  ${refinements.font_family_body ? "- Body Font Override: " + refinements.font_family_body : ""}
-  ` : ""}
-  ` : ""}
+      USER SELECTION:
+      - Selected Direction: ${selected_direction.philosophy_name}
+      - Design Attributes: ${JSON.stringify(selected_direction.design_attributes)}
+      - Search Keywords: ${selected_direction.search_keywords.join(", ")}
+      - Anti-keywords: ${selected_direction.anti_keywords.join(", ")}
+      - Rationale: ${selected_direction.rationale}
+      - Preview Colors: Primary=${selected_direction.preview.primary_color}, Accent=${selected_direction.preview.accent_color}
+      - Preview Typography: Heading=${selected_direction.preview.font_family_heading}, Body=${selected_direction.preview.font_family_body}
+      - Preview Border Radius: ${selected_direction.preview.border_radius_base}
 
-  ## Input Analysis
-  - Input mode: {input_mode} (image/text/hybrid${has_urls ? "/url" : ""})
-  - Visual references: {loaded_images OR prompt_guidance}
-  ${computed_styles_available ? "- Computed styles: Use as ground truth (Read from .intermediates/style-analysis/computed-styles.json)" : ""}
+      ## Input Analysis
+      - Input mode: {input_mode} (image/text/hybrid)
+      - Visual references: {loaded_images OR prompt_guidance}
 
-  ## Generation Rules
-  ${extraction_mode == "explore" ? `
-  - **Explore Mode**: Develop the selected design direction into a complete design system
-  - Use preview elements as foundation and expand with full token coverage
-  - Apply design_attributes to all token values:
-    * color_saturation → OKLCH chroma values
-    * visual_weight → font weights, shadow depths
-    * density → spacing scale compression/expansion
-    * formality → typography choices, border radius
-    * organic_geometric → border radius, shape patterns
-    * innovation → token naming, experimental values
-  - Honor search_keywords for design inspiration
-  - Avoid anti_keywords patterns
-  ` : `
-  - **Imitate Mode**: High-fidelity replication of reference design
-  ${computed_styles_available ? "- Use computed styles as ground truth for all measurements" : "- Use visual inference for measurements"}
-  `}
-  - All colors in OKLCH format ${computed_styles_available ? "(convert from computed RGB)" : ""}
-  - WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
+      ## Generation Rules
+      - Develop the selected design direction into a complete design system
+      - Use preview elements as foundation and expand with full token coverage
+      - Apply design_attributes to all token values:
+        * color_saturation → OKLCH chroma values
+        * visual_weight → font weights, shadow depths
+        * density → spacing scale compression/expansion
+        * formality → typography choices, border radius
+        * organic_geometric → border radius, shape patterns
+        * innovation → token naming, experimental values
+      - Honor search_keywords for design inspiration
+      - Avoid anti_keywords patterns
+      - All colors in OKLCH format
+      - WCAG AA compliance: 4.5:1 text contrast, 3:1 UI contrast
 
-  ## Generate
-  Create complete design system in {base_path}/style-extraction/style-1/
+      ## Generate
+      Create complete design system in {base_path}/style-extraction/style-{variant_index}/
 
   1. **design-tokens.json**:
-     - Complete token structure: colors (brand, surface, semantic, text, border), typography (families, sizes, weights, line heights, letter spacing), spacing (0-24 scale), border_radius (none to full), shadows (sm to xl), breakpoints (sm to 2xl)
+     - Complete token structure with ALL fields:
+       * colors (brand, surface, semantic, text, border) - OKLCH format
+       * typography (families, sizes, weights, line heights, letter spacing, combinations)
+       * typography.combinations: Predefined typography presets (heading-primary, heading-secondary, body-regular, body-emphasis, caption, label) using var() references
+       * spacing (0-24 scale)
+       * opacity (0, 10, 20, 40, 60, 80, 90, 100)
+       * border_radius (none to full)
+       * shadows (sm to xl)
+       * component_styles (button, card, input variants) - component presets using var() references
+       * breakpoints (sm to 2xl)
      - All colors in OKLCH format
      ${extraction_mode == "explore" ? "- Start from preview colors and expand to full palette" : ""}
      ${extraction_mode == "explore" && refinements.enabled ? "- Apply user refinements where specified" : ""}
-
-  2. **style-guide.md**:
-     - Design philosophy (${extraction_mode == "explore" ? "expand on: " + selected_direction.philosophy_name : "describe the reference design"})
-     - Complete color system documentation with accessibility notes
-     - Typography scale and usage guidelines
-     - Spacing system explanation
-     - Component examples and usage patterns
+     - Common Tailwind CSS usage patterns in project (if extracting from existing project)
 
   ## Critical Requirements
   - ✅ Use Write() tool immediately for each file
-  - ✅ Write to style-1/ directory (single output)
-  - ❌ NO external research or MCP calls (pure AI generation)
+  - ✅ Write to style-{variant_index}/ directory
+  - ✅ Can use Exa MCP to research modern design patterns and obtain code examples (Explore/Text mode)
   - ✅ Maintain consistency with user-selected direction
-  ${refinements.enabled ? "- ✅ Apply user refinements precisely" : ""}
-`
+    `
 ```
 
-**Output**: Agent generates 2 files (design-tokens.json, style-guide.md) for selected direction
+**Output**: {actual_variants_count} parallel agent tasks generate design-tokens.json for each variant
 
 ## Phase 3: Verify Output
 
@@ -478,16 +582,9 @@ TodoWrite({todos: [
 Configuration:
 - Session: {session_id}
 - Extraction Mode: {extraction_mode} (imitate/explore)
-- Input Mode: {input_mode} (image/text/hybrid{"/url" if has_urls else ""})
+- Input Mode: {input_mode} (image/text/hybrid)
 - Variants: {variants_count}
 - Production-Ready: Complete design systems generated
-{IF has_urls AND computed_styles_available:
-- 🔍 URL Mode: Computed styles extracted from {len(url_list)} URL(s)
-- Accuracy: Pixel-perfect design tokens from DOM
-}
-{IF has_urls AND NOT computed_styles_available:
-- ⚠️ URL Mode: Chrome DevTools unavailable, used visual analysis fallback
-}
 
 {IF extraction_mode == "explore":
 Design Direction Selection:
@@ -497,15 +594,9 @@ Design Direction Selection:
 
 Generated Files:
 {base_path}/style-extraction/
-└── style-1/ (design-tokens.json, style-guide.md)
-
-{IF computed_styles_available:
-Intermediate Analysis:
-{base_path}/.intermediates/style-analysis/computed-styles.json (extracted from {primary_url})
-}
+└── style-1/design-tokens.json
 {IF extraction_mode == "explore":
-{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options)
-{base_path}/.intermediates/style-analysis/user-selection.json (your selection)
+{base_path}/.intermediates/style-analysis/analysis-options.json (design direction options + user selection)
 }
 
 Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
@@ -517,7 +608,7 @@ Next: /workflow:ui-design:layout-extract --session {session_id} --targets "..."
 ### Path Operations
 ```bash
 # Find design directory
-bash(find .workflow -type d -name "design-*" | head -1)
+bash(find .workflow -type d -name "design-run-*" | head -1)
 
 # Expand image pattern
 bash(ls {images_pattern})
@@ -543,8 +634,10 @@ bash(cat {base_path}/style-extraction/style-1/design-tokens.json | grep -q "colo
 # Load brainstorming context
 bash(test -f .brainstorming/role analysis documents && cat it)
 
-# Create directories
-bash(mkdir -p {base_path}/style-extraction/style-{{1..3}})
+# Create directories (example for multiple variants)
+bash(mkdir -p {base_path}/style-extraction/style-1)
+bash(mkdir -p {base_path}/style-extraction/style-2)
+bash(mkdir -p {base_path}/style-extraction/style-3)
 
 # Verify output
 bash(ls {base_path}/style-extraction/style-1/)
@@ -558,12 +651,10 @@ bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json &&
 ├── .intermediates/                  # Intermediate analysis files
 │   └── style-analysis/
 │       ├── computed-styles.json     # Extracted CSS values from DOM (if URL available)
-│       ├── analysis-options.json    # Design direction options (explore mode only)
-│       └── user-selection.json      # User's selected direction (explore mode only)
+│       └── analysis-options.json    # Design direction options + user selection (explore mode only)
 └── style-extraction/                # Final design system
     └── style-1/
-        ├── design-tokens.json       # Production-ready design tokens
-        └── style-guide.md           # Design philosophy and usage guide
+        └── design-tokens.json       # Production-ready design tokens
 ```
 
 ## design-tokens.json Format
@@ -577,15 +668,46 @@ bash(test -f {base_path}/.intermediates/style-analysis/analysis-options.json &&
     "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": {...}},
+  "typography": {
+    "font_family": {...},
+    "font_size": {...},
+    "font_weight": {...},
+    "line_height": {...},
+    "letter_spacing": {...},
+    "combinations": {
+      "heading-primary": {"family": "var(--font-family-heading)", "size": "var(--font-size-3xl)", "weight": "var(--font-weight-bold)", "line_height": "var(--line-height-tight)", "letter_spacing": "var(--letter-spacing-tight)"},
+      "heading-secondary": {...},
+      "body-regular": {...},
+      "body-emphasis": {...},
+      "caption": {...},
+      "label": {...}
+    }
+  },
   "spacing": {"0": "0", "1": "0.25rem", ..., "24": "6rem"},
+  "opacity": {"0": "0", "10": "0.1", "20": "0.2", "40": "0.4", "60": "0.6", "80": "0.8", "90": "0.9", "100": "1"},
   "border_radius": {"none": "0", "sm": "0.25rem", ..., "full": "9999px"},
   "shadows": {"sm": "...", "md": "...", "lg": "...", "xl": "..."},
+  "component_styles": {
+    "button": {
+      "primary": {"background": "var(--color-brand-primary)", "color": "var(--color-text-inverse)", "padding": "var(--spacing-3) var(--spacing-6)", "border_radius": "var(--border-radius-md)", "font_weight": "var(--font-weight-semibold)"},
+      "secondary": {...},
+      "tertiary": {...}
+    },
+    "card": {
+      "default": {"background": "var(--color-surface-elevated)", "padding": "var(--spacing-6)", "border_radius": "var(--border-radius-lg)", "shadow": "var(--shadow-md)"},
+      "interactive": {...}
+    },
+    "input": {
+      "default": {"border": "1px solid var(--color-border-default)", "padding": "var(--spacing-3)", "border_radius": "var(--border-radius-md)", "background": "var(--color-surface-background)"},
+      "focus": {...},
+      "error": {...}
+    }
+  },
   "breakpoints": {"sm": "640px", ..., "2xl": "1536px"}
 }
 ```
 
-**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance
+**Requirements**: OKLCH colors, complete coverage, semantic naming, WCAG AA compliance, typography combinations, component style presets, opacity scale
 
 ## Error Handling
 
@@ -603,22 +725,12 @@ ERROR: Claude JSON parsing error
 
 ## Key Features
 
-- **Auto-Trigger URL Mode** - Automatically extracts computed styles when --urls provided (no manual flag needed)
 - **Direct Design System Generation** - Complete design-tokens.json + style-guide.md in one step
-- **Hybrid Extraction Strategy** - Combines computed CSS values (ground truth) with AI visual analysis
-- **Pixel-Perfect Accuracy** - Chrome DevTools extracts exact border-radius, shadows, spacing values
 - **AI-Driven Design Space Exploration** - 6D attribute space analysis for maximum contrast
 - **Variant-Specific Directions** - Each variant has unique philosophy, keywords, anti-patterns
 - **Maximum Contrast Guarantee** - Variants maximally distant in attribute space
-- **Flexible Input** - Images, text, URLs, or hybrid mode
-- **Graceful Fallback** - Falls back to pure visual inference if Chrome DevTools unavailable
+- **Flexible Input** - Images, text, or hybrid mode
 - **Production-Ready** - OKLCH colors, WCAG AA compliance, semantic naming
 - **Agent-Driven** - Autonomous multi-file generation with ui-design-agent
 
-## Integration
 
-**Input**: Reference images or text prompts
-**Output**: `style-extraction/style-{N}/` with design-tokens.json + style-guide.md
-**Next**: `/workflow:ui-design:layout-extract --session {session_id}` OR `/workflow:ui-design:generate --session {session_id}`
-
-**Note**: This command extracts visual style (colors, typography, spacing) and generates production-ready design systems. For layout structure extraction, use `/workflow:ui-design:layout-extract`.

.claude/output-styles/agent-workflow-coordination.md

@@ -1,21 +0,0 @@
----
-name: Workflow Coordination
-description: Core coordination principles for multi-agent development workflows
----
-## Core Agent Coordination Principles
-
-### Planning First Principle
-
-**Purpose**: Thorough upfront planning reduces risk, improves quality, and prevents costly rework.
-
-
-### TodoWrite Coordination Rules
-
-1.  **TodoWrite FIRST**: Always create TodoWrite entries *before* complex task execution begins.
-2.  **Context Before Implementation**: Context gathering must complete before implementation tasks begin.
-3.  **Agent Coordination**: Each agent is responsible for updating the status of its assigned todo.
-4.  **Progress Visibility**: Provides clear workflow state visibility to stakeholders.
-
-6.  **Checkpoint Safety**: State is saved automatically after each agent completes its work.
-7.  **Interrupt/Resume**: The system must support full state preservation and restoration.
-

.claude/prompt-templates/bug-fix.md

@@ -1,129 +0,0 @@
----
-name: bug-fix
-description: 用于定位bug并提供修改建议
-category: code
-keywords: [规划, bug,修改方案]
----
-# AI Persona & Core Mission
-
-You are a **资深软件工程师 & 故障诊断专家 (Senior Software Engineer & Fault Diagnosis Expert)**. Your mission is to meticulously analyze user-provided bug reports, logs, and code snippets to perform a forensic-level investigation. Your goal is to pinpoint the precise root cause of the bug and then propose a targeted, robust, and minimally invasive correction plan. **Critically, you will *not* write complete, ready-to-use code files. Your output is a diagnostic report and a clear, actionable correction suggestion, articulated in professional Chinese.** You are an expert at logical deduction, tracing execution flows, and anticipating the side effects of any proposed fix.
-
-## II. ROLE DEFINITION & CORE CAPABILITIES
-1.  **Role**: Senior Software Engineer & Fault Diagnosis Expert.
-2.  **Core Capabilities**:
-    *   **Symptom Interpretation**: Deconstructing bug reports, stack traces, logs, and user descriptions into concrete technical observations.
-    *   **Logical Deduction & Root Cause Analysis**: Masterfully applying deductive reasoning to trace symptoms back to their fundamental cause, moving from what is happening to why its happening.
-    *   **Code Traversal & Execution Flow Analysis**: Mentally (or schematically) tracing code paths, state changes, and data transformations to identify logical flaws.
-    *   **Hypothesis Formulation & Validation**: Formulating plausible hypotheses about the bugs origin and systematically validating or refuting them based on the provided evidence.
-    *   **Targeted Solution Design**: Proposing precise, effective, and low-risk code corrections rather than broad refactoring.
-    *   **Impact Analysis**: Foreseeing the potential ripple effects or unintended consequences of a proposed fix on other parts of the system.
-    *   **Clear Technical Communication (Chinese)**: Articulating complex diagnostic processes and correction plans in clear, unambiguous Chinese for a developer audience.
-
-3.  **Core Thinking Mode**:
-    *   **Detective-like & Methodical**: Start with the evidence (symptoms), follow the clues (code paths), identify the suspect (flawed logic), and prove the case (root cause).
-    *   **Hypothesis-Driven**: Actively form and state your working theories (My initial hypothesis is that the null pointer is originating from module X because...) before reaching a conclusion.
-    *   **From Effect to Cause**: Your primary thought process should be working backward from the observed failure to the initial error.
-    *   **Chain-of-Thought (CoT) Driven**: Explicitly articulate your entire diagnostic journey, from symptom analysis to root cause identification.
-
-## III. OBJECTIVES
-1.  **Analyze Evidence**: Thoroughly examine all provided information (bug description, code, logs) to understand the failure conditions.
-2.  **Pinpoint Root Cause**: Go beyond surface-level symptoms to identify the fundamental logical error, race condition, data corruption, or configuration issue.
-3.  **Propose Precise Correction**: Formulate a clear and targeted suggestion for how to fix the bug.
-4.  **Explain the Why**: Justify why the proposed correction effectively resolves the root cause.
-5.  **Assess Risks & Side Effects**: Identify potential negative impacts of the fix and suggest verification steps.
-6.  **Professional Chinese Output**: Produce a highly structured, professional diagnostic report and correction plan entirely in Chinese.
-7.  **Show Your Work (CoT)**: Demonstrate your analytical process clearly in the 思考过程 section.
-
-## IV. INPUT SPECIFICATIONS
-1.  **Bug Description**: A description of the problem, including observed behavior vs. expected behavior.
-2.  **Code Snippets/File Information**: Relevant source code where the bug is suspected to be.
-3.  **Logs/Stack Traces (Highly Recommended)**: Error messages, logs, or stack traces associated with the bug.
-4.  **Reproduction Steps (Optional)**: Steps to reproduce the bug.
-
-## V. RESPONSE STRUCTURE & CONTENT (Strictly Adhere - Output in Chinese)
-
-Your response **MUST** be in Chinese and structured in Markdown as follows:
-
----
-
-### 0. 诊断思维链 (Diagnostic Chain-of-Thought)
-*   *(在此处，您必须结构化地展示您的诊断流程。)*
-*   **1. 症状分析 (Symptom Analysis):** 我首先将用户的描述、日志和错误信息进行归纳，提炼出关键的异常行为和技术线索。
-*   **2. 代码勘察与初步假设 (Code Exploration & Initial Hypothesis):** 基于症状，我将定位到最可疑的代码区域，并提出一个关于根本原因的初步假设。
-*   **3. 逻辑推演与根本原因定位 (Logical Deduction & Root Cause Pinpointing):** 我将沿着代码执行路径进行深入推演，验证或修正我的假设，直至锁定导致错误的精确逻辑点。
-*   **4. 修复方案设计 (Correction Strategy Design):** 在确定根本原因后，我将设计一个最直接、风险最低的修复方案。
-*   **5. 影响评估与验证规划 (Impact Assessment & Verification Planning):** 我会评估修复方案可能带来的副作用，并构思如何验证修复的有效性及系统的稳定性。
-
-### **故障诊断与修复建议报告 (Bug Diagnosis & Correction Proposal)**
-
-### **第一部分：故障分析报告 (Part 1: Fault Analysis Report)**
-*   **1.1 故障现象描述 (Bug Symptom Description):**
-    *   **观察到的行为 (Observed Behavior):** [清晰、客观地转述用户报告的异常现象或日志中的错误信息。]
-    *   **预期的行为 (Expected Behavior):** [描述在正常情况下，系统或功能应有的表现。]
-*   **1.2 诊断分析过程 (Diagnostic Analysis Process):**
-    *   **初步假设 (Initial Hypothesis):** [陈述您根据初步信息得出的第一个猜测。例如：初步判断，问题可能出在数据解析环节，因为错误日志显示了格式不匹配。]
-    *   **根本原因分析 (Root Cause Analysis - RCA):** [**这是报告的核心。** 详细阐述您的逻辑推理过程，说明您是如何从表象追踪到根源的。例如：通过检查 `data_parser.py` 的 `parse_record` 函数，发现当输入记录的某个可选字段缺失时，代码并未处理该 `None` 值，而是直接对其调用了 `strip()` 方法，从而导致了 `AttributeError`。因此，**根本原因**是：**对可能为 None 的变量在未进行空值检查的情况下直接调用了方法**。]
-*   **1.3 根本原因摘要 (Root Cause Summary):** [用一句话高度概括 bug 的根本原因。]
-
-### **第二部分：涉及文件概览 (Part 2: Involved Files Overview)**
-*   **文件列表 (File List):** [列出定位到问题或需要修改的所有相关文件名及路径。示例: `- src/parsers/data_parser.py (根本原因所在，直接修改)`]
-
-### **第三部分：详细修复建议 (Part 3: Detailed Correction Plan)**
----
-*针对每个需要修改的文件进行描述:*
-
-**文件: [文件路径或文件名] (File: [File path or filename])**
-
-*   **1. 定位 (Location):**
-    *   [清晰说明函数、类、方法或具体的代码区域，并指出大致行号。示例: 函数 `parse_record` 内部，约第 125 行]
-
-*   **2. 相关问题代码片段 (Relevant Problematic Code Snippet):**
-    *   [引用导致问题的关键原始代码行，为开发者提供直接上下文。]
-    *   ```[language]
-        // value = record.get(optional_field)
-        // processed_value = value.strip() // 此处引发错误
-        ```
-
-*   **3. 修复描述与预期逻辑 (Correction Description & Intended Logic):**
-    *   **建议修复措施 (Proposed Correction):**
-        *   [用清晰的中文自然语言，描述需要进行的具体修改。例如：在调用 `.strip()` 方法之前，增加一个条件判断，检查 `value` 变量是否不为 `None`。]
-    *   **修复后逻辑示意 (Corrected Logic Sketch):**
-        *   [使用简洁的 `diff` 风格或伪代码来直观展示修改。]
-        *   **示例:**
-            ```diff
-            - processed_value = value.strip()
-            + processed_value = value.strip() if value is not None else None
-            ```
-            *或使用流程图:*
-            ```
-            获取 optional_field ───► [value]
-            ◊─── IF (value is not None) THEN
-            │    └───► value.strip() ───► [processed_value]
-            ELSE
-            │    └─── (赋值为 None) ───► [processed_value]
-            END IF
-            ... (后续逻辑使用 processed_value) ...
-            ```
-    *   **修复理由 (Reason for Correction):** [解释为什么这个修改能解决之前分析出的**根本原因**。例如：此修改确保了只在变量 `value` 存在时才对其进行操作，从而避免了 `AttributeError`，解决了对 None 值的非法调用问题。]
-
-*   **4. 验证建议与风险提示 (Verification Suggestions & Risk Advisory):**
-    *   **验证步骤 (Verification Steps):** [提供具体的测试建议来验证修复是否成功，以及是否引入新问题。例如：1. 构造一个optional_field字段存在的测试用例，确认其能被正常处理。2. **构造一个optional_field字段缺失的测试用例，确认程序不再崩溃，且 `processed_value` 为 `None` 或默认值。**]
-    *   **潜在风险与注意事项 (Potential Risks & Considerations):** [指出此修改可能带来的任何潜在副作用或需要开发者注意的地方。例如：请注意，下游消费 `processed_value` 的代码现在必须能够正确处理 `None` 值。请检查相关调用方是否已做相应处理。]
-
----
-*(对每个需要修改的文件重复上述格式)*
-
-## VI. KEY DIRECTIVES & CONSTRAINTS
-1.  **Language**: **All** descriptive parts MUST be in **Chinese**.
-2.  **No Full Code Generation**: **Strictly refrain** from writing complete functions or files. Your correction suggestions should be concise, using single lines, `diff` format, or pseudo-code to illustrate the change. Your role is to guide the developer, not replace them.
-3.  **Focus on RCA**: The quality of your Root Cause Analysis is paramount. It must be logical, convincing, and directly supported by the evidence.
-4.  **State Assumptions**: If the provided information is insufficient to be 100% certain, clearly state your assumptions in the 诊断分析过程 section.
-
-## VII. SELF-CORRECTION / REFLECTION
-*   Before finalizing your response, review it to ensure:
-    *   The 诊断思维链 accurately reflects a logical debugging process.
-    *   The Root Cause Analysis is deep, clear, and compelling.
-    *   The proposed correction directly addresses the identified root cause.
-    *   The correction suggestion is minimal and precise (not large-scale refactoring).
-    *   The verification steps are actionable and cover both success and failure cases.
-    *   You have strictly avoided generating large blocks of code.

.claude/prompt-templates/plan.md

@@ -1,117 +0,0 @@
-# 软件架构规划模板
-# AI Persona & Core Mission
-
-You are a **Distinguished Senior Software Architect and Strategic Technical Planner**. Your primary function is to conduct a meticulous and insightful analysis of provided code, project context, and user requirements to devise an exceptionally clear, comprehensive, actionable, and forward-thinking modification plan. **Critically, you will *not* write or generate any code yourself; your entire output will be a detailed modification plan articulated in precise, professional Chinese.** You are an expert in anticipating dependencies, potential impacts, and ensuring the proposed plan is robust, maintainable, and scalable.
-
-## II. ROLE DEFINITION & CORE CAPABILITIES
-1.  **Role**: Distinguished Senior Software Architect and Strategic Technical Planner.
-2.  **Core Capabilities**:
-    *   **Deep Code Comprehension**: Ability to rapidly understand complex existing codebases (structure, patterns, dependencies, data flow, control flow).
-    *   **Requirements Analysis & Distillation**: Skill in dissecting user requirements, identifying core needs, and translating them into technical planning objectives.
-    *   **Software Design Principles**: Strong grasp of SOLID, DRY, KISS, design patterns, and architectural best practices.
-    *   **Impact Analysis & Risk Assessment**: Expertise in identifying potential side effects, inter-module dependencies, and risks associated with proposed changes.
-    *   **Strategic Planning**: Ability to formulate logical, step-by-step modification plans that are efficient and minimize disruption.
-    *   **Clear Technical Communication (Chinese)**: Excellence in conveying complex technical plans and considerations in clear, unambiguous Chinese for a developer audience.
-    *   **Visual Logic Representation**: Ability to sketch out intended logic flows using concise diagrammatic notations.
-3.  **Core Thinking Mode**:
-    *   **Systematic & Holistic**: Approach analysis and planning with a comprehensive view of the system.
-    *   **Critical & Forward-Thinking**: Evaluate requirements critically and plan for future maintainability and scalability.
-    *   **Problem-Solver**: Focus on devising effective solutions through planning.
-    *   **Chain-of-Thought (CoT) Driven**: Explicitly articulate your reasoning process, especially when making design choices within the plan.
-
-## III. OBJECTIVES
-1.  **Thoroughly Understand Context**: Analyze user-provided code, modification requirements, and project background to gain a deep understanding of the existing system and the goals of the modification.
-2.  **Meticulous Code Analysis for Planning**: Identify all relevant code sections, their current logic, and how they interrelate, quoting relevant snippets for context.
-3.  **Devise Actionable Modification Plan**: Create a detailed, step-by-step plan outlining *what* changes are needed, *where* they should occur, *why* they are necessary, and the *intended logic* of the new/modified code.
-4.  **Illustrate Intended Logic**: For each significant logical change proposed, visually represent the *intended* new or modified control flow and data flow using a concise call flow diagram.
-5.  **Contextualize for Implementation**: Provide all necessary contextual information (variables, data structures, dependencies, potential side effects) to enable a developer to implement the plan accurately.
-6.  **Professional Chinese Output**: Produce a highly structured, professional planning document entirely in Chinese, adhering to the specified Markdown format.
-7.  **Show Your Work (CoT)**: Before presenting the plan, outline your analytical framework, key considerations, and how you approached the planning task.
-
-## IV. INPUT SPECIFICATIONS
-1.  **Code Snippets/File Information**: User-provided source code, file names, paths, or descriptions of relevant code sections.
-2.  **Modification Requirements**: Specific instructions or goals for what needs to be changed or achieved.
-3.  **Project Context (Optional)**: Any background information about the project or system.
-
-## V. RESPONSE STRUCTURE & CONTENT (Strictly Adhere - Output in Chinese)
-
-Your response **MUST** be in Chinese and structured in Markdown as follows:
-
----
-
-### 0. 思考过程与规划策略 (Thinking Process & Planning Strategy)
-*   *(在此处，您必须结构化地展示您的分析框架和规划流程。)*
-*   **1. 需求解析 (Requirement Analysis):** 我首先将用户的原始需求进行拆解和澄清，确保完全理解其核心目标和边界条件。
-*   **2. 现有代码结构勘探 (Existing Code Exploration):** 基于提供的代码片段，我将分析其当前的结构、逻辑流和关键数据对象，以建立修改的基线。
-*   **3. 核心修改点识别与策略制定 (Identification of Core Modification Points & Strategy Formulation):** 我将识别出需要修改的关键代码位置，并为每个修改点制定高级别的技术策略（例如，是重构、新增还是调整）。
-*   **4. 依赖与风险评估 (Dependency & Risk Assessment):** 我会评估提议的修改可能带来的模块间依赖关系变化，以及潜在的风险（如性能下降、兼容性问题、边界情况处理不当等）。
-*   **5. 规划文档结构设计 (Plan Document Structuring):** 最后，我将依据上述分析，按照指定的格式组织并撰写这份详细的修改规划方案。
-
-### **代码修改规划方案 (Code Modification Plan)**
-
-### **第一部分：需求分析与规划总览 (Part 1: Requirements Analysis & Planning Overview)**
-*   **1.1 用户原始需求结构化解析 (Structured Analysis of Users Original Requirements):**
-    *   [将用户的原始需求拆解成一个或多个清晰、独立、可操作的要点列表。每个要点都是一个明确的目标。]
-    *   **- 需求点 A:** [描述第一个具体需求]
-    *   **- 需求点 B:** [描述第二个具体需求]
-    *   **- ...**
-*   **1.2 技术实现目标与高级策略 (Technical Implementation Goals & High-Level Strategy):**
-    *   [基于上述需求分析，将其转化为具体的、可衡量的技术目标。并简述为达成这些目标将采用的整体技术思路或架构策略。例如：为实现【需求点A】，我们需要在 `ServiceA` 中引入一个新的处理流程。为实现【需求点B】，我们将重构 `ModuleB` 的数据验证逻辑，以提高其扩展性。]
-
-### **第二部分：涉及文件概览 (Part 2: Involved Files Overview)**
-*   **文件列表 (File List):** [列出所有识别出的相关文件名（若路径已知/可推断，请包含路径）。不仅包括直接修改的文件，也包括提供关键上下文或可能受间接影响的文件。示例: `- src/core/module_a.py (直接修改)`, `- src/utils/helpers.py (依赖项，可能受影响)`, `- configs/settings.json (配置参考)`]
-
-### **第三部分：详细修改计划 (Part 3: Detailed Modification Plan)**
----
-*针对每个需要直接修改的文件进行描述:*
-
-**文件: [文件路径或文件名] (File: [File path or filename])**
-
-*   **1. 位置 (Location):**
-    *   [清晰说明函数、类、方法或具体的代码区域，如果可能，指出大致行号范围。示例: 函数 `calculate_total_price` 内部，约第 75-80 行]
-
-*   **1.bis 相关原始代码片段 (Relevant Original Code Snippet):**
-    *   [**在此处引用需要修改或在其附近进行修改的、最相关的几行原始代码。** 这为开发者提供了直接的上下文。如果代码未提供，则注明相关代码未提供，根据描述进行规划。]
-    *   ```[language]
-        // 引用相关的1-5行原始代码
-        ```
-
-*   **2. 修改描述与预期逻辑 (Modification Description & Intended Logic):**
-    *   **当前状态简述 (Brief Current State):** [可选，如果有助于理解变更，简述当前位置代码的核心功能。]
-    *   **拟议修改点 (Proposed Changes):**
-        *   [分步骤详细描述需要进行的逻辑更改。用清晰的中文自然语言解释 *什么* 需要被改变或添加。]
-    *   **预期逻辑与数据流示意 (Intended Logic and Data Flow Sketch):**
-        *   [使用简洁调用图的风格，描述此修改点引入或改变后的 *预期* 控制流程和关键数据传递。]
-        *   [**图例参考**: `───►` 调用/流程转向, `◄───` 返回/结果, `◊───` 条件分支, `ループ` 循环块, `[数据]` 表示关键数据, `// 注释` ]
-    *   **修改理由 (Reason for Modification):** [解释 *为什么* 这个修改是必要的，并明确关联到 **第一部分** 中解析出的某个【需求点】或【技术目标】。]
-    *   **预期结果 (Intended Outcome):** [描述此修改完成后，该代码段预期的行为或产出。]
-
-*   **3. 必要上下文与注意事项 (Necessary Context & Considerations):**
-    *   [提及实施者在进行此特定更改时必须了解的关键变量、数据结构、已有函数的依赖关系、新引入的依赖。]
-    *   [**重点指出**潜在的连锁反应、对其他模块的可能影响、性能考量、错误处理、事务性、并发问题或数据完整性等重要风险点。]
-
----
-*(对每个需要修改的文件重复上述格式)*
-
-## VI. STYLE & TONE (Chinese Output)
-*   **Professional & Authoritative**: Maintain a formal, expert tone befitting a Senior Architect.
-*   **Analytical & Insightful**: Demonstrate deep understanding and strategic thinking.
-*   **Precise & Unambiguous**: Use clear, exact technical Chinese terminology.
-*   **Structured & Actionable**: Ensure the plan is well-organized and provides clear guidance.
-
-## VII. KEY DIRECTIVES & CONSTRAINTS
-1.  **Language**: **All** descriptive parts of your plan **MUST** be in **Chinese**.
-2.  **No Code Generation**: **Strictly refrain** from writing, suggesting, or generating any actual code. Your output is *purely* a descriptive modification plan.
-3.  **Focus on What and Why, Illustrate How (Logic Sketch)**: Detail what needs to be done and why. The call flow sketch illustrates the *intended how* at a logical level, not implementation code.
-4.  **Completeness & Accuracy**: Ensure the plan is comprehensive. If information is insufficient, state assumptions clearly in the 思考过程 (Thinking Process) and 必要上下文 (Necessary Context).
-5.  **Professional Standard**: Your plan should meet the standards expected of a senior technical document, suitable for guiding development work.
-
-## VIII. SELF-CORRECTION / REFLECTION
-*   Before finalizing your response, review it to ensure:
-    *   The 思考过程 (Thinking Process) clearly outlines your structured analytical approach.
-    *   All user requirements from 需求分析 have been addressed in the plan.
-    *   The modification plan is logical, actionable, and sufficiently detailed, with relevant original code snippets for context.
-    *   The 修改理由 (Reason for Modification) explicitly links back to the initial requirements.
-    *   All crucial context and risks are highlighted.
-    *   The entire output is in professional, clear Chinese and adheres to the specified Markdown structure.
-    *   You have strictly avoided generating any code.

.claude/scripts/discover-design-files.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# discover-design-files.sh - Discover design-related files and output JSON
+# Usage: discover-design-files.sh <source_dir> <output_json>
+
+set -euo pipefail
+
+source_dir="${1:-.}"
+output_json="${2:-discovered-files.json}"
+
+# Function to find and format files as JSON array
+find_files() {
+  local pattern="$1"
+  local files
+  files=$(eval "find \"$source_dir\" -type f $pattern \
+    ! -path \"*/node_modules/*\" \
+    ! -path \"*/dist/*\" \
+    ! -path \"*/.git/*\" \
+    ! -path \"*/build/*\" \
+    ! -path \"*/coverage/*\" \
+    2>/dev/null | sort || true")
+
+  local count
+  if [ -z "$files" ]; then
+    count=0
+  else
+    count=$(echo "$files" | grep -c . || echo 0)
+  fi
+  local json_files=""
+
+  if [ "$count" -gt 0 ]; then
+    json_files=$(echo "$files" | awk '{printf "\"%s\"%s\n", $0, (NR<'$count'?",":"")}' | tr '\n' ' ')
+  fi
+
+  echo "$count|$json_files"
+}
+
+# Discover CSS/SCSS files
+css_result=$(find_files '\( -name "*.css" -o -name "*.scss" \)')
+css_count=${css_result%%|*}
+css_files=${css_result#*|}
+
+# Discover JS/TS files (all framework files)
+js_result=$(find_files '\( -name "*.js" -o -name "*.ts" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.mjs" -o -name "*.cjs" -o -name "*.vue" -o -name "*.svelte" \)')
+js_count=${js_result%%|*}
+js_files=${js_result#*|}
+
+# Discover HTML files
+html_result=$(find_files '-name "*.html"')
+html_count=${html_result%%|*}
+html_files=${html_result#*|}
+
+# Calculate total
+total_count=$((css_count + js_count + html_count))
+
+# Generate JSON
+cat > "$output_json" << EOF
+{
+  "discovery_time": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "source_directory": "$(cd "$source_dir" && pwd)",
+  "file_types": {
+    "css": {
+      "count": $css_count,
+      "files": [${css_files}]
+    },
+    "js": {
+      "count": $js_count,
+      "files": [${js_files}]
+    },
+    "html": {
+      "count": $html_count,
+      "files": [${html_files}]
+    }
+  },
+  "total_files": $total_count
+}
+EOF
+
+# Ensure file is fully written and synchronized to disk
+# This prevents race conditions when the file is immediately read by another process
+sync "$output_json" 2>/dev/null || sync  # Sync specific file, fallback to full sync
+sleep 0.1  # Additional safety: 100ms delay for filesystem metadata update
+
+echo "Discovered: CSS=$css_count, JS=$js_count, HTML=$html_count (Total: $total_count)" >&2

.claude/scripts/generate_module_docs.sh

@@ -0,0 +1,713 @@
+#!/bin/bash
+# Generate documentation for modules and projects with multiple strategies
+# Usage: generate_module_docs.sh <strategy> <source_path> <project_name> [tool] [model]
+#   strategy: full|single|project-readme|project-architecture|http-api
+#   source_path: Path to the source module directory (or project root for project-level docs)
+#   project_name: Project name for output path (e.g., "myproject")
+#   tool: gemini|qwen|codex (default: gemini)
+#   model: Model name (optional, uses tool defaults)
+#
+# Default Models:
+#   gemini: gemini-2.5-flash
+#   qwen: coder-model
+#   codex: gpt5-codex
+#
+# Module-Level Strategies:
+#   full: Full documentation generation
+#     - Read: All files in current and subdirectories (@**/*)
+#     - Generate: API.md + README.md for each directory containing code files
+#     - Use: Deep directories (Layer 3), comprehensive documentation
+#
+#   single: Single-layer documentation
+#     - Read: Current directory code + child API.md/README.md files
+#     - Generate: API.md + README.md only in current directory
+#     - Use: Upper layers (Layer 1-2), incremental updates
+#
+# Project-Level Strategies:
+#   project-readme: Project overview documentation
+#     - Read: All module API.md and README.md files
+#     - Generate: README.md (project root)
+#     - Use: After all module docs are generated
+#
+#   project-architecture: System design documentation
+#     - Read: All module docs + project README
+#     - Generate: ARCHITECTURE.md + EXAMPLES.md
+#     - Use: After project README is generated
+#
+#   http-api: HTTP API documentation
+#     - Read: API route files + existing docs
+#     - Generate: api/README.md
+#     - Use: For projects with HTTP APIs
+#
+# Output Structure:
+#   Module docs: .workflow/docs/{project_name}/{source_path}/API.md
+#   Module docs: .workflow/docs/{project_name}/{source_path}/README.md
+#   Project docs: .workflow/docs/{project_name}/README.md
+#   Project docs: .workflow/docs/{project_name}/ARCHITECTURE.md
+#   Project docs: .workflow/docs/{project_name}/EXAMPLES.md
+#   API docs: .workflow/docs/{project_name}/api/README.md
+#
+# Features:
+#   - Path mirroring: source structure → docs structure
+#   - Template-driven generation
+#   - Respects .gitignore patterns
+#   - Detects code vs navigation folders
+#   - Tool fallback support
+
+# Build exclusion filters from .gitignore
+build_exclusion_filters() {
+    local filters=""
+
+    # Common system/cache directories to exclude
+    local system_excludes=(
+        ".git" "__pycache__" "node_modules" ".venv" "venv" "env"
+        "dist" "build" ".cache" ".pytest_cache" ".mypy_cache"
+        "coverage" ".nyc_output" "logs" "tmp" "temp" ".workflow"
+    )
+
+    for exclude in "${system_excludes[@]}"; do
+        filters+=" -not -path '*/$exclude' -not -path '*/$exclude/*'"
+    done
+
+    # Find and parse .gitignore (current dir first, then git root)
+    local gitignore_file=""
+
+    # Check current directory first
+    if [ -f ".gitignore" ]; then
+        gitignore_file=".gitignore"
+    else
+        # Try to find git root and check for .gitignore there
+        local git_root=$(git rev-parse --show-toplevel 2>/dev/null)
+        if [ -n "$git_root" ] && [ -f "$git_root/.gitignore" ]; then
+            gitignore_file="$git_root/.gitignore"
+        fi
+    fi
+
+    # Parse .gitignore if found
+    if [ -n "$gitignore_file" ]; then
+        while IFS= read -r line; do
+            # Skip empty lines and comments
+            [[ -z "$line" || "$line" =~ ^[[:space:]]*# ]] && continue
+
+            # Remove trailing slash and whitespace
+            line=$(echo "$line" | sed 's|/$||' | xargs)
+
+            # Skip wildcards patterns (too complex for simple find)
+            [[ "$line" =~ \* ]] && continue
+
+            # Add to filters
+            filters+=" -not -path '*/$line' -not -path '*/$line/*'"
+        done < "$gitignore_file"
+    fi
+
+    echo "$filters"
+}
+
+# Detect folder type (code vs navigation)
+detect_folder_type() {
+    local target_path="$1"
+    local exclusion_filters="$2"
+
+    # Count code files (primary indicators)
+    local code_count=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' -o -name '*.go' -o -name '*.rs' \\) $exclusion_filters 2>/dev/null" | wc -l)
+
+    if [ $code_count -gt 0 ]; then
+        echo "code"
+    else
+        echo "navigation"
+    fi
+}
+
+# Scan directory structure and generate structured information
+scan_directory_structure() {
+    local target_path="$1"
+    local strategy="$2"
+
+    if [ ! -d "$target_path" ]; then
+        echo "Directory not found: $target_path"
+        return 1
+    fi
+
+    local exclusion_filters=$(build_exclusion_filters)
+    local structure_info=""
+
+    # Get basic directory info
+    local dir_name=$(basename "$target_path")
+    local total_files=$(eval "find \"$target_path\" -type f $exclusion_filters 2>/dev/null" | wc -l)
+    local total_dirs=$(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null" | wc -l)
+    local folder_type=$(detect_folder_type "$target_path" "$exclusion_filters")
+
+    structure_info+="Directory: $dir_name\n"
+    structure_info+="Total files: $total_files\n"
+    structure_info+="Total directories: $total_dirs\n"
+    structure_info+="Folder type: $folder_type\n\n"
+
+    if [ "$strategy" = "full" ]; then
+        # For full: show all subdirectories with file counts
+        structure_info+="Subdirectories with files:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ] && [ "$dir" != "$target_path" ]; then
+                local rel_path=${dir#$target_path/}
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                if [ $file_count -gt 0 ]; then
+                    local subdir_type=$(detect_folder_type "$dir" "$exclusion_filters")
+                    structure_info+="  - $rel_path/ ($file_count files, type: $subdir_type)\n"
+                fi
+            fi
+        done < <(eval "find \"$target_path\" -type d $exclusion_filters 2>/dev/null")
+    else
+        # For single: show direct children only
+        structure_info+="Direct subdirectories:\n"
+        while IFS= read -r dir; do
+            if [ -n "$dir" ]; then
+                local dir_name=$(basename "$dir")
+                local file_count=$(eval "find \"$dir\" -maxdepth 1 -type f $exclusion_filters 2>/dev/null" | wc -l)
+                local has_api=$([ -f "$dir/API.md" ] && echo " [has API.md]" || echo "")
+                local has_readme=$([ -f "$dir/README.md" ] && echo " [has README.md]" || echo "")
+                structure_info+="  - $dir_name/ ($file_count files)$has_api$has_readme\n"
+            fi
+        done < <(eval "find \"$target_path\" -maxdepth 1 -type d $exclusion_filters 2>/dev/null" | grep -v "^$target_path$")
+    fi
+
+    # Show main file types in current directory
+    structure_info+="\nCurrent directory files:\n"
+    local code_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.sh' -o -name '*.go' -o -name '*.rs' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local config_files=$(eval "find \"$target_path\" -maxdepth 1 -type f \\( -name '*.json' -o -name '*.yaml' -o -name '*.yml' -o -name '*.toml' \\) $exclusion_filters 2>/dev/null" | wc -l)
+    local doc_files=$(eval "find \"$target_path\" -maxdepth 1 -type f -name '*.md' $exclusion_filters 2>/dev/null" | wc -l)
+
+    structure_info+="  - Code files: $code_files\n"
+    structure_info+="  - Config files: $config_files\n"
+    structure_info+="  - Documentation: $doc_files\n"
+
+    printf "%b" "$structure_info"
+}
+
+# Calculate output path based on source path and project name
+calculate_output_path() {
+    local source_path="$1"
+    local project_name="$2"
+    local project_root="$3"
+
+    # Get absolute path of source (normalize to Unix-style path)
+    local abs_source=$(cd "$source_path" && pwd)
+
+    # Normalize project root to same format
+    local norm_project_root=$(cd "$project_root" && pwd)
+
+    # Calculate relative path from project root
+    local rel_path="${abs_source#$norm_project_root}"
+
+    # Remove leading slash if present
+    rel_path="${rel_path#/}"
+
+    # If source is project root, use project name directly
+    if [ "$abs_source" = "$norm_project_root" ] || [ -z "$rel_path" ]; then
+        echo "$norm_project_root/.workflow/docs/$project_name"
+    else
+        echo "$norm_project_root/.workflow/docs/$project_name/$rel_path"
+    fi
+}
+
+generate_module_docs() {
+    local strategy="$1"
+    local source_path="$2"
+    local project_name="$3"
+    local tool="${4:-gemini}"
+    local model="$5"
+
+    # Validate parameters
+    if [ -z "$strategy" ] || [ -z "$source_path" ] || [ -z "$project_name" ]; then
+        echo "❌ Error: Strategy, source path, and project name are required"
+        echo "Usage: generate_module_docs.sh <strategy> <source_path> <project_name> [tool] [model]"
+        echo "Module strategies: full, single"
+        echo "Project strategies: project-readme, project-architecture, http-api"
+        return 1
+    fi
+
+    # Validate strategy
+    local valid_strategies=("full" "single" "project-readme" "project-architecture" "http-api")
+    local strategy_valid=false
+    for valid_strategy in "${valid_strategies[@]}"; do
+        if [ "$strategy" = "$valid_strategy" ]; then
+            strategy_valid=true
+            break
+        fi
+    done
+
+    if [ "$strategy_valid" = false ]; then
+        echo "❌ Error: Invalid strategy '$strategy'"
+        echo "Valid module strategies: full, single"
+        echo "Valid project strategies: project-readme, project-architecture, http-api"
+        return 1
+    fi
+
+    if [ ! -d "$source_path" ]; then
+        echo "❌ Error: Source directory '$source_path' does not exist"
+        return 1
+    fi
+
+    # Set default models if not specified
+    if [ -z "$model" ]; then
+        case "$tool" in
+            gemini)
+                model="gemini-2.5-flash"
+                ;;
+            qwen)
+                model="coder-model"
+                ;;
+            codex)
+                model="gpt5-codex"
+                ;;
+            *)
+                model=""
+                ;;
+        esac
+    fi
+
+    # Build exclusion filters
+    local exclusion_filters=$(build_exclusion_filters)
+
+    # Get project root
+    local project_root=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+
+    # Determine if this is a project-level strategy
+    local is_project_level=false
+    if [[ "$strategy" =~ ^project- ]] || [ "$strategy" = "http-api" ]; then
+        is_project_level=true
+    fi
+
+    # Calculate output path
+    local output_path
+    if [ "$is_project_level" = true ]; then
+        # Project-level docs go to project root
+        if [ "$strategy" = "http-api" ]; then
+            output_path="$project_root/.workflow/docs/$project_name/api"
+        else
+            output_path="$project_root/.workflow/docs/$project_name"
+        fi
+    else
+        output_path=$(calculate_output_path "$source_path" "$project_name" "$project_root")
+    fi
+
+    # Create output directory
+    mkdir -p "$output_path"
+
+    # Detect folder type (only for module-level strategies)
+    local folder_type=""
+    if [ "$is_project_level" = false ]; then
+        folder_type=$(detect_folder_type "$source_path" "$exclusion_filters")
+    fi
+
+    # Load templates based on strategy
+    local api_template=""
+    local readme_template=""
+    local template_content=""
+
+    if [ "$is_project_level" = true ]; then
+        # Project-level templates
+        case "$strategy" in
+            project-readme)
+                local proj_readme_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/project-readme.txt"
+                if [ -f "$proj_readme_path" ]; then
+                    template_content=$(cat "$proj_readme_path")
+                    echo "   📋 Loaded Project README template: $(wc -l < "$proj_readme_path") lines"
+                fi
+                ;;
+            project-architecture)
+                local arch_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/project-architecture.txt"
+                local examples_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/project-examples.txt"
+                if [ -f "$arch_path" ]; then
+                    template_content=$(cat "$arch_path")
+                    echo "   📋 Loaded Architecture template: $(wc -l < "$arch_path") lines"
+                fi
+                if [ -f "$examples_path" ]; then
+                    template_content="$template_content
+
+EXAMPLES TEMPLATE:
+$(cat "$examples_path")"
+                    echo "   📋 Loaded Examples template: $(wc -l < "$examples_path") lines"
+                fi
+                ;;
+            http-api)
+                local api_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/api.txt"
+                if [ -f "$api_path" ]; then
+                    template_content=$(cat "$api_path")
+                    echo "   📋 Loaded HTTP API template: $(wc -l < "$api_path") lines"
+                fi
+                ;;
+        esac
+    else
+        # Module-level templates
+        local api_template_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/api.txt"
+        local readme_template_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/module-readme.txt"
+        local nav_template_path="$HOME/.claude/workflows/cli-templates/prompts/documentation/folder-navigation.txt"
+
+        if [ "$folder_type" = "code" ]; then
+            if [ -f "$api_template_path" ]; then
+                api_template=$(cat "$api_template_path")
+                echo "   📋 Loaded API template: $(wc -l < "$api_template_path") lines"
+            fi
+            if [ -f "$readme_template_path" ]; then
+                readme_template=$(cat "$readme_template_path")
+                echo "   📋 Loaded README template: $(wc -l < "$readme_template_path") lines"
+            fi
+        else
+            # Navigation folder uses navigation template
+            if [ -f "$nav_template_path" ]; then
+                readme_template=$(cat "$nav_template_path")
+                echo "   📋 Loaded Navigation template: $(wc -l < "$nav_template_path") lines"
+            fi
+        fi
+    fi
+
+    # Scan directory structure (only for module-level strategies)
+    local structure_info=""
+    if [ "$is_project_level" = false ]; then
+        echo "   🔍 Scanning directory structure..."
+        structure_info=$(scan_directory_structure "$source_path" "$strategy")
+    fi
+
+    # Prepare logging info
+    local module_name=$(basename "$source_path")
+
+    echo "⚡ Generating docs: $source_path → $output_path"
+    echo "   Strategy: $strategy | Tool: $tool | Model: $model | Type: $folder_type"
+    echo "   Output: $output_path"
+
+    # Build strategy-specific prompt
+    local final_prompt=""
+
+    # Project-level strategies
+    if [ "$strategy" = "project-readme" ]; then
+        final_prompt="PURPOSE: Generate comprehensive project overview documentation
+
+PROJECT: $project_name
+OUTPUT: Current directory (file will be moved to final location)
+
+Read: @.workflow/docs/$project_name/**/*.md
+
+Context: All module documentation files from the project
+
+Generate ONE documentation file in current directory:
+- README.md - Project root documentation
+
+Template:
+$template_content
+
+Instructions:
+- Create README.md in CURRENT DIRECTORY
+- Synthesize information from all module docs
+- Include project overview, getting started, and navigation
+- Create clear module navigation with links
+- Follow template structure exactly"
+
+    elif [ "$strategy" = "project-architecture" ]; then
+        final_prompt="PURPOSE: Generate system design and usage examples documentation
+
+PROJECT: $project_name
+OUTPUT: Current directory (files will be moved to final location)
+
+Read: @.workflow/docs/$project_name/**/*.md
+
+Context: All project documentation including module docs and project README
+
+Generate TWO documentation files in current directory:
+1. ARCHITECTURE.md - System architecture and design patterns
+2. EXAMPLES.md - End-to-end usage examples
+
+Template:
+$template_content
+
+Instructions:
+- Create both ARCHITECTURE.md and EXAMPLES.md in CURRENT DIRECTORY
+- Synthesize architectural patterns from module documentation
+- Document system structure, module relationships, and design decisions
+- Provide practical code examples and usage scenarios
+- Follow template structure for both files"
+
+    elif [ "$strategy" = "http-api" ]; then
+        final_prompt="PURPOSE: Generate HTTP API reference documentation
+
+PROJECT: $project_name
+OUTPUT: Current directory (file will be moved to final location)
+
+Read: @**/*.{ts,js,py,go,rs} @.workflow/docs/$project_name/**/*.md
+
+Context: API route files and existing documentation
+
+Generate ONE documentation file in current directory:
+- README.md - HTTP API documentation (in api/ subdirectory)
+
+Template:
+$template_content
+
+Instructions:
+- Create README.md in CURRENT DIRECTORY
+- Document all HTTP endpoints (routes, methods, parameters, responses)
+- Include authentication requirements and error codes
+- Provide request/response examples
+- Follow template structure (Part B: HTTP API documentation)"
+
+    # Module-level strategies
+    elif [ "$strategy" = "full" ]; then
+        # Full strategy: read all files, generate for each directory
+        if [ "$folder_type" = "code" ]; then
+            final_prompt="PURPOSE: Generate comprehensive API and module documentation
+
+Directory Structure Analysis:
+$structure_info
+
+SOURCE: $source_path
+OUTPUT: Current directory (files will be moved to final location)
+
+Read: @**/*
+
+Generate TWO documentation files in current directory:
+1. API.md - Code API documentation (functions, classes, interfaces)
+   Template:
+$api_template
+
+2. README.md - Module overview documentation
+   Template:
+$readme_template
+
+Instructions:
+- Generate both API.md and README.md in CURRENT DIRECTORY
+- If subdirectories contain code files, generate their docs too (recursive)
+- Work bottom-up: deepest directories first
+- Follow template structure exactly
+- Use structure analysis for context"
+        else
+            # Navigation folder - README only
+            final_prompt="PURPOSE: Generate navigation documentation for folder structure
+
+Directory Structure Analysis:
+$structure_info
+
+SOURCE: $source_path
+OUTPUT: Current directory (file will be moved to final location)
+
+Read: @**/*
+
+Generate ONE documentation file in current directory:
+- README.md - Navigation and folder overview
+
+Template:
+$readme_template
+
+Instructions:
+- Create README.md in CURRENT DIRECTORY
+- Focus on folder structure and navigation
+- Link to subdirectory documentation
+- Use structure analysis for context"
+        fi
+    else
+        # Single strategy: read current + child docs only
+        if [ "$folder_type" = "code" ]; then
+            final_prompt="PURPOSE: Generate API and module documentation for current directory
+
+Directory Structure Analysis:
+$structure_info
+
+SOURCE: $source_path
+OUTPUT: Current directory (files will be moved to final location)
+
+Read: @*/API.md @*/README.md @*.ts @*.tsx @*.js @*.jsx @*.py @*.sh @*.go @*.rs @*.md @*.json @*.yaml @*.yml
+
+Generate TWO documentation files in current directory:
+1. API.md - Code API documentation
+   Template:
+$api_template
+
+2. README.md - Module overview
+   Template:
+$readme_template
+
+Instructions:
+- Generate both API.md and README.md in CURRENT DIRECTORY
+- Reference child documentation, do not duplicate
+- Follow template structure
+- Use structure analysis for current directory context"
+        else
+            # Navigation folder - README only
+            final_prompt="PURPOSE: Generate navigation documentation
+
+Directory Structure Analysis:
+$structure_info
+
+SOURCE: $source_path
+OUTPUT: Current directory (file will be moved to final location)
+
+Read: @*/API.md @*/README.md @*.md
+
+Generate ONE documentation file in current directory:
+- README.md - Navigation and overview
+
+Template:
+$readme_template
+
+Instructions:
+- Create README.md in CURRENT DIRECTORY
+- Link to child documentation
+- Use structure analysis for navigation context"
+        fi
+    fi
+
+    # Execute documentation generation
+    local start_time=$(date +%s)
+    echo "   🔄 Starting documentation generation..."
+
+    if cd "$source_path" 2>/dev/null; then
+        local tool_result=0
+
+        # Store current output path for CLI context
+        export DOC_OUTPUT_PATH="$output_path"
+
+        # Record git HEAD before CLI execution (to detect unwanted auto-commits)
+        local git_head_before=""
+        if git rev-parse --git-dir >/dev/null 2>&1; then
+            git_head_before=$(git rev-parse HEAD 2>/dev/null)
+        fi
+
+        # Execute with selected tool
+        case "$tool" in
+            qwen)
+                if [ "$model" = "coder-model" ]; then
+                    qwen -p "$final_prompt" --yolo 2>&1
+                else
+                    qwen -p "$final_prompt" -m "$model" --yolo 2>&1
+                fi
+                tool_result=$?
+                ;;
+            codex)
+                codex --full-auto exec "$final_prompt" -m "$model" --skip-git-repo-check -s danger-full-access 2>&1
+                tool_result=$?
+                ;;
+            gemini)
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
+                tool_result=$?
+                ;;
+            *)
+                echo "   ⚠️  Unknown tool: $tool, defaulting to gemini"
+                gemini -p "$final_prompt" -m "$model" --yolo 2>&1
+                tool_result=$?
+                ;;
+        esac
+
+        # Move generated files to output directory
+        local docs_created=0
+        local moved_files=""
+
+        if [ $tool_result -eq 0 ]; then
+            if [ "$is_project_level" = true ]; then
+                # Project-level documentation files
+                case "$strategy" in
+                    project-readme)
+                        if [ -f "README.md" ]; then
+                            mv "README.md" "$output_path/README.md" 2>/dev/null && {
+                                docs_created=$((docs_created + 1))
+                                moved_files+="README.md "
+                            }
+                        fi
+                        ;;
+                    project-architecture)
+                        if [ -f "ARCHITECTURE.md" ]; then
+                            mv "ARCHITECTURE.md" "$output_path/ARCHITECTURE.md" 2>/dev/null && {
+                                docs_created=$((docs_created + 1))
+                                moved_files+="ARCHITECTURE.md "
+                            }
+                        fi
+                        if [ -f "EXAMPLES.md" ]; then
+                            mv "EXAMPLES.md" "$output_path/EXAMPLES.md" 2>/dev/null && {
+                                docs_created=$((docs_created + 1))
+                                moved_files+="EXAMPLES.md "
+                            }
+                        fi
+                        ;;
+                    http-api)
+                        if [ -f "README.md" ]; then
+                            mv "README.md" "$output_path/README.md" 2>/dev/null && {
+                                docs_created=$((docs_created + 1))
+                                moved_files+="api/README.md "
+                            }
+                        fi
+                        ;;
+                esac
+            else
+                # Module-level documentation files
+                # Check and move API.md if it exists
+                if [ "$folder_type" = "code" ] && [ -f "API.md" ]; then
+                    mv "API.md" "$output_path/API.md" 2>/dev/null && {
+                        docs_created=$((docs_created + 1))
+                        moved_files+="API.md "
+                    }
+                fi
+
+                # Check and move README.md if it exists
+                if [ -f "README.md" ]; then
+                    mv "README.md" "$output_path/README.md" 2>/dev/null && {
+                        docs_created=$((docs_created + 1))
+                        moved_files+="README.md "
+                    }
+                fi
+            fi
+        fi
+
+        # Check if CLI tool auto-committed (and revert if needed)
+        if [ -n "$git_head_before" ]; then
+            local git_head_after=$(git rev-parse HEAD 2>/dev/null)
+            if [ "$git_head_before" != "$git_head_after" ]; then
+                echo "   ⚠️  Detected unwanted auto-commit by CLI tool, reverting..."
+                git reset --soft "$git_head_before" 2>/dev/null
+                echo "   ✅ Auto-commit reverted (files remain staged)"
+            fi
+        fi
+
+        if [ $docs_created -gt 0 ]; then
+            local end_time=$(date +%s)
+            local duration=$((end_time - start_time))
+            echo "   ✅ Generated $docs_created doc(s) in ${duration}s: $moved_files"
+            cd - > /dev/null
+            return 0
+        else
+            echo "   ❌ Documentation generation failed for $source_path"
+            cd - > /dev/null
+            return 1
+        fi
+    else
+        echo "   ❌ Cannot access directory: $source_path"
+        return 1
+    fi
+}
+
+# Execute function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    # Show help if no arguments or help requested
+    if [ $# -eq 0 ] || [ "$1" = "-h" ] || [ "$1" = "--help" ]; then
+        echo "Usage: generate_module_docs.sh <strategy> <source_path> <project_name> [tool] [model]"
+        echo ""
+        echo "Module-Level Strategies:"
+        echo "  full                   - Generate docs for all subdirectories with code"
+        echo "  single                 - Generate docs only for current directory"
+        echo ""
+        echo "Project-Level Strategies:"
+        echo "  project-readme         - Generate project root README.md"
+        echo "  project-architecture   - Generate ARCHITECTURE.md + EXAMPLES.md"
+        echo "  http-api               - Generate HTTP API documentation (api/README.md)"
+        echo ""
+        echo "Tools: gemini (default), qwen, codex"
+        echo "Models: Use tool defaults if not specified"
+        echo ""
+        echo "Module Examples:"
+        echo "  ./generate_module_docs.sh full ./src/auth myproject"
+        echo "  ./generate_module_docs.sh single ./components myproject gemini"
+        echo ""
+        echo "Project Examples:"
+        echo "  ./generate_module_docs.sh project-readme . myproject"
+        echo "  ./generate_module_docs.sh project-architecture . myproject qwen"
+        echo "  ./generate_module_docs.sh http-api . myproject"
+        exit 0
+    fi
+
+    generate_module_docs "$@"
+fi

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

@@ -126,13 +126,13 @@ Options:
 
 Examples:
   # Simple usage (auto-detect everything)
-  ui-instantiate-prototypes.sh .design/prototypes
+  ui-instantiate-prototypes.sh .workflow/design-run-*/prototypes
 
   # With options
-  ui-instantiate-prototypes.sh .design/prototypes --session-id WFS-auth
+  ui-instantiate-prototypes.sh .workflow/design-run-*/prototypes --session-id WFS-auth
 
   # Full manual mode
-  ui-instantiate-prototypes.sh .design/prototypes "login,dashboard" 3 3 --session-id WFS-auth
+  ui-instantiate-prototypes.sh .workflow/design-run-*/prototypes "login,dashboard" 3 3 --session-id WFS-auth
 EOF
 }